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.

PreviousTON NextIndexer API

Last updated 5 months ago

Was this helpful?

Get Address Information

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

get

/getAddressInformation

Authorizations

Query parameters

addressAddressrequired

Identifier of target TON account in any form.

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Get Extended Address Information

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.

get

/getExtendedAddressInformation

Authorizations

Query parameters

addressAddressrequired

Identifier of target TON account in any form.

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Get Wallet Information

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

get

/getWalletInformation

Authorizations

Query parameters

addressAddressrequired

Identifier of target TON account in any form.

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Get Transactions

Get transaction history of a given address.

get

/getTransactions

Authorizations

Query parameters

addressAddressrequired

Identifier of target TON account in any form.

limitLimit

Maximum number of transactions in response.

ltLt

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

hashHash

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

to_ltTo Lt

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

archivalArchival

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 -L \
  --url '/api/v2/getTransactions?address=text' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

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

Successful Response

Get Address Balance

Get balance (in nanotons) of a given address.

get

/getAddressBalance

Authorizations

Query parameters

addressAddressrequired

Identifier of target TON account in any form.

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Get Address

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

get

/getAddressState

Authorizations

Query parameters

addressAddressrequired

Identifier of target TON account in any form.

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Pack Address

Convert an address from raw to human-readable format.

get

/packAddress

Authorizations

Query parameters

addressAddressrequired

Identifier of target TON account in raw form.

Example: 0:83DFD552E63729B472FCBCC8C45EBCC6691702558B68EC7527E1BA403A0F31A8

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Unpack Address

Convert an address from human-readable to raw format.

get

/unpackAddress

Authorizations

Query parameters

addressAddressrequired

Identifier of target TON account in user-friendly form

Example: EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Get Masterchain Info

Get up-to-date masterchain state.

get

/getMasterchainInfo

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Get Masterchain Block Signatures

Get up-to-date masterchain state.

get

/getMasterchainBlockSignatures

Authorizations

Query parameters

seqnoSeqnorequired

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Get Shard Block Proof

Get merkle proof of shardchain block.

get

/getShardBlockProof

Authorizations

Query parameters

workchainWorkchainrequired

Block workchain id

shardShardrequired

Block shard id

seqnoSeqnorequired

Block seqno

from_seqnoFrom Seqno

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 -L \
  --url '/api/v2/getShardBlockProof?workchain=1&shard=1&seqno=1' \
  --header 'X-API-Key: YOUR_API_KEY'

200

422

504

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

Successful Response

Get Consensus Block

Get consensus block and its update timestamp.

get

/getConsensusBlock

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Lookup Block

Look up block by either seqno, lt or unixtime.

get

/lookupBlock

Authorizations

Query parameters

workchainWorkchainrequired

Workchain id to look up block in

shardShardrequired

Shard id to look up block in

seqnoSeqno

Block's height

ltLt

Block's logical time

unixtimeUnixtime

Block's unixtime

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Get Shards

Get shards information.

get

/shards

Authorizations

Query parameters

seqnoSeqnorequired

Masterchain seqno to fetch shards of.

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Get Block Transactions

Get transactions of the given block.

get

/getBlockTransactions

Authorizations

Query parameters

workchainWorkchainrequired

shardShardrequired

seqnoSeqnorequired

root_hashRoot Hash

file_hashFile Hash

after_ltAfter Lt

after_hashAfter Hash

countCount

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Get Block Header

Get metadata of a given block.

get

/getBlockHeader

Authorizations

Query parameters

workchainWorkchainrequired

shardShardrequired

seqnoSeqnorequired

root_hashRoot Hash

file_hashFile Hash

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Get Config Param

Get config by id.

get

/getConfigParam

Authorizations

Query parameters

config_idConfig Idrequired

Config id

seqnoSeqno

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

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Get Token Data

Get NFT or Jetton information.

get

/getTokenData

Authorizations

Query parameters

addressAddressrequired

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

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Get Try Locate Tx

Locate outcoming transaction of destination address by incoming message.

get

/tryLocateTx

Authorizations

Query parameters

sourceSourcerequired

destinationDestinationrequired

created_ltCreated Ltrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Get Try Locate Result Tx

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

get

/tryLocateResultTx

Authorizations

Query parameters

sourceSourcerequired

destinationDestinationrequired

created_ltCreated Ltrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Get Try Locate Source Tx

Locate incoming transaction of source address by outcoming message.

get

/tryLocateSourceTx

Authorizations

Query parameters

sourceSourcerequired

destinationDestinationrequired

created_ltCreated Ltrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Detect Address

Get all possible address forms.

get

/detectAddress

Authorizations

Query parameters

addressAddressrequired

Identifier of target TON account in any form.

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Send Boc

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

post

/sendBoc

Authorizations

Body

bocBocrequired

b64 encoded bag of cells

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Send Boc Return Hash

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

post

/sendBocReturnHash

Authorizations

Body

bocBocrequired

b64 encoded bag of cells

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Send Query

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.

post

/sendQuery

Authorizations

Body

addressAddressrequired

Address in any format

bodyBodyrequired

b64-encoded boc-serialized cell with message body

init_codeInit Code

b64-encoded boc-serialized cell with init-code

init_dataInit Data

b64-encoded boc-serialized cell with init-data

Responses

application/json

cURL

JavaScript

Python

HTTP

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":"","init_data":""}'

200

422

504

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

Successful Response

Estimate Fee

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

post

/estimateFee

Authorizations

Body

addressAddressrequired

Address in any format

bodyBodyrequired

b64-encoded cell with message body

init_codeInit Code

b64-encoded cell with init-code

init_dataInit Data

b64-encoded cell with init-data

ignore_chksigIgnore Chksig

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

Responses

application/json

cURL

JavaScript

Python

HTTP

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":"","init_data":"","ignore_chksig":true}'

200

422

504

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

Successful Response

Run Get Method

Run get method on smart contract.

post

/runGetMethod

Authorizations

Body

addressAddressrequired

Contract address

methodMethodrequired

Method name or method id

stackStackrequired

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

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response

Jsonrpc Handler

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

post

/jsonRPC

Authorizations

Body

methodMethodrequired

idId

jsonrpcJsonrpc

paramsParams

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

422

504

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

Successful Response