Overview
The API v3 accepts an API key for all methods. 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/v3 |
| Mainnet | https://toncenter.com/api/v3 |
REST endpoint authentication
Send the API key in the X-API-Key header:
curl "https://testnet.toncenter.com/api/v3/masterchainInfo" \
-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/v3/masterchainInfo?api_key=<API_KEY>"
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. |
