diff --git a/ecosystem/api/toncenter/v3.yaml b/ecosystem/api/toncenter/v3.yaml index f3a719430..2a13a0f02 100644 --- a/ecosystem/api/toncenter/v3.yaml +++ b/ecosystem/api/toncenter/v3.yaml @@ -2,19 +2,21 @@ openapi: 3.0.0 info: title: TON Index (Go) description: TON Index collects data from a full node to PostgreSQL database and provides convenient API to an indexed blockchain. - version: 1.2.4-rc + version: '1.2.4-rc' contact: {} servers: -- url: https://toncenter.com -- url: https://testnet.toncenter.com +- url: 'https://toncenter.com' +- url: 'https://testnet.toncenter.com' paths: /api/v3/accountStates: get: security: [] - description: Query account states + description: 'Returns the current on-chain state for one or more accounts. Includes balance, contract code and data + hashes, account status, and last transaction reference. Use `include_boc` to control whether full code and data BOCs + are returned.' tags: - Accounts - summary: Get Account States + summary: Get account states operationId: api_v3_get_account_states parameters: - name: address @@ -34,29 +36,29 @@ paths: default: true responses: '200': - description: OK + description: Current state for each requested account. content: application/json: schema: $ref: '#/components/schemas/AccountStatesResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' /api/v3/actions: get: security: [] - description: Get actions by specified filter. + description: 'Returns parsed high-level actions (transfers, swaps, burns, etc.) derived from on-chain traces. Filter + by account, transaction hash, message hash, trace ID, or action type. Actions provide a human-readable interpretation + of raw transactions.' tags: - Actions and traces - summary: Get Actions + summary: Get actions operationId: api_v3_get_actions parameters: - name: account in: query - description: List of account addresses to get actions. Can be sent in hex, base64 or base64url form. + description: 'List of account addresses to get actions. Can be sent in hex, base64 or base64url form.' schema: type: string - name: tx_hash @@ -99,28 +101,28 @@ paths: format: int32 - name: start_utime in: query - description: Query actions for traces with `trace_end_utime >= start_utime`. + description: 'Query actions for traces with `trace_end_utime >= start_utime`.' schema: type: integer format: int32 minimum: 0 - name: end_utime in: query - description: Query actions for traces with `trace_end_utime <= end_utime`. + description: 'Query actions for traces with `trace_end_utime <= end_utime`.' schema: type: integer format: int32 minimum: 0 - name: start_lt in: query - description: Query actions for traces with `trace_end_lt >= start_lt`. + description: 'Query actions for traces with `trace_end_lt >= start_lt`.' schema: type: integer format: int64 minimum: 0 - name: end_lt in: query - description: Query actions for traces with `trace_end_lt <= end_lt`. + description: 'Query actions for traces with `trace_end_lt <= end_lt`.' schema: type: integer format: int64 @@ -203,13 +205,13 @@ paths: default: false - name: include_transactions in: query - description: Include `transactions_full` array with detailed transaction data for each action in response. + description: 'Include `transactions_full` array with detailed transaction data for each action in response.' schema: type: boolean default: false - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -218,7 +220,7 @@ paths: maximum: 1000 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -235,24 +237,19 @@ paths: - desc responses: '200': - description: OK + description: Matching actions with optional address book and metadata. content: application/json: schema: $ref: '#/components/schemas/ActionsResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' /api/v3/addressBook: get: security: [] - description: Query address book + description: 'Returns the address book entries for a list of addresses. Each entry includes the user-friendly address + form, detected interfaces, and associated DNS domain (if any).' tags: - Accounts - summary: Address Book + summary: Get address book operationId: api_v3_get_address_book parameters: - name: address @@ -266,24 +263,22 @@ paths: type: string responses: '200': - description: OK + description: Address book entries keyed by raw address. content: application/json: schema: $ref: '#/components/schemas/AddressBook' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '422': + $ref: '#/components/responses/422' /api/v3/addressInformation: get: security: [] - description: Get smart contract information. + description: 'Returns the current state of an account on the TON blockchain. Includes balance (in nanotons), smart contract + code and data (as BOC-encoded strings), account status, and a reference to the last transaction. Compatible with the + v2 API response format.' tags: - Api/v2 - summary: Get Address Information + summary: Get address information operationId: api_v3_get_v2_addressInformation parameters: - name: address @@ -300,24 +295,23 @@ paths: default: true responses: '200': - description: OK + description: 'Current account state in v2-compatible format.' content: application/json: schema: $ref: '#/components/schemas/V2AddressInformation' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' /api/v3/adjacentTransactions: get: security: [] - description: Get parent and/or children for specified transaction. + description: 'Returns the parent and/or child transactions for a given transaction. Use `direction` to filter by inbound + or outbound messages. Useful for tracing the execution flow of a multi-hop message chain.' tags: - Blockchain Data - summary: Get Adjacent Transactions + summary: Get adjacent transactions operationId: api_v3_get_adjacent_transactions parameters: - name: hash @@ -335,21 +329,17 @@ paths: - out responses: '200': - description: OK + description: Parent and/or child transactions for the specified transaction. content: application/json: schema: $ref: '#/components/schemas/TransactionsResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' /api/v3/blocks: get: security: [] - description: Returns blocks by specified filters. + description: 'Returns blocks matching the specified filters. Query by workchain, shard, sequence number, root hash, + file hash, or time range. Each block includes metadata such as transaction count, validator info, and references to + previous blocks.' tags: - Blockchain Data summary: Get blocks @@ -368,7 +358,7 @@ paths: type: string - name: seqno in: query - description: Block block seqno. Must be sent with *workchain* and *shard*. + description: 'Block block seqno. Must be sent with *workchain* and *shard*.' schema: type: integer format: int32 @@ -390,35 +380,35 @@ paths: format: int32 - name: start_utime in: query - description: Query blocks with generation UTC timestamp **after** given timestamp. + description: 'Query blocks with generation UTC timestamp **after** given timestamp.' schema: type: integer format: int32 minimum: 0 - name: end_utime in: query - description: Query blocks with generation UTC timestamp **before** given timestamp. + description: 'Query blocks with generation UTC timestamp **before** given timestamp.' schema: type: integer format: int32 minimum: 0 - name: start_lt in: query - description: Query blocks with `lt >= start_lt`. + description: 'Query blocks with `lt >= start_lt`.' schema: type: integer format: int64 minimum: 0 - name: end_lt in: query - description: Query blocks with `lt <= end_lt`. + description: 'Query blocks with `lt <= end_lt`.' schema: type: integer format: int64 minimum: 0 - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -427,7 +417,7 @@ paths: maximum: 1000 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -444,25 +434,19 @@ paths: - desc responses: '200': - description: OK + description: Matching blocks with full metadata. content: application/json: schema: $ref: '#/components/schemas/BlocksResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' /api/v3/decode: get: security: [] - description: Decode opcodes and message bodies. Opcodes can be in hex (with or without 0x prefix) or decimal format. - Bodies should be in base64 or hex format. + description: 'Decodes opcodes and message bodies into human-readable form. Opcodes can be in hex (with or without `0x` + prefix) or decimal format. Bodies should be in base64 or hex format. Maximum 1000 items per list.' tags: - Utils - summary: Decode Opcodes and Bodies + summary: Decode opcodes and bodies operationId: api_v3_get_decode parameters: - name: opcodes @@ -483,24 +467,23 @@ paths: type: string responses: '200': - description: OK + description: Decoded opcodes and message bodies. content: application/json: schema: $ref: '#/components/schemas/DecodeResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '422': + $ref: '#/components/responses/422' + '500': + $ref: '#/components/responses/500' post: security: [] - description: Decode opcodes and message bodies. Opcodes can be in hex (with or without 0x prefix) or decimal format. - Bodies should be in base64 or hex format. Use POST method for long parameters that may be truncated in GET requests. + description: 'Decodes opcodes and message bodies into human-readable form. Opcodes can be in hex (with or without `0x` + prefix) or decimal format. Bodies should be in base64 or hex format. Maximum 1000 items per list. Use POST for long + parameter lists that may be truncated in GET requests.' tags: - Utils - summary: Decode Opcodes and Bodies + summary: Decode opcodes and bodies operationId: api_v3_post_decode requestBody: required: true @@ -510,24 +493,23 @@ paths: $ref: '#/components/schemas/DecodeRequest' responses: '200': - description: OK + description: Decoded opcodes and message bodies. content: application/json: schema: $ref: '#/components/schemas/DecodeResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '422': + $ref: '#/components/responses/422' + '500': + $ref: '#/components/responses/500' /api/v3/dns/records: get: security: [] - description: Query DNS records by specified filters. Currently .ton and .t.me DNS are supported. + description: 'Returns DNS records matching the specified filters. Currently supports `.ton` and `.t.me` domains. Query + by wallet address (returns records pointing to that wallet) or by exact domain name. Provide one filter, not both.' tags: - Dns - summary: Get DNS Records + summary: Get DNS records operationId: api_v3_get_dns_records parameters: - name: wallet @@ -542,7 +524,7 @@ paths: type: string - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -551,7 +533,7 @@ paths: maximum: 1000 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -559,25 +541,22 @@ paths: minimum: 0 responses: '200': - description: OK + description: Matching DNS records with address book. content: application/json: schema: $ref: '#/components/schemas/DNSRecordsResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '422': + $ref: '#/components/responses/422' /api/v3/estimateFee: post: security: [] - description: Estimate fees required for query processing. Fields body, init-code and init-data accepted in serialized - format (b64-encoded). + description: 'Estimates the fees required to process a transaction. Accepts a target address and serialized message + body, init-code, and init-data (all base64-encoded). Returns a breakdown of source and destination fees including + storage, gas, and forwarding costs.' tags: - Api/v2 - summary: Estimate Fee + summary: Estimate fee operationId: api_v3_post_v2_estimate_fee requestBody: required: true @@ -587,24 +566,19 @@ paths: $ref: '#/components/schemas/V2EstimateFeeRequest' responses: '200': - description: OK + description: Estimated fee breakdown for source and destination accounts. content: application/json: schema: $ref: '#/components/schemas/V2EstimateFeeResult' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' /api/v3/jetton/burns: get: security: [] - description: Get Jetton burns by specified filters + description: 'Returns Jetton burn events matching the specified filters. Filter by owner address, Jetton wallet address, + Jetton master address, or time range. Each burn includes the amount, query ID, and transaction reference.' tags: - Jettons - summary: Get Jetton Burns + summary: Get Jetton burns operationId: api_v3_get_jetton_burns parameters: - name: address @@ -630,35 +604,35 @@ paths: type: string - name: start_utime in: query - description: Query transactions with generation UTC timestamp **after** given timestamp. + description: 'Query transactions with generation UTC timestamp **after** given timestamp.' schema: type: integer format: int32 minimum: 0 - name: end_utime in: query - description: Query transactions with generation UTC timestamp **before** given timestamp. + description: 'Query transactions with generation UTC timestamp **before** given timestamp.' schema: type: integer format: int32 minimum: 0 - name: start_lt in: query - description: Query transactions with `lt >= start_lt`. + description: 'Query transactions with `lt >= start_lt`.' schema: type: integer format: int64 minimum: 0 - name: end_lt in: query - description: Query transactions with `lt <= end_lt`. + description: 'Query transactions with `lt <= end_lt`.' schema: type: integer format: int64 minimum: 0 - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -667,7 +641,7 @@ paths: maximum: 1000 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -684,24 +658,19 @@ paths: - desc responses: '200': - description: OK + description: Matching Jetton burn events with address book and metadata. content: application/json: schema: $ref: '#/components/schemas/JettonBurnsResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' /api/v3/jetton/masters: get: security: [] - description: Get Jetton masters by specified filters + description: 'Returns Jetton master contracts matching the specified filters. Filter by master address or admin address. + Each result includes total supply, mintability status, content metadata, and wallet code hash.' tags: - Jettons - summary: Get Jetton Masters + summary: Get Jetton masters operationId: api_v3_get_jetton_masters parameters: - name: address @@ -722,7 +691,7 @@ paths: type: string - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -731,7 +700,7 @@ paths: maximum: 1000 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -739,24 +708,20 @@ paths: minimum: 0 responses: '200': - description: OK + description: Matching Jetton master contracts with address book and metadata. content: application/json: schema: $ref: '#/components/schemas/JettonMastersResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' /api/v3/jetton/transfers: get: security: [] - description: Get Jetton transfers by specified filters + description: 'Returns Jetton transfer events matching the specified filters. Filter by owner address, Jetton wallet, + Jetton master, direction, or time range. Each transfer includes source, destination, amount, and optional forward/custom + payloads.' tags: - Jettons - summary: Get Jetton Transfers + summary: Get Jetton transfers operationId: api_v3_get_jetton_transfers parameters: - name: owner_address @@ -782,7 +747,7 @@ paths: type: string - name: direction in: query - description: Direction of transfer. *Note:* applied only with owner_address. + description: 'Direction of transfer. *Note:* applied only with owner_address.' schema: type: string enum: @@ -790,35 +755,35 @@ paths: - out - name: start_utime in: query - description: Query transactions with generation UTC timestamp **after** given timestamp. + description: 'Query transactions with generation UTC timestamp **after** given timestamp.' schema: type: integer format: int32 minimum: 0 - name: end_utime in: query - description: Query transactions with generation UTC timestamp **before** given timestamp. + description: 'Query transactions with generation UTC timestamp **before** given timestamp.' schema: type: integer format: int32 minimum: 0 - name: start_lt in: query - description: Query transactions with `lt >= start_lt`. + description: 'Query transactions with `lt >= start_lt`.' schema: type: integer format: int64 minimum: 0 - name: end_lt in: query - description: Query transactions with `lt <= end_lt`. + description: 'Query transactions with `lt <= end_lt`.' schema: type: integer format: int64 minimum: 0 - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -827,7 +792,7 @@ paths: maximum: 1000 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -844,24 +809,20 @@ paths: - desc responses: '200': - description: OK + description: Matching Jetton transfer events with address book and metadata. content: application/json: schema: $ref: '#/components/schemas/JettonTransfersResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' /api/v3/jetton/wallets: get: security: [] - description: Get Jetton wallets by specified filters + description: 'Returns Jetton wallet contracts matching the specified filters. Filter by wallet address, owner address, + or Jetton master address. Each result includes balance, owner, and associated Jetton master. Use `exclude_zero_balance` + to skip empty wallets.' tags: - Jettons - summary: Get Jetton Wallets + summary: Get Jetton wallets operationId: api_v3_get_jetton_wallets parameters: - name: address @@ -895,7 +856,7 @@ paths: type: boolean - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -904,7 +865,7 @@ paths: maximum: 1000 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -912,8 +873,8 @@ paths: minimum: 0 - name: sort in: query - description: Sort jetton wallets by balance. **Warning:** results may be inconsistent during the read with limit and - offset. + description: 'Sort jetton wallets by balance. **Warning:** results may be inconsistent during the read with limit + and offset.' schema: type: string enum: @@ -921,21 +882,18 @@ paths: - desc responses: '200': - description: OK + description: Matching Jetton wallet contracts with address book and metadata. content: application/json: schema: $ref: '#/components/schemas/JettonWalletsResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '422': + $ref: '#/components/responses/422' /api/v3/masterchainBlockShardState: get: security: [] - description: Get masterchain block shard state. Same as /api/v2/shards. + description: 'Returns the shard state at a given masterchain block sequence number. Equivalent to the v2 `/shards` endpoint. + Use this to discover which shard blocks were committed in a specific masterchain block.' tags: - Blockchain Data summary: Get masterchain block shard state @@ -950,24 +908,21 @@ paths: format: int32 responses: '200': - description: OK + description: Shard configuration at the specified masterchain block. content: application/json: schema: $ref: '#/components/schemas/TransactionsResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '404': + $ref: '#/components/responses/404' /api/v3/masterchainBlockShards: get: security: [] - description: Returns all worchain blocks, that appeared after previous masterchain block. + description: Returns all workchain blocks that appeared after the previous masterchain block for a given sequence number. + Useful for iterating through all shard blocks between masterchain blocks. tags: - Blockchain Data - summary: Get masterchain block shard state + summary: Get masterchain block shards operationId: api_v3_get_masterchainBlockShards parameters: - name: seqno @@ -979,7 +934,7 @@ paths: format: int32 - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -988,7 +943,7 @@ paths: maximum: 1000 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -996,45 +951,37 @@ paths: minimum: 0 responses: '200': - description: OK + description: Workchain blocks associated with the specified masterchain block. content: application/json: schema: $ref: '#/components/schemas/TransactionsResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '404': + $ref: '#/components/responses/404' /api/v3/masterchainInfo: get: security: [] - description: Get first and last indexed block + description: Returns the first and last indexed masterchain blocks. Use this to determine the current indexing range + and check whether the indexer is up to date. tags: - Blockchain Data - summary: Get Masterchain Info + summary: Get masterchain info operationId: api_v3_get_masterchain_info responses: '200': - description: OK + description: First and last indexed masterchain blocks. content: application/json: schema: $ref: '#/components/schemas/MasterchainInfo' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' /api/v3/message: post: security: [] - description: Send an external message to the TON network. + description: 'Sends a serialized external message (BOC) to the TON network for processing. The message must be a valid + base64-encoded bag-of-cells. Returns the message hash on success.' tags: - Api/v2 - summary: Send Message + summary: Send message operationId: api_v3_post_v2_message requestBody: required: true @@ -1044,21 +991,19 @@ paths: $ref: '#/components/schemas/V2SendMessageRequest' responses: '200': - description: OK + description: Message hash of the submitted external message. content: application/json: schema: $ref: '#/components/schemas/V2SendMessageResult' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '401': + $ref: '#/components/responses/401' /api/v3/messages: get: security: [] - description: Get messages by specified filters. + description: 'Returns messages matching the specified filters. Filter by message hash, body hash, source/destination + address, opcode, or time range. Use `source=null` to find external inbound messages or `destination=null` for log + messages.' tags: - Blockchain Data summary: Get messages @@ -1066,7 +1011,7 @@ paths: parameters: - name: msg_hash in: query - description: Message hash. Acceptable in hex, base64 and base64url forms. + description: 'Message hash. Acceptable in hex, base64 and base64url forms.' explode: true schema: type: array @@ -1079,45 +1024,45 @@ paths: type: string - name: source in: query - description: The source account address. Can be sent in hex, base64 or base64url form. Use value `null` to get external - messages. + description: 'The source account address. Can be sent in hex, base64 or base64url form. Use value `null` to get external + messages.' schema: type: string - name: destination in: query - description: The destination account address. Can be sent in hex, base64 or base64url form. Use value `null` to get - log messages. + description: 'The destination account address. Can be sent in hex, base64 or base64url form. Use value `null` to get + log messages.' schema: type: string - name: opcode in: query - description: Opcode of message in hex or signed 32-bit decimal form. + description: 'Opcode of message in hex or signed 32-bit decimal form.' schema: type: string - name: start_utime in: query - description: Query messages with `created_at >= start_utime`. + description: 'Query messages with `created_at >= start_utime`.' schema: type: integer format: int32 minimum: 0 - name: end_utime in: query - description: Query messages with `created_at >= start_utime`. + description: 'Query messages with `created_at >= start_utime`.' schema: type: integer format: int32 minimum: 0 - name: start_lt in: query - description: Query messages with `created_lt >= start_lt`. + description: 'Query messages with `created_lt >= start_lt`.' schema: type: integer format: int64 minimum: 0 - name: end_lt in: query - description: Query messages with `created_lt <= end_lt`. + description: 'Query messages with `created_lt <= end_lt`.' schema: type: integer format: int64 @@ -1142,7 +1087,7 @@ paths: type: boolean - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -1151,7 +1096,7 @@ paths: maximum: 1000 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -1159,7 +1104,7 @@ paths: minimum: 0 - name: sort in: query - description: Sort transactions by lt. If set to `desc`, you better set `start_lt = 1` to get latest messages. + description: 'Sort transactions by lt. If set to `desc`, you better set `start_lt = 1` to get latest messages.' schema: type: string default: desc @@ -1168,24 +1113,19 @@ paths: - desc responses: '200': - description: OK + description: Matching messages with address book and metadata. content: application/json: schema: $ref: '#/components/schemas/MessagesResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' /api/v3/metadata: get: security: [] - description: Query address metadata + description: 'Returns metadata for a list of addresses. Metadata includes indexing status and token information (name, + symbol, image, type) for known Jetton and NFT contracts.' tags: - Accounts - summary: Metadata + summary: Get metadata operationId: api_v3_get_metadata parameters: - name: address @@ -1199,24 +1139,22 @@ paths: type: string responses: '200': - description: OK + description: Address metadata keyed by raw address. content: application/json: schema: $ref: '#/components/schemas/Metadata' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '422': + $ref: '#/components/responses/422' /api/v3/multisig/orders: get: security: [] - description: Get multisig orders by specified filters + description: 'Returns multisig orders matching the specified filters. Filter by order address or parent multisig address. + Each order includes approval status, expiration date, signers, and optionally parsed actions. At least one of `address` + or `multisig_address` is required.' tags: - Multisig - summary: Get Multisig Orders + summary: Get multisig orders operationId: api_v3_get_multisig_orders parameters: - name: address @@ -1243,7 +1181,7 @@ paths: default: false - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -1252,7 +1190,7 @@ paths: maximum: 1024 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -1269,24 +1207,22 @@ paths: - desc responses: '200': - description: OK + description: Matching multisig orders with address book. content: application/json: schema: $ref: '#/components/schemas/MultisigOrderResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '422': + $ref: '#/components/responses/422' /api/v3/multisig/wallets: get: security: [] - description: Get multisig contracts by specified filters with associated orders + description: 'Returns multisig wallet contracts matching the specified filters. Filter by multisig address or signer/proposer + wallet address. Each result includes signers, proposers, threshold, and optionally associated orders. At least one + of `address` or `wallet_address` is required.' tags: - Multisig - summary: Get Multisig Wallets + summary: Get multisig wallets operationId: api_v3_get_multisig_wallets parameters: - name: address @@ -1307,7 +1243,7 @@ paths: type: string - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -1316,7 +1252,7 @@ paths: maximum: 1024 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -1339,21 +1275,18 @@ paths: default: true responses: '200': - description: OK + description: Matching multisig contracts with address book. content: application/json: schema: $ref: '#/components/schemas/MultisigResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '422': + $ref: '#/components/responses/422' /api/v3/nft/collections: get: security: [] - description: Get NFT collections by specified filters + description: 'Returns NFT collection contracts matching the specified filters. Filter by collection address or owner + address. Each result includes collection content metadata, next item index, and owner.' tags: - NFTs summary: Get NFT collections @@ -1377,7 +1310,7 @@ paths: type: string - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -1386,7 +1319,7 @@ paths: maximum: 1000 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -1394,21 +1327,17 @@ paths: minimum: 0 responses: '200': - description: OK + description: Matching NFT collection contracts with address book and metadata. content: application/json: schema: $ref: '#/components/schemas/NFTCollectionsResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' /api/v3/nft/items: get: security: [] - description: Get NFT items by specified filters + description: 'Returns NFT items matching the specified filters. Filter by item address, owner address, collection address, + or item index. Use `include_on_sale` to include items listed on marketplaces. When querying multiple collections, + provide exactly one `owner_address`.' tags: - NFTs summary: Get NFT items @@ -1454,13 +1383,13 @@ paths: default: false - name: sort_by_last_transaction_lt in: query - description: Sort NFT items by last transaction lt descending. **Warning:** results may be inconsistent during pagination - with limit and offset. + description: 'Sort NFT items by last transaction lt descending. **Warning:** results may be inconsistent during pagination + with limit and offset.' schema: type: boolean - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -1469,7 +1398,7 @@ paths: maximum: 1000 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -1477,24 +1406,21 @@ paths: minimum: 0 responses: '200': - description: OK + description: Matching NFT items with address book and metadata. content: application/json: schema: $ref: '#/components/schemas/NFTItemsResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '422': + $ref: '#/components/responses/422' /api/v3/nft/transfers: get: security: [] - description: Get transfers of NFT items by specified filters + description: 'Returns NFT transfer events matching the specified filters. Filter by owner address, item address, collection + address, direction, or time range. Each transfer includes old and new owner, forward payload, and transaction reference.' tags: - NFTs - summary: Get NFT Transfers + summary: Get NFT transfers operationId: api_v3_get_nft_transfers parameters: - name: owner_address @@ -1528,35 +1454,35 @@ paths: - out - name: start_utime in: query - description: Query transactions with generation UTC timestamp **after** given timestamp. + description: 'Query transactions with generation UTC timestamp **after** given timestamp.' schema: type: integer format: int32 minimum: 0 - name: end_utime in: query - description: Query transactions with generation UTC timestamp **before** given timestamp. + description: 'Query transactions with generation UTC timestamp **before** given timestamp.' schema: type: integer format: int32 minimum: 0 - name: start_lt in: query - description: Query transactions with `lt >= start_lt`. + description: 'Query transactions with `lt >= start_lt`.' schema: type: integer format: int64 minimum: 0 - name: end_lt in: query - description: Query transactions with `lt <= end_lt`. + description: 'Query transactions with `lt <= end_lt`.' schema: type: integer format: int64 minimum: 0 - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -1565,7 +1491,7 @@ paths: maximum: 1000 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -1582,29 +1508,24 @@ paths: - desc responses: '200': - description: OK + description: Matching NFT transfer events with address book and metadata. content: application/json: schema: $ref: '#/components/schemas/NFTTransfersResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' /api/v3/pendingActions: get: security: [] - description: Get actions by specified filter. + description: 'Returns parsed actions for pending (not yet finalized) traces. Filter by account address or external message + hash. Useful for tracking transactions that have been submitted but not yet confirmed on-chain.' tags: - Actions and traces - summary: Get Pending Actions + summary: Get pending actions operationId: api_v3_get_pending_actions parameters: - name: account in: query - description: List of account addresses to get actions. Can be sent in hex, base64 or base64url form. + description: 'List of account addresses to get actions. Can be sent in hex, base64 or base64url form.' schema: type: string - name: ext_msg_hash @@ -1625,35 +1546,34 @@ paths: type: string - name: include_transactions in: query - description: Include `transactions_full` array with detailed transaction data for each action in response. + description: 'Include `transactions_full` array with detailed transaction data for each action in response.' schema: type: boolean default: false responses: '200': - description: OK + description: Pending actions for matching traces. content: application/json: schema: $ref: '#/components/schemas/ActionsResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '422': + $ref: '#/components/responses/422' + '500': + $ref: '#/components/responses/500' /api/v3/pendingTraces: get: security: [] - description: Get traces by specified filter. + description: Returns pending traces that have not yet been finalized. Filter by account address or external message + hash. A pending trace represents a message chain that is still being processed by the network. tags: - Actions and traces - summary: Get Pending Traces + summary: Get pending traces operationId: api_v3_get_pending_traces parameters: - name: account in: query - description: List of account addresses to get transactions. Can be sent in hex, base64 or base64url form. + description: 'List of account addresses to get transactions. Can be sent in hex, base64 or base64url form.' schema: type: string - name: ext_msg_hash @@ -1666,21 +1586,20 @@ paths: type: string responses: '200': - description: OK + description: Pending traces for matching filters. content: application/json: schema: $ref: '#/components/schemas/TracesResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '422': + $ref: '#/components/responses/422' + '500': + $ref: '#/components/responses/500' /api/v3/pendingTransactions: get: security: [] - description: Get pending transactions by specified filter. + description: Returns pending transactions that have not yet been finalized. Filter by account address or trace ID. Use + only one filter at a time. At least one account address is required unless filtering by trace ID. tags: - Blockchain Data summary: Get pending transactions @@ -1688,7 +1607,7 @@ paths: parameters: - name: account in: query - description: List of account addresses to get transactions. Can be sent in hex, base64 or base64url form. + description: 'List of account addresses to get transactions. Can be sent in hex, base64 or base64url form.' explode: true schema: type: array @@ -1704,41 +1623,23 @@ paths: type: string responses: '200': - description: OK + description: Pending transactions for matching filters. content: application/json: schema: $ref: '#/components/schemas/TransactionsResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '422': + $ref: '#/components/responses/422' + '500': + $ref: '#/components/responses/500' /api/v3/runGetMethod: post: security: [] - description: |- - Run get method of smart contract. Stack supports only `num`, `cell` and `slice` types: - ``` - [ - { - "type": "num", - "value": "0x12a" - }, - { - "type": "cell", - "value": "te6..." // base64 encoded boc with cell - }, - { - "type": "slice", - "value": "te6..." // base64 encoded boc with slice - } - ] - ``` + description: 'Executes a get method on a smart contract and returns the result stack. The stack supports `num`, `cell`, + and `slice` types. Cell and slice values must be base64-encoded BOCs. Both `address` and `method` are required.' tags: - Api/v2 - summary: Run Get-Method + summary: Run get method operationId: api_v3_post_v2_rungetmethod requestBody: required: true @@ -1748,29 +1649,26 @@ paths: $ref: '#/components/schemas/V2RunGetMethodRequest' responses: '200': - description: OK + description: Get method execution result with output stack. content: application/json: schema: $ref: '#/components/schemas/V2RunGetMethodRequest' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '401': + $ref: '#/components/responses/401' /api/v3/topAccountsByBalance: get: security: [] - description: Get list of accounts sorted descending by balance. + description: 'Returns accounts sorted by balance in descending order. Use `limit` and `offset` for pagination. Useful + for analytics and leaderboard views.' tags: - Stats - summary: Get Top Accounts By Balance + summary: Get top accounts by balance operationId: api_v3_get_top_accounts_by_balance parameters: - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -1779,7 +1677,7 @@ paths: maximum: 1000 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -1787,31 +1685,27 @@ paths: minimum: 0 responses: '200': - description: OK + description: Accounts sorted by balance descending. content: application/json: schema: type: array items: $ref: '#/components/schemas/AccountBalance' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' /api/v3/traces: get: security: [] - description: Get traces by specified filter. + description: 'Returns execution traces matching the specified filters. A trace represents the full message chain triggered + by an external message. Filter by account, trace ID, transaction hash, or message hash. Use only one primary filter + at a time. Optionally include parsed actions.' tags: - Actions and traces - summary: Get Traces + summary: Get traces operationId: api_v3_get_traces parameters: - name: account in: query - description: List of account addresses to get transactions. Can be sent in hex, base64 or base64url form. + description: 'List of account addresses to get transactions. Can be sent in hex, base64 or base64url form.' schema: type: string - name: trace_id @@ -1846,28 +1740,28 @@ paths: format: int32 - name: start_utime in: query - description: Query traces, which was finished **after** given timestamp. + description: 'Query traces, which was finished **after** given timestamp.' schema: type: integer format: int32 minimum: 0 - name: end_utime in: query - description: Query traces, which was finished **before** given timestamp. + description: 'Query traces, which was finished **before** given timestamp.' schema: type: integer format: int32 minimum: 0 - name: start_lt in: query - description: Query traces with `end_lt >= start_lt`. + description: 'Query traces with `end_lt >= start_lt`.' schema: type: integer format: int64 minimum: 0 - name: end_lt in: query - description: Query traces with `end_lt <= end_lt`. + description: 'Query traces with `end_lt <= end_lt`.' schema: type: integer format: int64 @@ -1888,7 +1782,7 @@ paths: type: string - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -1897,7 +1791,7 @@ paths: maximum: 1000 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -1914,21 +1808,19 @@ paths: - desc responses: '200': - description: OK + description: Matching traces with address book and metadata. content: application/json: schema: $ref: '#/components/schemas/TracesResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '422': + $ref: '#/components/responses/422' /api/v3/transactions: get: security: [] - description: Get transactions by specified filter. + description: 'Returns transactions matching the specified filters. Filter by block coordinates, masterchain sequence + number, account address, transaction hash, logical time, or time range. Each transaction includes inbound message, + outbound messages, fees, and execution phases.' tags: - Blockchain Data summary: Get transactions @@ -1947,7 +1839,7 @@ paths: type: string - name: seqno in: query - description: Block block seqno. Must be sent with *workchain* and *shard*. + description: 'Block block seqno. Must be sent with *workchain* and *shard*.' schema: type: integer format: int32 @@ -1959,7 +1851,7 @@ paths: format: int32 - name: account in: query - description: List of account addresses to get transactions. Can be sent in hex, base64 or base64url form. + description: 'List of account addresses to get transactions. Can be sent in hex, base64 or base64url form.' explode: true schema: type: array @@ -1986,35 +1878,35 @@ paths: format: int64 - name: start_utime in: query - description: Query transactions with generation UTC timestamp **after** given timestamp. + description: 'Query transactions with generation UTC timestamp **after** given timestamp.' schema: type: integer format: int32 minimum: 0 - name: end_utime in: query - description: Query transactions with generation UTC timestamp **before** given timestamp. + description: 'Query transactions with generation UTC timestamp **before** given timestamp.' schema: type: integer format: int32 minimum: 0 - name: start_lt in: query - description: Query transactions with `lt >= start_lt`. + description: 'Query transactions with `lt >= start_lt`.' schema: type: integer format: int64 minimum: 0 - name: end_lt in: query - description: Query transactions with `lt <= end_lt`. + description: 'Query transactions with `lt <= end_lt`.' schema: type: integer format: int64 minimum: 0 - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -2023,7 +1915,7 @@ paths: maximum: 1000 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -2040,24 +1932,19 @@ paths: - desc responses: '200': - description: OK + description: Matching transactions with address book. content: application/json: schema: $ref: '#/components/schemas/TransactionsResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' /api/v3/transactionsByMasterchainBlock: get: security: [] - description: Returns transactions from masterchain block and from all shards. + description: Returns all transactions from a masterchain block and its associated shard blocks. Provides a complete + view of all activity committed in a single masterchain round. tags: - Blockchain Data - summary: Get transactions by Masterchain block + summary: Get transactions by masterchain block operationId: api_v3_get_transactions_by_masterchain_block parameters: - name: seqno @@ -2069,7 +1956,7 @@ paths: format: int32 - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -2078,7 +1965,7 @@ paths: maximum: 1000 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -2095,21 +1982,16 @@ paths: - desc responses: '200': - description: OK + description: All transactions in the specified masterchain block and its shards. content: application/json: schema: $ref: '#/components/schemas/TransactionsResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' /api/v3/transactionsByMessage: get: security: [] - description: Get transactions whose inbound/outbound message has the specified hash. \ + description: 'Returns transactions whose inbound or outbound message matches the specified hash, body hash, or opcode. + At least one of `msg_hash`, `body_hash`, or `opcode` is required. Use `direction` to filter by inbound or outbound.' tags: - Blockchain Data summary: Get transactions by message @@ -2117,7 +1999,7 @@ paths: parameters: - name: msg_hash in: query - description: Message hash. Acceptable in hex, base64 and base64url forms. + description: 'Message hash. Acceptable in hex, base64 and base64url forms.' schema: type: string - name: body_hash @@ -2127,7 +2009,7 @@ paths: type: string - name: opcode in: query - description: Opcode of message in hex or signed 32-bit decimal form. + description: 'Opcode of message in hex or signed 32-bit decimal form.' schema: type: string - name: direction @@ -2140,7 +2022,7 @@ paths: - out - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -2149,7 +2031,7 @@ paths: maximum: 1000 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -2157,24 +2039,22 @@ paths: minimum: 0 responses: '200': - description: OK + description: Transactions matching the specified message filters. content: application/json: schema: $ref: '#/components/schemas/TransactionsResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '422': + $ref: '#/components/responses/422' /api/v3/vesting: get: security: [] - description: Get vesting contracts by specified filters + description: 'Returns vesting contracts matching the specified filters. Filter by contract address or wallet address + (owner or sender). Each result includes vesting schedule parameters: start time, cliff duration, total duration, unlock + period, total amount, and optional whitelist.' tags: - Vesting - summary: Get Vesting Contracts + summary: Get vesting contracts operationId: api_v3_get_vesting_contracts parameters: - name: contract_address @@ -2201,7 +2081,7 @@ paths: default: false - name: limit in: query - description: Limit number of queried rows. Use with *offset* to batch read. + description: 'Limit number of queried rows. Use with *offset* to batch read.' schema: type: integer format: int32 @@ -2210,7 +2090,7 @@ paths: maximum: 1000 - name: offset in: query - description: Skip first N rows. Use with *limit* to batch read. + description: 'Skip first N rows. Use with *limit* to batch read.' schema: type: integer format: int32 @@ -2218,25 +2098,20 @@ paths: minimum: 0 responses: '200': - description: OK + description: Matching vesting contracts with address book. content: application/json: schema: $ref: '#/components/schemas/VestingContractsResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' /api/v3/walletInformation: get: security: [] - description: 'Get wallet smart contract information. The following wallets are supported: `v1r1`, `v1r2`, `v1r3`, `v2r1`, - `v2r2`, `v3r1`, `v3r2`, `v4r1`, `v4r2`, `v5beta`, `v5r1`. In case the account is not a wallet error code 409 is returned.' + description: 'Returns wallet-specific information for an account. Identifies the wallet version and extracts wallet + fields like `seqno` and `wallet_id`. Supported wallets: v1r1, v1r2, v1r3, v2r1, v2r2, v3r1, v3r2, v4r1, v4r2, v5beta, + v5r1. Returns error 409 if the account exists but isn''t a wallet contract.' tags: - Api/v2 - summary: Get Wallet Information + summary: Get wallet information operationId: api_v3_get_wallet_information parameters: - name: address @@ -2253,24 +2128,26 @@ paths: default: true responses: '200': - description: OK + description: 'Wallet-specific details: type, seqno, wallet ID, and balance.' content: application/json: schema: $ref: '#/components/schemas/V2WalletInformation' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '401': + $ref: '#/components/responses/401' + '409': + $ref: '#/components/responses/409' + '500': + $ref: '#/components/responses/500' /api/v3/walletStates: get: security: [] - description: Query wallet information + description: 'Returns wallet state for one or more addresses. Detects whether each address is a wallet contract and + extracts wallet-specific fields (type, seqno, wallet_id, signature permissions). Non-wallet addresses are included + with `is_wallet: false`.' tags: - Accounts - summary: Get Wallet States + summary: Get wallet states operationId: api_v3_get_wallet_states parameters: - name: address @@ -2284,1294 +2161,2118 @@ paths: type: string responses: '200': - description: OK + description: Wallet state for each requested address. content: application/json: schema: $ref: '#/components/schemas/WalletStatesResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/RequestError' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' components: schemas: AccountBalance: type: object + description: 'Lightweight account summary containing only the address and TON balance. Returned by the top-accounts-by-balance + endpoint for ranking and analytics.' properties: account: type: string + description: 'Account address in raw format (`workchain:hex`), e.g., `0:abc123...`.' balance: type: string + description: 'Account balance in nanotons (the smallest unit of TON). 1 TON = 1,000,000,000 nanotons. Divide by + 10^9 to get the human-readable TON amount.' AccountState: type: object + description: 'Snapshot of an account''s on-chain state at a point in time. Includes balance, contract code and data + hashes, extra currency holdings, and frozen state. Used in transaction objects to show the account state before and + after execution.' properties: account_status: type: string + description: 'Account lifecycle status: `uninit` (address exists but no contract deployed, can receive TON), `active` + (contract is deployed and working), or `frozen` (contract suspended due to zero balance, send TON to unfreeze).' balance: type: string + description: 'Account balance in nanotons. 1 TON = 1,000,000,000 nanotons. Divide by 10^9 to get the human-readable + TON amount.' code_boc: type: string + description: 'Smart contract code in BOC (Bag of Cells) format, base64 encoded. Empty or absent if the account is + uninitialized.' code_hash: type: string + description: 'SHA-256 hash of the contract code cell, hex encoded (64 characters). Use this to identify the contract + type without downloading the full code.' data_boc: type: string + description: 'Smart contract persistent storage in BOC format, base64 encoded. Contains the contract''s state variables. + Empty or absent if the account is uninitialized.' data_hash: type: string + description: 'SHA-256 hash of the contract data cell, hex encoded (64 characters).' extra_currencies: type: object + description: 'Map of extra currency balances held by this account. Keys are currency IDs (integers defined in masterchain + `ConfigParam 7`), values are balance amounts as decimal strings. Empty if the account holds no extra currencies.' additionalProperties: type: string frozen_hash: type: string + description: 'Hash of the frozen state. Present only when the account status is `frozen`. The account can be unfrozen + by sending it enough TON to cover storage fees.' hash: type: string + description: Hash of this account state snapshot. AccountStateFull: type: object + description: 'Complete account state with all available metadata. Extends `AccountState` with the full address, detected + contract interfaces (e.g., `wallet_v4r2`, `jetton_master`), supported get-method IDs, and a reference to the most + recent transaction. This is the primary schema for the account states endpoint.' properties: account_state_hash: type: string + description: 'Hash of the complete account state, including code, data, and balance.' address: type: string + description: 'Account address in raw format (`workchain:hex`), e.g., `0:abc123...`.' balance: type: string + description: 'Account balance in nanotons. 1 TON = 1,000,000,000 nanotons. Divide by 10^9 to get the human-readable + TON amount.' code_boc: type: string + description: 'Smart contract code in BOC format, base64 encoded. Empty or absent if the account is uninitialized.' code_hash: type: string + description: 'SHA-256 hash of the contract code cell, hex encoded (64 characters). Use this to identify the contract + type without downloading the full code.' contract_methods: type: array + description: 'List of detected get-method IDs (CRC32 hashes) supported by this contract. Use these to determine + which get methods you can call via the `runGetMethod` endpoint.' items: type: integer data_boc: type: string + description: 'Smart contract persistent storage in BOC format, base64 encoded. Contains the contract''s state variables.' data_hash: type: string + description: 'SHA-256 hash of the contract data cell, hex encoded (64 characters).' extra_currencies: type: object + description: 'Map of extra currency balances held by this account. Keys are currency IDs (integers), values are + balance amounts as decimal strings.' additionalProperties: type: string frozen_hash: type: string + description: 'Hash of the frozen state. Present only when status is `frozen`.' interfaces: type: array + description: 'List of detected smart contract interfaces, e.g., `wallet_v4r2`, `jetton_master`, `nft_item`. Determined + by matching the code hash and supported get methods against known contract standards.' items: type: string last_transaction_hash: type: string + description: 'Hash of the most recent transaction on this account, hex encoded. Use together with `last_transaction_lt` + to start paginating transaction history.' last_transaction_lt: type: string + description: Logical time of the most recent transaction on this account. Logical time is a globally unique counter + that orders all events on the blockchain; higher values are more recent. example: '0' status: type: string + description: 'Account lifecycle status: `uninit` (no contract deployed), `active` (contract running), or `frozen` + (suspended due to zero balance).' AccountStatesResponse: type: object + description: 'Response wrapper for account state queries. Contains the requested account states along with an address + book (for converting raw addresses to user-friendly form) and metadata (for token information).' properties: accounts: type: array + description: 'Array of full account state objects, one per requested address.' items: $ref: '#/components/schemas/AccountStateFull' address_book: + description: 'Address book mapping raw addresses to user-friendly base64url forms and detected interfaces for all + addresses referenced in the response.' $ref: '#/components/schemas/AddressBook' metadata: + description: 'Token and indexing metadata for all addresses referenced in the response. Includes token name, symbol, + and image for recognized Jetton and NFT contracts.' $ref: '#/components/schemas/Metadata' Action: type: object + description: 'A parsed high-level action derived from an on-chain execution trace. Actions provide a human-readable + interpretation of raw transactions, such as TON transfers, Jetton swaps, NFT mints, and staking operations. Each action + links back to its parent trace and the specific transactions involved.' properties: accounts: type: array + description: 'List of account addresses involved in this action. Includes sender, receiver, and any intermediary + contracts.' items: type: string action_id: type: string - details: {} + description: 'Unique identifier for this action, derived from the trace and action position.' + details: + description: 'Action-specific structured details. The schema varies by action `type`: for `ton_transfer` it includes + amount and comment; for `jetton_transfer` it includes Jetton-specific fields; for `jetton_swap` it includes DEX + details, etc.' end_lt: type: string + description: Logical time when this action completed. Logical time is a globally unique counter ordering all blockchain + events; higher values are more recent. example: '0' end_utime: type: integer + description: Unix timestamp (seconds since epoch) when this action completed. start_lt: type: string + description: Logical time when this action started. example: '0' start_utime: type: integer + description: Unix timestamp (seconds since epoch) when this action started. success: type: boolean + description: Whether the action completed successfully. An action is considered failed if any of its constituent + transactions were aborted. trace_end_lt: type: string + description: Logical time when the parent trace finished processing. example: '0' trace_end_utime: type: integer + description: Unix timestamp when the parent trace finished processing. trace_external_hash: type: string + description: Hash of the external inbound message that initiated the parent trace. Use this to look up the original + message that triggered the entire chain of actions. trace_external_hash_norm: type: string + description: 'Normalized hash of the external message that initiated the trace. Normalized hashes are stable across + re-serializations.' trace_id: type: string + description: 'Identifier of the parent trace. All actions within the same message chain share the same `trace_id`.' trace_mc_seqno_end: type: integer + description: Masterchain block sequence number in which the parent trace was finalized. transactions: type: array + description: List of transaction hashes involved in this action. Use these to look up full transaction details via + the transactions endpoint. items: type: string transactions_full: type: array + description: 'Full transaction objects for this action. Only populated when `include_transactions=true` is set in + the request.' items: $ref: '#/components/schemas/Transaction' type: type: string + description: 'Action type identifier. Possible values include: `ton_transfer`, `jetton_transfer`, `jetton_burn`, + `jetton_mint`, `jetton_swap`, `nft_mint`, `nft_transfer` (not exhaustive, use `supported_action_types` parameter + to discover all).' ActionPhase: type: object + description: 'Details of the action phase during transaction execution. The action phase processes the list of actions + generated by the TVM (sending messages, reserving currency, changing code, etc.) and reports how many succeeded, failed, + or were skipped.' properties: action_list_hash: type: string + description: Hash of the action list produced by the TVM during the compute phase. msgs_created: type: integer + description: Number of outbound messages successfully created during this phase. no_funds: type: boolean + description: Whether any actions failed because the account had insufficient funds to cover message value plus fees. result_arg: type: integer + description: 'Additional argument for the result code, providing extra context on failures.' result_code: type: integer + description: 'Action phase result code. `0` indicates all actions succeeded. Non-zero values indicate specific failure + reasons.' skipped_actions: type: integer + description: Number of actions that were skipped (not processed). spec_actions: type: integer + description: 'Number of special actions executed, such as `SETCODE` (change contract code), `RESERVE` (reserve currency), + or `SETLIB` (set library).' status_change: type: string + description: 'Account status change resulting from this phase, if any (e.g., account frozen or deleted).' success: type: boolean + description: Whether the action phase completed successfully (all actions processed without critical failure). tot_actions: type: integer + description: Total number of actions in the action list produced by the TVM. tot_msg_size: + description: Total size (in cells and bits) of all outbound messages created during this phase. $ref: '#/components/schemas/MsgSize' total_action_fees: type: string + description: 'Total action processing fees in nanotons, deducted from the account balance.' example: '0' total_fwd_fees: type: string + description: 'Total forwarding fees for all outbound messages created, in nanotons. This is the cost of delivering + the messages to their destinations.' example: '0' valid: type: boolean + description: Whether the action list produced by the TVM is structurally valid. ActionsResponse: type: object + description: Response wrapper for action queries. Contains parsed actions along with an address book and metadata for + all referenced addresses. properties: actions: type: array + description: 'Array of parsed high-level actions matching the query filters.' items: $ref: '#/components/schemas/Action' address_book: + description: 'Address book mapping raw addresses to user-friendly forms for all addresses referenced in the response.' $ref: '#/components/schemas/AddressBook' metadata: + description: Token and indexing metadata for all addresses referenced in the response. $ref: '#/components/schemas/Metadata' AddressBook: type: object + description: 'Dictionary mapping raw account addresses to their human-readable forms. Keys are raw addresses (hex), + values are `AddressBookRow` objects with the user-friendly base64url form, detected interfaces, and DNS domain.' additionalProperties: $ref: '#/components/schemas/AddressBookRow' AddressBookRow: type: object + description: 'A single address book entry providing the user-friendly address form, detected smart contract interfaces, + and associated DNS domain name (if any).' properties: domain: type: string + description: 'TON DNS domain name associated with this address (e.g., `example.ton`), if one exists.' interfaces: type: array + description: 'List of detected smart contract interfaces, e.g., `wallet_v4r2`, `jetton_master`, `nft_item`. Useful + for determining what kind of contract is deployed at this address.' items: type: string user_friendly: type: string + description: 'User-friendly address in base64url encoding (48 characters). This is the format commonly used in wallets + and explorers.' AddressMetadata: type: object + description: 'Metadata for an address including whether it has been indexed by the system and any associated token information + (for Jetton masters, Jetton wallets, NFT collections, and NFT items).' properties: is_indexed: type: boolean + description: Whether this address has been fully indexed by the system. Unindexed addresses may have incomplete + transaction history. token_info: type: array + description: 'Array of token metadata entries for this address. Contains name, symbol, image, and type for recognized + Jetton masters, Jetton wallets, NFT collections, and NFT items.' items: $ref: '#/components/schemas/TokenInfo' Block: type: object + description: 'A block on the TON blockchain with complete header metadata. Contains identification fields (workchain, + shard, seqno), timing (logical time range, generation timestamp), validator info, shard state flags (split/merge), + and references to previous blocks and the masterchain.' properties: after_merge: type: boolean + description: Whether this block was produced immediately after two sibling shards merged into one. after_split: type: boolean + description: Whether this block was produced immediately after a shard split into two. before_split: type: boolean + description: Whether this shard is scheduled to split after this block. The next two blocks will belong to the two + new child shards. created_by: type: string + description: 'Ed25519 public key of the validator that produced this block, hex encoded.' end_lt: type: string + description: 'Logical time at the end of this block. All transactions in this block have logical times within `[start_lt, + end_lt)`.' example: '0' file_hash: type: string + description: 'SHA-256 hash of the serialized block file. Together with `root_hash`, uniquely identifies a block + independently of its workchain/shard/seqno coordinates.' flags: type: integer + description: Block header flags (bitmask). Internal use by the TON node. gen_catchain_seqno: type: integer + description: Catchain sequence number at the time this block was generated. Catchain is the consensus protocol layer. gen_utime: type: string + description: Unix timestamp (seconds since epoch) when this block was generated by the validator. example: '0' global_id: type: integer + description: 'Global network identifier. `-239` for mainnet, `-3` for testnet.' key_block: type: boolean + description: 'Whether this is a key block. Key blocks contain updated validator sets and configuration parameters, + and are used as reference points for lite client proofs.' master_ref_seqno: type: integer + description: Sequence number of the masterchain block referenced by this shard block. Not present for masterchain + blocks themselves. masterchain_block_ref: + description: 'Full identifier of the associated masterchain block (workchain, shard, seqno).' $ref: '#/components/schemas/BlockId' min_ref_mc_seqno: type: integer + description: Minimum masterchain block sequence number referenced by any message in this block. prev_blocks: type: array + description: References to the previous block(s). Usually one block; two blocks after a shard merge. items: $ref: '#/components/schemas/BlockId' prev_key_block_seqno: type: integer + description: Sequence number of the most recent key block before this one. rand_seed: type: string + description: 'Random seed used for this block, hex encoded. Derived from the validator set and used for random number + generation in contracts.' root_hash: type: string + description: 'Root hash of the block''s Merkle tree, hex encoded. Together with `file_hash`, uniquely identifies + this block.' seqno: type: integer + description: 'Block sequence number within its workchain and shard. For the masterchain (workchain `-1`), this equals + the global block height.' shard: type: string + description: 'Shard identifier as a signed 64-bit integer string. The masterchain uses a single shard `-9223372036854775808` + (`0x8000000000000000`).' example: '0' start_lt: type: string + description: Logical time at the start of this block. example: '0' tx_count: type: integer + description: Number of transactions included in this block. validator_list_hash_short: type: integer + description: 'Short hash of the current validator set, used for fast validation.' version: type: integer + description: Block format version number. vert_seqno: type: integer + description: Vertical sequence number. Used during hard forks to distinguish blocks at the same seqno. vert_seqno_incr: type: boolean + description: Whether the vertical sequence number was incremented in this block (indicates a hard fork event). want_merge: type: boolean + description: Whether this shard has signaled that it wants to merge with its sibling shard due to low load. want_split: type: boolean + description: Whether this shard has signaled that it wants to split into two child shards due to high load. workchain: type: integer + description: 'Workchain ID. `-1` for the masterchain (validators, configuration), `0` for the basechain (user transactions + and smart contracts).' BlockId: type: object + description: 'Compact block identifier using the three-part key: workchain ID, shard identifier, and sequence number. + Together these uniquely identify any block on the TON blockchain.' properties: seqno: type: integer + description: Block sequence number within its workchain and shard. shard: type: string + description: 'Shard identifier as a signed 64-bit integer string.' example: '0' workchain: type: integer + description: 'Workchain ID. `-1` for masterchain, `0` for basechain.' BlocksResponse: type: object + description: Response wrapper containing a list of blocks matching the query filters. properties: blocks: type: array + description: Array of blocks matching the query filters. items: $ref: '#/components/schemas/Block' BouncePhase: type: object + description: 'Details of the bounce phase, which occurs when an internal message with the bounce flag set fails during + execution. The bounce phase constructs and sends back a bounce message with relevant fees.' properties: fwd_fees: type: string + description: 'Forwarding fees for delivering the bounce message back to the sender, in nanotons.' example: '0' msg_fees: type: string + description: 'Additional message fees for the bounce message, in nanotons.' example: '0' msg_size: + description: Size of the bounce message in cells and bits. $ref: '#/components/schemas/MsgSize' req_fwd_fees: type: string + description: 'Required forwarding fees as originally specified, in nanotons.' example: '0' type: type: string + description: 'Bounce phase outcome: `ok` (bounce message sent successfully), `no_funds` (insufficient funds to create + bounce message), or `neg_funds` (bounce would result in negative balance).' ComputePhase: type: object + description: 'Details of the compute phase during transaction execution. The TVM executes the smart contract code, consuming + gas and producing an action list. This phase reports gas usage, exit codes, VM step count, and whether computation + succeeded.' properties: account_activated: type: boolean + description: 'Whether the account transitioned from `uninit` to `active` during this computation (i.e., contract + was deployed).' exit_arg: type: integer + description: 'Additional TVM exit argument, providing context for non-zero exit codes.' exit_code: type: integer + description: 'TVM exit code. `0` and `1` indicate successful execution. Non-zero codes (2+) indicate errors: `2` + = stack underflow, `3` = stack overflow, `4` = integer overflow, `5` = range check error, etc.' gas_credit: type: string + description: 'Gas credit granted for processing external inbound messages, in gas units. External messages receive + a gas credit to execute enough code to accept the message; if the contract doesn''t call `ACCEPT`, the transaction + is discarded.' example: '0' gas_fees: type: string + description: 'Total gas fees charged for TVM execution, in nanotons. Computed as gas_used × gas_price.' example: '0' gas_limit: type: string + description: 'Maximum gas the TVM was allowed to consume, in gas units.' example: '0' gas_used: type: string + description: 'Actual gas consumed during TVM execution, in gas units.' example: '0' mode: type: integer + description: Compute phase mode indicator. msg_state_used: type: boolean + description: Whether the message's StateInit was used to initialize the account. reason: type: string + description: 'Human-readable reason the compute phase was skipped. Present only when `skipped` is `true` (e.g., + account not active, no gas).' skipped: type: boolean + description: 'Whether the compute phase was skipped entirely (e.g., the account has no code to execute).' success: type: boolean + description: Whether the TVM execution completed successfully (exit code 0 or 1). vm_final_state_hash: type: string + description: Hash of the TVM state after execution completed. vm_init_state_hash: type: string + description: Hash of the TVM state before execution started. vm_steps: type: integer + description: Number of TVM instruction steps executed. Each step corresponds to one TVM opcode. CreditPhase: type: object + description: 'Details of the credit phase during transaction execution. In this phase, the value carried by the inbound + message is credited to the account balance before computation begins.' properties: credit: type: string + description: 'Amount of TON credited to the account from the inbound message, in nanotons. This is the message value + minus any forwarding fees.' example: '0' credit_extra_currencies: type: object + description: 'Map of extra currency IDs to amounts credited from the inbound message. Keys are currency ID strings, + values are amount strings.' additionalProperties: type: string due_fees_collected: type: string + description: 'Storage fees that were due and collected during the credit phase, in nanotons.' example: '0' DNSRecord: type: object + description: 'A TON DNS record entry. TON DNS maps human-readable `.ton` and `.t.me` domains to wallet addresses, ADNL + site addresses, storage bags, and next-hop resolvers. Each record is backed by an NFT item on-chain.' properties: dns_next_resolver: type: string + description: 'Address of the next DNS resolver in the resolution chain. Used for subdomain delegation: queries for + subdomains are forwarded to this resolver.' dns_site_adnl: type: string + description: ADNL address of a TON Site associated with this domain. TON Sites are decentralized websites accessible + via the TON network. dns_storage_bag_id: type: string + description: TON Storage bag ID linked to this domain. Allows associating decentralized file storage with a DNS + name. dns_wallet: type: string + description: Wallet address associated with this domain. This is the address that receives funds when someone sends + TON to this domain name. domain: type: string + description: 'The fully qualified domain name (e.g., `example.ton` or `user.t.me`).' nft_item_address: type: string + description: Address of the NFT item contract that represents ownership of this domain. nft_item_owner: type: string + description: Current owner of the domain NFT. This is the address that controls the DNS record. DNSRecordsResponse: type: object + description: Response wrapper containing DNS records and an address book for all referenced addresses. properties: address_book: + description: 'Address book mapping raw addresses to user-friendly forms for all addresses referenced in the response.' $ref: '#/components/schemas/AddressBook' records: type: array + description: Array of DNS records matching the query filters. items: $ref: '#/components/schemas/DNSRecord' DecodeRequest: type: object + description: 'Request body for the decode endpoint. Accepts lists of opcodes (hex or decimal format) and message bodies + (base64 or hex format) to be decoded into human-readable form.' properties: bodies: type: array + description: 'List of message bodies to decode. Each body should be a base64-encoded or hex-encoded BOC. Maximum + 1000 items.' items: type: string opcodes: type: array + description: 'List of opcodes to decode into human-readable names. Each opcode can be in hex format (with or without + `0x` prefix) or decimal format. Maximum 1000 items.' items: type: string DecodeResponse: type: object + description: Response from the decode endpoint containing decoded opcode names and parsed message body structures. properties: bodies: type: array + description: Array of decoded message bodies. Each entry is a structured object with the decoded opcode name and + parsed payload fields. Entries that could not be decoded return the raw data. items: type: object additionalProperties: true opcodes: type: array + description: Array of decoded opcode names corresponding to the input opcodes. Unknown opcodes return the original + value unchanged. items: type: string JettonBurn: type: object + description: 'A Jetton burn event representing tokens permanently removed from circulation. Contains the burn amount, + the wallet and owner involved, the query ID for tracking, and a reference to the on-chain transaction.' properties: amount: type: string + description: 'Number of Jetton tokens burned, in the token''s smallest unit. Divide by 10^decimals (from the Jetton + master metadata) to get the human-readable amount.' custom_payload: type: string + description: 'Optional custom payload attached to the burn message, base64-encoded BOC. Application-specific data + defined by the Jetton implementation.' decoded_custom_payload: type: array + description: Decoded custom payload as a raw byte array. Present when the payload could be parsed. items: type: integer jetton_master: type: string + description: Address of the Jetton master contract that governs this token. jetton_wallet: type: string + description: Address of the Jetton wallet contract that executed the burn. owner: type: string + description: Address of the Jetton wallet owner who initiated the burn. query_id: type: string + description: 'Query ID specified by the sender for matching request/response messages. A 64-bit integer as a decimal + string.' response_destination: type: string + description: Address that will receive the burn notification response message. Typically the sender's wallet. trace_id: type: string + description: Identifier of the execution trace containing this burn event. Use this to see the full chain of messages. transaction_aborted: type: boolean + description: 'Whether the transaction containing this burn was aborted. If `true`, the burn did not actually take + effect.' transaction_hash: type: string + description: 'Hash of the on-chain transaction containing this burn event.' transaction_lt: type: string + description: Logical time of the transaction containing this burn. Higher values are more recent. example: '0' transaction_now: type: integer + description: Unix timestamp (seconds since epoch) of the transaction containing this burn. JettonBurnsResponse: type: object + description: Response wrapper containing Jetton burn events with address book and token metadata. properties: address_book: + description: 'Address book mapping raw addresses to user-friendly forms for all addresses referenced in the response.' $ref: '#/components/schemas/AddressBook' jetton_burns: type: array + description: Array of Jetton burn events matching the query filters. items: $ref: '#/components/schemas/JettonBurn' metadata: + description: Token and indexing metadata for all addresses referenced in the response. $ref: '#/components/schemas/Metadata' JettonMaster: type: object + description: 'A Jetton master contract, which is the central registry for a Jetton token. Stores the total supply, admin + address, mintability status, on-chain content metadata (name, symbol, image, decimals), and the code hash used to + deploy individual Jetton wallets.' properties: address: type: string + description: Address of this Jetton master contract. This is the canonical identifier for the token — use it to + look up Jetton wallets and transfers. admin_address: type: string + description: Address of the Jetton admin who can mint new tokens and change metadata. May be null/zero address if + the Jetton has been made immutable. code_hash: type: string + description: 'SHA-256 hash of the contract code, hex encoded. Use this to verify the contract implementation.' data_hash: type: string + description: 'SHA-256 hash of the contract data, hex encoded.' jetton_content: type: object + description: 'On-chain Jetton metadata as a key-value object. Standard fields include `name`, `symbol`, `image`, + `description`, and `decimals`. The `decimals` field (commonly `9`) determines how to convert raw amounts to human-readable + values.' additionalProperties: true jetton_wallet_code_hash: type: string + description: Code hash of the Jetton wallet contracts deployed by this master. All legitimate wallets for this Jetton + share this code hash. last_transaction_lt: type: string + description: Logical time of the most recent transaction on this master contract. Use for ordering and pagination. example: '0' mintable: type: boolean + description: 'Whether the admin can mint new tokens. Once set to `false`, the total supply is permanently fixed.' total_supply: type: string + description: 'Total supply of this Jetton in the token''s smallest unit. Divide by 10^decimals to get the human-readable + total.' JettonMastersResponse: type: object + description: Response wrapper containing Jetton master contracts with address book and token metadata. properties: address_book: + description: 'Address book mapping raw addresses to user-friendly forms for all addresses referenced in the response.' $ref: '#/components/schemas/AddressBook' jetton_masters: type: array + description: Array of Jetton master contracts matching the query filters. items: $ref: '#/components/schemas/JettonMaster' metadata: + description: Token and indexing metadata for all addresses referenced in the response. $ref: '#/components/schemas/Metadata' JettonTransfer: type: object + description: 'A Jetton transfer event representing tokens moved between owners. Contains the transfer amount, source + and destination owner addresses, the Jetton wallet that executed the transfer, optional forward and custom payloads, + and the TON amount forwarded for gas.' properties: amount: type: string + description: 'Number of Jetton tokens transferred, in the token''s smallest unit. Divide by 10^decimals (from the + Jetton master metadata) to get the human-readable amount.' custom_payload: type: string + description: 'Optional custom payload attached to the transfer, base64-encoded BOC. Application-specific data defined + by the Jetton implementation.' decoded_custom_payload: type: array + description: Decoded custom payload as a raw byte array. Present when the payload could be parsed. items: type: integer decoded_forward_payload: type: array + description: Decoded forward payload as a raw byte array. Present when the payload could be parsed. items: type: integer destination: type: string + description: 'Address of the destination owner (the recipient of the Jettons). This is the owner address, not the + destination Jetton wallet address.' forward_payload: type: string + description: 'Payload forwarded to the destination owner along with the transfer notification, base64-encoded BOC. + Often contains a text comment or application-specific data (e.g., a swap instruction for DEX contracts).' forward_ton_amount: type: string + description: 'Amount of TON forwarded to the destination along with the transfer notification, in nanotons. The + destination contract uses this gas to process the notification.' jetton_master: type: string + description: Address of the Jetton master contract that governs this token. query_id: type: string + description: 'Query ID specified by the sender for matching request/response messages. A 64-bit integer as a decimal + string.' response_destination: type: string + description: Address that will receive the excess TON remaining after the transfer is processed. Typically the sender's + wallet. source: type: string + description: 'Address of the source owner (the sender of the Jettons). This is the owner address, not the source + Jetton wallet address.' source_wallet: type: string + description: 'Address of the Jetton wallet contract that sent the tokens. This is the on-chain contract address, + distinct from the source owner address.' trace_id: type: string + description: Identifier of the execution trace containing this transfer. Use this to see the full chain of messages. transaction_aborted: type: boolean + description: 'Whether the transaction containing this transfer was aborted. If `true`, the transfer did not actually + take effect.' transaction_hash: type: string + description: 'Hash of the on-chain transaction containing this transfer event.' transaction_lt: type: string + description: Logical time of the transaction containing this transfer. Higher values are more recent. example: '0' transaction_now: type: integer + description: Unix timestamp (seconds since epoch) of the transaction containing this transfer. JettonTransfersResponse: type: object + description: Response wrapper containing Jetton transfer events with address book and token metadata. properties: address_book: + description: 'Address book mapping raw addresses to user-friendly forms for all addresses referenced in the response.' $ref: '#/components/schemas/AddressBook' jetton_transfers: type: array + description: Array of Jetton transfer events matching the query filters. items: $ref: '#/components/schemas/JettonTransfer' metadata: + description: Token and indexing metadata for all addresses referenced in the response. $ref: '#/components/schemas/Metadata' JettonWallet: type: object + description: 'A Jetton wallet contract that holds a specific Jetton token balance for a single owner. Each owner-token + pair has a unique Jetton wallet deployed by the Jetton master. Contains the current balance, owner address, and a + reference back to the master contract.' properties: address: type: string + description: 'Address of this Jetton wallet contract. Each owner-token pair has a unique wallet address, deterministically + derived from the owner address and Jetton master.' balance: type: string + description: 'Current Jetton token balance in the token''s smallest unit. Divide by 10^decimals (from the Jetton + master metadata) to get the human-readable amount.' code_hash: type: string + description: 'SHA-256 hash of the wallet contract code, hex encoded. Should match the `jetton_wallet_code_hash` + on the Jetton master.' data_hash: type: string + description: 'SHA-256 hash of the wallet contract data, hex encoded.' jetton: type: string + description: 'Address of the Jetton master contract this wallet belongs to. Use this to look up the token name, + symbol, and decimals.' last_transaction_lt: type: string + description: Logical time of the most recent transaction on this wallet. Use for ordering and pagination. example: '0' mintless_info: + description: 'Mintless claim information, present only for Jetton wallets that have unclaimed mintless tokens. See + `JettonWalletMintlessInfo` for details.' $ref: '#/components/schemas/JettonWalletMintlessInfo' owner: type: string + description: Address of the wallet owner — the user or contract that controls this Jetton balance. JettonWalletMintlessInfo: type: object + description: 'Mintless claim information for a Jetton wallet. Mintless Jettons allow users to claim tokens without the + master contract minting them first, reducing gas costs. Contains the claimable amount, validity window, and API URIs + for retrieving the claim proof payload.' properties: amount: type: string + description: Claimable Jetton amount in the token's smallest unit. This is the amount the owner can claim without + the master contract minting new tokens. custom_payload_api_uri: type: array + description: List of API endpoint URIs for retrieving the Merkle proof payload needed to execute the mintless claim + transaction. items: type: string expire_at: type: integer + description: Unix timestamp (seconds since epoch) after which the mintless claim expires and can no longer be executed. start_from: type: integer + description: Unix timestamp (seconds since epoch) from which the mintless claim becomes available. JettonWalletsResponse: type: object + description: Response wrapper containing Jetton wallet contracts with address book and token metadata. properties: address_book: + description: 'Address book mapping raw addresses to user-friendly forms for all addresses referenced in the response.' $ref: '#/components/schemas/AddressBook' jetton_wallets: type: array + description: Array of Jetton wallet contracts matching the query filters. items: $ref: '#/components/schemas/JettonWallet' metadata: + description: Token and indexing metadata for all addresses referenced in the response. $ref: '#/components/schemas/Metadata' MasterchainInfo: type: object + description: 'The first and last indexed masterchain blocks, indicating the range of data available from the indexer. + Use this to check whether the indexer is up to date and to determine the earliest available block for historical queries.' properties: first: + description: The earliest masterchain block available in the index. Historical queries before this block will return + no data. $ref: '#/components/schemas/Block' last: + description: The most recent masterchain block processed by the indexer. Compare this to the network's current block + to check indexer lag. $ref: '#/components/schemas/Block' Message: type: object + description: 'A message on the TON blockchain. Messages are the fundamental unit of communication between accounts. + Internal messages carry TON value between contracts; external inbound messages trigger contract execution from outside; + external outbound messages emit logs. Each message has headers (source, destination, value, fees) and a body (opcode + + payload).' properties: bounce: type: boolean + description: 'Whether the bounce flag is set on this message. When `true` and the destination contract fails to + process the message, a bounce message carrying the remaining value is sent back to the source.' bounced: type: boolean + description: Whether this message is itself a bounce — an automatic reply sent when the original message failed + at the destination. created_at: type: string + description: Unix timestamp (seconds since epoch) when this message was created. example: '0' created_lt: type: string + description: Logical time when this message was created. Logical time is a globally unique counter ordering all + blockchain events; higher values are more recent. example: '0' decoded_opcode: type: string + description: 'Human-readable name of the message opcode (e.g., `jetton_transfer`, `nft_transfer`, `excesses`). Decoded + from the first 32 bits of the message body.' destination: type: string + description: 'Destination address in raw format. Empty string for external outbound messages (logs emitted by contracts). + Use value `null` in query parameters to filter for these.' extra_flags: type: string + description: Additional message flags beyond the standard header fields. fwd_fee: type: string + description: Forwarding fee in nanotons — the cost of delivering this message from the source shard to the destination + shard. example: '0' hash: type: string + description: 'SHA-256 hash of the full message cell, hex encoded. Use this to look up the message or find related + transactions.' hash_norm: type: string + description: 'Normalized message hash, stable across re-serializations. Different from `hash` when the message contains + non-deterministic serialization.' ihr_disabled: type: boolean + description: 'Whether Instant Hypercube Routing is disabled for this message. IHR is currently disabled network-wide, + so this is typically `true`.' ihr_fee: type: string + description: 'IHR delivery fee in nanotons. Currently always `0` since IHR is disabled.' example: '0' import_fee: type: string + description: 'Import fee for external inbound messages, in nanotons. Covers the cost of importing the message into + the blockchain.' example: '0' in_msg_tx_hash: type: string + description: Hash of the transaction where this message was received (processed as an inbound message). init_state: + description: StateInit attached to the message for contract deployment. Contains the initial code and data cells. + Present only when deploying a new contract. $ref: '#/components/schemas/MessageContent' message_content: + description: 'Message body content including the raw BOC, body hash, and optional decoded representation with parsed + opcode and payload fields.' $ref: '#/components/schemas/MessageContent' opcode: type: integer + description: 'Integer opcode from the first 32 bits of the message body. Identifies the operation type. Common values: + `0x0f8a7ea5` (jetton_transfer), `0x7362d09c` (jetton_notify), `0x5fcc3d14` (nft_transfer).' out_msg_tx_hash: type: string + description: Hash of the transaction that created this message (as an outbound message). source: type: string + description: 'Source address in raw format. Empty string for external inbound messages (sent from outside the blockchain). + Use value `null` in query parameters to filter for these.' value: type: string + description: 'TON value carried by this message, in nanotons. This is the amount of TON being transferred from source + to destination.' example: '0' value_extra_currencies: type: object + description: 'Map of extra currency IDs to amounts carried by this message. Keys are currency ID strings, values + are amount strings. Empty if no extra currencies are attached.' additionalProperties: type: string MessageContent: type: object + description: 'Message body content. Contains the raw base64-encoded BOC of the message body, its hash, and an optional + decoded representation where the opcode and payload have been parsed into structured fields.' properties: body: type: string + description: 'Raw message body in BOC format, base64 encoded. Decode this to extract the opcode and payload.' decoded: type: object + description: 'Decoded message body as a structured object with named fields. The structure depends on the opcode. + For example, a `jetton_transfer` body decodes to `{query_id, amount, destination, ...}`.' hash: type: string + description: 'SHA-256 hash of the message body cell. Use `body_hash` in query parameters to find messages with the + same payload.' MessagesResponse: type: object + description: Response wrapper containing messages with address book and token metadata. properties: address_book: + description: 'Address book mapping raw addresses to user-friendly forms for all addresses referenced in the response.' $ref: '#/components/schemas/AddressBook' messages: type: array + description: Array of messages matching the query filters. items: $ref: '#/components/schemas/Message' metadata: + description: Token and indexing metadata for all addresses referenced in the response. $ref: '#/components/schemas/Metadata' Metadata: type: object + description: 'Dictionary mapping raw account addresses to their metadata. Each entry indicates whether the address is + indexed and provides token information (name, symbol, image, type) for recognized Jetton and NFT contracts.' additionalProperties: $ref: '#/components/schemas/AddressMetadata' MsgSize: type: object + description: Message size measured in TVM cells and bits. Used in transaction phase details to report the size of messages + created or bounced during execution. properties: bits: type: string + description: Total size in bits across all cells. example: '0' cells: type: string + description: Number of TVM cells. Each cell holds up to 1023 bits and 4 references to other cells. example: '0' Multisig: type: object + description: 'A multisig wallet contract implementing multi-party authorization. Stores the list of authorized signers, + proposers (who can create orders but not sign), the approval threshold, and all associated orders. Based on the TON + multisig standard.' properties: address: type: string + description: Address of the multisig wallet contract. code_hash: type: string + description: 'SHA-256 hash of the contract code, hex encoded. Use this to verify the multisig implementation version.' data_hash: type: string + description: 'SHA-256 hash of the contract data, hex encoded.' last_transaction_lt: type: string + description: Logical time of the most recent transaction on this contract. example: '0' next_order_seqno: type: string + description: Sequence number that will be assigned to the next created order. Increments with each new order. orders: type: array + description: 'List of orders associated with this multisig. Only populated when `include_orders=true` in the request.' items: $ref: '#/components/schemas/MultisigOrder' proposers: type: array + description: List of proposer wallet addresses. Proposers can create new orders but cannot sign (approve) them. items: type: string signers: type: array + description: 'List of signer wallet addresses. Signers can approve orders. Once an order reaches the threshold number + of approvals, it can be executed.' items: type: string threshold: type: integer + description: Minimum number of signer approvals required to execute an order. MultisigOrder: type: object + description: 'A multisig order representing a proposed set of actions awaiting approval. Tracks which signers have approved + (via bitmask), the expiration deadline, and the parsed action payloads. Once approvals reach the threshold, the order + can be executed.' properties: actions: type: array + description: 'List of parsed actions that will be executed when this order is approved. Each action is a message + to be sent from the multisig. Only populated when `parse_actions=true` in the request.' items: $ref: '#/components/schemas/index.OrderAction' address: type: string + description: 'Address of the order contract. Each order is a separate on-chain contract.' approvals_mask: type: string + description: Bitmask indicating which signers have approved this order. Bit N corresponds to signer N in the parent + multisig's signer list. approvals_num: type: integer + description: Current number of approvals this order has received. code_hash: type: string + description: 'SHA-256 hash of the order contract code, hex encoded.' data_hash: type: string + description: 'SHA-256 hash of the order contract data, hex encoded.' expiration_date: type: integer + description: Unix timestamp (seconds since epoch) after which this order expires and can no longer be approved or + executed. last_transaction_lt: type: string + description: Logical time of the most recent transaction on this order contract. example: '0' multisig_address: type: string + description: Address of the parent multisig wallet contract that this order belongs to. order_boc: type: string + description: 'Full order data in BOC format, base64 encoded. Contains the raw actions to be executed.' order_seqno: type: string + description: Sequence number of this order within the parent multisig. Orders are numbered sequentially starting + from 0. sent_for_execution: type: boolean + description: Whether this order has already been sent for execution after reaching the approval threshold. signers: type: array + description: 'List of signer addresses for this order, inherited from the parent multisig at order creation time.' items: type: string threshold: type: integer + description: 'Number of approvals required for this order, inherited from the parent multisig at order creation + time.' MultisigOrderResponse: type: object + description: Response wrapper containing multisig orders with address book. properties: address_book: + description: 'Address book mapping raw addresses to user-friendly forms for all addresses referenced in the response.' $ref: '#/components/schemas/AddressBook' orders: type: array + description: Array of multisig orders matching the query filters. items: $ref: '#/components/schemas/MultisigOrder' MultisigResponse: type: object + description: Response wrapper containing multisig contracts with address book. properties: address_book: + description: 'Address book mapping raw addresses to user-friendly forms for all addresses referenced in the response.' $ref: '#/components/schemas/AddressBook' multisigs: type: array + description: Array of multisig contracts matching the query filters. items: $ref: '#/components/schemas/Multisig' NFTCollection: type: object + description: 'An NFT collection contract that serves as a factory and registry for NFT items. Stores on-chain collection + metadata (name, description, image), the current item count, and the collection owner address.' properties: address: type: string + description: Address of this NFT collection contract. code_hash: type: string + description: 'SHA-256 hash of the collection contract code, hex encoded.' collection_content: type: object + description: 'On-chain collection metadata as a key-value object. Standard fields include `name`, `description`, + `image`, and `marketplace` URL.' additionalProperties: true data_hash: type: string + description: 'SHA-256 hash of the collection contract data, hex encoded.' last_transaction_lt: type: string + description: Logical time of the most recent transaction on this collection contract. example: '0' next_item_index: type: string + description: Index that will be assigned to the next minted NFT item. Also indicates the current total number of + items in sequential collections. owner_address: type: string + description: Address of the collection owner/admin who can mint new items and update metadata. NFTCollectionsResponse: type: object + description: Response wrapper containing NFT collections with address book and token metadata. properties: address_book: + description: 'Address book mapping raw addresses to user-friendly forms for all addresses referenced in the response.' $ref: '#/components/schemas/AddressBook' metadata: + description: Token and indexing metadata for all addresses referenced in the response. $ref: '#/components/schemas/Metadata' nft_collections: type: array + description: Array of NFT collections matching the query filters. items: $ref: '#/components/schemas/NFTCollection' NFTItem: type: object + description: 'An NFT item belonging to a collection. Contains the item index, on-chain content metadata, current owner, + and sale/auction status. The `real_owner` field reflects the actual owner even when the item is held by a sale contract.' properties: address: type: string + description: Address of this NFT item contract. auction_contract_address: type: string + description: 'Address of the auction contract currently holding this item, if it is in an active auction.' code_hash: type: string + description: 'SHA-256 hash of the item contract code, hex encoded.' collection: + description: 'Full collection object this item belongs to, including collection metadata.' $ref: '#/components/schemas/NFTCollection' collection_address: type: string + description: Address of the parent NFT collection contract. content: type: object + description: 'On-chain item metadata as a key-value object. Standard fields include `name`, `description`, `image`, + and `attributes` (array of trait objects).' additionalProperties: true data_hash: type: string + description: 'SHA-256 hash of the item contract data, hex encoded.' index: type: string + description: 'Item index within its collection, as a decimal string. Items are numbered sequentially starting from + 0.' init: type: boolean + description: Whether the item contract has been initialized (deployed with code and data). Uninitialized items exist + as placeholders. last_transaction_lt: type: string + description: Logical time of the most recent transaction on this item contract. example: '0' on_sale: type: boolean + description: Whether this item is currently listed for sale or auction on a marketplace. owner_address: type: string + description: 'Address of the current owner. When the item is on sale, this may be the sale contract address rather + than the real owner.' real_owner: type: string + description: 'Actual owner of the item, resolved through sale/auction contracts. Unlike `owner_address`, this always + reflects the true owner even when the item is held by a marketplace contract.' sale_contract_address: type: string + description: 'Address of the sale contract currently holding this item, if it is listed for fixed-price sale.' NFTItemsResponse: type: object + description: Response wrapper containing NFT items with address book and token metadata. properties: address_book: + description: 'Address book mapping raw addresses to user-friendly forms for all addresses referenced in the response.' $ref: '#/components/schemas/AddressBook' metadata: + description: Token and indexing metadata for all addresses referenced in the response. $ref: '#/components/schemas/Metadata' nft_items: type: array + description: Array of NFT items matching the query filters. items: $ref: '#/components/schemas/NFTItem' NFTTransfer: type: object + description: 'An NFT transfer event representing an ownership change. Contains the old and new owner addresses, optional + forward and custom payloads, and a reference to the on-chain transaction.' properties: custom_payload: type: string + description: 'Optional custom payload attached to the transfer, base64-encoded BOC.' decoded_custom_payload: type: array + description: Decoded custom payload as a raw byte array. Present when the payload could be parsed. items: type: integer decoded_forward_payload: type: array + description: Decoded forward payload as a raw byte array. Present when the payload could be parsed. items: type: integer forward_amount: type: string + description: 'Amount of TON forwarded to the new owner along with the ownership notification, in nanotons.' forward_payload: type: string + description: 'Payload forwarded to the new owner along with the transfer notification, base64-encoded BOC.' new_owner: type: string + description: Address of the new owner after the transfer. nft_address: type: string + description: Address of the NFT item contract that was transferred. nft_collection: type: string + description: 'Address of the parent NFT collection, if the item belongs to one.' old_owner: type: string + description: Address of the previous owner before the transfer. query_id: type: string + description: 'Query ID specified by the sender for matching request/response messages. A 64-bit integer as a decimal + string.' response_destination: type: string + description: Address that will receive the excess TON remaining after the transfer notification is processed. trace_id: type: string + description: Identifier of the execution trace containing this transfer event. transaction_aborted: type: boolean + description: 'Whether the transaction containing this transfer was aborted. If `true`, the transfer did not actually + take effect.' transaction_hash: type: string + description: 'Hash of the on-chain transaction containing this transfer event.' transaction_lt: type: string + description: Logical time of the transaction containing this transfer. Higher values are more recent. example: '0' transaction_now: type: integer + description: Unix timestamp (seconds since epoch) of the transaction containing this transfer. NFTTransfersResponse: type: object + description: Response wrapper containing NFT transfer events with address book and token metadata. properties: address_book: + description: 'Address book mapping raw addresses to user-friendly forms for all addresses referenced in the response.' $ref: '#/components/schemas/AddressBook' metadata: + description: Token and indexing metadata for all addresses referenced in the response. $ref: '#/components/schemas/Metadata' nft_transfers: type: array + description: Array of NFT transfer events matching the query filters. items: $ref: '#/components/schemas/NFTTransfer' RequestError: type: object + description: 'Error response returned when a request fails. Contains the HTTP status code and a human-readable error + message describing what went wrong.' properties: code: type: integer + description: 'HTTP status code indicating the error category: `401` (missing required field), `404` (data not found), + `409` (resource exists but wrong type), `422` (invalid parameters), `500` (server failure).' error: type: string + description: 'Human-readable error message describing what went wrong and how to fix it.' SplitInfo: type: object + description: Shard split/merge information included in transactions that occur during shard reconfiguration. Contains + the split depth and addresses of the current and sibling shards. properties: acc_split_depth: type: integer + description: Account split depth determining how accounts are distributed between the two shards after a split. cur_shard_pfx_len: type: integer + description: Current shard prefix bit length. Longer prefixes mean more granular sharding. sibling_addr: type: string + description: Address prefix of the sibling shard (the other half after a split). this_addr: type: string + description: Address prefix of this shard. StoragePhase: type: object + description: 'Details of the storage phase during transaction execution. In this phase, storage fees are deducted from + the account balance based on how much on-chain storage the contract uses and how long since the last transaction.' properties: status_change: type: string + description: 'Account status change resulting from the storage phase. If storage fees exceed the balance, the account + may be frozen.' storage_fees_collected: type: string + description: 'Storage fees successfully collected from the account balance, in nanotons. Based on the size of on-chain + state and time since the last transaction.' example: '0' storage_fees_due: type: string + description: 'Storage fees that are still owed but could not be collected due to insufficient balance, in nanotons. + If non-zero, the account may be frozen.' example: '0' TokenInfo: type: object + description: 'Token metadata for a Jetton or NFT contract. Contains the human-readable name, ticker symbol, image URL, + description, and token type. The `valid` flag indicates whether the metadata was successfully parsed from the on-chain + content.' properties: description: type: string + description: 'Human-readable description of the token, from on-chain metadata.' extra: type: object + description: Additional token metadata fields beyond the standard set. Structure varies by token. additionalProperties: true image: type: string + description: 'URL or on-chain reference to the token image. May be an HTTPS URL, IPFS URI, or on-chain data reference.' name: type: string + description: 'Token name from on-chain metadata (e.g., `Tether USD`, `TON Punks`).' nft_index: type: string + description: Item index within the parent collection. Present only for NFT items. symbol: type: string + description: 'Token ticker symbol from on-chain metadata (e.g., `USDT`, `STON`).' type: type: string + description: 'Token contract type: `jetton_masters` (fungible token root), `jetton_wallets` (individual token balance), + `nft_collections` (NFT collection), or `nft_items` (individual NFT).' valid: type: boolean + description: 'Whether the token metadata was successfully parsed from the on-chain content. If `false`, the name/symbol/image + fields may be missing or unreliable.' Trace: type: object + description: 'A full execution trace representing the complete message chain triggered by a single external message. + The trace tree shows how one inbound message fans out into multiple transactions across different contracts. Contains + timing, the root trace node, all transactions, and optionally parsed high-level actions.' properties: actions: type: array + description: 'Array of parsed high-level actions derived from this trace (e.g., transfers, swaps). Only populated + when `include_actions=true` in the request.' items: $ref: '#/components/schemas/Action' end_lt: type: string + description: Logical time when the last transaction in this trace was finalized. example: '0' end_utime: type: integer + description: Unix timestamp (seconds since epoch) when the last transaction in this trace was finalized. external_hash: type: string + description: Hash of the external inbound message that initiated this entire trace. Use this to find the original + message that started the chain. is_incomplete: type: boolean + description: 'Whether the trace is incomplete — some transactions in the chain may be missing from the index. This + can happen for very recent traces or during indexer catch-up.' mc_seqno_end: type: string + description: Masterchain block sequence number in which the last transaction of this trace was committed. mc_seqno_start: type: string + description: Masterchain block sequence number in which the first transaction of this trace was committed. start_lt: type: string + description: Logical time when the first transaction in this trace was created. example: '0' start_utime: type: integer + description: Unix timestamp (seconds since epoch) when the first transaction in this trace was created. trace: + description: Root node of the trace tree. Walk this tree to follow the full execution flow from the initial external + message through all resulting internal messages and transactions. $ref: '#/components/schemas/TraceNode' trace_id: type: string + description: 'Unique identifier for this trace. All transactions, messages, and actions within the same execution + chain share this ID.' trace_info: + description: 'Processing metadata including trace state (complete/pending), classification state, and message/transaction + counts.' $ref: '#/components/schemas/TraceMeta' transactions: type: object + description: 'Map of transaction hashes to full transaction objects for all transactions in this trace. Keys are + hex-encoded transaction hashes.' additionalProperties: $ref: '#/components/schemas/Transaction' transactions_order: type: array + description: Ordered list of transaction hashes reflecting the execution sequence. Process transactions in this + order to replay the trace chronologically. items: type: string warning: type: string + description: 'Warning message if any issues were detected during trace processing (e.g., missing transactions, unexpected + state).' TraceMeta: type: object + description: 'Processing metadata for a trace. Reports the current state of trace processing (complete, pending, etc.), + the classification state (whether actions were parsed), and counts of total and pending messages.' properties: classification_state: type: string + description: 'Whether the trace has been classified into high-level actions: `classified` (actions parsed), `unclassified` + (raw transactions only), or `failed` (classification attempted but failed).' messages: type: integer + description: 'Total number of messages in the trace, including the initial external message and all resulting internal + messages.' pending_messages: type: integer + description: 'Number of messages that have been sent but whose resulting transactions have not yet been indexed. + A value of `0` means the trace is fully processed.' trace_state: type: string + description: 'Current processing state of the trace: `complete` (all transactions indexed), `pending` (still waiting + for some transactions), or `unknown`.' transactions: type: integer + description: Total number of transactions in the trace. TraceNode: type: object + description: 'A single node in the trace tree. Each node represents one transaction triggered by an inbound message, + plus references to child nodes for any outbound messages that triggered further transactions. Walking the tree from + root to leaves shows the full execution flow.' properties: children: type: array + description: 'Child trace nodes, one per outbound message from this transaction that triggered a subsequent transaction. + An empty array means this is a leaf node (no further execution).' items: $ref: '#/components/schemas/TraceNode' in_msg: + description: 'The inbound message that triggered the transaction at this node. Contains the source, destination, + value, and body.' $ref: '#/components/schemas/Message' in_msg_hash: type: string + description: 'Hash of the inbound message, hex encoded.' transaction: + description: The full transaction object at this node. $ref: '#/components/schemas/Transaction' tx_hash: type: string + description: 'Hash of the transaction at this node, hex encoded.' TracesResponse: type: object + description: Response wrapper containing traces with address book and token metadata. properties: address_book: + description: 'Address book mapping raw addresses to user-friendly forms for all addresses referenced in the response.' $ref: '#/components/schemas/AddressBook' metadata: + description: Token and indexing metadata for all addresses referenced in the response. $ref: '#/components/schemas/Metadata' traces: type: array + description: Array of traces matching the query filters. items: $ref: '#/components/schemas/Trace' Transaction: type: object + description: 'A transaction on the TON blockchain. A transaction is the result of delivering one inbound message to + an account: the TVM executes the contract code, which may produce outbound messages, change the account state, and + consume fees. Contains the full execution record including all phases (storage, credit, compute, action, bounce), + inbound and outbound messages, and before/after account states.' properties: account: type: string + description: 'Address of the account that executed this transaction, in raw format.' account_state_after: + description: 'Account state snapshot after this transaction was executed. Compare with `account_state_before` to + see what changed.' $ref: '#/components/schemas/AccountState' account_state_before: + description: Account state snapshot before this transaction was executed. $ref: '#/components/schemas/AccountState' block_ref: + description: 'Reference to the block (workchain, shard, seqno) that contains this transaction.' $ref: '#/components/schemas/BlockId' description: + description: 'Detailed execution description broken down into phases: storage (fee collection), credit (value transfer), + compute (TVM execution), action (message creation), and bounce (error handling).' $ref: '#/components/schemas/TransactionDescr' emulated: type: boolean + description: 'Whether this transaction was emulated (simulated locally) rather than committed on-chain. Emulated + transactions appear in pending endpoints.' end_status: type: string + description: 'Account lifecycle status after the transaction: `uninit`, `active`, or `frozen`.' hash: type: string + description: 'SHA-256 hash of the transaction, hex encoded. Uniquely identifies this transaction on the blockchain.' in_msg: + description: 'The inbound message that triggered this transaction. Contains the sender, value, and message body. + External messages have an empty source address.' $ref: '#/components/schemas/Message' lt: type: string + description: 'Logical time of this transaction. A globally unique counter ordering all events on the blockchain. + Use together with `hash` for pagination: pass both as starting point to the transactions endpoint to fetch the + next page.' example: '0' mc_block_seqno: type: integer + description: Masterchain block sequence number associated with this transaction. The masterchain block that committed + the shard block containing this transaction. now: type: integer + description: Unix timestamp (seconds since epoch) when this transaction was created. orig_status: type: string + description: 'Account lifecycle status before the transaction: `uninit`, `active`, or `frozen`.' out_msgs: type: array + description: 'Array of outbound messages created by this transaction. Each message may trigger further transactions + on other accounts, forming an execution trace.' items: $ref: '#/components/schemas/Message' prev_trans_hash: type: string + description: Hash of the previous transaction on this same account. Use this to walk the account's transaction history + backward. prev_trans_lt: type: string + description: Logical time of the previous transaction on this same account. example: '0' total_fees: type: string + description: 'Total fees charged for this transaction in nanotons. Sum of storage fees, gas fees, forwarding fees, + and action fees.' example: '0' total_fees_extra_currencies: type: object + description: Map of extra currency IDs to fee amounts charged in those currencies. Usually empty — fees are almost + always paid in TON. additionalProperties: type: string trace_external_hash: type: string + description: Hash of the external inbound message that initiated the entire execution trace containing this transaction. trace_id: type: string + description: 'Identifier of the execution trace this transaction belongs to. All transactions triggered by the same + external message share the same `trace_id`.' TransactionDescr: type: object + description: 'Detailed description of how a transaction was executed, broken down into phases. Each phase is optional + depending on the transaction type. Ordinary transactions go through storage, credit, compute, and action phases. Tick/tock + transactions skip credit. Bounce occurs only when a bounced message is being processed.' properties: aborted: type: boolean + description: Whether the transaction was aborted. An aborted transaction still pays fees but does not commit state + changes or send outbound messages. action: + description: 'Action phase details: how many outbound messages were created, total forwarding fees, and whether + any actions failed.' $ref: '#/components/schemas/ActionPhase' bounce: + description: Bounce phase details. Present only when processing a bounced message or when a message with the bounce + flag fails and a bounce reply is generated. $ref: '#/components/schemas/BouncePhase' compute_ph: + description: 'Compute phase details: TVM execution results including gas used, exit code, and step count.' $ref: '#/components/schemas/ComputePhase' credit_first: type: boolean + description: 'Whether the credit phase ran before the compute phase. `true` for ordinary transactions (value credited + first, then executed), `false` for bounce transactions.' credit_ph: + description: 'Credit phase details: how much TON and extra currency was credited to the account from the inbound + message.' $ref: '#/components/schemas/CreditPhase' destroyed: type: boolean + description: 'Whether the account was destroyed (deleted from the blockchain state) after this transaction. Occurs + when the balance reaches zero and the contract self-destructs.' installed: type: boolean + description: 'Whether new code was installed on the account during this transaction (contract deployment or code + upgrade via `SETCODE`).' is_tock: type: boolean + description: 'Whether this is a tock transaction. Tick and tock are special transactions on masterchain system contracts + that run automatically every block. `true` = tock, `false` = tick.' split_info: + description: Shard split/merge information. Present only in special transactions during shard reconfiguration. $ref: '#/components/schemas/SplitInfo' storage_ph: + description: 'Storage phase details: how much storage fee was collected and whether the account status changed (e.g., + frozen due to insufficient balance).' $ref: '#/components/schemas/StoragePhase' type: type: string + description: 'Transaction type: `ordinary` (triggered by a message), `tick_tock` (automatic system transaction), + `split_prepare`/`split_install` (shard splitting), or `merge_prepare`/`merge_install` (shard merging).' TransactionsResponse: type: object + description: Response wrapper containing transactions with address book. properties: address_book: + description: 'Address book mapping raw addresses to user-friendly forms for all addresses referenced in the response.' $ref: '#/components/schemas/AddressBook' transactions: type: array + description: Array of transactions matching the query filters. items: $ref: '#/components/schemas/Transaction' V2AddressInformation: type: object + description: 'Account information in the v2 API-compatible format. Returns balance, contract code and data as base64-encoded + BOCs, account status, and last transaction reference.' properties: balance: type: string + description: 'Account balance in nanotons. 1 TON = 1,000,000,000 nanotons.' code: type: string + description: 'Smart contract code in BOC format, base64 encoded. Empty string if the account is uninitialized.' data: type: string + description: 'Smart contract persistent storage in BOC format, base64 encoded. Empty string if the account is uninitialized.' frozen_hash: type: string + description: Hash of the frozen state. Present only when the account is frozen. last_transaction_hash: type: string + description: 'Hash of the most recent transaction on this account. Use together with `last_transaction_lt` to start + paginating transaction history.' last_transaction_lt: type: string + description: Logical time of the most recent transaction. A globally unique counter ordering all blockchain events. status: type: string + description: 'Account lifecycle status: `uninit`, `active`, or `frozen`.' V2EstimateFeeRequest: type: object + description: 'Request body for fee estimation. Provide the target address, base64-encoded message body, and optionally + init code and init data (for contract deployment messages). Set `ignore_chksig` to `true` to skip signature verification + when you don''t have a real signature yet.' properties: address: type: string + description: Target account address that will receive and process the message. body: type: string + description: 'Message body in BOC format, base64 encoded. Contains the operation to be executed.' ignore_chksig: type: boolean + description: 'Set to `true` to skip signature verification during fee estimation. Useful when estimating fees before + signing the message.' init_code: type: string + description: 'Contract code for deployment messages, BOC format, base64 encoded. Required when deploying a new contract; + omit for regular transfers.' init_data: type: string + description: 'Initial contract storage for deployment, BOC format, base64 encoded. Required when deploying a new + contract; omit for regular transfers.' V2EstimateFeeResult: type: object + description: 'Fee estimation result with separate breakdowns for the sending account (source) and receiving account(s) + (destination). Each breakdown includes forwarding, gas, inbound forwarding, and storage fees in nanotons.' properties: destination_fees: type: array + description: 'Array of fee breakdowns charged on the receiving account(s). One entry per destination in multi-hop + transactions.' items: $ref: '#/components/schemas/V2EstimatedFee' source_fees: + description: Fees charged on the sending account. $ref: '#/components/schemas/V2EstimatedFee' V2EstimatedFee: type: object + description: 'Individual fee breakdown showing the four fee components: inbound message forwarding fee (`in_fwd_fee`), + storage fee for contract state (`storage_fee`), computation gas fee (`gas_fee`), and outbound message forwarding fee + (`fwd_fee`). All values are in nanotons.' properties: fwd_fee: type: integer + description: 'Fee for forwarding outbound messages created by this transaction, in nanotons.' gas_fee: type: integer + description: 'Computation gas fee for executing contract code, in nanotons.' in_fwd_fee: type: integer + description: 'Fee for importing the inbound message into the destination shard, in nanotons.' storage_fee: type: integer + description: 'Storage fee charged for keeping the contract state on-chain, in nanotons. Based on the size of code + + data cells and time since the last transaction.' V2RunGetMethodRequest: type: object + description: 'Request body for executing a smart contract get method. Provide the contract address, method name, and + optional input stack. Stack entries support `num` (hex string), `cell` (base64 BOC), and `slice` (base64 BOC) types.' properties: address: type: string + description: Address of the smart contract to execute the get method on. method: type: string + description: 'Name of the get method to execute (e.g., `seqno`, `get_wallet_data`, `get_nft_data`).' stack: type: array + description: 'Input stack entries for the get method. Each entry has a `type` (`num`, `cell`, or `slice`) and a + `value` in the corresponding format.' items: $ref: '#/components/schemas/V2StackEntity' V2SendMessageRequest: type: object + description: 'Request body for sending an external message to the TON network. The `boc` field must contain a valid + serialized external message in base64-encoded BOC format, including the destination address and a valid signature.' properties: boc: type: string + description: 'Serialized external message in BOC format, base64 encoded. Must contain a valid destination address, + signature, and message body.' V2SendMessageResult: type: object + description: 'Result of successfully submitting an external message. Contains the message hash (for looking up the message) + and the normalized hash (stable across re-serializations).' properties: message_hash: type: string + description: 'Hash of the submitted message, hex encoded. Use this to track the message status via the messages + or traces endpoints.' message_hash_norm: type: string + description: 'Normalized hash of the submitted message, stable across re-serializations. Use this for reliable message + lookups.' V2StackEntity: type: object + description: 'A single TVM stack entry used as input or output for get methods. The `type` field determines the format + of `value`: `num` uses a hex string (e.g., `0x12a`), `cell` and `slice` use base64-encoded BOC.' properties: type: type: string - value: {} + description: 'Stack entry type: `num` (integer as hex string, e.g., `0x12a`), `cell` (BOC as base64 string), or + `slice` (BOC as base64 string).' + value: + description: 'Stack entry value. Format depends on `type`: hex string for `num` (e.g., `0x12a`), base64-encoded + BOC for `cell` and `slice`.' V2WalletInformation: type: object + description: 'Wallet-specific information in the v2 API-compatible format. Extends basic account information with wallet-specific + fields: detected wallet version, current sequence number (needed for constructing transactions), and subwallet ID.' properties: balance: type: string + description: 'Wallet balance in nanotons. 1 TON = 1,000,000,000 nanotons.' last_transaction_hash: type: string + description: Hash of the most recent transaction on this wallet. last_transaction_lt: type: string + description: Logical time of the most recent transaction on this wallet. seqno: type: integer + description: 'Current wallet sequence number. Used for replay protection: each outgoing transaction must include + the current `seqno`, which increments by 1 after each transaction. Always fetch the current value before sending + a transaction.' status: type: string + description: 'Account lifecycle status: `uninit`, `active`, or `frozen`.' wallet_id: type: integer + description: 'Subwallet ID. Allows creating multiple independent wallets from a single key pair. The default value + is `698983191` (`0x29a9a317`).' wallet_type: type: string + description: 'Detected wallet contract version (e.g., `wallet_v3r2`, `wallet_v4r2`, `wallet_v5r1`). Determines which + message format and features are supported.' VestingContractsResponse: type: object + description: Response wrapper containing vesting contracts with address book. properties: address_book: + description: 'Address book mapping raw addresses to user-friendly forms for all addresses referenced in the response.' $ref: '#/components/schemas/AddressBook' vesting_contracts: type: array + description: Array of vesting contracts matching the query filters. items: $ref: '#/components/schemas/index.VestingInfo' WalletState: type: object + description: 'Wallet state combining account information with wallet-specific detection. The `is_wallet` flag indicates + whether the address is a recognized wallet contract. For wallets, includes the detected version, current `seqno`, + subwallet ID, and signature permissions.' properties: address: type: string + description: 'Account address in raw format (`workchain:hex`).' balance: type: string + description: 'Account balance in nanotons. 1 TON = 1,000,000,000 nanotons.' code_hash: type: string + description: 'SHA-256 hash of the contract code, hex encoded. Use this to identify the contract type.' extra_currencies: type: object + description: 'Map of extra currency balances held by this account. Keys are currency IDs, values are amounts as + decimal strings.' additionalProperties: type: string is_signature_allowed: type: boolean + description: 'Whether the wallet allows external messages without valid signatures. When `false`, the wallet only + accepts pre-authorized messages (e.g., gasless transactions via a relayer).' is_wallet: type: boolean + description: 'Whether this address is a recognized wallet contract. When `false`, the wallet-specific fields (`wallet_type`, + `seqno`, `wallet_id`) should be ignored.' last_transaction_hash: type: string + description: Hash of the most recent transaction on this account. last_transaction_lt: type: string + description: Logical time of the most recent transaction. Use for ordering and pagination. example: '0' seqno: type: integer + description: 'Current wallet sequence number. Each outgoing transaction must include the current `seqno`, which + increments by 1 after each transaction. Always fetch before sending.' status: type: string + description: 'Account lifecycle status: `uninit` (no contract deployed), `active` (contract running), or `frozen` + (suspended due to zero balance).' wallet_id: type: integer + description: Subwallet ID. Allows creating multiple independent wallets from a single key pair. wallet_type: type: string + description: 'Detected wallet contract version (e.g., `wallet_v3r2`, `wallet_v4r2`, `wallet_v5r1`).' WalletStatesResponse: type: object + description: Response wrapper containing wallet states with address book and token metadata. properties: address_book: + description: 'Address book mapping raw addresses to user-friendly forms for all addresses referenced in the response.' $ref: '#/components/schemas/AddressBook' metadata: + description: Token and indexing metadata for all addresses referenced in the response. $ref: '#/components/schemas/Metadata' wallets: type: array + description: 'Array of wallet states, one per requested address.' items: $ref: '#/components/schemas/WalletState' OrderAction: type: object + description: 'A single action within a multisig order. Represents one outbound message to be sent when the order is + executed. Contains the destination, TON value, send mode flags, and the parsed message body (if decoding succeeded).' properties: body_raw: type: array + description: Raw message body as a byte array (list of integers). Present when the body could not be parsed into + a known type. items: type: integer destination: type: string + description: Destination address that will receive this message when the order is executed. error: type: string + description: 'Error message explaining why parsing failed. Present only when `parsed` is `false`.' parsed: type: boolean - parsed_body: {} + description: 'Whether the action''s message body was successfully decoded into a known type. When `false`, check + `body_raw` for the raw data and `error` for the reason.' + parsed_body: + description: 'Parsed message body as a structured object with named fields. The structure depends on `parsed_body_type`. + Only present when `parsed` is `true`.' parsed_body_type: type: string + description: 'Type identifier for the parsed body (e.g., `jetton_transfer`, `ton_transfer`, `nft_transfer`). Determines + the schema of `parsed_body`.' send_mode: type: integer + description: 'Message send mode flags (0-255). Controls how value and fees are handled: `1` = pay fees separately, + `64` = carry remaining value, `128` = carry entire balance. See [message modes](https://docs.ton.org/v3/documentation/smart-contracts/message-management/sending-messages#message-modes) + for details.' value: type: string + description: 'Amount of TON to send with this message, in nanotons.' VestingInfo: type: object + description: 'Vesting contract details describing a token lockup schedule. Tokens are locked for a cliff period, then + unlock gradually in fixed intervals until the total duration is reached. The whitelist restricts which addresses can + receive the unlocked funds.' properties: address: type: string + description: 'Address of the vesting contract on-chain.' cliff_duration: type: integer + description: 'Cliff duration in seconds. No tokens unlock before the cliff period ends. After the cliff, tokens + begin unlocking according to `unlock_period`.' owner_address: type: string + description: Address of the vesting beneficiary who will receive the unlocked tokens. sender_address: type: string + description: Address of the entity that created and funded the vesting contract. start_time: type: integer + description: Unix timestamp (seconds since epoch) when the vesting schedule begins. The cliff period starts from + this time. total_amount: type: string + description: 'Total amount of TON locked in the vesting contract, in nanotons.' total_duration: type: integer + description: 'Total vesting duration in seconds, measured from `start_time`. All tokens are fully unlocked when + `start_time + total_duration` is reached.' unlock_period: type: integer + description: 'Duration of each unlock interval in seconds. After the cliff, tokens unlock in equal portions every + `unlock_period` seconds.' whitelist: type: array + description: 'List of addresses the beneficiary is allowed to send unlocked funds to. If empty, the beneficiary + can send to any address.' items: type: string securitySchemes: APIKeyHeader: type: apiKey - name: X-Api-Key + name: 'X-Api-Key' in: header APIKeyQuery: type: apiKey name: api_key in: query + responses: + '401': + description: Missing required field. + content: + application/json: + schema: + $ref: '#/components/schemas/RequestError' + '404': + description: Requested data not found. + content: + application/json: + schema: + $ref: '#/components/schemas/RequestError' + '409': + description: Resource exists but is the wrong type. + content: + application/json: + schema: + $ref: '#/components/schemas/RequestError' + '422': + description: Invalid request parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/RequestError' + '500': + description: 'Server-side failure.' + content: + application/json: + schema: + $ref: '#/components/schemas/RequestError' \ No newline at end of file