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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.ton.org/feedback

```json
{
  "path": "/ecosystem/api/toncenter/v3-pagination",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Pagination

export const Aside = ({type = "note", title = "", icon = "", iconType = "regular", children}) => {
  const asideVariants = ["note", "tip", "caution", "danger"];
  const asideComponents = {
    note: {
      outerStyle: "border-sky-500/20 bg-sky-50/50 dark:border-sky-500/30 dark:bg-sky-500/10",
      innerStyle: "text-sky-900 dark:text-sky-200",
      calloutType: "note",
      icon: <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="w-4 h-4 text-sky-500" aria-label="Note">
          <path fill-rule="evenodd" clip-rule="evenodd" d="M7 1.3C10.14 1.3 12.7 3.86 12.7 7C12.7 10.14 10.14 12.7 7 12.7C5.48908 12.6974 4.0408 12.096 2.97241 11.0276C1.90403 9.9592 1.30264 8.51092 1.3 7C1.3 3.86 3.86 1.3 7 1.3ZM7 0C3.14 0 0 3.14 0 7C0 10.86 3.14 14 7 14C10.86 14 14 10.86 14 7C14 3.14 10.86 0 7 0ZM8 3H6V8H8V3ZM8 9H6V11H8V9Z"></path>
        </svg>
    },
    tip: {
      outerStyle: "border-emerald-500/20 bg-emerald-50/50 dark:border-emerald-500/30 dark:bg-emerald-500/10",
      innerStyle: "text-emerald-900 dark:text-emerald-200",
      calloutType: "tip",
      icon: <svg width="11" height="14" viewBox="0 0 11 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="text-emerald-600 dark:text-emerald-400/80 w-3.5 h-auto" aria-label="Tip">
          <path d="M3.12794 12.4232C3.12794 12.5954 3.1776 12.7634 3.27244 12.907L3.74114 13.6095C3.88471 13.8248 4.21067 14 4.46964 14H6.15606C6.41415 14 6.74017 13.825 6.88373 13.6095L7.3508 12.9073C7.43114 12.7859 7.49705 12.569 7.49705 12.4232L7.50055 11.3513H3.12521L3.12794 12.4232ZM5.31288 0C2.52414 0.00875889 0.5 2.26889 0.5 4.78826C0.5 6.00188 0.949566 7.10829 1.69119 7.95492C2.14321 8.47011 2.84901 9.54727 3.11919 10.4557C3.12005 10.4625 3.12175 10.4698 3.12261 10.4771H7.50342C7.50427 10.4698 7.50598 10.463 7.50684 10.4557C7.77688 9.54727 8.48281 8.47011 8.93484 7.95492C9.67728 7.13181 10.1258 6.02703 10.1258 4.78826C10.1258 2.15486 7.9709 0.000106649 5.31288 0ZM7.94902 7.11267C7.52078 7.60079 6.99082 8.37878 6.6077 9.18794H4.02051C3.63739 8.37878 3.10743 7.60079 2.67947 7.11294C2.11997 6.47551 1.8126 5.63599 1.8126 4.78826C1.8126 3.09829 3.12794 1.31944 5.28827 1.3126C7.2435 1.3126 8.81315 2.88226 8.81315 4.78826C8.81315 5.63599 8.50688 6.47551 7.94902 7.11267ZM4.87534 2.18767C3.66939 2.18767 2.68767 3.16939 2.68767 4.37534C2.68767 4.61719 2.88336 4.81288 3.12521 4.81288C3.36705 4.81288 3.56274 4.61599 3.56274 4.37534C3.56274 3.6515 4.1515 3.06274 4.87534 3.06274C5.11719 3.06274 5.31288 2.86727 5.31288 2.62548C5.31288 2.38369 5.11599 2.18767 4.87534 2.18767Z"></path>
        </svg>
    },
    caution: {
      outerStyle: "border-amber-500/20 bg-amber-50/50 dark:border-amber-500/30 dark:bg-amber-500/10",
      innerStyle: "text-amber-900 dark:text-amber-200",
      calloutType: "warning",
      icon: <svg className="flex-none w-5 h-5 text-amber-400 dark:text-amber-300/80" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2" aria-label="Warning">
          <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"></path>
        </svg>
    },
    danger: {
      outerStyle: "border-red-500/20 bg-red-50/50 dark:border-red-500/30 dark:bg-red-500/10",
      innerStyle: "text-red-900 dark:text-red-200",
      calloutType: "danger",
      icon: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="currentColor" className="text-red-600 dark:text-red-400/80 w-4 h-4" aria-label="Danger">
          <path d="M17.1 292c-12.9-22.3-12.9-49.7 0-72L105.4 67.1c12.9-22.3 36.6-36 62.4-36l176.6 0c25.7 0 49.5 13.7 62.4 36L494.9 220c12.9 22.3 12.9 49.7 0 72L406.6 444.9c-12.9 22.3-36.6 36-62.4 36l-176.6 0c-25.7 0-49.5-13.7-62.4-36L17.1 292zm41.6-48c-4.3 7.4-4.3 16.6 0 24l88.3 152.9c4.3 7.4 12.2 12 20.8 12l176.6 0c8.6 0 16.5-4.6 20.8-12L453.4 268c4.3-7.4 4.3-16.6 0-24L365.1 91.1c-4.3-7.4-12.2-12-20.8-12l-176.6 0c-8.6 0-16.5 4.6-20.8 12L58.6 244zM256 128c13.3 0 24 10.7 24 24l0 112c0 13.3-10.7 24-24 24s-24-10.7-24-24l0-112c0-13.3 10.7-24 24-24zM224 352a32 32 0 1 1 64 0 32 32 0 1 1 -64 0z"></path>
        </svg>
    }
  };
  let variant = type;
  let gotInvalidVariant = false;
  if (!asideVariants.includes(type)) {
    gotInvalidVariant = true;
    variant = "danger";
  }
  const iconVariants = ["regular", "solid", "light", "thin", "sharp-solid", "duotone", "brands"];
  if (!iconVariants.includes(iconType)) {
    iconType = "regular";
  }
  return <>
      <div className={`callout my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border ${asideComponents[variant].outerStyle}`} data-callout-type={asideComponents[variant].calloutType}>
        <div className="mt-0.5 w-4" data-component-part="callout-icon">
          {}
          {icon === "" ? asideComponents[variant].icon : <Icon icon={icon} iconType={iconType} size={14} />}
        </div>
        <div className={`text-sm prose min-w-0 w-full ${asideComponents[variant].innerStyle}`} data-component-part="callout-content">
          {gotInvalidVariant ? <p>
              <span className="font-bold">
                Invalid <code>type</code> passed!
              </span>
              <br />
              <span className="font-bold">Received: </span>
              {type}
              <br />
              <span className="font-bold">Expected one of: </span>
              {asideVariants.join(", ")}
            </p> : <>
              {title && <p className="font-bold">{title}</p>}
              {children}
            </>}
        </div>
      </div>
    </>;
};

The v3 API uses offset-based pagination. Each paginated endpoint accepts `limit` and `offset` parameters. `limit` controls how many results to return per request, and `offset` skips a number of rows from the beginning of the result set. To retrieve the next page, increment `offset` by the value of `limit`.

The following endpoints support pagination:

| Endpoint                                                                                                              | Default limit | Max limit | Sortable |
| --------------------------------------------------------------------------------------------------------------------- | :-----------: | :-------: | :------: |
| [`transactions`](/ecosystem/api/toncenter/v3/blockchain-data/get-transactions)                                        |       10      |    1000   |    Yes   |
| [`actions`](/ecosystem/api/toncenter/v3/actions-and-traces/get-actions)                                               |       10      |    1000   |    Yes   |
| [`blocks`](/ecosystem/api/toncenter/v3/blockchain-data/get-blocks)                                                    |       10      |    1000   |    Yes   |
| [`messages`](/ecosystem/api/toncenter/v3/blockchain-data/get-messages)                                                |       10      |    1000   |    Yes   |
| [`traces`](/ecosystem/api/toncenter/v3/actions-and-traces/get-traces)                                                 |       10      |    1000   |    Yes   |
| [`jetton/burns`](/ecosystem/api/toncenter/v3/jettons/get-jetton-burns)                                                |       10      |    1000   |    Yes   |
| [`jetton/transfers`](/ecosystem/api/toncenter/v3/jettons/get-jetton-transfers)                                        |       10      |    1000   |    Yes   |
| [`jetton/wallets`](/ecosystem/api/toncenter/v3/jettons/get-jetton-wallets)                                            |       10      |    1000   |    Yes   |
| [`nft/items`](/ecosystem/api/toncenter/v3/nfts/get-nft-items)                                                         |       10      |    1000   |    Yes   |
| [`nft/transfers`](/ecosystem/api/toncenter/v3/nfts/get-nft-transfers)                                                 |       10      |    1000   |    Yes   |
| [`multisig/orders`](/ecosystem/api/toncenter/v3/multisig/get-multisig-orders)                                         |       10      |    1000   |    Yes   |
| [`multisig/wallets`](/ecosystem/api/toncenter/v3/multisig/get-multisig-wallets)                                       |       10      |    1000   |    Yes   |
| [`transactionsByMasterchainBlock`](/ecosystem/api/toncenter/v3/blockchain-data/get-transactions-by-masterchain-block) |       10      |    1000   |    Yes   |
| [`jetton/masters`](/ecosystem/api/toncenter/v3/jettons/get-jetton-masters)                                            |       10      |    1000   |    No    |
| [`nft/collections`](/ecosystem/api/toncenter/v3/nfts/get-nft-collections)                                             |       10      |    1000   |    No    |
| [`dns/records`](/ecosystem/api/toncenter/v3/dns/get-dns-records)                                                      |      100      |    1000   |    No    |
| [`masterchainBlockShards`](/ecosystem/api/toncenter/v3/blockchain-data/get-masterchain-block-shard-state-1)           |       10      |    1000   |    No    |
| [`topAccountsByBalance`](/ecosystem/api/toncenter/v3/stats/get-top-accounts-by-balance)                               |       10      |    1024   |    No    |
| [`transactionsByMessage`](/ecosystem/api/toncenter/v3/blockchain-data/get-transactions-by-message)                    |       10      |    1000   |    No    |
| [`vesting`](/ecosystem/api/toncenter/v3/vesting/get-vesting-contracts)                                                |       10      |    1000   |    No    |

All other v3 endpoints return single objects or fixed results and do not support pagination.

## Parameters

These parameters are shared across all paginated endpoints.

| Parameter | Type    | Description                                                                                               |
| --------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `limit`   | integer | Maximum number of rows to return. Defaults vary by endpoint; see table above.                             |
| `offset`  | integer | Number of rows to skip from the beginning of the result set. Default is `0`.                              |
| `sort`    | string  | Sort order: `desc` (default, newest first) or `asc` (oldest first). Available only on sortable endpoints. |

## Pagination example

This example uses the `transactions` endpoint, but the same `limit` and `offset` pattern applies to all paginated endpoints.

<Steps>
  <Step title="Fetch the first page">
    Send a request with `account` and `limit`. `offset` defaults to `0` for the first page.

    ```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
    curl "https://toncenter.com/api/v3/transactions?account=EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2&limit=3"
    ```

    Response (abbreviated):

    ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
    {
      "transactions": [
        {
          "account": "0:ED1691307050047117B998B561D8DE82D31FBF84910CED6EB5FC92E7485EF8A7",
          "hash": "KkpVTX9RwiZcug8KQuOFUF8+eNoxuHVuIFpGQqufCWU=",
          "lt": "67064337000004",
          "now": 1771410670
        },
        {
          "account": "0:ED1691307050047117B998B561D8DE82D31FBF84910CED6EB5FC92E7485EF8A7",
          "hash": "b5fhFby+j8gg936W+XEsAEhboQW0zPcOHOHgyqXkTwI=",
          "lt": "67011337000003",
          "now": 1771286044
        },
        {
          "account": "0:ED1691307050047117B998B561D8DE82D31FBF84910CED6EB5FC92E7485EF8A7",
          "hash": "lT/wWTiJIdEF8A2Rox9CRdQRzlUgnIDGeUfEHQ8jGZQ=",
          "lt": "66986300000006",
          "now": 1771226782
        }
      ],
      "address_book": { ... }
    }
    ```

    Three transactions returned, sorted by logical time in descending order (newest first).
  </Step>

  <Step title="Fetch the next page">
    Set `offset=3` to skip the first 3 results and get the next batch.

    ```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
    curl "https://toncenter.com/api/v3/transactions?account=EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2&limit=3&offset=3"
    ```

    Response (abbreviated):

    ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
    {
      "transactions": [
        {
          "account": "0:ED1691307050047117B998B561D8DE82D31FBF84910CED6EB5FC92E7485EF8A7",
          "hash": "07QaeBRRA62+RJPgetgSraYLH5i9G5QhC2dUvKAsAiI=",
          "lt": "66927779000007",
          "now": 1771088713
        },
        {
          "account": "0:ED1691307050047117B998B561D8DE82D31FBF84910CED6EB5FC92E7485EF8A7",
          "hash": "8d7sSor1NqbGNdX1JEGl1d4rX3lb7CeC3DZjhe7V7z4=",
          "lt": "66927779000003",
          "now": 1771088713
        },
        {
          "account": "0:ED1691307050047117B998B561D8DE82D31FBF84910CED6EB5FC92E7485EF8A7",
          "hash": "szM1I5/MU1uJGgeScS7uxNF6V/FsLkokCpul88ZEau8=",
          "lt": "66926353000007",
          "now": 1771085323
        }
      ],
      "address_book": { ... }
    }
    ```

    No overlap with the previous page. Offset pagination does not produce duplicates.
  </Step>

  <Step title="Repeat until the last page">
    Continue incrementing `offset` by the `limit` value on each request (`offset=6`, `offset=9`, ...). When the response returns fewer transactions than the `limit`, all results have been retrieved.
  </Step>
</Steps>

<Accordion title="Full pagination script">
  ```javascript theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
  const address = "EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2";

  async function main() {
    let allTransactions = [];
    let offset = 0;
    const limit = 3;
    let page = 0;

    while (true) {
      page++;
      const params = new URLSearchParams({
        account: address,
        limit: String(limit),
        offset: String(offset),
      });

      const res = await fetch(
        `https://toncenter.com/api/v3/transactions?${params}`
      );
      const data = await res.json();
      const transactions = data.transactions || [];

      console.log(`\n--- Page ${page} (offset=${offset}) ---`);

      for (const tx of transactions) {
        console.log(`  lt: ${tx.lt}  hash: ${tx.hash}`);
      }

      allTransactions.push(...transactions);

      if (transactions.length < limit) break;

      offset += limit;
    }

    console.log(`\nTotal transactions: ${allTransactions.length}`);
  }

  main();
  ```

  Output:

  ```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
  --- Page 1 (offset=0) ---
    lt: 67064337000004  hash: KkpVTX9RwiZcug8KQuOFUF8+eNoxuHVuIFpGQqufCWU=
    lt: 67011337000003  hash: b5fhFby+j8gg936W+XEsAEhboQW0zPcOHOHgyqXkTwI=
    lt: 66986300000006  hash: lT/wWTiJIdEF8A2Rox9CRdQRzlUgnIDGeUfEHQ8jGZQ=

  --- Page 2 (offset=3) ---
    lt: 66927779000007  hash: 07QaeBRRA62+RJPgetgSraYLH5i9G5QhC2dUvKAsAiI=
    lt: 66927779000003  hash: 8d7sSor1NqbGNdX1JEGl1d4rX3lb7CeC3DZjhe7V7z4=
    lt: 66926353000007  hash: szM1I5/MU1uJGgeScS7uxNF6V/FsLkokCpul88ZEau8=

  --- Page 3 (offset=6) ---

  Total transactions: 6
  ```
</Accordion>

## Sorting options

Sortable endpoints accept a `sort` parameter with two values:

* `desc` (default): newest results first, sorted by logical time (or UTC timestamp for `blocks`).
* `asc`: oldest results first.

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
curl "https://toncenter.com/api/v3/transactions?account=EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2&limit=3&sort=asc"
```

Response (abbreviated):

```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
{
  "transactions": [
    {
      "hash": "3ziyP0yvGklMTNWWXDplmlBcPH0P7MJtusoVthNu8e0=",
      "lt": "39547833000003",
      "now": 1690204554
    },
    {
      "hash": "lYXDtLL53JkKa35vP05gbwTyd6Lq4335TwlZeUebxZ8=",
      "lt": "39547876000003",
      "now": 1690204686
    },
    {
      "hash": "DSz0P/wmE0EkdfaxFl2R36Eie+Lw4paLa1sAHHUliJA=",
      "lt": "39548648000003",
      "now": 1690207175
    }
  ],
  "address_book": { ... }
}
```

With `sort=asc`, the earliest transactions are returned first, starting from 2023-07 for this account.

<Aside type="caution" title="Sorting with jetton/wallets">
  The `jetton/wallets` endpoint sorts results by balance instead of logical time. When balances change between requests, using `limit` and `offset` can skip or repeat wallets because the sort order changes between pages.
</Aside>