diff --git a/docs.json b/docs.json index 132e21c8b..e90a96633 100644 --- a/docs.json +++ b/docs.json @@ -133,6 +133,16 @@ "directory": "ecosystem/api/toncenter/v3" } }, + { + "group": "Streaming API", + "tag": "v2", + "pages": [ + "ecosystem/api/toncenter/streaming/overview", + "ecosystem/api/toncenter/streaming/sse", + "ecosystem/api/toncenter/streaming/wss", + "ecosystem/api/toncenter/streaming/reference" + ] + }, { "group": "Nominator Pools API", "openapi": { diff --git a/ecosystem/api/toncenter/introduction.mdx b/ecosystem/api/toncenter/introduction.mdx index f0963faaa..02ff4f1f0 100644 --- a/ecosystem/api/toncenter/introduction.mdx +++ b/ecosystem/api/toncenter/introduction.mdx @@ -4,7 +4,7 @@ title: Introduction TON Center HTTP APIs: read blockchain data, query smart contracts, send transactions. - + Indexed database for traces, Jettons, NFTs, and historical queries. + + + Low-latency updates on subscriptions through SSE or WebSockets. + diff --git a/ecosystem/api/toncenter/streaming/overview.mdx b/ecosystem/api/toncenter/streaming/overview.mdx new file mode 100644 index 000000000..53065d1c5 --- /dev/null +++ b/ecosystem/api/toncenter/streaming/overview.mdx @@ -0,0 +1,106 @@ +--- +title: "Streaming API overview" +sidebarTitle: "Overview" +--- + +import { Aside } from '/snippets/aside.jsx'; + +The TON Center **Streaming API** (v2) provides developer access to TON Blockchain through [Server-Sent Events (SSE)](https://en.wikipedia.org/wiki/Server-sent_events) and [WebSockets](https://en.wikipedia.org/wiki/WebSocket). It delivers low-latency, real-time updates on transactions and actions observed on the TON blockchain. Clients can subscribe to updates for monitoring a wallet, some contract addresses, or a specific trace of transactions. + +Streaming API serves as a real-time, streaming version of the [indexed access layer (API v3)](/ecosystem/api/toncenter/v3/overview). Use it when building wallets, explorers, monitoring systems, or automation tools. + + + + + +## Event groups + +The Streaming API emits the following event groups: + +- Trace-based events: `transactions`, `actions`, `trace` +- State updates: `account_state_change` and `jettons_change` +- Invalidation signal: `trace_invalidated` + +The [event types section](/ecosystem/api/toncenter/streaming/reference#event-types) and [notification schemas section](/ecosystem/api/toncenter/streaming/reference#notification-schemas) provide the exact payload structure for each event. + +## Finality model + +Trace-based events carry a `finality` field according to their finality level: + +```json +"finality": "pending" | "confirmed" | "finalized" +``` + +Each trace moves through the following monotonic lifecycle: + +```mermaid +flowchart LR + pending --> confirmed --> finalized + pending --> trace_invalidated + confirmed --> trace_invalidated +``` + +- `pending` — result of emulation or speculative execution. This state can be invalidated (`trace_invalidated`). +- `confirmed` — trace or transactions are included in a candidate shard block. Rollback chance is very small, but still possible. +- `finalized` — committed in the masterchain and will not be updated nor invalidated. + +Non-trace events behave differently: + +- `account_state_change` and `jettons_change` are emitted only when `finality` field is set to either `confirmed` or `finalized`. +- `trace_invalidated` applies to previously emitted trace-based data and is not emitted after `finalized`. + +## Delivery behavior + +The `min_finality` field is used to control how early the server emits trace-based updates: + +- `pending` — receive every trace snapshot as it moves from `pending` to `confirmed` to `finalized`. +- `confirmed` — skip pure emulation results and start at `confirmed` or later. +- `finalized` — receive only finalized trace-based events. + +Choose the setting based on the tolerance for speculative data: + +- Use `pending` for the lowest latency. +- Use `confirmed` for lower rollback risk with near-real-time delivery. +- Use `finalized` when only settled data is acceptable. + +The [delivery semantics section](/ecosystem/api/toncenter/streaming/reference#delivery-semantics) and [event invalidation section](/ecosystem/api/toncenter/streaming/reference#event-invalidation) document the exact behavior for each event type. + +## Supported interfaces + +The Streaming API exposes two transports: SSE and a WebSocket. Choose either of the transports to proceed with its usage: + + + + Recommended for browser environments or clients that prefer HTTP streaming and a fixed subscription. + + + + Preferred for persistent, bidirectional communication with dynamic subscription patterns. + + + +## See also + +- [Notification reference](/ecosystem/api/toncenter/streaming/reference) +- [API key](/ecosystem/api/toncenter/get-api-key) +- [API authentication](/ecosystem/api/toncenter/v3-authentication) diff --git a/ecosystem/api/toncenter/streaming/reference.mdx b/ecosystem/api/toncenter/streaming/reference.mdx new file mode 100644 index 000000000..61a09295b --- /dev/null +++ b/ecosystem/api/toncenter/streaming/reference.mdx @@ -0,0 +1,240 @@ +--- +title: "Streaming API notification reference" +sidebarTitle: "Notification reference" +--- + +import { Aside } from '/snippets/aside.jsx'; + +## Event types + +Once a subscription is established, the server sends event messages (notifications) matching the selected `types` and `min_finality`. Each message is a JSON object representing a single event. + +The `type` field in each notification identifies the notification schema: + +- `"transactions"` — subscribe to transactions and their finality levels. +- `"actions"` — subscribe to certain actions by setting `action_types`. +- `"trace"` — subscribe to a transaction trace. +- `"account_state_change"` — emitted for each matching confirmed or finalized account transaction. +- `"jettons_change"` — emitted for each matching confirmed or finalized jetton wallet transaction. +- `"trace_invalidated"` — emitted when earlier trace data becomes invalid. + +## Notification schemas + +Trace-related notifications, such as `"transactions"`, `"actions"`, and `"trace"` are grouped by the trace. They use the same `trace_external_hash_norm` value across all events generated from one external message. + +Transactions and actions in the same trace are ordered by logical time (LT) in descending order. The `"trace"` event includes the full trace tree and a map of all transactions in that trace. + +### `"transactions"` + +Subscriptions that include `"transactions"` can receive multiple notifications for the same trace as finality increases. + +Trace is determined by its `trace_external_hash_norm`. + +| Field | Type | Description | +| -------------------------- | --------------- | ------------------------------------------------------------------------ | +| `type` | `string` | Always `"transactions"`. | +| `finality` | `string` | `"pending"`, `"confirmed"`, or `"finalized"`. | +| `trace_external_hash_norm` | `string` | Normalized external message hash for the trace. | +| `transactions` | `Transaction[]` | Transactions in the trace, ordered by descending logical time. | +| `address_book` | `object` | Optional mapping of addresses to a friendly format and a TON DNS domain. | +| `metadata` | `object` | Optional mapping of token addresses to metadata (jetton or NFT). | + +```jsonc title="Notification example" +{ + "type": "transactions", + "finality": "pending", + "trace_external_hash_norm": "E7...NORMALIZED_EXTERNAL_MSG_HASH", + "transactions": [ /* transaction objects */ ], + "address_book": { /* mapping of known addresses */ }, + "metadata": { /* mapping of known token addresses to metadata */ } +} +``` + +### `"actions"` + +Subscriptions that include `"actions"` can receive multiple notifications for the same trace as finality increases. + + + +Trace is determined by its `trace_external_hash_norm`. + +| Field | Type | Description | +| -------------------------- | ---------- | ------------------------------------------------------------------------ | +| `type` | `string` | Always `"actions"`. | +| `finality` | `string` | `"pending"`, `"confirmed"`, or `"finalized"`. | +| `trace_external_hash_norm` | `string` | Normalized external message hash for the trace. | +| `actions` | `Action[]` | Classified actions for the trace. | +| `address_book` | `object` | Optional mapping of addresses to a friendly format and a TON DNS domain. | +| `metadata` | `object` | Optional mapping of token addresses to metadata (jetton or NFT). | + + + +```jsonc title="Notification example" +{ + "type": "actions", + "finality": "confirmed", + "trace_external_hash_norm": "E7...NORMALIZED_EXTERNAL_MSG_HASH", + "actions": [ /* action objects */ ], + "address_book": { /* mapping of known addresses */ }, + "metadata": { /* mapping of known token addresses to metadata */ } +} +``` + +### `"trace"` + +Subscriptions that include `"trace"` receive trace-wide payloads. These payloads are not filtered by account address and include all transactions and actions in the trace. + +Trace is determined by its `trace_external_hash_norm`. + +| Field | Type | Description | +| -------------------------- | ----------- | ------------------------------------------------------------------------ | +| `type` | `string` | Always `"trace"`. | +| `finality` | `string` | `"pending"`, `"confirmed"`, or `"finalized"`. | +| `trace_external_hash_norm` | `string` | Normalized external message hash for the trace. | +| `trace` | `TraceNode` | Trace tree. | +| `transactions` | `object` | Map of transaction hash to transaction object. | +| `actions` | `Action[]` | Optional classified actions for the trace. | +| `address_book` | `object` | Optional mapping of addresses to a friendly format and a TON DNS domain. | +| `metadata` | `object` | Optional mapping of token addresses to metadata (jetton or NFT). | + +```jsonc title="Notification example" +{ + "type": "trace", + "finality": "confirmed", + "trace_external_hash_norm": "E7...NORMALIZED_EXTERNAL_MSG_HASH", + "trace": {}, + "transactions": { /* mappings */ }, + "actions": [ /* action objects */ ], + "address_book": { /* mapping of known addresses */ }, + "metadata": { /* mapping of known token addresses to metadata */ } +} +``` + +### `"account_state_change"` + +Subscriptions that include `"account_state_change"` receive notifications for each transaction executed on a subscribed account address. + +This event is emitted only for `"confirmed"` and `"finalized"` finality levels. + +| Field | Type | Description | +| ---------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `type` | `string` | Always `"account_state_change"`. | +| `finality` | `string` | `"confirmed"` or `"finalized"`. | +| `account` | `string` | Account address in raw format, e.g., `0:abc...RAW_ADDRESS`. | +| `state` | `AccountState` | Account state without full code and data [BoCs](/foundations/serialization/boc). Includes state hash, nanoToncoin balance, [account status](/foundations/status), data and code hashes. All hashes are given in the Base64 format. | + +```jsonc title="Notification example" +{ + "type": "account_state_change", + "finality": "finalized", + "account": "0:18AA...RAW_ADDRESS", + "state": { + "hash": "P0Gc...BASE64_HASH", + "balance": "42...NANOTON_BALANCE", + "account_status": "active", + "data_hash": "7qNe...BASE64_HASH", + "code_hash": "ow8E...BASE64_HASH" + } +} +``` + +### `"jettons_change"` + +Subscriptions that include `"jettons_change"` receive notifications for each transaction on a jetton wallet contract when the subscribed address is its own address or its owner's TON wallet address. + +This event is emitted only for `"confirmed"` and `"finalized"` finality levels. + +| Field | Type | Description | +| -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `type` | `string` | Always `"jettons_change"`. | +| `finality` | `string` | `"confirmed"` or `"finalized"`. | +| `jetton` | `JettonWallet` | Jetton wallet data. Includes its raw address, jetton balance, owner's raw address, jetton master (minter) raw address, and logical time of its last transaction. | +| `address_book` | `object` | Optional mapping of addresses to a friendly format and a TON DNS domain. | +| `metadata` | `object` | Optional mapping of token addresses to metadata (jetton or NFT). | + +```jsonc title="Notification example" +{ + "type": "jettons_change", + "finality": "finalized", + "jetton": { + "address": "0:88DA...RAW_ADDRESS", + "balance": "42...JETTON_BALANCE", + "owner": "0:18AA...RAW_ADDRESS", + "jetton": "0:B113...RAW_ADDRESS", + "last_transaction_lt": "61664...LT_UNIX_TIME", + }, + "address_book": { /* mapping of known addresses */ }, + "metadata": { /* mapping of known token addresses to metadata */ } +} +``` + +### `"trace_invalidated"` + +The `"trace_invalidated"` notification signals that previously emitted speculative or intermediate trace data is no longer valid. + +Typical causes include: + +- external message was not accepted by the blockchain; +- later state change invalidated previous emulation result; +- confirmed shard block was replaced by another block, and the trace did not end up in the finalized block. + +Trace in the notification is determined by its `trace_external_hash_norm`. + +| Field | Type | Description | +| -------------------------- | -------- | ----------------------------------------------------------- | +| `type` | `string` | Always `"trace_invalidated"`. | +| `trace_external_hash_norm` | `string` | Normalized external message hash for the invalidated trace. | + +```jsonc title="Notification example" +{ + "type": "trace_invalidated", + "trace_external_hash_norm": "E7...NORMALIZED_EXTERNAL_MSG_HASH" +} +``` + +Upon receiving this notification, remove any stored `"trace"`, `"transactions"`, and `"actions"` data for the affected `trace_external_hash_norm`. + +The `"trace_invalidated"` notification cannot be sent for the `"finalized"` finality level of the trace. + +## Delivery semantics + +| Type | Finality values | Delivery behavior | +| ---------------------- | ----------------------------------------- | ----------------------------------------------------------------------------- | +| `transactions` | `"pending"`, `"confirmed"`, `"finalized"` | Emitted per trace as finality increases. | +| `actions` | `"pending"`, `"confirmed"`, `"finalized"` | Emitted per trace as action classification and finality progress. | +| `trace` | `"pending"`, `"confirmed"`, `"finalized"` | Emitted per trace with the full trace payload. | +| `account_state_change` | `"confirmed"`, `"finalized"` | Emitted for each matching confirmed or finalized account transaction. | +| `jettons_change` | `"confirmed"`, `"finalized"` | Emitted for each matching confirmed or finalized jetton wallet transaction. | +| `trace_invalidated` | Not applicable | Emitted when earlier trace-based data [becomes invalid](#event-invalidation). | + +### `min_finality` behavior + +For trace-based events: + +- `min_finality = "pending"` returns `"pending"`, `"confirmed"`, and `"finalized"` snapshots. +- `min_finality = "confirmed"` skips pure emulation and starts at `"confirmed"` or later. +- `min_finality = "finalized"` returns only finalized trace-based events. + +For non-trace events: + +- `"account_state_change"` and `"jettons_change"` are emitted only with `"confirmed"` and `"finalized"` finality levels. + +## Event invalidation + +Subscriptions that allow speculative states can later receive `"trace_invalidated"`. If the finality level reaches `"finalized"`, the server is guaranteed not to emit `"trace_invalidated"` for the trace. + + + +## See also + +- [Streaming API overview](/ecosystem/api/toncenter/streaming/overview) +- [SSE](/ecosystem/api/toncenter/streaming/sse) +- [WebSocket](/ecosystem/api/toncenter/streaming/wss) +- [API key](/ecosystem/api/toncenter/get-api-key) +- [API authentication](/ecosystem/api/toncenter/v3-authentication) diff --git a/ecosystem/api/toncenter/streaming/sse.mdx b/ecosystem/api/toncenter/streaming/sse.mdx new file mode 100644 index 000000000..6216e2b8c --- /dev/null +++ b/ecosystem/api/toncenter/streaming/sse.mdx @@ -0,0 +1,162 @@ +--- +title: "Streaming API: Server-Sent Events" +sidebarTitle: "Server-Sent Events" +--- + +import { Aside } from '/snippets/aside.jsx'; + +[Server-Sent Events (SSE)](https://en.wikipedia.org/wiki/Server-sent_events) transport of the [Streaming API](/ecosystem/api/toncenter/streaming/overview) uses a single `POST` request to establish the connection and specify the subscription. No further messages are sent by the client on this connection. + +## Usage + +Send one `POST` request to the SSE endpoint with a JSON body that defines the subscription. + +### Endpoints + +- Mainnet: `https://toncenter.com/api/streaming/v2/sse` +- Testnet: `https://testnet.toncenter.com/api/streaming/v2/sse` + +### Request fields + + + One or more event types to receive: `transactions`, `actions`, `trace`, `trace_invalidated`, `account_state_change`, `jettons_change`. The [event types section](/ecosystem/api/toncenter/streaming/reference#event-types) and [notification schemas section](/ecosystem/api/toncenter/streaming/reference#notification-schemas) provide the exact payload structure for each event. + + + + Wallet or contract addresses to monitor. Accepts [valid TON address formats](/foundations/addresses/formats). Optional when subscribing only to a `"trace"`, otherwise required. + + + + Optional list of normalized external message hashes to monitor. Required when subscribing to a `"trace"`. + + + + Optional minimum finality: `"pending"`, `"confirmed"`, or `"finalized"`. Defaults to `"finalized"`. + + + + Optional. If `true`, includes address book data in supported notifications. + + + + Optional. If `true`, includes token metadata (jetton or NFT) in supported notifications. + + + + Optional action type filter. Applies only to `"actions"`. Refer to a list of [available action types in API v3](/ecosystem/api/toncenter/v3/actions-and-traces/get-actions#parameter-action-type). + + + + Optional list of action classification types supported by the client. Defaults to `["latest"]`. + + + + +- Include `"trace"` in `types` and provide `trace_external_hash_norms` to subscribe to a specific trace. +- Omit `addresses` when subscribing only to a `"trace"`. + +### Examples + +Lowest-latency stream of `"pending"` → `"confirmed"` → `"finalized"` finality levels: + +```http +POST https://toncenter.com/api/streaming/v2/sse +Content-Type: application/json +Accept: text/event-stream + +{ + "types": ["transactions", "actions"], + "addresses": ["EQC...ACCOUNT_ADDRESS", "0:abc...RAW_ADDRESS"], + "min_finality": "pending", + "include_address_book": true, + "include_metadata": false, + "action_types": ["jetton_transfer", "ton_transfer"] +} +``` + +Subscribing to a specific trace: + +```http +POST https://toncenter.com/api/streaming/v2/sse +Content-Type: application/json +Accept: text/event-stream + +{ + "types": ["trace"], + "trace_external_hash_norms": ["E7...NORMALIZED_EXTERNAL_MSG_HASH"], + "min_finality": "pending", + "include_address_book": true, + "include_metadata": true +} +``` + +Successful SSE subscriptions receive the following message from the server: + +```json +{"status": "subscribed"} +``` + +To keep the subscription alive, the server sends the following `keepalive` line every 15 seconds: + +```text +: keepalive\n\n +``` + +Ignore SSE lines that begin with `:`. + +## Known limitations + +### Rate limit on reconnect (429 error) + +If a client reconnects immediately after a disconnect, the previous connection may still be open for \~1 minute. The reconnect attempt receives a 429 error. Use exponential backoff or [an enterprise plan API key](/ecosystem/api/toncenter/get-api-key). + +### POST-only subscription + +Despite SSE typically using `GET` requests, Streaming API endpoints require a `POST` with the subscription JSON in the request body. + + + +### No invalidation signal for `account_state_change` or `jettons_change` + +If a `"confirmed"` account state or jetton balance update is later rolled back, no `"trace_invalidated"` notification is sent for these event types. + +When using `"account_state_change"` or `"jettons_change"` at `"confirmed"` finality, consider waiting for `"finalized"` for balance-critical flows. + +## Next steps + +- Skim the server [notification reference](/ecosystem/api/toncenter/streaming/reference) +- [Get an API key](/ecosystem/api/toncenter/get-api-key) diff --git a/ecosystem/api/toncenter/streaming/wss.mdx b/ecosystem/api/toncenter/streaming/wss.mdx new file mode 100644 index 000000000..9f708d671 --- /dev/null +++ b/ecosystem/api/toncenter/streaming/wss.mdx @@ -0,0 +1,200 @@ +--- +title: "Streaming API: WebSocket" +sidebarTitle: "WebSocket" +--- + +import { Aside } from '/snippets/aside.jsx'; + +[WebSocket](https://en.wikipedia.org/wiki/WebSocket) transport of the [Streaming API](/ecosystem/api/toncenter/streaming/overview) is the preferred interface for persistent and bidirectional communication with dynamic subscription patterns. + +## Usage + +Connect to the WebSocket endpoint, then send JSON messages for `subscribe`, `unsubscribe`, and `ping` operations. + +Each request may include an optional `id` field for request and response correlation. + +### Endpoints + +- Mainnet: `wss://toncenter.com/api/streaming/v2/ws` +- Testnet: `wss://testnet.toncenter.com/api/streaming/v2/ws` + +### Operations + +#### `subscribe` + +Subscribe operation replaces the entire subscription snapshot for the current connection. + + + Must be `"subscribe"`. + + + + One or more event types to receive: `transactions`, `actions`, `trace`, `trace_invalidated`, `account_state_change`, `jettons_change`. The [event types section](/ecosystem/api/toncenter/streaming/reference#event-types) and [notification schemas section](/ecosystem/api/toncenter/streaming/reference#notification-schemas) provide the exact payload structure for each event. + + + + Wallet or contract addresses to monitor. Accepts [valid TON address formats](/foundations/addresses/formats). May be left empty when subscribing only to a `"trace"`, otherwise required for non-trace event types. + + + + Optional list of normalized external message hashes to monitor. Required when subscribing to a `"trace"`. + + + + Optional minimum finality: `"pending"`, `"confirmed"`, or `"finalized"`. Defaults to `"finalized"`. + + + + Optional. If `true`, includes address book data in supported notifications. + + + + Optional. If `true`, includes token metadata (jetton or NFT) in supported notifications. + + + + Optional action type filter. Applies only to `"actions"`. Refer to a list of [available action types in API v3](/ecosystem/api/toncenter/v3/actions-and-traces/get-actions#parameter-action-type). + + + + Optional list of action classification types supported by the client. Defaults to `["latest"]`. + + + + Optional request identifier to match responses with requests. + + +```json title="Request example" +{ + "operation": "subscribe", + "types": ["transactions", "actions", "account_state_change", "jettons_change", "trace"], + "addresses": [""], + "trace_external_hash_norms": ["E7...NORMALIZED_EXTERNAL_MSG_HASH"], + "min_finality": "pending", + "include_address_book": true, + "include_metadata": false, + "action_types": ["jetton_transfer", "ton_transfer"], + "id": "1" +} +``` + +```json title="Successful response" +{"id": "1", "status": "subscribed"} +``` + +#### `unsubscribe` + +Unsubscribe operation removes one or more addresses or trace hashes from the active subscription. + + + Must be `"unsubscribe"`. + + + + Wallet or contract addresses to remove from monitoring. Accepts [valid TON address formats](/foundations/addresses/formats). + + + + List of normalized external message hashes to remove from monitoring. + + + + Optional request identifier to match responses with requests. + + +```json title="Request example" +{ + "operation": "unsubscribe", + "addresses": [""], + "trace_external_hash_norms": ["E7...NORMALIZED_EXTERNAL_MSG_HASH"], + "id": "2" +} +``` + +```json title="Successful response" +{"id": "2", "status": "unsubscribed"} +``` + +#### `ping` + +Ping operation serves as a `keepalive` or a connection health check. + + + Must be `"ping"`. + + + + Optional request identifier to match responses with requests. + + +It is recommended to send `ping` request every 15 seconds to keep the connection active. + +```json title="Request example" +{ + "operation": "ping", + "id": "ping-42" +} +``` + +```json title="Successful response" +{"id": "ping-42", "status": "pong"} +``` + +## Next steps + +- Skim the server [notification reference](/ecosystem/api/toncenter/streaming/reference) +- [Get an API key](/ecosystem/api/toncenter/get-api-key) diff --git a/ecosystem/api/toncenter/v2/overview.mdx b/ecosystem/api/toncenter/v2/overview.mdx index 0d5027b62..9c202e287 100644 --- a/ecosystem/api/toncenter/v2/overview.mdx +++ b/ecosystem/api/toncenter/v2/overview.mdx @@ -1,17 +1,19 @@ --- -title: Overview +title: API v2 overview +sidebarTitle: 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. +import { Aside } from '/snippets/aside.jsx'; -API v2 serves as a non-indexed access layer. +The TON Center **API v2** provides developer access to 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. -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 v2 serves as the 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. + + ## Base URLs @@ -23,11 +25,11 @@ to query data from liteservers and exposes it through a standard REST interface. API v2 uses semantic versioning in the format `a.b.c` (for example, `2.1.1`): -| Segment | Example | Meaning | -| ------- | ------- | ------- | +| 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. | +| **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 @@ -83,14 +85,11 @@ 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 +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). +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. See the [API v2](https://github.com/toncenter/ton-http-api) repository for setup instructions. diff --git a/ecosystem/api/toncenter/v3/overview.mdx b/ecosystem/api/toncenter/v3/overview.mdx index 9637619da..57a6c40b9 100644 --- a/ecosystem/api/toncenter/v3/overview.mdx +++ b/ecosystem/api/toncenter/v3/overview.mdx @@ -1,14 +1,19 @@ --- -title: Overview +title: API v3 overview +sidebarTitle: Overview --- -The TON Center API v3 provides developer access to the TON blockchain through an indexed data layer. -It allows applications to read blockchain data, run analytical queries, retrieve historical information, -and decode Jetton, NFT, and action data. +import { Aside } from '/snippets/aside.jsx'; + +The TON Center **API v3** provides developer access to TON Blockchain through an indexed data layer. It allows applications to read blockchain data, run analytical queries, retrieve historical information, and decode Jetton, NFT, and action data. API v3 serves as the indexed access layer. -It reads raw data from a node’s RocksDB storage, parses and decodes it, and stores it in PostgreSQL. +It reads raw data from a node's RocksDB storage, parses and decodes it, and stores it in PostgreSQL. + + ## Base URLs diff --git a/ecosystem/subsecond.mdx b/ecosystem/subsecond.mdx index ea320c6e6..3270d88bc 100644 --- a/ecosystem/subsecond.mdx +++ b/ecosystem/subsecond.mdx @@ -159,7 +159,7 @@ Confirm that the node version supports the new consensus. ### TON Center Streaming API v2 -TON Center Streaming API v2 provides: +TON Center [Streaming API v2][streaming] provides: - Push-based delivery of transaction status updates. - Four statuses: `"pending"`, `"confirmed"`, `"finalized"`, `"trace_invalidated"`. @@ -292,8 +292,8 @@ Perform the following tests to validate UX and wallet behavior. - [TON Core deployment progress, Telegram channel](https://t.me/toncore/99) - [TON Core R\&D technical overview, Telegram channel](https://t.me/toncore/98) - [UX approaches for sub-second finality, Telegraph](https://telegra.ph/New-Approaches-to-Blockchain-User-Experience-08-02) -- [Streaming API v2 specification, Gist](https://gist.github.com/dungeon-master-666/98db8d73e9cd9a1b7802bc06ded5b155) -- [TON Center API overview and endpoints][toncenter] +- [TON Center Streaming API v2][streaming] +- [TON Center overview and endpoints][toncenter] - [AppKit documentation][appkit] ## Get support @@ -302,3 +302,4 @@ Use the [sub-second finality support chat](https://t.me/subsecond_upgrade) for q [appkit]: /ecosystem/appkit/overview [toncenter]: /ecosystem/api/overview +[streaming]: /ecosystem/api/toncenter/streaming/overview