### Quick Start: Get Account Balance

Source: https://toncenter.ness.su/index

A basic example demonstrating how to initialize the TON Center REST client and fetch the balance of a TON address. This snippet uses the v2 accounts API.

```python
import asyncio

from toncenter.rest import ToncenterRestClient
from toncenter.types import Network
from toncenter.utils import to_amount


async def main() -> None:
    async with ToncenterRestClient(network=Network.MAINNET) as client:
        info = await client.v2.accounts.get_address_information(
            "EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2"
        )
        print(f"Balance: {to_amount(int(info.balance))} TON")


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Quick Example: Fetching Account Balance and Jettons

Source: https://toncenter.ness.su/rest/overview

Demonstrates how to use the ToncenterRestClient to fetch an account's TON balance using V2 and list its Jetton holdings using V3. Requires the toncenter library to be installed.

```python
import asyncio

from toncenter.rest import ToncenterRestClient
from toncenter.types import Network
from toncenter.utils import to_amount


async def main() -> None:
    async with ToncenterRestClient(network=Network.MAINNET) as client:
        # V2 — current account state from liteserver
        info = await client.v2.accounts.get_address_information(
            "EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2"
        )
        print(f"Balance: {to_amount(int(info.balance))} TON")

        # V3 — indexed jetton wallets
        jettons = await client.v3.jettons.get_jetton_wallets(
            owner_address=["EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2"]
        )
        for jw in jettons.jetton_wallets or []:
            print(f"Jetton: {jw.jetton} — {jw.balance}")


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Run Get Method Request Example

Source: https://toncenter.ness.su/api_v2/run_get_method_post

Example of a POST request to the /api/v2/runGetMethod endpoint. This is used to call a read-only method on a smart contract.

```yaml
POST /api/v2/runGetMethod
openapi: 3.1.1
info:
  title: TON HTTP API C++
  description: >
    This API enables HTTP access to TON blockchain - getting accounts and
    wallets information, looking up blocks and transactions, sending messages to
    the blockchain, calling get methods of smart contracts, and more.


    In addition to REST API, all methods are available through [JSON-RPC
    endpoint](#json%20rpc)  with `method` equal to method name and `params`
    passed as a dictionary.


    The response contains a JSON object, which always has a boolean field `ok`
    and either `error` or `result`. If `ok` equals true, the request was
    successful and the result of the query can be found in the `result` field.
    In case of an unsuccessful request, `ok` equals false and the error is
    explained in the `error`.


    API Key should be sent either as `api_key` query parameter or `X-API-Key`
    header
  version: 2.1.1
servers:
  - url: https://toncenter.com
    description: Mainnet
  - url: https://testnet.toncenter.com
    description: Testnet
security: []
tags:
  - name: utils
    description: Some useful methods
  - name: accounts
    description: Information about accounts
  - name: blocks
    description: Information about blocks
  - name: transactions
    description: Fetching and locating transactions
  - name: configuration
    description: Information about blockchain config
  - name: run method
    description: Run get-method of smart contracts
  - name: send
    description: Send data to blockchain
  - name: rpc
    description: JSON-RPC and POST endpoints
paths:
  /api/v2/runGetMethod:
    post:
      tags:
        - run method
        - rpc
      summary: Run Get Method
      description: Run get method of smart contract
      operationId: runGetMethod_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunGetMethodRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  result:
                    title: RunGetMethodResult
                    allOf:
                      - $ref: '#/components/schemas/RunGetMethodResult'
                required:
                  - ok
                  - result
        default:
          $ref: '#/components/responses/default'
components:
  schemas:
    RunGetMethodRequest:
      type: object
      additionalProperties: false
      required:
        - address
        - method
        - stack
      properties:
        address:
          $ref: '#/components/schemas/TonAddr'
        method:
          oneOf:
            - type: string
            - type: integer
              format: int32
        stack:
          type: array
          items:
            $ref: '#/components/schemas/LegacyStackEntry'
        seqno:
          type: integer
          format: int32
    RunGetMethodResult:
      type: object
      additionalProperties: false
      required:
        - '@type'
        - gas_used
        - stack
        - exit_code
        - block_id
        - last_transaction_id
      properties:
        '@type':
          type: string
          enum: 
            - smc.runResult
          default: smc.runResult
        gas_used:
          type: integer
          format: int64
        stack:
          type: array
          items:
            $ref: '#/components/schemas/LegacyStackEntry'
        exit_code:
          type: integer
          format: int32
        block_id:
          $ref: '#/components/schemas/TonBlockIdExt'
        last_transaction_id:
          $ref: '#/components/schemas/InternalTransactionId'
    TonAddr:
      type: string
      x-usrv-cpp-type: ton_http::types::ton_addr
    LegacyStackEntry:
      type: array
      items:
        oneOf:
          - type: string
          - type: integer
            format: int64
          - $ref: '#/components/schemas/LegacyStackEntryCell'
          - $ref: '#/components/schemas/TvmTuple'
            x-usrv-cpp-indirect: true
          - $ref: '#/components/schemas/TvmList'
            x-usrv-cpp-indirect: true
      minItems: 2
      maxItems: 2
    TonBlockIdExt:
      type: object
      additionalProperties: false
      properties:
        '@type':
          type: string
          enum: 
            - ton.blockIdExt
          default: ton.blockIdExt
        workchain:
          type: integer
        shard:
          type: string
          x-usrv-cpp-type: std::int64_t
        seqno:
          type: integer

```

--------------------------------

### TON Center API v2 - Get Token Data Example

Source: https://toncenter.ness.su/api_v2/get_token_data_get

Example of a request to the get_token_data endpoint to retrieve information about a specific token.

```http
GET /api_v2/get_token_data?address=EQCD39VS5fc82029VSfR2_16_0_1_0...&token_address=EQCD39VS5fc82029VSfR2_16_0_1_0... HTTP/1.1
Host: toncenter.ness.su
Content-Type: application/json
```

--------------------------------

### Get Actions

Source: https://toncenter.ness.su/api_v3/actions_get

Fetches a list of actions. You can control the level of detail for transactions, the number of results, the starting point, and the sorting order.

```APIDOC
## GET /actions

### Description
Retrieves a list of actions performed on the TON blockchain. Supports filtering by transaction details, pagination, and sorting.

### Method
GET

### Endpoint
/actions

### Query Parameters
- **transactions_full** (boolean) - Optional - If true, includes detailed transaction data for each action. Defaults to false.
- **limit** (integer) - Optional - The maximum number of actions to return. Defaults to 10.
- **offset** (integer) - Optional - The number of actions to skip from the beginning. Defaults to 0.
- **sort** (string) - Optional - The order in which to sort actions. Can be 'asc' or 'desc'. Defaults to 'desc'.

### Response
#### Success Response (200)
- **actions** (array) - An array of Action objects.
- **address_book** (object) - An address book mapping.
- **metadata** (object) - Metadata related to the response.

#### Response Example
{
  "actions": [
    {
      "accounts": ["string"],
      "action_id": "string",
      "details": {},
      "end_lt": "string",
      "end_utime": 0,
      "finality": 0,
      "start_lt": "string",
      "start_utime": 0,
      "success": true,
      "trace_end_lt": "string",
      "trace_end_utime": 0,
      "trace_external_hash": "string",
      "trace_external_hash_norm": "string",
      "trace_id": "string",
      "trace_mc_seqno_end": 0,
      "transactions": ["string"],
      "transactions_full": [{}],
      "type": "string"
    }
  ],
  "address_book": {},
  "metadata": {}
}

#### Error Response (400)
- **code** (integer) - The error code.
- **error** (string) - A description of the error.

#### Error Response Example
{
  "code": 0,
  "error": "string"
}
```

--------------------------------

### Run Get Method

Source: https://toncenter.ness.su/llms.txt

Runs a 'get' method of a smart contract.

```APIDOC
## POST /run_get_method

### Description
Run get method of smart contract.

### Method
POST

### Endpoint
/api_v2/run_get_method_post.md
```

--------------------------------

### Example Error Response: Ratelimit Exceeded

Source: https://toncenter.ness.su/api_v2/get_address_state_get

This example shows the response when the API rate limit has been exceeded.

```json
{
  "ok": false,
  "code": 429,
  "error": "...",
  "@extra": "..."
}
```

--------------------------------

### Example Error Response: Tonlib Timeout

Source: https://toncenter.ness.su/api_v2/get_address_state_get

This example demonstrates the response when the Tonlib service times out while processing the request.

```json
{
  "ok": false,
  "code": 504,
  "error": "...",
  "@extra": "..."
}
```

--------------------------------

### Run Get Method Std

Source: https://toncenter.ness.su/llms.txt

Provides a standardized way to run a 'get' method of a smart contract.

```APIDOC
## POST /run_get_method_std

### Description
Run get method of smart contract.

### Method
POST

### Endpoint
/api_v2/run_get_method_std_post.md
```

--------------------------------

### Run Get Method

Source: https://toncenter.ness.su/openapi/v3.yaml

Executes a get method of a smart contract. The stack supports 'num', 'cell', and 'slice' types.

```APIDOC
## POST /api/v3/runGetMethod

### Description
Run get method of smart contract. Stack supports only `num`, `cell` and `slice` types:
```
[
  {
    "type": "num",
    "value": "0x12a"
  },
  {
    "type": "cell",
    "value": "te6..." // base64 encoded boc with cell
  },
  {
    "type": "slice",
    "value": "te6..." // base64 encoded boc with slice
  }
]
```

### Method
POST

### Endpoint
/api/v3/runGetMethod

### Request Body
- **schema** - #/components/schemas/V2RunGetMethodRequest

### Response
#### Success Response (200)
- **schema** - #/components/schemas/V2RunGetMethodRequest

#### Error Response (400)
- **schema** - #/components/schemas/RequestError
```

--------------------------------

### Manual Session Management

Source: https://toncenter.ness.su/rest/guide

This example shows how to manually create and close a client session. Ensure you always close the session to release resources.

```python
from toncenter.rest import ToncenterRestClient
from toncenter.types import Network

client = ToncenterRestClient(network=Network.MAINNET)
await client.create_session()
try:
    balance = await client.v2.accounts.get_address_balance("EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2")
finally:
    await client.close_session()
```

--------------------------------

### Install TON Center Plugin Locally

Source: https://toncenter.ness.su/claude-plugin

Clone the repository and run the CLAude CLI with the plugin directory to install the TON Center plugin locally.

```bash
git clone https://github.com/nessshon/toncenter.git
claude --plugin-dir ./toncenter
```

--------------------------------

### Get Traces

Source: https://toncenter.ness.su/openapi/v3.yaml

Retrieves traces based on various filters including account address, trace ID, transaction hash, message hash, masterchain sequence number, or start time.

```APIDOC
## GET /api/v3/traces

### Description
Get traces by specified filter.

### Method
GET

### Endpoint
/api/v3/traces

### Parameters
#### Query Parameters
- **account** (string) - Query - List of account addresses to get transactions. Can be sent in hex, base64 or base64url form.
- **trace_id** (array of strings) - Query - Find trace by trace id.
- **tx_hash** (array of strings) - Query - Find trace by transaction hash.
- **msg_hash** (array of strings) - Query - Find trace by message hash.
- **mc_seqno** (integer) - Query - Query traces that was completed in masterchain block with given seqno.
- **start_utime** (integer) - Query - Query traces, which was finished *after* given timestamp.

### Response
#### Success Response (200)
- **schema** - #/components/schemas/TracesResponse

#### Error Response (400)
- **schema** - #/components/schemas/RequestError
```

--------------------------------

### Run Get Method with Stack Parameters

Source: https://toncenter.ness.su/llms.txt

Demonstrates how to call a smart contract's get method with various stack parameter types including numbers, cells, and slices. Ensure parameters are correctly base64 encoded if they are complex types like cells or slices.

```json
[
  { "type": "num", "value": "0x12a" },
  { "type": "cell", "value": "te6..." // base64 encoded boc with cell
  },
  { "type": "slice", "value": "te6..." // base64 encoded boc with slice
  }
]
```

--------------------------------

### Get Address State (GET)

Source: https://toncenter.ness.su/openapi/v2.yaml

Retrieves the state of a TON address using a GET request. Supports optional sequence number filtering.

```APIDOC
## GET /api/v2/getAddressState

### Description
Get address state.

### Method
GET

### Endpoint
/api/v2/getAddressState

### Parameters
#### Query Parameters
- **address** (string) - Required - The address to query.
- **seqnoOptional** (integer) - Optional - The sequence number to filter by.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **result** (object) - Contains the address state.
```

--------------------------------

### Example Error Response: Not a Token

Source: https://toncenter.ness.su/api_v2/get_address_state_get

This example shows the JSON response when the provided address is not a recognized Jetton or NFT contract.

```json
{
  "ok": false,
  "code": 409,
  "error": "Smart contract is not a Jetton or NFT",
  "@extra": "..."
}
```

--------------------------------

### Get Transactions

Source: https://toncenter.ness.su/llms.txt

Get transactions by specified filter.

```APIDOC
## GET /api_v3/transactions_get

### Description
Get transactions by specified filter.

### Method
GET

### Endpoint
/api_v3/transactions_get
```

--------------------------------

### Monitor Connection State Changes

Source: https://toncenter.ness.su/streaming/guide

Sets up an SSE connection and registers a callback function to print the connection state whenever it changes.

```python
from toncenter.streaming import ConnectionState

def on_state(state: ConnectionState) -> None:
    print(state.value)

sse = ToncenterSSE("YOUR_API_KEY", Network.MAINNET, on_state_change=on_state)
```

--------------------------------

### Get Traces

Source: https://toncenter.ness.su/llms.txt

Get traces by specified filter.

```APIDOC
## GET /api_v3/traces_get

### Description
Get traces by specified filter.

### Method
GET

### Endpoint
/api_v3/traces_get
```

--------------------------------

### Get Config All

Source: https://toncenter.ness.su/llms.txt

Retrieves all blockchain configuration parameters.

```APIDOC
## GET /get_config_all

### Description
Get all blockchain configuration parameters.

### Method
GET

### Endpoint
/api_v2/get_config_all_get.md
```

--------------------------------

### Get Messages

Source: https://toncenter.ness.su/llms.txt

Get messages by specified filters.

```APIDOC
## GET /api_v3/messages_get

### Description
Get messages by specified filters.

### Method
GET

### Endpoint
/api_v3/messages_get
```

--------------------------------

### Using Context Manager for Session

Source: https://toncenter.ness.su/rest/guide

This snippet demonstrates the recommended way to manage client sessions using Python's async context manager. The session is automatically created and closed.

```python
from toncenter.rest import ToncenterRestClient
from toncenter.types import Network

async with ToncenterRestClient(network=Network.MAINNET) as client:
    balance = await client.v2.accounts.get_address_balance("EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2")
```

--------------------------------

### Get Address Balance (GET)

Source: https://toncenter.ness.su/openapi/v2.yaml

Retrieves the balance of a TON address in nanotons using a GET request. Supports optional sequence number filtering.

```APIDOC
## GET /api/v2/getAddressBalance

### Description
Get address balance in nanotons.

### Method
GET

### Endpoint
/api/v2/getAddressBalance

### Parameters
#### Query Parameters
- **address** (string) - Required - The address to query.
- **seqnoOptional** (integer) - Optional - The sequence number to filter by.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **result** (object) - Contains the address balance.
  - **AddressBalance** (object) - Schema for address balance.
```

--------------------------------

### Initialize Client with Multiple API Keys for Rotation

Source: https://toncenter.ness.su/rest/guide

Use a list of ApiKey objects to enable automatic key rotation. Each ApiKey can have its own rps_limit. This is useful for managing rate limits across different key tiers.

```python
from toncenter.types import ApiKey

client = ToncenterRestClient(
    api_key=[
        ApiKey("free-key", rps_limit=10),
        ApiKey("plus-key", rps_limit=25),
    ],
    network=Network.MAINNET,
)
```

--------------------------------

### Get Wallet Information (GET)

Source: https://toncenter.ness.su/openapi/v2.yaml

Retrieves wallet-specific information about a TON address using a GET request. Supports optional sequence number filtering.

```APIDOC
## GET /api/v2/getWalletInformation

### Description
Get wallet-specific information about address.

### Method
GET

### Endpoint
/api/v2/getWalletInformation

### Parameters
#### Query Parameters
- **address** (string) - Required - The address to query.
- **seqnoOptional** (integer) - Optional - The sequence number to filter by.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **result** (object) - Contains the wallet information.
  - **WalletInformation** (object) - Schema for wallet information.
```

--------------------------------

### Run Get Method

Source: https://toncenter.ness.su/llms.txt

Run get method of smart contract. Stack supports only `num`, `cell` and `slice` types: ``` [ { "type": "num", "value": "0x12a" }, { "type": "cell", "value": "te6..." // base64 encoded boc with cell }, { "type": "slice", "value": "te6..." // base64 encoded boc with slice } ] ```

```APIDOC
## POST /api_v3/run_get_method_post

### Description
Run get method of smart contract. Stack supports only `num`, `cell` and `slice` types: ``` [ { "type": "num", "value": "0x12a" }, { "type": "cell", "value": "te6..." // base64 encoded boc with cell }, { "type": "slice", "value": "te6..." // base64 encoded boc with slice } ] ```

### Method
POST

### Endpoint
/api_v3/run_get_method_post
```

--------------------------------

### Get Address Information (GET)

Source: https://toncenter.ness.su/openapi/v2.yaml

Retrieves basic information about a TON address using a GET request. Supports optional sequence number filtering.

```APIDOC
## GET /api/v2/getAddressInformation

### Description
Get basic information about address.

### Method
GET

### Endpoint
/api/v2/getAddressInformation

### Parameters
#### Query Parameters
- **address** (string) - Required - The address to query.
- **seqnoOptional** (integer) - Optional - The sequence number to filter by.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **result** (object) - Contains the address information.
  - **AddressInformation** (object) - Schema for address information.
```

--------------------------------

### Get Extended Address Information (GET)

Source: https://toncenter.ness.su/openapi/v2.yaml

Retrieves extended information about a TON address using a GET request. Supports optional sequence number filtering.

```APIDOC
## GET /api/v2/getExtendedAddressInformation

### Description
Get extended information about address.

### Method
GET

### Endpoint
/api/v2/getExtendedAddressInformation

### Parameters
#### Query Parameters
- **address** (string) - Required - The address to query.
- **seqnoOptional** (integer) - Optional - The sequence number to filter by.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **result** (object) - Contains the extended address information.
  - **ExtendedAddressInformation** (object) - Schema for extended address information.
```

--------------------------------

### Get Pending Traces

Source: https://toncenter.ness.su/llms.txt

Get traces by specified filter.

```APIDOC
## GET /api_v3/pending_traces_get

### Description
Get traces by specified filter.

### Method
GET

### Endpoint
/api_v3/pending_traces_get
```

--------------------------------

### Get Pending Actions

Source: https://toncenter.ness.su/llms.txt

Get actions by specified filter.

```APIDOC
## GET /api_v3/pending_actions_get

### Description
Get actions by specified filter.

### Method
GET

### Endpoint
/api_v3/pending_actions_get
```

--------------------------------

### Get Vesting Contracts

Source: https://toncenter.ness.su/llms.txt

Get vesting contracts by specified filters.

```APIDOC
## GET /api_v3/vesting_get

### Description
Get vesting contracts by specified filters.

### Method
GET

### Endpoint
/api_v3/vesting_get
```

--------------------------------

### /api/v2/runGetMethod

Source: https://toncenter.ness.su/openapi/v2.yaml

Executes a 'get' method of a smart contract. This is a POST-only operation.

```APIDOC
## POST /api/v2/runGetMethod

### Description
Run get method of smart contract.

### Method
POST

### Endpoint
/api/v2/runGetMethod

### Request Body
- **RunGetMethodRequest** - Required - Schema for running a get method.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the request was successful.
- **result** (RunGetMethodResult) - The result of the get method execution.

### Request Example
```json
{
  "example": "RunGetMethodRequest"
}
```

### Response Example
```json
{
  "ok": true,
  "result": {
    "example": "RunGetMethodResult"
  }
}
```
```

--------------------------------

### Get Pending Transactions

Source: https://toncenter.ness.su/llms.txt

Get pending transactions by specified filter.

```APIDOC
## GET /api_v3/pending_transactions_get

### Description
Get pending transactions by specified filter.

### Method
GET

### Endpoint
/api_v3/pending_transactions_get
```

--------------------------------

### Get All Config

Source: https://toncenter.ness.su/api_v2/get_config_all_get

Fetches all blockchain configuration parameters. This endpoint can optionally accept a `seqno` query parameter to specify a block sequence number.

```APIDOC
## GET /api/v2/getConfigAll

### Description
Get all blockchain configuration parameters.

### Method
GET

### Endpoint
/api/v2/getConfigAll

### Parameters
#### Query Parameters
- **seqno** (integer) - Optional - Block seqno

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the request was successful.
- **result** (ConfigInfo) - Contains the configuration details.

### Response Example
```json
{
  "ok": true,
  "result": {
    "@type": "configInfo",
    "config": {
      "@type": "tvm.cell",
      "bytes": "base64_encoded_bytes"
    }
  }
}
```
```

--------------------------------

### Get Nft Items

Source: https://toncenter.ness.su/llms.txt

Get NFT items by specified filters.

```APIDOC
## GET /api_v3/nft_items_get

### Description
Get NFT items by specified filters.

### Method
GET

### Endpoint
/api_v3/nft_items_get
```

--------------------------------

### Get Nft Collections

Source: https://toncenter.ness.su/llms.txt

Get NFT collections by specified filters.

```APIDOC
## GET /api_v3/nft_collections_get

### Description
Get NFT collections by specified filters.

### Method
GET

### Endpoint
/api_v3/nft_collections_get
```

--------------------------------

### Install TON Center Plugin in Claude Code

Source: https://toncenter.ness.su/claude-plugin

Use these commands within Claude Code to add and install the TON Center plugin from the marketplace.

```bash
/plugin marketplace add nessshon/claude-plugins
/plugin install toncenter@nessshon-plugins
```