Skip to content

Buy and sell an asset

To trade a listing, you need its trading currency. This example starts with 150 synthetic USD and uses it to buy and sell 100 shares of Industrial and Commercial Bank of China (XSHG-601398) on the Shanghai Stock Exchange. Use your wallet’s network throughout.

Send GET /assets/XSHG-601398/quote?currency=CNY. Read the asset name in data.public.asset.name and the price per share in data.public.quote.price_per_unit. Suppose the quote is 9.40 CNY and you’re willing to pay up to 9.50 CNY per share. For 100 shares, you need at most 950 CNY.

Check the exchange rate with GET /assets/fiat-USD/quote?currency=CNY. If you’ll accept at least 6.50 CNY per USD, send this body to POST /wallets/{address}/trades. For each trade, send Content-Type: application/json, Authorization: Bearer <trade-token>, and a fresh UUIDv4 or UUIDv7 in Idempotency-Key. Reuse the same request and key if you retry within three hours of acceptance.

{
"operation": "sell",
"asset": { "id": "fiat-USD", "units": "150" },
"quote": { "currency": "CNY", "minimum_price_per_unit": "6.50" }
}

On 201 Created, read data.public.quote.amount for the CNY credited. At 6.70 CNY per USD, you receive 1,005 synthetic CNY.

Send the buy to the same endpoint. Set the maximum per share to 9.50 CNY.

{
"operation": "buy",
"asset": { "id": "XSHG-601398", "units": "100" },
"quote": { "currency": "CNY", "maximum_price_per_unit": "9.50" }
}

At 9.40 CNY per share, the receipt shows "940" in data.public.quote.amount. That is the synthetic CNY spent. If the price exceeds your limit, the API returns 409 and the trade ends.

When you’re ready to sell, choose the minimum price you’ll accept per share. To sell all 100 shares for at least 9.30 CNY per share, send this body to the same endpoint.

{
"operation": "sell",
"asset": { "id": "XSHG-601398", "units": "100" },
"quote": { "currency": "CNY", "minimum_price_per_unit": "9.30" }
}

Read data.public.quote.amount in the sale receipt for the synthetic CNY received. Subtract the buy receipt’s amount to find the gain or loss in CNY. A sale at 9.30 CNY per share returns 930 CNY, a loss of 10 CNY on the shares. Your balances show the remaining cash under fiat-CNY.