> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arco.financial/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer Guide

Mainnet product guide draft · English v1.0 · 7 October 2026

[Docs Home](/index)

Partners can connect ARCO product data and users' EVM wallets to integrate product discovery, deposits and redemptions, and holdings into their services. Wallets sign user transactions; APIs and indexers provide product information, prices, activity, and redemption status. Transaction quantities and execution results are verified against the relevant product contracts.

To implement an integration, follow the examples in [Developer Quickstart](/resources/developer-quickstart) for configuration inputs, payment asset approvals, quotes and simulation, submission, and verification of actual receipt.

## Getting started

1. Confirm the target product's participation, transfer, and redemption conditions and the scope of the partner integration.

2. Obtain the network, payment asset, ProductToken, vault and feed addresses, and ABIs from the official integration specification.

3. Integrate product data, wallet connection, deposit and redemption flows, and completion status displays.

4. Verify the product's pricing, limits, liquidity and settlement conditions, and exception handling.

Use the official integration specification for the relevant release version to obtain product addresses, the API environment, and access requirements. The interfaces below are references for understanding and integrating the public ProductToken, DepositVault, and RedemptionVault implementations. Connect ArcoUSD's multiple assets and 1:1 exchange, Savings yield linkage, Funds burns and treasury settlement, and OTC execution and fees according to their release interfaces and operating specifications. See [Smart Contracts and References](/resources/smart-contracts-and-references) for the scope of the public implementation and supporting materials.

## Core interfaces

| Component | Reads and actions |
| - | - |
| ProductToken | Read holdings and units with `balanceOf` and `decimals` |
| Payment asset | Manage deposit assets and approvals with `balanceOf`, `allowance`, and `approve` |
| DepositVault | `quoteDeposit`, `deposit`, and `requestDeposit` where request-based deposits are offered |
| RedemptionVault | `quoteRedeem`, `redeemInstant`, `requestRedeem`, and `claimRedeem` where claims are offered |
| Product data API | Product catalog, official deployments, NAV and price history, activity, and redemption status |

ProductToken uses the ERC20 interface. Deposits and redemptions use separate vault interfaces, so services that assume ERC4626 calls require a separate adapter design. Use the product's user-facing contract addresses and official ABIs, distinguishing implementation addresses from addresses used for user calls.

## Identifying a product

| Identifier | Integration reference |
| - | - |
| Catalog key and transaction `productId` | Mapping between the product listing and the execution target |
| `chainId` | The product's official deployment network |
| Payment asset and ProductToken | Each token's address, units, and product mapping |
| DepositVault and RedemptionVault | The product's deposit and redemption call addresses |
| Product and payment asset price feeds | Price sources, units, and vault connections |
| ABI and release version | Official call interface and applicable deployment version |

Do not select a transaction target from a product name or catalog key alone. Use the product's official deployment specification to map the transaction `productId`, network, token, vault and feed addresses, and ABIs. Distinguish listing identifiers from execution identifiers, and compare the selected product's network with the wallet's network.

## Connecting products and liquidity routes

| Specification item | Integration requirements |
| - | - |
| Product participation | ArcoUSD supported assets, Savings deposit and received tokens, and Funds burn, purchase, and receipt stages |
| Pricing and exchange mode | Distinguish the 1:1 basis, product valuation price, and OTC execution quote |
| Redemption route | Standard, internal direct Instant redemption, OTC settlement methods, and supported assets |
| Quote | Quantity, applicable price, fees, net amount received, validity period, and payment timing |
| Status and records | Acceptance, burn, transfer, settlement, payment, execution and request identifiers, and actual receipt |

Connect public direct redemption calls and OTC orders and executions through their respective interfaces. Do not record a transfer in an OTC token acquisition as a burn, or display a Funds arcoUSD burn as completion of an external asset purchase.

### Supported features by product and version

| Scope | Interfaces or designs available for reference | Support information to connect at release |
| - | - | - |
| Public implementation reference 8160f354 | ERC20 reads, deposits and requested deposits, internal direct redemption, requested redemption and claims | A reference for public code behavior; it does not indicate mainnet trading availability |
| ArcoUSD | Multiple stablecoins and 1:1 exchange design | Release version, supported assets, calls and payment routes, and reserve conditions |
| Savings | Deposit, received and redeemed tokens, valuation, and yield linkage design | Release version and each product's tokens, pricing method, and deposit and redemption calls |
| Funds | arcoUSD burn, treasury asset movement, external purchase, and receipt design | Release version, purchase and redemption interfaces, settlement status, and completion evidence |
| OTC | Quote, order, execution, and settlement flow | Offered products and versions, token transfer or redemption method, price, fees, quote expiry, and settlement conditions |

Determine execution availability from the **supported feature matrix for each product and release version**. The existence of an address and ABI does not mean every function or payment route is offered. Official release materials connect supported, unsupported and temporarily suspended status with ABI files, applicable versions, the price fixing point, and required participation policies.

## Deposit transactions

Read the payment asset balance and allowance, and use `quoteDeposit` to obtain the expected issuance quantity. The approval target is the selected product's DepositVault. Determine the required allowance and permitted price movement before preparing the deposit transaction.

```solidity theme={"system"}
function quoteDeposit(uint256 paymentAssets) view returns (uint256 sharesOut);
function deposit(uint256 paymentAssets, uint256 minSharesOut, address recipient) returns (uint256 sharesOut);
```

`paymentAssets` is an integer quantity in the payment asset's smallest units. `minSharesOut` is the minimum acceptable ProductToken receipt, and `recipient` is the receiving address. Before requesting a signature from the user's wallet, check the chain, product, recipient, and approval target and simulate the transaction. After a successful transaction, refresh the ProductToken balance and activity status.

Where a product offers request-based deposits, distinguish acceptance of funds from completed token issuance. Explain request processing and the treatment of funds for incomplete deposits.

## Redemption transactions

Read the ProductToken holding and use `quoteRedeem` to obtain the expected payment asset amount. Prepare the transaction using the instant or request-based redemption offered by the product.

```solidity theme={"system"}
function quoteRedeem(uint256 sharesIn) view returns (uint256 assetsOut);
function redeemInstant(uint256 sharesIn, uint256 minAssetsOut, address recipient) returns (uint256 assetsOut);
function requestRedeem(uint256 sharesIn, uint256 minAssetsOut, address recipient) returns (uint256 requestId);
function claimRedeem(uint256 requestId);
```

`sharesIn` is a quantity in ProductToken's smallest units, and `minAssetsOut` is the minimum acceptable payment asset receipt. The public `requestRedeem` interface above burns tokens in the request transaction and records the expected payment using the price at that time. Do not apply this behavior directly to products that fix NAV at settlement; check the relevant release ABI and pricing policy. For products requiring a claim, guide the designated recipient through claiming after payment approval.

## Handling quantities and prices

Read each token's `decimals` and convert transaction quantities to integers in its smallest units. Calculate amounts with large integers or an exact decimal type, and send them through APIs as strings with explicit units. Do not round a displayed amount and use it directly as a transaction argument.

Account for price movement between a quote and execution through minimum receipt quantities and the product's price validity policy. Do not mark transactions as complete if they fail pricing, limit, pause, participation policy, or liquidity conditions.

## Transaction status and settlement records

| User flow | States to distinguish in the partner interface |
| - | - |
| Deposit | Awaiting signature, submitted, confirmed, tokens received |
| Instant redemption | Awaiting signature, submitted, confirmed, payment asset received |
| Requested redemption | Request accepted, preparing payment, payment or claim, payment complete |
| Exceptions | User rejected, failed, update delayed, outcome under verification |

Receiving a transaction hash does not mean the transaction succeeded. Verify success on the target chain, the route's token transfers, issuance or burns, and actual payment. For OTC, distinguish order or quote acceptance from completed settlement. If API updates lag, distinguish an actual completed transaction from a pending interface update.

Identify a redemption request using `chainId`, `redemptionVaultAddress`, and `requestId` together. Also record the product ID, request transaction, recipient, quantity, and payment route to avoid mixing identical request numbers from different vaults. Link payment completion to the successful transaction and actual receipt for the selected route.

### Events and completion checks

The names and meanings below refer to the [public redemption contract](https://github.com/LBMike/arco-giwa/blob/8160f354b55dfe9a525565e30ddc007f51448f3d/packages/contracts/contracts/vaults/ArcoRedemptionVault.sol) and [public deposit contract](https://github.com/LBMike/arco-giwa/blob/8160f354b55dfe9a525565e30ddc007f51448f3d/packages/contracts/contracts/vaults/ArcoDepositVault.sol). Use the release contract's complete ABI to match log addresses, events, and arguments.

| Event | Status and evidence to verify |
| - | - |
| `ProductDeposit` | sender, recipient, paymentAssets, sharesOut, and actual ProductToken issuance and receipt |
| `ProductDepositRequested` | Request ID and payment asset acceptance, distinguished from completed token issuance |
| `ProductDepositFulfilled` | Request ID, recipient, issued quantity, and actual token receipt |
| `ProductRedeemInstant` | Quantity burned from the user, recipient, payment amount, and actual payment asset receipt |
| `ProductRedeemRequested` | Request ID, user, recipient, burned quantity, and fixed expected payment, distinguished from completed payment |
| `ProductRedeemFulfilled` | Assets reserved for the request and readiness to claim; this event alone does not establish completed payment |
| `ProductRedeemClaimed` | Request ID, recipient, payment amount, and actual payment asset receipt |

For release routes using direct operator payments, connect the separate payment transaction and receipt result. Use the relevant OTC specification to verify OTC order IDs, execution, and settlement. Similar API status labels and event names do not establish the same payment procedure.

### Errors and recovery queries

| Observation | Partner response |
| - | - |
| User rejects a signature | Display cancellation. Check whether a transaction was submitted, then let the user choose again |
| `ADV: min shares`, `ARV: min assets` | Display a new quote and minimum receipt for confirmation. Do not lower the minimum automatically |
| `PPF: stale`, `PPF: outside bounds` | Display a price validity issue and recheck the price. Block new execution until the price is updated or restored to a valid state |
| `ADV: below minimum`, `ARV: below minimum` | Check quantity, token units, and the product minimum |
| `ADV: max supply`, `ADV: vault allowance`, `ARV: vault allowance`, `ARV: liquidity` | Check product limits and available liquidity. Offer another route only where it is actually available |
| `FP: paused`, `FP: fn paused`, token or participation permission errors | Check the contract's pause scope and participation policy. Do not bypass them based on API display values |
| `ARV: not fulfilled`, `ARV: not recipient`, `ARV: claimed` | Query request status, the designated recipient, and prior payment results. Do not repeat the same claim |
| RPC timeout after submission, replacement transaction, or unknown outcome | Display outcome under verification and query the original and replacement transactions, account nonce, receipts, and logs. Do not submit a new request automatically |
| API update delay or reorganization after chain success | Distinguish chain results from data update status. Track the product's confirmation criteria and reconcile status after a reorganization |

These error strings come from the public reference code. Map them to the applicable ABI and error specification for release contracts. If the failure reason is unavailable, do not infer completion or failure.

## APIs and operating permissions

Partner API specifications cover product discovery, deployments and price history, wallet activity, and redemption requests. Distinguish API display data, directly queried token balances, and on-chain transaction results, and show the data reference time. Provide administrator APIs and permissions for funds, prices, and request processing separately from user integrations.

### Public API implementation reference

The paths below are references for the read implementation in the [public routes](https://github.com/LBMike/arco-giwa/blob/8160f354b55dfe9a525565e30ddc007f51448f3d/server/src/app.ts). **The mainnet API base URL, authentication, version, call limits, pagination, and response guarantees will be finalized in the release specification.** These paths do not indicate that the same endpoints will be offered at release.

| GET path in public code | Input and response reference |
| - | - |
| `/api/v1/evm/networks` | Network list |
| `/api/v1/evm/registry/:chainId` | Integer chainId; returns the DB registry or file registry |
| `/api/v1/evm/catalog/:chainId` | Product array with paymentAsset, vaultConfig, and pauseState. Check differences between DB and file response formats |
| `/api/v1/evm/market/:chainId/:productId/history` | productId, apy, and points. Each point's t is the feed publication timestamp in seconds; navBase and navUsd are display values |
| `/api/v1/activity/:wallet`, `/api/v1/redemptions/:wallet` | Wallet address and indexed activity or redemption arrays. The current implementation fixes the query scope to the GIWA validation chain |

The current catalog's pause lookup can fall back to default values if the lookup fails. Do not authorize execution from the displayed `pauseState` alone; check contract pause state and simulate the transaction. The current portfolio implementation returns an empty `positions` array, so query ProductToken directly for actual holdings. The code serializes bigint as decimal strings but uses number for market and history display prices. Do not use those display values as transaction quantities or minimum receipt amounts.

The request format is shown below. Variables are values from the partner's approved environment; no illustrative server address is substituted for a real one.

```bash theme={"system"}
curl --fail-with-body "$API_BASE/api/v1/evm/market/$CHAIN_ID/$PRODUCT_ID/history"
```

Set `API_BASE` for the actual environment before use. The following is an **example response structure**, not live data. It represents a selected productId with no price history and no APY.

```json theme={"system"}
{
  "productId": "<selected productId>",
  "apy": null,
  "points": []
}
```

If the market service is not connected, the public route returns HTTP 503 and `{"error":"Market service unavailable"}`. History query errors return HTTP 404. Release APIs must specify error codes, authentication, pagination, data timestamps, indexer progress, and requery policies, distinguishing them from this reference response.

Partner release validation covers approvals and signatures, price changes, minimum receipt quantities, insufficient liquidity, requested redemption and completed payment, and network or indexing delays. Apply product interfaces, access policies, and error handling according to the release specification.

### Integration acceptance criteria

| Verification item | Acceptance criteria |
| - | - |
| Product and deployment selection | Selected productId, chain, token, vault and feeds, full ABIs, and release version match |
| Approval and successful transaction | Confirm the approval target and minimum receipt, then verify a successful receipt and actual issuance or payment |
| Failure and rejection | Do not mark price, limit, pause, or participation failures or user rejection as complete |
| Requests and claims | Distinguish request acceptance, burn, payment preparation, claim, and actual receipt for the release route |
| Delays and unknown outcomes | Requery using the original transaction and request identifiers; prevent duplicate submissions and duplicate payment completion displays |
| Product support scope | Do not replace unsupported calls, OTC, or settlement routes with public direct redemption functions |

Reproduce these results in a validation environment. Before release, confirm that the same integration code corresponds to the official deployment and current operating conditions. Mainnet validation and transaction execution follow the approved release process.

## Related guides

* [Deposits and Redemptions](/liquidity/deposits-and-redemptions)

* [NAV and Returns](/transparency/nav-and-returns)

* [Security and Operations](/security/operations)

* [Smart Contracts and References](/resources/smart-contracts-and-references)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.