Developer Guide

Mainnet product guide draft · English v1.0 · 7 October 2026 Docs Home 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 for configuration inputs, payment asset approvals, quotes and simulation, submission, and verification of actual receipt.

Getting started

Confirm the target product’s participation, transfer, and redemption conditions and the scope of the partner integration.
Obtain the network, payment asset, ProductToken, vault and feed addresses, and ABIs from the official integration specification.
Integrate product data, wallet connection, deposit and redemption flows, and completion status displays.
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 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.

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.

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 and public deposit contract. 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. 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.

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.

{
  "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.

About ARCO

ARCO Products

Liquidity and Product Use

Pricing and Transparency

Security and Product Terms

Resources

Getting started

Core interfaces

Identifying a product

Connecting products and liquidity routes

Supported features by product and version

Deposit transactions

Redemption transactions

Handling quantities and prices

Transaction status and settlement records

Events and completion checks

Errors and recovery queries

APIs and operating permissions

Public API implementation reference

Integration acceptance criteria

​Getting started

​Core interfaces

​Identifying a product

​Connecting products and liquidity routes

​Supported features by product and version

​Deposit transactions

​Redemption transactions

​Handling quantities and prices

​Transaction status and settlement records

​Events and completion checks

​Errors and recovery queries

​APIs and operating permissions

​Public API implementation reference

​Integration acceptance criteria

​Related guides

Getting started

Core interfaces

Identifying a product

Connecting products and liquidity routes

Supported features by product and version

Deposit transactions

Redemption transactions

Handling quantities and prices

Transaction status and settlement records

Events and completion checks

Errors and recovery queries

APIs and operating permissions

Public API implementation reference

Integration acceptance criteria

Related guides