The v2 API uses cursor-based pagination to retrieve large result sets in batches. Instead of specifying a page number, the identifier of the last record received is passed to the API, which returns the next batch starting from that point. This ensures consistent results even when new data is being added.Three endpoints support pagination:
All other v2 endpoints return single objects or fixed results and do not support pagination.
URL encodingTransaction hashes are base64-encoded and may contain +, /, and = characters. These must be URL-encoded when passed as query parameters: + → %2B, / → %2F, = → %3D. Most HTTP libraries handle this automatically, but this is important when constructing URLs manually.
Returns the transaction history of a given account. Results are ordered by logical time in descending order (newest first).Pagination uses lt and hash as a cursor pair. Both must be provided together. These values come from the last transaction in the previous response.
Inclusive cursorThe transaction passed as lt/hash is included as the first result in the next response. In the responses above, transaction 66784070000010 appears as the last item on page 1 and again as the first item on page 2. When implementing pagination, skip the first result on subsequent pages to avoid processing the same transaction twice.
4
Repeat until the last page
Continue extracting the cursor from the last transaction and fetching the next page. When the response returns fewer transactions than the limit, all results have been retrieved.
Full pagination script
Copy
Ask AI
const address = "EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2";async function main() { let allTransactions = []; let lt = undefined; let hash = undefined; let page = 0; while (true) { page++; const params = new URLSearchParams({ address, limit: "5" }); if (lt && hash) { params.set("lt", lt); params.set("hash", hash); } const res = await fetch( `https://toncenter.com/api/v2/getTransactions?${params}` ); const { result } = await res.json(); console.log( lt ? `\n--- Page ${page} (cursor: lt=${lt}) ---` : `\n--- Page ${page} (no cursor) ---` ); for (let i = 0; i < result.length; i++) { const tx = result[i]; if (i === 0 && lt && hash) { console.log( ` [skipped] lt: ${tx.transaction_id.lt} hash: ${tx.transaction_id.hash} (duplicate)` ); } else { console.log( ` lt: ${tx.transaction_id.lt} hash: ${tx.transaction_id.hash}` ); } } if (lt && hash) { result.shift(); } allTransactions.push(...result); if (result.length < 5) break; const last = result[result.length - 1]; lt = last.transaction_id.lt; hash = last.transaction_id.hash; } console.log(`\nTotal unique transactions: ${allTransactions.length}`);}main();
Returns a list of short transaction identifiers for all transactions in a given block.Pagination uses after_lt and after_hash as a cursor pair. Both must be provided together. The response includes an incomplete field that indicates whether more transactions remain in the block.
The incomplete field is now false, meaning all transactions in this block have been retrieved. Total: 3 + 1 = 4 transactions.
Exclusive cursorThe cursor for getBlockTransactions is exclusive. The transaction passed as after_lt/after_hash is not included in the next response. No deduplication is needed.
Full pagination script
Copy
Ask AI
async function main() { const workchain = -1; const shard = "-9223372036854775808"; const seqno = 57442406; console.log(`Block: workchain=${workchain} shard=${shard} seqno=${seqno}\n`); let allTransactions = []; let afterLt = undefined; let afterHash = undefined; let page = 0; while (true) { page++; const params = new URLSearchParams({ workchain: String(workchain), shard: shard, seqno: String(seqno), count: "3", }); if (afterLt && afterHash) { params.set("after_lt", afterLt); params.set("after_hash", afterHash); } const res = await fetch( `https://toncenter.com/api/v2/getBlockTransactions?${params}` ); const { result } = await res.json(); const txs = result.transactions || []; console.log( afterLt ? `--- Page ${page} (cursor: after_lt=${afterLt}) ---` : `--- Page ${page} (no cursor) ---` ); for (const tx of txs) { console.log( ` account: ${tx.account} lt: ${tx.lt} hash: ${tx.hash}` ); } allTransactions.push(...txs); if (!result.incomplete) break; const last = txs[txs.length - 1]; afterLt = last.lt; afterHash = last.hash; } console.log(`\nTotal transactions in block: ${allTransactions.length}`);}main();
Returns full transaction details for all transactions in a given block. Pagination works the same way as getBlockTransactions, using after_lt and after_hash as cursors with the incomplete field as the end of results signal. The only difference is that this endpoint returns complete transaction objects instead of short identifiers.
The incomplete field is false. All transactions in this block have been retrieved.
Exclusive cursorThe cursor for getBlockTransactionsExt is exclusive. The transaction passed as after_lt/after_hash is not included in the next response. No deduplication is needed.
Full pagination script
Copy
Ask AI
async function main() { const workchain = -1; const shard = "-9223372036854775808"; const seqno = 57442406; console.log(`Block: workchain=${workchain} shard=${shard} seqno=${seqno}\n`); let allTransactions = []; let afterLt = undefined; let afterHash = undefined; let page = 0; while (true) { page++; const params = new URLSearchParams({ workchain: String(workchain), shard: shard, seqno: String(seqno), count: "3", }); if (afterLt && afterHash) { params.set("after_lt", afterLt); params.set("after_hash", afterHash); } const res = await fetch( `https://toncenter.com/api/v2/getBlockTransactionsExt?${params}` ); const { result } = await res.json(); const txs = result.transactions || []; console.log( afterLt ? `--- Page ${page} (cursor: after_lt=${afterLt}) ---` : `--- Page ${page} (no cursor) ---` ); for (const tx of txs) { console.log( ` account: ${tx.address.account_address} lt: ${tx.transaction_id.lt} hash: ${tx.transaction_id.hash} fee: ${tx.fee}` ); } allTransactions.push(...txs); if (!result.incomplete) break; const last = txs[txs.length - 1]; afterLt = last.transaction_id.lt; afterHash = last.transaction_id.hash; } console.log(`\nTotal transactions in block: ${allTransactions.length}`);}main();
