HTTP API

入门

本文档提供了使用 TON HTTP API 的全面指南，包括 API 端点、请求和响应格式以及错误处理。无论您是构建新应用程序还是与现有应用程序集成，本文档都将帮助您快速高效地开始使用 TON HTTP API。

Get Address Information

get

Get basic information about the address: balance, code, data, last_transaction_id.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

addressstringrequired

Identifier of target TON account in any form.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/getAddressInformation?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Extended Address Information

get

Similar to previous one but tries to parse additional information for known contract types. This method is based on tonlib's function getAccountState. For detecting wallets we recommend to use getWalletInformation.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

addressstringrequired

Identifier of target TON account in any form.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/getExtendedAddressInformation?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Wallet Information

get

Retrieve wallet information. This method parses contract state and currently supports more wallet types than getExtendedAddressInformation: simple wallet, standart wallet, v3 wallet, v4 wallet.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

addressstringrequired

Identifier of target TON account in any form.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/getWalletInformation?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Transactions

get

Get transaction history of a given address.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

addressstringrequired

Identifier of target TON account in any form.

limitinteger · max: 100 · default: 10optional

Maximum number of transactions in response.

ltintegeroptional

Logical time of transaction to start with, must be sent with hash.

hashstringoptional

Hash of transaction to start with, in base64 or hex encoding , must be sent with lt.

to_ltinteger · default: 0optional

Logical time of transaction to finish with (to get tx from lt to to_lt).

archivalboolean · default: falseoptional

By default getTransaction request is processed by any available liteserver. If archival=true only liteservers with full history are used.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/getTransactions?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Address

get

Get state of a given address. State can be either unitialized, active or frozen.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

addressstringrequired

Identifier of target TON account in any form.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/getAddressState?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Address Balance

get

Get balance (in nanotons) of a given address.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

addressstringrequired

Identifier of target TON account in any form.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/getAddressBalance?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Pack Address

get

Convert an address from raw to human-readable format.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

addressstringrequired

Identifier of target TON account in raw form.

Example: 0:83DFD552E63729B472FCBCC8C45EBCC6691702558B68EC7527E1BA403A0F31A8

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/packAddress?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Unpack Address

get

Convert an address from human-readable to raw format.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

addressstringrequired

Identifier of target TON account in user-friendly form

Example: EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/unpackAddress?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Masterchain Info

get

Get up-to-date masterchain state.

Authorizations

APIKeyHeaderAPIKeyQuery

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/getMasterchainInfo' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Masterchain Block Signatures

get

Get up-to-date masterchain state.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

seqnointegerrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/getMasterchainBlockSignatures?seqno=1' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Shard Block Proof

get

Get merkle proof of shardchain block.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

workchainintegerrequired

Block workchain id

shardintegerrequired

Block shard id

seqnointegerrequired

Block seqno

from_seqnointegeroptional

Seqno of masterchain block starting from which proof is required. If not specified latest masterchain block is used.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/getShardBlockProof?workchain=1&shard=1&seqno=1' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Consensus Block

get

Get consensus block and its update timestamp.

Authorizations

APIKeyHeaderAPIKeyQuery

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/getConsensusBlock' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Lookup Block

get

Look up block by either seqno, lt or unixtime.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

workchainintegerrequired

Workchain id to look up block in

shardintegerrequired

Shard id to look up block in

seqnointegeroptional

Block's height

ltintegeroptional

Block's logical time

unixtimeintegeroptional

Block's unixtime

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/lookupBlock?workchain=1&shard=1' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Shards

get

Get shards information.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

seqnointegerrequired

Masterchain seqno to fetch shards of.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/shards?seqno=1' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Block Transactions

get

Get transactions of the given block.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

workchainintegerrequired

shardintegerrequired

seqnointegerrequired

root_hashstringoptional

file_hashstringoptional

after_ltintegeroptional

after_hashstringoptional

countinteger · default: 40optional

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/getBlockTransactions?workchain=1&shard=1&seqno=1' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Block Header

get

Get metadata of a given block.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

workchainintegerrequired

shardintegerrequired

seqnointegerrequired

root_hashstringoptional

file_hashstringoptional

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/getBlockHeader?workchain=1&shard=1&seqno=1' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Config Param

get

Get config by id.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

config_idintegerrequired

Config id

seqnointegeroptional

Masterchain seqno. If not specified, latest blockchain state will be used.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/getConfigParam?config_id=1' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Token Data

get

Get NFT or Jetton information.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

addressstringrequired

Address of NFT collection/item or Jetton master/wallet smart contract

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/getTokenData?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Try Locate Tx

get

Locate outcoming transaction of destination address by incoming message.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

sourcestringrequired

destinationstringrequired

created_ltintegerrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/tryLocateTx?source=text&destination=text&created_lt=1' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Try Locate Result Tx

get

Same as previous. Locate outcoming transaction of destination address by incoming message

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

sourcestringrequired

destinationstringrequired

created_ltintegerrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/tryLocateResultTx?source=text&destination=text&created_lt=1' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Try Locate Source Tx

get

Locate incoming transaction of source address by outcoming message.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

sourcestringrequired

destinationstringrequired

created_ltintegerrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/tryLocateSourceTx?source=text&destination=text&created_lt=1' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Detect Address

get

Get all possible address forms.

Authorizations

APIKeyHeaderAPIKeyQuery

Query parameters

addressstringrequired

Identifier of target TON account in any form.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v2/detectAddress?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Send Boc

post

Send serialized boc file: fully packed and serialized external message to blockchain.

Authorizations

APIKeyHeaderAPIKeyQuery

Body

bocstringrequired

b64 encoded bag of cells

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/v2/sendBoc' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "boc": "text"
  }'

application/json

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Send Boc Return Hash

post

Send serialized boc file: fully packed and serialized external message to blockchain. The method returns message hash.

Authorizations

APIKeyHeaderAPIKeyQuery

Body

bocstringrequired

b64 encoded bag of cells

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/v2/sendBocReturnHash' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "boc": "text"
  }'

application/json

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Send Query

post

Send query - unpacked external message. This method takes address, body and init-params (if any), packs it to external message and sends to network. All params should be boc-serialized.

Authorizations

APIKeyHeaderAPIKeyQuery

Body

addressstringrequired

Address in any format

bodystringrequired

b64-encoded boc-serialized cell with message body

init_codestring · default: ""optional

b64-encoded boc-serialized cell with init-code

init_datastring · default: ""optional

b64-encoded boc-serialized cell with init-data

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/v2/sendQuery' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "address": "text",
    "body": "text",
    "init_code": "text",
    "init_data": "text"
  }'

application/json

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Estimate Fee

post

Estimate fees required for query processing. body, init-code and init-data accepted in serialized format (b64-encoded).

Authorizations

APIKeyHeaderAPIKeyQuery

Body

addressstringrequired

Address in any format

bodystringrequired

b64-encoded cell with message body

init_codestring · default: ""optional

b64-encoded cell with init-code

init_datastring · default: ""optional

b64-encoded cell with init-data

ignore_chksigboolean · default: trueoptional

If true during test query processing assume that all chksig operations return True

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/v2/estimateFee' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "address": "text",
    "body": "text",
    "init_code": "text",
    "init_data": "text",
    "ignore_chksig": true
  }'

application/json

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Run Get Method

post

Run get method on smart contract.

Authorizations

APIKeyHeaderAPIKeyQuery

Body

addressstringrequired

Contract address

methodany ofrequired

Method name or method id

stackany[][]required

Array of stack elements: [['num',3], ['cell', cell_object], ['slice', slice_object]]

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/v2/runGetMethod' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "address": "text",
    "method": "text",
    "stack": [
      []
    ]
  }'

application/json

200

422

504

200

{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Jsonrpc Handler

post

All methods in the API are available through JSON-RPC protocol (spec).

Authorizations

APIKeyHeaderAPIKeyQuery

Body

methodstringrequired

paramsobject · default: {}optional

idstringoptional

jsonrpcstringoptional

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/v2/jsonRPC' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "method": "text",
    "params": {},
    "id": "text",
    "jsonrpc": "text"
  }'

application/json

200

422

504

200

{
  "ok": true,
  "result": null,
  "error": "text",
  "code": 1,
  "id": "text",
  "jsonrpc": "text"
}

Successful Response