ton-org · laviniat1996 · Oct 30, 2025 · Oct 30, 2025 · Oct 30, 2025 · Oct 31, 2025
diff --git a/docs.json b/docs.json
@@ -75,6 +75,7 @@
                 "pages": [
                   "ecosystem/api/toncenter/overview",
                   "ecosystem/api/toncenter/get-api-key",
+                  "ecosystem/api/toncenter/rate-limit",
                   {
                     "group": "API v2",
                     "openapi": {

diff --git a/ecosystem/api/toncenter/overview.mdx b/ecosystem/api/toncenter/overview.mdx
@@ -1,7 +1,139 @@
 ---
-title: "Overview"
+title: Overview
+description: Learn what the TON Center APIs provide and how to use them.
 ---
 
-import { Stub } from '/snippets/stub.jsx';
+The **TON Center API** provides developer access to the TON blockchain through REST and JSON-RPC endpoints.
+It allows applications to read blockchain data, run smart contract methods, and send transactions.
 
-<Stub issue="731" />
+TON Center serves as a public gateway to the TON network. It implements two types APIs, **API v2** and **API v3**, that correspond to the non-indexed and indexed access layers.
+
+Applications interact with the TON blockchain by connecting to a TON node.
+Since nodes communicate through the binary ADNL protocol, an intermediate layer
+is needed for web-based access. API v2 provides this bridge by using [`tonlib`](https://github.com/ton-blockchain/ton/tree/master/tonlib/tonlib)
+to query data from liteservers and exposes it
+through a standard REST interface. API v3 extends this model by reading raw data from a node’s
+RocksDB storage, parsing and decoding that data, and storing it in PostgreSQL.
+
+## Base URLs
+
+| API        | Mainnet                        | Testnet                                |
+| ---------- | ------------------------------ | -------------------------------------- |
+| **API v2** | `https://toncenter.com/api/v2` | `https://testnet.toncenter.com/api/v2` |
+| **API v3** | `https://toncenter.com/api/v3` | `https://testnet.toncenter.com/api/v3` |
+
+## Typical use cases
+
+### API v2
+
+- Query account balances and state
+- Run get-methods on smart contracts
+- Send or broadcast messages
+- Retrieve latest transactions and block information
+
+### API v3
+
+- Query historical transactions and traces
+- Retrieve decoded Jetton and NFT data
+- Run analytical or filtered searches across multiple accounts
+- Power explorers or reporting tools
+
+## Endpoints API v2
+
+| Category                      | Method                                | Description                                               |
+| ----------------------------- | ------------------------------------- | --------------------------------------------------------- |
+| **Accounts**                  | `GET /detectAddress`                  | Detect all address formats and return normalized versions |
+| **Accounts**                  | `GET /getAddressBalance`              | Get balance for an address                                |
+| **Accounts**                  | `GET /getAddressInformation`          | Get account info including balance and state              |
+| **Accounts**                  | `GET /getExtendedAddressInformation`  | Extended account info (wallet type, seqno, etc)           |
+| **Accounts**                  | `GET /getJettonBalances`              | Get Jetton balances for a wallet                          |
+| **Accounts**                  | `GET /getMasterchainInfoExt`          | Get extended masterchain info                             |
+| **Accounts**                  | `GET /getNftItemsByCollectionAddress` | Get NFT items by collection                               |
+| **Accounts**                  | `GET /getTokenData`                   | Get Jetton metadata by master address                     |
+| **Accounts**                  | `GET /packAddress`                    | Convert raw address to user-friendly format               |
+| **Accounts**                  | `GET /unpackAddress`                  | Convert user-friendly address to raw format               |
+| **Blocks**                    | `GET /getBlockHeader`                 | Get block header metadata                                 |
+| **Blocks**                    | `GET /getBlockTransactions`           | Get transactions in a block                               |
+| **Blocks**                    | `GET /getConfigParam`                 | Get specific config parameter                             |
+| **Blocks**                    | `GET /getConfigAll`                   | Get all config parameters                                 |
+| **Blocks**                    | `GET /getMasterchainBlockSignatures`  | Get masterchain block signatures                          |
+| **Blocks**                    | `GET /getMasterchainInfo`             | Get last masterchain block info                           |
+| **Blocks**                    | `GET /getRawBlockHeader`              | Get raw block header                                      |
+| **Blocks**                    | `GET /getRawMasterchainInfo`          | Get raw masterchain info                                  |
+| **Blocks**                    | `GET /getRawShardBlockHeader`         | Get raw shard block header                                |
+| **Blocks**                    | `GET /getTime`                        | Get server time                                           |
+| **Blocks**                    | `GET /lookupBlock`                    | Lookup block by seqno/lt/root hash                        |
+| **Config**                    | `GET /getConfigParam`                 | Get specific config parameter                             |
+| **Config**                    | `GET /getConfigAll`                   | Get all config parameters                                 |
+| **Transactions**              | `GET /getTransactions`                | Get account transactions                                  |
+| **Transactions**              | `GET /tryLocateSourceTx`              | Try to find source transaction by message hash            |
+| **Transactions**              | `GET /tryLocateResultTx`              | Try to find result transaction by message hash            |
+| **Messages and transactions** | `POST /sendBoc`                       | Send BoC to the network                                   |
+| **Messages and transactions** | `POST /sendBocReturnHash`             | Send BoC and return its hash                              |
+| **Messages and transactions** | `POST /sendQuery`                     | Send external query to liteserver                         |
+| **Messages and transactions** | `GET /tryLocateTx`                    | Try to find transaction by message hash                   |
+| **Smart contracts**           | `POST /runGetMethod`                  | Run a get-method on a smart contract                      |
+| **JSON-RPC**                  | `POST /jsonRPC`                       | Proxy JSON-RPC requests to liteservers                    |
+
+## Endpoints API v3
+
+| Category                   | Method                                    | Description                                                                |
+| -------------------------- | ----------------------------------------- | -------------------------------------------------------------------------- |
+| **Accounts**               | `GET /accounts`                           | List or search accounts with filters                                       |
+| **Accounts**               | `GET /accounts/{account_id}`              | Get account details by ID                                                  |
+| **Accounts**               | `GET /accounts/{account_id}/transactions` | List transactions for an account                                           |
+| **Accounts**               | `GET /accounts/{account_id}/actions`      | List high-level actions for an account (DEX, Jettons, NFTs, etc)           |
+| **Actions and traces**     | `GET /actions`                            | List decoded high-level actions like swaps, transfers, or stake operations |
+| **Actions and traces**     | `GET /traces`                             | List full transaction traces with filters and pagination                   |
+| **Actions and traces**     | `GET /emulateTrace`                       | Emulate a transaction trace for a given external message or BoC            |
+| **Actions and traces**     | `GET /emulateActions`                     | Classify emulated traces into actions                                      |
+| **Blockchain data**        | `GET /transactions/{hash}`                | Get transaction by hash                                                    |
+| **Blockchain data**        | `GET /transactionsByMessage`              | Find transactions by message hash                                          |
+| **Blockchain data**        | `GET /blocks/{workchain}/{shard}/{seqno}` | Get a specific block by coordinates                                        |
+| **Blockchain data**        | `GET /blocks`                             | Search or filter blocks with pagination                                    |
+| **Blockchain data**        | `GET /messages/{hash}`                    | Get message by hash                                                        |
+| **Blockchain data**        | `GET /messages`                           | Search messages with filters                                               |
+| **Blockchain data**        | `GET /validators`                         | Get current validators and info                                            |
+| **Blockchain data**        | `GET /masterchain`                        | Get masterchain status                                                     |
+| **Blockchain data**        | `GET /shards`                             | List active shards and their info                                          |
+| **Blockchain data**        | `GET /workchains`                         | List all configured workchains                                             |
+| **Jettons**                | `GET /jettons`                            | List all Jetton contracts                                                  |
+| **Jettons**                | `GET /jettons/{master}`                   | Get Jetton master contract info                                            |
+| **Jettons**                | `GET /jettons/{master}/holders`           | List holders of a Jetton                                                   |
+| **Jettons**                | `GET /jettons/{master}/transactions`      | Get Jetton transactions                                                    |
+| **NFTs**                   | `GET /nfts`                               | List NFTs (items or collections)                                           |
+| **NFTs**                   | `GET /nfts/{collection}`                  | Get NFT collection details                                                 |
+| **NFTs**                   | `GET /nfts/{collection}/{item}`           | Get specific NFT item details                                              |
+| **DNS**                    | `GET /dns/{domain}`                       | Resolve TON DNS records                                                    |
+| **Utils**                  | `GET /estimateFee`                        | Estimate fees for an external message                                      |
+| **Utils**                  | `GET /detectAddress`                      | Normalize and inspect address formats                                      |
+| **Stats and analytics**    | `GET /stats`                              | Retrieve aggregated network and protocol statistics                        |
+| **Legacy (v2-compatible)** | `POST /runGetMethod`                      | Run get-method                                                             |
+| **Legacy (v2-compatible)** | `POST /sendBoc`                           | Send BoC                                                                   |
+| **Legacy (v2-compatible)** | `POST /sendBocReturnHash`                 | Send BoC and return hash                                                   |
+| **Legacy (v2-compatible)** | `GET /getAddressInformation`              | Get address info                                                           |
+| **Legacy (v2-compatible)** | `GET /getTransactions`                    | Get transactions                                                           |
+
+## How to access the API
+
+Developers can access TON Center APIs either through hosted infrastructure managed by TON Center or by running their own instance.
+
+### Managed Service
+
+Hosted access uses TON Center’s managed infrastructure instead of running a personal node. This approach enables
+immediate network access without setup or maintenance.
+
+Requests without an API key are limited to a default rate of 1 request per second.
+
+To increase this limit or access private liteservers, generate an [API key](/ecosystem/api/toncenter/get-api-key) and [choose a plan](/ecosystem/api/toncenter/rate-limit).
+
+### Self-hosted service
+
+Run a self-hosted TON Center infrastructure for full control over performance and data retention.
+
+- [API v2](https://github.com/toncenter/ton-http-api)
+- [API v3](https://github.com/toncenter/ton-indexer)
+
+### Minimum recommended configuration
+
+16-core CPU, 128 GB RAM, 1 TB NVMe SSD, and 1 Gbps network connection.
diff --git a/ecosystem/api/toncenter/rate-limit.mdx b/ecosystem/api/toncenter/rate-limit.mdx
@@ -0,0 +1,60 @@
+---
+title: "Managed plans and rate limiting"
+description: "Understand TON Center API rate limits."
+---
+
+import {Aside} from "/snippets/aside.jsx";
+
+To ensure stability and fair access, TON Center applies rate limits to all API requests.\
+If an application exceeds these limits, the API returns a `429` response.
+
+Increase limits by [requesting an API key](/ecosystem/api/toncenter/get-api-key) and selecting a higher subscription plan.
+Without any API key, the default rate limit is 1 request per second.
+
+## Default limits
+
+| Plan           | Tokens per Network | Requests per Second | Notes                                                                                                       |
+| -------------- | ------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **Free**       | 1                  | 10                  | Shared liteservers, ideal for quick tests and small projects.                                               |
+| **Plus**       | 3                  | 25                  | Private liteservers for more consistent performance.                                                        |
+| **Advanced**   | 10                 | 100                 | Private infrastructure with priority routing.                                                               |
+| **Enterprise** | Custom             | Custom              | Tailored throughput and support. Contact [@toncenter\_support](https://t.me/toncenter_support) for details. |
+
+Rate limits apply per API token and per network (mainnet/testnet).
+
+<Aside>
+  Each token represents an individual API key used to authenticate requests.
+  Plans differ by how many tokens can be generated per network (mainnet and testnet).
+  For example, the "Free" plan allows 1 key per network, while higher plans provide multiple keys for separate apps or environments.
+</Aside>
+
+## Rate limit exceeded
+
+When requests are sent faster than the allowed rate limit, the TON Center API temporarily blocks new ones.
+A JSON response indicates the rate limit was exceeded:
+
+```json
+{
+  "ok": false,
+  "result": "Ratelimit exceed",
+  "code": 429
+}
+```
+
+When this occurs:
+
+- Stop sending new requests and wait a few seconds before retrying.
+- Implement exponential backoff to avoid repeated rate-limit violations.
+
+## Common mistakes
+
+If a paid plan is active but the rate remains 1 RPS:
+
+- Check that your API key is included correctly in your requests.
+  Requests without a valid API key are limited to 1 RPS, even if a subscription is active.
+
+- Verify the correct key is used for the intended environment (mainnet or testnet).
+  Each network requires its own key.
+
+Wait up to 10 minutes after upgrading the plan or changing the API key.
+Subscription and key updates can take several minutes to propagate across TON Center’s rate-limiting system.
diff --git a/resources/dictionaries/custom.txt b/resources/dictionaries/custom.txt
@@ -813,4 +813,27 @@ Yung
 Zakrevskis
 Zellic
 zerostate
+ZK-proof 
+bigl  
+bigr   
+texttt  
+textit  
+deserialisation  
+nssss 
+hanges
+lxxx
+xsss
+rxxssss
+rxxsssss
+rxxcccc
+xccc
+mscdf
+xysss
+ijk
+sss
+infty 
+analysed
+compromizing
+mathit
+toncenter
 ZK-proof