> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ton.org/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.ton.org/feedback
```json
{
"path": "/ecosystem/api/toncenter/v2/transactions/get-block-transactions",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Get block transactions
> Returns a summary of transactions in a specific block. Each item contains the account address and transaction ID, but not full transaction details. Use `count` to limit results and `after_lt`/`after_hash` for pagination. Call getTransactions with each transaction ID to get full details.
## OpenAPI
````yaml get /api/v2/getBlockTransactions
openapi: 3.1.1
info:
title: TON HTTP API C++
description: >
This API enables HTTP access to TON blockchain - getting accounts and
wallets information, looking up blocks and transactions, sending messages to
the blockchain, calling get methods of smart contracts, and more.
In addition to REST API, all methods are available through a JSON-RPC
endpoint with `method` equal to method name and `params` passed as a
dictionary.
The response contains a JSON object, which always has a boolean field `ok`
and either `error` or `result`. If `ok` equals true, the request was
successful and the result of the query can be found in the `result` field.
In case of an unsuccessful request, `ok` equals false and the error is
explained in the `error`.
API Key should be sent either as `api_key` query parameter or `X-API-Key`
header
version: 2.1.1
servers:
- url: https://toncenter.com
description: TON Mainnet
- url: https://testnet.toncenter.com
description: TON Testnet
security: []
tags:
- name: Accounts
description: Information about accounts
- name: Transactions
description: Fetching and locating transactions
- name: Blocks
description: Information about blocks
- name: Run method
description: Run get-method of smart contracts
- name: Send
description: Send data to blockchain
- name: Utils
description: Some useful methods
- name: Configuration
description: Information about blockchain config
- name: RPC
description: JSON-RPC and POST endpoints
paths:
/api/v2/getBlockTransactions:
get:
tags:
- Transactions
summary: Get block transactions
description: >-
Returns a summary of transactions in a specific block. Each item
contains the account address and transaction ID, but not full
transaction details. Use `count` to limit results and
`after_lt`/`after_hash` for pagination. Call getTransactions with each
transaction ID to get full details.
operationId: getBlockTransactions_get
parameters:
- $ref: '#/components/parameters/workchain'
- $ref: '#/components/parameters/shard'
- $ref: '#/components/parameters/seqno'
- $ref: '#/components/parameters/rootHashOptional'
- $ref: '#/components/parameters/fileHashOptional'
- $ref: '#/components/parameters/afterLtOptional'
- $ref: '#/components/parameters/afterAccountHashOptional'
- $ref: '#/components/parameters/countOptional'
responses:
'200':
description: >-
Returns short transaction identifiers (account, lt, hash) for
transactions in the specified block.
content:
application/json:
schema:
$ref: '#/components/schemas/BlockTransactionsResponse'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'422':
$ref: '#/components/responses/422_block_tx'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
security:
- APIKeyHeader: []
- APIKeyQuery: []
components:
parameters:
workchain:
name: workchain
in: query
description: >-
The workchain to query. Use `-1` for masterchain (validators, system
contracts, config) or `0` for basechain (regular accounts and
contracts). Most user transactions happen on workchain `0`.
required: true
schema:
type: integer
format: int32
shard:
name: shard
in: query
description: >-
The shard identifier. Masterchain always uses `-9223372036854775808`.
For basechain, shards split and merge dynamically. Use the `shards`
endpoint to discover current shard configuration.
required: true
schema:
type: string
x-usrv-cpp-type: std::int64_t
seqno:
name: seqno
in: query
description: >-
Masterchain block sequence number (block height). Used to query state at
a specific point in time. If omitted, returns the current state.
required: true
schema:
type: integer
format: int32
rootHashOptional:
name: root_hash
in: query
description: >-
The block's root hash for verification. Together with `file_hash`, this
uniquely and cryptographically identifies a block. Only needed when
proof of block identity is required.
required: false
schema:
type: string
x-usrv-cpp-type: '#/components/schemas/TonHash'
fileHashOptional:
name: file_hash
in: query
description: >-
The block's file hash for verification. Together with `root_hash`, this
provides cryptographic proof of block identity. Only needed for
trustless verification.
required: false
schema:
type: string
x-usrv-cpp-type: '#/components/schemas/TonHash'
afterLtOptional:
name: after_lt
in: query
description: >-
Pagination cursor. Pass the `lt` value from the last item in the
previous response to get the next page. Transactions and messages are
ordered by logical time.
required: false
schema:
type: string
x-usrv-cpp-format: std::int64_t
afterAccountHashOptional:
name: after_hash
in: query
description: >-
Secondary pagination cursor for block transactions. When multiple
accounts have transactions at the same `lt`, use this to continue from a
specific account.
required: false
schema:
type: string
x-usrv-cpp-type: '#/components/schemas/TonAddrWithoutWorkchain'
countOptional:
name: count
in: query
description: >-
Maximum number of items to return. The default is 40. Use smaller values
for faster responses or larger values to reduce the number of API calls.
required: false
schema:
type: integer
format: int64
default: 40
minimum: 1
maximum: 10000
schemas:
BlockTransactionsResponse:
type: object
additionalProperties: false
required:
- ok
- result
properties:
ok:
type: boolean
default: true
description: >-
Returns `true` if the request succeeded; otherwise `false`. See the
`error` field for details.
result:
$ref: '#/components/schemas/BlockTransactions'
description: Response data. Present only when `ok` is `true`.
'@extra':
type: string
description: >-
Optional request ID that can be passed in the request and received
back in the response. Useful for matching async responses.
BlockTransactions:
type: object
additionalProperties: false
description: >-
List of short transaction identifiers found in a specific block, with a
flag indicating whether more transactions are available for pagination.
properties:
'@type':
type: string
enum:
- blocks.transactions
default: blocks.transactions
description: >-
TonLib type identifier for block transaction listings. Refer to the
[TonLib type reference](/ecosystem/api/toncenter/v2-tonlib-types)
for a full list.
id:
$ref: '#/components/schemas/TonBlockIdExt'
description: Full block identifier for the queried block.
req_count:
type: integer
description: >-
The maximum number of transactions requested, as specified by the
`count` request parameter. If `incomplete` is `true`, more
transactions exist beyond this limit.
incomplete:
type: boolean
description: >-
Returns `true` if there are more transactions in this block;
otherwise `false`. Use the last transaction as cursor for
pagination.
transactions:
type: array
description: >-
Array of compact transaction references. Each entry contains the
account address (string), logical time (string), and transaction
hash (base64 or hex).
items:
$ref: '#/components/schemas/ShortTxId'
required:
- '@type'
- id
- req_count
- incomplete
- transactions
TonBlockIdExt:
type: object
additionalProperties: false
properties:
'@type':
type: string
enum:
- ton.blockIdExt
default: ton.blockIdExt
description: >-
TonLib type identifier for full block identifiers. Refer to the
[TonLib type reference](/ecosystem/api/toncenter/v2-tonlib-types)
for a full list.
workchain:
type: integer
description: 'Workchain ID: `-1` for masterchain, `0` for basechain.'
shard:
type: string
x-usrv-cpp-type: std::int64_t
description: >-
Shard identifier as a signed 64-bit integer string. Masterchain uses
`-9223372036854775808`.
seqno:
type: integer
description: >-
Block sequence number within its workchain and shard. For the
masterchain (workchain `-1`), this equals the global block height.
For basechain shards (workchain `0`), this is the sequence number
local to that specific shard, not a global height.
root_hash:
$ref: '#/components/schemas/TonHash'
description: Merkle root hash of the block state tree.
file_hash:
$ref: '#/components/schemas/TonHash'
description: >-
Hash of the serialized block file. Together with `root_hash`,
uniquely identifies a block.
required:
- '@type'
- workchain
- shard
- seqno
- root_hash
- file_hash
description: >-
A complete block identifier with cryptographic hashes. Contains
`workchain`, `shard`, `seqno` (position) plus `root_hash` and
`file_hash` (verification).
ShortTxId:
type: object
additionalProperties: false
description: >-
Compact transaction reference containing the account address, logical
time, and hash. Used in block transaction listings for efficient
enumeration.
properties:
'@type':
type: string
enum:
- blocks.shortTxId
default: blocks.shortTxId
description: >-
TonLib type identifier for compact transaction references. Refer to
the [TonLib type
reference](/ecosystem/api/toncenter/v2-tonlib-types) for a full
list.
mode:
type: integer
description: Bitmask indicating which optional fields are present.
account:
$ref: '#/components/schemas/TonAddr'
description: Account address that executed this transaction.
lt:
type: string
description: >-
Logical time of this transaction. A globally unique counter that
orders all events on the blockchain.
x-usrv-cpp-type: std::int64_t
hash:
$ref: '#/components/schemas/TonHash'
description: SHA-256 hash of this transaction, encoded in base64.
required:
- '@type'
- mode
- account
- lt
- hash
TonHash:
type: string
x-usrv-cpp-type: ton_http::types::ton_hash
description: >-
A 256-bit hash value. Accepts either hex format (64 characters) or
base64 format (44 characters). Used for block hashes, transaction
hashes, and cryptographic proofs.
TonAddr:
type: string
x-usrv-cpp-type: ton_http::types::ton_addr
description: >-
Account address in [raw](/foundations/addresses/formats#raw-format)
format (e.g., `0:ca6e321c...`) or
[user-friendly](/foundations/addresses/formats#user-friendly-format)
format (e.g., `EQDKbjIcfM...`). All formats are automatically detected.
responses:
'401':
description: API key does not exist. Check for typos or generate a new key.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- ok
- code
- error
properties:
ok:
type: boolean
const: false
description: Always `false` for error responses.
code:
type: integer
const: 401
description: HTTP status code `401`.
error:
type: string
enum:
- API key does not exist
'@extra':
type: string
description: Extra data passed through from the request.
example:
ok: false
code: 401
error: API key does not exist
'403':
description: >-
API key is not allowed for this network (e.g. testnet key used on
mainnet).
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- ok
- code
- error
properties:
ok:
type: boolean
const: false
description: Always `false` for error responses.
code:
type: integer
const: 403
description: HTTP status code `403`.
error:
type: string
enum:
- Network not allowed
'@extra':
type: string
description: Extra data passed through from the request.
example:
ok: false
code: 403
error: Network not allowed
'429':
description: >-
Rate limit exceeded. Back off and retry, or use an API key for higher
limits.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- ok
- code
- error
properties:
ok:
type: boolean
const: false
description: Always `false` for error responses.
code:
type: integer
const: 429
description: HTTP status code `429`.
error:
type: string
enum:
- Ratelimit exceeded
'@extra':
type: string
description: Extra data passed through from the request.
example:
ok: false
code: 429
error: Ratelimit exceeded
'504':
description: Timeout waiting for liteserver response.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- ok
- code
- error
properties:
ok:
type: boolean
const: false
description: Always `false` for error responses.
code:
type: integer
const: 504
description: HTTP status code `504`.
error:
type: string
enum:
- LITE_SERVER_NETWORK timeout
'@extra':
type: string
description: Extra data passed through from the request.
example:
ok: false
code: 504
error: LITE_SERVER_NETWORK timeout
422_block_tx:
description: Invalid block transactions parameters.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- ok
- code
- error
properties:
ok:
type: boolean
const: false
description: Always `false` for error responses.
code:
type: integer
const: 422
description: HTTP status code `422`.
error:
type: string
enum:
- failed to parse workchain
- failed to parse shard
- failed to parse seqno
- after_lt and after_hash should be used together
- after_lt should be non-negative
- count should be positive
- count should be less or equal 10000
'@extra':
type: string
description: Extra data passed through from the request.
example:
ok: false
code: 422
error: failed to parse workchain
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: X-API-Key
description: >-
API key header of the form `X-API-Key: `, where `` is the
API key. Requests without a key are limited to 1 RPS. Refer to the
[authentication guide](/ecosystem/api/toncenter/v2-authentication) for
details.
APIKeyQuery:
type: apiKey
in: query
name: api_key
description: >-
API key query parameter of the form `?api_key=`, where ``
is the API key. Equivalent to the header method. Refer to the
[authentication guide](/ecosystem/api/toncenter/v2-authentication) for
details.
````