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 | 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.
Fetch the first page
Send a request with account and limit. offset defaults to 0 for the first page.
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).
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.
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.
Sorting options
Sortable endpoints accept a sort parameter with two values:
desc(default): newest results first, sorted by logical time (or UTC timestamp forblocks).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, starting from 2023-07 for this account.
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.
Last updated on