Pagination

What this is. Every v3 list endpoint returns results in chunks. You navigate forward or backward using an opaque cursor the server returns to you. Cursors are tokens: treat them as strings, and pass them back unchanged. When it matters. Any time you list trades, deposits, withdrawals, withdrawal accounts, accounts, payout addresses, or payouts. Two common patterns: “load all records” (back-fill into your DB) and “fetch what’s new since I last polled” (continuous sync). What you’ll learn. The request parameters, response envelope, forward and backward iteration patterns, and why page numbers (and total counts) don’t exist here. These v3 list endpoints use cursor pagination: GET /v3/fx/trades, GET /v3/fx/deposits, GET /v3/fx/withdrawals, GET /v3/fx/withdrawal-accounts, GET /v3/common/accounts, GET /v3/payments/payout-addresses, and GET /v3/payments/payouts. Results are sorted newest-first by createdAt and you page through them using cursors returned in the response. Default page size is 25; maximum is 100.

Request parameters

Param	Type	Default	Notes
`limit`	integer (1–100)	25	Max records per page
`startingAfter`	opaque cursor string	none	Return records older than the cursor’s position (next page)
`endingBefore`	opaque cursor string	none	Return records newer than the cursor’s position (previous page)

startingAfter and endingBefore are mutually exclusive. Set one or the other, not both. On the first request, omit both. You get the newest page.

Cursors are opaque. The cursor value the server returns is a string token. Treat it as opaque. Do not decode, trim, re-encode, parse, or substitute its contents. Pass it back verbatim. The token’s internal format is an implementation detail and OpenFX reserves the right to change it.

Mental model. Lists are newest-first, so “starting after this cursor” means “older than the records this cursor points at” and “ending before this cursor” means “newer than the records this cursor points at”. Think of the cursor as a position on a vertical timeline with newest at the top.

Response envelope

Paginated responses wrap the array of records in a pagination envelope that carries the cursors for navigation:

{
  "data": [],
  "pagination": {
    "limit": 25,
    "hasNext": true,
    "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTAyLTA3VDEzOjAyOjI5LjE0N1oiLCJpZCI6IjZhOGRmZjAzLWFiY2QtNDEyMy1iYWNkLTAxMjM0NTY3ODlhYiJ9",
    "hasPrev": false,
    "prevCursor": null
  }
}

Field	Type	Notes
`data`	array	The records on this page, newest-first.
`pagination.limit`	integer	The `limit` the server used (echoes your request or the default).
`pagination.hasNext`	boolean	`true` if more records exist after this page: the signal to keep paginating forward. `false` on the last page.
`pagination.nextCursor`	`string \| null`	Opaque token for the next page (older records); pass to `?startingAfter=`. `null` when `hasNext` is `false`.
`pagination.hasPrev`	boolean	`true` if records exist before this page: the signal to keep paginating backward. `false` on the first page.
`pagination.prevCursor`	`string \| null`	Opaque token for the previous page (newer records); pass to `?endingBefore=`. `null` when `hasPrev` is `false`.

hasNext / hasPrev are the booleans you branch on; nextCursor / prevCursor are the tokens you pass back. A page with both hasNext: false and hasPrev: false is the entire paginated result set.

Bounded lists do not paginate. GET /v3/fx/pairs and GET /v3/fx/balances return their complete data array without cursor parameters or a pagination object. Apply the cursor flow on this page to the paginated lists above.

What’s not in the response. total, total_count, and total_pages are intentionally not part of the envelope. Running a COUNT(*) on every list call would defeat the cursor-seek index plan that keeps list endpoints fast at scale. Use hasNext / hasPrev to detect whether more pages exist; there is no total-count or page-number field.

Decoding cursors

Don’t. Cursors are opaque. Clients should never decode, parse, trim, re-encode, or substitute them. The cursor format is an implementation detail of the server, and OpenFX reserves the right to change it at any time without notice (different encoding, different payload fields, different length). Code that decodes cursors will break the day the encoding changes. The contract is: the server returns a cursor string; the client passes that same string back verbatim on the next request via ?startingAfter= or ?endingBefore=. Round-trip it as opaque bytes.

Cursor direction visualized

The timeline below shows a list of trades with the newest at the top. Suppose pagination.nextCursor from a previous response is currently positioned at trade C (highlighted). Each cursor parameter selects a different window:

Request	Returns	When to use
`?endingBefore=<cursor at C>`	`[A, B]` (newer than C, newest-first within the window)	“Fetch what’s new since I last saw trade C.”
`?startingAfter=<cursor at C>`	`[D, E]` (older than C, newest-first within the window)	“Continue paginating into history past trade C.”
`?startingAfter=<cursor at E>`	`[]` with `pagination.hasNext: false`, `nextCursor: null`	You’ve reached the oldest record: nothing older than E.
`?endingBefore=<cursor at A>`	`[]` with `pagination.hasPrev: false`, `prevCursor: null`	You’re already at the newest record: nothing newer than A.

The records the cursor refers to are not included in the result page. startingAfter returns records older than the cursor’s position; endingBefore returns records newer than it.

Worked example: fetch all trades (forward iteration)

Walk forward (newest → oldest) until hasNext is false. JWT TTL is 60s; a full back-fill across thousands of records can outlive it, so each of these signs per page rather than capturing one token. See Rate limiting → Handling rate limits pattern.

// Walks GET /v3/fx/trades forward (newest -> oldest) until hasNext is
// false — the pattern from /v3/pagination#worked-example-fetch-all-trades-forward-iteration.
// signRequest is the real helper from /v3/authentication — adjust this path
// if you've copied it somewhere else in your own project.
const { signRequest } = require("../../authentication/node/sign-request");
// Fetches one page. Takes signRequest and the HTTP call as parameters so
// the cursor-walking logic below is testable without a real request.
async function fetchPage(signRequest, cursor) {
  const url = new URL("https://api.openfx.com/v3/fx/trades");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("startingAfter", cursor);
  // Sign per page: the wall-clock to walk all pages is unbounded by the
  // JWT's 60s TTL.
  const { headers } = signRequest({ method: "GET", url: url.toString() });
  const res = await fetch(url, { headers });
  return res.json();
}
// Walks forward until hasNext is false. Takes fetchPage as a parameter so
// the cursor-threading and termination logic is testable without a real
// request or real credentials.
async function* allTrades(signRequest, fetchPageFn = fetchPage) {
  let cursor = null;
  while (true) {
    const page = await fetchPageFn(signRequest, cursor);
    for (const trade of page.data) yield trade;
    if (!page.pagination.hasNext) return;
    cursor = page.pagination.nextCursor; // opaque token, round-trip verbatim
  }
}
module.exports = { allTrades, fetchPage };
if (require.main === module) {
  (async () => {
    try {
      for await (const trade of allTrades(signRequest)) {
        console.log(trade.id, trade.createdAt);
      }
    } catch (err) {
      console.error("Error:", err.message);
      process.exitCode = 1;
    }
  })();
}

"""Walks GET /v3/fx/trades forward (newest -> oldest) until hasNext is
false — the pattern from
/v3/pagination#worked-example-fetch-all-trades-forward-iteration."""
import os
import sys
# sign_request is the real helper from /v3/authentication — adjust this path
# if you've copied it somewhere else in your own project.
sys.path.insert(
    0, os.path.join(os.path.dirname(__file__), "..", "..", "authentication", "python")
)
from sign_request import sign_request  # noqa: E402
import requests  # noqa: E402
def fetch_page(sign_request_fn, cursor):
    """Fetches one page. Takes sign_request as a parameter so the
    cursor-walking logic below is testable without a real request."""
    params = {"limit": 100}
    if cursor:
        params["startingAfter"] = cursor
    url = "https://api.openfx.com/v3/fx/trades"
    prepared = requests.Request("GET", url, params=params).prepare()
    # Sign per page: the wall-clock to walk all pages is unbounded by the
    # JWT's 60s TTL.
    headers, _ = sign_request_fn("GET", prepared.url, b"")
    return requests.get(prepared.url, headers=headers).json()
def all_trades(sign_request_fn, fetch_page_fn=fetch_page):
    """Walks forward until hasNext is false. Takes fetch_page as a parameter
    so the cursor-threading and termination logic is testable without a
    real request or real credentials."""
    cursor = None
    while True:
        page = fetch_page_fn(sign_request_fn, cursor)
        for trade in page["data"]:
            yield trade
        if not page["pagination"]["hasNext"]:
            return
        cursor = page["pagination"]["nextCursor"]  # opaque token, round-trip verbatim
if __name__ == "__main__":
    for trade in all_trades(sign_request):
        print(trade["id"], trade["createdAt"])

// Walks GET /v3/fx/trades forward (newest -> oldest) until hasNext is
// false — the pattern from
// /v3/pagination#worked-example-fetch-all-trades-forward-iteration.
import java.net.HttpURLConnection;
import java.net.URI;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.function.BiFunction;
public class AllTrades {
    // A minimal page shape: just the two fields the walking logic needs.
    static class Page {
        final List<String> tradeIds;
        final boolean hasNext;
        final String nextCursor;
        Page(List<String> tradeIds, boolean hasNext, String nextCursor) {
            this.tradeIds = tradeIds;
            this.hasNext = hasNext;
            this.nextCursor = nextCursor;
        }
    }
    // Named Signer, not SignRequest, to avoid colliding with the real
    // SignRequest class from /v3/authentication, compiled alongside this
    // file on the classpath.
    interface Signer {
        Map<String, String> signRequest(String method, String url, byte[] body) throws Exception;
    }
    // Fetches one page. Takes signer as a parameter so the cursor-walking
    // logic below is testable without a real request.
    static Page fetchPage(Signer signer, String cursor) throws Exception {
        String url = "https://api.openfx.com/v3/fx/trades?limit=100"
                + (cursor != null ? "&startingAfter=" + cursor : "");
        // Sign per page: the wall-clock to walk all pages is unbounded by
        // the JWT's 60s TTL.
        Map<String, String> headers = signer.signRequest("GET", url, new byte[0]);
        HttpURLConnection conn = (HttpURLConnection) URI.create(url).toURL().openConnection();
        conn.setRequestMethod("GET");
        for (Map.Entry<String, String> h : headers.entrySet()) {
            conn.setRequestProperty(h.getKey(), h.getValue());
        }
        conn.getResponseCode();
        // A real implementation would parse the JSON response body here,
        // using whatever JSON library you're already using.
        return new Page(List.of(), false, null);
    }
    // Walks forward until hasNext is false. Takes fetchPage as a parameter
    // so the cursor-threading and termination logic is testable without a
    // real request or real credentials.
    static List<String> allTrades(Signer signer, BiFunction<Signer, String, Page> fetchPageFn) {
        List<String> ids = new ArrayList<>();
        String cursor = null;
        while (true) {
            Page page = fetchPageFn.apply(signer, cursor);
            ids.addAll(page.tradeIds);
            if (!page.hasNext) return ids;
            cursor = page.nextCursor; // opaque token, round-trip verbatim
        }
    }
    // Adapts fetchPage (which throws) to the checked-exception-free
    // BiFunction shape allTrades needs.
    static Page fetchPageUnchecked(Signer signer, String cursor) {
        try {
            return fetchPage(signer, cursor);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
    public static void main(String[] args) {
        // SignRequest is the real helper from /v3/authentication, compiled
        // on the classpath alongside this file — see that page's example.
        List<String> ids = allTrades(SignRequest::signRequest, AllTrades::fetchPageUnchecked);
        System.out.println(ids);
    }
}

// Walks GET /v3/fx/trades forward (newest -> oldest) until hasNext is
// false — the pattern from
// /v3/pagination#worked-example-fetch-all-trades-forward-iteration.
// Requires OpenSSL and libcurl.
#include <curl/curl.h>
#include <functional>
#include <optional>
#include <string>
#include <vector>
// Matches the definition in ../../authentication/cpp/sign_request.cpp,
// compiled together with this file — see that file for the real
// implementation of signRequest.
struct SignedRequest {
    std::string authHeader;
    std::string sigHeader;
};
SignedRequest signRequest(const std::string& method, const std::string& urlPath,
                           const std::string& query, const std::string& body);
// A minimal page shape: just the two fields the walking logic needs.
struct Page {
    std::vector<std::string> tradeIds;
    bool hasNext;
    std::optional<std::string> nextCursor;
};
using Signer = std::function<SignedRequest(const std::string&, const std::string&, const std::string&, const std::string&)>;
using FetchPageFn = std::function<Page(const Signer&, const std::optional<std::string>&)>;
static size_t discard(char*, size_t s, size_t n, void*) { return s * n; }
// Fetches one page. Takes signer as a parameter so the cursor-walking
// logic below is testable without a real request.
Page fetchPage(const Signer& signer, const std::optional<std::string>& cursor) {
    std::string query = "limit=100";
    if (cursor) query += "&startingAfter=" + *cursor;
    std::string url = "https://api.openfx.com/v3/fx/trades?" + query;
    // Sign per page: the wall-clock to walk all pages is unbounded by the
    // JWT's 60s TTL.
    SignedRequest req = signer("GET", "/v3/fx/trades", query, "");
    CURL* curl = curl_easy_init();
    curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, ("Authorization: " + req.authHeader).c_str());
    headers = curl_slist_append(headers, ("X-Request-Signature: " + req.sigHeader).c_str());
    curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, discard);
    curl_easy_perform(curl);
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    // A real implementation would parse the JSON response body here,
    // using whatever JSON library you're already using.
    return {{}, false, std::nullopt};
}
// Walks forward until hasNext is false. Takes fetchPage as a parameter so
// the cursor-threading and termination logic is testable without a real
// request or real credentials.
std::vector<std::string> allTrades(const Signer& signer, const FetchPageFn& fetchPageFn) {
    std::vector<std::string> ids;
    std::optional<std::string> cursor = std::nullopt;
    while (true) {
        Page page = fetchPageFn(signer, cursor);
        for (auto& id : page.tradeIds) ids.push_back(id);
        if (!page.hasNext) return ids;
        cursor = page.nextCursor; // opaque token, round-trip verbatim
    }
}
#ifndef ALL_TRADES_NO_MAIN
#include <iostream>
int main() {
    try {
        auto ids = allTrades(signRequest, fetchPage);
        for (auto& id : ids) std::cout << id << std::endl;
        return 0;
    } catch (const std::exception& e) {
        std::cerr << "Error: " << e.what() << std::endl;
        return 1;
    }
}
#endif

// Walks GET /v3/fx/trades forward (newest -> oldest) until hasNext is
// false — the pattern from
// /v3/pagination#worked-example-fetch-all-trades-forward-iteration.
package main
import (
	"fmt"
	"net/http"
	// auth is the real signRequest helper from /v3/authentication — see
	// go.mod's replace directive if you've copied it somewhere else.
	auth "openfx-v3-authentication-example"
)
// Matches auth.SignRequest's signature, so that function can be passed
// directly wherever a SignerFunc is expected.
type SignerFunc func(method, url string, body []byte) (*auth.SignedRequest, error)
// A minimal page shape: just the two fields the walking logic needs.
type Page struct {
	TradeIDs   []string
	HasNext    bool
	NextCursor *string
}
// Fetches one page. Takes signer as a parameter so the cursor-walking
// logic below is testable without a real request.
func fetchPage(signer SignerFunc, cursor *string) (*Page, error) {
	url := "https://api.openfx.com/v3/fx/trades?limit=100"
	if cursor != nil {
		url += "&startingAfter=" + *cursor
	}
	// Sign per page: the wall-clock to walk all pages is unbounded by the
	// JWT's 60s TTL.
	signed, err := signer("GET", url, nil)
	if err != nil {
		return nil, err
	}
	req, err := http.NewRequest("GET", url, nil)
	if err != nil {
		return nil, err
	}
	for k, v := range signed.Headers {
		req.Header.Set(k, v)
	}
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()
	// A real implementation would parse the JSON response body here.
	return &Page{HasNext: false}, nil
}
type fetchPageFunc func(signer SignerFunc, cursor *string) (*Page, error)
// Walks forward until hasNext is false. Takes fetchPage as a parameter so
// the cursor-threading and termination logic is testable without a real
// request or real credentials.
func allTrades(signer SignerFunc, fetchPageFn fetchPageFunc) ([]string, error) {
	var ids []string
	var cursor *string
	for {
		page, err := fetchPageFn(signer, cursor)
		if err != nil {
			return nil, err
		}
		ids = append(ids, page.TradeIDs...)
		if !page.HasNext {
			return ids, nil
		}
		cursor = page.NextCursor // opaque token, round-trip verbatim
	}
}
func main() {
	ids, err := allTrades(auth.SignRequest, fetchPage)
	if err != nil {
		fmt.Println("Error:", err)
		return
	}
	fmt.Println(ids)
}

#!/usr/bin/env bash
# Walks GET /v3/fx/trades forward (newest -> oldest) until hasNext is false
# — the pattern from
# /v3/pagination#worked-example-fetch-all-trades-forward-iteration.
# Illustrative only: cURL can't compute the ES256 request signature itself,
# so $OPENFX_JWT/$OPENFX_SIGNATURE below are placeholders — get real values
# from signRequest, in any supported language, via /v3/authentication. Sign
# per page: the wall-clock to walk all pages is unbounded by the JWT's 60s
# TTL. X-App-Mode is hard-coded to SANDBOX below. To target Live, use a Live API
# key (mint the JWT from it) and set X-App-Mode to LIVE.
set -euo pipefail
extract_field() { # $1: JSON, $2: field name
  echo "$1" | grep -o "\"$2\":\"[^\"]*\"" | head -1 | sed -E "s/.*:\"([^\"]*)\"/\1/"
}
extract_bool() { # $1: JSON, $2: field name
  echo "$1" | grep -o "\"$2\":[a-z]*" | head -1 | sed -E "s/.*:([a-z]*)/\1/"
}
CURSOR=""
while true; do
  URL="https://api.openfx.com/v3/fx/trades?limit=100"
  if [ -n "$CURSOR" ]; then
    URL="$URL&startingAfter=$CURSOR"
  fi
  export OPENFX_JWT="<jwt-from-signRequest>"
  export OPENFX_SIGNATURE="<signature-from-signRequest>"
  PAGE=$(curl -s "$URL" \
    -H "Authorization: Bearer $OPENFX_JWT" \
    -H "X-Request-Signature: $OPENFX_SIGNATURE" \
    -H "X-App-Mode: SANDBOX")
  echo "$PAGE" | grep -o '"id":"[^"]*"'
  HAS_NEXT=$(extract_bool "$PAGE" "hasNext")
  if [ "$HAS_NEXT" != "true" ]; then
    break
  fi
  CURSOR=$(extract_field "$PAGE" "nextCursor") # opaque token, round-trip verbatim
done

Worked example: walk backward from a known cursor

The mirror image of the forward walk: page from a starting point toward the newest record, stopping when hasPrev is false (equivalently, when prevCursor is null). Useful for catch-up loops that recover a gap older than your most recent sync.

// `signRequest({ method, url, body })` returns { headers, body } with a freshly minted JWT
// AND a freshly computed X-Request-Signature each call. See the Authentication guide.
// `startCursor` is a cursor you saved from a previous request. Iteration ends when
// prevCursor === null (the head of the list).
async function* tradesNewerThan(signRequest, startCursor) {
  let cursor = startCursor;
  while (cursor !== null) {
    const url = new URL("https://api.openfx.com/v3/fx/trades");
    url.searchParams.set("limit", "100");
    url.searchParams.set("endingBefore", cursor);

    const signed = signRequest({
      method: "GET",
      url: url.toString(),
    });
    const page = await fetch(url, { headers: signed.headers }).then((r) =>
      r.json(),
    );

    for (const trade of page.data) yield trade;
    cursor = page.pagination.prevCursor; // opaque; null when we've reached the newest record
  }
}

Worked example: fetch “what’s new since last seen”

The typical sync-job pattern: you’ve persisted the most recent cursor from your last poll; on this poll you want only the new records that have appeared since.

Get a starting cursor

A first run has no saved cursor, and the newest page returns prevCursor: null, so there is nothing to start from. Request a single-record page instead and keep its nextCursor. A nextCursor sits on the last record of its page, so with limit=1 it sits on the newest record, and endingBefore with that cursor returns only records newer than it. The nextCursor is null when the list holds one record or none (hasNext is false), so wait and request again until it returns a cursor. You use the same request on every later poll to refresh your saved cursor (see Poll for new records).

// `signRequest({ method, url, body })` returns { headers, body } with a freshly minted JWT
// AND a freshly computed X-Request-Signature each call. See the Authentication guide.
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function getJson(url) {
  const signed = signRequest({ method: "GET", url: url.toString() });
  return fetch(url, { headers: signed.headers }).then((r) => r.json());
}

// Fetch the single newest record and return its nextCursor, or null if there is none yet.
async function fetchNewestCursor() {
  const url = new URL("https://api.openfx.com/v3/fx/trades");
  url.searchParams.set("limit", "1");
  const page = await getJson(url);
  return page.pagination.nextCursor;
}

// First run only: retry with a pause until the list holds a cursor to start from.
async function getStartingCursor(maxAttempts = 10, delayMs = 30000) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const cursor = await fetchNewestCursor();
    if (cursor !== null) return cursor;
    if (attempt < maxAttempts) await sleep(delayMs);
  }
  return null; // Still no cursor: try again later.
}

Take this cursor before you load existing history. Records created while the load runs then arrive in your first poll instead of falling between the two. Because a poll can return a record more than once, make your handler idempotent on resource ID.

The starting-cursor request applies to the FX lists (GET /v3/fx/trades, /deposits, /withdrawals, and /withdrawal-accounts).

Poll for new records

A backward page (endingBefore) returns prevCursor only while more newer records remain (hasPrev is true). The page that reaches the newest record returns prevCursor: null, so it gives you nothing to save. To move your saved cursor forward, request the newest-record cursor again with the limit=1 request above. Request that cursor before you read the new records, so a record created during the poll arrives in the next poll instead of falling between the two. Then page toward the newest record with prevCursor until hasPrev is false, and save the refreshed cursor.

// Reuses `sleep`, `getJson`, and `fetchNewestCursor` from the previous example.
// `signRequest` mints a fresh JWT and X-Request-Signature on every call. If you run this in a
// sync loop every N minutes, call it once per poll and sleep between polls. See Rate limiting →
// Handling rate limits pattern: https://docs.openfx.com/v3/rate-limiting#handling-rate-limits-pattern
//
// Returns the cursor to save. Persist it only after `handleRecords` has succeeded for every page.
async function pollNewTrades(lastSeenCursor, handleRecords) {
  // 1. Refresh the saved cursor first. Null means fewer than two records exist: keep the old one.
  const newestCursor = await fetchNewestCursor();

  // 2. Page toward the newest record.
  let cursor = lastSeenCursor;
  for (;;) {
    const url = new URL("https://api.openfx.com/v3/fx/trades");
    url.searchParams.set("limit", "25");
    url.searchParams.set("endingBefore", cursor);
    const page = await getJson(url);

    // page.data holds records newer than the cursor, newest-first within the page.
    await handleRecords(page.data);

    if (!page.pagination.hasPrev) break; // Reached the newest record.
    cursor = page.pagination.prevCursor;
  }

  return newestCursor ?? lastSeenCursor;
}

For a continuous sync loop, persist the returned cursor only after you’ve successfully handled the records in every page. If your handler crashes before the DB write, the next poll re-fetches the same records. That’s safe, because your handler should be idempotent on resource ID.

Why cursor pagination

Page-based pagination (?page=2&limit=25) breaks down at scale:

New records appearing during pagination cause records to shift between pages (you see the same trade twice or miss one)
Deep pages get progressively slower (the database has to skip every prior row)
“How many pages total?” requires a separate COUNT(*) query

Cursors fix all three. The cursor encodes the row’s position; the server seeks directly to that position and reads the next page from there. The pagination envelope makes the cursor a first-class field of the response, so clients never have to guess where the cursor “is”; the server hands it back to you.

Common mistakes

Decoding or parsing the cursor. Cursors are opaque. Don’t decode them, don’t try to extract anything from them, don’t munge them. Pass the string back exactly as you received it. The format is an implementation detail and will change.
Picking the wrong cursor for the direction you want. For “load all” (forward), use pagination.nextCursor and pass it as ?startingAfter=. For “what’s new since” (backward), use pagination.prevCursor and pass it as ?endingBefore=. Mixing them sends you in the wrong direction.
Sorting the data array client-side and then deriving a cursor. The cursor is in the response envelope, not in the array. Read pagination.nextCursor / pagination.prevCursor directly; sort data for display second.
Re-deriving “is there more?” from the cursor when the boolean is right there. pagination.hasNext and pagination.hasPrev are the canonical end-of-list signals: branch on them. (A cursor is null whenever its boolean is false, but the booleans are the contract.)
Setting both startingAfter and endingBefore. They are mutually exclusive. Pick a direction.
Treating limit as a guarantee. It’s a max. The server may return fewer records. Paginate until pagination.hasNext is false, not until data.length < limit.
Persisting cursors longer than the resource lives. Cursors point to a position in the underlying sort. If the record they point to is purged (rare on Trade / Trade-account resources at any meaningful timescale), paginating past it returns the next-newest record.

Gotchas

Cursors are stable across requests. A cursor you persisted yesterday continues to point to the same position in the list today (subject to record retention).
limit is a max, not a guarantee. The server may return fewer records than requested if filters apply.
nextCursor and prevCursor reflect the chosen direction independently. A page returned via ?startingAfter= still carries a prevCursor you can use to walk back if you need to. The envelope is symmetric: only the request parameter says which direction you’re moving.
Empty page on the boundary. Calling ?startingAfter=<cursor at oldest record> returns data: [] with pagination.hasNext: false and pagination.nextCursor: null, not an error.

What’s next

Rate limiting

The back-off pattern for back-fill loops that hit RATE_LIMIT_EXCEEDED.

Idempotency

Make sync jobs safe across crashes and restarts.

List trades

Paginate trades via the canonical list endpoint.

Retrieve a trade

Fetch a single record by ID without paging.

Core concepts

Endpoints

Webhooks

Request parameters

Response envelope

Decoding cursors

Cursor direction visualized

Worked example: fetch all trades (forward iteration)

Worked example: walk backward from a known cursor

Worked example: fetch “what’s new since last seen”

Get a starting cursor

Poll for new records

Common mistakes

Gotchas

What’s next

Rate limiting

Idempotency

List trades

Retrieve a trade

​Request parameters

​Response envelope

​Decoding cursors

​Cursor direction visualized

​Worked example: fetch all trades (forward iteration)

​Worked example: walk backward from a known cursor

​Worked example: fetch “what’s new since last seen”

​Get a starting cursor

​Poll for new records

​Why cursor pagination

​Common mistakes

​Gotchas

​What’s next

Rate limiting

Idempotency

List trades

Retrieve a trade

Request parameters

Response envelope

Decoding cursors

Cursor direction visualized

Worked example: fetch all trades (forward iteration)

Worked example: walk backward from a known cursor

Worked example: fetch “what’s new since last seen”

Get a starting cursor

Poll for new records

Why cursor pagination

Common mistakes

Gotchas

What’s next