Authentication for API v2

Overview

The API v2 accepts an API key for all methods, including the JSON-RPC endpoint. Requests without an API key are limited to one request per second. To make more than one request per second, please include an API key.

The key can be sent either in an HTTP header or as a query parameter. Only one of these is needed per request.

To obtain an API key, see the TON Center API key guide.

Method	Location	Name
API key	Header	X-API-Key
API key	Query	api_key

Never expose the API key in client-side code or public repositories. Store keys in a secrets manager or environment variables, rotate them periodically, and generate a new key immediately if one is compromised.

Public hosts

Network	Host
Testnet	https://testnet.toncenter.com/api/v2
Mainnet	https://toncenter.com/api/v2

REST endpoint authentication

Header authentication

Send the API key in the X-API-Key header:

curl "https://testnet.toncenter.com/api/v2/getMasterchainInfo" \
  -H "X-API-Key: <API_KEY>"

Query parameter authentication

Pass the key as a query parameter named api_key:

curl "https://testnet.toncenter.com/api/v2/getMasterchainInfo?api_key=<API_KEY>"

Both forms are equivalent.

JSON-RPC endpoint authentication

Endpoint: POST /api/v2/jsonRPC

The same API key rules apply. Example using header authentication:

curl "https://testnet.toncenter.com/api/v2/jsonRPC" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <API_KEY>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getMasterchainInfo",
    "params": {}
  }'

Or using the query parameter:

curl "https://testnet.toncenter.com/api/v2/jsonRPC?api_key=<API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getMasterchainInfo",
    "params": {}
  }'

API key error codes

Status	Error	Meaning
401	API key does not exist	The provided key is invalid. Check for typos or generate a new key.
403	Network not allowed	The key was issued for a different network (e.g., testnet key on mainnet). Use a key matching the target network.
429	Ratelimit exceeded	Too many requests. Back off and retry, or use an API key for higher limits.