diff --git a/docs.json b/docs.json index 253cef7cf..ea7350a15 100644 --- a/docs.json +++ b/docs.json @@ -102,7 +102,8 @@ "pages": [ "ecosystem/api/toncenter/v3/overview", "ecosystem/api/toncenter/v3-errors", - "ecosystem/api/toncenter/v3-authentication" + "ecosystem/api/toncenter/v3-authentication", + "ecosystem/api/toncenter/v3-pagination" ], "openapi": { "source": "ecosystem/api/toncenter/v3.yaml", diff --git a/ecosystem/api/toncenter/v3-pagination.mdx b/ecosystem/api/toncenter/v3-pagination.mdx new file mode 100644 index 000000000..51aa3ba60 --- /dev/null +++ b/ecosystem/api/toncenter/v3-pagination.mdx @@ -0,0 +1,245 @@ +--- +title: "Pagination" +--- + +import { Aside } from '/snippets/aside.jsx'; + +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. + + + + Send a request with `account` and `limit`. `offset` defaults to `0` for the first page. + + ```bash + curl "https://toncenter.com/api/v3/transactions?account=EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2&limit=3" + ``` + + Response (abbreviated): + + ```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). + + + + Set `offset=3` to skip the first 3 results and get the next batch. + + ```bash + curl "https://toncenter.com/api/v3/transactions?account=EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2&limit=3&offset=3" + ``` + + Response (abbreviated): + + ```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. + + + + 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. + + + + + ```javascript + 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 + --- 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 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 +curl "https://toncenter.com/api/v3/transactions?account=EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2&limit=3&sort=asc" +``` + +Response (abbreviated): + +```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. + +