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
200

Successful Response

application/json
get
GET /api/v2/getAddressInformation?address=text HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

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
200

Successful Response

application/json
get
GET /api/v2/getExtendedAddressInformation?address=text HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

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
200

Successful Response

application/json
get
GET /api/v2/getWalletInformation?address=text HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

Get Transactions

get

Get transaction history of a given address.

Authorizations
Query parameters
addressstringRequired

Identifier of target TON account in any form.

limitinteger · max: 100Optional

Maximum number of transactions in response.

Default: 10
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_ltintegerOptional

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

Default: 0
archivalbooleanOptional

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

Default: false
Responses
200

Successful Response

application/json
get
GET /api/v2/getTransactions?address=text HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

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
200

Successful Response

application/json
get
GET /api/v2/getAddressBalance?address=text HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

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
200

Successful Response

application/json
get
GET /api/v2/getAddressState?address=text HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

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
200

Successful Response

application/json
get
GET /api/v2/packAddress?address=text HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

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
200

Successful Response

application/json
get
GET /api/v2/unpackAddress?address=text HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

Get Masterchain Info

get

Get up-to-date masterchain state.

Authorizations
Responses
200

Successful Response

application/json
get
GET /api/v2/getMasterchainInfo HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

Get Masterchain Block Signatures

get

Get up-to-date masterchain state.

Authorizations
Query parameters
seqnointegerRequired
Responses
200

Successful Response

application/json
get
GET /api/v2/getMasterchainBlockSignatures?seqno=1 HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

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
200

Successful Response

application/json
get
GET /api/v2/getShardBlockProof?workchain=1&shard=1&seqno=1 HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

Get Consensus Block

get

Get consensus block and its update timestamp.

Authorizations
Responses
200

Successful Response

application/json
get
GET /api/v2/getConsensusBlock HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

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
200

Successful Response

application/json
get
GET /api/v2/lookupBlock?workchain=1&shard=1 HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

Get Shards

get

Get shards information.

Authorizations
Query parameters
seqnointegerRequired

Masterchain seqno to fetch shards of.

Responses
200

Successful Response

application/json
get
GET /api/v2/shards?seqno=1 HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

Get Block Transactions

get

Get transactions of the given block.

Authorizations
Query parameters
workchainintegerRequired
shardintegerRequired
seqnointegerRequired
root_hashstringOptional
file_hashstringOptional
after_ltintegerOptional
after_hashstringOptional
countintegerOptionalDefault: 40
Responses
200

Successful Response

application/json
get
GET /api/v2/getBlockTransactions?workchain=1&shard=1&seqno=1 HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

Get Block Header

get

Get metadata of a given block.

Authorizations
Query parameters
workchainintegerRequired
shardintegerRequired
seqnointegerRequired
root_hashstringOptional
file_hashstringOptional
Responses
200

Successful Response

application/json
get
GET /api/v2/getBlockHeader?workchain=1&shard=1&seqno=1 HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

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
200

Successful Response

application/json
get
GET /api/v2/getConfigParam?config_id=1 HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

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
200

Successful Response

application/json
get
GET /api/v2/getTokenData?address=text HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

Get Try Locate Tx

get

Locate outcoming transaction of destination address by incoming message.

Authorizations
Query parameters
sourcestringRequired
destinationstringRequired
created_ltintegerRequired
Responses
200

Successful Response

application/json
get
GET /api/v2/tryLocateTx?source=text&destination=text&created_lt=1 HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

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
200

Successful Response

application/json
get
GET /api/v2/tryLocateResultTx?source=text&destination=text&created_lt=1 HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

Get Try Locate Source Tx

get

Locate incoming transaction of source address by outcoming message.

Authorizations
Query parameters
sourcestringRequired
destinationstringRequired
created_ltintegerRequired
Responses
200

Successful Response

application/json
get
GET /api/v2/tryLocateSourceTx?source=text&destination=text&created_lt=1 HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

Detect Address

get

Get all possible address forms.

Authorizations
Query parameters
addressstringRequired

Identifier of target TON account in any form.

Responses
200

Successful Response

application/json
get
GET /api/v2/detectAddress?address=text HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

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

Send Boc

post

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

Authorizations
Body
bocstringRequired

b64 encoded bag of cells

Responses
200

Successful Response

application/json
post
POST /api/v2/sendBoc HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 14

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

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
200

Successful Response

application/json
post
POST /api/v2/sendBocReturnHash HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 14

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

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_codestringOptional

b64-encoded boc-serialized cell with init-code

Default: ""
init_datastringOptional

b64-encoded boc-serialized cell with init-data

Default: ""
Responses
200

Successful Response

application/json
post
POST /api/v2/sendQuery HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 62

{
  "address": "text",
  "body": "text",
  "init_code": "",
  "init_data": ""
}
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

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_codestringOptional

b64-encoded cell with init-code

Default: ""
init_datastringOptional

b64-encoded cell with init-data

Default: ""
ignore_chksigbooleanOptional

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

Default: true
Responses
200

Successful Response

application/json
post
POST /api/v2/estimateFee HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 83

{
  "address": "text",
  "body": "text",
  "init_code": "",
  "init_data": "",
  "ignore_chksig": true
}
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Run Get Method

post

Run get method on smart contract.

Authorizations
Body
addressstringRequired

Contract address

methodany ofRequired

Method name or method id

stringOptional
or
integerOptional
Responses
200

Successful Response

application/json
post
POST /api/v2/runGetMethod HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "address": "text",
  "method": "text",
  "stack": [
    []
  ]
}
{
  "ok": true,
  "result": "text",
  "error": "text",
  "code": 1
}

Jsonrpc Handler

post

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

Authorizations
Body
methodstringRequired
paramsobject · ParamsOptionalDefault: {}
idstringOptional
jsonrpcstringOptional
Responses
200

Successful Response

application/json
post
POST /api/v2/jsonRPC HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 58

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

Last updated

Was this helpful?