diff --git a/.github/scripts/generate-emulate-api-table.py b/.github/scripts/generate-emulate-api-table.py new file mode 100644 index 000000000..45a5fe48f --- /dev/null +++ b/.github/scripts/generate-emulate-api-table.py @@ -0,0 +1,65 @@ +import json +import re +from pathlib import Path + + +SPEC_PATH = "content/api/emulate.json" +MDX_PATH = "content/api/emulate/overview.mdx" +MARKER = "API_EMULATE_ENDPOINTS" +LINK_BASE = "/api/emulate" +API_BASE = "/api/emulate/v1" + + +def slugify(value: str) -> str: + slug = re.sub(r"[^a-z0-9\s-]", "", value.lower()) + slug = re.sub(r"\s+", "-", slug) + return re.sub(r"-+", "-", slug).strip("-") + + +def generate_table(spec: dict) -> str: + lines = [ + "| Category | Method | Description |", + "| -------- | ------ | ----------- |", + ] + + for path, path_item in spec["paths"].items(): + for method in ["get", "post", "put", "patch", "delete"]: + if method not in path_item: + continue + + operation = path_item[method] + tag = operation["tags"][0] + summary = operation["summary"] + description = operation["description"] + link = f"{LINK_BASE}/{slugify(tag)}/{slugify(summary)}" + method_display = f"[`{method.upper()} {path.removeprefix(API_BASE)}`]({link})" + lines.append(f"| {tag} | {method_display} | {description} |") + + return "\n".join(lines) + + +def main(): + repo_root = Path(__file__).resolve().parents[2] + spec = json.loads((repo_root / SPEC_PATH).read_text()) + mdx_path = repo_root / MDX_PATH + content = mdx_path.read_text() + table = generate_table(spec) + pattern = rf"(\{{/\* BEGIN_AUTO_GENERATED: {MARKER} \*/\}})[ \t]*\n.*?(\{{/\* END_AUTO_GENERATED: {MARKER} \*/\}})" + new_content, count = re.subn( + pattern, + lambda match: f"{match[1]}\n{table}\n{match[2]}", + content, + flags=re.DOTALL, + ) + if count != 1: + raise ValueError(f"Expected one {MARKER} marker block in {MDX_PATH}") + + if new_content != content: + mdx_path.write_text(new_content) + print(f"Updated {MDX_PATH}") + else: + print(f"No changes needed in {MDX_PATH}") + + +if __name__ == "__main__": + main() diff --git a/.github/scripts/generate-openapi-pages.mjs b/.github/scripts/generate-openapi-pages.mjs index 0bcf26ec1..069bf216c 100644 --- a/.github/scripts/generate-openapi-pages.mjs +++ b/.github/scripts/generate-openapi-pages.mjs @@ -57,5 +57,20 @@ const genV3 = async () => name: (path) => commonNameTransform(path.info.title), }); +const genEmulate = async () => + await generateFiles({ + ...commonConfig, + input: createOpenAPI({ + input: { + emulate: path.resolve('./content/api/emulate.json'), + }, + }), + output: path.resolve('./content/api/emulate'), + per: 'operation', + groupBy: 'tag', + name: (path) => commonNameTransform(path.info.title), + }); + await genV2(); await genV3(); +await genEmulate(); diff --git a/.remarkignore b/.remarkignore index 9b7719ee5..96df63266 100644 --- a/.remarkignore +++ b/.remarkignore @@ -19,6 +19,7 @@ node_modules/ /content/tvm/instructions.mdx /content/api/v2/ /content/api/v3/ +/content/api/emulate/ # Ignore some other files /content/index.mdx diff --git a/content/api/emulate.json b/content/api/emulate.json new file mode 100644 index 000000000..d5652be5e --- /dev/null +++ b/content/api/emulate.json @@ -0,0 +1,385 @@ +{ + "openapi": "3.1.1", + "info": { + "description": "Emulate transactions and traces before sending messages to the TON blockchain.", + "title": "TON Emulate API", + "contact": {}, + "version": "0.0.1" + }, + "servers": [ + { + "url": "https://toncenter.com", + "description": "TON Mainnet" + }, + { + "url": "https://testnet.toncenter.com", + "description": "TON Testnet" + } + ], + "paths": { + "/api/emulate/v1/emulateTonConnect": { + "post": { + "tags": [ + "Traces" + ], + "summary": "Emulate TON Connect trace", + "description": "Emulate a trace by composing an external message from a TON Connect request.", + "operationId": "emulateTonConnect", + "parameters": [ + { + "name": "X-Actions-Version", + "in": "header", + "description": "Supported actions version used when classifying the emulated trace.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "description": "TON Connect emulation request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TonConnectEmulateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Emulated trace and transactions, with optional actions, code, data, address book, and metadata.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EmulateTraceResponse" + } + } + } + }, + "400": { + "description": "Invalid request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EmulateError" + } + } + } + }, + "500": { + "description": "Emulation or result processing failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EmulateError" + } + } + } + } + } + } + }, + "/api/emulate/v1/emulateTrace": { + "post": { + "tags": [ + "Traces" + ], + "summary": "Emulate trace", + "description": "Emulate a trace from an external message serialized as a base64-encoded BoC.", + "operationId": "emulateTrace", + "parameters": [ + { + "name": "X-Actions-Version", + "in": "header", + "description": "Supported actions version used when classifying the emulated trace.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "description": "External message emulation request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EmulateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Emulated trace and transactions, with optional actions, code, data, address book, and metadata.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EmulateTraceResponse" + } + } + } + }, + "400": { + "description": "Invalid request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EmulateError" + } + } + } + }, + "500": { + "description": "Emulation or result processing failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EmulateError" + } + } + } + } + } + } + } + }, + "tags": [ + { + "name": "Traces", + "description": "Trace emulation for external messages and TON Connect requests." + } + ], + "components": { + "schemas": { + "EmulateRequest": { + "type": "object", + "properties": { + "boc": { + "type": "string", + "description": "External message serialized as a base64-encoded BoC.", + "minLength": 1 + }, + "ignore_chksig": { + "type": "boolean", + "example": false, + "default": false, + "description": "Skip signature checks during emulation." + }, + "include_code_data": { + "type": "boolean", + "example": false, + "default": false, + "description": "Include contract code and data cells in the response." + }, + "include_address_book": { + "type": "boolean", + "example": false, + "default": false, + "description": "Include address book entries. Requires address book support on the server." + }, + "include_metadata": { + "type": "boolean", + "example": false, + "default": false, + "description": "Include account metadata. Requires metadata support on the server." + }, + "with_actions": { + "type": "boolean", + "example": false, + "default": false, + "description": "Classify the emulated trace into actions." + }, + "mc_block_seqno": { + "type": [ + "integer", + "null" + ], + "example": null, + "description": "Masterchain block sequence number used for emulation. If omitted or null, use the latest available state.", + "minimum": 0, + "maximum": 4294967295 + } + }, + "required": [ + "boc" + ] + }, + "TonConnectEmulateRequest": { + "type": "object", + "properties": { + "from": { + "type": "string", + "example": "EQB3ncyBUTjZUA5EnFKR5_EnOMI9V1tTEAAPaiU71gc4TiUt", + "description": "Wallet address from which to compose the external message.", + "minLength": 1 + }, + "messages": { + "type": "array", + "items": { + "type": "object", + "properties": { + "address": { + "type": "string", + "example": "EQB3ncyBUTjZUA5EnFKR5_EnOMI9V1tTEAAPaiU71gc4TiUt", + "description": "Destination account address.", + "minLength": 1 + }, + "amount": { + "type": "string", + "example": "1000000000", + "description": "Amount to send, in nanograms, as a decimal string.", + "pattern": "^[0-9]+$" + }, + "payload": { + "type": [ + "string", + "null" + ], + "description": "Message body serialized as a base64-encoded BoC. Optional." + }, + "stateInit": { + "type": [ + "string", + "null" + ], + "example": null, + "description": "Contract initial state serialized as a base64-encoded BoC. Optional." + } + }, + "required": [ + "address", + "amount" + ] + }, + "description": "Internal messages to include in the wallet request.", + "minItems": 1, + "maxItems": 4 + }, + "valid_until": { + "type": [ + "integer", + "null" + ], + "example": null, + "description": "Expiration time of the wallet request as a Unix timestamp, in seconds.", + "minimum": 0 + }, + "include_code_data": { + "type": "boolean", + "example": false, + "default": false, + "description": "Include contract code and data cells in the response." + }, + "include_address_book": { + "type": "boolean", + "example": false, + "default": false, + "description": "Include address book entries. Requires address book support on the server." + }, + "include_metadata": { + "type": "boolean", + "example": false, + "default": false, + "description": "Include account metadata. Requires metadata support on the server." + }, + "with_actions": { + "type": "boolean", + "example": false, + "default": false, + "description": "Classify the emulated trace into actions." + }, + "mc_block_seqno": { + "type": [ + "integer", + "null" + ], + "example": null, + "description": "Masterchain block sequence number used for emulation. If omitted or null, use the latest available state.", + "minimum": 0, + "maximum": 4294967295 + } + }, + "required": [ + "from", + "messages" + ] + }, + "EmulateTraceResponse": { + "type": "object", + "required": [ + "mc_block_seqno", + "trace", + "transactions", + "rand_seed", + "is_incomplete" + ], + "properties": { + "mc_block_seqno": { + "type": "integer", + "minimum": 0, + "description": "Masterchain block sequence number used for emulation." + }, + "trace": { + "$ref": "./v3.yaml#/components/schemas/TraceNode", + "description": "Tree of emulated transactions." + }, + "transactions": { + "type": "object", + "description": "Emulated transactions keyed by transaction hash.", + "additionalProperties": { + "$ref": "./v3.yaml#/components/schemas/Transaction" + } + }, + "actions": { + "type": "array", + "description": "Actions classified from the emulated trace when requested.", + "items": { + "$ref": "./v3.yaml#/components/schemas/Action" + } + }, + "code_cells": { + "type": "object", + "description": "Base64-encoded contract code cells keyed by cell hash, when requested.", + "additionalProperties": { + "type": "string" + } + }, + "data_cells": { + "type": "object", + "description": "Base64-encoded contract data cells keyed by cell hash, when requested.", + "additionalProperties": { + "type": "string" + } + }, + "address_book": { + "$ref": "./v3.yaml#/components/schemas/AddressBook" + }, + "metadata": { + "$ref": "./v3.yaml#/components/schemas/Metadata" + }, + "rand_seed": { + "type": "string", + "description": "Random seed used for emulation." + }, + "is_incomplete": { + "type": "boolean", + "description": "Whether the trace exceeded the emulation depth limit." + } + } + }, + "EmulateError": { + "type": "object", + "required": [ + "error" + ], + "properties": { + "error": { + "type": "string", + "description": "Error description." + } + } + } + } + } +} diff --git a/content/api/emulate/meta.json b/content/api/emulate/meta.json new file mode 100644 index 000000000..402f2e76a --- /dev/null +++ b/content/api/emulate/meta.json @@ -0,0 +1,8 @@ +{ + "$schema": "../../../meta-schema.json", + "title": "Emulation API", + "pages": [ + "overview", + "..." + ] +} diff --git a/content/api/emulate/overview.mdx b/content/api/emulate/overview.mdx new file mode 100644 index 000000000..9ebe216c7 --- /dev/null +++ b/content/api/emulate/overview.mdx @@ -0,0 +1,59 @@ +--- +title: "TON Center Emulation API overview" +sidebarTitle: "Overview" +--- + +The TON Center Emulation API simulates execution of transactions and traces on the blockchain. Submit an external message or a TON Connect request to inspect the resulting transactions and optional actions. + +Emulation **does not** send messages to the blockchain. + +## Base URLs + +| Network | Base URL | +| ------- | ---------------------------------------------- | +| Mainnet | `https://toncenter.com/api/emulate/v1` | +| Testnet | `https://testnet.toncenter.com/api/emulate/v1` | + +## Endpoints + +{/* BEGIN_AUTO_GENERATED: API_EMULATE_ENDPOINTS */} +| Category | Method | Description | +| -------- | ------ | ----------- | +| Traces | [`POST /emulateTonConnect`](/api/emulate/traces/emulate-ton-connect-trace) | Emulate a trace by composing an external message from a TON Connect request. | +| Traces | [`POST /emulateTrace`](/api/emulate/traces/emulate-trace) | Emulate a trace from an external message serialized as a base64-encoded BoC. | +{/* END_AUTO_GENERATED: API_EMULATE_ENDPOINTS */} + +### Emulating a TON Connect request + +TON Connect emulation accepts one to four internal messages. The sending wallet must be deployed. Supported wallets are `v3r1`, `v3r2`, `v4r1`, `v4r2`, and [`v5r1`](/contracts/standard/wallets/v5). + +Replace `` with the sending wallet address and `` with the recipient address. The `amount` is a decimal string in nanograms: `1000000000` represents 1 GRAM. + +```bash +curl "https://testnet.toncenter.com/api/emulate/v1/emulateTonConnect" \ + -H "Content-Type: application/json" \ + --data '{ + "from": "", + "messages": [ + { + "address": "", + "amount": "1000000000" + } + ], + "with_actions": true + }' +``` + +## Results and options + +The response includes the masterchain block sequence number, a transaction tree in `trace`, a `transactions` map keyed by hash, and the random seed used for emulation. The boolean `is_incomplete` field indicates whether the trace exceeded the emulation depth limit. + +- Set `with_actions` to classify the trace into actions. Use `X-Actions-Version` to select the supported actions version. +- Set `include_code_data` to include contract code and data cells. +- Set `include_address_book` or `include_metadata` to include address book entries or account metadata. These options require server support. +- Set `mc_block_seqno` to select the masterchain state for emulation. If omitted or null, the server uses the latest available state. +- For external-message emulation, set `ignore_chksig` to skip signature checks. + + + Shared transaction, trace, action, address book, and metadata models follow [API v3](/api/v3/overview). + diff --git a/content/api/emulate/traces/emulate-ton-connect-trace.mdx b/content/api/emulate/traces/emulate-ton-connect-trace.mdx new file mode 100644 index 000000000..16deeb1bd --- /dev/null +++ b/content/api/emulate/traces/emulate-ton-connect-trace.mdx @@ -0,0 +1,31 @@ +--- +title: Emulate TON Connect trace +full: true +noindex: true +sidebarTitle: Emulate TON Connect trace +_openapi: + preload: + - emulate + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Emulate a trace by composing an external message from a TON Connect + request. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/emulate/traces/emulate-trace.mdx b/content/api/emulate/traces/emulate-trace.mdx new file mode 100644 index 000000000..df1623873 --- /dev/null +++ b/content/api/emulate/traces/emulate-trace.mdx @@ -0,0 +1,31 @@ +--- +title: Emulate trace +full: true +noindex: true +sidebarTitle: Emulate trace +_openapi: + preload: + - emulate + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Emulate a trace from an external message serialized as a base64-encoded + BoC. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/meta.json b/content/api/meta.json index 4dec87109..93cbcdb4d 100644 --- a/content/api/meta.json +++ b/content/api/meta.json @@ -9,6 +9,7 @@ "get-api-key", "v2", "v3", + "emulate", "streaming" ] } diff --git a/content/api/overview.mdx b/content/api/overview.mdx index 93e2c034b..875548255 100644 --- a/content/api/overview.mdx +++ b/content/api/overview.mdx @@ -70,6 +70,10 @@ TON Center is the official provider of HTTP APIs for TON: read blockchain data, + + Use the [Emulation API](/api/emulate/overview) to simulate transactions and traces before sending messages to the blockchain. + + ## References - [TON node and liteserver source](https://github.com/ton-blockchain/ton) diff --git a/content/api/v2.json b/content/api/v2.json index f69e809ac..7b083bca8 100644 --- a/content/api/v2.json +++ b/content/api/v2.json @@ -3,7 +3,7 @@ "info": { "title": "TON HTTP API C++", "description": "This API enables HTTP access to TON blockchain - getting accounts and wallets information, looking up blocks and transactions, sending messages to the blockchain, calling get methods of smart contracts, and more.\n\nIn addition to REST API, all methods are available through a JSON-RPC endpoint with `method` equal to method name and `params` passed as a dictionary.\n\nThe response contains a JSON object, which always has a boolean field `ok` and either `error` or `result`. If `ok` equals true, the request was successful and the result of the query can be found in the `result` field. In case of an unsuccessful request, `ok` equals false and the error is explained in the `error`.\n\nAPI Key should be sent either as `api_key` query parameter or `X-API-Key` header\n", - "version": "2.1.1" + "version": "v2.1.17-7e98895" }, "servers": [ { @@ -57,6 +57,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get address information", + "description": "Returns the current state of any account on the TON blockchain. Includes the balance (in nanograms), smart contract code and data (if deployed), account status, and a reference to the last transaction. This is the primary endpoint for checking if an address exists and what's deployed there.", + "operationId": "getAddressInformation_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddressInformationRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "The complete current state of the requested account.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddressInformationResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -75,7 +119,7 @@ "Accounts" ], "summary": "Get extended address information", - "description": "Returns detailed account information with parsed contract state. For wallet contracts, identifies the wallet version (v3, v4, v5) and extracts wallet-specific fields like `seqno` and public key. For other contracts, returns the raw state.", + "description": "Returns detailed account information with parsed contract state. For recognized contract types, returns type-specific state fields. For other contracts, returns the raw state.", "operationId": "getExtendedAddressInformation_get", "parameters": [ { @@ -110,6 +154,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get extended address information", + "description": "Returns detailed account information with parsed contract state. For recognized contract types, returns type-specific state fields. For other contracts, returns the raw state.", + "operationId": "getExtendedAddressInformation_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExtendedAddressInformationRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns detailed account information including parsed contract state and type.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExtendedAddressInformationResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -163,6 +251,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get wallet information", + "description": "Returns wallet-specific information for an address. If the address is a known wallet contract, returns the wallet type, current `seqno` (needed for sending transactions), and `wallet_id`. Always check `wallet: true` before using wallet-specific fields. Call this before sending any transaction to get the current `seqno`.", + "operationId": "getWalletInformation_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WalletInformationRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns wallet-specific details: type, `seqno`, subwallet ID, and balance.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WalletInformationResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -216,6 +348,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get address balance", + "description": "Returns the GRAM balance of an account in nanograms. 1 GRAM = 1,000,000,000 nanograms. A lightweight endpoint that returns only the balance without contract code, data, or other account details. Returns \"0\" for addresses that have never received any funds.", + "operationId": "getAddressBalance_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddressBalanceRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns the account balance in nanograms.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddressBalanceResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -234,7 +410,7 @@ "Accounts" ], "summary": "Get address state", - "description": "Returns the lifecycle state of an account. Possible values: `uninitialized` (address has no deployed contract but can receive GRAM), `active` (contract is deployed and working), `frozen` (contract suspended due to zero balance, send GRAM to unfreeze). Refer to the [account lifecycle states documentation](/foundations/status) for details. Check this before interacting with a contract.", + "description": "Returns the lifecycle state of an account. Possible values: `uninitialized` (address has no deployed contract but can receive GRAM), `active` (contract is deployed and working), `frozen` (contract state frozen). Refer to the [account lifecycle states documentation](/foundations/status) for details. Check this before interacting with a contract.", "operationId": "getAddressState_get", "parameters": [ { @@ -246,7 +422,7 @@ ], "responses": { "200": { - "description": "Returns the account lifecycle state: `uninit`, `active`, or `frozen`. Refer to the [account lifecycle states documentation](/foundations/status) for details.", + "description": "Returns the account lifecycle state: `uninitialized`, `active`, or `frozen`. Refer to the [account lifecycle states documentation](/foundations/status) for details.", "content": { "application/json": { "schema": { @@ -269,6 +445,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get address state", + "description": "Returns the lifecycle state of an account. Possible values: `uninitialized` (address has no deployed contract but can receive GRAM), `active` (contract is deployed and working), `frozen` (contract state frozen). Refer to the [account lifecycle states documentation](/foundations/status) for details. Check this before interacting with a contract.", + "operationId": "getAddressState_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddressStateRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns the account lifecycle state: `uninitialized`, `active`, or `frozen`. Refer to the [account lifecycle states documentation](/foundations/status) for details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddressStateResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -325,6 +545,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get token data", + "description": "Returns metadata for Jetton or NFT contracts. Automatically detects the contract type and returns appropriate fields. For Jetton masters: total supply, admin, metadata. For Jetton wallets: balance, owner. For NFT items: collection, owner, content. For NFT collections: item count, metadata.", + "operationId": "getTokenData_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TokenDataRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns parsed token metadata for Jetton masters, Jetton wallets, NFT collections, and NFT items.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TokenDataResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -396,6 +660,9 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -406,28 +673,69 @@ "APIKeyQuery": [] } ] - } - }, - "/api/v2/getBlockTransactionsExt": { - "get": { + }, + "post": { "tags": [ - "Transactions" + "RPC" ], - "summary": "Get block transactions (extended)", - "description": "Returns full transaction objects for all transactions in a specific block. Each transaction includes complete data: inbound and outbound messages, fees, state changes, and BoC-encoded raw data. Use `count` to limit results and `after_lt`/`after_hash` for pagination when `incomplete` is true.", - "operationId": "getBlockTransactionsExt_get", - "parameters": [ - { - "$ref": "#/components/parameters/workchain" - }, - { - "$ref": "#/components/parameters/shard" - }, - { - "$ref": "#/components/parameters/seqno" - }, - { - "$ref": "#/components/parameters/rootHashOptional" + "summary": "Get block transactions", + "description": "Returns a summary of transactions in a specific block. Each item contains the account address and transaction ID, but not full transaction details. Use `count` to limit results and `after_lt`/`after_hash` for pagination. Call getTransactions with each transaction ID to get full details.", + "operationId": "getBlockTransactions_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BlockTransactionsRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns short transaction identifiers (account, lt, hash) for transactions in the specified block.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BlockTransactionsResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + } + }, + "/api/v2/getBlockTransactionsExt": { + "get": { + "tags": [ + "Transactions" + ], + "summary": "Get block transactions (extended)", + "description": "Returns full transaction objects for transactions in a specific block. Each transaction includes complete data: inbound and outbound messages, fees, and BoC-encoded raw data. Use `count` to limit results and `after_lt`/`after_hash` for pagination when `incomplete` is true.", + "operationId": "getBlockTransactionsExt_get", + "parameters": [ + { + "$ref": "#/components/parameters/workchain" + }, + { + "$ref": "#/components/parameters/shard" + }, + { + "$ref": "#/components/parameters/seqno" + }, + { + "$ref": "#/components/parameters/rootHashOptional" }, { "$ref": "#/components/parameters/fileHashOptional" @@ -467,6 +775,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get block transactions (extended)", + "description": "Returns full transaction objects for transactions in a specific block. Each transaction includes complete data: inbound and outbound messages, fees, and BoC-encoded raw data. Use `count` to limit results and `after_lt`/`after_hash` for pagination when `incomplete` is true.", + "operationId": "getBlockTransactionsExt_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BlockTransactionsExtRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns full transaction objects for transactions in the specified block.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BlockTransactionsExtResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -533,6 +885,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get transactions", + "description": "Returns transaction history for an account. Transactions are returned newest-first. Each transaction shows the incoming message that triggered it, all outgoing messages, and fees paid. For pagination: use the `lt` and `hash` from the oldest transaction as the starting point for the next request.", + "operationId": "getTransactions_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TransactionsRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns a list of transactions for the specified account, ordered by logical time.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TransactionsResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -599,6 +995,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get transactions (standard)", + "description": "Returns transaction history for an account in a standardized format. Transactions are returned newest-first. Each transaction includes the triggering inbound message, all outbound messages, and fees paid. The response includes a `previous_transaction_id` cursor for paginating through older transactions.", + "operationId": "getTransactionsStd_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TransactionsRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns transactions in standardized format with a pagination cursor.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TonlibResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -658,6 +1098,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Try locate transaction", + "description": "Finds a transaction by message parameters. Given a source address, destination address, and message creation time (created_lt), returns the transaction that processed this message. Useful for locating when a previously sent message was executed.", + "operationId": "tryLocateTx_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TryLocateTxRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns the transaction matching the given source, destination, and created logical time.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LocateTxResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -717,6 +1201,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Try locate result transaction", + "description": "Finds the transaction that received a specific message. Given message parameters, returns the transaction on the destination account that processed the incoming message. Use this to trace message delivery across accounts.", + "operationId": "tryLocateResultTx_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TryLocateResultTxRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns the resulting transaction on the destination account for the given message.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LocateResultTxResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -776,6 +1304,9 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -786,26 +1317,67 @@ "APIKeyQuery": [] } ] - } - }, - "/api/v2/getMasterchainInfo": { - "get": { + }, + "post": { "tags": [ - "Blocks" + "RPC" ], - "summary": "Get masterchain info", - "description": "Returns the current state of the TON masterchain. The `last` field contains the latest block used for querying current state. The `seqno` in `last` is the current block height. Use this endpoint to obtain the latest block reference for other queries.", - "operationId": "getMasterchainInfo_get", - "parameters": [], - "responses": { - "200": { - "description": "The current masterchain state, including the latest block identifier, its state root hash, and the genesis block reference. Use `result.last.seqno` as the current block height.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/MasterchainInfoResponse" - } - } + "summary": "Try locate source transaction", + "description": "Finds the transaction that sent a specific message. Given message parameters, returns the transaction on the source account that created this outgoing message. Useful for tracing where a message originated from.", + "operationId": "tryLocateSourceTx_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TryLocateSourceTxRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns the originating transaction on the source account for the given message.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LocateSourceTxResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + } + }, + "/api/v2/getMasterchainInfo": { + "get": { + "tags": [ + "Blocks" + ], + "summary": "Get masterchain info", + "description": "Returns the current state of the TON masterchain. The `last` field contains the latest block used for querying current state. The `seqno` in `last` is the current block height. Use this endpoint to obtain the latest block reference for other queries.", + "operationId": "getMasterchainInfo_get", + "parameters": [], + "responses": { + "200": { + "description": "The current masterchain state, including the latest block identifier, its state root hash, and the genesis block reference. Use `result.last.seqno` as the current block height.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MasterchainInfoResponse" + } + } } }, "401": { @@ -819,6 +1391,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get masterchain info", + "description": "Returns the current state of the TON masterchain. The `last` field contains the latest block used for querying current state. The `seqno` in `last` is the current block height. Use this endpoint to obtain the latest block reference for other queries.", + "operationId": "getMasterchainInfo_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MasterchainInfoRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "The current masterchain state, including the latest block identifier, its state root hash, and the genesis block reference. Use `result.last.seqno` as the current block height.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MasterchainInfoResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -869,6 +1485,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get masterchain block signatures", + "description": "Returns validator signatures for a specific masterchain block. Each signature proves that a validator approved this block. Use this for building cryptographic proofs or verifying block authenticity in trustless applications.", + "operationId": "getMasterchainBlockSignatures_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MasterchainBlockSignaturesRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns validator signatures for the specified masterchain block.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MasterchainBlockSignaturesResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -935,6 +1595,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get shard block proof", + "description": "Returns a Merkle proof that links a shardchain block to a masterchain block. This proof cryptographically verifies that the shard block is part of the canonical chain. Used by light clients and cross-chain bridges to verify shard data without trusting the API.", + "operationId": "getShardBlockProof_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShardBlockProofRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns a cryptographic proof chain linking a shard block to the masterchain.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShardBlockProofResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -978,6 +1682,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get consensus block", + "description": "Returns the latest block that has reached consensus and is guaranteed to be final. This block will never be reverted, making it safe for confirming transactions that require absolute finality.", + "operationId": "getConsensusBlock_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConsensusBlockRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "The latest masterchain block that has achieved finality, guaranteed to never be reverted. Returns its sequence number and Unix timestamp.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConsensusBlockResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -996,7 +1744,7 @@ "Blocks" ], "summary": "Lookup block", - "description": "Finds a block by position or time. Specify workchain and shard, then provide either: `seqno` (exact block number), lt (find block containing this logical time), or unixtime (find block closest to this timestamp). Returns the full block ID including hashes needed for verification.", + "description": "Finds a block by position or time. Specify workchain and shard, then provide exactly one of: `seqno` (exact block number), lt (find block containing this logical time), or unixtime (find block closest to this timestamp). Returns the full block ID including hashes needed for verification.", "operationId": "lookupBlock_get", "parameters": [ { @@ -1054,6 +1802,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Lookup block", + "description": "Finds a block by position or time. Specify workchain and shard, then provide exactly one of: `seqno` (exact block number), lt (find block containing this logical time), or unixtime (find block closest to this timestamp). Returns the full block ID including hashes needed for verification.", + "operationId": "lookupBlock_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LookupBlockRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns the full block identifier matching the given `seqno`, logical time, or unix timestamp.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LookupBlockResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -1105,6 +1897,9 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -1115,19 +1910,60 @@ "APIKeyQuery": [] } ] - } - }, - "/api/v2/getBlockHeader": { - "get": { + }, + "post": { "tags": [ - "Blocks" + "RPC" ], - "summary": "Get block header", - "description": "Returns block metadata without the full transaction list. Includes timestamps, validator info, and references to previous blocks. Intended for block explorers and other use cases that require block information without transactions.", - "operationId": "getBlockHeader_get", - "parameters": [ - { - "$ref": "#/components/parameters/workchain" + "summary": "Get shards", + "description": "Returns the active shardchain block identifiers at a given masterchain block height. Each shard processes a subset of accounts in parallel. The response shows how the basechain is currently partitioned and which block each shard is at.", + "operationId": "getShards_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShardsRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns the list of active shard block identifiers at the specified masterchain block.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TonlibResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + } + }, + "/api/v2/getBlockHeader": { + "get": { + "tags": [ + "Blocks" + ], + "summary": "Get block header", + "description": "Returns block metadata without the full transaction list. Includes timestamps, validator info, and references to previous blocks. Intended for block explorers and other use cases that require block information without transactions.", + "operationId": "getBlockHeader_get", + "parameters": [ + { + "$ref": "#/components/parameters/workchain" }, { "$ref": "#/components/parameters/shard" @@ -1167,6 +2003,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get block header", + "description": "Returns block metadata without the full transaction list. Includes timestamps, validator info, and references to previous blocks. Intended for block explorers and other use cases that require block information without transactions.", + "operationId": "getBlockHeader_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BlockHeaderRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns the block header with merge/split flags, validator info, and timing data.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BlockHeaderResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -1209,6 +2089,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get outbound message queue size", + "description": "Returns the current size of the outbound message queue for each shard. A growing queue indicates network congestion. If the queue is large, transactions may take longer to process. Monitor this to detect network issues.", + "operationId": "getOutMsgQueueSize_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OutMsgQueueSizeRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Outgoing message queue sizes for all active shards. A growing queue indicates network congestion and may cause transaction delays.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OutMsgQueueSizeResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -1270,6 +2194,9 @@ }, "542": { "$ref": "#/components/responses/542" + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -1331,6 +2258,9 @@ }, "542": { "$ref": "#/components/responses/542" + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -1389,6 +2319,9 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -1447,6 +2380,9 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -1505,6 +2441,9 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -1552,6 +2491,50 @@ }, "429": { "$ref": "#/components/responses/429" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Detect address", + "description": "Validates an address and returns it in all standard formats. Use this to convert between address formats or to validate user input. Returns raw format (`0:abc`), base64 bounceable (`EQ`), base64 non-bounceable (`UQ`), and URL-safe variants.", + "operationId": "detectAddress_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DetectAddressRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns the address in all supported formats (raw, bounceable, non-bounceable) with base64 and URL-safe variants.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DetectAddressResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -1599,6 +2582,50 @@ }, "429": { "$ref": "#/components/responses/429" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Detect hash", + "description": "Validates a hash and returns it in all standard formats. Use this to convert between hex (64 chars) and base64 (44 chars) representations. Works with any 256-bit hash including transaction hashes, block hashes, and message hashes.", + "operationId": "detectHash_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DetectHashRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns the hash in all supported formats (hex, base64, URL-safe base64).", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DetectHashResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -1646,6 +2673,50 @@ }, "429": { "$ref": "#/components/responses/429" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Pack address", + "description": "Converts a raw address to user-friendly base64 format. Raw addresses use the format `workchain:hex` (e.g., `0:abc...`). The packed format is shorter and includes a checksum for error detection.", + "operationId": "packAddress_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PackAddressRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns the address converted to user-friendly (base64) format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PackAddressResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -1664,7 +2735,7 @@ "Utils" ], "summary": "Unpack address", - "description": "Converts a user-friendly base64 address back to its raw components. Returns the workchain ID, account hex, and flags indicating if the address is bounceable or testnet-only.", + "description": "Converts a user-friendly base64 address to a raw address string in `workchain:hex` format.", "operationId": "unpackAddress_get", "parameters": [ { @@ -1673,7 +2744,7 @@ ], "responses": { "200": { - "description": "Returns the unpacked address components: workchain, hex account ID, and format flags.", + "description": "Converts a user-friendly base64 address to a raw address string in `workchain:hex` format.", "content": { "application/json": { "schema": { @@ -1693,6 +2764,9 @@ }, "429": { "$ref": "#/components/responses/429" + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -1703,22 +2777,63 @@ "APIKeyQuery": [] } ] - } - }, - "/api/v2/getConfigParam": { - "get": { + }, + "post": { "tags": [ - "Configuration" + "RPC" ], - "summary": "Get config parameter", - "description": "Returns a specific blockchain configuration parameter. TON stores all network settings on-chain as numbered parameters. Common ones: 0 (config contract), 1 (elector), 15 (election timing), 17 (stake limits), 20-21 (gas prices), 34 (current validators). Check TON documentation for the full list.", - "operationId": "getConfigParam_get", - "parameters": [ - { - "name": "config_id", - "in": "query", - "description": "Parameter number", - "required": true, + "summary": "Unpack address", + "description": "Converts a user-friendly base64 address to a raw address string in `workchain:hex` format.", + "operationId": "unpackAddress_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnpackAddressRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Converts a user-friendly base64 address to a raw address string in `workchain:hex` format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnpackAddressResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + } + }, + "/api/v2/getConfigParam": { + "get": { + "tags": [ + "Configuration" + ], + "summary": "Get config parameter", + "description": "Returns a specific blockchain configuration parameter. TON stores all network settings on-chain as numbered parameters. Common ones: 0 (config contract), 1 (elector), 15 (election timing), 17 (stake limits), 20-21 (gas prices), 34 (current validators). Check TON documentation for the full list.", + "operationId": "getConfigParam_get", + "parameters": [ + { + "name": "config_id", + "in": "query", + "description": "Legacy alias for `param`.", + "required": false, "schema": { "type": "integer", "format": "int32" @@ -1733,6 +2848,16 @@ "type": "integer", "format": "int32" } + }, + { + "name": "param", + "in": "query", + "description": "Parameter number. Use `param` or the legacy `config_id` alias.", + "required": false, + "schema": { + "type": "integer", + "format": "int32" + } } ], "responses": { @@ -1760,6 +2885,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get config parameter", + "description": "Returns a specific blockchain configuration parameter. TON stores all network settings on-chain as numbered parameters. Common ones: 0 (config contract), 1 (elector), 15 (election timing), 17 (stake limits), 20-21 (gas prices), 34 (current validators). Check TON documentation for the full list.", + "operationId": "getConfigParam_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConfigParamRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns the specified blockchain configuration parameter as a TVM cell.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConfigParamResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -1814,6 +2983,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get all config parameters", + "description": "Returns all blockchain configuration parameters at once. Includes gas prices, validator settings, workchain configs, and governance rules. Use the optional `seqno` to get historical configuration at a specific block height.", + "operationId": "getConfigAll_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConfigAllRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns all blockchain configuration parameters as a single TVM cell.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConfigAllResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -1873,6 +3086,50 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get libraries", + "description": "Returns smart contract library code by hash. Some contracts reference shared libraries instead of including all code directly. When a library reference appears in contract code, this endpoint fetches the actual library implementation.", + "operationId": "getLibraries_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LibrariesRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Returns the code of the requested shared library cells.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LibrariesResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -1931,6 +3188,9 @@ }, "504": { "$ref": "#/components/responses/504" + }, + "default": { + "$ref": "#/components/responses/default" } }, "security": [ @@ -1942,68 +3202,343 @@ } ] } - } - }, - "tags": [ - { - "name": "Accounts", - "description": "Information about accounts" - }, - { - "name": "Transactions", - "description": "Fetching and locating transactions" - }, - { - "name": "Blocks", - "description": "Information about blocks" - }, - { - "name": "Run method", - "description": "Run get-method of smart contracts" - }, - { - "name": "Send", - "description": "Send data to blockchain" - }, - { - "name": "Utils", - "description": "Some useful methods" - }, - { - "name": "Configuration", - "description": "Information about blockchain config" }, - { - "name": "RPC", - "description": "JSON-RPC and POST endpoints" - } - ], - "components": { - "parameters": { - "address": { - "name": "address", - "in": "query", - "required": true, - "schema": { - "$ref": "#/components/schemas/TonAddr" + "/api/v2/getShardAccountCell": { + "get": { + "tags": [ + "Accounts" + ], + "summary": "Get shard account cell", + "description": "Get the raw TVM cell containing the shard account.", + "operationId": "getShardAccountCell_get", + "parameters": [ + { + "$ref": "#/components/parameters/address" + }, + { + "$ref": "#/components/parameters/seqnoOptional" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TvmCellResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" + } }, - "description": "The account address to query." - }, - "hash": { - "name": "hash", - "in": "query", - "required": true, - "schema": { - "$ref": "#/components/schemas/TonHash" - } + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] }, - "hashOptional": { - "name": "hash", - "in": "query", - "required": false, - "schema": { - "$ref": "#/components/schemas/TonHash" - } + "post": { + "tags": [ + "RPC" + ], + "summary": "Get shard account cell", + "description": "Get the raw TVM cell containing the shard account.", + "operationId": "getShardAccountCell_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShardAccountCellRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TvmCellResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + } + }, + "/api/v2/dnsResolve": { + "get": { + "tags": [ + "Accounts" + ], + "summary": "Resolve TON DNS name", + "description": "Recursively resolve a TON DNS domain into all records. Supports .ton, .t.me, and delegated subdomains. When resolver_address is omitted, discover the root from on-chain config parameter 4. Root discovery and all resolver calls use the same masterchain block, selected by seqno or the current state.", + "operationId": "dnsResolve_get", + "parameters": [ + { + "name": "domain", + "in": "query", + "description": "Domain to resolve; relative to resolver_address when supplied. Case-insensitive; a trailing dot is accepted.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "resolver_address", + "in": "query", + "description": "Starting resolver address. Defaults to on-chain config parameter 4 at the selected block.", + "required": false, + "schema": { + "$ref": "#/components/schemas/TonAddr" + } + }, + { + "$ref": "#/components/parameters/seqnoOptional" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DnsResolvedResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Resolve TON DNS name", + "description": "Recursively resolve a TON DNS domain into all records, using the same behavior as GET. Replaces the former address, name, category, and ttl parameters with domain, resolver_address, and seqno. Missing records produce an empty entries array.", + "operationId": "dnsResolve_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DnsResolveRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DnsResolvedResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + } + }, + "/api/v2/getBlock": { + "get": { + "tags": [ + "Blocks" + ], + "summary": "Get block", + "description": "Get raw block data as a base64-encoded BoC.", + "operationId": "getBlock_get", + "parameters": [ + { + "$ref": "#/components/parameters/workchain" + }, + { + "$ref": "#/components/parameters/shard" + }, + { + "$ref": "#/components/parameters/seqno" + }, + { + "$ref": "#/components/parameters/rootHashOptional" + }, + { + "$ref": "#/components/parameters/fileHashOptional" + }, + { + "$ref": "#/components/parameters/archivalOptional" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BlockDataResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + }, + "post": { + "tags": [ + "RPC" + ], + "summary": "Get block", + "description": "Get raw block data as a base64-encoded BoC.", + "operationId": "getBlock_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BlockDataRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BlockDataResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" + } + }, + "security": [ + { + "APIKeyHeader": [] + }, + { + "APIKeyQuery": [] + } + ] + } + } + }, + "tags": [ + { + "name": "Accounts", + "description": "Information about accounts" + }, + { + "name": "Transactions", + "description": "Fetching and locating transactions" + }, + { + "name": "Blocks", + "description": "Information about blocks" + }, + { + "name": "Run method", + "description": "Run get-method of smart contracts" + }, + { + "name": "Send", + "description": "Send data to blockchain" + }, + { + "name": "Utils", + "description": "Some useful methods" + }, + { + "name": "Configuration", + "description": "Information about blockchain config" + }, + { + "name": "RPC", + "description": "JSON-RPC and POST endpoints" + } + ], + "components": { + "parameters": { + "address": { + "name": "address", + "in": "query", + "required": true, + "schema": { + "$ref": "#/components/schemas/TonAddr" + }, + "description": "The account address to query, in raw or user-friendly format." + }, + "hash": { + "name": "hash", + "in": "query", + "required": true, + "schema": { + "$ref": "#/components/schemas/TonHash" + }, + "description": "The 256-bit hash in any form" + }, + "hashOptional": { + "name": "hash", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/TonHash" + }, + "description": "The 256-bit hash in any form" }, "workchain": { "name": "workchain", @@ -2028,7 +3563,7 @@ "seqno": { "name": "seqno", "in": "query", - "description": "Masterchain block sequence number (block height). Used to query state at a specific point in time. If omitted, returns the current state.", + "description": "Block sequence number within the specified workchain and shard.", "required": true, "schema": { "type": "integer", @@ -2048,7 +3583,7 @@ "rootHashOptional": { "name": "root_hash", "in": "query", - "description": "The block's root hash for verification. Together with `file_hash`, this uniquely and cryptographically identifies a block. Only needed when proof of block identity is required.", + "description": "The block's root hash. Together with `file_hash`, uniquely identifies a block.", "required": false, "schema": { "type": "string", @@ -2058,7 +3593,7 @@ "fileHashOptional": { "name": "file_hash", "in": "query", - "description": "The block's file hash for verification. Together with `root_hash`, this provides cryptographic proof of block identity. Only needed for trustless verification.", + "description": "The block's file hash. Together with `root_hash`, uniquely identifies a block.", "required": false, "schema": { "type": "string", @@ -2078,7 +3613,7 @@ "afterAccountHashOptional": { "name": "after_hash", "in": "query", - "description": "Secondary pagination cursor for block transactions. When multiple accounts have transactions at the same `lt`, use this to continue from a specific account.", + "description": "Account ID in hex or base64 for block transaction pagination. Use together with `after_lt` from the last transaction in the previous page.", "required": false, "schema": { "type": "string", @@ -2122,7 +3657,7 @@ "toLtOptional": { "name": "to_lt", "in": "query", - "description": "Stop fetching when reaching this logical time. Use this to limit the time range of returned transactions. Set to 0 (default) to fetch all available history.", + "description": "Stop fetching when reaching this logical time. Set to 0 (default) to leave the lower logical-time bound unspecified.", "required": false, "schema": { "type": "string", @@ -2170,18 +3705,8 @@ } }, "responses": { - "default": { - "description": "Error response.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TonlibErrorResponse" - } - } - } - }, - "401": { - "description": "API key does not exist. Check for typos or generate a new key.", + "401": { + "description": "API key does not exist. Check for typos or generate a new key.", "content": { "application/json": { "schema": { @@ -2352,6 +3877,183 @@ } } }, + "429": { + "description": "Rate limit exceeded. Back off and retry, or use an API key for higher limits.", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "ok", + "code", + "error" + ], + "properties": { + "ok": { + "type": "boolean", + "const": false, + "description": "Always `false` for error responses." + }, + "code": { + "type": "integer", + "const": 429, + "description": "HTTP status code `429`." + }, + "error": { + "type": "string", + "enum": [ + "Ratelimit exceeded" + ] + }, + "@extra": { + "type": "string", + "description": "Extra data passed through from the request." + } + } + }, + "example": { + "ok": false, + "code": 429, + "error": "Ratelimit exceeded" + } + } + } + }, + "504": { + "description": "Timeout waiting for liteserver response.", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "ok", + "code", + "error" + ], + "properties": { + "ok": { + "type": "boolean", + "const": false, + "description": "Always `false` for error responses." + }, + "code": { + "type": "integer", + "const": 504, + "description": "HTTP status code `504`." + }, + "error": { + "type": "string", + "enum": [ + "LITE_SERVER_NETWORK timeout" + ] + }, + "@extra": { + "type": "string", + "description": "Extra data passed through from the request." + } + } + }, + "example": { + "ok": false, + "code": 504, + "error": "LITE_SERVER_NETWORK timeout" + } + } + } + }, + "542": { + "description": "Liteserver-specific error or unsupported stack type.", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "ok", + "code", + "error" + ], + "properties": { + "ok": { + "type": "boolean", + "const": false, + "description": "Always `false` for error responses." + }, + "code": { + "type": "integer", + "const": 542, + "description": "HTTP status code `542`." + }, + "error": { + "type": "string", + "enum": [ + "Unsupported stack entry type: " + ] + }, + "@extra": { + "type": "string", + "description": "Extra data passed through from the request." + } + } + }, + "example": { + "ok": false, + "code": 542, + "error": "Unsupported stack entry type: " + } + } + } + }, + "default": { + "description": "Error response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TonlibErrorResponse" + }, + "examples": { + "409": { + "summary": "Not a token", + "value": { + "ok": false, + "code": 409, + "error": "Smart contract is not a Jetton or NFT", + "@extra": "..." + } + }, + "422": { + "summary": "Request validation error", + "value": { + "ok": false, + "code": 422, + "error": "...", + "@extra": "..." + } + }, + "429": { + "summary": "Ratelimit exceeded", + "value": { + "ok": false, + "code": 429, + "error": "...", + "@extra": "..." + } + }, + "504": { + "summary": "Tonlib timeout", + "value": { + "ok": false, + "code": 504, + "error": "...", + "@extra": "..." + } + } + } + } + } + }, "422_address": { "description": "Invalid address or `seqno` parameter.", "content": { @@ -2866,49 +4568,6 @@ } } }, - "429": { - "description": "Rate limit exceeded. Back off and retry, or use an API key for higher limits.", - "content": { - "application/json": { - "schema": { - "type": "object", - "additionalProperties": false, - "required": [ - "ok", - "code", - "error" - ], - "properties": { - "ok": { - "type": "boolean", - "const": false, - "description": "Always `false` for error responses." - }, - "code": { - "type": "integer", - "const": 429, - "description": "HTTP status code `429`." - }, - "error": { - "type": "string", - "enum": [ - "Ratelimit exceeded" - ] - }, - "@extra": { - "type": "string", - "description": "Extra data passed through from the request." - } - } - }, - "example": { - "ok": false, - "code": 429, - "error": "Ratelimit exceeded" - } - } - } - }, "500_send": { "description": "Transaction simulation failed.", "content": { @@ -3050,100 +4709,14 @@ } } } - }, - "504": { - "description": "Timeout waiting for liteserver response.", - "content": { - "application/json": { - "schema": { - "type": "object", - "additionalProperties": false, - "required": [ - "ok", - "code", - "error" - ], - "properties": { - "ok": { - "type": "boolean", - "const": false, - "description": "Always `false` for error responses." - }, - "code": { - "type": "integer", - "const": 504, - "description": "HTTP status code `504`." - }, - "error": { - "type": "string", - "enum": [ - "LITE_SERVER_NETWORK timeout" - ] - }, - "@extra": { - "type": "string", - "description": "Extra data passed through from the request." - } - } - }, - "example": { - "ok": false, - "code": 504, - "error": "LITE_SERVER_NETWORK timeout" - } - } - } - }, - "542": { - "description": "Liteserver-specific error or unsupported stack type.", - "content": { - "application/json": { - "schema": { - "type": "object", - "additionalProperties": false, - "required": [ - "ok", - "code", - "error" - ], - "properties": { - "ok": { - "type": "boolean", - "const": false, - "description": "Always `false` for error responses." - }, - "code": { - "type": "integer", - "const": 542, - "description": "HTTP status code `542`." - }, - "error": { - "type": "string", - "enum": [ - "Unsupported stack entry type: " - ] - }, - "@extra": { - "type": "string", - "description": "Extra data passed through from the request." - } - } - }, - "example": { - "ok": false, - "code": 542, - "error": "Unsupported stack entry type: " - } - } - } - } - }, - "securitySchemes": { - "APIKeyHeader": { - "type": "apiKey", - "in": "header", - "name": "X-API-Key", - "description": "API key header of the form `X-API-Key: `, where `` is the API key. Requests without a key are limited to 1 RPS. Refer to the [authentication guide](/api/v2/authentication) for details." + } + }, + "securitySchemes": { + "APIKeyHeader": { + "type": "apiKey", + "in": "header", + "name": "X-API-Key", + "description": "API key header of the form `X-API-Key: `, where `` is the API key. Requests without a key are limited to 1 RPS. Refer to the [authentication guide](/api/v2/authentication) for details." }, "APIKeyQuery": { "type": "apiKey", @@ -3393,7 +4966,7 @@ } ], "x-usrv-cpp-type": "std::int64_t", - "description": "Logical time of this event. A globally unique counter that orders all blockchain events. Higher values are more recent." + "description": "Logical time used to look up a block." }, "unixtime": { "oneOf": [ @@ -3465,7 +5038,7 @@ }, "root_hash": { "$ref": "#/components/schemas/TonHash", - "description": "Merkle root hash of the block state tree. Used for cryptographic verification." + "description": "Root hash of the block. Together with `file_hash`, uniquely identifies a block." }, "file_hash": { "$ref": "#/components/schemas/TonHash", @@ -3527,7 +5100,7 @@ }, "root_hash": { "$ref": "#/components/schemas/TonHash", - "description": "Merkle root hash of the block state tree. Used for cryptographic verification." + "description": "Root hash of the block. Together with `file_hash`, uniquely identifies a block." }, "file_hash": { "$ref": "#/components/schemas/TonHash", @@ -3592,7 +5165,7 @@ } ], "x-usrv-cpp-type": "std::int64_t", - "description": "Logical time of this event. A globally unique counter that orders all blockchain events. Higher values are more recent." + "description": "Logical time of the transaction. Use together with its hash for pagination and lookups." }, "hash": { "$ref": "#/components/schemas/TonHash", @@ -3689,9 +5262,6 @@ "ConfigParamRequest": { "type": "object", "additionalProperties": false, - "required": [ - "config_id" - ], "properties": { "config_id": { "oneOf": [ @@ -3704,7 +5274,7 @@ } ], "x-usrv-cpp-type": "std::int32_t", - "description": "Configuration parameter number. Each number controls different blockchain settings." + "description": "Configuration parameter number. Each number controls different blockchain settings. Legacy alias for `param`; specify exactly one of these fields." }, "seqno": { "oneOf": [ @@ -3718,8 +5288,33 @@ ], "x-usrv-cpp-type": "std::int32_t", "description": "Masterchain block sequence number (block height). Used to query blockchain config at a specific block. If omitted, the latest masterchain block is used." + }, + "param": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "integer", + "format": "int32" + } + ], + "x-usrv-cpp-type": "std::int32_t", + "description": "Configuration parameter number. Each number controls different blockchain settings." } - } + }, + "oneOf": [ + { + "required": [ + "param" + ] + }, + { + "required": [ + "config_id" + ] + } + ] }, "ConfigAllRequest": { "type": "object", @@ -3876,7 +5471,11 @@ "x-usrv-cpp-type": "ton_http::types::ton_addr", "description": "The account address in raw format (`workchain:hex`), e.g. `0:abc123...`. Use the [pack address](/api/v2/utils/pack-address) endpoint to convert to user-friendly base64 format." } - } + }, + "required": [ + "@type", + "account_address" + ] }, "TonBlockIdExt": { "type": "object", @@ -3905,7 +5504,7 @@ }, "root_hash": { "$ref": "#/components/schemas/TonHash", - "description": "Merkle root hash of the block state tree." + "description": "Root hash of the block. Together with `file_hash`, uniquely identifies a block." }, "file_hash": { "$ref": "#/components/schemas/TonHash", @@ -3993,7 +5592,7 @@ }, "lt": { "type": "string", - "description": "Logical time of this transaction. A globally unique counter that orders all events on the blockchain.", + "description": "Logical time of the transaction. Use together with its hash for pagination and lookups.", "x-usrv-cpp-type": "std::int64_t" }, "hash": { @@ -4861,7 +6460,7 @@ }, "mintable": { "type": "boolean", - "description": "Returns `true` if new tokens can still be minted; `false` means the supply is permanently capped." + "description": "Returns `true` if new tokens can be minted; otherwise `false`." }, "admin_address": { "$ref": "#/components/schemas/TonAddr", @@ -5075,7 +6674,7 @@ "active", "frozen" ], - "description": "The lifecycle state of an account: `uninitialized` (no contract deployed), `active` (contract working normally), or `frozen` (suspended due to zero balance). Refer to the [account lifecycle states documentation](/foundations/status) for details." + "description": "The lifecycle state of an account: `uninitialized` (no contract deployed), `active` (contract working normally), or `frozen` (contract state frozen). Refer to the [account lifecycle states documentation](/foundations/status) for details." }, "BlockSignature": { "type": "object", @@ -5255,7 +6854,7 @@ }, "lt": { "type": "string", - "description": "Logical time of this transaction. A globally unique counter that orders all events on the blockchain.", + "description": "Logical time of the transaction. Use together with its hash for pagination and lookups.", "x-usrv-cpp-type": "std::int64_t" }, "hash": { @@ -5413,7 +7012,7 @@ }, "ihr_fee": { "$ref": "#/components/schemas/Int256", - "description": "Instant Hypercube Routing (IHR) fee in nanograms. Always `0`. This is hardcoded at the protocol level and cannot be changed." + "description": "Instant Hypercube Routing (IHR) fee in nanograms." }, "created_lt": { "type": "string", @@ -5573,7 +7172,7 @@ }, "ihr_fee": { "$ref": "#/components/schemas/Int256", - "description": "Instant Hypercube Routing (IHR) fee in nanograms. Always `0`. This is hardcoded at the protocol level and cannot be changed." + "description": "Instant Hypercube Routing (IHR) fee in nanograms." }, "created_lt": { "type": "string", @@ -5610,7 +7209,7 @@ "body_hash", "msg_data" ], - "description": "A message between accounts. Contains sender, recipient, GRAM amount transferred, and the message body. The `created_lt` field orders messages globally." + "description": "A message between accounts. Contains sender, recipient, GRAM amount transferred, and the message body. The `created_lt` field is the message creation logical time." }, "Transaction": { "type": "object", @@ -5714,7 +7313,7 @@ "$ref": "#/components/schemas/MasterchainInfo" }, { - "$ref": "#/components/schemas/MasterchainBlockSignatures" + "$ref": "#/components/schemas/BlockSignatures" }, { "$ref": "#/components/schemas/ShardBlockProof" @@ -5766,6 +7365,18 @@ }, { "$ref": "#/components/schemas/RunGetMethodResult" + }, + { + "$ref": "#/components/schemas/DnsResolved" + }, + { + "$ref": "#/components/schemas/BlockSignaturesSimplex" + }, + { + "$ref": "#/components/schemas/BlockData" + }, + { + "$ref": "#/components/schemas/TvmCell" } ], "discriminator": { @@ -5781,7 +7392,7 @@ "ext.tokens.nftCollectionData": "#/components/schemas/NftCollectionData", "ext.tokens.nftItemData": "#/components/schemas/NftItemData", "blocks.masterchainInfo": "#/components/schemas/MasterchainInfo", - "blocks.blockSignatures": "#/components/schemas/MasterchainBlockSignatures", + "blocks.blockSignatures": "#/components/schemas/BlockSignatures", "blocks.shardBlockProof": "#/components/schemas/ShardBlockProof", "ext.blocks.consensusBlock": "#/components/schemas/ConsensusBlock", "ton.blockIdExt": "#/components/schemas/TonBlockIdExt", @@ -5798,7 +7409,11 @@ "raw.extMessageInfo": "#/components/schemas/ExtMessageInfo", "ok": "#/components/schemas/ResultOk", "smc.runResult": "#/components/schemas/RunGetMethodStdResult", - "ext.runResult": "#/components/schemas/RunGetMethodResult" + "ext.runResult": "#/components/schemas/RunGetMethodResult", + "dns.resolved": "#/components/schemas/DnsResolved", + "blocks.blockSignatures.simplex": "#/components/schemas/BlockSignaturesSimplex", + "blocks.blockData": "#/components/schemas/BlockData", + "tvm.cell": "#/components/schemas/TvmCell" } } }, @@ -5819,9 +7434,24 @@ "description": "Returns `true` if the request succeeded; otherwise `false`. See the `error` field for details." }, "result": { - "type": "object", "description": "The method return value. The structure depends on the method called; see individual method documentation for response schemas. Only present when `ok` is `true`.", - "additionalProperties": true + "anyOf": [ + { + "type": "string" + }, + { + "$ref": "#/components/schemas/AccountStateEnum" + }, + { + "$ref": "#/components/schemas/TonlibObject" + }, + { + "type": "array", + "items": { + "$ref": "#/components/schemas/TonlibObject" + } + } + ] }, "@extra": { "type": "string", @@ -5851,23 +7481,35 @@ "ok": { "type": "boolean", "const": false, - "description": "Always `false` for error responses." + "description": "Always `false` for error responses.", + "title": "Ok", + "default": false }, "code": { "type": "integer", - "minimum": 400, - "maximum": 599, - "description": "HTTP status code. Common values: 404 (not found), 409 (conflict), 422 (validation error), 429 (rate limit), 500 (server error), 504 (timeout), 542 (liteserver error)." + "minimum": 100, + "maximum": 600, + "description": "HTTP status code. Common values: 404 (not found), 409 (conflict), 422 (validation error), 429 (rate limit), 500 (server error), 504 (timeout), 542 (liteserver error).", + "title": "Error code" }, "error": { "type": "string", - "description": "Error message explaining what went wrong." + "description": "Error message explaining what went wrong.", + "title": "Error description" }, "@extra": { "type": "string", - "description": "Extra data passed through from the request." + "description": "Extra data passed through from the request.", + "title": "Extra information" + }, + "jsonrpc": { + "type": "string" + }, + "id": { + "type": "string" } - } + }, + "title": "TonlibErrorResponse" }, "JsonRpcResponse": { "allOf": [ @@ -6028,7 +7670,7 @@ }, "balance": { "$ref": "#/components/schemas/Int256", - "description": "The account balance in nanograms (the smallest unit of GRAM). 1 GRAM = 1,000,000,000 nanograms (10^9), so divide by 10^9 to get the human-readable GRAM amount. Refer to the [units and decimals guide](/onboarding/wallet-apps/deep-links#jetton-transfer) for more context. If this field appears on a Jetton wallet, the balance is in the token's base units. Divide by 10^decimals, where `decimals` is defined by the Jetton master contract. Refer to the [Jetton overview](/contracts/standard/tokens/jettons/overview) for details on how Jetton decimals work." + "description": "The account balance in nanograms (the smallest unit of GRAM). 1 GRAM = 1,000,000,000 nanograms (10^9), so divide by 10^9 to get the human-readable GRAM amount. Refer to the [units and decimals guide](/onboarding/wallet-apps/deep-links#jetton-transfer) for more context." }, "extra_currencies": { "type": "array", @@ -6051,7 +7693,7 @@ }, "data": { "$ref": "#/components/schemas/Bytes", - "description": "Raw transaction or contract data in BoC (Bag of Cells) format, base64 encoded." + "description": "Smart contract persistent storage in BoC format, base64 encoded." }, "frozen_hash": { "$ref": "#/components/schemas/TonHash", @@ -6064,7 +7706,7 @@ }, "state": { "$ref": "#/components/schemas/AccountStateEnum", - "description": "Account state: uninit, active, or frozen." + "description": "Account state: uninitialized, active, or frozen." }, "suspended": { "type": "boolean", @@ -6103,7 +7745,7 @@ }, "balance": { "$ref": "#/components/schemas/Int256", - "description": "The account balance in nanograms (the smallest unit of GRAM). 1 GRAM = 1,000,000,000 nanograms (10^9), so divide by 10^9 to get the human-readable GRAM amount. Refer to the [units and decimals guide](/onboarding/wallet-apps/deep-links#jetton-transfer) for more context. If this field appears on a Jetton wallet, the balance is in the token's base units. Divide by 10^decimals, where `decimals` is defined by the Jetton master contract. Refer to the [Jetton overview](/contracts/standard/tokens/jettons/overview) for details on how Jetton decimals work." + "description": "The account balance in nanograms (the smallest unit of GRAM). 1 GRAM = 1,000,000,000 nanograms (10^9), so divide by 10^9 to get the human-readable GRAM amount. Refer to the [units and decimals guide](/onboarding/wallet-apps/deep-links#jetton-transfer) for more context." }, "extra_currencies": { "type": "array", @@ -6169,7 +7811,7 @@ }, "account_state": { "$ref": "#/components/schemas/AccountStateEnum", - "description": "Account lifecycle state: `uninit`, `active`, or `frozen`." + "description": "Account lifecycle state: `uninitialized`, `active`, or `frozen`." }, "last_transaction_id": { "$ref": "#/components/schemas/InternalTransactionId", @@ -6188,9 +7830,10 @@ "wallet v4 r1", "wallet v4 r2", "wallet v5 beta", - "wallet v5 r1" + "wallet v5 r1", + "tg-wallet" ], - "description": "Wallet contract version (e.g., `wallet v4 r2`, `wallet v5 r1`). Empty if not a recognized wallet." + "description": "Recognized wallet contract type, such as `wallet v4 r2`, `wallet v5 r1`, or `tg-wallet`." }, "seqno": { "type": "integer", @@ -6203,7 +7846,7 @@ }, "is_signature_allowed": { "type": "boolean", - "description": "Returns `true` if external signatures are enabled (v5 wallets only); `false` means the wallet is controlled only by plugins." + "description": "Whether signature authentication is enabled for this wallet (v5 wallets only)." } }, "required": [ @@ -6213,7 +7856,7 @@ "account_state", "last_transaction_id" ], - "description": "Information about a wallet account. The `wallet` field indicates if this is a known wallet type. If true, `wallet_type`, `seqno`, and `wallet_id` will be populated. Check `seqno` before sending transactions." + "description": "Information about a wallet account. Check `wallet` before using wallet-specific fields such as `wallet_type`, `seqno`, and `wallet_id`; available fields depend on the wallet type." }, "AddressBalance": { "$ref": "#/components/schemas/Int256" @@ -6251,37 +7894,25 @@ "last", "state_root_hash", "init" - ] + ], + "description": "Information about the latest masterchain block." }, "MasterchainBlockSignatures": { - "type": "object", - "additionalProperties": false, - "properties": { - "@type": { - "type": "string", - "enum": [ - "blocks.blockSignatures" - ], - "default": "blocks.blockSignatures", - "description": "TonLib type identifier for block signature collections. Refer to the [TonLib type reference](/api/v2-tonlib-types) for a full list." - }, - "id": { - "$ref": "#/components/schemas/TonBlockIdExt", - "description": "Full block identifier for the signed block." + "oneOf": [ + { + "$ref": "#/components/schemas/BlockSignatures" }, - "signatures": { - "type": "array", - "items": { - "$ref": "#/components/schemas/BlockSignature" - }, - "description": "Array of validator signatures for this block. Each entry contains the validator's short node ID (base64 hash) and their Ed25519 signature (base64)." + { + "$ref": "#/components/schemas/BlockSignaturesSimplex" } - }, - "required": [ - "@type", - "id", - "signatures" - ] + ], + "discriminator": { + "propertyName": "@type", + "mapping": { + "blocks.blockSignatures": "#/components/schemas/BlockSignatures", + "blocks.blockSignatures.simplex": "#/components/schemas/BlockSignaturesSimplex" + } + } }, "ShardBlockProof": { "type": "object", @@ -7565,7 +9196,7 @@ "description": "Returns `true` if the request succeeded; otherwise `false`. See the `error` field for details." }, "result": { - "$ref": "#/components/schemas/UnpackedAddress", + "$ref": "#/components/schemas/UnpackAddress", "description": "Response data. Present only when `ok` is `true`." }, "@extra": { @@ -8244,6 +9875,491 @@ "description": "Optional request ID that can be passed in the request and received back in the response. Useful for matching async responses." } } + }, + "BlockSignatures": { + "type": "object", + "additionalProperties": false, + "properties": { + "@type": { + "type": "string", + "enum": [ + "blocks.blockSignatures" + ], + "default": "blocks.blockSignatures", + "description": "TonLib type identifier for block signature collections. Refer to the [TonLib type reference](/api/v2-tonlib-types) for a full list." + }, + "id": { + "$ref": "#/components/schemas/TonBlockIdExt", + "description": "Full block identifier for the signed block." + }, + "signatures": { + "type": "array", + "items": { + "$ref": "#/components/schemas/BlockSignature" + }, + "description": "Array of validator signatures for this block. Each entry contains the validator's short node ID (base64 hash) and their Ed25519 signature (base64)." + } + }, + "required": [ + "@type", + "id", + "signatures" + ] + }, + "ShardAccountCellRequest": { + "$ref": "#/components/schemas/AddressWithSeqnoRequest" + }, + "DnsResolveRequest": { + "type": "object", + "additionalProperties": false, + "required": [ + "domain" + ], + "properties": { + "domain": { + "type": "string", + "description": "Domain to resolve; relative to resolver_address when supplied. Case-insensitive; a trailing dot is accepted." + }, + "resolver_address": { + "$ref": "#/components/schemas/TonAddr" + }, + "seqno": { + "type": "integer", + "format": "int32", + "description": "Masterchain block for root discovery and every resolver call. Defaults to current state." + } + } + }, + "BlockDataRequest": { + "type": "object", + "additionalProperties": false, + "required": [ + "workchain", + "shard", + "seqno" + ], + "properties": { + "workchain": { + "description": "Workchain ID: `-1` for masterchain, `0` for basechain. Most user transactions are on workchain `0`.", + "oneOf": [ + { + "type": "string" + }, + { + "type": "integer", + "format": "int32" + } + ], + "x-usrv-cpp-type": "std::int32_t" + }, + "shard": { + "description": "Shard identifier. A signed 64-bit integer. Masterchain uses -9223372036854775808.", + "oneOf": [ + { + "type": "string" + }, + { + "type": "integer", + "format": "int64", + "x-usrv-cpp-type": "std::int64_t" + } + ], + "x-usrv-cpp-type": "std::int64_t" + }, + "seqno": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "integer", + "format": "int32" + } + ], + "x-usrv-cpp-type": "std::int32_t" + }, + "root_hash": { + "$ref": "#/components/schemas/TonHash" + }, + "file_hash": { + "$ref": "#/components/schemas/TonHash" + }, + "archival": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "integer", + "format": "int32" + }, + { + "type": "boolean" + } + ], + "x-usrv-cpp-type": "bool" + } + } + }, + "AdnlAddress": { + "type": "object", + "additionalProperties": false, + "required": [ + "@type", + "adnl_address" + ], + "properties": { + "@type": { + "type": "string", + "enum": [ + "adnlAddress" + ], + "default": "adnlAddress" + }, + "adnl_address": { + "type": "string" + } + } + }, + "DnsEntryDataUnknown": { + "type": "object", + "additionalProperties": false, + "required": [ + "@type", + "bytes" + ], + "properties": { + "@type": { + "type": "string", + "enum": [ + "dns.entryDataUnknown" + ], + "default": "dns.entryDataUnknown" + }, + "bytes": { + "$ref": "#/components/schemas/Bytes" + } + } + }, + "DnsEntryDataText": { + "type": "object", + "additionalProperties": false, + "required": [ + "@type", + "text" + ], + "properties": { + "@type": { + "type": "string", + "enum": [ + "dns.entryDataText" + ], + "default": "dns.entryDataText" + }, + "text": { + "type": "string" + } + } + }, + "DnsEntryDataNextResolver": { + "type": "object", + "additionalProperties": false, + "required": [ + "@type", + "resolver" + ], + "properties": { + "@type": { + "type": "string", + "enum": [ + "dns.entryDataNextResolver" + ], + "default": "dns.entryDataNextResolver" + }, + "resolver": { + "$ref": "#/components/schemas/AccountAddress" + } + } + }, + "DnsEntryDataSmcAddress": { + "type": "object", + "additionalProperties": false, + "required": [ + "@type", + "smc_address" + ], + "properties": { + "@type": { + "type": "string", + "enum": [ + "dns.entryDataSmcAddress" + ], + "default": "dns.entryDataSmcAddress" + }, + "smc_address": { + "$ref": "#/components/schemas/AccountAddress" + } + } + }, + "DnsEntryDataAdnlAddress": { + "type": "object", + "additionalProperties": false, + "required": [ + "@type", + "adnl_address" + ], + "properties": { + "@type": { + "type": "string", + "enum": [ + "dns.entryDataAdnlAddress" + ], + "default": "dns.entryDataAdnlAddress" + }, + "adnl_address": { + "$ref": "#/components/schemas/AdnlAddress" + } + } + }, + "DnsEntryDataStorageAddress": { + "type": "object", + "additionalProperties": false, + "required": [ + "@type", + "bag_id" + ], + "properties": { + "@type": { + "type": "string", + "enum": [ + "dns.entryDataStorageAddress" + ], + "default": "dns.entryDataStorageAddress" + }, + "bag_id": { + "$ref": "#/components/schemas/TonHashHex" + } + } + }, + "DnsEntryData": { + "oneOf": [ + { + "$ref": "#/components/schemas/DnsEntryDataUnknown" + }, + { + "$ref": "#/components/schemas/DnsEntryDataText" + }, + { + "$ref": "#/components/schemas/DnsEntryDataNextResolver" + }, + { + "$ref": "#/components/schemas/DnsEntryDataSmcAddress" + }, + { + "$ref": "#/components/schemas/DnsEntryDataAdnlAddress" + }, + { + "$ref": "#/components/schemas/DnsEntryDataStorageAddress" + } + ], + "discriminator": { + "propertyName": "@type", + "mapping": { + "dns.entryDataUnknown": "#/components/schemas/DnsEntryDataUnknown", + "dns.entryDataText": "#/components/schemas/DnsEntryDataText", + "dns.entryDataNextResolver": "#/components/schemas/DnsEntryDataNextResolver", + "dns.entryDataSmcAddress": "#/components/schemas/DnsEntryDataSmcAddress", + "dns.entryDataAdnlAddress": "#/components/schemas/DnsEntryDataAdnlAddress", + "dns.entryDataStorageAddress": "#/components/schemas/DnsEntryDataStorageAddress" + } + } + }, + "DnsEntry": { + "type": "object", + "additionalProperties": false, + "required": [ + "@type", + "name", + "category", + "entry" + ], + "properties": { + "@type": { + "type": "string", + "enum": [ + "dns.entry" + ], + "default": "dns.entry" + }, + "name": { + "type": "string" + }, + "category": { + "$ref": "#/components/schemas/TonHash" + }, + "entry": { + "$ref": "#/components/schemas/DnsEntryData" + } + } + }, + "DnsResolved": { + "type": "object", + "additionalProperties": false, + "required": [ + "@type", + "entries" + ], + "properties": { + "@type": { + "type": "string", + "enum": [ + "dns.resolved" + ], + "default": "dns.resolved" + }, + "entries": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DnsEntry" + } + } + } + }, + "BlockSignaturesSimplex": { + "type": "object", + "additionalProperties": false, + "properties": { + "@type": { + "type": "string", + "enum": [ + "blocks.blockSignatures.simplex" + ], + "default": "blocks.blockSignatures.simplex" + }, + "id": { + "$ref": "#/components/schemas/TonBlockIdExt" + }, + "signatures": { + "type": "array", + "items": { + "$ref": "#/components/schemas/BlockSignature" + } + }, + "session_id": { + "$ref": "#/components/schemas/TonHash" + }, + "slot": { + "type": "integer", + "format": "int32" + }, + "candidate": { + "$ref": "#/components/schemas/Bytes" + } + }, + "required": [ + "@type", + "id", + "signatures", + "session_id", + "slot", + "candidate" + ] + }, + "BlockData": { + "type": "object", + "additionalProperties": false, + "description": "Raw block data returned by a LiteServer.", + "properties": { + "@type": { + "type": "string", + "enum": [ + "blocks.blockData" + ], + "default": "blocks.blockData" + }, + "id": { + "$ref": "#/components/schemas/TonBlockIdExt", + "description": "Extended identifier of the returned block." + }, + "data": { + "$ref": "#/components/schemas/Bytes", + "description": "Full block BoC encoded as base64." + } + }, + "required": [ + "@type", + "id", + "data" + ] + }, + "TvmCellResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "ok", + "result" + ], + "properties": { + "ok": { + "type": "boolean", + "default": true, + "description": "Returns `true` if the request succeeded; otherwise `false`. See the `error` field for details." + }, + "result": { + "$ref": "#/components/schemas/TvmCell", + "description": "Response data. Present only when `ok` is `true`." + }, + "@extra": { + "type": "string", + "description": "Optional request ID that can be passed in the request and received back in the response. Useful for matching async responses." + } + } + }, + "DnsResolvedResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "ok", + "result" + ], + "properties": { + "ok": { + "type": "boolean", + "default": true, + "description": "Returns `true` if the request succeeded; otherwise `false`. See the `error` field for details." + }, + "result": { + "$ref": "#/components/schemas/DnsResolved", + "description": "Response data. Present only when `ok` is `true`." + }, + "@extra": { + "type": "string", + "description": "Optional request ID that can be passed in the request and received back in the response. Useful for matching async responses." + } + } + }, + "BlockDataResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "ok", + "result" + ], + "properties": { + "ok": { + "type": "boolean", + "default": true, + "description": "Returns `true` if the request succeeded; otherwise `false`. See the `error` field for details." + }, + "result": { + "$ref": "#/components/schemas/BlockData", + "description": "Response data. Present only when `ok` is `true`." + }, + "@extra": { + "type": "string", + "description": "Optional request ID that can be passed in the request and received back in the response. Useful for matching async responses." + } + } } } } diff --git a/content/api/v2/accounts/get-address-state.mdx b/content/api/v2/accounts/get-address-state.mdx index b3315f0b3..0589f9385 100644 --- a/content/api/v2/accounts/get-address-state.mdx +++ b/content/api/v2/accounts/get-address-state.mdx @@ -15,9 +15,9 @@ _openapi: - content: 'Returns the lifecycle state of an account. Possible values: `uninitialized` (address has no deployed contract but can receive GRAM), `active` (contract is deployed and working), `frozen` (contract - suspended due to zero balance, send GRAM to unfreeze). Refer to the - [account lifecycle states documentation](/foundations/status) for - details. Check this before interacting with a contract.' + state frozen). Refer to the [account lifecycle states + documentation](/foundations/status) for details. Check this before + interacting with a contract.' --- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} diff --git a/content/api/v2/accounts/get-extended-address-information.mdx b/content/api/v2/accounts/get-extended-address-information.mdx index 2ea842ecd..36fb908ef 100644 --- a/content/api/v2/accounts/get-extended-address-information.mdx +++ b/content/api/v2/accounts/get-extended-address-information.mdx @@ -13,9 +13,8 @@ _openapi: headings: [] contents: - content: Returns detailed account information with parsed contract state. For - wallet contracts, identifies the wallet version (v3, v4, v5) and - extracts wallet-specific fields like `seqno` and public key. For other - contracts, returns the raw state. + recognized contract types, returns type-specific state fields. For + other contracts, returns the raw state. --- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} diff --git a/content/api/v2/accounts/get-shard-account-cell.mdx b/content/api/v2/accounts/get-shard-account-cell.mdx new file mode 100644 index 000000000..c9249dcc9 --- /dev/null +++ b/content/api/v2/accounts/get-shard-account-cell.mdx @@ -0,0 +1,30 @@ +--- +title: Get shard account cell +full: true +noindex: true +sidebarTitle: Get shard account cell +_openapi: + preload: + - v2 + method: GET + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Get the raw TVM cell containing the shard account. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/accounts/resolve-ton-dns-name.mdx b/content/api/v2/accounts/resolve-ton-dns-name.mdx new file mode 100644 index 000000000..a67055ded --- /dev/null +++ b/content/api/v2/accounts/resolve-ton-dns-name.mdx @@ -0,0 +1,34 @@ +--- +title: Resolve TON DNS name +full: true +noindex: true +sidebarTitle: Resolve TON DNS name +_openapi: + preload: + - v2 + method: GET + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Recursively resolve a TON DNS domain into all records. Supports .ton, + .t.me, and delegated subdomains. When resolver_address is omitted, + discover the root from on-chain config parameter 4. Root discovery and + all resolver calls use the same masterchain block, selected by seqno + or the current state. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/blocks/get-block.mdx b/content/api/v2/blocks/get-block.mdx new file mode 100644 index 000000000..7e0832ffb --- /dev/null +++ b/content/api/v2/blocks/get-block.mdx @@ -0,0 +1,30 @@ +--- +title: Get block +full: true +noindex: true +sidebarTitle: Get block +_openapi: + preload: + - v2 + method: GET + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Get raw block data as a base64-encoded BoC. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/blocks/lookup-block.mdx b/content/api/v2/blocks/lookup-block.mdx index a3e5e3d56..b7b6d0d2e 100644 --- a/content/api/v2/blocks/lookup-block.mdx +++ b/content/api/v2/blocks/lookup-block.mdx @@ -13,7 +13,7 @@ _openapi: headings: [] contents: - content: 'Finds a block by position or time. Specify workchain and shard, then - provide either: `seqno` (exact block number), lt (find block + provide exactly one of: `seqno` (exact block number), lt (find block containing this logical time), or unixtime (find block closest to this timestamp). Returns the full block ID including hashes needed for verification.' diff --git a/content/api/v2/overview.mdx b/content/api/v2/overview.mdx index 2da8900b0..0f6b469f5 100644 --- a/content/api/v2/overview.mdx +++ b/content/api/v2/overview.mdx @@ -47,6 +47,8 @@ API v2 uses semantic versioning in the format `a.b.c` (for example, `2.1.1`): | **Accounts** | [`GET /getAddressBalance`](/api/v2/accounts/get-address-balance) | Get address balance | | **Accounts** | [`GET /getAddressState`](/api/v2/accounts/get-address-state) | Get address state | | **Accounts** | [`GET /getTokenData`](/api/v2/accounts/get-token-data) | Get token data | +| **Accounts** | [`GET /getShardAccountCell`](/api/v2/accounts/get-shard-account-cell) | Get shard account cell | +| **Accounts** | [`GET /dnsResolve`](/api/v2/accounts/resolve-ton-dns-name) | Resolve TON DNS name | | **Blocks** | [`GET /getMasterchainInfo`](/api/v2/blocks/get-masterchain-info) | Get masterchain info | | **Blocks** | [`GET /getMasterchainBlockSignatures`](/api/v2/blocks/get-masterchain-block-signatures) | Get masterchain block signatures | | **Blocks** | [`GET /getShardBlockProof`](/api/v2/blocks/get-shard-block-proof) | Get shard block proof | @@ -55,6 +57,7 @@ API v2 uses semantic versioning in the format `a.b.c` (for example, `2.1.1`): | **Blocks** | [`GET /getShards`](/api/v2/blocks/get-shards) | Get shards | | **Blocks** | [`GET /getBlockHeader`](/api/v2/blocks/get-block-header) | Get block header | | **Blocks** | [`GET /getOutMsgQueueSize`](/api/v2/blocks/get-outbound-message-queue-size) | Get outbound message queue size | +| **Blocks** | [`GET /getBlock`](/api/v2/blocks/get-block) | Get block | | **Transactions** | [`GET /getBlockTransactions`](/api/v2/transactions/get-block-transactions) | Get block transactions | | **Transactions** | [`GET /getBlockTransactionsExt`](/api/v2/transactions/get-block-transactions-extended) | Get block transactions (extended) | | **Transactions** | [`GET /getTransactions`](/api/v2/transactions/get-transactions) | Get transactions | diff --git a/content/api/v2/rpc/detect-address.mdx b/content/api/v2/rpc/detect-address.mdx new file mode 100644 index 000000000..55a06e4c9 --- /dev/null +++ b/content/api/v2/rpc/detect-address.mdx @@ -0,0 +1,33 @@ +--- +title: Detect address +full: true +noindex: true +sidebarTitle: Detect address +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Validates an address and returns it in all standard formats. Use this + to convert between address formats or to validate user input. Returns + raw format (`0:abc`), base64 bounceable (`EQ`), base64 non-bounceable + (`UQ`), and URL-safe variants. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/detect-hash.mdx b/content/api/v2/rpc/detect-hash.mdx new file mode 100644 index 000000000..938815af6 --- /dev/null +++ b/content/api/v2/rpc/detect-hash.mdx @@ -0,0 +1,33 @@ +--- +title: Detect hash +full: true +noindex: true +sidebarTitle: Detect hash +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Validates a hash and returns it in all standard formats. Use this to + convert between hex (64 chars) and base64 (44 chars) representations. + Works with any 256-bit hash including transaction hashes, block + hashes, and message hashes. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-address-balance.mdx b/content/api/v2/rpc/get-address-balance.mdx new file mode 100644 index 000000000..268b5705c --- /dev/null +++ b/content/api/v2/rpc/get-address-balance.mdx @@ -0,0 +1,33 @@ +--- +title: Get address balance +full: true +noindex: true +sidebarTitle: Get address balance +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Returns the GRAM balance of an account in nanograms. 1 GRAM = + 1,000,000,000 nanograms. A lightweight endpoint that returns only the + balance without contract code, data, or other account details. Returns + "0" for addresses that have never received any funds. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-address-information.mdx b/content/api/v2/rpc/get-address-information.mdx new file mode 100644 index 000000000..a880afa64 --- /dev/null +++ b/content/api/v2/rpc/get-address-information.mdx @@ -0,0 +1,34 @@ +--- +title: Get address information +full: true +noindex: true +sidebarTitle: Get address information +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Returns the current state of any account on the TON blockchain. + Includes the balance (in nanograms), smart contract code and data (if + deployed), account status, and a reference to the last transaction. + This is the primary endpoint for checking if an address exists and + what's deployed there. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-address-state.mdx b/content/api/v2/rpc/get-address-state.mdx new file mode 100644 index 000000000..3907b7520 --- /dev/null +++ b/content/api/v2/rpc/get-address-state.mdx @@ -0,0 +1,35 @@ +--- +title: Get address state +full: true +noindex: true +sidebarTitle: Get address state +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: 'Returns the lifecycle state of an account. Possible values: + `uninitialized` (address has no deployed contract but can receive + GRAM), `active` (contract is deployed and working), `frozen` (contract + state frozen). Refer to the [account lifecycle states + documentation](/foundations/status) for details. Check this before + interacting with a contract.' +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-all-config-parameters.mdx b/content/api/v2/rpc/get-all-config-parameters.mdx new file mode 100644 index 000000000..a234cd58d --- /dev/null +++ b/content/api/v2/rpc/get-all-config-parameters.mdx @@ -0,0 +1,33 @@ +--- +title: Get all config parameters +full: true +noindex: true +sidebarTitle: Get all config parameters +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Returns all blockchain configuration parameters at once. Includes gas + prices, validator settings, workchain configs, and governance rules. + Use the optional `seqno` to get historical configuration at a specific + block height. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-block-header.mdx b/content/api/v2/rpc/get-block-header.mdx new file mode 100644 index 000000000..4b3934328 --- /dev/null +++ b/content/api/v2/rpc/get-block-header.mdx @@ -0,0 +1,33 @@ +--- +title: Get block header +full: true +noindex: true +sidebarTitle: Get block header +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Returns block metadata without the full transaction list. Includes + timestamps, validator info, and references to previous blocks. + Intended for block explorers and other use cases that require block + information without transactions. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-block-transactions-extended.mdx b/content/api/v2/rpc/get-block-transactions-extended.mdx new file mode 100644 index 000000000..f6ce9d3f6 --- /dev/null +++ b/content/api/v2/rpc/get-block-transactions-extended.mdx @@ -0,0 +1,33 @@ +--- +title: Get block transactions (extended) +full: true +noindex: true +sidebarTitle: Get block transactions (extended) +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: 'Returns full transaction objects for transactions in a specific block. + Each transaction includes complete data: inbound and outbound + messages, fees, and BoC-encoded raw data. Use `count` to limit results + and `after_lt`/`after_hash` for pagination when `incomplete` is true.' +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-block-transactions.mdx b/content/api/v2/rpc/get-block-transactions.mdx new file mode 100644 index 000000000..57fa758ff --- /dev/null +++ b/content/api/v2/rpc/get-block-transactions.mdx @@ -0,0 +1,34 @@ +--- +title: Get block transactions +full: true +noindex: true +sidebarTitle: Get block transactions +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Returns a summary of transactions in a specific block. Each item + contains the account address and transaction ID, but not full + transaction details. Use `count` to limit results and + `after_lt`/`after_hash` for pagination. Call getTransactions with each + transaction ID to get full details. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-block.mdx b/content/api/v2/rpc/get-block.mdx new file mode 100644 index 000000000..5797b1924 --- /dev/null +++ b/content/api/v2/rpc/get-block.mdx @@ -0,0 +1,30 @@ +--- +title: Get block +full: true +noindex: true +sidebarTitle: Get block +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Get raw block data as a base64-encoded BoC. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-config-parameter.mdx b/content/api/v2/rpc/get-config-parameter.mdx new file mode 100644 index 000000000..3a3ab25dd --- /dev/null +++ b/content/api/v2/rpc/get-config-parameter.mdx @@ -0,0 +1,34 @@ +--- +title: Get config parameter +full: true +noindex: true +sidebarTitle: Get config parameter +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: 'Returns a specific blockchain configuration parameter. TON stores all + network settings on-chain as numbered parameters. Common ones: 0 + (config contract), 1 (elector), 15 (election timing), 17 (stake + limits), 20-21 (gas prices), 34 (current validators). Check TON + documentation for the full list.' +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-consensus-block.mdx b/content/api/v2/rpc/get-consensus-block.mdx new file mode 100644 index 000000000..5ed0c402f --- /dev/null +++ b/content/api/v2/rpc/get-consensus-block.mdx @@ -0,0 +1,32 @@ +--- +title: Get consensus block +full: true +noindex: true +sidebarTitle: Get consensus block +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Returns the latest block that has reached consensus and is guaranteed + to be final. This block will never be reverted, making it safe for + confirming transactions that require absolute finality. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-extended-address-information.mdx b/content/api/v2/rpc/get-extended-address-information.mdx new file mode 100644 index 000000000..9d8e82177 --- /dev/null +++ b/content/api/v2/rpc/get-extended-address-information.mdx @@ -0,0 +1,32 @@ +--- +title: Get extended address information +full: true +noindex: true +sidebarTitle: Get extended address information +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Returns detailed account information with parsed contract state. For + recognized contract types, returns type-specific state fields. For + other contracts, returns the raw state. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-libraries.mdx b/content/api/v2/rpc/get-libraries.mdx new file mode 100644 index 000000000..695e233c5 --- /dev/null +++ b/content/api/v2/rpc/get-libraries.mdx @@ -0,0 +1,33 @@ +--- +title: Get libraries +full: true +noindex: true +sidebarTitle: Get libraries +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Returns smart contract library code by hash. Some contracts reference + shared libraries instead of including all code directly. When a + library reference appears in contract code, this endpoint fetches the + actual library implementation. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-masterchain-block-signatures.mdx b/content/api/v2/rpc/get-masterchain-block-signatures.mdx new file mode 100644 index 000000000..1ff7812cf --- /dev/null +++ b/content/api/v2/rpc/get-masterchain-block-signatures.mdx @@ -0,0 +1,33 @@ +--- +title: Get masterchain block signatures +full: true +noindex: true +sidebarTitle: Get masterchain block signatures +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Returns validator signatures for a specific masterchain block. Each + signature proves that a validator approved this block. Use this for + building cryptographic proofs or verifying block authenticity in + trustless applications. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-masterchain-info.mdx b/content/api/v2/rpc/get-masterchain-info.mdx new file mode 100644 index 000000000..15b5c6f5b --- /dev/null +++ b/content/api/v2/rpc/get-masterchain-info.mdx @@ -0,0 +1,33 @@ +--- +title: Get masterchain info +full: true +noindex: true +sidebarTitle: Get masterchain info +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Returns the current state of the TON masterchain. The `last` field + contains the latest block used for querying current state. The `seqno` + in `last` is the current block height. Use this endpoint to obtain the + latest block reference for other queries. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-outbound-message-queue-size.mdx b/content/api/v2/rpc/get-outbound-message-queue-size.mdx new file mode 100644 index 000000000..354c7e843 --- /dev/null +++ b/content/api/v2/rpc/get-outbound-message-queue-size.mdx @@ -0,0 +1,33 @@ +--- +title: Get outbound message queue size +full: true +noindex: true +sidebarTitle: Get outbound message queue size +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Returns the current size of the outbound message queue for each shard. + A growing queue indicates network congestion. If the queue is large, + transactions may take longer to process. Monitor this to detect + network issues. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-shard-account-cell.mdx b/content/api/v2/rpc/get-shard-account-cell.mdx new file mode 100644 index 000000000..891e022a1 --- /dev/null +++ b/content/api/v2/rpc/get-shard-account-cell.mdx @@ -0,0 +1,30 @@ +--- +title: Get shard account cell +full: true +noindex: true +sidebarTitle: Get shard account cell +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Get the raw TVM cell containing the shard account. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-shard-block-proof.mdx b/content/api/v2/rpc/get-shard-block-proof.mdx new file mode 100644 index 000000000..b42ca4a34 --- /dev/null +++ b/content/api/v2/rpc/get-shard-block-proof.mdx @@ -0,0 +1,33 @@ +--- +title: Get shard block proof +full: true +noindex: true +sidebarTitle: Get shard block proof +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Returns a Merkle proof that links a shardchain block to a masterchain + block. This proof cryptographically verifies that the shard block is + part of the canonical chain. Used by light clients and cross-chain + bridges to verify shard data without trusting the API. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-shards.mdx b/content/api/v2/rpc/get-shards.mdx new file mode 100644 index 000000000..40f021be7 --- /dev/null +++ b/content/api/v2/rpc/get-shards.mdx @@ -0,0 +1,33 @@ +--- +title: Get shards +full: true +noindex: true +sidebarTitle: Get shards +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Returns the active shardchain block identifiers at a given masterchain + block height. Each shard processes a subset of accounts in parallel. + The response shows how the basechain is currently partitioned and + which block each shard is at. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-token-data.mdx b/content/api/v2/rpc/get-token-data.mdx new file mode 100644 index 000000000..fb8c3f8bd --- /dev/null +++ b/content/api/v2/rpc/get-token-data.mdx @@ -0,0 +1,34 @@ +--- +title: Get token data +full: true +noindex: true +sidebarTitle: Get token data +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: 'Returns metadata for Jetton or NFT contracts. Automatically detects + the contract type and returns appropriate fields. For Jetton masters: + total supply, admin, metadata. For Jetton wallets: balance, owner. For + NFT items: collection, owner, content. For NFT collections: item + count, metadata.' +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-transactions-standard.mdx b/content/api/v2/rpc/get-transactions-standard.mdx new file mode 100644 index 000000000..b01891504 --- /dev/null +++ b/content/api/v2/rpc/get-transactions-standard.mdx @@ -0,0 +1,34 @@ +--- +title: Get transactions (standard) +full: true +noindex: true +sidebarTitle: Get transactions (standard) +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Returns transaction history for an account in a standardized format. + Transactions are returned newest-first. Each transaction includes the + triggering inbound message, all outbound messages, and fees paid. The + response includes a `previous_transaction_id` cursor for paginating + through older transactions. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-transactions.mdx b/content/api/v2/rpc/get-transactions.mdx new file mode 100644 index 000000000..f416d14ef --- /dev/null +++ b/content/api/v2/rpc/get-transactions.mdx @@ -0,0 +1,34 @@ +--- +title: Get transactions +full: true +noindex: true +sidebarTitle: Get transactions +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: 'Returns transaction history for an account. Transactions are returned + newest-first. Each transaction shows the incoming message that + triggered it, all outgoing messages, and fees paid. For pagination: + use the `lt` and `hash` from the oldest transaction as the starting + point for the next request.' +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/get-wallet-information.mdx b/content/api/v2/rpc/get-wallet-information.mdx new file mode 100644 index 000000000..ce96cb12a --- /dev/null +++ b/content/api/v2/rpc/get-wallet-information.mdx @@ -0,0 +1,34 @@ +--- +title: Get wallet information +full: true +noindex: true +sidebarTitle: Get wallet information +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: 'Returns wallet-specific information for an address. If the address is + a known wallet contract, returns the wallet type, current `seqno` + (needed for sending transactions), and `wallet_id`. Always check + `wallet: true` before using wallet-specific fields. Call this before + sending any transaction to get the current `seqno`.' +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/lookup-block.mdx b/content/api/v2/rpc/lookup-block.mdx new file mode 100644 index 000000000..d0c9d05c9 --- /dev/null +++ b/content/api/v2/rpc/lookup-block.mdx @@ -0,0 +1,34 @@ +--- +title: Lookup block +full: true +noindex: true +sidebarTitle: Lookup block +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: 'Finds a block by position or time. Specify workchain and shard, then + provide exactly one of: `seqno` (exact block number), lt (find block + containing this logical time), or unixtime (find block closest to this + timestamp). Returns the full block ID including hashes needed for + verification.' +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/meta.json b/content/api/v2/rpc/meta.json index 01a779486..ad1c37042 100644 --- a/content/api/v2/rpc/meta.json +++ b/content/api/v2/rpc/meta.json @@ -2,6 +2,7 @@ "$schema": "../../../../../../meta-schema.json", "title": "RPC", "pages": [ - "json-rpc-endpoint" + "json-rpc-endpoint", + "..." ] } diff --git a/content/api/v2/rpc/pack-address.mdx b/content/api/v2/rpc/pack-address.mdx new file mode 100644 index 000000000..555600199 --- /dev/null +++ b/content/api/v2/rpc/pack-address.mdx @@ -0,0 +1,32 @@ +--- +title: Pack address +full: true +noindex: true +sidebarTitle: Pack address +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Converts a raw address to user-friendly base64 format. Raw addresses + use the format `workchain:hex` (e.g., `0:abc...`). The packed format + is shorter and includes a checksum for error detection. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/resolve-ton-dns-name.mdx b/content/api/v2/rpc/resolve-ton-dns-name.mdx new file mode 100644 index 000000000..a9e5b3410 --- /dev/null +++ b/content/api/v2/rpc/resolve-ton-dns-name.mdx @@ -0,0 +1,33 @@ +--- +title: Resolve TON DNS name +full: true +noindex: true +sidebarTitle: Resolve TON DNS name +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Recursively resolve a TON DNS domain into all records, using the same + behavior as GET. Replaces the former address, name, category, and ttl + parameters with domain, resolver_address, and seqno. Missing records + produce an empty entries array. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/try-locate-result-transaction.mdx b/content/api/v2/rpc/try-locate-result-transaction.mdx new file mode 100644 index 000000000..73c01f65b --- /dev/null +++ b/content/api/v2/rpc/try-locate-result-transaction.mdx @@ -0,0 +1,33 @@ +--- +title: Try locate result transaction +full: true +noindex: true +sidebarTitle: Try locate result transaction +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Finds the transaction that received a specific message. Given message + parameters, returns the transaction on the destination account that + processed the incoming message. Use this to trace message delivery + across accounts. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/try-locate-source-transaction.mdx b/content/api/v2/rpc/try-locate-source-transaction.mdx new file mode 100644 index 000000000..75d062992 --- /dev/null +++ b/content/api/v2/rpc/try-locate-source-transaction.mdx @@ -0,0 +1,33 @@ +--- +title: Try locate source transaction +full: true +noindex: true +sidebarTitle: Try locate source transaction +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Finds the transaction that sent a specific message. Given message + parameters, returns the transaction on the source account that created + this outgoing message. Useful for tracing where a message originated + from. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/try-locate-transaction.mdx b/content/api/v2/rpc/try-locate-transaction.mdx new file mode 100644 index 000000000..cde6afdac --- /dev/null +++ b/content/api/v2/rpc/try-locate-transaction.mdx @@ -0,0 +1,33 @@ +--- +title: Try locate transaction +full: true +noindex: true +sidebarTitle: Try locate transaction +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Finds a transaction by message parameters. Given a source address, + destination address, and message creation time (created_lt), returns + the transaction that processed this message. Useful for locating when + a previously sent message was executed. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/rpc/unpack-address.mdx b/content/api/v2/rpc/unpack-address.mdx new file mode 100644 index 000000000..4aa544509 --- /dev/null +++ b/content/api/v2/rpc/unpack-address.mdx @@ -0,0 +1,31 @@ +--- +title: Unpack address +full: true +noindex: true +sidebarTitle: Unpack address +_openapi: + preload: + - v2 + method: POST + webhook: false + toc: [] + structuredData: + headings: [] + contents: + - content: Converts a user-friendly base64 address to a raw address string in + `workchain:hex` format. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +export default function Layout(props) { + const { APIPage, OpenAPIPage } = props.components ?? {}; + // "APIPage" is the old name from v10, this allows both for backward compatibility + const Comp = OpenAPIPage ?? APIPage; + return ( + <> + {props.children} + + + ); +} diff --git a/content/api/v2/transactions/get-block-transactions-extended.mdx b/content/api/v2/transactions/get-block-transactions-extended.mdx index aa8304155..6c3ca019e 100644 --- a/content/api/v2/transactions/get-block-transactions-extended.mdx +++ b/content/api/v2/transactions/get-block-transactions-extended.mdx @@ -12,11 +12,10 @@ _openapi: structuredData: headings: [] contents: - - content: 'Returns full transaction objects for all transactions in a specific - block. Each transaction includes complete data: inbound and outbound - messages, fees, state changes, and BoC-encoded raw data. Use `count` - to limit results and `after_lt`/`after_hash` for pagination when - `incomplete` is true.' + - content: 'Returns full transaction objects for transactions in a specific block. + Each transaction includes complete data: inbound and outbound + messages, fees, and BoC-encoded raw data. Use `count` to limit results + and `after_lt`/`after_hash` for pagination when `incomplete` is true.' --- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} diff --git a/content/api/v2/utils/unpack-address.mdx b/content/api/v2/utils/unpack-address.mdx index 25a0b0789..108e87b72 100644 --- a/content/api/v2/utils/unpack-address.mdx +++ b/content/api/v2/utils/unpack-address.mdx @@ -12,9 +12,8 @@ _openapi: structuredData: headings: [] contents: - - content: Converts a user-friendly base64 address back to its raw components. - Returns the workchain ID, account hex, and flags indicating if the - address is bounceable or testnet-only. + - content: Converts a user-friendly base64 address to a raw address string in + `workchain:hex` format. --- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} diff --git a/content/api/v3.yaml b/content/api/v3.yaml index 7f10ee19b..14fc2e31d 100644 --- a/content/api/v3.yaml +++ b/content/api/v3.yaml @@ -237,6 +237,12 @@ paths: enum: - asc - desc + - name: cursor + in: query + description: Continue after the page that returned this `next_cursor`. Send the same filters and sort; do not + combine with `offset`. + schema: + type: string responses: "200": description: OK @@ -3084,7 +3090,7 @@ paths: - APIKeyQuery: [] description: >- Get wallet smart contract information. Supports the following wallet versions: `v1r1`, `v1r2`, `v1r3`, `v2r1`, - `v2r2`, `v3r1`, `v3r2`, `v4r1`, `v4r2`, `v5beta`, and `v5r1`. If the account is not a wallet, returns error code + `v2r2`, `v3r1`, `v3r2`, `v4r1`, `v4r2`, `v5beta`, `v5r1`, and `tg-wallet`. If the account is not a wallet, returns error code `409`. tags: - API v2 @@ -3306,6 +3312,9 @@ components: $ref: "#/components/schemas/Transaction" type: type: string + parent_gasless_action: + description: The `action_id` of the `gasless_request` action that directly produced this action. + type: string ActionPhase: type: object properties: @@ -3350,6 +3359,8 @@ components: $ref: "#/components/schemas/AddressBook" metadata: $ref: "#/components/schemas/Metadata" + next_cursor: + type: string AddressBook: type: object additionalProperties: @@ -3545,6 +3556,10 @@ components: type: string nft_item_owner: type: string + self_assigned: + description: Whether the owner, wallet, and last wallet writer are the same. Available only when the server + uses `-dns-self-assigned-only`. + type: boolean DNSAuction: type: object properties: diff --git a/content/api/v3/api-v2/get-wallet-information.mdx b/content/api/v3/api-v2/get-wallet-information.mdx index 44fbd9437..f02d12061 100644 --- a/content/api/v3/api-v2/get-wallet-information.mdx +++ b/content/api/v3/api-v2/get-wallet-information.mdx @@ -14,8 +14,8 @@ _openapi: contents: - content: 'Get wallet smart contract information. Supports the following wallet versions: `v1r1`, `v1r2`, `v1r3`, `v2r1`, `v2r2`, `v3r1`, `v3r2`, - `v4r1`, `v4r2`, `v5beta`, and `v5r1`. If the account is not a wallet, - returns error code `409`.' + `v4r1`, `v4r2`, `v5beta`, `v5r1`, and `tg-wallet`. If the account is + not a wallet, returns error code `409`.' --- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} diff --git a/package.json b/package.json index 71064001a..b195a105c 100644 --- a/package.json +++ b/package.json @@ -28,6 +28,7 @@ "lint:all": "npm run check:all", "gen:tc2:overview": "python3 .github/scripts/generate-v2-api-table.py", "gen:tc3:overview": "python3 .github/scripts/generate-v3-api-table.py", + "gen:emu:overview": "python3 .github/scripts/generate-emulate-api-table.py", "gen:mdx-for-openapi": "node .github/scripts/generate-openapi-pages.mjs", "gen:meta-schema": "node .github/scripts/generate-meta-schema.mjs", "gen:stats": "python3 .github/scripts/stats.py", diff --git a/src/lib/openapi.ts b/src/lib/openapi.ts index ec844bf75..0bfd1e378 100644 --- a/src/lib/openapi.ts +++ b/src/lib/openapi.ts @@ -6,5 +6,6 @@ export const openapi = createOpenAPI({ input: { v2: path.resolve('./content/api/v2.json'), v3: path.resolve('./content/api/v3.yaml'), + emulate: path.resolve('./content/api/emulate.json'), }, });