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/tradesAuthorization: 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/tradesAuthorization: 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/tradesAuthorization: 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). |