Quickstart: First API Trade

This guide walks through the smallest API flow for a partner integration:

Discover a tradable stock.
Confirm mUSD.
Deposit if needed.
Place a market buy.
Record and track the transaction.
Confirm the portfolio changed after settlement.

Use this as the smoke test before adding limit orders, withdrawals, or One Click.

Flow

1. Configure Request Context

Every request must include:

Header

Example

x-api-key

Partner API key

x-api-ts

Current Unix milliseconds

x-api-nonce

UUID

x-api-sign

HMAC-SHA256 authentication value

x-api-chain-id

8453, 143, 1, or target chain

x-api-p

Anchored for the Anchored API

Use the exact /api/v1/... path in the HMAC payload. Do not include the domain or /rwa/trading.

2. Discover a Tradable Stock

GET /api/v1/symbols

Pick an item where tradable is true. Relevant response fields:

Field

Use

symbol

Symbol and quote lookup

contractAddress

stockAddress for order requests

price

Quote context

Optional quote refresh:

GET /api/v1/prices/{symbol}

3. Check Portfolio

GET /api/v1/users/{userId}/balance

For a plain market buy, check mUsdBalance, the API field for mUSD. Wallet USDC is not buying power until it is deposited into mUSD. If the cash token is approved and instant deposit is available, /api/v1/orders/with-deposit/calldata can deposit and place the buy in one transaction.

4. Deposit Cash If Needed

First check allowance:

GET /api/v1/users/{userId}/balance?spenderAddress={spender}

If allowance is too low, have the user approve the spender from cash/deposits.md.

Then build deposit calldata:

POST /api/v1/cash/deposits/calldata

Example body:

{
  "userAddress": "0x1111111111111111111111111111111111111111",
  "tokenAddress": "0x2222222222222222222222222222222222222222",
  "tokenAmount": "100"
}

Submit the returned toAddress, value, and callData on-chain. Then record:

POST /api/v1/cash/deposits/tx

Poll deposit detail until operationStatus is settled or mUsdBalance is updated.

5. Place a Market Buy

Build order calldata:

POST /api/v1/orders/calldata

Example body:

{
  "stockAddress": "0x3333333333333333333333333333333333333333",
  "side": "Buy",
  "type": "Market",
  "notional": "10",
  "deadline": 1893456000
}

Submit the returned StockRouter transaction with your wallet client.

6. Record and Track the Order

Record the self-submitted tx:

POST /api/v1/orders/tx

Example:

{
  "txHash": "0xabc..."
}

Then track:

GET /api/v1/orders/tx/{txHash}
GET /api/v1/orders/{orderId}

The transaction can be mined before execution and settlement are final. Treat the order as final only after it moves into history and portfolio balances reflect the settlement.

7. Confirm Portfolio

After settlement:

GET /api/v1/users/{userId}/balance
GET /api/v1/users/{userId}/positions

Expected result:

mUsdBalance decreases by filled notional plus fees, with unspent mUSD refunded.
The bought stock appears as exchangeBalance.
Order detail shows settlement fields such as settlePrice, settlePay, and settleReceive.