API Integration Playbook

Use this page as the practical operating guide for an RWA API integration. Before submitting orders, moving cash, or reconciling portfolio state, verify these request and state checks.

The most important habit is to separate wallet state, mUSD, exchangeBalance, and final settlement state. The API connects these systems, but they do not update at the same time.

Integration Mental Model

Diagram color key: blue is self-submit, purple is One Click.

For self-submit requests, call the API to build StockRouter calldata, submit the transaction with the user wallet, then record txHash. For One Click requests, call /send; the API submits through OneClickRouter. For state reads, the API indexes Cashier and Stock into fields such as mUsdBalance, orders, and exchangeBalance.

StockRouter enforces on-chain entry, Cashier accounts for mUSD, and Stock accounts for orders and Stock.stockBalance. Build integrations around the async lifecycle instead of assuming a trade is final when the transaction is mined.

Discover Tradable Stocks

Start every trading flow from the symbol list. Treat a stock token as tradable only when the API marks it tradable for the current chainId and x-api-p.

1. Call GET /api/v1/symbols.

2. Keep only symbols where tradable is true.

3. Call GET /api/v1/config for fee rates, cashier buffer state, and per-token deposit/withdraw limits.

4. Use contractAddress as stockAddress when building orders.

5. Refresh quote context with GET /api/v1/prices/{symbol}.

6. Check GET /api/v1/corporate-action?symbol=AAPL when splits/dividends may affect downstream accounting.

Do not hardcode token addresses unless your release process also verifies they match the active API response.

Check Buying Power

For plain buys, the important value is mUsdBalance, not the cash token walletBalance. A user can have USDC in their wallet and still have no mUSD until a deposit happens. If the cash token is approved and instant deposit is available, /orders/with-deposit/* can deposit and place the buy in one transaction.

Field	API meaning
mUsdBalance	mUSD available for buys and withdrawals
walletBalance	ERC-20 tokens in wallet; not automatically mUSD
walletAllowance	Whether deposit can succeed on-chain

Use mUsdBalance for plain market buys and limit buys. If it is insufficient, deposit cash first. When cash token approval and instant deposit conditions are met, /orders/with-deposit/* can deposit and place the buy in one transaction.

Check Stock Available To Sell

For plain sells, the important value is exchangeBalance. walletBalance means the user owns an ERC-20 stock token in their wallet, but it is not yet credited inside Stock.

Do not treat wallet stock as plain-sell balance. A plain sell uses exchangeBalance, the API view of Stock.stockBalance. To sell wallet-held stock with separate calls, approve the stock token and call /stock/deposits/* first. To deposit and sell in one transaction, use /orders/with-deposit/* after stock token approval.

Prepare Deposits Correctly

Deposit means: wallet cash token -> mUSD -> buy power. Track the conversion so the integration does not treat wallet balance as spendable mUSD.

Before building deposit calldata:

1. Check wallet cash balance.

2. Check allowance with GET /api/v1/users/{userId}/balance?spenderAddress={spender}.

3. Request ERC-20 approval from the owner wallet if walletAllowance is too low.

4. For self-submit, build deposit calldata and submit the returned StockRouter transaction.

5. For One Click, call /cash/deposits/send after delegation is enabled.

6. Record txHash for self-submit flows and poll the deposit operation.

If allowance is too low, /cash/deposits/calldata can still return calldata, but the chain transaction will fail.

Place A Market Buy

Market buy input is notional: the maximum mUSD amount to spend. The final fill may spend less and refund the rest. The order is not economically final until settlement has credited stock and refunded unused mUSD.

Place A Market Sell

Market sell input is quantity: the maximum stock quantity to sell. Stock locks that quantity first; settlement applies only the filled amount and returns any unfilled stock to Stock.stockBalance.

Place A Limit Order

Limit orders have a price, quantity, and timeInForce. Current production contracts accept only DAY; backend processing and settlement handle the practical lifecycle after placement.

Treat a limit order as an open commitment that locks mUSD or stock until fill, cancel, expiry, or settlement. Keep it separate from final portfolio balances.

Reconcile Order Finality

A mined transaction means the order was accepted on-chain; it does not mean execution and settlement are final. Watch both mapping state and order detail:

1. POST /api/v1/orders/tx records a self-submitted tx.

2. GET /api/v1/orders/tx/{txHash} finds the tx mapping.

3. The indexer backfills orderId.

4. GET /api/v1/orders/{orderId} tracks open or historical state.

5. Portfolio balances update after settlement.

An order is economically final only after settlement updates mUSD and exchangeBalance.

Understand Instant Vs Queued Cash

Cash can be instant when buffers are available. Otherwise it is queued until final settlement completes. Track status with:

• GET /api/v1/cash/deposits/{operationId}

• GET /api/v1/cash/withdrawals/{operationId}

Handle both instant and queued outcomes. A queued operation is not necessarily failed; it may be waiting for final cash settlement.

The underlying contracts use two buffers: a global creditBuffer for instant deposits and a per-token withdrawalBuffer for instant withdrawals. Deposits and withdrawals can replenish each other's buffers. See cash/buffer-mechanism.md.

Choose Execution Mode

Both modes call the same router methods. One Click only changes who submits the router transaction.

Mode	Use when	Trade-off
Self-submit	You manage wallets, custody, or transaction policy	More control; must record txHash
One Click	You use delegated transaction submission	Requires user delegation and API key bound userAddress

Use Self-submit when your integration owns transaction policy or custody. Use One Click when the integration needs delegated submission after explicit authorization.

Treat API Calldata As A Router Instruction

For self-submit, use toAddress, value, and callData exactly as returned by the API. Do not reconstruct calldata by hand unless you are deliberately bypassing the partner API. The API output is already shaped for the correct router method and product context.

Pre-Trade Checklist

Before placing an order, confirm:

• Symbol is tradable for the selected chain/product.

• x-api-chain-id, wallet network, and x-api-p match.

• Portfolio has been refreshed.

• Plain buys use mUsdBalance; plain sells use exchangeBalance.

• Order-with-deposit flows require token allowance and, for buys, instant deposit availability.

• Deposit allowance is sufficient if funding is required.

• Execution mode is selected.

• Self-submit flows record txHash; One Click flows have /1ct/status = enable.

If a trade fails or appears stuck, check these in order: API response code, tx receipt, /orders/tx/{txHash}, /orders/{orderId}, then portfolio balances.

Related Docs

Need	Doc
First API trade flow	../guides/quickstart-first-trade.md
How do I authenticate?	authenticate/
How do I read balances?	portfolio/overview.md
How do I deposit?	cash/deposits.md
How do I place or cancel orders?	trading/place-and-cancel-orders.md
How do I track status?	trading/order-status-and-history.md
How do I submit with viem?	guides/demo-code.md
How do I debug issues?	../reference/troubleshooting.md