feat(api): add pagination page for v3 api

docs.json

@@ -101,7 +101,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",

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.
+
+<Steps>
+  <Step
+    title="Fetch the first page"
+  >
+    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).
+  </Step>
+
+  <Step
+    title="Fetch the next page"
+  >
+    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.
+  </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
+  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
+  ```
+</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
+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.
+
+<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>