## GET /openapi/v1/dex/tokens/trades

One DEX token's recent trades, newest first, a page at a time. **Only the last 48 hours, and at
most 100 trades**, are served.

### Query parameters

| Parameter | Type | Default | Notes |
|:--|:--|:--|:--|
| `chain_slug`, `address` | string | required | See [naming a token](#dex-tokens-what-the-endpoints-share) |
| `limit` | integer | 20 | At most 100; 0 or below is 20 |
| `cursor` | string | the first page | The `next_cursor` of the page before, passed back as it came |

### Response

```json
{
  "code": 0,
  "message": "success",
  "message_key": "SUCCESS",
  "result": {
    "available": true,
    "data_time": "2026-10-21T08:05:00Z",
    "stale": false,
    "window_limit": { "hours": 48, "max": 100 },
    "last_trade_time": "2026-10-21T08:04:00Z",
    "items": [
      {
        "id": "0x5e2c7a1f3b9d4e8a6c0f2b7d9e1a3c5f7b9d2e4a6c8f0b1d3e5a7c9f1b3d5e7a:2",
        "tx_time": "2026-10-21T08:04:00Z",
        "tx_type": "buy",
        "price": "0.0204910145",
        "base_amount": "48800.5",
        "base_symbol": "XDP",
        "quote_amount": "0.2857",
        "quote_symbol": "WETH",
        "value": "1000.12",
        "exchange_name": "Uniswap V3",
        "maker": "0x1f2e3d4c5b6a79880716253443526170f8e9d0c1",
        "tx_hash": "0x5e2c7a1f3b9d4e8a6c0f2b7d9e1a3c5f7b9d2e4a6c8f0b1d3e5a7c9f1b3d5e7a",
        "holder_tags": ["whale"]
      }
    ],
    "next_cursor": "MTc5MTE4MjY0MDAwMDow…"
  }
}
```

**Order and paging.** The array is newest first. `tx_time` is to the second, and within one
second the array's order is the only order we give, so page by `next_cursor`, never by time: pass
it back as `cursor` until it is `null`. Pass a cursor back only to the token and tab that issued
it — that is the paging we promise; a `cursor` that is not in the form we issue is a `400`.

| Field | Type | Notes |
|:--|:--|:--|
| `available` | boolean | `false` when we do not collect this token's trades — not an error, and retrying soon will not change it; `items` is then `[]` |
| `data_time` | string | When the trades were last refreshed. When `available` is `false`, the token's `data_time` as on `/dex/tokens/info`: when the list that supplied it was built, or when a token no list holds was last listed |
| `stale` | boolean | Last refreshed more than 30 minutes ago. When `available` is `false`, the token's `stale` as on `/dex/tokens/info` (always `false` for a token no list holds) |
| `window_limit` | object | `hours` and `max`: how far back the trades reach and how many are kept |
| `last_trade_time` | string or `null` | The newest trade we have seen for the token, whether or not `available` |
| `items[].id` | string | Unique within the token. One transaction can hold several trades, so `tx_hash` repeats and `id` does not |
| `items[].tx_time` | string | RFC3339, to the second |
| `items[].tx_type` | string | `buy` or `sell`, of the token asked for |
| `items[].price` | string or `null` | USD |
| `items[].base_amount`, `items[].quote_amount` | string or `null` | Token amounts: `base` is the token asked for, `quote` the other side of the pool |
| `items[].value` | string or `null` | The trade's value in USD |
| `items[].base_symbol`, `items[].quote_symbol`, `items[].exchange_name` | string or `null` | |
| `items[].maker` | string or `null` | The trader's wallet |
| `items[].tx_hash` | string | |
| `items[].holder_tags` | array | Labels on the trader's wallet; may be empty |
| `next_cursor` | string or `null` | `null` when nothing older is in the window |

`available` can be `true` with no `items`: the token is tracked and had no trade in the window.

### Examples

```bash
curl -H "X-Api-Key: <your-api-key>" \
  "https://open-api.coinworldcap.com/openapi/v1/dex/tokens/trades?chain_slug=base&address=0x07b3d902783c3c12b077508c3b5c00113d1291d0&limit=20"

# The next page
curl -H "X-Api-Key: <your-api-key>" \
  "https://open-api.coinworldcap.com/openapi/v1/dex/tokens/trades?chain_slug=base&address=0x07b3d902783c3c12b077508c3b5c00113d1291d0&limit=20&cursor=<next_cursor>"
```

| HTTP status | `code` | When |
|:--|:--|:--|
| 400 | 40000 | `chain_slug` or `address` missing; `limit` above 100 or not an integer; a `cursor` not in the form we issue |
| 404 | 40400 | The token, as on `/dex/tokens/info` |
| 503 | 50300 | No Trending list younger than three hours; reading the trades, or a token no list holds, timed out (retryable) |
| 500 | 50000 | Reading the trades failed for another reason |

The other errors are in [Errors](#errors).