> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ton.org/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.ton.org/feedback
```json
{
"path": "/ecosystem/api/toncenter/v2/accounts/get-token-data",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Get token data
> Returns metadata for Jetton or NFT contracts. Automatically detects the contract type and returns appropriate fields. For Jetton masters: total supply, admin, metadata. For Jetton wallets: balance, owner. For NFT items: collection, owner, content. For NFT collections: item count, metadata.
## OpenAPI
````yaml get /api/v2/getTokenData
openapi: 3.1.1
info:
title: TON HTTP API C++
description: >
This API enables HTTP access to TON blockchain - getting accounts and
wallets information, looking up blocks and transactions, sending messages to
the blockchain, calling get methods of smart contracts, and more.
In addition to REST API, all methods are available through a JSON-RPC
endpoint with `method` equal to method name and `params` passed as a
dictionary.
The response contains a JSON object, which always has a boolean field `ok`
and either `error` or `result`. If `ok` equals true, the request was
successful and the result of the query can be found in the `result` field.
In case of an unsuccessful request, `ok` equals false and the error is
explained in the `error`.
API Key should be sent either as `api_key` query parameter or `X-API-Key`
header
version: 2.1.1
servers:
- url: https://toncenter.com
description: TON Mainnet
- url: https://testnet.toncenter.com
description: TON Testnet
security: []
tags:
- name: Accounts
description: Information about accounts
- name: Transactions
description: Fetching and locating transactions
- name: Blocks
description: Information about blocks
- name: Run method
description: Run get-method of smart contracts
- name: Send
description: Send data to blockchain
- name: Utils
description: Some useful methods
- name: Configuration
description: Information about blockchain config
- name: RPC
description: JSON-RPC and POST endpoints
paths:
/api/v2/getTokenData:
get:
tags:
- Accounts
summary: Get token data
description: >-
Returns metadata for Jetton or NFT contracts. Automatically detects the
contract type and returns appropriate fields. For Jetton masters: total
supply, admin, metadata. For Jetton wallets: balance, owner. For NFT
items: collection, owner, content. For NFT collections: item count,
metadata.
operationId: getTokenData_get
parameters:
- $ref: '#/components/parameters/address'
responses:
'200':
description: >-
Returns parsed token metadata for Jetton masters, Jetton wallets,
NFT collections, and NFT items.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenDataResponse'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'409':
$ref: '#/components/responses/409'
'422':
$ref: '#/components/responses/422_address'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500_token'
'504':
$ref: '#/components/responses/504'
security:
- APIKeyHeader: []
- APIKeyQuery: []
components:
parameters:
address:
name: address
in: query
required: true
schema:
$ref: '#/components/schemas/TonAddr'
description: The account address to query.
schemas:
TokenDataResponse:
type: object
additionalProperties: false
required:
- ok
- result
properties:
ok:
type: boolean
default: true
description: >-
Returns `true` if the request succeeded; otherwise `false`. See the
`error` field for details.
result:
$ref: '#/components/schemas/TokenData'
description: Response data. Present only when `ok` is `true`.
'@extra':
type: string
description: >-
Optional request ID that can be passed in the request and received
back in the response. Useful for matching async responses.
TonAddr:
type: string
x-usrv-cpp-type: ton_http::types::ton_addr
description: >-
Account address in [raw](/foundations/addresses/formats#raw-format)
format (e.g., `0:ca6e321c...`) or
[user-friendly](/foundations/addresses/formats#user-friendly-format)
format (e.g., `EQDKbjIcfM...`). All formats are automatically detected.
TokenData:
oneOf:
- $ref: '#/components/schemas/JettonMasterData'
- $ref: '#/components/schemas/JettonWalletData'
- $ref: '#/components/schemas/NftCollectionData'
- $ref: '#/components/schemas/NftItemData'
discriminator:
propertyName: '@type'
mapping:
ext.tokens.jettonMasterData:
$ref: '#/components/schemas/JettonMasterData'
ext.tokens.jettonWalletData:
$ref: '#/components/schemas/JettonWalletData'
ext.tokens.nftCollectionData:
$ref: '#/components/schemas/NftCollectionData'
ext.tokens.nftItemData:
$ref: '#/components/schemas/NftItemData'
description: >-
Token metadata returned by getTokenData. Can be a Jetton master, Jetton
wallet, NFT collection, or NFT item depending on which contract was
queried.
JettonMasterData:
type: object
additionalProperties: false
required:
- '@type'
- address
- contract_type
- total_supply
- mintable
- jetton_content
- jetton_wallet_code
properties:
'@type':
type: string
enum:
- ext.tokens.jettonMasterData
default: ext.tokens.jettonMasterData
description: >-
TonLib type identifier for Jetton master contract data. Refer to the
[token type
reference](/ecosystem/api/toncenter/v2-tonlib-types#token-types-ton-center-extensions)
for a full list.
address:
$ref: '#/components/schemas/TonAddr'
description: Contract address of this Jetton master.
contract_type:
type: string
enum:
- jetton_master
default: jetton_master
description: >-
Type of token contract: jetton_master, jetton_wallet,
nft_collection, or nft_item.
total_supply:
$ref: '#/components/schemas/Int256'
description: >-
Total tokens in circulation, in the smallest unit. Divide by
10^decimals for human-readable amount.
mintable:
type: boolean
description: >-
Returns `true` if new tokens can still be minted; `false` means the
supply is permanently capped.
admin_address:
$ref: '#/components/schemas/TonAddr'
description: >-
Admin address that can mint tokens or update metadata. Empty if
admin rights were revoked.
jetton_content:
$ref: '#/components/schemas/TokenContent'
description: 'Token metadata: name, symbol, decimals, description, and image URL.'
jetton_wallet_code:
$ref: '#/components/schemas/Bytes'
description: >-
Code used to deploy individual user wallets for this token. Used to
verify wallet authenticity.
description: >-
Jetton (fungible token) master contract data. Contains total supply,
whether minting is allowed, admin address, and token metadata (name,
symbol, decimals). This is the central contract that tracks the token.
JettonWalletData:
type: object
additionalProperties: false
required:
- '@type'
- address
- contract_type
- balance
- owner
- jetton
- jetton_wallet_code
properties:
'@type':
type: string
enum:
- ext.tokens.jettonWalletData
default: ext.tokens.jettonWalletData
description: >-
TonLib type identifier for Jetton wallet contract data. Refer to the
[token type
reference](/ecosystem/api/toncenter/v2-tonlib-types#token-types-ton-center-extensions)
for a full list.
address:
$ref: '#/components/schemas/TonAddr'
description: Contract address of this Jetton wallet.
contract_type:
type: string
enum:
- jetton_wallet
default: jetton_wallet
description: >-
Type of token contract: jetton_master, jetton_wallet,
nft_collection, or nft_item.
balance:
$ref: '#/components/schemas/Int256'
description: >-
The token balance in the Jetton's base units (smallest
denomination). To get the human-readable amount, divide by
10^decimals, where `decimals` is a metadata field on the Jetton
master contract (commonly 9, but varies per token). Refer to the
[Jetton overview](/standard/tokens/jettons/overview) for how Jetton
decimals are defined.
owner:
$ref: '#/components/schemas/TonAddr'
description: Wallet owner's address (the user who holds these tokens).
jetton:
$ref: '#/components/schemas/TonAddr'
description: Address of the Jetton master contract this wallet belongs to.
mintless_is_claimed:
type: boolean
description: >-
Returns `true` if the mintless jetton allocation has been claimed;
otherwise `false`.
jetton_wallet_code:
$ref: '#/components/schemas/Bytes'
description: >-
Wallet contract code. Should match the master contract's wallet code
to verify authenticity.
description: >-
Jetton wallet contract data. Each user has a separate wallet contract
for each token they hold. Contains the token balance, owner address, and
reference to the master contract.
NftCollectionData:
type: object
additionalProperties: false
required:
- '@type'
- address
- contract_type
- next_item_index
- collection_content
properties:
'@type':
type: string
enum:
- ext.tokens.nftCollectionData
default: ext.tokens.nftCollectionData
description: >-
TonLib type identifier for NFT collection contract data. Refer to
the [token type
reference](/ecosystem/api/toncenter/v2-tonlib-types#token-types-ton-center-extensions)
for a full list.
address:
$ref: '#/components/schemas/TonAddr'
description: Contract address of this NFT collection.
contract_type:
type: string
enum:
- nft_collection
default: nft_collection
description: >-
Type of token contract: jetton_master, jetton_wallet,
nft_collection, or nft_item.
next_item_index:
$ref: '#/components/schemas/Int256'
description: >-
Index that will be assigned to the next minted NFT. Also indicates
total items if minted sequentially.
owner_address:
$ref: '#/components/schemas/TonAddr'
description: Collection owner's address. Controls minting and metadata updates.
collection_content:
$ref: '#/components/schemas/TokenContent'
description: 'Collection metadata: name, description, and cover image.'
description: >-
NFT collection contract data. Contains the number of items minted,
collection owner, and collection metadata (name, description, image).
NftItemData:
type: object
additionalProperties: false
required:
- '@type'
- address
- contract_type
- init
- index
- content
properties:
'@type':
type: string
enum:
- ext.tokens.nftItemData
default: ext.tokens.nftItemData
description: >-
TonLib type identifier for NFT item contract data. Refer to the
[token type
reference](/ecosystem/api/toncenter/v2-tonlib-types#token-types-ton-center-extensions)
for a full list.
address:
$ref: '#/components/schemas/TonAddr'
description: Contract address of this NFT item.
contract_type:
type: string
enum:
- nft_item
default: nft_item
description: >-
Type of token contract: jetton_master, jetton_wallet,
nft_collection, or nft_item.
init:
type: boolean
description: >-
Returns `true` if this NFT item has been initialized (deployed);
otherwise `false`.
index:
$ref: '#/components/schemas/Int256'
description: This item's sequential index within its collection.
collection_address:
$ref: '#/components/schemas/TonAddr'
description: >-
Address of the NFT collection this item belongs to. Empty if
standalone NFT.
owner_address:
$ref: '#/components/schemas/TonAddr'
description: Current owner's address. Changes on each transfer.
content:
oneOf:
- $ref: '#/components/schemas/TokenContent'
- $ref: '#/components/schemas/DnsContent'
description: NFT item metadata and content (name, description, image URL).
description: >-
Individual NFT data. Contains the item index, collection reference,
current owner, and item-specific content/metadata.
Int256:
type: string
x-usrv-cpp-type: ton_http::types::int256
description: >-
A large integer represented as a string to avoid precision loss. Used
for balances and other values that may exceed JavaScript's safe integer
limit.
TokenContent:
type: object
additionalProperties: false
required:
- type
- data
properties:
type:
type: string
enum:
- onchain
- offchain
description: >-
Storage method for token (jetton) metadata content: `onchain`
(stored in contract data) or `offchain` (external URI).
data:
oneOf:
- type: string
- $ref: '#/components/schemas/TokenContentDict'
description: >-
Token metadata key-value pairs (name, symbol, decimals, image,
description).
Bytes:
type: string
x-usrv-cpp-type: ton_http::types::bytes
description: >-
Binary data encoded as base64. Used for serialized cells (BoC format),
message bodies, and smart contract code/data.
DnsContent:
type: object
additionalProperties: false
required:
- domain
- data
properties:
domain:
type: string
description: The resolved domain name.
data:
$ref: '#/components/schemas/DnsRecordSet'
description: Parsed DNS records for this domain.
TokenContentDict:
type: object
additionalProperties: true
DnsRecordSet:
type: object
additionalProperties: true
properties:
dns_next_resolver:
$ref: '#/components/schemas/DnsRecord'
description: Next resolver contract for subdomain lookups.
wallet:
$ref: '#/components/schemas/DnsRecord'
description: Wallet address associated with this domain.
site:
$ref: '#/components/schemas/DnsRecord'
description: Site hosting address (ADNL or TON Storage).
storage:
$ref: '#/components/schemas/DnsRecord'
description: TON Storage bag ID for files hosted under this domain.
DnsRecord:
oneOf:
- $ref: '#/components/schemas/DnsRecordStorageAddress'
- $ref: '#/components/schemas/DnsRecordSmcAddress'
- $ref: '#/components/schemas/DnsRecordAdnlAddress'
- $ref: '#/components/schemas/DnsRecordNextResolver'
discriminator:
propertyName: '@type'
mapping:
dns_storage_address:
$ref: '#/components/schemas/DnsRecordStorageAddress'
dns_smc_address:
$ref: '#/components/schemas/DnsRecordSmcAddress'
dns_adnl_address:
$ref: '#/components/schemas/DnsRecordAdnlAddress'
dns_next_resolver:
$ref: '#/components/schemas/DnsRecordNextResolver'
DnsRecordStorageAddress:
type: object
additionalProperties: false
required:
- '@type'
- bag_id
properties:
'@type':
type: string
enum:
- dns_storage_address
default: dns_storage_address
description: >-
TonLib type identifier for TON Storage DNS records. Refer to the
[TonLib type reference](/ecosystem/api/toncenter/v2-tonlib-types)
for a full list.
bag_id:
$ref: '#/components/schemas/TonHashHex'
description: >-
TON Storage bag identifier in hex, pointing to distributed file
storage.
DnsRecordSmcAddress:
type: object
additionalProperties: false
required:
- '@type'
- smc_addr
properties:
'@type':
type: string
enum:
- dns_smc_address
default: dns_smc_address
description: >-
TonLib type identifier for smart contract address DNS records. Refer
to the [TonLib type
reference](/ecosystem/api/toncenter/v2-tonlib-types) for a full
list.
smc_addr:
$ref: '#/components/schemas/SmcAddr'
description: Smart contract address associated with this DNS record.
DnsRecordAdnlAddress:
type: object
additionalProperties: false
required:
- '@type'
- adnl_addr
properties:
'@type':
type: string
enum:
- dns_adnl_address
default: dns_adnl_address
description: >-
TonLib type identifier for ADNL address DNS records. Refer to the
[TonLib type reference](/ecosystem/api/toncenter/v2-tonlib-types)
for a full list.
adnl_addr:
$ref: '#/components/schemas/TonHashHex'
description: >-
ADNL (Abstract Datagram Network Layer) address in hex, used for TON
Sites and services.
DnsRecordNextResolver:
type: object
additionalProperties: false
required:
- '@type'
- resolver
properties:
'@type':
type: string
enum:
- dns_next_resolver
default: dns_next_resolver
description: >-
TonLib type identifier for next-resolver DNS records. Refer to the
[TonLib type reference](/ecosystem/api/toncenter/v2-tonlib-types)
for a full list.
resolver:
$ref: '#/components/schemas/SmcAddr'
description: Smart contract address of the next DNS resolver in the chain.
TonHashHex:
type: string
x-usrv-cpp-type: ton_http::types::ton_hash_hex
description: A 256-bit hash in hexadecimal format. Exactly 64 characters (0-9, a-f).
SmcAddr:
type: object
additionalProperties: false
required:
- '@type'
- workchain_id
- address
properties:
'@type':
type: string
enum:
- addr_std
default: addr_std
description: >-
TonLib type identifier for standard smart contract addresses. Refer
to the [TonLib type
reference](/ecosystem/api/toncenter/v2-tonlib-types) for a full
list.
workchain_id:
type: integer
format: int32
description: Workchain ID (`0` for basechain, `-1` for masterchain).
address:
$ref: '#/components/schemas/TonHashHex'
description: Account identifier as a 64-character hex string.
responses:
'401':
description: API key does not exist. Check for typos or generate a new key.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- ok
- code
- error
properties:
ok:
type: boolean
const: false
description: Always `false` for error responses.
code:
type: integer
const: 401
description: HTTP status code `401`.
error:
type: string
enum:
- API key does not exist
'@extra':
type: string
description: Extra data passed through from the request.
example:
ok: false
code: 401
error: API key does not exist
'403':
description: >-
API key is not allowed for this network (e.g. testnet key used on
mainnet).
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- ok
- code
- error
properties:
ok:
type: boolean
const: false
description: Always `false` for error responses.
code:
type: integer
const: 403
description: HTTP status code `403`.
error:
type: string
enum:
- Network not allowed
'@extra':
type: string
description: Extra data passed through from the request.
example:
ok: false
code: 403
error: Network not allowed
'409':
description: Resource exists but is the wrong type.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- ok
- code
- error
properties:
ok:
type: boolean
const: false
description: Always `false` for error responses.
code:
type: integer
const: 409
description: HTTP status code `409`.
error:
type: string
enum:
- Smart contract is not Jetton or NFT
'@extra':
type: string
description: Extra data passed through from the request.
example:
ok: false
code: 409
error: Smart contract is not Jetton or NFT
'429':
description: >-
Rate limit exceeded. Back off and retry, or use an API key for higher
limits.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- ok
- code
- error
properties:
ok:
type: boolean
const: false
description: Always `false` for error responses.
code:
type: integer
const: 429
description: HTTP status code `429`.
error:
type: string
enum:
- Ratelimit exceeded
'@extra':
type: string
description: Extra data passed through from the request.
example:
ok: false
code: 429
error: Ratelimit exceeded
'504':
description: Timeout waiting for liteserver response.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- ok
- code
- error
properties:
ok:
type: boolean
const: false
description: Always `false` for error responses.
code:
type: integer
const: 504
description: HTTP status code `504`.
error:
type: string
enum:
- LITE_SERVER_NETWORK timeout
'@extra':
type: string
description: Extra data passed through from the request.
example:
ok: false
code: 504
error: LITE_SERVER_NETWORK timeout
422_address:
description: Invalid address or `seqno` parameter.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- ok
- code
- error
properties:
ok:
type: boolean
const: false
description: Always `false` for error responses.
code:
type: integer
const: 422
description: HTTP status code `422`.
error:
type: string
enum:
- empty address
- failed to parse address
- failed to parse seqno
- seqno should be positive
'@extra':
type: string
description: Extra data passed through from the request.
example:
ok: false
code: 422
error: empty address
500_token:
description: Failed to retrieve or parse token data.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- ok
- code
- error
properties:
ok:
type: boolean
const: false
description: Always `false` for error responses.
code:
type: integer
const: 500
description: HTTP status code `500`.
error:
type: string
enum:
- Failed to unpack token data
- Invalid uri
- missing uri field in offchain data
- failed to serialize TokenData
- Exit code != 0
- Stack size < 5
'@extra':
type: string
description: Extra data passed through from the request.
example:
ok: false
code: 500
error: Failed to unpack token data
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: X-API-Key
description: >-
API key header of the form `X-API-Key: `, where `` is the
API key. Requests without a key are limited to 1 RPS. Refer to the
[authentication guide](/ecosystem/api/toncenter/v2-authentication) for
details.
APIKeyQuery:
type: apiKey
in: query
name: api_key
description: >-
API key query parameter of the form `?api_key=`, where ``
is the API key. Equivalent to the header method. Refer to the
[authentication guide](/ecosystem/api/toncenter/v2-authentication) for
details.
````