Pagination

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	10	1000	Yes
actions	10	1000	Yes
blocks	10	1000	Yes
messages	10	1000	Yes
traces	10	1000	Yes
jetton/burns	10	1000	Yes
jetton/transfers	10	1000	Yes
jetton/wallets	10	1000	Yes
nft/items	10	1000	Yes
nft/transfers	10	1000	Yes
multisig/orders	10	1000	Yes
multisig/wallets	10	1000	Yes
transactionsByMasterchainBlock	10	1000	Yes
jetton/masters	10	1000	No
nft/collections	10	1000	No
dns/records	100	1000	No
masterchainBlockShards	10	1000	No
topAccountsByBalance	10	1024	No
transactionsByMessage	10	1000	No
vesting	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	Required	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). Only available on sortable endpoints.

Pagination example

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

1. Fetch the first page

   Send a request with account and limit. No offset is needed for the first page (it defaults to 0).

   curl "https://toncenter.com/api/v3/transactions?account=EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2&limit=3"
   

   Response (abbreviated):

   {
     "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).

2. Fetch the next page

   Set offset=3 to skip the first 3 results and get the next batch.

   curl "https://toncenter.com/api/v3/transactions?account=EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2&limit=3&offset=3"
   

   Response (abbreviated):

   {
     "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.

3. 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.

Full pagination script

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:

--- 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

Sorting

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.

curl "https://toncenter.com/api/v3/transactions?account=EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2&limit=3&sort=asc"

Response (abbreviated):

{
  "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 (from July 2023 for this account).

Sorting with jetton/wallets

The jetton/wallets endpoint sorts by balance instead of logical time. Results may be inconsistent when paginating with limit and offset if balances change between requests.