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

# Bridge API Pagination Guide

> This page describes how to paginate any Bridge “list” endpoint using cursor-based pagination. It applies across resources (transactions, deposits, payouts, etc.), not just a single API.

Most list endpoints return results in reverse chronological order (newest to oldest) and support stable, cursor-based pagination with `starting_after` and `ending_before`.

## **Endpoint shape**

* Base URL: [**https://api.bridge.xyz**](https://api.bridge.xyz)
* Typical list endpoint pattern: GET /v0/{resource}
* Default order: newest → oldest (unless an endpoint specifies otherwise)
* Page size: controlled by `limit` (maximum 100)
* Pagination: cursor-based using item `id` values

Authentication: send your API key in the `Api-Key` header.

Security note: do not hardcode live keys in source or docs; use environment variables.

## **Query parameters**

* `limit`
  * Description: number of items to return
  * Range: 1–100
  * Tip: set explicitly (e.g., `limit=50`) for predictable pagination
* `starting_after`
  * Description: fetches items that come after the given id in the default ordering, i.e., older items
  * How to use: pass the last item’s id from your current page to get the next page of older results
* `ending_before`
  * Description: fetches items that come before the given id in the default ordering, i.e., newer items
  * How to use: pass the first item’s id from a known page to retrieve any items that are newer than it

Use only one of `starting_after` or `ending_before` per request.

## **Response shape**

* data: array of resource objects (0 to `limit` items)
* count: number of items in this page (if provided by the endpoint)
* Stop condition: when `data` is empty, there are no more items in that direction

Note: Field names inside `data` vary by resource. All paginable resources include an `id` used as the cursor.

## **cURL examples**

Use an environment variable for your API key:

* macOS/Linux: export BRIDGE\_API\_KEY="sk\_live\_..."
* Windows PowerShell: \$env:BRIDGE\_API\_KEY = "sk\_live\_..."

Replace {resource} with the list endpoint you’re using (e.g., transactions, payouts, etc.).

### **1) Fetch the first page (newest first)**

This returns the newest 3 items:

```
curl --location 'https://api.bridge.xyz/v0/{resource}?limit=3' \
  --header 'Accept: application/json' \
  --header "Api-Key: $BRIDGE_API_KEY"
```

Take note of:

* First item’s id: newest on this page
* Last item’s id: oldest on this page

### **2) Get the next page of older items**

Use `starting_after` with the last id from the previous page:

```
curl --location 'https://api.bridge.xyz/v0/{resource}?limit=3&starting_after={LAST_ID_FROM_PREVIOUS_PAGE}' \
  --header 'Accept: application/json' \
  --header "Api-Key: $BRIDGE_API_KEY"
```

### **3) Fetch newer items since a known id**

If your last run’s first item id was {FIRST_ID_YOU_SAW}, use `ending_before` to get any newer items:

```
curl --location 'https://api.bridge.xyz/v0/{resource}?ending_before={FIRST_ID_YOU_SAW}' \
  --header 'Accept: application/json' \
  --header "Api-Key: $BRIDGE_API_KEY"
```

If there are new items, they’ll be returned; otherwise you may see an empty page.

## **Practical patterns**

### **Backfill all historical items (older direction)**

1. Request with your chosen `limit` (e.g., 100).
2. Process the page.
3. Save the last id from the page (the oldest in this batch).
4. Repeat with `starting_after=<last_id>` until `data` is empty.

### **Periodically check for new items (newer direction)**

1. Save the first id from your last successful fetch (the newest you’ve seen).
2. Request with `ending_before=<that_first_id>`.
3. If `data` is non-empty, process the new items and update your saved first id to the newest id returned.
4. If empty, nothing new is available.

### **Boundary behavior**

* Reached oldest items: using `starting_after` eventually returns `data: []`.
* No newer items: using `ending_before` may return `data: []`.

## **Tips and best practices**

* Treat item ids as stable cursors; always use the first and last ids from each page for the next request.
* Don’t combine `starting_after` and `ending_before` in the same call.
* Stick to a consistent `limit` for predictable throughput; max is 100.
* Expect partial pages near the ends (fewer than `limit` items).
* If you need to process items oldest-to-newest, reverse the page locally after fetching.
* When running concurrent pagination and ingestion, de-duplicate by `id` in your datastore.

## **Minimal JavaScript examples**

Assume a helper fetchFn(path) that does authenticated fetches relative to [**https://api.bridge.xyz**](https://api.bridge.xyz).

### **Backfill older pages**

```
// Fetch older pages until no more items are returned.
const backfillAll = async (fetchFn) => {
  let startingAfter = null;
  const pageSize = 100;

  while (true) {
    const qs = new URLSearchParams({ limit: String(pageSize) });
    if (startingAfter) qs.set("starting_after", startingAfter);

    const res = await fetchFn(`/v0/{resource}?${qs.toString()}`);
    const { data = [] } = await res.json();

    if (data.length === 0) break;

    // Process items (newest → oldest on this page)
    // ...

    // Next cursor: last id (oldest on this page)
    startingAfter = data[data.length - 1].id;
  }
};
```

### **Poll for newer items since a known id**

```
// Fetch any items newer than `firstSeenId`.
// Returns the updated newest id to store for next poll.
const fetchNewerSince = async (fetchFn, firstSeenId) => {
  const qs = new URLSearchParams({ ending_before: firstSeenId });
  const res = await fetchFn(`/v0/{resource}?${qs.toString()}`);
  const { data = [] } = await res.json();

  if (data.length > 0) {
    // Items returned are newest → oldest within the page.
    // Update the cursor to the newest id we now know about.
    return data[0].id;
  }
  return firstSeenId;
};
```

## **Summary**

* Results are newest → oldest by default.
* Use `starting_after=<last_id>` to go older.
* Use `ending_before=<first_id>` to fetch items newer than a known id.
* Control page size with `limit` (max 100).
* Stop when `data` is empty in the direction you’re traversing.