Skip to content

Trades

POST /wallets/{address}/trades

Buys and sells use synthetic funds and update simulated holdings at real-world reference prices. See What can you trade? for asset examples.

Sell USD for ZAR

POST /wallets/01a1f8d3-ea7b-7a12-8b34-56789abcdef0/trades
Authorization: Bearer <trade-token>
Idempotency-Key: <forex-idempotency-key>
Content-Type: application/json
{
"operation": "sell",
"asset": {
"id": "fiat-USD",
"units": "0.0005"
},
"quote": {
"currency": "ZAR",
"minimum_price_per_unit": "17.50"
}
}

Response: 201 Created

{
"meta": {
"network": "bubblegum",
"at": "2026-11-20T15:10:00.124000000Z"
},
"data": {
"public": {
"transaction": "01a1f981-ddbb-7b23-9c45-6789abcdef01",
"operation": "sell",
"asset": {
"id": "fiat-USD",
"units": "0.0005"
},
"quote": {
"currency": "ZAR",
"price_per_unit": "17.59",
"amount": "0.008795"
}
}
}
}

Buy AAPL with USD

POST /wallets/01a1f8d3-ea7b-7a12-8b34-56789abcdef0/trades
Authorization: Bearer <trade-token>
Idempotency-Key: <buy-idempotency-key>
Content-Type: application/json
{
"operation": "buy",
"asset": {
"id": "XNGS-AAPL",
"units": "0.001"
},
"quote": {
"currency": "USD",
"maximum_price_per_unit": "249.85"
}
}

Response: 201 Created

{
"meta": {
"network": "bubblegum",
"at": "2026-11-20T15:15:00.124000000Z"
},
"data": {
"public": {
"transaction": "01a1f986-719b-7c34-ad56-789abcdef002",
"operation": "buy",
"asset": {
"id": "XNGS-AAPL",
"units": "0.001"
},
"quote": {
"currency": "USD",
"price_per_unit": "249.37",
"amount": "0.24937"
}
}
}
}

Sell AAPL for USD

POST /wallets/01a1f8d3-ea7b-7a12-8b34-56789abcdef0/trades
Authorization: Bearer <trade-token>
Idempotency-Key: <sell-idempotency-key>
Content-Type: application/json
{
"operation": "sell",
"asset": {
"id": "XNGS-AAPL",
"units": "0.001"
},
"quote": {
"currency": "USD",
"minimum_price_per_unit": "251.12"
}
}

Response: 201 Created

{
"meta": {
"network": "bubblegum",
"at": "2026-11-20T15:20:00.124000000Z"
},
"data": {
"public": {
"transaction": "01a1f98b-057b-7d45-be67-89abcdef0001",
"operation": "sell",
"asset": {
"id": "XNGS-AAPL",
"units": "0.001"
},
"quote": {
"currency": "USD",
"price_per_unit": "251.43",
"amount": "0.25143"
}
}
}
}
Input Meaning and format
address Wallet address. UUIDv7 (RFC 9562), lowercase, 36 characters.
trade-token Wallet trade token. sk-{network}-{lookup}-{secret}. Independent OS CSPRNG values, lowercase hex: lookup has 128-bit entropy (32 characters); secret has 256-bit entropy (64 characters).
Idempotency-Key Client-generated UUIDv4 or UUIDv7. Unique per wallet across trades and transfers. Reuse for retries. Expires 3 hours after acceptance.
operation buy or sell.
asset.id Asset ID: fiat-{currency}, crypto-{symbol}, or {MIC}-{symbol}. Currency: uppercase ISO 4217; MIC: uppercase ISO 10383. Maximum 128 UTF-8 bytes.
asset.units Asset units to buy or sell. Positive plain decimal string, up to 64 characters, representable with 18 decimal places. Maximum 340282366920938463463.374607431768211455.
quote.currency Required for buy and sell. Uppercase ISO 4217: the listing’s trading currency for exchange assets, USD for crypto, or the counter currency for forex.
quote.maximum_price_per_unit Maximum fiat price to pay per asset unit, in quote.currency. Positive plain decimal string, up to 64 characters, representable with 18 decimal places. Maximum 340282366920938463463.374607431768211455. Required for buy.
quote.minimum_price_per_unit Minimum fiat price to receive per asset unit, in quote.currency. Positive plain decimal string, up to 64 characters, representable with 18 decimal places. Maximum 340282366920938463463.374607431768211455. Required for sell.

The API rounds the total in the quote currency to 18 decimal places, up for a buy and down for a sell. It checks that total against the number of units multiplied by your price limit. A small trade can therefore exceed a buy limit or fall below a sell limit even when the displayed price matches the limit. A sale that rounds to zero returns 422.

Output Meaning and format
transaction Reference for the asset credit (buy) or asset debit (sell). UUIDv7 (RFC 9562), lowercase, 36 characters.
operation buy or sell.
asset.id Asset ID: fiat-{currency}, crypto-{symbol}, or {MIC}-{symbol}. Currency: uppercase ISO 4217; MIC: uppercase ISO 10383. Maximum 128 UTF-8 bytes.
asset.units Asset units bought or sold. Positive plain decimal string, up to 18 decimal places; no trailing fractional zeros. Maximum 340282366920938463463.374607431768211455.
quote.currency Currency of the synthetic funds paid or received. Uppercase ISO 4217 code.
quote.price_per_unit Actual execution price per asset unit, in quote.currency. Positive plain decimal string, up to 18 decimal places; no trailing fractional zeros. Maximum 340282366920938463463.374607431768211455.
quote.amount Amount of synthetic funds paid for a buy or received for a sell, in quote.currency. Positive plain decimal string, up to 18 decimal places; no trailing fractional zeros. Maximum 340282366920938463463.374607431768211455.
network Selected network. String.
at Response time. RFC 3339 (ISO 8601 profile), UTC (Z), exactly 9 fractional digits (nanoseconds).