HTTP API

Getting Started

This documentation provides a comprehensive guide to using the TON HTTP API, including API endpoints, request and response formats, and error handling. Whether you're building a new application or integrating with an existing one, this documentation will help you get started with the TON HTTP API quickly and efficiently.

Get Address Information

get

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

Authorizations
Query parameters
addressstringrequired

Identifier of target TON account in any form.

Responses
curl -L \
  --url '/api/v2/getAddressInformation?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "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
Query parameters
addressstringrequired

Identifier of target TON account in any form.

Responses
curl -L \
  --url '/api/v2/getExtendedAddressInformation?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "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
Query parameters
addressstringrequired

Identifier of target TON account in any form.

Responses
curl -L \
  --url '/api/v2/getWalletInformation?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Transactions

get

Get transaction history of a given address.

Authorizations
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
curl -L \
  --url '/api/v2/getTransactions?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Address Balance

get

Get balance (in nanotons) of a given address.

Authorizations
Query parameters
addressstringrequired

Identifier of target TON account in any form.

Responses
curl -L \
  --url '/api/v2/getAddressBalance?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "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
Query parameters
addressstringrequired

Identifier of target TON account in any form.

Responses
curl -L \
  --url '/api/v2/getAddressState?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Pack Address

get

Convert an address from raw to human-readable format.

Authorizations
Query parameters
addressstringrequired

Identifier of target TON account in raw form.

Example: 0:83DFD552E63729B472FCBCC8C45EBCC6691702558B68EC7527E1BA403A0F31A8
Responses
curl -L \
  --url '/api/v2/packAddress?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Unpack Address

get

Convert an address from human-readable to raw format.

Authorizations
Query parameters
addressstringrequired

Identifier of target TON account in user-friendly form

Example: EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N
Responses
curl -L \
  --url '/api/v2/unpackAddress?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Masterchain Info

get

Get up-to-date masterchain state.

Authorizations
Responses
curl -L \
  --url '/api/v2/getMasterchainInfo' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Masterchain Block Signatures

get

Get up-to-date masterchain state.

Authorizations
Query parameters
seqnointegerrequired
Responses
curl -L \
  --url '/api/v2/getMasterchainBlockSignatures?seqno=1' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Shard Block Proof

get

Get merkle proof of shardchain block.

Authorizations
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
curl -L \
  --url '/api/v2/getShardBlockProof?workchain=1&shard=1&seqno=1' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Consensus Block

get

Get consensus block and its update timestamp.

Authorizations
Responses
curl -L \
  --url '/api/v2/getConsensusBlock' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Lookup Block

get

Look up block by either seqno, lt or unixtime.

Authorizations
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
curl -L \
  --url '/api/v2/lookupBlock?workchain=1&shard=1' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Shards

get

Get shards information.

Authorizations
Query parameters
seqnointegerrequired

Masterchain seqno to fetch shards of.

Responses
curl -L \
  --url '/api/v2/shards?seqno=1' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Block Transactions

get

Get transactions of the given block.

Authorizations
Query parameters
workchainintegerrequired
shardintegerrequired
seqnointegerrequired
root_hashstringoptional
file_hashstringoptional
after_ltintegeroptional
after_hashstringoptional
countinteger Β· default: 40optional
Responses
curl -L \
  --url '/api/v2/getBlockTransactions?workchain=1&shard=1&seqno=1' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Block Header

get

Get metadata of a given block.

Authorizations
Query parameters
workchainintegerrequired
shardintegerrequired
seqnointegerrequired
root_hashstringoptional
file_hashstringoptional
Responses
curl -L \
  --url '/api/v2/getBlockHeader?workchain=1&shard=1&seqno=1' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Config Param

get

Get config by id.

Authorizations
Query parameters
config_idintegerrequired

Config id

seqnointegeroptional

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

Responses
curl -L \
  --url '/api/v2/getConfigParam?config_id=1' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Get Token Data

get

Get NFT or Jetton information.

Authorizations
Query parameters
addressstringrequired

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

Responses
curl -L \
  --url '/api/v2/getTokenData?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "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
Query parameters
sourcestringrequired
destinationstringrequired
created_ltintegerrequired
Responses
curl -L \
  --url '/api/v2/tryLocateTx?source=text&destination=text&created_lt=1' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "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
Query parameters
sourcestringrequired
destinationstringrequired
created_ltintegerrequired
Responses
curl -L \
  --url '/api/v2/tryLocateResultTx?source=text&destination=text&created_lt=1' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "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
Query parameters
sourcestringrequired
destinationstringrequired
created_ltintegerrequired
Responses
curl -L \
  --url '/api/v2/tryLocateSourceTx?source=text&destination=text&created_lt=1' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Detect Address

get

Get all possible address forms.

Authorizations
Query parameters
addressstringrequired

Identifier of target TON account in any form.

Responses
curl -L \
  --url '/api/v2/detectAddress?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'
{
  "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
Body
bocstringrequired

b64 encoded bag of cells

Responses
curl -L \
  --request POST \
  --url '/api/v2/sendBoc' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "boc": "text"
  }'
{
  "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
Body
bocstringrequired

b64 encoded bag of cells

Responses
curl -L \
  --request POST \
  --url '/api/v2/sendBocReturnHash' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "boc": "text"
  }'
{
  "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
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
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"
  }'
{
  "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
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
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
  }'
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Successful Response

Run Get Method

post

Run get method on smart contract.

Authorizations
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
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": [
      []
    ]
  }'
{
  "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
Body
methodstringrequired
paramsobject Β· default: {}optional
idstringoptional
jsonrpcstringoptional
Responses
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"
  }'
{
  "ok": true,
  "result": null,
  "error": "text",
  "code": 1,
  "id": "text",
  "jsonrpc": "text"
}

Successful Response

PreviousTONNextIndexer API

Last updated

Was this helpful?