Skip to content

fix(api): apply styleguide-fixes #1864

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
aigerimu wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

fix(api): apply styleguide-fixes #1864

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0c04804
styleguide-fixes
aigerimu Feb 18, 2026
c86a327
Merge branch 'main' into apis-styleguide
aigerimu Feb 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions ecosystem/api/toncenter/v2-authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,8 @@ curl "https://testnet.toncenter.com/api/v2/jsonRPC?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. |
| Status | Error | Meaning |
|--------|--------------------------|------------------------------------------------------------------------------------------------------------------|
Copy link

@github-actions github-actions bot Feb 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[HIGH] Status column no longer right-aligned in v2 API key error table

In the v2 authentication documentation, the separator row for the Status column has been changed from a right-aligned numeric column definition (-----:) to a plain left-aligned definition (--------). This causes the HTTP status codes in the first column to be left-aligned, which regresses from the previous, more readable numeric alignment. The style guide requires numeric columns in tables to be right-aligned for easier scanning and comparison (see https://github.com/ton-org/docs/blob/main/contribute/style-guide-extended.mdx?plain=1#L890-L900 for the table alignment rule). The issue is introduced directly on the separator row at line 89, which is part of the PR diff.

Suggested change
|--------|--------------------------|------------------------------------------------------------------------------------------------------------------|
| -----: | ------------------------ | ----------------------------------------------------------------------------------------------------------------- |

Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!

| `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. |
97 changes: 45 additions & 52 deletions ecosystem/api/toncenter/v2/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,77 +2,72 @@
title: Overview
---

The TON Center API v2 provides developer access to the TON blockchain through
[REST](https://en.wikipedia.org/wiki/REST) and [JSON-RPC](https://en.wikipedia.org/wiki/JSON-RPC) endpoints.
It allows applications to read blockchain data, run smart contract methods, and send transactions.
The TON Center API v2 provides developer access to the TON blockchain through [REST](https://en.wikipedia.org/wiki/REST) and [JSON-RPC](https://en.wikipedia.org/wiki/JSON-RPC) endpoints. It allows applications to read blockchain data, run smart contract methods, and send transactions.

API v2 serves as a non-indexed access layer.
API v2 serves as a non-indexed access layer.

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.
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.

## Base URLs

| API | Mainnet | Testnet |
| ---------- | ------------------------------ | -------------------------------------- |
| **API v2** | `https://toncenter.com/api/v2` | `https://testnet.toncenter.com/api/v2` |
| API v2 | `https://toncenter.com/api/v2` | `https://testnet.toncenter.com/api/v2` |

## Versioning

API v2 uses semantic versioning in the format `a.b.c` (for example, `2.1.1`):

| Segment | Example | Meaning |
| ------- | ------- | ------- |
| **Major** | `2.x.x` | Fixed at `2` to avoid confusion ("API v2 v3.x.x"). Will not change. |
| **Minor** | `2.1.x` | Implementation variant: `0` = Python version, `1` = C++ version. |
| **Patch** | `2.1.1` | Bumped with every release on GitHub. |
| Major | `2.x.x` | Fixed at `2` to avoid confusion ("API v2 v3.x.x"). Will not change. |
| Minor | `2.1.x` | Implementation variant: `0` = Python version, `1` = C++ version. |
| Patch | `2.1.1` | Bumped with every release on GitHub. |

## Typical use cases

- Query account balances and state
- Run get-methods on smart contracts
- Send or broadcast messages
- Retrieve latest transactions and block information
- Query account balances and state
- Run get-methods on smart contracts
- Send or broadcast messages
- Retrieve latest transactions and block information

## Endpoints

{/* BEGIN_AUTO_GENERATED: API_V2_ENDPOINTS */}
| Category | Method | Description |
| -------- | ------ | ----------- |
| **Accounts** | [`GET /getAddressInformation`](/ecosystem/api/toncenter/v2/accounts/get-account-state-and-balance) | Get account state and balance |
| **Accounts** | [`GET /getExtendedAddressInformation`](/ecosystem/api/toncenter/v2/accounts/get-detailed-account-state-extended) | Get detailed account state (extended) |
| **Accounts** | [`GET /getWalletInformation`](/ecosystem/api/toncenter/v2/accounts/get-wallet-information) | Get wallet information |
| **Accounts** | [`GET /getTransactions`](/ecosystem/api/toncenter/v2/accounts/list-account-transactions) | List account transactions |
| **Accounts** | [`GET /getAddressBalance`](/ecosystem/api/toncenter/v2/accounts/get-account-balance-only) | Get account balance only |
| **Accounts** | [`GET /getAddressState`](/ecosystem/api/toncenter/v2/accounts/get-account-lifecycle-state) | Get account lifecycle state |
| **Accounts** | [`GET /packAddress`](/ecosystem/api/toncenter/v2/accounts/convert-raw-address-to-user-friendly-format) | Convert raw address to user-friendly format |
| **Accounts** | [`GET /unpackAddress`](/ecosystem/api/toncenter/v2/accounts/convert-user-friendly-address-to-raw-format) | Convert user-friendly address to raw format |
| **Accounts** | [`GET /getTokenData`](/ecosystem/api/toncenter/v2/accounts/get-nft-or-jetton-metadata) | Get NFT or Jetton metadata |
| **Accounts** | [`GET /detectAddress`](/ecosystem/api/toncenter/v2/accounts/detect-all-address-formats) | Detect all address formats |
| **Blocks** | [`GET /getMasterchainInfo`](/ecosystem/api/toncenter/v2/blocks/get-latest-masterchain-info) | Get latest masterchain info |
| **Blocks** | [`GET /getMasterchainBlockSignatures`](/ecosystem/api/toncenter/v2/blocks/get-masterchain-block-signatures) | Get masterchain block signatures |
| **Blocks** | [`GET /getShardBlockProof`](/ecosystem/api/toncenter/v2/blocks/get-shard-block-proof) | Get shard block proof |
| **Blocks** | [`GET /getConsensusBlock`](/ecosystem/api/toncenter/v2/blocks/get-latest-consensus-block) | Get latest consensus block |
| **Blocks** | [`GET /lookupBlock`](/ecosystem/api/toncenter/v2/blocks/look-up-block-by-height-lt-or-timestamp) | Look up block by height, LT, or timestamp |
| **Blocks** | [`GET /shards`](/ecosystem/api/toncenter/v2/blocks/get-shards-at-masterchain-seqno) | Get shards at masterchain seqno |
| **Blocks** | [`GET /getBlockTransactions`](/ecosystem/api/toncenter/v2/blocks/list-block-transactions) | List block transactions |
| **Blocks** | [`GET /getBlockTransactionsExt`](/ecosystem/api/toncenter/v2/blocks/list-block-transactions-extended-details) | List block transactions (extended details) |
| **Blocks** | [`GET /getBlockHeader`](/ecosystem/api/toncenter/v2/blocks/get-block-header-metadata) | Get block header metadata |
| **Blocks** | [`GET /getLibraries`](/ecosystem/api/toncenter/v2/blocks/get-smart-contract-libraries) | Get smart contract libraries |
| **Blocks** | [`GET /getOutMsgQueueSizes`](/ecosystem/api/toncenter/v2/blocks/get-outgoing-message-queue-sizes) | Get outgoing message queue sizes |
| **Transactions** | [`GET /tryLocateTx`](/ecosystem/api/toncenter/v2/transactions/locate-transaction-by-incoming-message) | Locate transaction by incoming message |
| **Transactions** | [`GET /tryLocateResultTx`](/ecosystem/api/toncenter/v2/transactions/locate-result-transaction-by-incoming-message) | Locate result transaction by incoming message |
| **Transactions** | [`GET /tryLocateSourceTx`](/ecosystem/api/toncenter/v2/transactions/locate-source-transaction-by-outgoing-message) | Locate source transaction by outgoing message |
| **JSON-RPC** | [`POST /jsonRPC`](/ecosystem/api/toncenter/v2/json-rpc/json-rpc-handler) | JSON-RPC handler |
| **Config** | [`GET /getConfigParam`](/ecosystem/api/toncenter/v2/config/get-single-config-parameter) | Get single config parameter |
| **Config** | [`GET /getConfigAll`](/ecosystem/api/toncenter/v2/config/get-all-config-parameters) | Get all config parameters |
| **Messages and transactions** | [`POST /sendBoc`](/ecosystem/api/toncenter/v2/messages-and-transactions/send-external-message-boc) | Send external message (BoC) |
| **Messages and transactions** | [`POST /sendBocReturnHash`](/ecosystem/api/toncenter/v2/messages-and-transactions/send-external-message-and-return-hash) | Send external message and return hash |
| **Messages and transactions** | [`POST /sendQuery`](/ecosystem/api/toncenter/v2/messages-and-transactions/send-unpacked-external-query) | Send unpacked external query |
| **Messages and transactions** | [`POST /estimateFee`](/ecosystem/api/toncenter/v2/messages-and-transactions/estimate-transaction-fees) | Estimate transaction fees |
| **Smart contracts** | [`POST /runGetMethod`](/ecosystem/api/toncenter/v2/smart-contracts/run-get-method-on-contract) | Run get-method on contract |
| Accounts | [`GET /getAddressInformation`](/ecosystem/api/toncenter/v2/accounts/get-account-state-and-balance) | Get account state and balance |
| Accounts | [`GET /getExtendedAddressInformation`](/ecosystem/api/toncenter/v2/accounts/get-detailed-account-state-extended) | Get detailed account state (extended) |
| Accounts | [`GET /getWalletInformation`](/ecosystem/api/toncenter/v2/accounts/get-wallet-information) | Get wallet information |
| Accounts | [`GET /getTransactions`](/ecosystem/api/toncenter/v2/accounts/list-account-transactions) | List account transactions |
| Accounts | [`GET /getAddressBalance`](/ecosystem/api/toncenter/v2/accounts/get-account-balance-only) | Get account balance only |
| Accounts | [`GET /getAddressState`](/ecosystem/api/toncenter/v2/accounts/get-account-lifecycle-state) | Get account lifecycle state |
| Accounts | [`GET /packAddress`](/ecosystem/api/toncenter/v2/accounts/convert-raw-address-to-user-friendly-format) | Convert raw address to user-friendly format |
| Accounts | [`GET /unpackAddress`](/ecosystem/api/toncenter/v2/accounts/convert-user-friendly-address-to-raw-format) | Convert user-friendly address to raw format |
| Accounts | [`GET /getTokenData`](/ecosystem/api/toncenter/v2/accounts/get-nft-or-jetton-metadata) | Get NFT or Jetton metadata |
| Accounts | [`GET /detectAddress`](/ecosystem/api/toncenter/v2/accounts/detect-all-address-formats) | Detect all address formats |
| Blocks | [`GET /getMasterchainInfo`](/ecosystem/api/toncenter/v2/blocks/get-latest-masterchain-info) | Get latest masterchain info |
| Blocks | [`GET /getMasterchainBlockSignatures`](/ecosystem/api/toncenter/v2/blocks/get-masterchain-block-signatures) | Get masterchain block signatures |
| Blocks | [`GET /getShardBlockProof`](/ecosystem/api/toncenter/v2/blocks/get-shard-block-proof) | Get shard block proof |
| Blocks | [`GET /getConsensusBlock`](/ecosystem/api/toncenter/v2/blocks/get-latest-consensus-block) | Get latest consensus block |
| Blocks | [`GET /lookupBlock`](/ecosystem/api/toncenter/v2/blocks/look-up-block-by-height-lt-or-timestamp) | Look up block by height, LT, or timestamp |
| Blocks | [`GET /shards`](/ecosystem/api/toncenter/v2/blocks/get-shards-at-masterchain-seqno) | Get shards at masterchain seqno |
| Blocks | [`GET /getBlockTransactions`](/ecosystem/api/toncenter/v2/blocks/list-block-transactions) | List block transactions |
| Blocks | [`GET /getBlockTransactionsExt`](/ecosystem/api/toncenter/v2/blocks/list-block-transactions-extended-details) | List block transactions (extended details) |
| Blocks | [`GET /getBlockHeader`](/ecosystem/api/toncenter/v2/blocks/get-block-header-metadata) | Get block header metadata |
| Blocks | [`GET /getLibraries`](/ecosystem/api/toncenter/v2/blocks/get-smart-contract-libraries) | Get smart contract libraries |
| Blocks | [`GET /getOutMsgQueueSizes`](/ecosystem/api/toncenter/v2/blocks/get-outgoing-message-queue-sizes) | Get outgoing message queue sizes |
| Transactions | [`GET /tryLocateTx`](/ecosystem/api/toncenter/v2/transactions/locate-transaction-by-incoming-message) | Locate transaction by incoming message |
| Transactions | [`GET /tryLocateResultTx`](/ecosystem/api/toncenter/v2/transactions/locate-result-transaction-by-incoming-message) | Locate result transaction by incoming message |
| Transactions | [`GET /tryLocateSourceTx`](/ecosystem/api/toncenter/v2/transactions/locate-source-transaction-by-outgoing-message) | Locate source transaction by outgoing message |
| JSON-RPC | [`POST /jsonRPC`](/ecosystem/api/toncenter/v2/json-rpc/json-rpc-handler) | JSON-RPC handler |
| Config | [`GET /getConfigParam`](/ecosystem/api/toncenter/v2/config/get-single-config-parameter) | Get single config parameter |
| Config | [`GET /getConfigAll`](/ecosystem/api/toncenter/v2/config/get-all-config-parameters) | Get all config parameters |
| Messages and transactions | [`POST /sendBoc`](/ecosystem/api/toncenter/v2/messages-and-transactions/send-external-message-boc) | Send external message (BoC) |
| Messages and transactions | [`POST /sendBocReturnHash`](/ecosystem/api/toncenter/v2/messages-and-transactions/send-external-message-and-return-hash) | Send external message and return hash |
| Messages and transactions | [`POST /sendQuery`](/ecosystem/api/toncenter/v2/messages-and-transactions/send-unpacked-external-query) | Send unpacked external query |
| Messages and transactions | [`POST /estimateFee`](/ecosystem/api/toncenter/v2/messages-and-transactions/estimate-transaction-fees) | Estimate transaction fees |
| Smart contracts | [`POST /runGetMethod`](/ecosystem/api/toncenter/v2/smart-contracts/run-get-method-on-contract) | Run get-method on contract |
{/* END_AUTO_GENERATED: API_V2_ENDPOINTS */}

## How to access the API
Expand All @@ -81,14 +76,12 @@ Developers can access API v2 either through hosted infrastructure managed by TON

### 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.
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 API v2 infrastructure for full control over performance and data retention.
See the [API v2](https://github.com/toncenter/ton-http-api) repository for setup instructions.
Run a self-hosted TON Center API v2 infrastructure for full control over performance and data retention. For setup instructions, use [API v2](https://github.com/toncenter/ton-http-api) repository.
8 changes: 4 additions & 4 deletions ecosystem/api/toncenter/v3-authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ Both forms are equivalent.
## 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. |
|--------|--------------------------|-------------------------------------------------------------------------------------------------------------------|
Copy link

@github-actions github-actions bot Feb 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[HIGH] Status column no longer right-aligned in v3 API key error table

In the v3 authentication documentation, the separator row for the Status column has also been changed from a right-aligned numeric column definition to a plain left-aligned one. As in the v2 document, this change left-aligns the HTTP status codes, reducing readability and violating the numeric-column alignment rule from the style guide. The regression is localized to the separator row at line 58, which lies within the PR diff and directly controls how the column is rendered. Keeping numeric status codes right-aligned is important for quickly scanning and comparing error codes.

Suggested change
|--------|--------------------------|-------------------------------------------------------------------------------------------------------------------|
| -----: | ------------------------ | ----------------------------------------------------------------------------------------------------------------- |

Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!

| `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. |
Loading
Loading