---
title: 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?](https://docs.replicalab.finance/explanation/tradable-assets.md) for asset examples.

**Sell USD for ZAR**

```http
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`**

```json
{
  "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**

```http
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`**

```json
{
  "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**

```http
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`**

```json
{
  "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). |