> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metastreams.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Page through trade lists with an opaque cursor, and through candles with a time window.

Trade lists are paged with a cursor. Candles are paged with a time window.

## Cursor pagination

These endpoints return trades a page at a time, newest first:

* `GET /v1/tokens/{chain}/{address}/trades`
* `GET /v1/trades`

### Parameters

| Parameter | Default | Meaning |
| - | - | - |
| `limit` | `20` | Trades per page, from 1 to 100. A value outside that range is moved into it, not refused. |
| `cursor` | — | The `nextCursor` from the previous page. Leave it out for the first page. |

### Response

```json theme={null}
{
  "trades": [ { "id": "4xQm...", "timestamp": 1789632015120 } ],
  "nextCursor": "eyJ0cyI6MTc4OTYzMjAxNTEyMCwiaWQiOiI0eFFtIn0",
  "hasMore": true
}
```

| Field | Meaning |
| - | - |
| `trades` | The page. Always present, possibly empty. |
| `nextCursor` | The cursor for the next page, or `null` on the last page. |
| `hasMore` | `true` when another page exists. |

### Read every page

<CodeGroup>
  ```python Python theme={null}
  import os
  import requests

  url = "https://{{API_HOST}}/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/trades"
  headers = {"Authorization": f"Bearer {os.environ['API_KEY']}"}
  params = {"limit": 100}

  while True:
      response = requests.get(url, headers=headers, params=params, timeout=10)
      response.raise_for_status()
      page = response.json()
      for trade in page["trades"]:
          print(trade["id"], trade["side"], trade["volume"]["usd"])
      if not page["hasMore"]:
          break
      params["cursor"] = page["nextCursor"]
  ```

  ```typescript TypeScript theme={null}
  const url = "https://{{API_HOST}}/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/trades";
  const headers = { Authorization: `Bearer ${process.env.API_KEY}` };
  let cursor: string | null = null;

  do {
    const params = new URLSearchParams({ limit: "100" });
    if (cursor) params.set("cursor", cursor);
    const response = await fetch(`${url}?${params}`, { headers });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const page = await response.json();
    for (const trade of page.trades) console.log(trade.id, trade.side, trade.volume.usd);
    cursor = page.hasMore ? page.nextCursor : null;
  } while (cursor);
  ```
</CodeGroup>

### Rules

* **Treat the cursor as opaque.** Do not build, change or store meaning in it. Send back exactly what you received.
* **Pages do not shift.** The cursor marks a position in the list, not an offset. New trades that arrive while you page do not duplicate or skip results.
* **A bad cursor is refused.** A cursor the API cannot read returns `400 VALIDATION_ERROR` on the `cursor` field. It never silently restarts from the first page.
* **An unknown token returns an empty page,** not a `404`.

## Paging through candles

`GET /v1/tokens/{chain}/{address}/ohlcv` returns candles oldest first, and has no cursor. Choose the range with these parameters:

| Parameter | Meaning |
| - | - |
| `countBack` | Return the latest N candles, from 1 to 5,000. Takes priority over `from`. |
| `from` | Window start in milliseconds, inclusive. Ignored when `countBack` is set. |
| `to` | Window end in milliseconds, exclusive. Leave it out to read up to now. |

With neither `countBack` nor `from`, the response holds the latest 500 candles. A window that holds more than 5,000 candles keeps the newest 5,000.

To read further back, repeat the request with `to` set to the `time` of the oldest candle you received:

```bash theme={null}
curl "https://{{API_HOST}}/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/ohlcv?timeframe=1m&countBack=5000&to=1789545600000" \
  -H "Authorization: Bearer $API_KEY"
```

Because `to` is exclusive, the oldest candle of the previous page is not repeated.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.