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 basic information about the address: balance, code, data, last_transaction_id.

GET/api/v2/getAddressInformation

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/getAddressInformation?address=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

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/api/v2/getExtendedAddressInformation

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/getExtendedAddressInformation?address=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

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/api/v2/getWalletInformation

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/getWalletInformation?address=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Get Transactions

Get transaction history of a given address.

GET/api/v2/getTransactions

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/getTransactions?address=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Get Address Balance

Get balance (in nanotons) of a given address.

GET/api/v2/getAddressBalance

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/getAddressBalance?address=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Get Address

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

GET/api/v2/getAddressState

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/getAddressState?address=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Pack Address

Convert an address from raw to human-readable format.

GET/api/v2/packAddress

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/packAddress?address=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Unpack Address

Convert an address from human-readable to raw format.

GET/api/v2/unpackAddress

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/unpackAddress?address=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Get Masterchain Info

Get up-to-date masterchain state.

GET/api/v2/getMasterchainInfo

Authorization

APIKeyHeaderAPIKeyQuery

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/getMasterchainInfo', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Get Masterchain Block Signatures

Get up-to-date masterchain state.

GET/api/v2/getMasterchainBlockSignatures

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/getMasterchainBlockSignatures?seqno=0', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Get Shard Block Proof

Get merkle proof of shardchain block.

GET/api/v2/getShardBlockProof

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/getShardBlockProof?workchain=0&shard=0&seqno=0', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Get Consensus Block

Get consensus block and its update timestamp.

GET/api/v2/getConsensusBlock

Authorization

APIKeyHeaderAPIKeyQuery

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/getConsensusBlock', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Lookup Block

Look up block by either seqno, lt or unixtime.

GET/api/v2/lookupBlock

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/lookupBlock?workchain=0&shard=0', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Get Shards

Get shards information.

GET/api/v2/shards

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/shards?seqno=0', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Get Block Transactions

Get transactions of the given block.

GET/api/v2/getBlockTransactions

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/getBlockTransactions?workchain=0&shard=0&seqno=0', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Get Block Header

Get metadata of a given block.

GET/api/v2/getBlockHeader

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/getBlockHeader?workchain=0&shard=0&seqno=0', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Get Config Param

Get config by id.

GET/api/v2/getConfigParam

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/getConfigParam?config_id=0', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Get Token Data

Get NFT or Jetton information.

GET/api/v2/getTokenData

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/getTokenData?address=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Get Try Locate Tx

Locate outcoming transaction of destination address by incoming message.

GET/api/v2/tryLocateTx

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/tryLocateTx?source=text&destination=text&created_lt=0', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Get Try Locate Result Tx

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

GET/api/v2/tryLocateResultTx

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/tryLocateResultTx?source=text&destination=text&created_lt=0', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Get Try Locate Source Tx

Locate incoming transaction of source address by outcoming message.

GET/api/v2/tryLocateSourceTx

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/tryLocateSourceTx?source=text&destination=text&created_lt=0', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Detect Address

Get all possible address forms.

GET/api/v2/detectAddress

Authorization

APIKeyHeaderAPIKeyQuery

Query parameters

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/detectAddress?address=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Send Boc

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

POST/api/v2/sendBoc

Authorization

APIKeyHeaderAPIKeyQuery

Body

application/json

boc*Boc

b64 encoded bag of cells

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/sendBoc', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "boc": "text"
    }),
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Send Boc Return Hash

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

POST/api/v2/sendBocReturnHash

Authorization

APIKeyHeaderAPIKeyQuery

Body

application/json

boc*Boc

b64 encoded bag of cells

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/sendBocReturnHash', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "boc": "text"
    }),
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

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/api/v2/sendQuery

Authorization

APIKeyHeaderAPIKeyQuery

Body

application/json

address*Address

Address in any format

body*Body

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

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/sendQuery', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "address": "text",
      "body": "text"
    }),
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Estimate Fee

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

POST/api/v2/estimateFee

Authorization

APIKeyHeaderAPIKeyQuery

Body

application/json

address*Address

Address in any format

body*Body

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

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/estimateFee', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "address": "text",
      "body": "text"
    }),
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Run Get Method

Run get method on smart contract.

POST/api/v2/runGetMethod

Authorization

APIKeyHeaderAPIKeyQuery

Body

application/json

address*Address

Contract address

method*Method

Method name or method id

stringinteger

stack*Stack

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

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

stringarray of anyobject

errorError

codeCode

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/runGetMethod', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "address": "text",
      "method": "text",
      "stack": [
        []
      ]
    }),
});
const data = await response.json();

Response

200

{
  "ok": false,
  "result": "text",
  "error": "text",
  "code": 0
}

Jsonrpc Handler

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

POST/api/v2/jsonRPC

Authorization

APIKeyHeaderAPIKeyQuery

Body

application/json

method*Method

paramsParams

idId

jsonrpcJsonrpc

Response

200422504

Successful Response

Body

application/json

ok*Ok

resultResult

errorError

codeCode

id*Id

jsonrpcJsonrpc

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/jsonRPC', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "method": "text"
    }),
});
const data = await response.json();

Response

200

{
  "ok": false,
  "error": "text",
  "code": 0,
  "id": "text",
  "jsonrpc": "2.0"
}