constant data
// example c7
// placeholder for simplicity
0 tuple 0x076ef1ea , 1 tuple constant c7
// execute method 97865
97865 code data c7 runvmctx .s
// result: 123 0 C{96A296D224F285C67BEE93C30F8A309157F0DAA35DC5B87E410B78630A09CFC7}
// where:
// 123 is the value returned by the get method
// 0 is the exit code
// C{...} is a new data cell
```
Note that if the get method uses some values from c7, for example with instructions such as `NOW` or `MYCODE`, the c7 tuple should be populated according to its [structure](/blockchain-basics/tvm/registers#c7-%E2%80%94-environment-information-and-global-variables).
### Decentralized way [#decentralized-way]
The process of fetching the actual contract state and initializing c7 can be handled by [liteserver](/blockchain-basics/nodes/overview) for easier execution. To execute a get method via liteserver, the request follows the [`liteServer.runSmcMethod` TL schema](https://github.com/ton-blockchain/ton/blob/f58297f1b668c7b49e8b30b65062951ca7c18acc/tl/generate/scheme/lite_api.tl#L90).
In that request, `params:bytes` is a [BoC](/blockchain-basics/primitives/serialization/boc) of a serialized [`VmStack`](https://github.com/ton-blockchain/ton/blob/f58297f1b668c7b49e8b30b65062951ca7c18acc/crypto/block/block.tlb#L891) object containing the stack with arguments.
The response follows the [liteServer.runMethodResult TL schema](https://github.com/ton-blockchain/ton/blob/f58297f1b668c7b49e8b30b65062951ca7c18acc/tl/generate/scheme/lite_api.tl#L39). Apart from the values used for initialization and proofs, the result is included as `result:mode.2?bytes`, which is a BoC of a serialized `VmStack` object, similarly to the request.
An example execution via liteclient that handles serialization:
```text
runmethod UQBKgXCNLPexWhs2L79kiARR1phGH1LwXxRbNsCFF9doczSI get_public_key
```
Result:
```text
arguments: [ 78748 ]
result: [ 37001869727465363790964079650574219024351072622925678701060821828351030750605 ]
```
### High-level API [#high-level-api]
The easiest path is using a high-level API, such as [TON Center](/applications/api/toncenter/introduction). It has a [`/api/v3/runGetMethod`](/applications/api/toncenter/v3/apiv2/run-get-method) endpoint that takes a smart contract address, a get method name, and arguments and returns the resulting stack. Example usage:
```bash
curl -X 'POST' \
'https://toncenter.com/api/v3/runGetMethod' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"address": "EQBG-g6ahkAUGWpefWbx-D_9sQ8oWbvy6puuq78U2c4NUDFS",
"method": "get_nft_address_by_index",
"stack": [
{
"type": "num",
"value": "123"
}
]
}'
```
The result for this call is presented below. The stack in this case contains a single cell element in BoC format.
```text
{
"gas_used": 4049,
"exit_code": 0,
"stack": [
{
"type": "cell",
"value": "te6cckEBAQEAJAAAQ4AVoN3BhVDLKet4AYoVxOHz8WkaFncQfg/M79YWJEV4pxDg5fQi"
}
]
}
```
# Initialization (/blockchain-basics/tvm/initialization)
## Initialization of `cc`, `cp`, and gas limits [#initialization-of-cc-cp-and-gas-limits]
* The original `cc`, current continuation, is initialized using the cell slice created from the `code` section of the smart contract. If the account is frozen or uninitialized, the code must be provided in the `init` field of the incoming message.
* The `cp`, current TVM codepage, is set to the default value of 0.
* The gas limit values are initialized based on the results of the [credit phase](/blockchain-basics/primitives/phases).
## Registers initialization [#registers-initialization]
For more info about registers, take a look at [Registers](/blockchain-basics/tvm/registers)
* `c0`: `Quit` — extraordinary continuation which terminates TVM with exit code `0`.
* `c1`: `Quit` — extraordinary continuation which terminates TVM with exit code `1`. Both exit codes `0` and `1` are considered successful terminations of TVM.
* `c2`: `ExcQuit` — extraordinary continuation which terminates TVM with an exception. In this case, the exit code is an exception number.
* `c3`: root cell of code currently executing in TVM.
* `c4`: root cell of account data.
* `c5`: empty cell.
* `c7`: `Tuple[Tuple[0x076ef1ea, 0, 0, ...]]`.
## Stack [#stack]
The contents of the stack depend on the event that triggered the transaction:
* Internal message
* External message
* Tick-tock
* Split prepare
* Merge install
* [Get method (off-chain)](/blockchain-basics/tvm/get-method)
The top of the stack is always the *function selector*, an *integer* that identifies the event that caused the transaction.
The following function selectors are defined:
| ID | Name | Description |
| -- | ----------------- | -------------------------------------------------- |
| 0 | onInternalMessage | Received an internal message |
| -1 | onExternalMessage | Received an external message |
| -2 | onRunTickTock | Received a tick-tock event |
| -3 | onSplitPrepare | Received a split prepare event (unimplemented yet) |
| -4 | onSplitInstall | Received a split install event (unimplemented yet) |
Get methods can have arbitrary IDs and should not overlap with the ones listed above.
### External/internal message [#externalinternal-message]
| Index | Name | Type | Description |
| ----- | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `s0` | Function selector | `Integer` | `-1` for external messages, `0` for internal messages. |
| `s1` | Message body | `Slice` | This is an arbitrary payload of a message, which can be used for text comments (when sending TONs from one wallet to another) or for smart contract commands. |
| `s2` | Message | `Cell` | Cell containing message metadata (sender, receiver, amount) as well as message body. |
| `s3` | Message value | `Integer` | Amount of received nanotons (`0` for externals). |
| `s4` | Contract balance | `Integer` | Current account balance in nanotons. |
### Tick‑tock [#ticktock]
| Index | Name | Type | Description |
| ----- | ----------------- | ------- | ------------------------------------------------------ |
| `s0` | Function selector | Integer | `-2` for tick-tock transactions. |
| `s1` | Tick or tock? | Integer | `0` for tick transactions, `-1` for tock transactions. |
| `s2` | Account address | Integer | 256-bit raw account address (without workchain). |
| `s3` | Contract | Integer | Current account balance in nanotons. |
### Split/merge events [#splitmerge-events]
These events are not implemented yet. Possible stack layout for split/merge events is described in [TON Blockchain](/blockchain-basics/whitepapers/tblkch#4-4-8-processing-split-prepare-transactions) whitepaper. However, it is subject to change.
# Instructions (/blockchain-basics/tvm/instructions)
#### `00` NOP [#00-nop]
Does nothing.y`.
{/* STATIC_END tvm_instructions */}
# TVM overview (/blockchain-basics/tvm/overview)
TON Virtual Machine (TVM) is a [stack-based](https://en.wikipedia.org/wiki/Stack_machine) virtual machine which executes smart contracts on TON blockchain.
TVM is invoked when a message is sent to an account that has deployed contract code, when a get method is called on an account, and in some [more rare cases](/blockchain-basics/tvm/initialization#stack).
Executing code on same inputs and prior state deterministically produces same outputs, so that validators can agree on whether code was executed correctly.
Every instruction consumes [gas](/blockchain-basics/tvm/gas). Gas exhaustion stops execution. This limit is imposed so that expensive computations (i.e. infinite loops) cannot be used to exhaust validators' computation resources, causing [denial of service](https://en.wikipedia.org/wiki/Denial-of-service_attack).
## Data model [#data-model]
* TVM has no [random-access memory](https://en.wikipedia.org/wiki/Random-access_memory). Instead it uses a stack of values as a scratchpad.
* There are no memory addresses. Most instructions either store their parameters directly in the code, or take them from the top of the stack.
* All values are [immutable](https://en.wikipedia.org/wiki/Immutable_object).
Most of the data is stored as immutable tree of [cells](/blockchain-basics/primitives/serialization/cells).
* Reading and writing of cells is done with [slices and builders](/blockchain-basics/tvm/builders-and-slices).
* There are no function addresses or function pointers. Code is executed from bitcode inside [continuations](/blockchain-basics/tvm/continuations).
## TVM state [#tvm-state]
On incoming messages or get method call, a new instance of TVM is started, with a new state. Derivation of the initial state from the message is described in [its own article](/blockchain-basics/tvm/initialization).
The total state of TVM consists of the following components:
* **Stack**. A regular [stack data structure](https://en.wikipedia.org/wiki/Stack_\(abstract_data_type\)). The vast majority of instructions `pop()` operands from the top and `push()` results back.
* [**Control registers**](/blockchain-basics/tvm/registers). A small fixed set of special registers, denoted as `c0`, `c1`, ..., `c5`, and `c7` (`c6` does not exist).
* [**Gas counter**](/blockchain-basics/tvm/gas). Tracks remaining computation budget. Each instruction decrements gas. When counter hits zero/negative value, an exception is raised, and the run aborts.
* **Current continuation (`cc`)**. A special register that stores a list of the next instructions to execute. Similar to the instruction pointer in traditional architectures.
* **Current codepage (`cp`)**. Determines how to decode the next instruction in `cc`. Different codepages may implement different instruction sets, allowing for adding new features to TVM without affecting old smart contracts. Currently, only codepage `0` (`cp0`) is implemented. Smart contract runs [`SETCP0`](/blockchain-basics/tvm/instructions#ff-setcp) instruction to explicitly use codepage `0`.
## TVM data types [#tvm-data-types]
Values on the stack and inside of registers are of one of the following seven types:
| Type | Description |
| ------------ | --------------------------------------------------------------------------------------------------------------------------- |
| Integer | 257-bit signed integer. Has the special `NaN` value representing arithmetic faults. |
| Cell | Node of a tree with bit string on it (\<= 1023 bits), and up to 4 arrows (refs). |
| Slice | Read cursor over a Cell. |
| Builder | Write cursor to construct a new Cell. |
| Tuple | List of 0..255 elements of any of seven types. Types of elements can be distinct. |
| Continuation | Executable Slice with TVM bitcode. [Continuations](https://en.wikipedia.org/wiki/Continuation) are callable like functions. |
| Null | Empty value. |
## Example of a smart contract: counter [#example-of-a-smart-contract-counter]
Here is a sample contract, written in [Fift](/blockchain-basics/languages/fift/overview). It implements the following logic:
* If an event is not an internal message, stop execution.
* Read 32-bit number (`msg_counter`) from internal message's body.
* Check that it is equal to the 32-bit number stored in `c4` (persistent account storage).
* Increment it.
* Save it back to `c4`.
When an account with this code gets an internal message, TVM stack [is initialized](/blockchain-basics/tvm/initialization#stack) with these values:
1. `s0` (top of the stack), function selector, is `0`. For other events, e.g., external messages or get method calls, selector will be non-zero.
2. `s1`, message body. The example contract expects exactly 32 bits here.
3. Three more values `s2`, `s3`, `s4` [are pushed](/blockchain-basics/tvm/initialization#external%2Finternal-message) by TVM onto a stack. They won't be used in the example. After execution finishes, they'll still be on the stack, and will be silently ignored.
In `Current stack` comments, we represent stack at that moment of execution, keeping its top to the right (e.g., `s2 s1 s0`, where `s0` is the top of the stack).
```fift Fift
<{
// Current stack: msg_body selector
// Use codepage 0. Picks the only available instruction set.
SETCP0
// This instruction does not affect the stack.
// Current stack: msg_body selector
// Consume `selector` from the top of the stack.
// Stop execution if `selector != 0`,
// i.e. "is not an internal message".
IFRET
// Continue execution if we received an internal message.
// Current stack: msg_body
// Load (LD) unsigned (U) 32-bit integer from a slice.
// This instruction pops (consumes) a slice from the stack,
// pushes an integer, and then pushes a new slice with
// 32 bits cut from it
32 LDU
// Current stack: msg_counter msg_body'
// msg_body' is a slice whose read cursor was moved by 32 bits
// when we loaded a 32-bit integer.
// For example, if we had slice x{00000001} on the stack and
// then invoked 32 LDU, there will be integer `1` and `x{}`
// (empty slice) on the stack
// Assert the END of a slice (S).
// These instructions consume a slice and check that it is
// empty (no more data to read), otherwise it throws an
// exception, because there was more data than we expected.
ENDS
// Current stack: msg_counter
// Push c4 (persistent storage) on the stack.
// `storage` is a cell
c4 PUSH
// Current stack: msg_counter storage
// Convert Cell to a Slice, i.e. make it readable
CTOS
// Current stack: msg_counter storage_slice
// Read 32-bit unsigned integer from `storage_slice`
32 LDU
// Current stack: msg_counter storage_counter storage_slice'
// Assert there is no more data in the storage
ENDS
// Current stack: msg_counter storage_counter
// Duplicate s0 (top of stack) under two top values
TUCK
// Current stack: storage_counter msg_counter storage_counter
// Check counters are equal
EQUAL
// Current stack: storage_counter msg_counter==storage_counter?
// Throw an exception with code 33 if it is not equal
33 THROWIFNOT
// Current stack: storage_counter
// Increase counter
INC
// Current stack: storage_counter+1
// Create an empty Builder
NEWC
// Current stack: storage_counter+1 builder
// Store (ST) unsigned (U) 32-bit integer `storage_counter+1` to a builder
32 STU
// Current stack: builder'
// Finalize Builder to a Cell
ENDC
// Current stack: new_storage
// Save `new_storage` to c4 (persistent storage)
c4 POP
// Current stack: (no values)
}>
```
# Registers (/blockchain-basics/tvm/registers)
TVM registers hold special values, such as contract storage, list of output actions, or exception handler
Only `c4` (new state) and `c5` (final actions) represent durable effects of a successful on‑chain run. Everything else is transient.
## `c0` — return continuation [#c0--return-continuation]
**Type**: `Continuation`
**Initial value**: `Quit` — extraordinary continuation which terminates TVM with exit code `0`.
When [`RET`](/blockchain-basics/tvm/instructions#db30-ret) is called or the current continuation remains no instructions (*implicit ret*), `c0` is invoked. Call-like instructions use it to store the current continuation in order to return to it after executing the inner function.
## `c1` — alternative return continuation [#c1--alternative-return-continuation]
**Type**: Continuation
**Initial value**: `Quit` — extraordinary continuation which terminates TVM with exit code `1`. Both exit codes `0` and `1` are considered successful terminations of TVM.
Same as `c0`, but invoked only in special control flow instructions, such as [`RETALT`](/blockchain-basics/tvm/instructions#db31-retalt), [`IFRETALT`](/blockchain-basics/tvm/instructions#e308-ifretalt), and others.
## `c2` — exception handler [#c2--exception-handler]
**Type**: Continuation
**Initial value**: `ExcQuit` — extraordinary continuation which terminates TVM with an exception. In this case, the exit code is an exception number.
Invoked implicitly on any exception that occurs during TVM execution. Can be invoked explicitly by [`THROW`](/blockchain-basics/tvm/instructions#f2c4_-throw)-like instructions. To set a custom exception handler, use [TRY](/blockchain-basics/tvm/instructions#f2ff-try).
## `c3` — function selector [#c3--function-selector]
**Type**: Continuation
**Initial value**: Root cell of code currently executing in TVM.
Invoked by [`CALLDICT`](/blockchain-basics/tvm/instructions#f0-calldict) instruction with a function ID (integer) passed on the stack. The function selector should jump to a function with that ID.
Fift-ASM assembler constructs following function selector ([`Asm.fif`:1624](https://github.com/ton-blockchain/ton/blob/4ebd7412c52248360464c2df5f434c8aaa3edfe1/crypto/fift/lib/Asm.fif#L1624)):
```fift Fift
SETCP0
<{
// a dictionary which maps 19-bit function id (integer) => function code (slice)
}> DICTPUSHCONST
DICTIGETJMPZ // get a function with given id from dictionary and execute it
11 THROWARG // if no function found, throw with exit code 11 and function id as additional argument
```
## `c4` — persistent account storage [#c4--persistent-account-storage]
**Type**: Cell
**Initial value**: Root cell of account data.
This register helps to store some information between smart contract invocations. When the transaction succeeds, the final value of `c4` is saved as new account data.
## `c5` — outbound actions accumulator [#c5--outbound-actions-accumulator]
**Type**: Cell
**Initial value**: Empty cell.
List of actions to perform in the action phase after TVM execution: send a message, reserve funds, update code, and install libraries.
`c5` has an `OutList` structure:
```tlb title="TL-B"
out_list_empty$_ = OutList 0;
out_list$_ {n:#} prev:^(OutList n) action:OutAction = OutList (n + 1);
action_send_msg#0ec3c86d mode:(## 8) out_msg:^(MessageRelaxed Any) = OutAction;
action_set_code#ad4de08e new_code:^Cell = OutAction;
action_reserve_currency#36e6b809 mode:(## 8) currency:CurrencyCollection = OutAction;
libref_hash$0 lib_hash:bits256 = LibRef;
libref_ref$1 library:^Cell = LibRef;
action_change_library#26fa1dd4 mode:(## 7) libref:LibRef = OutAction;
```
The previous action is always the first reference of the next one. If action itself has a reference, it is stored as the second reference in the list. At the beginning of the list, an empty cell is stored as the first reference of the first action.
## `c7` — environment information and global variables [#c7--environment-information-and-global-variables]
**Type**: Tuple
**Initial value**: `Tuple[Tuple[0x076ef1ea, 0, 0, ...]]`.
The zero element of the `c7` tuple is an environment information (which itself is also a tuple). The remaining 255 slots are used for global variables. [`[i] SETGLOB`](/tvm/instructions#f87_-setglob) modifies `c7`, inserting an element with index `i`, [`[i] GETGLOB`](/tvm/instructions#f85_-getglob) reads `i`-th element from `c7`.
### Structure of environment information tuple [#structure-of-environment-information-tuple]
\#
Instruction
Field
Type
Description
0
\-
0x076ef1ea
integer
tag of the
SmartContractInfo
TL-B structure
1
\-
actions count
integer
increments when new action is pushed to
`c5`
.
2
\-
messages sent
integer
increments when new
`action_send_msg`
is pushed to
`c5`
3
NOW
unix time
integer
current time (timestamp of block collation)
4
BLOCKLT
current block LT (logical time)
integer
5
LTIME
current transaction LT
integer
6
RANDSEED
random seed
integer
`sha256(block_rand_seed . account_address)`
7
BALANCE
smart contract balance
tuple
tuple of integer (TON balance) and cell or
`null`
(extra currencies dictionary)
8
MYADDR
smart contract address
slice
9
CONFIGROOT
global blockchain configuration
cell or
`null`
(dictionary)
10
MYCODE
smart contract code
cell
11
INCOMINGVALUE
value of incoming message
tuple
tuple of integer (TON value) and cell or
`null`
(extra currencies dictionary)
12
STORAGEFEES
fees collected during storage phase
integer
13
PREVBLOCKSINFOTUPLE, PREVMCBLOCKS_100
last 16 masterchain blocks, last keyblock, and last 16 masterchain blocks with seqno divisible by 100
tuple
tuple has following `PrevBlocksInfo` structure:
```tlb
[ wc:Integer
shard:Integer
seqno:Integer
root_hash:Integer
file_hash:Integer ]
= BlockId;
[ last_mc_blocks:BlockId[]
prev_key_block:BlockId
last_mc_blocks_divisible_by_100:BlockId[] ]
= PrevBlocksInfo;
```
14
UNPACKEDCONFIGTUPLE
unpacked config values
tuple
* 0: `StoragePrices` from the `ConfigParam 18` — not the whole dictionary, but only the one `StoragePrices` entry which corresponds to the current time
* 1: `ConfigParam 19`, global ID
* 2: `ConfigParam 20`, masterchain gas prices
* 3: `ConfigParam 21`, non-masterchain gas prices
* 4: `ConfigParam 24`, masterchain forward fees
* 5: `ConfigParam 25`, non-masterchain forward fees
* 6: `ConfigParam 43`, size limits
15
DUEPAYMENT
current debt for storage fee in nanotons
integer
16
GETPRECOMPILEDGAS
gas usage for the current contract if it is precompiled,
null
otherwise
integer or
`null`
see
`ConfigParam 45`
17
INMSGPARAMS
inbound message parameters
tuple
* 0: `bounce: boolean` — can bounce
* 1: `bounced: boolean` — did bounce
* 2: `src_addr: slice` — sender
* 3: `fwd_fee: int`
* 4: `created_lt: int`
* 5: `created_at: int`
* 6: `orig_value: int` — this is sometimes different from the value in `INCOMINGVALUE` and TVM stack because of storage fees
* 7: `value: int` — same as in `INCOMINGVALUE` and on the initial TVM stack
* 8: `value_extra: cell or null` — same as in `INCOMINGVALUE`
* 9: `state_init: cell or null`
For external messages, tick-tock transactions and get methods: `bounce`, `bounced`, `fwd_fee`, `created_lt`, `created_at`, `orig_value`, `value` are 0, `value_extra` is null.
# Blockchain nodes overview (/blockchain-basics/nodes/overview)
A full node is a software that stores the whole blockchain state locally, opposite to lite-clients, which request small pieces of data from liteservers when needed. It does not solve any problem itself, but provides a base for other services requiring a full blockchain state (validator, liteserver, etc). Usually, full nodes keep only the latest part of the blockchain state, which is vital for ensuring client applications' network stability and operation. Full nodes *prune* the state of the TON blockchain they keep. This means the full node automatically removes earlier blocks that become unnecessary for the network to manage its data volume effectively. To allow client applications to look for blocks and transactions and send new transactions into the TON blockchain, full nodes are equipped with the liteserver functionality.
## Full node modes [#full-node-modes]
| Role | What it does | When to use it |
| ------------------ | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Liteserver | Stores the latest shards, tracks the masterchain, and serves data to lite-clients. | Required for custom infrastructure, analytics, or to back your own APIs. |
| Archive liteserver | Stores all blockchain data, including old blocks and states. | Required for explorers and other services working with historical data. |
| Validator | Signs blocks, participates in elections, and earns rewards. | Needed to run validation with your stake or to operate a nominator pool service. |
| Collator | Produces blocks for validators. | Needed to reduce load on your validators by setting up block creation on a separate machine. |
| Nominator pool | Accepts funds from stakers and runs a validator with their stake. | Needed when you want to securely accept stakes from multiple parties and share rewards between them. |
| Single nominator | Secure way to run a validator without depositing all funds to a hot wallet. | Generally, you should use it each time you want to run a new validator. |
| Liquid staking | Same as nominator pool, but exchanges stakers' funds for a synthetic token to be used in DeFi. | Needed to run a liquid staking protocol. |
## Do you need your own node? [#do-you-need-your-own-node]
* **Run your own full node** when you need guaranteed uptime or to serve high-volume workloads without third-party rate limits. Validators and staking services need to install a node and activate validator mode.
* **Rely on public endpoints** when building prototypes or light integrations. Community liteservers and APIs such as [TON Center](/applications/api/toncenter/introduction) or other [RPC providers](/applications/api/overview) already expose the blockchain for read access and transaction submission.
## Pick your target environment [#pick-your-target-environment]
| If you need | Run |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Validator or nominator capacity | [Setting up a node using MyTonCtrl](/blockchain-basics/nodes/cpp/setup-mytonctrl) with the validator, nominator pool, or single nominator workflows; the wrapper automates validator wallets, overlays, elections, and upgrades. |
| Liteserver APIs | [Setting up a node using MyTonCtrl](/blockchain-basics/nodes/cpp/setup-mytonctrl) with liteserver option (and archive mode if needed) to expose API for applications. |
| An isolated development network | [Setting up a local blockchain using MyLocalTon](/blockchain-basics/nodes/cpp/setup-mylocalton) to spin up a local shard, explorer, and APIs for rapid iterations with no mainnet impact. |
| Kubernetes-native production operations | [Use Rust node chart workflows](/blockchain-basics/nodes/rust/quick-start) and references. |
## Rust node overview [#rust-node-overview]
TON Rust node is an alternative implementation of a TON full node written in Rust. It is protocol-compatible with TON and follows an operational model designed for containerized environments rather than single-instance deployments.
Rust node operational focus:
* container-based architecture;
* Kubernetes-native deployment model;
* deterministic, version-pinned builds with automated release validation;
* node lifecycle management within a cluster environment;
* integration with external key management systems such as [HashiCorp Vault](https://www.hashicorp.com/en/products/vault).
Rust node is designed for:
* node providers operating multiple full nodes, liteservers, or validators;
* staking operators managing one or many validators as cluster resources;
* operators running node infrastructure that requires external key management integration and structured operational processes.
This model targets predictable scaling: infrastructure growth is handled through standardized deployment patterns, centralized control, and safer upgrade workflows.
### Advantages [#advantages]
* Multi-node deployment and centralized management: a new node can be launched in minutes, excluding sync time, using standardized Helm workflows.
* Fully tested container delivery: release images are version-pinned and validated by more than 10 automated test suites before publication.
* Built-in observability: Rust node exposes Prometheus metrics across 8 subsystems and serves `/healthz` and `/readyz` from the same metrics HTTP server.
* Grafana-ready workflow: a bundled dashboard and documented Prometheus/Grafana integration are provided for Kubernetes deployments.
* Key isolation: validator wallet and ADNL keys are designed for Vault-backed workflows instead of direct in-node private key storage.
### Rust node resource recommendations [#rust-node-resource-recommendations]
Recommended Kubernetes requests and limits are:
| Role | CPU request | CPU limit | Memory request | Memory limit |
| ---------------------- | ----------- | --------- | -------------- | ------------ |
| Full node / liteserver | 8 | 16 | 32GiB | 64GiB |
| Validator | 16 | 32 | 64GiB | 128GiB |
The node can run on fewer resources, but these values provide headroom for load spikes such as elections, heavy traffic, and catch-up after restarts.
Source: [TON Rust Node resource recommendations](https://github.com/RSquad/ton-rust-node/blob/e8bd0451b326099146a90a913beedaebd952fa56/helm/ton-rust-node/docs/resources.md).
## Full node [#full-node]
**The full node** is a basic node type within the TON blockchain. It serves as the backbone of the TON blockchain by keeping its block history — in other words, its *current state*.
Compared to **archive nodes**, full nodes keep only the latest part of the blockchain state, which is vital for ensuring client applications' network stability and operation. Full nodes *prune* the state of the TON blockchain they keep. This means the full node automatically removes earlier blocks that become unnecessary for the network to manage its data volume effectively.
To allow client applications to look for blocks and transactions and send new transactions into the TON blockchain, full nodes are equipped with the liteserver functionality.
## Archive node [#archive-node]
The archive node is a full node that keeps the entire block history of the TON blockchain. These nodes act as the decentralized point of truth to ensure consistency of the whole blockchain history. They are a backend for blockchain explorers and other applications relying on deep transaction history.
Archive nodes do not prune the blockchain state, elevating system requirements, especially in storage. According to the latest estimations, while full and validator nodes require about 1 TB of disk space, archive nodes need about 12 TB to store the complete block history.
## Validator node [#validator-node]
**Validator nodes** or **validators** are the TON network participants who propose new blocks and verify transactions according to the TON's *proof-of-stake* mechanism. In this way, validators contribute to the overall blockchain security.
Validators get rewards in TON for successful participation in the validation process.
To be entitled to propose and validate blocks, other participants elect validators based on the amount of TON they hold — in other words, their *stake*. The more TON a validator stakes, the higher its chances of being elected, validating blocks for the network, and earning rewards. As a rule, validator operators motivate other TON holders to stake with them to get passive income from the resulting rewards. In this way, validators ensure network stability and security and contribute to its growth.
## Interacting with TON nodes [#interacting-with-ton-nodes]
TON nodes can run in **liteserver mode**, which allows external applications to interact with the TON blockchain. In this mode, the nodes process client requests, enabling clients to access blockchain data, send transactions, and retrieve information about blocks and transactions.
Full and archive nodes typically enable liteserver mode because they store blockchain history and handle external requests. In contrast, validator nodes do not need it, as they focus on efficiently validating new blocks without additional workload from external queries. Use MyTonCtrl to [enable liteserver mode in a full or archive C++ node](/blockchain-basics/nodes/cpp/setup-mytonctrl#liteserver-quickstart).
Liteserver mode, or *liteserver* for short, uses the Abstract Datagram Network Layer (ADNL) protocol. Direct connections require either a client called *lite-client* downloaded from the [latest TON release](https://github.com/ton-blockchain/ton/releases/latest), or a library that understands ADNL. In the [SDK table](/applications/sdks), such libraries have a mark in the ADNL column.
To connect from a webpage or otherwise interact with TON nodes over HTTP, an HTTP-to-ADNL frontend is required. [TON Center](/applications/api/toncenter/introduction) is an official HTTP API provider, and its API endpoints can be used directly or [self-hosted](/applications/api/overview). In the [SDK table](/applications/sdks), libraries that use these endpoints or other HTTP providers have a mark in the HTTP column.
# TMA create CLI (/ecosystem/tma/create-mini-app)
Your browser does not support the \ tag.
Mini Apps run within Telegram and are instantly accessible — without the need for installation or redirects.
## TMA developer tools [#tma-developer-tools]
* [TMA create CLI](/ecosystem/tma/create-mini-app)
* [Telegram UI Kit](/ecosystem/tma/telegram-ui/overview)
* [Analytics](/ecosystem/tma/analytics/analytics)
# Documentation style guide (/overview/contribute/style-guide)
This guide covers the basics: how to structure pages, write examples, and keep docs consistent and safe.
## Write for the reader [#write-for-the-reader]
* Default audience: experienced software developers new to blockchain. Explain TON-specific concepts. Do not re-teach general programming. This keeps pages focused.
* Be answer‑first. Start with what the reader will achieve, what they need, and the steps. This shortens the time to success.
* Lead with a working example. Show a copy‑pasteable snippet early and the expected output. This shows it works.
* Use a neutral, precise tone. Write in the present tense, active voice, and second person (“Run the node”). This makes actions clear.
* Avoid marketing or hype (“blazingly fast”, “seamless”, “revolutionary”) and vague praise. Prefer measurable facts or omit the claim.
* Keep it scannable. Use short sections and paragraphs, clear headings, lists, and tables. Most readers skim to find the next action.
* Aim for one main idea per sentence. Split long, multi‑clause sentences or turn them into lists.
* Use bold only for a few scan‑worthy words in a paragraph, not full sentences or tokens. If a skimming reader loses nothing when the bold is removed, drop it.
* Use italics for new or defined terms and subtle emphasis; use bold for words a skimming reader should find quickly.
* Draft in plain text first. During editing, add minimal emphasis and remove any styling that does not change meaning.
## Page types [#page-types]
* Step-by-step guides — for beginners; handhold from zero to first success on one happy path; explain from scratch, define terms, and link out for depth.
* How-tos — a focused recipe for a specific outcome; assume concepts known and show only what’s needed.
* Explanation — concepts, architecture, and trade‑offs; clarify why and when, with minimal examples.
* Reference — exact, complete facts (APIs, CLI, types, errors); stable anchors and minimal prose.
* Don’t mix types on the same page.
## Where pages go [#where-pages-go]
* Keep the flow linear; follow the `docs.json` sidebar.
* In each topic group, order pages: Explanation → How‑to → Reference.
* Canonical specs — `reference/`. Link to it; don’t duplicate tables or parameters.
## Structure pages for success [#structure-pages-for-success]
* Start with Objective and Prerequisites so readers know they’re in the right place. Use Prerequisites for things the reader must have or have done; use an Audience note for skills or knowledge.
* Make each step a single action; use sub‑bullets for options.
* Include Verify and Troubleshoot so readers can confirm success and fix common errors.
* End with Next steps / See also only if essential (1–3 links). Prefer a linear path that needs no extra navigation.
## Examples that run [#examples-that-run]
* Make commands copy‑pasteable. Do not include shell prompts like `$` or `>`. Prompts break commands when pasted.
* Separate command and output. Use two fenced blocks. Mixing them causes copy errors.
* Use `` placeholders in commands and prose and define each on first use (for example, ``). In code, use `UPPER_SNAKE` if `< >` clashes with syntax. One clear convention prevents hard‑coded values from slipping in.
* Tag code fences with a language (`bash`, `json`, `rust`, and so on). This enables correct highlighting and tooling.
* Prefer end‑to‑end examples on testnet by default. Safe defaults encourage trying the steps.
* Label partial snippets as Not runnable and link to a complete example.
* Do not hard‑wrap long commands. Use soft wrap in the UI or safe continuation if the shell supports it. Hard wraps break execution.
* For UI buttons, menu items, and key names, wrap the label in `… ` instead of quotes or bold. This keeps controls easy to spot and consistent with the main style guide.
Good
```bash
ton-node start --ledger --network testnet
```
Expected output
```text
Node started. Workchain: 0 Shard: -1 Status: running
```
Define placeholders
`` — local ledger directory.
`` — HTTPS endpoint of your TON RPC provider.
## Safety warnings [#safety-warnings]
Add a Caution or Warning when a step moves funds, changes fees or withdrawals, exposes or stores private keys or mnemonics, modifies validator or network settings, or performs chain‑affecting operations such as resharding, pruning, halting, or replay. These actions can cause irreversible loss or outages.
On long guides with many risky commands, combine a clear page‑level warning at the top (covering risk, scope, rollback where feasible, and environment) with short local notes next to each critical step. Local notes can be brief if they point back to the main warning.
Pattern
> Warning — funds at risk
> Running the next command on mainnet transfers funds irreversibly.
> Safer first (testnet):
>
> ```bash
> jetton transfer --to --amount --network testnet
> ```
>
> If you must use mainnet: no rollback; on‑chain transfers are final.
Default to testnet in task pages. Make destructive flags opt‑in and document mitigations.
## Necessary disclaimers [#necessary-disclaimers]
Add a Caution or Warning when a page or step:
* Moves funds or changes fee/withdrawal behavior.
* Exposes, stores, or transmits private keys or mnemonics.
* Modifies validator configuration, networking, or other consensus‑affecting parameters.
* Performs chain‑affecting operations (for example, resharding, pruning, halting, replay).
* Uses destructive flags or commands that delete, rewrite, or lock state (for example, `--purge`, `--force`).
* Runs on mainnet, where actions are irreversible; label the environment and give the safer testnet first.
Make sure the guide as a whole clearly covers the risk, scope, rollback or mitigation (where feasible), and the environment label (testnet vs mainnet). For a single hazardous step, put these points directly in its callout. On long risky guides, put a big safety callout at the top and keep step‑level notes short, pointing back to that summary.
## Titles and headings [#titles-and-headings]
* Use sentence case. Keep headings concise and unique.
* Use imperatives for tasks (“Deploy a validator”); nouns for concepts (“Validator architecture”). Titles should signal action vs. explanation.
* Don’t style headings, except when an identifier needs code font.
* Use clear section labels such as Verify, Troubleshoot, and See also.
## Link to details, don’t duplicate [#link-to-details-dont-duplicate]
* On first useful mention, link flags, parameters, error codes, and data types to their reference anchors.
* Do not paste reference tables into guides. Link instead. Duplicated tables go stale.
* Use descriptive link text that names the destination, not generic labels like “click here”, “here”, or “this page”, and avoid mechanics-focused link labels like “click” or “go to”.
* Link core TON terms to the Glossary on first useful mention unless you define them on the page.
* Internal links **MUST** be root‑absolute (start with `/`). Deep‑link to the exact section or anchor that contains the needed fact (not the page top). **MUST NOT** use relative segments like `./` or `../` in any Markdown/MDX link. (Why: content moves frequently; root‑absolute links survive reorganizations.)
## Images [#images]
* Use the `` component for all images. Markdown image syntax `` and raw `
`@ton/mcp` is currently in alpha . It is safe for use in mainnet, but APIs, behaviors, and [underlying wallet contracts][wallets] may change between releases. Pin a specific version for production use and check the [changelog][changelog] before upgrading.
For all official TON MCP servers, their setup, and related skills, refer to the [TON MCP portal](https://mcp.ton.org/).
## Features [#features]
* Balance queries: check Toncoin and jetton (token) balances, view transaction history
* Transfers: send Toncoin, jettons, and NFTs
* Assets: list, inspect, and manage popular jettons and NFTs
* Swaps: get quotes for token swaps through DEX aggregators
* DNS: resolve TON DNS domains and perform reverse lookups
* Agentic wallets: create, import, and manage self-custody [agentic wallets][wallets]
* Multiple transports: standard I/O (default), multi-session HTTP server, and serverless (AWS Lambda, Vercel, or custom integrations)
## Quick start [#quick-start]
There are two ways to set up `@ton/mcp`:
Skills give an agent instructions on how to launch and use `@ton/mcp` on its own. No manual MCP client configuration is required. This approach works best with agents that support the [skills specification][skills-spec].
Run the following command to install the skills for `@ton/mcp`:
```bash
npx skills add ton-connect/kit/packages/mcp
```
After installation, agents can launch and manage `@ton/mcp` on their own. No further configuration is needed. The server starts in [agentic wallets mode](#agentic-wallets-mode) by default.
Register `@ton/mcp` as a server in Claude Desktop, Cursor, Windsurf, or another MCP client. Use this approach when the agent does not support skills or when finer control over server configuration is needed.
Add the following block to the MCP client configuration file:
```json
{
"mcpServers": {
"ton": {
"command": "npx",
"args": ["-y", "@ton/mcp@alpha"]
}
}
}
```
The server starts in [agentic wallets mode](#agentic-wallets-mode) by default. For [single-wallet mode](#single-wallet-mode), add `MNEMONIC` or `PRIVATE_KEY` to the `env` object.
See [environment variables](#environment-variables) for the full list of configuration options.
To start using `@ton/mcp` in agentic wallets mode:
To create a first agentic wallet, ask the agent to "create an agentic wallet" and follow the instructions.
The process goes as follows:
1. The agent generates private keys for a new wallet and suggests [opening the dashboard](https://agents.ton.org/).
2. On the dashboard, the user should connect their regular mainnet or testnet TON wallet: it will be the owner of an agentic wallet.
3. Agentic wallet gets deployed from the dashboard.
4. User provides the address of the deployed agentic wallet to the agent.
5. Agent imports the wallet and can then sign transactions using its operator key.
The user can revoke access or withdraw funds at any time from the dashboard.
An agentic wallet is a TON contract. There are three ways to fund it:
1. During creation: use the "Initial TON deposit" field on the deployment page.
2. From the dashboard: use the Fund button to transfer Toncoin, jettons, or NFTs.
3. Directly: use a wallet app like Tonkeeper to transfer assets to the agentic wallet address directly.
To check the balance, ask the agent: "What is my agent balance?"
Once setup is complete, ask agent to perform desired actions. For example:
* `Send 1 TON to UQB.._WALLET_ADDRESS` - sign and send a transfer from the agentic wallet.
* `Swap 5 TON for USDT` - get a quote and execute a swap.
* `Resolve the contract address of this DNS domain: DOMAIN_NAME.ton` - obtain the wallet address of the domain owner.
* `Show my NFTs` - query all NFTs owned by the wallet.
* `Check my balance` - current Toncoin and jetton balances. Do not use this data for any calculations, as it becomes outdated quickly.
* `Get my last transactions` - list of several latest events initiated by the wallet.
* `Import agentic wallet` - reinstate a wallet previously managed by another agent.
Web dashboard allows to see all agentic wallets in one place. Monitor transactions, fund and withdraw assets, grant and revoke accesses, rotate operator keys without redeploying the wallets.
## Runtime modes [#runtime-modes]
`@ton/mcp` supports two runtime modes:
* [Agentic wallets mode](#agentic-wallets-mode) (default) - operates with self-custody wallets for autonomous AI agents.
* [Single-wallet mode](#single-wallet-mode) (optional) - operates with a single in-memory wallet.
### Agentic wallets mode [#agentic-wallets-mode]
[Agentic wallets][wallets] are self-custody wallets designed for autonomous agents. The user retains the owner key, and the agent holds a separate operator key. This split-key design gives agents access to transfers, swaps, and other on-chain operations without exposing the root credentials.
Agentic wallets mode is the **default**. When neither `MNEMONIC` nor `PRIVATE_KEY` is set, the server loads wallets from a local config registry at `~/.config/ton/config.json` or the path in `TON_CONFIG_PATH`.
In this mode the server provides additional tools for multi-wallet management, agentic wallet onboarding, operator key rotation, and wallet import. Wallet-scoped tools accept an optional selector parameter: wallet ID, name, or address. When omitted, the current active wallet is used.
```bash
# Start in agentic wallets mode (default)
npx @ton/mcp@alpha
# Start with a custom config path
TON_CONFIG_PATH=/path/to/config.json npx @ton/mcp@alpha
```
### Single-wallet mode [#single-wallet-mode]
Single-wallet mode starts the server with one in-memory wallet derived from a mnemonic or private key. This mode is useful for one-off tasks or for operating a single known wallet.
Set `MNEMONIC` or `PRIVATE_KEY` as an environment variable to activate this mode:
```bash
# First, securely set either a MNEMONIC=" ... "
# or a PRIVATE_KEY=""
# Then, launch the server
npx @ton/mcp@alpha
```
`MNEMONIC` and `PRIVATE_KEY` grant full control of the wallet. Store these values in environment variables or a secrets manager. Do not commit them to Git or other source control systems. Do not pass them inline in shell commands.
The default TON wallet version in the single-wallet mode is [`v5r1`][wallets-comparison]. Override it with `WALLET_VERSION`:
```bash
# First, securely set either a MNEMONIC or a PRIVATE_KEY
# Then, use a diffent wallet version
WALLET_VERSION=v4r2 npx @ton/mcp@alpha
```
## Transport modes [#transport-modes]
The `@ton/mcp` server supports two transport modes:
* [Standard I/O](#standard-i%2Fo) (stdio, default)
* [HTTP](#http), which can also be run [serverless](#serverless)
### Standard I/O [#standard-io]
Standard IO is the default transport. The server reads MCP requests from stdin and writes responses to stdout. Most MCP clients, including Claude Desktop and Cursor, can use this transport. They spawn the server process and interact over standard streams.
```bash
npx @ton/mcp@alpha
```
### HTTP [#http]
HTTP mode starts a multi-session HTTP server. Each MCP client session gets its own server transport, so multiple clients can initialize and reconnect independently.
```bash
# Start on the default port (3000)
npx @ton/mcp@alpha --http
# Start on a custom port
npx @ton/mcp@alpha --http 8080
# Start on a custom host and port
npx @ton/mcp@alpha --http 8080 --host 127.0.0.1
```
The MCP endpoint is available at `http://:/mcp`. Point the MCP client to this URL to connect.
#### Serverless [#serverless]
The package exports a `@ton/mcp/serverless` entry point for deployment as a serverless function on AWS Lambda, Vercel, Cloudflare Workers, and similar platforms. In serverless mode, credentials are passed via request headers rather than environment variables.
Serverless headers carry wallet credentials in every request. Use HTTPS in production to prevent credential interception. Restrict access to the serverless endpoint with authentication or network-level controls.
Serverless mode operates in [single-wallet mode](#single-wallet-mode) only and always uses the [`v5r1` TON wallet version][wallets-comparison]. It does not use the wallet registry, nor does it expose wallet management or onboarding tools.
| Header | Description |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| `MNEMONIC` | Space-separated 24-word mnemonic phrase. |
| `PRIVATE_KEY` | Hex-encoded 32-byte or 64-byte private key (paired with the public key). Takes priority over `MNEMONIC`. |
| `NETWORK` | Either `mainnet` (default) or `testnet`. |
| `TONCENTER_API_KEY` | Optional API key for higher rate limits. |
```typescript title="AWS Lambda"
import { createServerlessHandler } from '@ton/mcp/serverless';
export const handler = createServerlessHandler();
```
```typescript title="Vercel"
import { createServerlessHandler } from '@ton/mcp/serverless';
export default createServerlessHandler();
```
```typescript title="Custom integration"
import { createServerlessHandler } from '@ton/mcp/serverless';
const handle = createServerlessHandler();
const response = await handle({
method: 'POST',
url: '/mcp',
headers: {
'MNEMONIC': ' ... ',
'NETWORK': 'mainnet',
},
body: {},
});
```
## Available tools [#available-tools]
### Common tools [#common-tools]
All transfer tools move real funds. The agent confirms every transfer with the user before executing. After sending, the default flow polls `get_transaction_status` until the transaction completes or fails.
* Wallet management:
* `get_wallet` - returns the current wallet address and network: `mainnet` or `testnet`.
* Balances and history:
* `get_balance` - returns the Toncoin balance of the current wallet.
* `get_balance_by_address` - returns the Toncoin balance for any address.
* `get_jetton_balance` - returns the balance of a specific jetton in the current wallet.
* `get_jettons` - lists all jettons held by the current wallet with balances and metadata.
* `get_jettons_by_address` - lists all jettons held by any address with balances and metadata. Supports pagination.
* `get_jetton_info` - returns metadata for a jetton minter (master) contract: name, symbol, decimals, image, URI.
* `get_known_jettons` - returns a built-in list of popular jettons on TON with addresses and metadata.
* `get_transactions` - returns recent transaction history: Toncoin transfers, jetton transfers, swaps.
* `get_transaction_status` - returns the status (pending, completed, or failed) and trace details for a transaction by its normalized hash.
* Transfers:
* `send_ton` - sends Toncoin to an address. Amounts are in human-readable format. For example, `"1.5"` for 1.5 Toncoin. Returns a `normalizedHash`.
* `send_jetton` - sends jettons to an address. Amounts are in human-readable format. Returns a `normalizedHash`.
* `send_nft` - transfers an NFT to another address. Returns a `normalizedHash`.
* `send_raw_transaction` - sends a raw transaction with full control over messages. Amounts are in nanoToncoin. Supports multiple messages. Returns a `normalizedHash`.
* Swaps:
* `get_swap_quote` - returns a quote for a token swap. The response includes transaction parameters ready for `send_raw_transaction`. Use `"TON"` for native Toncoin or a jetton minter (master) contract address.
* NFTs:
* `get_nfts` - lists NFTs in the current wallet with metadata, collection info, and attributes. Supports pagination.
* `get_nfts_by_address` - lists NFTs held by any address. Supports pagination.
* `get_nft` - returns detailed information about a specific NFT by its item contract address.
* DNS:
* `resolve_dns` - resolves a TON DNS domain to a wallet address.
* `back_resolve_dns` - reverse-resolves a wallet address to its associated DNS domain when one exists.
### Agentic tools [#agentic-tools]
* Wallet management:
* `list_wallets` - lists all wallets in the local config registry.
* `get_current_wallet` - returns the active wallet from the local config registry.
* `set_active_wallet` - switches the active wallet in the local config registry by its ID, name, or address.
* `remove_wallet` - soft-deletes a wallet from the local config registry. The wallet remains in the config file but is hidden from MCP lookups.
* Agentic wallet management:
* `agentic_validate_wallet` - validates an agentic wallet address against the expected network and collection.
* `agentic_list_wallets_by_owner` - lists agentic wallets owned by a given main wallet address.
* `agentic_import_wallet` - imports existing agentic wallet into the local registry. If no matching pending draft exists, the wallet is read-only until `agentic_rotate_operator_key` completes.
* `agentic_rotate_operator_key` - starts operator key rotation: generates a replacement key, persists a pending draft, and returns a dashboard URL for the on-chain change.
* `agentic_get_pending_operator_key_rotation` - returns one pending operator key rotation by ID.
* `agentic_complete_rotate_operator_key` - completes a key rotation after the on-chain transaction confirms and updates the stored operator key locally.
* `agentic_cancel_rotate_operator_key` - cancels a pending key rotation and discards the replacement key.
* Agentic wallet onboarding:
* `agentic_start_root_wallet_setup` - starts first-time root agent setup: generates operator keys, persists a pending draft, and returns a dashboard URL.
* `agentic_list_pending_root_wallet_setups` - lists pending root agent onboarding drafts and their callback status.
* `agentic_get_root_wallet_setup` - returns one pending onboarding draft by setup ID.
* `agentic_complete_root_wallet_setup` - completes onboarding from a callback payload or a manually supplied wallet address, then imports the wallet and makes it active.
* `agentic_cancel_root_wallet_setup` - cancels a pending onboarding draft and removes its state.
## Environment variables [#environment-variables]
### Common [#common]
TON network and default env override target for `TONCENTER_API_KEY`. Use `mainnet` for production and `testnet` for development and testing.
Defaults to `mainnet`.
API key for [TON Center](/applications/api/toncenter/introduction). Raises the default rate limit from 1 request per second to the limit of the selected plan. Without a key, the server uses a built-in shared key suitable for low-volume development and experiments.
For production workloads, [obtain a dedicated key](/applications/api/toncenter/get-api-key).
Optional public base URL for agentic onboarding callbacks
Host for the local callback server in stdio mode. Defaults to `127.0.0.1`.
Port for the local callback server in stdio mode. Defaults to a random free port.
### Agentic wallets [#agentic-wallets]
Config path for agentic wallets mode. Defaults to `~/.config/ton/config.json`.
### Single-wallet [#single-wallet]
Space-separated 24-word mnemonic phrase for the single-wallet mode.
Alternative to `PRIVATE_KEY`.
Hex-encoded private key for the single-wallet mode. Can be given either 32-byte standalone or 64-byte when paired with the public key.
Alternative to `MNEMONIC`. Takes priority over it.
TON wallet version to use in the single-wallet mode: [`v5r1`, `v4r2`][wallets-comparison], or [`agentic`][wallets].
Defaults to `v5r1`.
Address of the agentic wallet in the single-wallet mode. Required for `WALLET_VERSION` set to `agentic`, unless derived from initial params.
Optional index of the agentic wallet NFT contract.
Defaults to none.
Agentic collection address override for single-wallet mode.
Defaults to `EQByQ19qvWxW7VibSbGEgZiYMqilHY5y1a_eeSL2VaXhfy07` on the mainnet.
## Library usage [#library-usage]
The package also exports a programmatic API for building custom MCP servers:
```typescript
import { createTonWalletMCP } from '@ton/mcp';
import {
Signer,
WalletV5R1Adapter,
TonWalletKit,
MemoryStorageAdapter,
Network,
} from '@ton/walletkit';
// Mnemonic as a single string of 24 words:
// " ... "
const MNEMONIC = process.env.MNEMONIC!;
// Initialize WalletKit
const network = Network.mainnet();
const kit = new TonWalletKit({
networks: { [network.chainId]: {} },
storage: new MemoryStorageAdapter(),
});
await kit.waitForReady();
// Create a wallet from a mnemonic
const signer = await Signer.fromMnemonic(MNEMONIC.split(' '), { type: 'ton' });
const walletAdapter = await WalletV5R1Adapter.create(signer, {
client: kit.getApiClient(network),
network,
});
const wallet = await kit.addWallet(walletAdapter);
// Create the MCP server object
const server = await createTonWalletMCP({ wallet });
```
Agentic wallets mode:
```typescript
import { createTonWalletMCP } from '@ton/mcp';
// A key for higher RPS limits
const TONCENTER_API_KEY = process.env.TONCENTER_API_KEY!;
// Create the MCP server object
const server = await createTonWalletMCP({
networks: {
mainnet: { apiKey: TONCENTER_API_KEY },
},
});
```
## See also [#see-also]
* [Agentic wallets][wallets]
* [`@ton/mcp` on GitHub][mcp-repo]
[mcp-repo]: https://github.com/ton-connect/kit/tree/main/packages/mcp
[mcp-npm]: https://www.npmjs.com/package/@ton/mcp?activeTab=versions
[mcp-spec]: https://modelcontextprotocol.io/
[skills-spec]: https://agentskills.io/specification
[wallets]: /ecosystem/ai/wallets
[wallets-comparison]: /standard/wallets/comparison#comparison-table
[changelog]: https://github.com/ton-connect/kit/blob/main/packages/mcp/CHANGELOG.md
# Overview of AI in TON (/overview/ai/overview)
There are AI products utilizing TON Blockchain, such as agents and wallet tooling. Additionally, TON documentation is AI-friendly, and enables all kinds of AI workflows.
## AI ecosystem [#ai-ecosystem]
### `@ton/mcp` [#tonmcp]
The main official entry point is [`@ton/mcp`](/overview/ai/mcp), a TON MCP server for agents. It exposes tools for balance checks, asset queries, transfers, TON DNS resolution, swaps, and [agentic wallet](/overview/ai/wallets) management. Use [`@ton/mcp`](/overview/ai/mcp) when an agent needs to operate on TON through MCP or through a skills-based setup.
For the catalog of official TON MCP servers, setup guides, and related skills, see the [TON MCP portal](https://mcp.ton.org/).
### Agentic wallets [#agentic-wallets]
[Agentic wallet contracts](/overview/ai/wallets) provide self-custody wallets for autonomous AI agents operating on TON. They are used by `@ton/mcp` in its default agentic wallets mode.
### Community [#community]
The [AI Dev Wall on Telegram](https://t.me/ai_dev_wall) is a builder channel for TON AI tooling and project updates. This channel primarily features third-party, community resources.
## Documentation [#documentation]
TON documentation exposes several AI-facing surfaces:
* The in-site assistant can answer questions over the docs and cite relevant pages. Assistant can be invoked by a shortcut Ctrl+K (or Cmd+K on macOS), a query in the floating input field at the bottom of each page, from any selection on the page, or via a button on each code block to explain its contents.
* MCP server allows reading and querying documentation pages via MCP clients: `https://docs.ton.org/mcp`. Unlike [`@ton/mcp`](/overview/ai/mcp), it does not provide agents with tools to act on TON, only the documentation content.
* The contextual menu can copy page content, open a page in external AI tools, or connect to the documentation MCP.
* The [`llms.txt`](https://docs.ton.org/llms.txt) file provides a machine-readable index of documentation pages.
* Raw Markdown is available through `.md` page routes. This is useful when a tool needs the page content without the site UI. For example, to obtain raw contents of this page, query `https://docs.ton.org/ecosystem/ai/overview.md`.
# Agentic wallet contracts (/overview/ai/wallets)
Agentic wallets are self-custody wallets designed for autonomous AI agents on TON.
Agentic wallet contracts have not been audited. Use testnet for experiments.
## Split-key architecture [#split-key-architecture]
Each agentic wallet is a smart contract deployed as [Soulbound Token (SBT)](/blockchain-basics/standard/tokens/nft/comparison#sbt) within a shared NFT collection. Internally, each agentic wallet retains full [wallet v5](/blockchain-basics/standard/wallets/comparison#comparison-table) functionality. It stores the user's address (owner), the agent's (operator) public key, and a nonce to protect against replay attacks.
The deployment process goes as follows:
1. The agent creates a pair of keys (public and private), keeping the private key in the local config registry.
2. User deploys an agentic wallet from their regular TON wallet by providing the operator's public key and wallet address (owner address).
3. The contract checks that the sender's address matches the stored owner's address. If it doesn't match, the wallet will be deployed in an uninitialized state and will not appear in explorers, preventing the creation of unwanted wallets without the user's consent.
4. If deployment is successful, the agent receives the address of the new wallet.
With a private operator key and a new wallet address, the agent can sign and send transactions from that wallet. Alas, the user can withdraw funds, rotate the operator key, or deactivate the agent at any time by setting the operator key to zero.
This split-key design gives agents access to transfers, swaps, and other on-chain operations without exposing the user's root credentials or violating the user's ownership and control.
## Funding [#funding]
Transactions initiated by the agent (operator) must be signed with the operator key. Because the operator key is separate from the user's key (owner's key), the agent never controls the owner's main wallet. However, an agent with an active operator key has complete control of the balance and assets held in its own agentic wallet.
Only fund agentic wallets with amounts and assets that they are allowed to risk.
## Dashboard [#dashboard]
The [agentic wallets dashboard](https://agents.ton.org/) is a web interface for managing agentic wallets. It supports:
* Wallet creation - deploy a new agentic wallet, assign an operator key, and fund it with Toncoin.
* Real-time monitoring - observe agent transactions as they happen.
* Key rotation - rotate operator keys without redeploying the wallet contract.
* Revocation - revoke agent access by removing the operator key.
* Funding and withdrawal - deposit or withdraw Toncoin, jettons, and NFTs.
Connect an existing TON wallet to access the dashboard.
## Get started [#get-started]
The recommended way to create and use agentic wallets is through [`@ton/mcp`](/overview/ai/mcp). The [`@ton/mcp` quick start](/overview/ai/mcp#quick-start) guide covers the full setup flow and gives common usage examples.
## FAQ [#faq]
The owner key is never shared with agents. The agent has its own operator key that can only be used to spend from its own agentic wallet, and any balance in that wallet is fully under the agent's control. All operations are performed on-chain with no intermediaries.
The agent can only spend what was deposited into its wallet. The owner's main wallet is completely separate.
However, if the agent behaves incorrectly or performs expensive transactions, it can spend the entire wallet balance before the owner reacts.
The risk is capped to the deposited amount. Only deposit funds that are acceptable to lose.
Not yet. This is a developer preview. The contracts are open source and [available on GitHub](https://github.com/the-ton-tech/agentic-wallet-contract), but a formal audit has not been completed.
There is no limit. Each agent has its own wallet and balance. All agents are managed from a single dashboard.
Select Revoke , then confirm the transaction. The operator is deactivated, and remaining funds can be withdrawn.
# Analytics and data providers (/overview/infrastructure/analytics)
Developers often need to run analytical queries on top of on-chain data — for example, to track historical changes and aggregate data from multiple accounts.
Since blockchains are not designed for analytical workloads, you need to build an indexing pipeline and run off-chain analytical queries.
Creating such pipelines from scratch can be resource-consuming, so we recommend using one of the tools mentioned on this page.
## Dune analytics [#dune-analytics]
[Dune analytics](https://dune.com/) is one of the leading platforms for running analytical queries and building dashboards. It comes with 100+ blockchain integrations, and TON is among them. Basically, one needs to be familiar with SQL language to write queries, but the [Dune AI](https://docs.dune.com/learning/how-tos/dune-ai-prompt-engineering) prompt engine allows users to start working with data even without SQL knowledge.
### Raw and decoded tables [#raw-and-decoded-tables]
Dune analytics consumes data from the public [TON Data Lake](#public-data-lake) (see below) and comes with a variety of raw and decoded tables.
The [raw tables](https://dune.com/queries?category=canonical\&namespace=ton) include:
* [Blocks](https://docs.dune.com/data-catalog/ton/blocks)
* [Transactions](https://docs.dune.com/data-catalog/ton/transactions)
* [Messages](https://docs.dune.com/data-catalog/ton/messages) — includes raw body and `StateInit` data.
* [Balances history](https://docs.dune.com/data-catalog/ton/balances_history) — allows you to get a precise point-in-time balance for any account.
* [Jetton events](https://docs.dune.com/data-catalog/ton/jetton_events) — comes with transfers, burns, and mints.
Since mints are not covered by the [TEP-74](https://github.com/ton-blockchain/TEPs/blob/master/text/0074-jettons-standard.md) standard, it is not possible to reconstruct balances based solely on jetton events, so the balance history should be used.
Apart from raw tables, there are decoded tables that allow you to work with high-level structures in a unified manner:
* [NFT events](https://dune.com/queries?category=canonical\&namespace=ton\&id=ton.nft_events) — comprehensive source of NFT-related data, including
sales, transfers, and mints.
* [DEX trades](https://docs.dune.com/data-catalog/ton/dex_trades) — includes a unified data model for DEX trades. The full list of
supported DEXs is available [here](https://github.com/ton-studio/ton-etl/blob/main/datalake/README.md#dex-trades).
* [DEX pools](https://docs.dune.com/data-catalog/ton/dex_pools) — comes with the full history of DEX pool balances and TVL estimations.
Finally, two tables with off-chain metadata are available:
* [Jetton metadata](https://docs.dune.com/data-catalog/ton/jetton_metadata)
* [NFT metadata](https://dune.com/queries?category=canonical\&namespace=ton\&id=ton.nft_metadata).
### Bespoke data marts [#bespoke-data-marts]
Dune analytics allows projects to build bespoke data marts for each protocol — it is widely used for EVMs with the help of ABIs.
#### Decoding raw data [#decoding-raw-data]
Since TON handles complex [data structures](/blockchain-basics/primitives/serialization/cells) and doesn't have ABIs, a [special decoding framework](https://github.com/duneanalytics/spellbook/blob/main/dbt_subprojects/daily_spellbook/macros/project/ton/README.md) was created. It works on top of the [Spellbook](https://github.com/duneanalytics/spellbook) — a powerful tool for building custom tables with [`dbt`](https://github.com/dbt-labs/dbt-core) and Jinja macros. It helps decode important information from raw protocol message payloads.
The following protocols are decoded using this framework and serve as examples:
* [EVAA](https://dune.com/queries?category=abstraction\&namespace=evaa) ([implementation](https://github.com/duneanalytics/spellbook/tree/main/dbt_subprojects/daily_spellbook/models/evaa/ton))
* [Affluent](https://dune.com/queries?category=abstraction\&namespace=affluent) ([implementation](https://github.com/duneanalytics/spellbook/tree/main/dbt_subprojects/daily_spellbook/models/affluent/ton))
* [StormTrade](https://dune.com/queries?category=abstraction\&namespace=stormtrade) ([implementation](https://github.com/duneanalytics/spellbook/tree/main/dbt_subprojects/daily_spellbook/models/stormtrade/ton))
* [TON DNS](https://dune.com/queries?category=abstraction\&namespace=dns_ton) ([implementation](https://github.com/duneanalytics/spellbook/tree/main/dbt_subprojects/daily_spellbook/models/ton/dns))
#### Custom views [#custom-views]
In addition to decoding raw data, the Spellbook allows building custom materialized views. Some of them are widely used and maintained to be up to date:
* [ton.prices\_daily](https://dune.com/queries?category=abstraction\&namespace=ton\&id=ton.prices_daily) — prices calculated based on all other tables. The prices include jettons traded on DEXs, LP tokens for DEXs, perpetuals, tsUSDe, and other core assets. It is recommended to use this table if you need to build an estimation of assets denominated in TON or USD.
* [ton.accounts](https://dune.com/queries?category=abstraction\&namespace=ton\&id=ton.accounts) — materialized view with information about all accounts. It comes with the latest TON balance, interface (if any), funding information, and other fields.
* [ton.latest\_balances](https://dune.com/queries?category=abstraction\&namespace=ton\&id=ton.latest_balances) — helper table to get the latest balances for TON and Jettons.
All tables mentioned above are updated daily.
### Getting started with Dune [#getting-started-with-dune]
If you're just starting to explore TON data on Dune, we recommend checking these articles first:
For inspiration to build your own dashboards, check out these examples:
## Public Data Lake [#public-data-lake]
Dune integration runs on the public data lake from the [TON-ETL](https://github.com/re-doubt/ton-etl/blob/main/datalake/README.md) project.
[TON-ETL](https://github.com/re-doubt/ton-etl/blob/main/datalake/README.md) is built on top of [TON Center](https://github.com/toncenter) indexer and allows extraction of data from TON Node into data formats suitable for MPP (Massively Parallel Processing) engines: Presto, Apache Spark, etc.
You can deploy it on your own infrastructure or use publicly available data from the S3 bucket: `s3://aws-public-blockchain/v1.1/ton/`. This dataset is part of the [AWS Public Blockchain Data](https://registry.opendata.aws/aws-public-blockchain/) project and is optimized for use within the AWS big data stack.
Examples of AWS Athena and AWS Bedrock integration can be found in this [article](https://repost.aws/articles/AR3ABC81yvTPW2ktfHiHPWIA/new-dataset-added-to-the-aws-public-blockchain-data-ton-the-open-network).
The TON-ETL extracts raw data and performs decoding to create a unified view of high-level on-chain activity. The most important part is decoding DEX activity.
The decoding implementation must solve the following tasks:
* Decoding of swap events. The code must check the authenticity of the swap. For example, you cannot rely on the opcode alone since anyone can generate messages with your opcode.
* Extracting all swap-related fields: tokens sold and bought, amounts, query IDs, trader, router (if any), and pool.
* Fetching pool reserves and LP token supply, if applicable.
To add support for a new DEX and decode its activity, you need to prepare a relevant PR on GitHub [to TON-ETL's repo](https://github.com/ton-studio/ton-etl). Use those past PRs as a reference: [BidAsk](https://github.com/ton-studio/ton-etl/pull/186), [CoffeeSwap](https://github.com/ton-studio/ton-etl/pull/171/files), [MemesLab](https://github.com/ton-studio/ton-etl/pull/144).
## Real-time streams [#real-time-streams]
In addition to bulk data export, TON-ETL provides real-time data streaming via Kafka. A [public endpoint](https://github.com/ton-studio/ton-etl/blob/main/datalake/README.md#near-real-time--data-streaming-via-pulic-kafka-topics) is available free of charge for non-profit projects.
For projects that don't meet the non-profit criteria or require an in-house solution, you can deploy the infrastructure yourself by:
1. Running your own [TON node](/blockchain-basics/nodes/overview)
2. Launching [ton-etl](https://github.com/re-doubt/ton-etl/blob/main/README.md)
3. Setting up [ton-index-worker](https://github.com/ton-studio/ton-index-worker)
## TON Labels [#ton-labels]
While data availability and integrations are essential, building insightful dashboards requires enriching data with address labels.
The [TON Labels](https://github.com/ton-studio/ton-labels) project simplifies this process by providing a comprehensive taxonomy of addresses in TON Ecosystem. It covers active addresses across various categories, including centralized exchanges (CEXs), decentralized applications (dApps), and DeFi protocols.
You can access the latest labels either directly from [the build branch](https://github.com/ton-studio/ton-labels/blob/build/assets.json) or through Dune analytics using the [`dune.ton_foundation.dataset_labels`](https://dune.com/queries?category=uploaded_data\&id=dune.ton_foundation.dataset_labels) table.
## Other platforms [#other-platforms]
* [Chainbase](https://docs.chainbase.com/catalog/Ton/Overview) offers a set of raw and decoded tables with TON data. It allows you to run SQL queries and fetch results via API.
* [TON Console](https://docs.tonconsole.com/tonconsole/analytics) provides analysts with Analytics Service.
* [TokenTerminal](https://tokenterminal.com/explorer/projects/the-open-network) comes with high-level metrics across TON Ecosystem.
* [Artemis](https://app.artemisanalytics.com/project/ton?from=projects) contains key metrics for TON and allows you to build customized charts.
* [Spice harvester](https://github.com/txsociety/spice-harvester) supports high-load transaction monitoring and asset tracking on TON through a self-hosted API with access to invoice states and metadata.
# Bridges (/overview/infrastructure/bridges)
In the TON ecosystem, bridges allow users to transfer assets and data between TON and other major blockchains like Ethereum, BNB Chain, and Polygon.
In this article, we will explore cross-chain bridges on TON.
## What are Cross-Chain Bridges? [#what-are-cross-chain-bridges]
Cross-chain bridges are protocols that allow users to transfer cryptocurrencies, tokens, and sometimes arbitrary data from one blockchain to another. They act as connectors between otherwise isolated blockchain networks, enabling a multi-chain ecosystem where assets can move freely across different platforms.
Bridges typically work by locking assets on the source blockchain and minting equivalent wrapped tokens on the destination blockchain. When users want to move assets back, the wrapped tokens are burned on the destination chain, and the original assets are unlocked on the source chain.
### Types of Cross-Chain Bridges [#types-of-cross-chain-bridges]
#### 1. Trustless vs. Custodial Bridges [#1-trustless-vs-custodial-bridges]
Trustless Bridges:
* Use smart contracts and cryptographic proofs for validation
* No single point of failure
* Decentralized verification mechanisms
Centralized Bridges:
* Rely on trusted entities or multi-signature wallets
* Single point of failure risk
* Generally, they are easier to implement
#### 2. Asset Transfer Methods [#2-asset-transfer-methods]
Lock-and-Mint Bridges:
* Lock original assets on the source chain
* Mint wrapped tokens on the destination chain
* Most common bridge type
Burn-and-Mint Bridges:
* Burn tokens on the source chain
* Mint new tokens on the destination chain
* Used for native multi-chain tokens
## Bridges on TON [#bridges-on-ton]
The TON blockchain has a bridge ecosystem that connects it to major EVM-compatible networks. There are several kinds of bridge providers on TON.
### Legacy: Official TON Bridges [#legacy-official-ton-bridges]
During the early development of TON ecosystem (2021-2023) there were a few official TON bridges, supported at the protocol level. Now, they are considered legacy and not recommended for usage since they can be deprecated at any moment.
TON blockchain supports several official bridges configured at the protocol level:
#### Outbound Bridges (Config parameters 71-73) [#outbound-bridges-config-parameters-71-73]
These bridges wrap TON into other networks:
* **ETH-TON Bridge** ([Config Parameter 71](/blockchain-basics/primitives/config#param-71-73%3A-outbound-bridges))
* **BNB-TON Bridge** ([Config Parameter 72](/blockchain-basics/primitives/config#param-71-73%3A-outbound-bridges))
* **Polygon-TON Bridge** ([Config Parameter 73](/blockchain-basics/primitives/config#param-71-73%3A-outbound-bridges))
#### Inbound Bridges (Config parameters 79, 81-82) [#inbound-bridges-config-parameters-79-81-82]
These bridges wrap tokens from other networks into TON:
* **ETH-TON Bridge** ([Config Parameter 79](/blockchain-basics/primitives/config#param-79%2C-81-and-82%3A-inbound-bridges))
* **BNB-TON Bridge** ([Config Parameter 81](/blockchain-basics/primitives/config#param-79%2C-81-and-82%3A-inbound-bridges))
* **Polygon-TON Bridge** ([Config Parameter 82](/blockchain-basics/primitives/config#param-79%2C-81-and-82%3A-inbound-bridges))
You can read more about these bridge configuration parameters on the [TON Config page](/blockchain-basics/primitives/config).
### Third-Party Bridge Ecosystem [#third-party-bridge-ecosystem]
The TON ecosystem features multiple bridge providers offering different features and supported networks. You can read more about them in [TON Bridges page](https://ton.org/en/bridges).
You can see existing bridges statistics on [TON Foundation Bridge Dashboard](https://dune.com/ton_foundation/bridges).
# Network status (/overview/infrastructure/status)
This page lists websites that show if specific parts of TON blockchain are working normally.
| | |
| ---------------------------------------------------------------- | ------------------------------------------------------------- |
| [https://tonstat.us/](https://tonstat.us/) | HTTP and ADNL server availability and performance. |
| [https://status.toncenter.com/](https://status.toncenter.com/) | Low-level metrics, such as latencies, rates, and loads. |
| [https://validators.ton.org/](https://validators.ton.org/) | Official validation dashboard. |
| [https://tonscan.com/validation](https://tonscan.com/validation) | Pretty validation dashboard. |
| [https://t.me/tonstatus](https://t.me/tonstatus) | Notifications and requests for action for mainnet validators. |
| [https://t.me/testnetstatus](https://t.me/testnetstatus) | Notifications and requests for action for testnet validators. |
| [https://t.me/validators](https://t.me/validators) | Bot for validator owners to track their status. |
# Coming from Ethereum (/overview/learn-more/from-ethereum)
Learn how to develop and build on TON coming from the Ethereum (EVM) ecosystem.
## Execution model [#execution-model]
### Asynchronous blockchain [#asynchronous-blockchain]
A fundamental aspect of TON development is the asynchronous execution model. Messages sent by one contract take time to arrive at another, so the resulting transactions for processing incoming messages occur after the current transaction terminates.
Compared to Ethereum, where multiple messages and state changes on different contracts can be processed within the same atomic transaction, a TON transaction represents a state change only for one account and only for a processing of a single message. Even though in both blockchains a signed included-in-block unit is called a "transaction", one transaction on Ethereum usually corresponds to several transactions on TON, that are processed over a span of several blocks.
| Action description | Ethereum | TON |
| :--------------------------------------------------------------------------------------------- | -------------------------------------- | -------------------------------- |
| Single message processing with state change on one contract | Message call or "internal transaction" | Transaction |
| Number of state changes and messages on different accounts produced from initial contract call | Transaction | Chain of transactions or "trace" |
Consider a practical example: liquidity withdrawal on a DEX.
* On Ethereum, it appears as a single atomic transaction with multiple contract calls inside it. This transaction has a single hash and is included in one block.
21 bits among them, whichever is smaller.
Every map that is expected to grow beyond 1,000 values is dangerous. In the TVM map, key access is asymptotically logarithmic, meaning that gas consumption continuously increases to find keys as the map grows.
Instead, [sharding](/blockchain-basics/contract-dev/techniques/contract-sharding) should be used.
## Ecosystem [#ecosystem]
### Tooling [#tooling]
The recommended programming language for smart contract development in TON is [Tolk](/blockchain-basics/tolk/overview). Other established languages also exist and are still used, albeit in legacy status.
For off-chain software, TypeScript is the most adopted language in TON. Most of the tooling, bindings and [SDKs](/applications/sdks) are implemented in TypeScript.
| Use case | Ethereum tool | TON counterparts |
| :------------------------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------- |
| Blockchain interaction | Ethers, Web3.js, Viem | [`@ton/ton`](https://www.npmjs.com/package/@ton/ton), [Asset-sdk](https://github.com/ton-community/assets-sdk) |
| Wallet connection protocol | WalletConnect, Wagmi | [TON Connect](https://github.com/ton-connect) |
| Dev environment framework / scripting | Hardhat, Truffle | [Acton](https://github.com/ton-blockchain/acton), [Blueprint](https://github.com/ton-org/blueprint) |
| Simulation engine | Revm & Reth | [Emulator within Acton](https://github.com/ton-blockchain/acton), [Sandbox](https://github.com/ton-org/sandbox) |
For low-level manipulation of TON-specific data structures, there is [`@ton/core`](https://www.npmjs.com/package/@ton/core). Another library with wrappers for most important contracts and HTTP APIs is [`@ton/ton`](https://www.npmjs.com/package/@ton/ton).
### Services [#services]
Web3 developers often rely on specific products and services for on-chain development.
The following table showcases some use cases that existing TON services support.
| Use case | Ethereum service | TON service |
| --------------------------------------- | ---------------- | -------------------------------------------------------------------- |
| User-friendly explorer | Etherscan | [Tonviewer](https://tonviewer.com/), [Tonscan](https://tonscan.org/) |
| Open-source dev explorer | Blockscout | [TON Explorer](https://explorer.toncoin.org/) |
| Debugger | Remix Debugger | [TxTracer](https://txtracer.ton.org/) |
| IDE | Remix IDE | [Web IDE](https://ide.ton.org/) |
| Asm playground and compilation explorer | EVM.Codes | [TxTracer](https://txtracer.ton.org/) |
### Standards [#standards]
The table maps Ethereum standards and proposals, including ERC and EIP, to their TON counterparts, referred to as TEP.
Due to significant differences in execution models, most of the standards in TON differ significantly in semantics and general approach compared to their Ethereum analogs.
| Description | Ethereum standard | TON Standard (TEP) |
| --------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------ |
| Fungible token standard | ERC-20 | [Jettons (TEP-0074)](/blockchain-basics/standard/tokens/jettons/overview) |
| Non-fungible token standard | ERC-721 | [NFT standard (TEP-0062)](/blockchain-basics/standard/tokens/nft/overview) |
| Token metadata | ERC-4955 (Not exactly, but close match) | [Token Data Standard (TEP-0064)](/blockchain-basics/standard/tokens/metadata) |
| NFT royalty standard | EIP-2981 | [NFT Royalty Standard (TEP-0066)](/blockchain-basics/standard/tokens/nft/comparison) |
| DNS-like registry | ENS (EIP-137) | [DNS Standard (TEP-0081)](/blockchain-basics/primitives/web3/overview) |
| Soulbound / account-bound token concept | EIP-4973 | [SBT Standard (TEP-0085)](/blockchain-basics/standard/tokens/nft/comparison#sbt) |
| Wallet connection protocol | WalletConnect / EIP-1193 | [TonConnect (TEP-0115)](/applications/ton-connect/overview) |
# Glossary (/overview/learn-more/glossary)
## A [#a]
### Airdrop [#airdrop]
a free distribution of tokens among specific participants.
### Altcoin [#altcoin]
all cryptocurrencies, except Bitcoin, are called altcoins.
### Application Programming Interface (API) [#application-programming-interface-api]
a mechanism that allows two programs to interact with each other through a series of protocols.
### Annual Percentage Yield (APY) [#annual-percentage-yield-apy]
a calculated yearly interest rate for a given asset.
***
## B [#b]
### Bearish [#bearish]
the term “bearish” is used when the price of an asset has declined due to investors selling. (The term is often used to describe the overall market sentiment.)
### Binance [#binance]
a major cryptocurrency exchange. [Website](https://www.binance.com/).
### Bitcoin (BTC) [#bitcoin-btc]
the preeminent cryptocurrency and the first decentralized network with open-source code, which laid the groundwork for the proliferation of blockchain technology. [**Wikipedia**](https://en.wikipedia.org/wiki/Bitcoin).
### Blockchain [#blockchain]
a distributed ledger of data in the form of a chain of blocks recording transaction information for every event on the network.
### Bag of Cells (BoC) [#bag-of-cells-boc]
serialization format for cells. Commonly used in code. [Article](/blockchain-basics/primitives/serialization/boc).
### Bot [#bot]
a program written for two ecosystems to interact with each other — e.g., The Open Network and the Telegram messenger. On Telegram, bots are accounts in the messenger operated by software.
### Bridge [#bridge]
a program connecting various blockchains to transfer tokens and data from one network to another. [Article](/overview/infrastructure/oracles/overview).
### Bullish [#bullish]
the term “bullish” is used to describe an asset whose value is appreciating. (“Bullish” is the opposite of “bearish” — i.e., when the market's overall value is increasing.)
### Burning [#burning]
the act of permanently removing tokens from circulating and total supply.
***
## C [#c]
### Centralized exchange (CEX) [#centralized-exchange-cex]
a centralized cryptocurrency exchange to trade tokens.
### CoinMarketCap (CMC) [#coinmarketcap-cmc]
a crypto information aggregator that closely follows changes in token prices and market capitalization. [Website](https://coinmarketcap.com/).
### Coinbase [#coinbase]
a major cryptocurrency exchange based in the United States. [Website](https://www.coinbase.com/).
### Cryptobot [#cryptobot]
a peer-to-peer (P2P) bot service for buying, trading, and selling Toncoin and other cryptocurrencies.
### Custodial [#custodial]
a type of crypto wallet where a third party stores cryptocurrencies, and not their true owner.
***
## D [#d]
### Decentralized application (dApp) [#decentralized-application-dapp]
applications run on-chain and rely on smart contracts for computation, storage, and communication.
### Dollar-cost averaging (DCA) [#dollar-cost-averaging-dca]
an investment strategy whereby investors buy a fixed amount at regular intervals regardless of price to reduce timing risk.
### Decentralization [#decentralization]
one of the main tenets behind TON and other blockchains. Without decentralization, Web3 would be impossible to achieve; therefore, every element of the TON ecosystem revolves around maximizing decentralization.
### DeFi [#defi]
the decentralized analog to traditional finance; it includes accessible financial services and applications based on smart contracts.
### Decentralized exchange (DEX) [#decentralized-exchange-dex]
an exchange where users can trade cryptocurrencies without any intermediaries. The online entity needed to guarantee safe transactions is the blockchain itself.
### Diamond hands [#diamond-hands]
a colloquial term describing an investor who has no intention of selling their assets regardless of the state of the market — even if there's a crash or the market is bearish.
### Domain Name System (DNS) [#domain-name-system-dns]
a technology that translates human-readable domain names (e.g. ton.org) to machine-readable IP addresses (e.g. 192.0.2.44).
### Dolphin [#dolphin]
an investor who has relatively small capital but has an influence on the community.
### Donate [#donate]
a bot service on Telegram through which people can donate money, and content creators can monetize their channels and services in Toncoin.
### Dump [#dump]
rapidly selling a cryptocurrency or asset, often causing a price decline.
### Durov [#durov]
Pavel Durov, a Russian entrepreneur who is famous for having founded the VK social network and Telegram messenger.
Nikolai Durov is Pavel's brother, who helped develop VK, Telegram, and TON.
### Do Your Own Research (DYOR) [#do-your-own-research-dyor]
the process by which you do research on a project, company or cryptocurrency before deciding to invest.
***
## E [#e]
### Ethereum Virtual Machine (EVM) [#ethereum-virtual-machine-evm]
a machine behaving like a decentralized computer, it computes the state of the Ethereum blockchain after each new block and executes smart contracts.
### Exchange [#exchange]
a place for trading and using other market instruments.
***
## F [#f]
### Farming [#farming]
lending your crypto assets to receive rewards.
### Fiat [#fiat]
regular money issued by central banks or financial authorities.
### Fear of missing out (FOMO) [#fear-of-missing-out-fomo]
a psychological state that consumes some investors when the idea of losing potential gains from an opportunity is present. It usually appears during a bull market and when traders don't do their due diligence analyzing a particular project.
### Fungible tokens [#fungible-tokens]
cryptocurrencies that carry the same value as any other token of the same kind at any given moment.
### FUD [#fud]
“fear, uncertainty, and doubt,” market sentiments based on many factors.
### Full node [#full-node]
a computer on blockchain that synchronizes and copies the entire blockchain.
### FunC [#func]
the smart contract language on TON.
***
## G [#g]
### Gas [#gas]
the fee paid for transactions on the blockchain.
### GitHub [#github]
a platform for hosting code and collaborating via Git repositories.
***
## H [#h]
### Hackathon [#hackathon]
a collaborative event where programmers and builders develop software projects.
### Hash [#hash]
a fixed-size digest computed from data using a hashing algorithm.
### Hash rate [#hash-rate]
the indication of how much computational power is being used on a network for crypto mining.
### Hold [#hold]
saving — i.e., not selling — an asset or assets from your portfolio.
***
## I [#i]
### Initial Coin Offering (ICO) [#initial-coin-offering-ico]
a method for crypto projects to attract capital in the early stages.
### Initial Decentralized exchange Offering (IDO) [#initial-decentralized-exchange-offering-ido]
a method of attracting capital when launching a cryptocurrency or token on a decentralized exchange.
### Inflation [#inflation]
the process when the value of a currency — e.g., U.S. dollar or the euro — decreases. Toncoin has predictable issuance and a low inflation rate.
***
## K [#k]
### Know Your Customer (KYC) [#know-your-customer-kyc]
the process by which a user verifies their identity when creating an account for a crypto service.
***
## L [#l]
### Launchpad [#launchpad]
a platform for crypto startups that brings investors and projects together.
### Liquidity pool [#liquidity-pool]
grouping together crypto assets and freezing them in a smart contract. Liquidity pools are used for decentralized trading, loans, and other endeavors.
***
## M [#m]
### Mainnet [#mainnet]
the main network of a blockchain.
### Market capitalization (market cap) [#market-capitalization-market-cap]
the total market value of a cryptocurrency's circulating supply.
### Masterchain [#masterchain]
the main chain that references shard and workchain blocks; a shard block is finalized once a Masterchain block references it.
### Metaverse [#metaverse]
a digital universe similar to a video game where users create avatars and interact with the digital representations of other people or users.
### Moon [#moon]
a crypto term that describes a crypto asset's vertical trajectory on a price chart — i.e., it quickly gains value.
***
## N [#n]
### "Not financial advice" (NFA) [#not-financial-advice-nfa]
acronym used as a disclaimer to avoid liability or responsibility when investors discuss cryptocurrencies or projects with other people.
### Non-fungible token (NFT) [#non-fungible-token-nft]
a unique digital token on a blockchain that cannot be duplicated or minted more than once.
### Nominator [#nominator]
those who provide financial resources to validators so the latter can confirm blocks on TON blockchain.
### Non-custodial [#non-custodial]
a kind of crypto wallet that gives full control over assets to the owner/user.
***
## O [#o]
### Off-ramp [#off-ramp]
ways to convert cryptocurrencies into fiat money.
### On-ramp [#on-ramp]
ways to convert (buy) cryptocurrency by spending fiat money.
### Onion routing [#onion-routing]
a technology similar to Tor that allows anonymous interactions on a network. All messages are encrypted in various layers akin to an onion. TON Proxy applies such a technique.
***
## P [#p]
### Paper hands [#paper-hands]
an investor who's inclined to panic-sell — an inexperienced investor.
### Proof-of-stake [#proof-of-stake]
a consensus mechanism to process transactions in new blocks on the blockchain.
### Proof-of-work [#proof-of-work]
a consensus algorithm where one party proves to another that a specific amount of computational work was spent. By expending a little energy, a party can verify this.
### Proxy [#proxy]
a service on a computer network that allows clients to establish indirect network connections with other network services.
### Pump [#pump]
artificially inflating the price of a cryptocurrency or asset.
### Peer-to-peer (P2P) [#peer-to-peer-p2p]
transactions among users without the help of a third party or intermediary.
***
## R [#r]
### Roadmap [#roadmap]
a project's strategic plan that displays when its products, services, updates, etc. will be released.
### Return on investment (ROI) [#return-on-investment-roi]
the profits made from investments.
***
## S [#s]
### Soulbound token (SBT) [#soulbound-token-sbt]
an NFT that can never be transferred because it contains information about its owner and their accomplishments.
### Scalability [#scalability]
the ability of a blockchain network to process complex transactions as well as a large number of them.
### Securities and Exchange Commission (SEC) [#securities-and-exchange-commission-sec]
a financial regulator in the United States. [Website](https://www.sec.gov/).
### Shard [#shard]
a mechanism that helps a blockchain network to scale by breaking into smaller blockchains to relieve network congestion — something which TON blockchain does.
### Smart contract [#smart-contract]
self-executing code that oversees and enables operations with the help of mathematical algorithms and without human intervention.
### Spot trading [#spot-trading]
trading a financial asset for money.
### Stablecoin [#stablecoin]
a cryptocurrency that aims to maintain a stable value (often pegged to a fiat currency).
### Staking [#staking]
a way for users to earn a passive income by storing coins or tokens in a proof-of-stake algorithm, which, in turn, ensures the blockchain runs smoothly. For this, they earn rewards as an incentive.
### Swap [#swap]
the exchange of two financial assets — e.g., Toncoin for USDT.
***
## T [#t]
### TON Enhancement Proposals (TEPs) [#ton-enhancement-proposals-teps]
a [standard set](https://github.com/ton-blockchain/TEPs) of ways to interact with various parts of the TON ecosystem.
### TON Pay [#ton-pay]
a payment integration for TON that provides APIs, UI components, and webhooks for creating and tracking transfers.
### Testnet [#testnet]
a network for testing projects or services before launching on the mainnet.
### Ticker [#ticker]
the short form of a cryptocurrency, asset, or token on exchanges, trading services, or other DeFi solutions — e.g. TON for Toncoin.
### The Merge [#the-merge]
the transition process of Ethereum switching from proof-of-work to proof-of-stake.
### Token [#token]
a form of digital asset; it can have multiple functions.
### Tokenomics [#tokenomics]
the economic plan and distribution strategy of a cryptocurrency (or token).
### To the moon [#to-the-moon]
a colloquial phrase used when people create FOMO. It refers to hopefuls wanting the value of a cryptocurrency rapidly gaining a lot of value — hence its trajectory to the moon.
### Toncoin [#toncoin]
the native cryptocurrency of the TON ecosystem, which is used to develop services and pay for fees and services. It can be bought, sold, and traded.
### Trading [#trading]
buying and selling cryptocurrencies with the goal of making a profit.
### Total Value Locked (TVL) [#total-value-locked-tvl]
the total value of assets currently locked (e.g. staked) in a specific protocol.
### TON Virtual Machine (TVM) [#ton-virtual-machine-tvm]
a machine that behaves like a decentralized computer; it computes the state of the TON blockchain after each new block and executes smart contracts.
***
## V [#v]
### Validator [#validator]
those who verify new blocks on TON blockchain.
***
## W [#w]
### “We're all gonna make it” (WAGMI) [#were-all-gonna-make-it-wagmi]
a sentence often used in the crypto community to express the aspirations of becoming rich one day by investing in cryptocurrencies.
### Wallet [#wallet]
an application that manages private keys and assets for sending, receiving, and storing cryptocurrencies. A Telegram bot (e.g., @wallet) also provides wallet functions within the TON ecosystem.
### Web3 [#web3]
a new generation of the internet based on blockchain technology that includes decentralization and tokenomics.
### Whale [#whale]
an investor who owns a large number of cryptocurrencies and tokens.
### White paper [#white-paper]
the main document of a project written by its developers. It explains the technology and the project's goals.
### Watchlist [#watchlist]
a customizable list of cryptocurrencies whose price action an investor wishes to follow.
### Workchain [#workchain]
secondary chains that connect to the masterchain. They can contain a massive number of different connected chains that have their own consensus rules. They can also contain address and transaction information and virtual machines for smart contracts. Additionally, they can be compatible with the masterchain and interact with one another.
***
## Y [#y]
### Yield farming [#yield-farming]
lending or placing cryptocurrencies or tokens in a smart contract to earn rewards in the form of transaction fees.
# Other resources (/overview/learn-more/more-tutorials)
This page collects additional learning resources beyond this documentation. You'll find a mix of official content not hosted in this documentation and community-created materials to help you continue your journey.
Whether you prefer structured courses, in-depth articles, video tutorials, or real code examples, there is something here to match your learning style and current skill level.
## Courses [#courses]
### Blockchain basics with TON [#blockchain-basics-with-ton]
Deprecated
This course introduces blockchain basics, focusing on practical skills in the TON ecosystem. You will understand how blockchain functions and its diverse applications.
This course is for junior developers, people new to crypto, non-technical IT professionals, and anyone curious about blockchains.
* [English](https://stepik.org/course/201294/promo)
* [Chinese](https://stepik.org/course/200976/promo)
* [Russian](https://stepik.org/course/202221/promo)
### TON & Telegram Blockchain development [#ton--telegram-blockchain-development]
Deprecated
The course is aimed at developers and IT specialists interested in gaining practical knowledge about the technologies and concepts of the TON Blockchain, such as FunC, dApps, decentralization, smart contracts, contract testing, as well as the creation of Mini Apps within Telegram.
* [English](https://stepik.org/course/176754/promo)
* [Chinese](https://stepik.org/course/201638/promo)
* [Russian](https://stepik.org/course/201855/promo)
## Articles [#articles]
Introductory:
* [How a Blockchain Can Help You on a Deserted Island](https://talkol.medium.com/why-decentralized-consensus-blockchain-is-good-for-business-5ff263468210)
Beginner-friendly:
* [What is Blockchain? What is a Smart Contract? What is Gas?](https://blog.ton.org/what_is_blockchain)
### "Hello World" guide series [#hello-world-guide-series]
A step-by-step tutorial series that starts with creating a new TON wallet and ends with a working, test-covered, and deployed smart contract, along with a Telegram Mini App frontend for it.
* [Part 1: Working with your first TON wallet](https://helloworld.tonstudio.io/01-wallet/)
* [Part 2: Writing your first smart contract](https://helloworld.tonstudio.io/02-contract/)
* [Part 3: Building your first web client](https://helloworld.tonstudio.io/03-client/)
* [Part 4: Testing your first smart contract](https://helloworld.tonstudio.io/04-testing/)
## Videos [#videos]
Introductory:
* [Crypto Networks and Why They Matter](https://www.youtube.com/watch?v=2wxtiNgXBaU)
### Playlists [#playlists]
Beginner-friendly:
* [TON Development with Tact](https://www.youtube.com/watch?v=Vf3Fx7qgL6k\&list=PLQ5rEj25H3U2P5qp7nsgVtNGYxEojnnez)
{/* NOTE: ## Podcasts */}
## Interactive learning [#interactive-learning]
### Code playgrounds [#code-playgrounds]
* [TxTracer](https://txtracer.ton.org/) - Trace and analyze TON Blockchain transactions with tools to visualize execution, inspect and debug smart contracts with a code editor and user-friendly interface.
* [Assembly Playground](https://txtracer.ton.org/play/) - Experiment with TVM assembly code directly in your browser. Write, test, and debug assembly instructions with real-time execution.
* [Code Explorer](https://txtracer.ton.org/code-explorer/) - Compile FunC or Tolk code to assembly and explore the generated bytecode to understand how your smart contracts work under the hood.
* [TVM Instruction table](https://txtracer.ton.org/spec/) - Browse the TVM instruction reference with detailed descriptions, opcodes, stack effects, and control flow information for every instruction.
* [Sandbox](https://txtracer.ton.org/sandbox/) - Inspect transactions produced by your local tests using the `@ton/sandbox` package. Visualize messages, transaction info, VM logs and exit codes with an interactive UI.
{/* NOTE: ### Tours */}
### Challenges and exercises [#challenges-and-exercises]
* [Hack the TON](https://www.hacktheton.com/en) - TON-based wargame inspired by The Ethernaut, played in the TON Virtual Machine. Each level is a smart contract that needs to be hacked. Our goal is to help you to learn how to develop safe TON smart contracts and build a thriving community around this craft.
## Smart contract examples [#smart-contract-examples]
Examples of smart contracts on TON include wallets, electors (which manage validator elections on TON), multi-signature wallets, and many more. They can serve as an excellent reference for those studying on real projects.
* [Tolk benchmark contracts](https://github.com/ton-blockchain/tolk-bench) - Tolk vs. FunC gas benchmarks and, simultaneously, reference Tolk contracts.
## Join the community [#join-the-community]
* [All TON communities](https://ton.org/en/community)
* [Telegram Dev chats](https://t.me/addlist/1r5Vcb8eljk5Yzcy)
# Get your TON Center API key (/applications/api/toncenter/get-api-key)
To interact with TON Center's API at higher rate limits, you'll need to generate an API key via the official [Telegram bot](https://t.me/toncenter).
## Open the TON Center bot [#open-the-ton-center-bot]
Open the [`@toncenter`](https://t.me/toncenter) bot in Telegram. Click **Start** to begin the setup.
## (optional) Upgrade your plan [#optional-upgrade-your-plan]
To upgrade:
* Select your desired plan in the bot interface and click **Purchase Subscription**.
* You'll be shown payment instructions like the following:
Direct liteserver for balances, sending transactions, contract queries.
Indexed database for traces, Jettons, NFTs, and historical queries.
Low-latency updates on subscriptions through SSE or WebSockets.
# Rate limits (/applications/api/toncenter/rate-limit)
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](/applications/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 [#default-limits]
| Plan | Tokens per network | Requests per second | Notes |
| ---------- | ------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------- |
| Free | 1 | 10 | Shared liteservers suitable for low-volume testing and small projects. |
| Plus | 3 | 25 | Private liteservers that reduce contention compared to shared access. |
| Advanced | 10 | 100 | Private infrastructure with capacity for higher request rates. |
| Enterprise | Custom | Custom | Custom throughput and support. Contact [`@toncenter_support`](https://t.me/toncenter_support) for details. |
Rate limits apply to all API keys in total separately for every TON network, including mainnet and testnet. For example, the Plus plan users can create three API keys for the mainnet. The total limit for these three keys will be 25 requests per second.
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.
## Rate limit exceeded [#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 is 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.
## Troubleshooting [#troubleshooting]
If a paid plan is active but the rate remains 1 RPS:
* Check that the API key is included correctly in the 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.
# API authentication (/applications/api/toncenter/v2-authentication)
## Overview [#overview]
The API v2 accepts an API key for all methods, including the JSON-RPC endpoint. Requests without an API key are limited to one request per second. To make more than one request per second, please include an API key.
The key can be sent either in an HTTP header or as a query parameter. Only one of these is needed per request.
To obtain an API key, see the [TON Center API key guide](/applications/api/toncenter/get-api-key).
| Method | Location | Name |
| ------- | -------- | ----------- |
| API key | Header | `X-API-Key` |
| API key | Query | `api_key` |
Never expose the API key in client-side code or public repositories. Store keys in a secrets manager or environment variables, rotate them periodically, and generate a new key immediately if one is compromised.
## Public hosts [#public-hosts]
| Network | Host |
| ------- | -------------------------------------- |
| Testnet | `https://testnet.toncenter.com/api/v2` |
| Mainnet | `https://toncenter.com/api/v2` |
## REST endpoint authentication [#rest-endpoint-authentication]
### Header authentication [#header-authentication]
Send the API key in the `X-API-Key` header:
```bash
curl "https://testnet.toncenter.com/api/v2/getMasterchainInfo" \
-H "X-API-Key: "
```
### Query parameter authentication [#query-parameter-authentication]
Pass the key as a query parameter named `api_key`:
```bash
curl "https://testnet.toncenter.com/api/v2/getMasterchainInfo?api_key="
```
Both forms are equivalent.
## JSON-RPC endpoint authentication [#json-rpc-endpoint-authentication]
**Endpoint:** `POST /api/v2/jsonRPC`
The same API key rules apply. Example using header authentication:
```bash
curl "https://testnet.toncenter.com/api/v2/jsonRPC" \
-H "Content-Type: application/json" \
-H "X-API-Key: " \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "getMasterchainInfo",
"params": {}
}'
```
Or using the query parameter:
```bash
curl "https://testnet.toncenter.com/api/v2/jsonRPC?api_key=" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "getMasterchainInfo",
"params": {}
}'
```
## API key error codes [#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. |
# API error codes (/applications/api/toncenter/v2-errors)
All TON Center API v2 methods use a standard set of HTTP status codes to indicate the result of a request.
| Status code | Description |
| --------------------------- | ------------------------------------------------------------------------------------------- |
| `404 Not Found` | The requested resource does not exist in storage. |
| `405 Method Not Allowed` | The endpoint was called with an unsupported HTTP method. Use GET or POST. |
| `409 Conflict` | The resource was found but does not match the expected type for this method. |
| `422 Unprocessable Content` | The request parameters failed validation (e.g., missing, malformed, or conflicting values). |
| `429 Too Many Requests` | Too many requests. Back off and retry. |
| `500 Internal Server Error` | An internal error occurred. Retry or contact support if it persists. |
| `504 Gateway Timeout` | The liteserver did not respond in time. Retry the request. |
| `542 Server Error` | A liteserver error or an unsupported TVM stack type was encountered. |
For method-specific error messages and troubleshooting details, refer to the documentation for the relevant endpoint.
# Tonlib type identifiers (/applications/api/toncenter/v2-tonlib-types)
Every object returned by API v2 includes a `@type` field that identifies the object's structure. These values originate from two sources:
1. Tonlib types such as `raw.fullAccountState` and `tvm.cell` come from the [tonlib TL schema](https://github.com/ton-blockchain/ton/blob/a31025f39ed0dae5f6799280133624dc3a23cefb/tl/generate/scheme/tonlib_api.tl), the type definition language used by the C++ library powering this API.
2. Extended types, which are prefixed with `ext.`, are added by TON Center to provide parsed representations with additional decoded fields that are not available in the base tonlib schema.
The `@type` field acts as a **discriminator**: when a response can return different object shapes, the `@type` value indicates which fields to expect. This pattern is useful for type-safe deserialization in statically typed languages.
```json
{
"@type": "raw.fullAccountState",
"balance": "1000000000",
"code": "te6cc...",
"data": "te6cc...",
"last_transaction_id": {
"@type": "internal.transactionId",
"lt": "12345678",
"hash": "abc..."
}
}
```
## TL primitive types [#tl-primitive-types]
The TL schema maps to JSON types as follows:
| TL type | JSON type | Notes |
| :---------- | :-------- | :------------------------------------------------------------- |
| `int32` | number | 32-bit signed integer |
| `int53` | number | 53-bit signed integer; safe for JavaScript `Number` |
| `int64` | string | 64-bit signed integer as decimal string; exceeds JS safe range |
| `int256` | string | 256-bit integer as decimal or hex string |
| `bytes` | string | Binary data, base64-encoded |
| `string` | string | UTF-8 text |
| `Bool` | boolean | `true` or `false` |
| `vector` | array | Ordered list of elements of type `T` |
## Account state [#account-state]
When querying account information, the `account_state` field uses `@type` to indicate which kind of contract is deployed. The TL schema defines these as variants of `AccountState`:
```tl
raw.accountState code:bytes data:bytes frozen_hash:bytes = AccountState;
wallet.v3.accountState wallet_id:int64 seqno:int32 = AccountState;
wallet.v4.accountState wallet_id:int64 seqno:int32 = AccountState;
wallet.highload.v1.accountState wallet_id:int64 seqno:int32 = AccountState;
wallet.highload.v2.accountState wallet_id:int64 = AccountState;
dns.accountState wallet_id:int64 = AccountState;
rwallet.accountState wallet_id:int64 seqno:int32 unlocked_balance:int64 config:rwallet.config = AccountState;
pchan.accountState config:pchan.config state:pchan.State description:string = AccountState;
uninited.accountState frozen_hash:bytes = AccountState;
```
| `@type` value | API schema | TL fields |
| :-------------------------------- | :----------------------------- | :------------------------------------------------- |
| `raw.accountState` | `AccountStateRaw` | `code`, `data`, `frozen_hash` |
| `wallet.v3.accountState` | `AccountStateWalletV3` | `wallet_id`, `seqno` |
| `wallet.v4.accountState` | `AccountStateWalletV4` | `wallet_id`, `seqno` |
| `wallet.highload.v1.accountState` | `AccountStateWalletHighloadV1` | `wallet_id`, `seqno` |
| `wallet.highload.v2.accountState` | `AccountStateWalletHighloadV2` | `wallet_id` |
| `dns.accountState` | `AccountStateDns` | `wallet_id` |
| `rwallet.accountState` | `AccountStateRWallet` | `wallet_id`, `seqno`, `unlocked_balance`, `config` |
| `pchan.accountState` | `AccountStatePChan` | `config`, `state`, `description` |
| `uninited.accountState` | `AccountStateUninited` | `frozen_hash` |
## Account information [#account-information]
Full account queries return one of these top-level types:
```tl
raw.fullAccountState balance:int64 extra_currencies:vector code:bytes data:bytes
last_transaction_id:internal.transactionId block_id:ton.blockIdExt frozen_hash:bytes sync_utime:int53
= raw.FullAccountState;
fullAccountState address:accountAddress balance:int64 extra_currencies:vector
last_transaction_id:internal.transactionId block_id:ton.blockIdExt sync_utime:int53
account_state:AccountState revision:int32
= FullAccountState;
```
| `@type` value | API schema | Description |
| :------------------------------- | :--------------------------- | :------------------------------------------------------------------- |
| `raw.fullAccountState` | `AddressInformation` | Raw state with balance, code, data, and frozen hash. |
| `fullAccountState` | `ExtendedAddressInformation` | Parsed state with identified contract type. |
| `ext.accounts.walletInformation` | `WalletInformation` | Wallet-specific: `type`, `seqno`, `wallet_id`; TON Center extension. |
## Address types [#address-types]
```tl
accountAddress account_address:string = AccountAddress;
```
| `@type` value | API schema | TL fields |
| :--------------- | :--------------- | :---------------- |
| `accountAddress` | `AccountAddress` | `account_address` |
| `addr_std` | `SmcAddr` | `workchain`, `id` |
## Block identifiers [#block-identifiers]
```tl
ton.blockIdExt workchain:int32 shard:int64 seqno:int32 root_hash:bytes file_hash:bytes = ton.BlockIdExt;
```
| `@type` value | API schema | TL fields |
| :--------------- | :-------------- | :------------------------------------------------------ |
| `ton.blockIdExt` | `TonBlockIdExt` | `workchain`, `shard`, `seqno`, `root_hash`, `file_hash` |
## Block data [#block-data]
These types are returned by block query endpoints. The TL definitions:
```tl
blocks.masterchainInfo last:ton.BlockIdExt state_root_hash:bytes init:ton.BlockIdExt = blocks.MasterchainInfo;
blocks.shards shards:vector = blocks.Shards;
blocks.header id:ton.blockIdExt global_id:int32 version:int32 flags:# after_merge:Bool after_split:Bool
before_split:Bool want_merge:Bool want_split:Bool validator_list_hash_short:int32 catchain_seqno:int32
min_ref_mc_seqno:int32 is_key_block:Bool prev_key_block_seqno:int32 start_lt:int64 end_lt:int64
gen_utime:int53 vert_seqno:# prev_blocks:vector = blocks.Header;
blocks.transactions id:ton.blockIdExt req_count:int32 incomplete:Bool
transactions:vector = blocks.Transactions;
blocks.transactionsExt id:ton.blockIdExt req_count:int32 incomplete:Bool
transactions:vector = blocks.TransactionsExt;
blocks.blockSignatures id:ton.blockIdExt signatures:(vector blocks.signature) = blocks.BlockSignatures;
blocks.shardBlockProof from:ton.blockIdExt mc_id:ton.blockIdExt
links:(vector blocks.shardBlockLink) mc_proof:(vector blocks.blockLinkBack) = blocks.ShardBlockProof;
blocks.outMsgQueueSizes shards:(vector blocks.outMsgQueueSize)
ext_msg_queue_size_limit:int32 = blocks.OutMsgQueueSizes;
```
| `@type` value | API schema | Description |
| :-------------------------- | :--------------------------- | :-------------------------------------------- |
| `blocks.masterchainInfo` | `MasterchainInfo` | Latest and genesis block references. |
| `blocks.shards` | `Shards` | Active shard block identifiers. |
| `blocks.header` | `BlockHeader` | Block metadata, merge or split flags, timing. |
| `blocks.transactions` | `BlockTransactions` | Short transaction IDs within a block. |
| `blocks.transactionsExt` | `BlockTransactionsExt` | Full transactions within a block. |
| `blocks.shortTxId` | `ShortTxId` | Compact reference: account, lt, hash. |
| `blocks.blockSignatures` | `MasterchainBlockSignatures` | Validator signatures for a block. |
| `blocks.signature` | `BlockSignature` | Single validator signature. |
| `blocks.shardBlockProof` | `ShardBlockProof` | Merkle proof chain to masterchain. |
| `blocks.shardBlockLink` | `ShardBlockLink` | Single link in a proof chain. |
| `blocks.blockLinkBack` | `BlockLinkBack` | Backward proof link between blocks. |
| `blocks.outMsgQueueSize` | `OutMsgQueueSize` | Per-shard queue size. |
| `blocks.outMsgQueueSizes` | `OutMsgQueueSizes` | Queue sizes across all shards. |
| `ext.blocks.consensusBlock` | `ConsensusBlock` | Latest finalized block; TON Center extension. |
## Transactions and messages [#transactions-and-messages]
```tl
raw.transaction address:accountAddress utime:int53 data:bytes transaction_id:internal.transactionId
fee:int64 storage_fee:int64 other_fee:int64 in_msg:raw.message
out_msgs:vector = raw.Transaction;
raw.transactions transactions:vector
previous_transaction_id:internal.transactionId = raw.Transactions;
raw.message hash:bytes source:accountAddress destination:accountAddress value:int64
extra_currencies:vector fwd_fee:int64 ihr_fee:int64 created_lt:int64
body_hash:bytes msg_data:msg.Data = raw.Message;
raw.extMessageInfo hash:bytes hash_norm:bytes = raw.ExtMessageInfo;
internal.transactionId lt:int64 hash:bytes = internal.TransactionId;
```
| `@type` value | API schema | Description |
| :----------------------- | :---------------------- | :-------------------------------------------------------- |
| `raw.transaction` | `TransactionStd` | Raw transaction with messages and fees. |
| `raw.transactions` | `TransactionsStd` | Paginated transaction list with cursor. |
| `raw.message` | `MessageStd` | Raw message with sender, recipient, value. |
| `raw.extMessageInfo` | `ExtMessageInfo` | External message hash after broadcast. |
| `internal.transactionId` | `InternalTransactionId` | Transaction reference: lt + hash. |
| `ext.transaction` | `Transaction` | Transaction with decoded comments; TON Center extension. |
| `ext.message` | `Message` | Message with decoded text comments; TON Center extension. |
### Message body types [#message-body-types]
The `msg_data` field on messages uses `@type` to indicate how to interpret the body:
```tl
msg.dataRaw body:bytes init_state:bytes = msg.Data;
msg.dataText text:bytes = msg.Data;
msg.dataDecryptedText text:bytes = msg.Data;
msg.dataEncryptedText text:bytes = msg.Data;
```
| `@type` value | API schema | Description |
| :---------------------- | :--------------------- | :---------------------------------------- |
| `msg.dataRaw` | `MsgDataRaw` | Raw binary body + optional init state. |
| `msg.dataText` | `MsgDataText` | Plain text comment; base64-encoded UTF-8. |
| `msg.dataEncryptedText` | `MsgDataEncryptedText` | Encrypted message body. |
| `msg.dataDecryptedText` | `MsgDataDecryptedText` | Decrypted message body. |
## TVM types [#tvm-types]
Used as input and output for smart contract get methods: `runGetMethod`, `runGetMethodStd`.
### Stack entries [#stack-entries]
Each stack entry wraps a value with a type tag:
```tl
tvm.stackEntryNumber number:tvm.Number = tvm.StackEntry;
tvm.stackEntryCell cell:tvm.cell = tvm.StackEntry;
tvm.stackEntrySlice slice:tvm.slice = tvm.StackEntry;
tvm.stackEntryTuple tuple:tvm.Tuple = tvm.StackEntry;
tvm.stackEntryList list:tvm.List = tvm.StackEntry;
tvm.stackEntryUnsupported = tvm.StackEntry;
```
| `@type` value | API schema | Value field |
| :-------------------------- | :------------------------- | :------------------------------------------------ |
| `tvm.stackEntryNumber` | `TvmStackEntryNumber` | `number` (decimal string via `tvm.numberDecimal`) |
| `tvm.stackEntryCell` | `TvmStackEntryCell` | `cell` (base64 BoC via `tvm.cell`) |
| `tvm.stackEntrySlice` | `TvmStackEntrySlice` | `slice` (base64 BoC via `tvm.slice`) |
| `tvm.stackEntryTuple` | `TvmStackEntryTuple` | `tuple` (nested stack entries) |
| `tvm.stackEntryList` | `TvmStackEntryList` | `list` (nested stack entries) |
| `tvm.stackEntryUnsupported` | `TvmStackEntryUnsupported` | No value (type not representable) |
### Value types [#value-types]
```tl
tvm.cell bytes:bytes = tvm.Cell;
tvm.slice bytes:bytes = tvm.Slice;
tvm.numberDecimal number:string = tvm.Number;
tvm.tuple elements:vector = tvm.Tuple;
tvm.list elements:vector = tvm.List;
```
| `@type` value | API schema | TL fields |
| :------------------ | :----------------- | :------------------------- |
| `tvm.cell` | `TvmCell` | `bytes` (base64 BoC) |
| `tvm.slice` | `TvmSlice` | `bytes` (base64 BoC) |
| `tvm.numberDecimal` | `TvmNumberDecimal` | `number` (decimal string) |
| `tvm.tuple` | `TvmTuple` | `elements` (stack entries) |
| `tvm.list` | `TvmList` | `elements` (stack entries) |
### Get method result [#get-method-result]
```tl
smc.runResult gas_used:int53 stack:vector exit_code:int32 = smc.RunResult;
```
| `@type` value | API schema | TL fields |
| :-------------- | :---------------------- | :------------------------------- |
| `smc.runResult` | `RunGetMethodResult` | `gas_used`, `stack`, `exit_code` |
| `smc.runResult` | `RunGetMethodStdResult` | Same fields, typed stack entries |
## Fees [#fees]
```tl
fees in_fwd_fee:int53 storage_fee:int53 gas_fee:int53 fwd_fee:int53 = Fees;
query.fees source_fees:fees destination_fees:vector = query.Fees;
```
| `@type` value | API schema | TL fields |
| :------------ | :---------- | :------------------------------------------------ |
| `fees` | `Fees` | `in_fwd_fee`, `storage_fee`, `gas_fee`, `fwd_fee` |
| `query.fees` | `QueryFees` | `source_fees`, `destination_fees` |
## Configuration [#configuration]
```tl
configInfo config:tvm.cell = ConfigInfo;
```
| `@type` value | API schema | TL fields |
| :------------ | :----------- | :-------------------------------- |
| `configInfo` | `ConfigInfo` | `config` TVM cell with parameters |
## Libraries [#libraries]
```tl
smc.libraryEntry hash:int256 data:bytes = smc.LibraryEntry;
smc.libraryResult result:(vector smc.libraryEntry) = smc.LibraryResult;
```
| `@type` value | API schema | TL fields |
| :------------------ | :-------------- | :----------------- |
| `smc.libraryEntry` | `LibraryEntry` | `hash`, `data` |
| `smc.libraryResult` | `LibraryResult` | `result` (entries) |
## Token types (TON Center extensions) [#token-types-ton-center-extensions]
These types are not in the base tonlib TL schema. They are added by TON Center to provide parsed Jetton and NFT data via the `getTokenData` endpoint.
| `@type` value | API schema | Description |
| :----------------------------- | :------------------ | :----------------------------------------------- |
| `ext.tokens.jettonMasterData` | `JettonMasterData` | Jetton master: total supply, admin, metadata. |
| `ext.tokens.jettonWalletData` | `JettonWalletData` | Jetton wallet: balance, owner, master reference. |
| `ext.tokens.nftCollectionData` | `NftCollectionData` | NFT collection: item count, owner, metadata. |
| `ext.tokens.nftItemData` | `NftItemData` | NFT item: index, owner, collection reference. |
## DNS record types [#dns-record-types]
DNS entries use `@type` to indicate the record type stored at a domain:
```tl
dns.entryDataNextResolver resolver:AccountAddress = dns.EntryData;
dns.entryDataSmcAddress smc_address:AccountAddress = dns.EntryData;
dns.entryDataAdnlAddress adnl_address:AdnlAddress = dns.EntryData;
dns.entryDataStorageAddress bag_id:int256 = dns.EntryData;
```
| `@type` value | API schema | TL fields |
| :----------------------------- | :------------------------ | :---------------------- |
| `dns.entryDataNextResolver` | `DnsRecordNextResolver` | `resolver` (address) |
| `dns.entryDataSmcAddress` | `DnsRecordSmcAddress` | `smc_address` (address) |
| `dns.entryDataAdnlAddress ` | `DnsRecordAdnlAddress` | `adnl_address` |
| `dns.entryDataStorageAddress ` | `DnsRecordStorageAddress` | `bag_id` (int256) |
## Payment channel types [#payment-channel-types]
```tl
pchan.config alice_public_key:string alice_address:accountAddress bob_public_key:string
bob_address:accountAddress init_timeout:int32 close_timeout:int32 channel_id:int64 = pchan.Config;
pchan.stateInit signed_A:Bool signed_B:Bool min_A:int64 min_B:int64
expire_at:int53 A:int64 B:int64 = pchan.State;
pchan.stateClose signed_A:Bool signed_B:Bool min_A:int64 min_B:int64
expire_at:int53 A:int64 B:int64 = pchan.State;
pchan.statePayout A:int64 B:int64 = pchan.State;
```
| `@type` value | API schema | Description |
| :------------------ | :----------------- | :----------------------------- |
| `pchan.config` | `PChanConfig` | Channel parties, timeouts, ID |
| `pchan.stateInit` | `PChanStateInit` | Initialization phase (signing) |
| `pchan.stateClose` | `PChanStateClose` | Closing phase (signing) |
| `pchan.statePayout` | `PChanStatePayout` | Payout phase (final balances) |
## Restricted wallet types [#restricted-wallet-types]
```tl
rwallet.limit seconds:int32 value:int64 = rwallet.Limit;
rwallet.config start_at:int53 limits:vector = rwallet.Config;
```
| `@type` value | API schema | TL fields |
| :--------------- | :-------------- | :------------------- |
| `rwallet.config` | `RWalletConfig` | `start_at`, `limits` |
| `rwallet.limit` | `RWalletLimit` | `seconds`, `value` |
## Utility types [#utility-types]
TON Center extensions.
| `@type` value | API schema | Description |
| :--------------------------------- | :--------------------------- | :------------------------------ |
| `ext.utils.detectedAddress` | `DetectAddress` | Address in all encoding formats |
| `ext.utils.detectedAddressVariant` | `DetectAddressBase64Variant` | Base64 and URL-safe base64 pair |
| `ext.utils.detectedHash` | `DetectHash` | Hash in hex, base64, URL-safe |
| `extraCurrency` | `ExtraCurrencyBalance` | Non-TON currency ID and balance |
| `ok` | `ResultOk` | Success with no return data |
## Reference [#reference]
For background on the TL-B format used across the TON ecosystem, see the [TL-B overview](/blockchain-basics/languages/tl-b/overview).
Types prefixed with `ext.` are TON Center extensions not present in the upstream TL schema.
# API authentication (/applications/api/toncenter/v3-authentication)
## Overview [#overview]
The API v3 accepts an API key for all methods. Requests without an API key are limited to one request per second. To make more than one request per second, please include an API key.
The key can be sent either in an HTTP header or as a query parameter. Only one of these is needed per request.
To obtain an API key, see the [TON Center API key guide](/applications/api/toncenter/get-api-key).
| Method | Location | Name |
| ------- | -------- | ----------- |
| API key | Header | `X-API-Key` |
| API key | Query | `api_key` |
Never expose the API key in client-side code or public repositories. Store keys in a secrets manager or environment variables, rotate them periodically, and generate a new key immediately if one is compromised.
## Public hosts [#public-hosts]
| Network | Host |
| ------- | -------------------------------------- |
| Testnet | `https://testnet.toncenter.com/api/v3` |
| Mainnet | `https://toncenter.com/api/v3` |
## REST endpoint authentication [#rest-endpoint-authentication]
### Header authentication [#header-authentication]
Send the API key in the `X-API-Key` header:
```bash
curl "https://testnet.toncenter.com/api/v3/masterchainInfo" \
-H "X-API-Key: "
```
### Query parameter authentication [#query-parameter-authentication]
Pass the key as a query parameter named `api_key`:
```bash
curl "https://testnet.toncenter.com/api/v3/masterchainInfo?api_key="
```
Both forms are equivalent.
## API key error codes [#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. |
# API error codes (/applications/api/toncenter/v3-errors)
All TON Center API v3 methods use a standard set of HTTP status codes to indicate the result of a request.
| Status code | Description |
| --------------------------- | ---------------------------------------------------------------------------------- |
| `401 Unauthorized` | A required parameter was not included in the request. |
| `404 Not Found` | The requested resource does not exist in storage. |
| `409 Conflict` | The resource was found but does not match the expected type for this method. |
| `422 Unprocessable Content` | The request parameters failed validation (e.g., conflicting or malformed filters). |
| `500 Internal Server Error` | An internal error occurred. Retry or contact support if it persists. |
For method-specific error messages and troubleshooting details, refer to the documentation for the relevant endpoint.
# Pagination (/applications/api/toncenter/v3-pagination)
The v3 API uses offset-based pagination. Each paginated endpoint accepts `limit` and `offset` parameters. `limit` controls how many results to return per request, and `offset` skips a number of rows from the beginning of the result set. To retrieve the next page, increment `offset` by the value of `limit`.
The following endpoints support pagination:
| Endpoint | Default limit | Max limit | Sortable |
| ------------------------------------------------------------------------------------------------------------------------ | :-----------: | :-------: | :------: |
| [`transactions`](/applications/api/toncenter/v3/blockchain-data/get-transactions) | 10 | 1000 | Yes |
| [`actions`](/applications/api/toncenter/v3/actions-and-traces/get-actions) | 10 | 1000 | Yes |
| [`blocks`](/applications/api/toncenter/v3/blockchain-data/get-blocks) | 10 | 1000 | Yes |
| [`messages`](/applications/api/toncenter/v3/blockchain-data/get-messages) | 10 | 1000 | Yes |
| [`traces`](/applications/api/toncenter/v3/actions-and-traces/get-traces) | 10 | 1000 | Yes |
| [`jetton/burns`](/applications/api/toncenter/v3/jettons/get-jetton-burns) | 10 | 1000 | Yes |
| [`jetton/transfers`](/applications/api/toncenter/v3/jettons/get-jetton-transfers) | 10 | 1000 | Yes |
| [`jetton/wallets`](/applications/api/toncenter/v3/jettons/get-jetton-wallets) | 10 | 1000 | Yes |
| [`nft/items`](/applications/api/toncenter/v3/nfts/get-nft-items) | 10 | 1000 | Yes |
| [`nft/transfers`](/applications/api/toncenter/v3/nfts/get-nft-transfers) | 10 | 1000 | Yes |
| [`multisig/orders`](/applications/api/toncenter/v3/multisig/get-multisig-orders) | 10 | 1000 | Yes |
| [`multisig/wallets`](/applications/api/toncenter/v3/multisig/get-multisig-wallets) | 10 | 1000 | Yes |
| [`transactionsByMasterchainBlock`](/applications/api/toncenter/v3/blockchain-data/get-transactions-by-masterchain-block) | 10 | 1000 | Yes |
| [`jetton/masters`](/applications/api/toncenter/v3/jettons/get-jetton-masters) | 10 | 1000 | No |
| [`nft/collections`](/applications/api/toncenter/v3/nfts/get-nft-collections) | 10 | 1000 | No |
| [`dns/records`](/applications/api/toncenter/v3/dns/get-dns-records) | 100 | 1000 | No |
| [`masterchainBlockShards`](/applications/api/toncenter/v3/blockchain-data/get-masterchain-block-shard-state-1) | 10 | 1000 | No |
| [`topAccountsByBalance`](/applications/api/toncenter/v3/stats/get-top-accounts-by-balance) | 10 | 1024 | No |
| [`transactionsByMessage`](/applications/api/toncenter/v3/blockchain-data/get-transactions-by-message) | 10 | 1000 | No |
| [`vesting`](/applications/api/toncenter/v3/vesting/get-vesting-contracts) | 10 | 1000 | No |
All other v3 endpoints return single objects or fixed results and do not support pagination.
## Parameters [#parameters]
These parameters are shared across all paginated endpoints.
| Parameter | Type | Description |
| --------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `limit` | integer | Maximum number of rows to return. Defaults vary by endpoint; see table above. |
| `offset` | integer | Number of rows to skip from the beginning of the result set. Default is `0`. |
| `sort` | string | Sort order: `desc` (default, newest first) or `asc` (oldest first). Available only on sortable endpoints. |
## Pagination example [#pagination-example]
This example uses the `transactions` endpoint, but the same `limit` and `offset` pattern applies to all paginated endpoints.
Send a request with `account` and `limit`. `offset` defaults to `0` for the first page.
```bash
curl "https://toncenter.com/api/v3/transactions?account=EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2&limit=3"
```
Response (abbreviated):
```json
{
"transactions": [
{
"account": "0:ED1691307050047117B998B561D8DE82D31FBF84910CED6EB5FC92E7485EF8A7",
"hash": "KkpVTX9RwiZcug8KQuOFUF8+eNoxuHVuIFpGQqufCWU=",
"lt": "67064337000004",
"now": 1771410670
},
{
"account": "0:ED1691307050047117B998B561D8DE82D31FBF84910CED6EB5FC92E7485EF8A7",
"hash": "b5fhFby+j8gg936W+XEsAEhboQW0zPcOHOHgyqXkTwI=",
"lt": "67011337000003",
"now": 1771286044
},
{
"account": "0:ED1691307050047117B998B561D8DE82D31FBF84910CED6EB5FC92E7485EF8A7",
"hash": "lT/wWTiJIdEF8A2Rox9CRdQRzlUgnIDGeUfEHQ8jGZQ=",
"lt": "66986300000006",
"now": 1771226782
}
],
"address_book": { ... }
}
```
Three transactions returned, sorted by logical time in descending order (newest first).
Set `offset=3` to skip the first 3 results and get the next batch.
```bash
curl "https://toncenter.com/api/v3/transactions?account=EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2&limit=3&offset=3"
```
Response (abbreviated):
```json
{
"transactions": [
{
"account": "0:ED1691307050047117B998B561D8DE82D31FBF84910CED6EB5FC92E7485EF8A7",
"hash": "07QaeBRRA62+RJPgetgSraYLH5i9G5QhC2dUvKAsAiI=",
"lt": "66927779000007",
"now": 1771088713
},
{
"account": "0:ED1691307050047117B998B561D8DE82D31FBF84910CED6EB5FC92E7485EF8A7",
"hash": "8d7sSor1NqbGNdX1JEGl1d4rX3lb7CeC3DZjhe7V7z4=",
"lt": "66927779000003",
"now": 1771088713
},
{
"account": "0:ED1691307050047117B998B561D8DE82D31FBF84910CED6EB5FC92E7485EF8A7",
"hash": "szM1I5/MU1uJGgeScS7uxNF6V/FsLkokCpul88ZEau8=",
"lt": "66926353000007",
"now": 1771085323
}
],
"address_book": { ... }
}
```
No overlap with the previous page. Offset pagination does not produce duplicates.
Continue incrementing `offset` by the `limit` value on each request (`offset=6`, `offset=9`, ...). When the response returns fewer transactions than the `limit`, all results have been retrieved.
```javascript
const address = "EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2";
async function main() {
let allTransactions = [];
let offset = 0;
const limit = 3;
let page = 0;
while (true) {
page++;
const params = new URLSearchParams({
account: address,
limit: String(limit),
offset: String(offset),
});
const res = await fetch(
`https://toncenter.com/api/v3/transactions?${params}`
);
const data = await res.json();
const transactions = data.transactions || [];
console.log(`\n--- Page ${page} (offset=${offset}) ---`);
for (const tx of transactions) {
console.log(` lt: ${tx.lt} hash: ${tx.hash}`);
}
allTransactions.push(...transactions);
if (transactions.length < limit) break;
offset += limit;
}
console.log(`\nTotal transactions: ${allTransactions.length}`);
}
main();
```
Output:
```bash
--- Page 1 (offset=0) ---
lt: 67064337000004 hash: KkpVTX9RwiZcug8KQuOFUF8+eNoxuHVuIFpGQqufCWU=
lt: 67011337000003 hash: b5fhFby+j8gg936W+XEsAEhboQW0zPcOHOHgyqXkTwI=
lt: 66986300000006 hash: lT/wWTiJIdEF8A2Rox9CRdQRzlUgnIDGeUfEHQ8jGZQ=
--- Page 2 (offset=3) ---
lt: 66927779000007 hash: 07QaeBRRA62+RJPgetgSraYLH5i9G5QhC2dUvKAsAiI=
lt: 66927779000003 hash: 8d7sSor1NqbGNdX1JEGl1d4rX3lb7CeC3DZjhe7V7z4=
lt: 66926353000007 hash: szM1I5/MU1uJGgeScS7uxNF6V/FsLkokCpul88ZEau8=
--- Page 3 (offset=6) ---
Total transactions: 6
```
## Sorting options [#sorting-options]
Sortable endpoints accept a `sort` parameter with two values:
* `desc` (default): newest results first, sorted by logical time (or UTC timestamp for `blocks`).
* `asc`: oldest results first.
```bash
curl "https://toncenter.com/api/v3/transactions?account=EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2&limit=3&sort=asc"
```
Response (abbreviated):
```json
{
"transactions": [
{
"hash": "3ziyP0yvGklMTNWWXDplmlBcPH0P7MJtusoVthNu8e0=",
"lt": "39547833000003",
"now": 1690204554
},
{
"hash": "lYXDtLL53JkKa35vP05gbwTyd6Lq4335TwlZeUebxZ8=",
"lt": "39547876000003",
"now": 1690204686
},
{
"hash": "DSz0P/wmE0EkdfaxFl2R36Eie+Lw4paLa1sAHHUliJA=",
"lt": "39548648000003",
"now": 1690207175
}
],
"address_book": { ... }
}
```
With `sort=asc`, the earliest transactions are returned first, starting from 2023-07 for this account.
The `jetton/wallets` endpoint sorts results by balance instead of logical time. When balances change between requests, using `limit` and `offset` can skip or repeat wallets because the sort order changes between pages.
# Use basic getter hooks (/applications/appkit/get-started/basic-getter-hooks)
Read the connected wallet's state from React using AppKit's getter hooks. They re-render when the underlying state changes and do not themselves start wallet actions — transactions and signatures use mutation hooks such as `useTransferTon`, `useSignText`, and `useSendTransaction`.
## Before you begin [#before-you-begin]
You need the React providers in place. See [Installation → Wrap the application](/applications/appkit/get-started/installation/react-app#wrap-the-application).
## Three return shapes [#three-return-shapes]
Getter hooks come in three return shapes. Which shape a hook uses depends on where the data lives.
**Tuple with setter** — for state AppKit stores reactively and that the app can change. The first element is the value (or `null` if not yet set), the second is the setter.
```tsx
const [wallet, setWalletId] = useSelectedWallet();
const [network, setDefaultNetwork] = useDefaultNetwork();
```
The hooks that return tuples: `useSelectedWallet`, `useDefaultNetwork`.
**Direct value** — for store-derived state that is read-only from React. Returns the value itself, no wrapper.
```tsx
const address = useAddress(); // string | undefined
const network = useNetwork(); // Network | undefined
const networks = useNetworks(); // Network[]
const connectors = useConnectors(); // Connector[]
const wallets = useConnectedWallets(); // WalletInterface[]
const connector = useConnectorById('tonconnect'); // Connector | undefined
const appKit = useAppKit(); // AppKit
```
These hooks use `useSyncExternalStore` under the hood and re-render when the underlying state changes.
**TanStack Query result** — for chain data fetched through an API client. Returns `{ data, isLoading, isError, error, refetch }` and accepts a `query` field for `refetchInterval`, `enabled`, `staleTime`, and the rest of the TanStack Query options.
```tsx
const { data: balance, isLoading } = useBalance();
const { data: jettons } = useJettons({ query: { refetchInterval: 20000 } });
```
The hooks that return query results: `useBalance`, `useJettons`, `useNfts`, `useTransactionStatus`, `useJettonInfo`, `useJettonBalanceByAddress`, `useJettonWalletAddress`, `useBlockNumber`, `useNft`, and the `*ByAddress` variants.
## Provider data is not chain finality [#provider-data-is-not-chain-finality]
A getter hook reflects a snapshot of provider data, not the chain itself. The user's wallet may report state that differs from what the configured `apiClient` returns — usually because the indexer is a few blocks behind the wallet, sometimes because the two read different networks. For live updates without manual refetch, mount the matching `useWatch*` hook (covered on [Stream live updates](/applications/appkit/get-started/streaming)).
## Tips [#tips]
Treat hook data as the latest read, not as a settlement check. Verify chain effects with `getTransactionStatus` or a backend before crediting value, and re-check after any reconnect.
## Code example [#code-example]
See a [working example](https://github.com/ton-connect/kit/tree/main/apps/appkit-minter) that uses `useBalance`, `useJettons`, and `useNfts` to render wallet state — [try it live](https://appkit-minter.vercel.app/).
## What to do next [#what-to-do-next]
* Move on to [Send transactions](/applications/appkit/get-started/sending-transactions) — at that point you'll have a working app.
* For a full walkthrough of reading TON, jetton, and NFT data, see [Read balances](/applications/appkit/howto/read-balances).
* Look up the full hook surface in the [`@ton/appkit-react` reference](/applications/appkit/reference/appkit-react).
# Add wallet connectors (/applications/appkit/get-started/connectors)
Wire up a connector so AppKit can talk to a wallet. A connector is the transport that carries requests to the wallet and responses back — it does not sign, and is not itself a wallet. Signing always happens inside the user's wallet application. AppKit cares about the connector's `id`, `type`, `metadata`, and the methods it exposes (`connectWallet`, `disconnectWallet`, `getConnectedWallets`, `destroy`). The protocol underneath is hidden.
## Before you begin [#before-you-begin]
Install AppKit first. See [Prepare your project](/applications/appkit/get-started/installation/installation).
## Create the AppKit instance [#create-the-appkit-instance]
The `AppKit` constructor takes a `connectors` array of connector factories such as `createTonConnectConnector`. A single `AppKit` instance can hold more than one connector, and the user picks at connect time. The example below registers a single TON Connect connector — enough to start wiring up the connect button.
```ts
// appkit.ts
import { AppKit, createTonConnectConnector } from '@ton/appkit';
export const appKit = new AppKit({
connectors: [
createTonConnectConnector({
tonConnectOptions: {
manifestUrl: 'https://example.com/tonconnect-manifest.json',
},
}),
],
});
```
## Render a connect button [#render-a-connect-button]
Drop `
{({ isLoading, onSubmit, disabled, text }) => (
{isLoading ? 'Sending…' : text}
)}
```
The component exposes `{ isLoading, onSubmit, disabled, text }` to the render-prop child.
## Pick the right call [#pick-the-right-call]
The three layers trade off control against work done for you. Components own the full lifecycle and ship a default render-prop UI hook, so you write the least code; mutation hooks give you the lifecycle without UI, so you build the button yourself; core actions give you neither — just a function that drives the wallet — and are the right pick from vanilla code or when you need to compose multiple transactions in one user action. Pick by how much of the lifecycle you want AppKit to own.
| Goal | Component | Hook | Core action |
| ----------------------------------- | ---------------------- | -------------------- | ----------------- |
| Send Toncoin | `
{({ isLoading, onSubmit, disabled, text }) => (
{isLoading ? 'Sending…' : text}
)}
;
```
## Tips [#tips]
Pick the widget level by control needs. Use a ready-made component for the smallest integration, render props for custom layout, and hooks or core actions when the flow needs more control than one widget can provide.
## Code example [#code-example]
See a [working example](https://github.com/ton-connect/kit/tree/main/apps/appkit-minter) that integrates `
If `networks` is omitted entirely, AppKit constructs a **mainnet-only** `ApiClientToncenter` with no API key. Fine for quick prototyping; expect rate limits on real workloads. Testnet apps must declare `networks` explicitly.
## Lifecycle [#lifecycle]
```text
new AppKit(config) → connect → connector:connected → wallets:updated → (auto-select) wallets:selection-changed
```
## Action shapes [#action-shapes]
AppKit exposes its capabilities as standalone functions instead of instance methods. Every action takes the `AppKit` instance as its first argument, which keeps the API easy to test and tree-shake.
```ts
import { getSelectedWallet, transferTon } from '@ton/appkit';
const wallet = getSelectedWallet(appKit);
if (wallet) {
await transferTon(appKit, { recipientAddress: 'EQ...', amount: '1.25' });
}
```
Actions use three patterns. **Queries** read state synchronously or with a one-shot async call (`getSelectedWallet`, `getBalance`). **Watchers** subscribe to changes and return an unsubscribe function (`watchSelectedWallet`, `watchBalance`). **Mutations** trigger side effects and return a promise (`connect`, `transferTon`, `sendTransaction`).
Read actions that target the selected wallet (`getBalance`, `getJettons`, `getNfts`, …) return **`null`** when no wallet is selected. Mutation and signing actions (`transferTon`, `sendTransaction`, `signText`, …) **throw** `Error('Wallet not connected')` in the same case. Check for a selected wallet — or be ready for the throw — before calling a mutation.
## React integration [#react-integration]
`@ton/appkit-react` provides hooks for the main AppKit actions and watchers. Mount `AppKitProvider` once at the root inside a TanStack `QueryClientProvider`, then call hooks anywhere below it. See [Installation → Wrap the application](/applications/appkit/get-started/installation/react-app#wrap-the-application) for the full mount.
Most async data hooks return TanStack Query results such as `{ data, isLoading, error, refetch }`, and mutation hooks return `{ mutate, mutateAsync, isPending, error }`. Watch hooks such as `useWatchBalance` return `void` and keep the related query cache fresh while mounted. Wallet state hooks read AppKit's local store directly: `useSelectedWallet()` returns `[wallet, setWalletId]`, while `useConnectedWallets()` and `useConnectors()` return arrays.
## Tips [#tips]
* Create one AppKit instance for one app runtime. Do not share an instance across windows or processes.
* Pass the instance to actions directly, or provide it to React with `AppKitProvider`. Do not call actions before the instance is constructed.
* Connector `id`s are singletons. Registering a second connector with the same `id` calls `destroy()` on the old one before installing the new.
* Swap and staking provider `providerId`s are singletons too, but only the registry entry is replaced — the previous provider is not torn down. Hold the reference if you need to dispose of it yourself.
* Do not call signing or transfer mutations without first checking that a wallet is selected.
## Related pages [#related-pages]
* [Connect to a wallet](/applications/appkit/howto/connect-to-a-wallet)
* [Providers](/applications/appkit/howto/providers)
* [Send Toncoin](/applications/appkit/howto/send-toncoin)
* [Sign data](/applications/appkit/howto/sign-data)
# Connect to a wallet (/applications/appkit/howto/connect-to-a-wallet)
Open a wallet session, restore it across reloads, and disconnect cleanly.
## How it works [#how-it-works]
A wallet is the signing application that owns the keys. A connector is the transport AppKit uses to open the wallet flow, restore sessions, list connected wallets, and route signing requests. A connector is not a wallet and does not sign — signing always happens inside the user's wallet application.
AppKit can track multiple connected wallets, but one wallet is selected for actions such as transfers and data signing. A selected wallet can change after disconnects, network changes, or session restore, so read it from AppKit state instead of storing it as long-lived application state. The same wallet on a different network has a different wallet id, and AppKit treats those as separate wallet objects.
## Before you begin [#before-you-begin]
You need an `AppKit` instance with at least one connector and the React providers mounted. See [Add wallet connectors](/applications/appkit/get-started/connectors) for the instance and [Installation → Wrap the application](/applications/appkit/get-started/installation/react-app#wrap-the-application) for the provider setup.
## Drop-in button [#drop-in-button]
` disconnect.mutate({ connectorId: wallet.connectorId })}>
Disconnect {wallet.getAddress()}
);
}
return connectors.map((connector) => (
connect.mutate({ connectorId: connector.id })}>
Connect {connector.metadata.name}
));
}
```
If the `connectorId` passed to `connect` is not registered, the action throws `Connector with id "" not found`. Confirm registration with `getConnectors` (or `useConnectors` in React) before calling `connect`.
## Read the connected wallet [#read-the-connected-wallet]
`useSelectedWallet` returns the wallet used by the next action. The wallet exposes `getAddress()` and `getNetwork()`.
```tsx
import { useSelectedWallet } from '@ton/appkit-react';
const [wallet] = useSelectedWallet();
const address = wallet?.getAddress();
const network = wallet?.getNetwork();
```
For just the address string, `useAddress` is the convenience hook:
```tsx
import { useAddress } from '@ton/appkit-react';
const address = useAddress(); // string | undefined
```
## Register a connector after construction [#register-a-connector-after-construction]
If connector configuration is not available at construction time, register it with `addConnector`. Use this for user-scoped manifest URLs, feature flags, or dynamic wallet sets. `addConnector` accepts a `Connector` instance or a factory and returns an unregister function.
```ts
import { addConnector, createTonConnectConnector } from '@ton/appkit';
import { appKit } from './appkit';
const unregister = addConnector(
appKit,
createTonConnectConnector({
tonConnectOptions: { manifestUrl: 'https://example.com/tonconnect-manifest.json' },
}),
);
// Later, to remove and destroy the connector:
unregister();
```
Connector ids are singletons. Registering a second connector with the same id calls `destroy()` on the previous one before installing the new.
## Connect from vanilla JS [#connect-from-vanilla-js]
```ts
import { connect, disconnect, getConnectors } from '@ton/appkit';
import { appKit } from './appkit';
const [connector] = getConnectors(appKit);
await connect(appKit, { connectorId: connector.id });
// Later:
await disconnect(appKit, { connectorId: connector.id });
```
`connector.connectWallet()` and `connector.disconnectWallet()` are the lower-level equivalents when direct connector access is preferred.
## Wallet and Connector interfaces [#wallet-and-connector-interfaces]
Every connected wallet exposes the same minimum surface: a reference to the connector that produced it, four identity readers, and two wallet-approved operations that are routed through the connector.
```ts
interface WalletInterface {
/** Connector that created this wallet */
readonly connectorId: string;
// Identity
getAddress(): UserFriendlyAddress;
getPublicKey(): Hex;
getNetwork(): Network;
getWalletId(): string;
// Actions requiring wallet signature
sendTransaction(request: TransactionRequest): Promise;
signData(payload: SignDataRequest): Promise;
}
```
Connectors implement a small interface that AppKit treats as opaque transport — the protocol underneath is hidden.
```ts
interface Connector {
readonly id: string;
readonly type: string;
readonly metadata: ConnectorMetadata;
destroy(): void;
connectWallet(network?: Network): Promise;
disconnectWallet(): Promise;
getConnectedWallets(): WalletInterface[];
}
```
The bundled `createTonConnectConnector` covers most apps. It wraps `@tonconnect/ui`, restores prior sessions when the connector is first read, and syncs TON Connect with AppKit's default network.
## Errors and recovery [#errors-and-recovery]
Wrap every action in try/catch and convert errors with `getErrorMessage` from `@ton/appkit`.
| Error | Recovery |
| ----------------- | -------------------------------------------------- |
| User rejected | Keep state unchanged and allow retry. |
| Missing connector | Check the AppKit configuration. |
| Expired session | Disconnect and request a new connection. |
| Wrong network | Prompt the user to switch network in their wallet. |
## Tips [#tips]
* Do not call mutations or signing actions while `getSelectedWallet` is `null` — the action will throw.
* Do not assume every connector supports every flow. Catch rejections from the wallet and surface a recovery option.
* Do not store `selectedWalletId` as long-lived application state. The selected wallet can change after disconnects, network changes, or session restores.
* In application code, use public actions or React hooks instead of calling connector methods directly, so AppKit's event flow stays consistent. Connector methods are still the public surface for custom connector implementations.
## Related pages [#related-pages]
* [AppKit](/applications/appkit/howto/appkit)
* [`@ton/appkit-react` reference](/applications/appkit/reference/appkit-react)
* [Use UI widgets](/applications/appkit/howto/use-ui-widgets)
# Gasless (/applications/appkit/howto/gasless)
Gasless in AppKit lets the selected wallet sign a transaction while a relayer broadcasts it and charges fees in an accepted jetton instead of TON.
## Relayer model [#relayer-model]
Gasless does not remove the wallet step. The selected wallet still reviews and signs the message set, and the relayer only takes over after the wallet signature exists.
The `GaslessManager` coordinates a gasless provider. The provider describes which gas jettons it accepts, how it estimates fees, and which message shapes it is willing to relay.
## Fee and signature flow [#fee-and-signature-flow]
The flow begins by reading relayer configuration, then estimating the fee for the chosen gas jetton. The estimate gives the app two things to present together: the fee charged by the relayer and the message set the wallet must sign.
After signing, the app sends the signed payload to the relayer. The relayer broadcasts the transaction on behalf of the wallet and charges its fee according to its own rules.
```ts
import { estimateGasless, getGaslessConfig, sendGaslessTransaction } from '@ton/appkit';
const config = await getGaslessConfig(appKit, { network });
const gasJetton = config.gasJettons[0];
const estimate = await estimateGasless(appKit, {
network,
gasJetton,
messages,
});
const response = await sendGaslessTransaction(appKit, {
estimate,
});
```
Show the chosen gas jetton and estimated fee before opening the wallet. The wallet signs the message set; the relayer handles broadcast after that signature exists.
## Failure boundaries [#failure-boundaries]
Gasless introduces a relayer failure class in addition to wallet and chain failures. The wallet can reject signing, the relayer can reject the signed request, and the chain can still reject or fail the broadcast transaction.
Those outcomes need different recovery paths. A relayer rejection may require a different gas jetton or payload, while a chain failure requires normal transaction-status handling.
## Tips [#tips]
* Show the fee in the chosen gas jetton before opening the wallet.
* Treat relayer rejection and chain rejection as different outcomes.
* Verify the final on-chain result after the relayer accepts the signed request.
## Related pages [#related-pages]
* [Providers](/applications/appkit/howto/providers)
* [Send Toncoin](/applications/appkit/howto/send-toncoin)
* [How to](/applications/appkit/howto/howto)
# How to (/applications/appkit/howto/howto)
How-to guides explain how AppKit features work, then show the code path for using them in an app.
Start with [Get started](/applications/appkit/get-started/get-started) for installation and the smallest setup. Use these guides when you need both the model behind a feature and the practical code that drives it.
## Core setup [#core-setup]
| Guide | What it covers |
| --------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [AppKit](/applications/appkit/howto/appkit) | Runtime state, configuration, lifecycle, and React provider setup. |
| [Connect to a wallet](/applications/appkit/howto/connect-to-a-wallet) | Wallet and connector model, connect UI, selected wallet, and errors. |
| [Providers](/applications/appkit/howto/providers) | API clients, streaming providers, swap providers, and staking setup. |
| [Networks](/applications/appkit/howto/networks) | Mainnet, testnet, default network, API clients, and mismatch checks. |
## Wallet data and assets [#wallet-data-and-assets]
| Guide | What it covers |
| --------------------------------------------------------- | -------------------------------------------------------------------- |
| [Read balances](/applications/appkit/howto/read-balances) | Toncoin and jetton reads for the selected wallet or any address. |
| [Send Toncoin](/applications/appkit/howto/send-toncoin) | Toncoin transfer flow, amount handling, and settlement checks. |
| [Send jettons](/applications/appkit/howto/send-jettons) | Jetton metadata, decimals, transfer requests, and settlement checks. |
| [NFTs](/applications/appkit/howto/nfts) | NFT reads, rendering, transfer requests, and ownership verification. |
| [Sign data](/applications/appkit/howto/sign-data) | Text, binary, and cell signatures with verifier-side checks. |
| [Streaming](/applications/appkit/howto/streaming) | Live balance, jetton, and transaction updates. |
## Product flows [#product-flows]
| Guide | What it covers |
| ----------------------------------------------------------- | ----------------------------------------------------------------- |
| [Swaps](/applications/appkit/howto/swaps) | Quote freshness, provider routing, build flow, and settlement. |
| [Staking](/applications/appkit/howto/staking) | Stake and unstake quotes, provider metadata, balances, and sends. |
| [Onramp](/applications/appkit/howto/onramp) | Fiat redirects, crypto deposits, provider status, and completion. |
| [Gasless](/applications/appkit/howto/gasless) | Jetton-paid fees, relayer estimates, wallet signing, and sends. |
| [Use UI widgets](/applications/appkit/howto/use-ui-widgets) | Default UI, render props, hooks, and vertical flow components. |
## Conventions [#conventions]
Every guide assumes an `AppKit` instance and the React provider are already mounted unless it is showing setup. Code samples use public package imports and keep product-state decisions separate from wallet approval.
# Networks (/applications/appkit/howto/networks)
A network in AppKit is the chain context AppKit uses to read data, submit requests, and compare wallet state against the app's expected chain.
## Configured networks [#configured-networks]
AppKit can be configured with more than one network at the same time. Each network is identified by a `Network` value with a `chainId`, and each configured chain has an API client behind it.
The API client is the app's source for chain reads: balances, transactions, block height, asset metadata, and request submission. AppKit includes Toncenter and TonAPI clients, and a pre-built client can be supplied when an app needs its own transport or authentication policy.
At least one network must be configured. If a flow tries to read from a chain that the AppKit instance does not know about, the app has no reliable source of truth for that chain.
## Default network [#default-network]
Some flows are explicitly scoped to a network. Others need a fallback when the caller does not pass one. The default network is that fallback.
Changing the default network changes the chain AppKit uses for reads and actions that do not specify a network. Connectors observe this change so wallet-facing flows can compare the selected wallet's network with the app's current expectation.
## Configure networks [#configure-networks]
Each network entry takes an `apiClient` — either the inline `{ url, key }` shape that targets TON Center, or a constructed `ApiClient` instance (such as `ApiClientTonApi`) for any other backend. The inline shape has preset URLs for mainnet and testnet, so `url` can be omitted for those.
### Configure multiple networks [#configure-multiple-networks]
Add more entries to `networks` to declare additional chains, including custom networks beyond mainnet and testnet. The example below configures mainnet and testnet through TON Center, plus a custom chain through a TonAPI client instance with its own endpoint URL.
```ts
const customNetwork = Network.custom('custom_chain_id');
const appKit = new AppKit({
networks: {
[Network.mainnet().chainId]: {
apiClient: {
key: 'your-mainnet-key',
},
},
[Network.testnet().chainId]: {
apiClient: {
url: 'https://testnet.toncenter.com',
key: 'your-testnet-key',
},
},
[customNetwork.chainId]: {
apiClient: new ApiClientTonApi({
network: customNetwork,
endpoint: 'https://your-custom-endpoint.example',
apiKey: 'your-custom-key',
}),
},
},
});
```
### Set and read the default network [#set-and-read-the-default-network]
Set the default network with `setDefaultNetwork`:
```ts
import { setDefaultNetwork } from '@ton/appkit';
setDefaultNetwork(appKit, { network: Network.testnet() });
```
Use `getDefaultNetwork` or the React `useDefaultNetwork` hook when UI needs to show the active chain. `useDefaultNetwork` returns a `[network, setNetwork]` tuple — the value is `Network | undefined`, and the setter updates the default network reactively.
```tsx
import { useDefaultNetwork } from '@ton/appkit-react';
const [network] = useDefaultNetwork();
return {network?.chainId} ;
```
## Network mismatch [#network-mismatch]
A network mismatch happens when the app expects one chain and the selected wallet or provider reports another. This is not a display issue — it changes where a transaction request would be signed and where a result would settle.
Block unsafe actions when the expected network and the reported network do not match. Surface the expected network and let the wallet or app flow resolve the mismatch before sending a transaction request.
## Tips [#tips]
* Develop on testnet first.
* Never derive product state from a network the AppKit instance is not configured to read.
* Block unsafe actions when the selected wallet network does not match the expected network.
## Related pages [#related-pages]
* [Providers](/applications/appkit/howto/providers)
* [Connect to a wallet](/applications/appkit/howto/connect-to-a-wallet)
* [How to](/applications/appkit/howto/howto)
# NFTs (/applications/appkit/howto/nfts)
Read, render, and transfer NFTs owned by the connected wallet.
**Verify NFT authenticity.** Scammers create fake NFTs that mimic popular collections. An NFT item contract can claim any collection address, so reading the `collection` field from the item alone is not sufficient. To verify that an NFT item genuinely belongs to a collection, query the collection contract with the item's index and check that the returned address matches the item's address. See [how to verify an NFT item](/blockchain-basics/standard/tokens/nft/verify) for the full procedure.
## How it works [#how-it-works]
NFTs are unique digital assets on TON, similar to ERC-721 tokens on Ethereum. Unlike jettons, which have a balance, a wallet either owns a specific NFT item or it does not. NFTs consist of a collection contract and individual NFT item contracts; each item carries an `ownerAddress` that reflects current ownership.
AppKit reads NFT ownership and metadata through the configured API client. NFT names, images, attributes, and collection fields are display data from contracts and indexers, so render them defensively.
Transfers are wallet-approved transaction requests. The wallet accepting the request starts the chain flow, while ownership verification confirms that the NFT moved.
## Before you begin [#before-you-begin]
A connected wallet and the React provider mounted. See [Connect to a wallet](/applications/appkit/howto/connect-to-a-wallet).
## Read NFTs [#read-nfts]
```tsx
import { useNfts } from '@ton/appkit-react';
export function MyNfts() {
const { data, isLoading, isError, refetch } = useNfts({
query: { refetchInterval: 10000 },
});
if (isError) return refetch()}>Retry ;
if (isLoading) return Loading… ;
const nfts = data?.nfts ?? [];
return {nfts.length} NFT(s)
;
}
```
For a different address, use `useNftsByAddress({ address })`.
## Render with `
{nfts.map((nft) => (
console.log(nft)} />
))}
);
```
## Transfer an NFT [#transfer-an-nft]
**Assets at risk.** Transferring an NFT is irreversible — once sent, only the new owner can transfer it back. Verify both the NFT address and the recipient address before initiating a transfer. A common failure mode is **stale ownership**: the NFT changes owners between the read and the transfer attempt. Reread `ownerAddress` before opening the wallet. If `isOnSale` is true, also check `realOwnerAddress`.
Before opening the wallet, make sure the sender's wallet has enough Toncoin to cover the [fees](/blockchain-basics/primitives/fees).
An NFT transfer carries the destination owner address, the NFT contract address, and an optional small Toncoin amount that is forwarded to the recipient message. For NFTs the recommended pattern is to build the request offline with `createTransferNftTransaction`, then hand it to ` console.log('done')}
onError={(e) => console.error(getErrorMessage(e))}
>
{({ isLoading, onSubmit, disabled, text }) => (
{isLoading ? 'Sending…' : text}
)}
);
}
```
The shorter route is the `useTransferNft` hook or the `transferNft` core action — both build the request internally and call the wallet directly.
```ts
import { transferNft } from '@ton/appkit';
await transferNft(appKit, {
nftAddress: 'EQ...',
recipientAddress: 'EQ...',
});
```
## Read a single NFT [#read-a-single-nft]
```ts
import { getNft } from '@ton/appkit';
const nft = await getNft(appKit, { address: 'EQ...' });
```
## Continuous ownership monitoring [#continuous-ownership-monitoring]
A discrete ownership check is fine for assembling an outgoing transfer, but UI state should not be derived from it — ownership can change between read and render. There is no `watchNfts` streaming action; to keep an NFT view in sync, mount a query hook with a refetch interval, or run a polling loop from vanilla code.
```tsx
import { useNfts } from '@ton/appkit-react';
const { data, isLoading, error, refetch } = useNfts({
limit: 100,
query: { refetchInterval: 10_000 },
});
```
From vanilla JS:
```ts
import { type AppKit, type NFT, getNfts } from '@ton/appkit';
/** Start polling. Returns a stop function. */
export function startNftOwnershipMonitoring(
appKit: AppKit,
onNftsUpdate: (nfts: NFT[]) => void,
intervalMs: number = 10_000,
): () => void {
let isRunning = true;
const poll = async () => {
while (isRunning) {
const result = await getNfts(appKit, { limit: 100 });
onNftsUpdate(result?.nfts ?? []);
await new Promise((resolve) => setTimeout(resolve, intervalMs));
}
};
poll();
return () => { isRunning = false; };
}
```
Pick an interval based on UX needs — shorter intervals provide fresher data but increase API usage. For large wallets, call `getNfts` with increasing `offset` to paginate.
## `NFT` type [#nft-type]
NFT-related queries produce objects that conform to the following interface:
```ts title="TypeScript"
/**
* Non-fungible token (NFT) on the TON blockchain.
*/
export interface NFT {
/** Contract address of the NFT item */
address: string;
/** Index of the item within its collection */
index?: string;
/** Display information about the NFT (name, description, images, etc.) */
info?: TokenInfo;
/** Custom attributes/traits of the NFT (e.g., rarity, properties) */
attributes?: NFTAttribute[];
/** Information about the collection this item belongs to */
collection?: NFTCollection;
/** Address of the auction contract, if the NFT is being auctioned */
auctionContractAddress?: string;
/** Hash of the NFT smart contract code */
codeHash?: string;
/** Hash of the NFT's on-chain data */
dataHash?: string;
/** Whether the NFT contract has been initialized */
isInited?: boolean;
/** Whether the NFT is soulbound (non-transferable) */
isSoulbound?: boolean;
/** Whether the NFT is currently listed for sale */
isOnSale?: boolean;
/** Current owner address of the NFT */
ownerAddress?: string;
/** Real owner address when NFT is on sale (sale contract becomes temporary owner) */
realOwnerAddress?: string;
/** Address of the sale contract, if the NFT is listed for sale */
saleContractAddress?: string;
/** Off-chain metadata of the NFT (key-value pairs) */
extra?: { [key: string]: unknown };
}
```
NFT display data (`info`, `attributes`, `extra`) is off-chain and untrusted. The contract address is the authoritative routing key. When `isOnSale` is `true`, `ownerAddress` points to the sale contract and `realOwnerAddress` points to the seller. Render the seller, but route on-chain interactions through `ownerAddress`.
## Confirm settlement [#confirm-settlement]
The wallet accepting the request does not prove the NFT moved. Track the transaction with [Streaming](/applications/appkit/howto/streaming) and verify ownership before crediting value.
## Common failures [#common-failures]
| Failure | Meaning |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| User rejected | The user closed or rejected the wallet request. |
| Stale ownership | The NFT changed owners between the read and the transfer. Reread `ownerAddress` before sending. |
| NFT on sale | `isOnSale === true` — the NFT is held by a sale contract. Cancel the listing or transfer through the sale contract flow. |
| Soulbound NFT | `isSoulbound === true` — the item cannot be transferred. |
| Invalid address | The recipient or NFT contract address is malformed or for the wrong network. |
## Tips [#tips]
* Verify the current `ownerAddress` before allowing a user-initiated transfer. NFTs can change owners between reads and transfers.
* Display **verified** fields first: contract address, owner address, real owner address, and collection address. Treat off-chain display data (`info`, `attributes`, `extra`) as **display data only**. Sanitize names and images, and never route on display metadata.
* Use `getTransactionStatus` to confirm settlement before updating NFT state in your app. The wallet response only proves the user signed.
* Refetch the NFT list after settlement so the owner fields are current.
* Do not concatenate NFT addresses for analytics keys. Use the contract address verbatim and `index` as a string when present.
## Code example [#code-example]
See a [working example](https://github.com/ton-connect/kit/tree/main/apps/appkit-minter) of an NFT list rendered with `useNfts` — [try it live](https://appkit-minter.vercel.app/).
## Related pages [#related-pages]
* [Use UI widgets](/applications/appkit/howto/use-ui-widgets)
* [AppKit reference](/applications/appkit/reference/reference)
* [Send Toncoin](/applications/appkit/howto/send-toncoin)
# Onramp (/applications/appkit/howto/onramp)
Onramp in AppKit covers external flows that bring value into a TON wallet through fiat payment providers or crypto bridge aggregators.
## Two external flows [#two-external-flows]
| Flow | What starts in AppKit | What finishes outside AppKit |
| ------------- | ----------------------------------------------------- | -------------------------------------------------------------------------- |
| Fiat onramp | A provider quote and hosted payment URL. | Fiat payment, KYC, provider settlement, and delivery to the TON address. |
| Crypto onramp | A bridge quote and source-chain deposit instructions. | Source-chain deposit, bridge processing, status updates, and TON delivery. |
Both flows use the same manager and provider idea as other AppKit integrations. The manager gives the app one surface to ask for quotes; the provider owns payment pages, bridge routes, fees, limits, and completion status.
## Fiat onramp [#fiat-onramp]
A fiat onramp sends the user to a hosted provider page. AppKit can collect quotes and produce the URL for Mercuryo, MoonPay, TON Pay, or another registered provider, but it does not process card payments or perform KYC.
The redirect is the beginning of an external process. The selected wallet address may be the destination, but wallet state alone is not the completion source for the provider flow.
```ts
import { buildOnrampUrl, getOnrampQuote } from '@ton/appkit';
const quote = await getOnrampQuote(appKit, {
fiatCurrency: 'USD',
cryptoCurrency: 'TON',
fiatAmount: '100',
destinationAddress: wallet.getAddress().toString(),
});
const url = await buildOnrampUrl(appKit, { quote });
window.location.assign(url);
```
## Crypto onramp [#crypto-onramp]
A crypto onramp starts with bridge intent: a source chain, a source asset, and a TON destination. AppKit asks the provider for a quote, creates a deposit, and exposes the chain-specific instructions needed to fund it.
Deposit addresses, memos, source-chain confirmations, bridge timing, and refunds are provider concerns. AppKit surfaces status so the app can track progress without pretending to move funds itself.
```ts
import { createCryptoOnrampDeposit, getCryptoOnrampQuote, getCryptoOnrampStatus } from '@ton/appkit';
const quote = await getCryptoOnrampQuote(appKit, {
fromChain: 'ethereum',
fromToken: 'USDT',
toToken: 'TON',
amount: '50',
destinationAddress: wallet.getAddress().toString(),
});
const deposit = await createCryptoOnrampDeposit(appKit, { quote });
const status = await getCryptoOnrampStatus(appKit, { depositId: deposit.id });
```
## Tips [#tips]
* Treat a hosted URL or deposit instruction as the start of a long-running provider process.
* Verify completion through provider status, not wallet state alone.
* Surface provider fees, limits, and timing as provider data rather than guaranteed outcomes.
## Related pages [#related-pages]
* [Providers](/applications/appkit/howto/providers)
* [Networks](/applications/appkit/howto/networks)
* [How to](/applications/appkit/howto/howto)
# Providers (/applications/appkit/howto/providers)
Providers connect AppKit to external data sources and DeFi services. AppKit uses four provider-related components: the **API client** that reads chain state, the **streaming provider** that delivers live updates, the **swap provider** that quotes and builds DEX transactions, and the **staking provider** that quotes and builds staking transactions. Each component is managed by the matching manager on the `AppKit` instance.
A provider is not a wallet and not a connector. The wallet still signs every transaction; the connector still owns the session. A provider is the source of *data* about the chain or about a DeFi protocol, and AppKit treats whatever it returns as external input — useful for showing prices, balances, and quotes, but never as proof of settlement.
| Type | Use | Manager |
| ------------------ | -------------------------------------------------------------------- | ------------------------- |
| API client | Reads blockchain data such as balances, jettons, and NFTs. | `AppKit.networkManager` |
| Streaming provider | Pushes live balance, transaction, and jetton updates over WebSocket. | `AppKit.streamingManager` |
| Swap provider | Returns swap quotes and builds swap transactions. | `AppKit.swapManager` |
| Staking provider | Returns staking quotes, balance, and builds stake transactions. | `AppKit.stakingManager` |
Only swap and staking providers are registered through `registerProvider`. Streaming providers are registered with `appKit.streamingManager.registerProvider(...)`, and API clients are configured per network through `networks[chainId].apiClient`.
## Swaps [#swaps]
A swap provider integrates a DEX or aggregator. It returns a **quote** for a route (input asset, output asset, amount, fees, and execution assumptions), then builds a `TransactionRequest` when the user accepts the quote. AppKit does not price markets itself; `SwapManager` coordinates the registered providers. Bundled options include Omniston and DeDust. See [Swaps](/applications/appkit/howto/swaps) for the full quote-then-build flow.
## Staking [#staking]
A staking provider quotes a stake or unstake intent for a specific pool or protocol, then builds the matching `TransactionRequest`.
Liquid-staking positions may appear in the wallet as derivative balances, such as tsTON. AppKit exposes pool metadata and APY as provider-supplied **display data**, not a guarantee of future yield or redemption timing.
Unstake mechanics — instant, delayed, or round-end — are provider-specific. The bundled staking provider is Tonstakers. See [Staking](/applications/appkit/howto/staking) for the full flow.
## How they are registered [#how-they-are-registered]
Provider setup uses three registration paths. **API clients** are bound to a network through the `networks` field of `AppKitConfig`. **Streaming providers** are also network-specific and are registered directly on `appKit.streamingManager`. **Swap** and **staking** providers are network-aware DeFi providers: pass them in `providers` at construction or register them later with `registerProvider`. Each DeFi provider declares its `type` so AppKit can route it to the correct manager.
Omniston requires its own SDK package — install it before registering the provider:
```bash
npm i @ston-fi/omniston-sdk
```
```ts
import { AppKit, Network, registerProvider } from '@ton/appkit';
import { OmnistonSwapProvider } from '@ton/appkit/swap/omniston';
import { createTonstakersProvider } from '@ton/appkit/staking/tonstakers';
const appKit = new AppKit({
networks: {
[Network.mainnet().chainId]: {
apiClient: { url: 'https://toncenter.com', key: 'your-mainnet-api-key' },
},
[Network.testnet().chainId]: {
apiClient: { url: 'https://testnet.toncenter.com', key: 'your-testnet-api-key' },
},
},
providers: [new OmnistonSwapProvider()],
});
registerProvider(appKit, createTonstakersProvider());
```
When a network entry does not provide a custom API client, AppKit creates a TonCenter client for that network. TonAPI and TonCenter streaming providers are available through WalletKit and can be registered on `appKit.streamingManager`. Omniston and DeDust are available as swap providers, and Tonstakers is available as a staking provider. Custom DeFi backends can use the same `registerProvider` path by implementing the swap or staking interface.
`registerProvider` returns `void`. To replace a provider, call `registerProvider` again with the same `providerId` — the registry entry is overwritten. If the previous provider owns resources you need to clean up, hold the reference and dispose of it yourself before re-registering.
## Two-step transactions [#two-step-transactions]
Swap and staking actions follow a quote-then-build pattern. `getSwapQuote` and `getStakingQuote` return provider offers, including fees, settlement amounts, and routing data. `buildSwapTransaction` and `buildStakeTransaction` turn an accepted quote into a `TransactionRequest`. Building the request does not broadcast it; the request still has to be submitted with `sendTransaction` and approved in the connected wallet.
```ts
import { AppKit, getSwapQuote, buildSwapTransaction, sendTransaction } from '@ton/appkit';
const quote = await getSwapQuote(appKit, {
amount: '1000000000',
from: { address: 'EQ-USDT-MASTER', decimals: 6 },
to: { address: 'ton', decimals: 9 },
network,
});
const request = await buildSwapTransaction(appKit, {
quote,
userAddress: wallet.getAddress().toString(),
});
await sendTransaction(appKit, request);
```
This separation matters because quotes can expire. The settlement amount shown when the quote is fetched is not guaranteed when the transaction lands on chain. Refetch the quote before building the transaction, and verify the on-chain result before updating product state.
## Custom providers [#custom-providers]
Apps that integrate their own DEX or staking backend implement the same provider interface as the bundled providers, then register the provider with `registerProvider`. Provider ids are singletons; registering another provider with the same `providerId` replaces the previous entry.
## Tips [#tips]
* Provider responses are external data. Validate critical outcomes, including settlement amounts, addresses, and signatures, before changing product state.
* Quotes can expire. Build the transaction soon after fetching the quote, or refetch before showing the user a final price.
* Do not assume a provider is registered. Call `getStakingProviders(appKit)` or `hasStreamingProvider(appKit, network)` and degrade gracefully when the list is empty or the provider is absent.
* Treat provider ids as singletons. Registering a second provider with the same id replaces the previous one.
## Related pages [#related-pages]
* [AppKit](/applications/appkit/howto/appkit)
* [Swaps](/applications/appkit/howto/swaps)
* [Staking](/applications/appkit/howto/staking)
* [Streaming](/applications/appkit/howto/streaming)
# Read balances (/applications/appkit/howto/read-balances)
Read Toncoin and jetton balances for the connected wallet or any address.
## How it works [#how-it-works]
Balance reads come from the configured API client for the active network. Selected-wallet hooks are convenient for wallet UI, while address-explicit hooks are better for receipts, profiles, admin views, and backend-confirmed destinations.
Live balance changes are streaming signals. They are useful for refreshing UI, but product decisions should still rely on a point-in-time read from the network the app is configured to trust.
## Before you begin [#before-you-begin]
A connected wallet (or a known address) and the React provider mounted. See [Connect to a wallet](/applications/appkit/howto/connect-to-a-wallet).
## Pick the right hook [#pick-the-right-hook]
| Goal | Hook |
| --------------------------------------- | --------------------- |
| Toncoin balance for the selected wallet | `useBalance` |
| Toncoin balance for an explicit address | `useBalanceByAddress` |
| Jetton balances for the selected wallet | `useJettons` |
| Jetton balances for an explicit address | `useJettonsByAddress` |
All four are query hooks. They return `{ data, isLoading, error, refetch }` and accept a `query` field to forward TanStack Query options such as `refetchInterval`.
## Read the connected wallet [#read-the-connected-wallet]
```tsx
import { useBalance, useJettons } from '@ton/appkit-react';
export function Balances() {
const ton = useBalance({ query: { refetchInterval: 20000 } });
const jettons = useJettons({ query: { refetchInterval: 20000 } });
if (ton.isLoading || jettons.isLoading) return Loading… ;
if (ton.isError) return Failed to load TON ;
return (
TON: {ton.data ?? '0'}
Jettons: {jettons.data?.jettons.length ?? 0}
);
}
```
`ton.data` is a string in TON units. Render it directly, or use `toNano` only when another API expects raw nanotons.
Jetton reads return formatted balances in the token's own units. Use the token metadata for symbols and decimals when rendering a list.
## Read by address [#read-by-address]
Use the `*ByAddress` hooks to read any address — useful for receipt screens or admin tooling.
```tsx
import { useBalanceByAddress, useJettonsByAddress } from '@ton/appkit-react';
export function ProfileBalances({ address }: { address: string }) {
const ton = useBalanceByAddress({ address });
const jettons = useJettonsByAddress({ address });
return TON: {ton.data ?? '0'}
;
}
```
## Render a jetton row [#render-a-jetton-row]
The SDK ships `getFormattedJettonInfo` to normalize jetton metadata for display.
```tsx
import { getFormattedJettonInfo } from '@ton/appkit';
const formatted = getFormattedJettonInfo(jetton);
// formatted: { name, symbol, decimals, balance, image, address }
```
## Read from vanilla JS [#read-from-vanilla-js]
```ts
import { getBalanceByAddress, getJettonsByAddress } from '@ton/appkit';
const ton = await getBalanceByAddress(appKit, { address: 'EQ...' });
const jettons = await getJettonsByAddress(appKit, { address: 'EQ...' });
```
## Live updates [#live-updates]
Mount `useWatchBalance()` and `useWatchJettons()` once high in the tree to keep the cache pushed live. See [Stream live updates](/applications/appkit/get-started/streaming).
## Code example [#code-example]
See a [working example](https://github.com/ton-connect/kit/tree/main/apps/appkit-minter) of TON and jetton balances rendered together with the same hooks documented above — [try it live](https://appkit-minter.vercel.app/).
## Related pages [#related-pages]
* [Streaming](/applications/appkit/howto/streaming)
* [AppKit reference](/applications/appkit/reference/reference)
* [Send Toncoin](/applications/appkit/howto/send-toncoin)
# Send jettons (/applications/appkit/howto/send-jettons)
Transfer a jetton (a TON fungible token) from the connected wallet to another address.
## How it works [#how-it-works]
Jettons are TON fungible tokens. Each holder has a jetton wallet contract derived from `(jettonMaster, ownerAddress)` — the owner is the user's TON wallet, and the jetton wallet is a separate contract owned by it. Transfer UI asks for the recipient's owner address, not their jetton wallet address. AppKit derives the sender's jetton wallet internally (that's the destination of the outer TON message), builds the inner jetton transfer payload that names the recipient's owner address, and wraps it in the outer message. The sender's jetton wallet then forwards the transfer to the recipient's jetton wallet on-chain. For example, USDT on TON is implemented as a jetton with the master address `EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs`.
Each jetton stores `name`, `symbol`, and `decimals` in its metadata. Amounts are decimal strings in the jetton's own units, so read the `decimals` field from chain metadata before building a transfer — different jettons can use different precision. USDT uses 6 decimals, so `'0.1'` represents 100,000 micro-USDT.
To deploy and mint a new jetton on the mainnet without writing code, use the dedicated official tool: [TON MINTER](https://minter.ton.org).
## Before you begin [#before-you-begin]
A connected wallet, the React provider mounted, and the jetton's master address. See [Connect to a wallet](/applications/appkit/howto/connect-to-a-wallet) and [Read balances](/applications/appkit/howto/read-balances) to discover what the wallet holds.
**Funds at risk.** Transferring without accounting for `decimals` can send drastically more or fewer tokens than intended. Verify the `decimals` value from chain metadata before calculating transfer amounts.
Before opening the wallet, make sure the sender's wallet has enough Toncoin to cover the [fees](/blockchain-basics/primitives/fees).
## Component (recommended) [#component-recommended]
` console.error(getErrorMessage(e))}
onSuccess={({ boc }) => console.log('sent', boc)}
>
{({ isLoading, onSubmit, disabled, text }) => (
{text}
)}
```
`amount` is a decimal string in jetton units (so `'1.0'` for one full token, regardless of `decimals`).
## Hook [#hook]
```tsx
import { useTransferJetton } from '@ton/appkit-react';
const transferJetton = useTransferJetton();
transferJetton.mutate({
recipientAddress: 'EQ...',
jettonAddress: 'EQ...',
amount: '1.0',
jettonDecimals: 6,
});
```
## Core action [#core-action]
```ts
import { transferJetton } from '@ton/appkit';
await transferJetton(appKit, {
recipientAddress: 'EQ...',
jettonAddress: 'EQ...',
amount: '1.0',
jettonDecimals: 6,
});
```
## Look up jetton metadata [#look-up-jetton-metadata]
When you need the symbol, decimals, or icon for a UI, call `getJettonInfo` and pass the result through `getFormattedJettonInfo`.
```ts
import { getJettonInfo, getFormattedJettonInfo } from '@ton/appkit';
const jetton = await getJettonInfo(appKit, { address: 'EQ...' });
const formatted = getFormattedJettonInfo(jetton);
// formatted: { name, symbol, decimals, balance, image, address }
```
## Parameters [#parameters]
| Field | Type | Required | Notes |
| ------------------ | -------- | -------- | --------------------------------------- |
| `recipientAddress` | `string` | Yes | TON address of the recipient. |
| `jettonAddress` | `string` | Yes | Address of the jetton master contract. |
| `amount` | `string` | Yes | Decimal jetton units, e.g. `'1.0'`. |
| `jettonDecimals` | `number` | Yes | Decimal precision of the jetton. |
| `comment` | `string` | No | Plain text memo on the jetton transfer. |
## Confirm settlement [#confirm-settlement]
Jetton transfers settle through the same trace API as Toncoin transfers, but typically produce multiple internal messages. Use `getTransactionStatus(appKit, { boc })` and inspect `onchainMessages`, `pendingMessages`, and `totalMessages` to track progress; treat only `status === 'completed'` as final.
Track the transaction with [Streaming](/applications/appkit/howto/streaming) and verify the recipient's jetton balance in your backend before delivering value.
If the recipient has never held this jetton, the transfer deploys the recipient's jetton wallet contract on first receive, which costs additional gas. The default outer-TON allowance on a built `transferJetton` request is designed to cover this case.
## Common failures [#common-failures]
| Failure | Meaning |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| User rejected | The user closed or rejected the wallet request. |
| Wrong decimals | The amount was scaled with the wrong `decimals` value. The transfer may move drastically more or fewer tokens than intended. |
| Insufficient balance | The wallet cannot cover the jetton amount or the outer TON fee allowance. |
| Invalid address | The recipient or jetton master address is malformed or for the wrong network. |
## Tips [#tips]
* Always pass the destination **owner address** as `recipientAddress`. AppKit derives the sender's jetton wallet contract and writes the destination owner address into the jetton transfer payload.
* Read decimals from chain metadata (`getJettonInfo`) before building a transfer. Different jettons can use different precision.
* Treat the `boc` from `sendTransaction` as "user signed". Verify settlement with `getTransactionStatus` before crediting an order.
* Refetch the user's jetton list and balances after settlement.
* Do not display jetton metadata without sanitizing — names and images are user-supplied.
## Code example [#code-example]
See a [working example](https://github.com/ton-connect/kit/tree/main/apps/appkit-minter) of jetton transfers built with these mutations — [try it live](https://appkit-minter.vercel.app/).
## Related pages [#related-pages]
* [Read balances](/applications/appkit/howto/read-balances)
* [Send Toncoin](/applications/appkit/howto/send-toncoin)
* [Use UI widgets](/applications/appkit/howto/use-ui-widgets)
# Send Toncoin (/applications/appkit/howto/send-toncoin)
Transfer Toncoin from the connected wallet. Pick the call style that fits your UI.
## How it works [#how-it-works]
Toncoin is the native asset on TON. AppKit keeps Toncoin amounts as decimal strings in human-readable TON units and converts them when it builds the wallet request. Precision is 9 digits — `'0.1'` is 100,000,000 nanoToncoin; the smallest representable amount is `'0.000000001'` (1 nanoToncoin).
The flow has three steps: AppKit assembles the request, the wallet signs and broadcasts, and the chain settles. A wallet response means the selected wallet accepted and submitted the request — it does not prove that the transaction settled on chain, so product state should wait for status tracking or a backend verification read.
## Before you begin [#before-you-begin]
A connected wallet and the React provider mounted. See [Connect to a wallet](/applications/appkit/howto/connect-to-a-wallet). Use testnet during development.
## Component (recommended) [#component-recommended]
`(null);
return (
setError(getErrorMessage(e))}
onSuccess={({ boc }) => console.log('sent', boc)}
>
{({ isLoading, onSubmit, disabled, text }) => (
{isLoading ? 'Sending…' : text}
)}
);
}
```
`amount` is a decimal string in TON. The component accepts an optional `comment` for a memo on chain.
## Hook [#hook]
`useTransferTon` is the mutation hook behind the component.
```tsx
import { useTransferTon } from '@ton/appkit-react';
const transferTon = useTransferTon();
transferTon.mutate({
recipientAddress: 'EQ...',
amount: '0.05',
comment: 'Test payment',
});
```
Read `transferTon.isPending`, `transferTon.error`, and use `mutation.onSuccess` / `mutation.onError` if you initialize the hook with options.
## Core action [#core-action]
```ts
import { transferTon } from '@ton/appkit';
import { appKit } from './appkit';
await transferTon(appKit, {
recipientAddress: 'EQ...',
amount: '0.05',
comment: 'Test payment',
});
```
## Parameters [#parameters]
| Field | Type | Required | Notes |
| ------------------ | -------- | -------- | --------------------------------------------------- |
| `recipientAddress` | `string` | Yes | TON address. |
| `amount` | `string` | Yes | Decimal TON, e.g. `'0.05'`. |
| `comment` | `string` | No | Plain text memo. Mutually exclusive with `payload`. |
| `payload` | `string` | No | Base64 cell. Overrides `comment` when set. |
| `stateInit` | `string` | No | Base64 cell, used to deploy. |
## Confirm settlement [#confirm-settlement]
TON achieves transaction [finality](https://docs.ton.org/payments/overview#transaction-finality) after a single masterchain block confirmation, with new blocks produced roughly every 400 ms. Once a transaction appears in a masterchain block, it becomes irreversible.
`sendTransaction` returning a `boc` means **the user signed**. Settlement is a separate state — verify with `getTransactionStatus(appKit, { boc })`, which returns `'unknown' | 'pending' | 'completed' | 'failed'` along with `totalMessages`, `pendingMessages`, and `onchainMessages` for trace progress. Treat only `status === 'completed'` as final.
Applications should not block the UI while waiting for confirmation. Show a "signed / confirming" state, let [Streaming](/applications/appkit/howto/streaming) push live updates, and act on `completed` when it arrives. For finding a transaction by external message hash and applying normalization, see the [message lookup guide](/ecosystem/ton-connect/message-lookup).
## Common failures [#common-failures]
| Failure | Meaning |
| -------------------- | ------------------------------------------------------------ |
| User rejected | The user closed or rejected the wallet request. |
| Insufficient balance | The wallet cannot pay amount and fees. |
| Expired request | The transaction deadline passed before approval. |
| Invalid address | The recipient address is malformed or for the wrong network. |
## Tips [#tips]
* Validate the recipient address, amount, and expected network before calling any mutation. Do not rely on the wallet as the final input validator.
* Treat `sendTransaction` returning a `boc` as "user signed", not "settled". Wait for `getTransactionStatus` to return `completed` before delivering value.
* Do not block UI while waiting for settlement. Show a "signed / confirming" state, let `watchBalance` / `watchTransactions` update the view, and act on `completed` when it arrives.
* Refetch wallet balances and cached lists after settlement. Use trace status, not the immediate wallet response, as the trigger for product state changes.
* Do not derive product success from the wallet response shape. Verify on the chain.
* Keep amounts as strings or bigints until you display them. Floating-point math loses precision at TON's nine decimal places.
## Code example [#code-example]
See a [working example](https://github.com/ton-connect/kit/tree/main/apps/appkit-minter) of TON transfers built with these mutations — [try it live](https://appkit-minter.vercel.app/).
## Related pages [#related-pages]
* [Send jettons](/applications/appkit/howto/send-jettons)
* [NFTs](/applications/appkit/howto/nfts)
* [Use UI widgets](/applications/appkit/howto/use-ui-widgets)
# Sign data (/applications/appkit/howto/sign-data)
Ask the wallet to sign a payload. AppKit supports plain text, raw binary, and TON cells.
## How it works [#how-it-works]
Signed data attests to application data without sending a transaction. It fits user-facing acknowledgments, off-chain receipts, and signatures that a backend or TON smart contract verifies later.
The wallet returns an Ed25519 signature, signing address, wallet timestamp, observed dApp domain, and the original payload. The verifier owns freshness, domain, nonce, and signer checks. For wallet-ownership sign-in, use `ton_proof` during connection instead.
## Before you begin [#before-you-begin]
You need a connected wallet and the React provider mounted. See [Connect to a wallet](/applications/appkit/howto/connect-to-a-wallet).
## Pick the right call [#pick-the-right-call]
| Payload type | Hook | Core action |
| --------------- | --------------- | ------------ |
| Plain text | `useSignText` | `signText` |
| Binary (base64) | `useSignBinary` | `signBinary` |
| TON cell (BoC) | `useSignCell` | `signCell` |
All three hooks are mutation hooks. They return `{ mutate, mutateAsync, isPending, error, data }`.
## Sign text [#sign-text]
```tsx
import { useSignText } from '@ton/appkit-react';
const { mutate: signText, data } = useSignText();
signText({
text: 'Message to sign',
});
// data: { signature, address, timestamp, domain, payload }
```
## Sign binary [#sign-binary]
```tsx
import { useSignBinary } from '@ton/appkit-react';
const { mutate: signBinary, data } = useSignBinary();
signBinary({
bytes: 'base64-encoded-payload',
});
// data: { signature, address, timestamp, domain, payload }
```
## Sign a cell [#sign-a-cell]
For application protocols that exchange typed payloads, send a TON cell.
```tsx
import { useSignCell } from '@ton/appkit-react';
import { beginCell } from '@ton/core';
const { mutate: signCell, data } = useSignCell();
const cell = beginCell().storeUint(42, 32).storeStringTail('hello').endCell();
signCell({
cell: cell.toBoc().toString('base64'),
schema: 'message#_ value:uint32 text:Text = Message;',
});
// data: { signature, address, timestamp, domain, payload }
```
## Verify the signature [#verify-the-signature]
The wallet returns a signature response that includes `signature`, `address`, `timestamp`, `domain`, and the original `payload`. Verify the response server side against the payload and the wallet's public key before trusting it. Treat the client-side response as a hint, not proof.
## Related pages [#related-pages]
* [AppKit reference](/applications/appkit/reference/reference)
* [Connect to a wallet](/applications/appkit/howto/connect-to-a-wallet)
# Staking (/applications/appkit/howto/staking)
Quote a stake or unstake, build the transaction, and send it through the connected wallet.
## How it works [#how-it-works]
The `StakingManager` routes each quote and build call to a single registered staking provider — by default the first one you registered, or the one you pass as `providerId`. `setDefaultProvider` on the manager overrides the default; an unknown `providerId` throws. A quote describes the intent (`direction: 'stake' | 'unstake'`, `amount`, optional `unstakeMode`), and `useBuildStakeTransaction` turns an accepted quote into a `TransactionRequest`.
The protocol shape — derivative jetton, unstake modes, settlement timing, pool model — is provider-specific. Tonstakers, the bundled provider, issues `tsTON` and supports `INSTANT`, `WHEN_AVAILABLE`, and `ROUND_END` unstake modes. Read the user's staked-token balance with `useStakedBalance`, or query the jetton balance directly. `apy` and `instantUnstakeAvailable` from `useStakingProviderInfo` are provider-supplied display data, not guarantees of future yield or withdrawal timing.
## Before you begin [#before-you-begin]
You need a connected wallet and a staking provider registered on the AppKit instance. Tonstakers ships bundled — see [Providers → How they are registered](/applications/appkit/howto/providers#how-they-are-registered).
## Hooks [#hooks]
| Hook | Purpose |
| -------------------------- | ------------------------------------------------------ |
| `useStakingProviders` | List registered staking provider IDs. |
| `useStakingProviderInfo` | Read APY and instant-unstake liquidity for a provider. |
| `useStakedBalance` | Read the user's staked-token balance (e.g. `tsTON`). |
| `useStakingQuote` | Quote a stake or unstake intent. |
| `useBuildStakeTransaction` | Build a `TransactionRequest` from a quote. |
The first three are query hooks (`{ data, isLoading, isError, refetch }`); the last two are mutation/query pair used together. The built `TransactionRequest` is handed to `… ;
if (isError) return — ;
return (
Staked: {data?.stakedBalance ?? '0'} tsTON
Instant unstake liquidity:{' '}
{data?.instantUnstakeAvailable ?? '0'} TON
);
}
```
## Quote a stake or unstake [#quote-a-stake-or-unstake]
`useStakingQuote` takes the intent and returns settlement amounts. For an unstake, pass `unstakeMode` (`UnstakeMode.INSTANT`, `UnstakeMode.WHEN_AVAILABLE`, or `UnstakeMode.ROUND_END`) when the provider supports more than one.
```tsx
import { UnstakeMode, useNetwork, useStakingQuote } from '@ton/appkit-react';
export function StakePreview({ amount }: { amount: string }) {
const network = useNetwork();
const { data: quote, isLoading, isError } = useStakingQuote({
amount,
direction: 'stake',
network,
});
if (isLoading) return Fetching quote… ;
if (isError || !quote) return Staking unavailable ;
const rate = Number(quote.amountOut) / Number(quote.amountIn);
return (
Stake {quote.amountIn} TON → receive {quote.amountOut} tsTON
Rate: 1 TON ≈ {rate.toFixed(4)} tsTON
);
}
```
For an unstake, swap `direction` and add `unstakeMode`:
```tsx
const { data: quote } = useStakingQuote({
amount,
direction: 'unstake',
unstakeMode: UnstakeMode.INSTANT,
network,
});
```
## Build and send the transaction [#build-and-send-the-transaction]
`useBuildStakeTransaction` is the mutation that turns an accepted quote into a `TransactionRequest`. Hand it to ` console.log('sent', boc)}
/>
);
}
```
## After the send [#after-the-send]
After the send completes, pass the response to `getTransactionStatus` to confirm settlement, then refetch `useStakedBalance` to see the new staked-token balance. The response carries either a `boc` or a `normalizedHash`; pass whichever is set.
## Tips [#tips]
* The user's stake is a derivative jetton (e.g. `tsTON`), not an opaque AppKit object. Refresh with `useStakedBalance` (or a jetton balance read) after sends.
* APY and instant-unstake liquidity from `useStakingProviderInfo` are provider-supplied display data, not guarantees of future yield or withdrawal timing.
* Unstake mechanics (instant, delayed, round-end) are provider-specific. Pass `unstakeMode` on the quote when the provider supports more than one.
## Related pages [#related-pages]
* [Providers](/applications/appkit/howto/providers#staking)
* [Read balances](/applications/appkit/howto/read-balances)
* [How to](/applications/appkit/howto/howto)
# Streaming (/applications/appkit/howto/streaming)
Streaming in AppKit is a per-network subscription layer that turns provider events into live balance, jetton, and transaction updates for the app.
## Live provider signals [#live-provider-signals]
Streaming complements point-in-time API reads. Instead of asking an API client for the latest state after every interaction, the app subscribes to changes for an address on a specific network.
The `StreamingManager` coordinates providers by `chainId`. A streaming provider implements one transport for one network, such as a Toncenter or TonAPI websocket stream. Registering another provider for the same network replaces the previous stream for that chain. Provider registration is covered on [Providers → How they are registered](/applications/appkit/howto/providers#how-they-are-registered).
## Subscription lifetime [#subscription-lifetime]
A subscription belongs to the consumer that created it. Balance, jetton, transaction, and combined watches all return an unsubscribe function, and that function is the app's handle for stopping updates when a component unmounts or a flow ends.
When the underlying transport drops and reconnects, the SDK does not replay events from the gap. Updates resume from the provider's current view of the chain, so any intermediate transitions on a watched address are lost.
## Before you begin [#before-you-begin]
You need a connected wallet (for the default-address `useWatch*` hooks) and a streaming provider registered on the AppKit instance. See [Providers → How they are registered](/applications/appkit/howto/providers#how-they-are-registered).
## Watch from React [#watch-from-react]
Mount watch hooks near the part of the tree that needs live data. The hook keeps related query caches fresh while it is mounted; passing `onChange` adds a side-effect callback on top of the cache refresh. Every React watch hook accepts an optional `{ onChange?, network? }`, and the `*ByAddress` variants additionally accept an `address`.
Mount as many watchers as you need. The SDK deduplicates subscribers by network, address, and type, so multiple hook instances watching the same data share one underlying socket subscription. There is no benefit to lifting watchers into a single root component just to share them — pull them into the component that actually needs the live value.
### Watch a balance [#watch-a-balance]
`useWatchBalance` refreshes the cache that `useBalance` reads. `useBalance` is a TanStack Query result (`{ data, isLoading, isError, refetch, ... }`); `data` is the formatted TON balance as a string when present.
```tsx
import { useBalance, useWatchBalance } from '@ton/appkit-react';
export function LiveBalance() {
useWatchBalance();
const balance = useBalance();
return {balance.data ?? '0'} TON ;
}
```
### Watch transactions [#watch-transactions]
`useWatchTransactions` reacts to transaction lifecycle changes. The update payload exposes `traceHash` and `status` (`'pending' | 'confirmed' | 'finalized' | 'invalidated'`). Plug in your own notification or state-update logic; the SDK does not pick a UI primitive for you.
```tsx
import { useWatchTransactions } from '@ton/appkit-react';
export function FinalizedLog() {
useWatchTransactions({
onChange: (update) => {
if (update.status === 'finalized' && update.traceHash) {
console.log('finalized', update.traceHash);
}
},
});
return null;
}
```
### Watch by address [#watch-by-address]
For receipt screens, admin tooling, or order-tracking widgets, subscribe to an address that may not be the connected wallet. The `*ByAddress` hooks take an `address` and keep the matching `useBalanceByAddress` / cache fresh while also delivering each update to `onChange`.
```tsx
import {
useBalanceByAddress,
useWatchBalanceByAddress,
useWatchTransactionsByAddress,
} from '@ton/appkit-react';
export function OrderTracker({ orderAddress }: { orderAddress: string }) {
useWatchBalanceByAddress({
address: orderAddress,
onChange: (update) => {
if (update.status === 'finalized') {
console.log('order balance', update.balance);
}
},
});
const balance = useBalanceByAddress({ address: orderAddress });
useWatchTransactionsByAddress({
address: orderAddress,
onChange: (update) => {
if (update.status === 'finalized') {
console.log('finalized txs', update.transactions.length);
}
},
});
return {balance.data ?? '0'} TON ;
}
```
### Watch jettons [#watch-jettons]
`useWatchJettons` pushes jetton balance changes for the connected wallet. Each update covers one jetton (`masterAddress`, `walletAddress`, `ownerAddress`, `rawBalance`) and may include `decimals` and a formatted `balance` when the jetton's decimals are known.
```tsx
import { useWatchJettons } from '@ton/appkit-react';
export function PortfolioWatcher() {
useWatchJettons({
onChange: (update) => {
if (update.status === 'finalized' && update.balance !== undefined) {
console.log(update.masterAddress, update.balance);
}
},
});
return null;
}
```
## From vanilla code [#from-vanilla-code]
A non-React consumer keeps the unsubscribe function returned by each `watch*` action and calls it when the screen or process no longer needs updates.
```ts
import { watchBalance } from '@ton/appkit';
const unsubscribe = watchBalance(appKit, {
onChange: (update) => {
console.log(update.address, update.balance);
},
});
unsubscribe();
```
The same shape applies to `watchBalanceByAddress`, `watchJettons`, `watchJettonsByAddress`, `watchTransactions`, and `watchTransactionsByAddress`. Each takes `{ network?, onChange }` (and `address` on the `*ByAddress` variants) and returns an unsubscribe function.
## Connection state [#connection-state]
Connection state describes transport health, not chain finality. A websocket can disconnect and reconnect while the underlying account state continues to change.
After reconnect, updates may resume from the provider's current view of the chain. A flow that needs certainty should refresh from the configured API client before it changes product state.
`appKit.streamingManager.onConnectionChange(network, callback)` registers a listener for the WebSocket connection state of one network. The callback receives `connected: boolean`; the method returns an unsubscribe function. Pair it with `useNetwork` so the listener follows the currently selected network.
```tsx
import { useEffect, useState } from 'react';
import { useAppKit, useNetwork } from '@ton/appkit-react';
export function StreamingHealth() {
const appKit = useAppKit();
const network = useNetwork();
const [connected, setConnected] = useState(true);
useEffect(() => {
if (!network) return;
return appKit.streamingManager.onConnectionChange(network, setConnected);
}, [appKit, network]);
return {connected ? 'live' : 'reconnecting'} ;
}
```
## Tips [#tips]
* Store every unsubscribe function and call it when the consumer goes away.
* Call `hasStreamingProvider` before subscribing on a network that may not have a provider registered, and degrade gracefully when it returns `false`.
* Treat streaming updates as best-effort UI refresh signals. Reconcile with a point-in-time read before changing product state that depends on correctness.
* `update.status` carries one of `'pending' | 'confirmed' | 'finalized' | 'invalidated'` on every streaming payload. Only `'finalized'` is irreversible; treat the others as intermediate.
## Related pages [#related-pages]
* [Providers → How they are registered](/applications/appkit/howto/providers#how-they-are-registered)
* [Networks](/applications/appkit/howto/networks)
* [Read balances](/applications/appkit/howto/read-balances)
# Swaps (/applications/appkit/howto/swaps)
Quote a swap, build the transaction, and send it through the connected wallet.
## How it works [#how-it-works]
The `SwapManager` routes each quote and build call to a single registered swap provider — by default the first one you registered, or the one you pass as `providerId`. `setDefaultProvider` on the manager overrides the default; an unknown `providerId` throws. A quote is the chosen provider's current offer for a route — input asset, output asset, amount, fees, and execution assumptions — and `useBuildSwapTransaction` turns an accepted quote into a `TransactionRequest`. AppKit does not price markets itself; the provider does.
The quote is provider-supplied data and can expire. Refresh it close to the moment the user confirms, and treat the displayed `toAmount` as an estimate, not a guarantee. The wallet still owns approval, signing, and rejection on the final send.
## Before you begin [#before-you-begin]
You need a connected wallet and at least one swap provider registered on the AppKit instance. Omniston and DeDust ship bundled — see [Providers → How they are registered](/applications/appkit/howto/providers#how-they-are-registered).
## Hooks [#hooks]
| Hook | Purpose |
| ------------------------- | ------------------------------------------ |
| `useSwapQuote` | Fetch a swap quote. |
| `useBuildSwapTransaction` | Build a `TransactionRequest` from a quote. |
`useSwapQuote` is a query hook (`{ data, isLoading, isError, refetch }`); `useBuildSwapTransaction` is a mutation hook (`{ mutate, mutateAsync, isPending, error }`). Pass the built `TransactionRequest` to `Fetching quote… ;
if (isError || !quote) return Swap unavailable ;
return (
{quote.fromAmount} {USDT.symbol} → {quote.toAmount} {TON.symbol}
);
}
```
## Build and send the transaction [#build-and-send-the-transaction]
`useBuildSwapTransaction` is the mutation that turns an accepted quote into a `TransactionRequest`. Wrap it in a `request` callback and hand it to ` console.log('sent', boc)}
/>
);
}
```
## After the send [#after-the-send]
After the send completes, pass the response to `getTransactionStatus` to confirm settlement before updating balances, orders, or inventory. The response carries either a `boc` or a `normalizedHash`; pass whichever is set.
## Tips [#tips]
* Refresh a quote before building if the user paused on the confirmation screen — the route can move while the modal is open.
* Provider responses are external data; treat `toAmount` as an estimate, not a guarantee.
* `minReceived` is the slippage-protected lower bound on the output after `slippageBps` is applied. Compare against your product floor before letting the user sign.
* Slippage protection is provider-specific. `slippageBps` caps price drift; pass provider-specific fields through `providerOptions` when a provider needs more.
## Related pages [#related-pages]
* [Providers](/applications/appkit/howto/providers#swaps)
* [Send Toncoin](/applications/appkit/howto/send-toncoin)
* [How to](/applications/appkit/howto/howto)
# Use UI widgets (/applications/appkit/howto/use-ui-widgets)
`@ton/appkit-react` exports ready-to-use components for the most common AppKit flows. Drop them into your tree and connect callbacks. The default styles ship in `@ton/appkit-react/styles.css`.
## How it works [#how-it-works]
Widgets are React vertical flows over the same AppKit instance, selected wallet, network, and providers used by hooks and core actions. They are not a separate design system.
Use the default UI when the built-in flow fits. Use render props when the widget should keep AppKit state and behavior but the app owns layout. Use hooks directly when the product flow no longer matches one component.
## Before you begin [#before-you-begin]
You need the React providers mounted and the styles imported once at the entry file. See [Installation → Wrap the application](/applications/appkit/get-started/installation/react-app#wrap-the-application).
```tsx
import '@ton/appkit-react/styles.css';
```
## Component catalog [#component-catalog]
| Component | What it does |
| ------------------------- | --------------------------------------------------------------------------- |
| `
## Send a jetton [#send-a-jetton]
`
## Send a prepared transaction [#send-a-prepared-transaction]
` console.log('sent', boc)}
/>;
```
Pass a `children` render-prop with `{ isLoading, onSubmit, disabled, text }` instead of (or alongside) `text` if you want full control over the button markup.
## Render an NFT [#render-an-nft]
```tsx
import { NftItem, useNfts } from '@ton/appkit-react';
const { data } = useNfts();
const nfts = data?.nfts ?? [];
{nfts.map((nft) => (
/* open detail */ undefined}
/>
))}
;
```
## Swap widget [#swap-widget]
`UserFriendlyAddress \| AddressNetwork UseBalanceReturnType \Loading...
;
}
if (error) {
return Error: {error.message}
;
}
return Balance: {balance}
;
```
#### useBalanceByAddress [#usebalancebyaddress]
React hook reading the Toncoin balance of an arbitrary address through TanStack Query — useful for addresses that aren't tied to the selected wallet (use [`useBalance`](#usebalance) for the selected wallet).
| Parameter | Type | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseBalanceByAddressParameters`](#usebalancebyaddressparameters) | Target address, optional network override, and TanStack Query overrides. |
| `parameters.address` | UserFriendlyAddress \| AddressNetwork UseBalanceByAddressReturnType \Loading...
;
}
if (error) {
return Error: {error.message}
;
}
return Balance: {balance}
;
```
#### useWatchBalance [#usewatchbalance]
Subscribe to Toncoin balance updates for the currently selected wallet. Updates flow into the TanStack Query cache so [`useBalance`](#usebalance) picks up the new data automatically (use [`useWatchBalanceByAddress`](#usewatchbalancebyaddress) for a fixed address). Requires a streaming provider registered for the network — the hook exits silently with a console warning when none is configured.
| Parameter | Type | Description |
| --------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseWatchBalanceParameters`](#usewatchbalanceparameters) | Update callback and optional network override. |
| `parameters.onChange` | (update: BalanceUpdate ) => void | Callback fired on every balance update from the streaming provider. |
| `parameters.network` | Network Current balance: {balance}
;
```
#### useWatchBalanceByAddress [#usewatchbalancebyaddress]
Subscribe to Toncoin balance updates for an arbitrary address — updates flow into the TanStack Query cache so [`useBalanceByAddress`](#usebalancebyaddress) picks up the new data automatically. Requires a streaming provider registered for the network — the hook exits silently with a console warning when none is configured.
| Parameter | Type | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters`\* | [`UseWatchBalanceByAddressParameters`](#usewatchbalancebyaddressparameters) | Address, update callback and optional network override. |
| `parameters.address` | UserFriendlyAddress \| AddressNetwork (update: BalanceUpdate ) => void | Callback fired on every balance update from the streaming provider. |
Returns: `void`.
**Example**
```tsx
const address = 'UQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJKZ';
const network = Network.mainnet();
const { data: balance } = useBalanceByAddress({ address, network });
useWatchBalanceByAddress({ address, network });
return Current balance: {balance}
;
```
### Connectors [#connectors]
#### useConnectorById [#useconnectorbyid]
Look up a connector by its id and stay subscribed to its registration lifecycle — updates when a connector with that id is registered (via AppKit's constructor or [`addConnector`](/applications/appkit/reference/appkit#addconnector)) or unregistered. Returns the matching [`Connector`](/applications/appkit/reference/appkit#connector), or `undefined` when none with that id is currently registered. Use [`useConnectedWallets`](#useconnectedwallets) if you want to react to wallet connect/disconnect events instead.
| Parameter | Type | Description |
| --------- | -------- | ------------------------------- |
| `id`\* | `string` | ID of the connector to look up. |
Returns: Connector | undefinedUseConnectorsReturnType UseCreateCryptoOnrampDepositReturnType \CryptoOnrampContextType UseCryptoOnrampProviderReturnType UseCryptoOnrampProvidersReturnType UseCryptoOnrampQuoteReturnType \UseCryptoOnrampStatusReturnType \UserFriendlyAddress UserFriendlyAddress Network UseJettonBalanceByAddressReturnType \Loading...
;
}
if (error) {
return Error: {error.message}
;
}
return Jetton Balance: {balance}
;
```
#### useJettonInfo [#usejettoninfo]
React hook reading jetton-master metadata (name, symbol, decimals, image, description) through TanStack Query.
| Parameter | Type | Description |
| -------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseJettonInfoParameters`](#usejettoninfoparameters) | Jetton master address, optional network override and TanStack Query overrides. |
| `parameters.address` | UserFriendlyAddress Network UseJettonInfoReturnType \Loading...
;
}
if (error) {
return Error: {error.message}
;
}
return (
Jetton Info
Name: {info?.name}
Symbol: {info?.symbol}
Decimals: {info?.decimals}
);
```
#### useJettonWalletAddress [#usejettonwalletaddress]
React hook deriving the owner's jetton-wallet address — the per-owner contract that actually holds the jetton balance for a given master — through TanStack Query.
| Parameter | Type | Description |
| -------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseJettonWalletAddressParameters`](#usejettonwalletaddressparameters) | Jetton master, owner address, optional network override and TanStack Query overrides. |
| `parameters.jettonAddress` | UserFriendlyAddress UserFriendlyAddress Network ` — TanStack Query result for the jetton-wallet address read.
**Example**
```tsx
const {
data: walletAddress,
isLoading,
error,
} = useJettonWalletAddress({
ownerAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
jettonAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiXme1Xc56Iwobkzgnjj',
});
if (isLoading) {
return Loading...
;
}
if (error) {
return Error: {error.message}
;
}
return Jetton Wallet Address: {walletAddress}
;
```
#### useJettons [#usejettons]
React hook listing jettons held by the currently selected wallet through TanStack Query — auto-resolves the wallet address (use [`useJettonsByAddress`](#usejettonsbyaddress) for an arbitrary address).
| Parameter | Type | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseJettonsParameters`](#usejettonsparameters) | TanStack Query overrides (`select`, `enabled`, `staleTime`, …), pagination and an optional network override. |
| `parameters.address` | UserFriendlyAddress \| AddressNetwork UseJettonsReturnType \Loading...
;
}
if (error) {
return Error: {error.message}
;
}
return (
Jettons
{jettons?.jettons.map((jetton) => (
{jetton.info.name}: {jetton.balance}
))}
);
```
#### useJettonsByAddress [#usejettonsbyaddress]
React hook listing jettons held by an arbitrary address through TanStack Query — useful for wallets that aren't selected in AppKit (use [`useJettons`](#usejettons) for the selected wallet).
| Parameter | Type | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseJettonsByAddressParameters`](#usejettonsbyaddressparameters) | Owner address, optional network override, pagination and TanStack Query overrides. |
| `parameters.address` | UserFriendlyAddress \| AddressNetwork UseJettonsByAddressReturnType \Loading...
;
}
if (error) {
return Error: {error.message}
;
}
return (
Jettons
{jettons?.jettons.map((jetton) => (
{jetton.info.name}: {jetton.balance}
))}
);
```
#### useTransferJetton [#usetransferjetton]
Transfer a jetton from the selected wallet in one step — derives the owner's jetton-wallet from the master address, builds the transfer message, signs it through the wallet and broadcasts it. Call `mutate` with the `jettonAddress` (master), the `recipientAddress`, an `amount` (in jetton units as a human-readable decimal — converted into raw smallest units using `jettonDecimals`), the `jettonDecimals` itself and an optional `comment`. On success, `data` carries the BoC and normalized hash of the broadcast transaction. Throws `Error('Wallet not connected')` if no wallet is currently selected — TanStack Query surfaces it via the mutation's `error`.
| Parameter | Type | Description |
| --------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseTransferJettonParameters`](#usetransferjettonparameters) | TanStack Query mutation overrides. |
| `parameters.mutation` | [`MutationOptionsOverride`](/applications/appkit/reference/appkit#mutationoptionsoverride) | TanStack Query mutation options forwarded to `useMutation` (`onSuccess`, `onError`, `onMutate`, `retry`, …). `mutationFn`, `mutationKey` and `throwOnError` are managed by the wrapper. |
Returns: UseTransferJettonReturnType \
{isPending ? 'Transferring...' : 'Transfer Jetton'}
{error &&
Error: {error.message}
}
);
```
#### useWatchJettons [#usewatchjettons]
Subscribe to jetton-balance updates for the currently selected wallet. Updates flow into the TanStack Query cache so [`useJettons`](#usejettons) picks up the new data automatically (use [`useWatchJettonsByAddress`](#usewatchjettonsbyaddress) for a fixed address). Requires a streaming provider registered for the network — the hook exits silently with a console warning when none is configured.
| Parameter | Type | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| `parameters` | [`UseWatchJettonsParameters`](#usewatchjettonsparameters) | Update callback and optional network override. |
| `parameters.onChange` | (update: JettonUpdate ) => void | Callback fired on every jetton-balance update from the streaming provider. |
| `parameters.network` | Network
Your Jettons:
{jettons?.jettons.map((j) => (
{j.info.name}: {j.balance}
))}
);
```
#### useWatchJettonsByAddress [#usewatchjettonsbyaddress]
Subscribe to jetton-balance updates for an arbitrary owner address. Updates flow into the TanStack Query cache so [`useJettonsByAddress`](#usejettonsbyaddress) and [`useJettonBalanceByAddress`](#usejettonbalancebyaddress) pick up the new data automatically. Requires a streaming provider registered for the network — the hook exits silently with a console warning when none is configured.
| Parameter | Type | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters`\* | [`UseWatchJettonsByAddressParameters`](#usewatchjettonsbyaddressparameters) | Owner address, update callback and optional network override. |
| `parameters.address` | UserFriendlyAddress \| Address(update: JettonUpdate ) => void | Callback fired on every jetton-balance update from the streaming provider. |
| `parameters.network` | Network
Jettons for {address}:
{jettons?.jettons.map((j) => (
{j.info.name}: {j.balance}
))}
);
```
### NFTs [#nfts]
#### useNft [#usenft]
React hook reading metadata and ownership for a single NFT through TanStack Query, keyed by its contract address. `data` is `null` when the indexer has no record.
| Parameter | Type | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `parameters` | [`UseNftParameters`](#usenftparameters) | NFT address, optional network override, and TanStack Query overrides. |
| `parameters.address` | UserFriendlyAddress \| AddressNetwork UseNftReturnType \Loading...
;
}
if (error) {
return Error: {error.message}
;
}
return (
NFT Details
Name: {nft?.info?.name}
Collection: {nft?.collection?.name}
Owner: {nft?.ownerAddress}
);
```
#### useNfts [#usenfts]
React hook that reads NFTs held by the currently selected wallet through TanStack Query — auto-resolves the wallet address (use [`useNftsByAddress`](#usenftsbyaddress) for an arbitrary address).
| Parameter | Type | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseNFTsParameters`](#usenftsparameters) | Optional pagination, network override, and TanStack Query overrides. |
| `parameters.address` | UserFriendlyAddress \| AddressNetwork UseNFTsReturnType \Loading...
;
}
if (error) {
return Error: {error.message}
;
}
return (
My NFTs
{nfts?.nfts.map((nft) => (
{nft.info?.name} ({nft.collection?.name})
))}
);
```
#### useNftsByAddress [#usenftsbyaddress]
React hook that reads NFTs held by an arbitrary address through TanStack Query — useful for wallets that aren't selected in AppKit (use [`useNfts`](#usenfts) for the selected wallet).
| Parameter | Type | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseNFTsByAddressParameters`](#usenftsbyaddressparameters) | Owner address, optional pagination and network override, plus TanStack Query overrides. |
| `parameters.address` | UserFriendlyAddress \| AddressNetwork UseNFTsByAddressReturnType \Loading...
;
}
if (error) {
return Error: {error.message}
;
}
return (
NFTs
{nfts?.nfts.map((nft) => (
{nft.info?.name} ({nft.collection?.name})
))}
);
```
#### useTransferNft [#usetransfernft]
Transfer an NFT from the selected wallet in one step — builds the ownership-transfer message and broadcasts it. Call `mutate` with an `nftAddress`, the `recipientAddress`, an optional `amount` (the TON attached for gas — defaults to AppKit's NFT gas-fee constant when omitted) and an optional `comment`. On success, `data` carries the BoC and normalized hash of the broadcast transaction. Throws `Error('Wallet not connected')` if no wallet is currently selected — TanStack Query surfaces it via the mutation's `error`.
| Parameter | Type | Description |
| --------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseTransferNftParameters`](#usetransfernftparameters) | TanStack Query mutation overrides. |
| `parameters.mutation` | [`MutationOptionsOverride`](/applications/appkit/reference/appkit#mutationoptionsoverride) | TanStack Query mutation options forwarded to `useMutation` (`onSuccess`, `onError`, `onMutate`, `retry`, …). `mutationFn`, `mutationKey` and `throwOnError` are managed by the wrapper. |
Returns: UseTransferNftReturnType \
{isPending ? 'Transferring...' : 'Transfer NFT'}
{error &&
Error: {error.message}
}
);
```
### Networks [#networks]
#### useBlockNumber [#useblocknumber]
React hook reading the latest masterchain seqno through TanStack Query — useful for freshness checks and pagination cursors.
| Parameter | Type | Description |
| -------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseBlockNumberParameters`](#useblocknumberparameters) | TanStack Query overrides and optional network. |
| `parameters.network` | Network UseBlockNumberReturnType \UseDefaultNetworkReturnType UseNetworkReturnType UseNetworksReturnType AppKit >]` — Tuple `[theme, setTheme]` for reading and switching the active theme.
#### useI18n [#usei18n]
Read the i18n context published by [`I18nProvider`](#i18nprovider) (or the wrapping [`AppKitProvider`](#appkitprovider)). Returns the active locale, translation function and helpers to switch locales or merge dictionaries. Throws when rendered outside the provider tree.
Returns: I18nContextType UseSignBinaryReturnType \UseSignCellReturnType \UseSignTextReturnType \UseBuildStakeTransactionReturnType \UserFriendlyAddress Network UseStakedBalanceReturnType \StakingContextType UseStakingProviderReturnType Network UseStakingProviderInfoReturnType \Network StakingProviderMetadata | undefinedUseStakingProvidersReturnType StakingQuoteDirection UserFriendlyAddress Network UnstakeModes UseStakingQuoteReturnType \UseBuildSwapTransactionReturnType \SwapContextType UseSwapProviderReturnType UseSwapProvidersReturnType SwapToken SwapToken Network UseSwapQuoteReturnType \UseSendTransactionReturnType \UseTransactionStatusReturnType \UseTransferTonReturnType \(update: TransactionsUpdate ) => void | Callback fired on every transactions update from the streaming provider. |
Returns: `void`.
**Example**
```tsx
const [lastUpdate, setLastUpdate] = useState(null);
useWatchTransactions({
onChange: (update) => {
setLastUpdate(update);
},
});
return (
{lastUpdate ? (
Last update for: {lastUpdate.address}
) : (
'Waiting for transactions...'
)}
UserFriendlyAddress \| Address(update: TransactionsUpdate ) => void | Callback fired on every transactions update from the streaming provider. |
| `parameters.network` | Network (null);
useWatchTransactionsByAddress({
address,
onChange: (update) => {
setLastUpdate(update);
},
});
return (
{lastUpdate ? (
New transactions for: {lastUpdate.address}
) : (
'Waiting for transactions...'
)}
UseAddressReturnType " not found')` when no connector with that id is registered — TanStack Query surfaces it via the mutation's `error`.
| Parameter | Type | Description |
| --------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseConnectParameters`](#useconnectparameters) | TanStack Query mutation overrides. |
| `parameters.mutation` | [`MutationOptionsOverride`](/applications/appkit/reference/appkit#mutationoptionsoverride) | TanStack Query mutation options forwarded to `useMutation` (`onSuccess`, `onError`, `onMutate`, `retry`, …). `mutationFn`, `mutationKey` and `throwOnError` are managed by the wrapper. |
Returns: UseConnectReturnType \UseConnectedWalletsReturnType " not found')` when no connector with that id is registered — TanStack Query surfaces it via the mutation's `error`.
| Parameter | Type | Description |
| --------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseDisconnectParameters`](#usedisconnectparameters) | TanStack Query mutation overrides. |
| `parameters.mutation` | [`MutationOptionsOverride`](/applications/appkit/reference/appkit#mutationoptionsoverride) | TanStack Query mutation options forwarded to `useMutation` (`onSuccess`, `onError`, `onMutate`, `retry`, …). `mutationFn`, `mutationKey` and `throwOnError` are managed by the wrapper. |
Returns: UseDisconnectReturnType \UseSelectedWalletReturnType (response: SendTransactionReturnType ) => void | Called once the transaction is broadcast. Receives the wallet's [`SendTransactionReturnType`](/applications/appkit/reference/appkit#sendtransactionreturntype) (BoC + normalized hash). |
**Example**
```tsx
return (
console.log('Transaction sent:', result)}
onError={(error) => console.error('Transaction failed:', error)}
/>
);
```
#### SendTonButton [#sendtonbutton]
Pre-wired button that builds a TON transfer with [`createTransferTonTransaction`](/applications/appkit/reference/appkit#createtransfertontransaction) and dispatches it through the standard `Send` flow on click — disabled until both `recipientAddress` and `amount` are set.
| Prop | Type | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recipientAddress`\* | `string` | Recipient address. |
| `amount`\* | `string` | Amount in TON as a human-readable decimal string (e.g., `"1.5"`). Converted to nano-TON internally. |
| `comment` | `string` | Optional human-readable comment attached to the transfer. |
| `text` | `ReactNode` | Override the button label. Defaults to "Send". |
| `size` | `ButtonSize` | Size class applied to the button. Pass `'unset'` to skip the size class entirely (no padding, no typography) — useful with `variant="unstyled"`. |
| `borderRadius` | `ButtonBorderRadius` | Border radius token. Defaults to a size-dependent value (`s` → `2xl`, `m` → `l`, `l` → `xl`). |
| `variant` | `ButtonVariant` | Visual variant. Use `'unstyled'` to opt out of all built-in styling — the consumer is fully responsible for visuals via `className`. The Button still provides ref forwarding, `disabled`/`loading` plumbing, and `icon`/`children` rendering. |
| `loading` | `boolean` | When true, renders a spinner instead of `icon`/`children` and disables the button. |
| `fullWidth` | `boolean` | When true, the button stretches to fill its container width. |
| `icon` | `ReactNode` | Optional leading icon rendered before `children` when not loading. |
| `children` | `(props: SendRenderProps) => ReactNode` | Custom render function — replaces the default button with the caller's UI. Receives the current send state and click handler via [`SendRenderProps`](#sendrenderprops). |
| `onError` | `(error: Error) => void` | Called when the wallet rejects the request or the send fails. Receives the raised `Error`. |
| `onSuccess` | (response: SendTransactionReturnType ) => void | Called once the transaction is broadcast. Receives the wallet's [`SendTransactionReturnType`](/applications/appkit/reference/appkit#sendtransactionreturntype) (BoC + normalized hash). |
**Example**
```tsx
return (
console.log('Transaction sent:', result)}
onError={(error) => console.error('Transaction failed:', error)}
/>
);
```
### Crypto Onramp [#crypto-onramp-1]
#### CryptoOnrampWidget [#cryptoonrampwidget]
Drop-in widget for buying TON-side tokens with a crypto payment from another chain — wraps [`CryptoOnrampWidgetProvider`](#cryptoonrampwidgetprovider) (which drives token/method selection, quote fetching, deposit creation and status polling) around [`CryptoOnrampWidgetUI`](#cryptoonrampwidgetui). Pass a `children` render function to swap in a fully custom UI while keeping the same provider state.
| Prop | Type | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children` | (props: CryptoOnrampWidgetRenderProps ) => ReactNode | Custom render function. When provided, replaces the default [`CryptoOnrampWidgetUI`](#cryptoonrampwidgetui) and is called with the full [`CryptoOnrampWidgetRenderProps`](#cryptoonrampwidgetrenderprops) (context state, actions and forwarded `` props), so callers can build a fully custom UI on top of the same provider. |
| `tokens` |
CryptoOnrampToken \[] | Target tokens (what the user buys on TON). Defaults to a built-in list. |
| `tokenSections` |
CryptoOnrampTokenSectionConfig \[] | Optional section configs grouping `tokens` in the picker. |
| `paymentMethods` |
CryptoPaymentMethod \[] | Source crypto payment methods (what the user pays with on another chain). Defaults to a built-in list. |
| `methodSections` |
PaymentMethodSectionConfig \[] | Optional section configs grouping `paymentMethods` in the picker. |
| `chains` |
Record\ChainInfo> | Custom CAIP-2 → chain display info overrides. Merged on top of the built-in defaults, so consumers only need to provide what they want to override or add — for example, a single entry keyed by `'eip155:42161'` with a `name` of `'Arbitrum'` and a `logo` URL. |
| `defaultTokenId` | `string` | ID of the target token pre-selected on mount. |
| `defaultMethodId` | `string` | ID of the source payment method pre-selected on mount. |
**Example**
```tsx
// Uses built-in defaults for tokens, payment methods and chain display info.
// Make sure a crypto-onramp provider (Layerswap / swaps.xyz) is registered on AppKit.
return
;
```
#### CryptoOnrampWidgetProvider [#cryptoonrampwidgetprovider]
Context provider that powers the crypto-to-TON onramp widget — wires together token/method selection state, quote fetching ([`useCryptoOnrampQuote`](#usecryptoonrampquote)), deposit creation ([`useCreateCryptoOnrampDeposit`](#usecreatecryptoonrampdeposit)), deposit status polling ([`useCryptoOnrampStatus`](#usecryptoonrampstatus)), the target-token balance and validation. Consumers read the state via [`useCryptoOnrampContext`](#usecryptoonrampcontext).
| Prop | Type | Description |
| ----------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tokens` |
CryptoOnrampToken \[] | Target tokens (what the user buys on TON). Defaults to a built-in list. |
| `tokenSections` |
CryptoOnrampTokenSectionConfig \[] | Optional section configs grouping `tokens` in the picker. |
| `paymentMethods` |
CryptoPaymentMethod \[] | Source crypto payment methods (what the user pays with on another chain). Defaults to a built-in list. |
| `methodSections` |
PaymentMethodSectionConfig \[] | Optional section configs grouping `paymentMethods` in the picker. |
| `chains` |
Record\ChainInfo> | Custom CAIP-2 → chain display info overrides. Merged on top of the built-in defaults, so consumers only need to provide what they want to override or add — for example, a single entry keyed by `'eip155:42161'` with a `name` of `'Arbitrum'` and a `logo` URL. |
| `defaultTokenId` | `string` | ID of the target token pre-selected on mount. |
| `defaultMethodId` | `string` | ID of the source payment method pre-selected on mount. |
#### CryptoOnrampWidgetUI [#cryptoonrampwidgetui]
Presentational UI for the crypto-to-TON onramp widget — renders the from/to selectors, amount input with presets, continue button, info block (you-get / balance / provider) and the token-pick / method-pick / refund-address / deposit modals. All state and actions come from props ([`CryptoOnrampWidgetRenderProps`](#cryptoonrampwidgetrenderprops)). Typically rendered inside [`CryptoOnrampWidgetProvider`](#cryptoonrampwidgetprovider) via [`CryptoOnrampWidget`](#cryptoonrampwidget).
| Prop | Type | Description |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `tokens`\* |
CryptoOnrampToken \[] | Full list of target tokens the user can buy. |
| `tokenSections` |
CryptoOnrampTokenSectionConfig \[] | Optional section configs grouping `tokens` in the picker. |
| `selectedToken`\* |
CryptoOnrampToken \| null | Currently selected target token to buy. `null` until tokens load. |
| `setSelectedToken`\* |
(token: CryptoOnrampToken ) => void | Updates `selectedToken`. |
| `paymentMethods`\* |
CryptoPaymentMethod \[] | Available source crypto payment methods. |
| `methodSections` |
PaymentMethodSectionConfig \[] | Optional section configs grouping `paymentMethods` in the picker. |
| `selectedMethod`\* |
CryptoPaymentMethod | Currently selected source payment method. |
| `setSelectedMethod`\* |
(method: CryptoPaymentMethod ) => void | Updates `selectedMethod`. |
| `chains`\* |
Record\ChainInfo> | CAIP-2 → chain display info map (built-in defaults merged with consumer overrides). |
| `amount`\* | `string` | Current amount input value as a decimal string. |
| `setAmount`\* | `(value: string) => void` | Updates `amount`. |
| `amountInputMode`\* |
CryptoAmountInputMode | Which side `amount` is denominated in — see [`CryptoAmountInputMode`](#cryptoamountinputmode). |
| `setAmountInputMode`\* |
(mode: CryptoAmountInputMode ) => void | Updates `amountInputMode`. |
| `convertedAmount`\* | `string` | Other side of `amount` after applying the current quote's rate. |
| `presetAmounts`\* |
OnrampAmountPreset \[] | Quick-pick amount buttons rendered in the widget. |
| `quote`\* |
CryptoOnrampQuote \| null | Current quote, or `null` if not yet fetched / invalidated. |
| `isLoadingQuote`\* | `boolean` | Whether a quote is in flight (includes the input-debounce window). |
| `quoteError`\* | `string \| null` | Quote-side validation/fetch error as an i18n key, or `null`. |
| `quoteProviderName`\* | `string \| null` | Display name of the provider behind the current quote, when available. |
| `deposit`\* |
CryptoOnrampDeposit \| null | Current deposit returned by the provider once `createDeposit` succeeded. |
| `isCreatingDeposit`\* | `boolean` | Whether `createDeposit` is in flight. |
| `depositError`\* | `string \| null` | Deposit-side error as an i18n key, or `null`. |
| `depositAmount`\* | `string` | Formatted deposit amount the user must send on the source chain. |
| `createDeposit`\* | `() => void` | Triggers deposit creation from the current quote. |
| `depositStatus`\* |
CryptoOnrampStatus \| null | Latest deposit status polled via [`useCryptoOnrampStatus`](#usecryptoonrampstatus), or `null`. |
| `isRefundAddressRequired`\* | `boolean` | Whether the current quote provider requires a refund address before deposit. |
| `isReversedAmountSupported`\* | `boolean` | Whether the current quote provider supports reversed (target-amount) input. |
| `refundAddress`\* | `string` | Refund address the user typed, if `isRefundAddressRequired`. |
| `setRefundAddress`\* | `(address: string) => void` | Updates `refundAddress`. |
| `targetBalance`\* | `string` | Connected wallet's balance of the selected target token (formatted, token units). |
| `isLoadingTargetBalance`\* | `boolean` | Whether the target token balance is being fetched. |
| `isWalletConnected`\* | `boolean` | Whether a TON wallet is currently connected. |
| `canContinue`\* | `boolean` | Whether the user can proceed — valid amount, quote available, and wallet connected. |
| `onReset`\* | `() => void` | Invalidates the active quote and clears the deposit, returning the widget to its initial state. |
### NFTs [#nfts-1]
#### NftItem [#nftitem]
Card-style button rendering an NFT's image, name and collection name with an "On Sale" badge when applicable — falls back to a placeholder icon when the image is missing or fails to load.
| Prop | Type | Description |
| ------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `nft`\* |
NFT | NFT to render — name, collection name, image and on-sale state are derived via `getFormattedNftInfo`. |
**Example**
```tsx
return
console.log('NFT clicked')} />;
```
### Providers [#providers]
#### AppKitProvider [#appkitprovider]
Top-level React provider that wires AppKit, the TonConnect bridge and i18n into the component tree — wrap your app once near the root so descendant hooks ([`useAppKit`](#useappkit), [`useBalance`](#usebalance), …) and components can resolve their context.
| Prop | Type | Description |
| ---------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| `appKit`\* | AppKit
My App
{/* Your App Content */}
);
```
#### I18nProvider [#i18nprovider]
React provider that mounts the i18n context for [`useI18n`](#usei18n) and child components — already wrapped by [`AppKitProvider`](#appkitprovider), so apps usually only render it directly when they need to override the locale or dictionaries.
| Prop | Type | Description |
| ---------- | ---------------------- | -------------------------------------------------------------------------------------------- |
| `locale` | `string` | Initial locale code. Defaults to the i18n library's default when omitted. |
| `lngDicts` | `Record` | Translation dictionaries keyed by locale. Loaded into the underlying i18n instance on mount. |
**Example**
```tsx
// Override the locale. Pass `lngDicts` with your own translations when you need them.
return (
My App
);
```
### Shared [#shared]
#### AmountPresets [#amountpresets]
Horizontal row of preset amount buttons — typically used next to an amount input to offer quick fills.
| Prop | Type | Description |
| ------------------ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `presets`\* | AmountPreset \[]` wrapper — receives all native button props. |
| `CurrencyItem.Logo` | Token logo cell rendered as a 40px [`Logo`](#logo). |
| `CurrencyItem.Info` | Vertical block holding the [`CurrencyItem.Header`](#currencyitem) and [`CurrencyItem.Ticker`](#currencyitem). |
| `CurrencyItem.VerifiedBadge` | Verified checkmark badge — rendered next to the name when `isVerified` is set. |
| `CurrencyItem.Header` | Top line of `Info` (name + verified badge). |
| `CurrencyItem.Name` | Primary text line — defaults to the token name, falling back to the ticker when no name is provided. |
| `CurrencyItem.Ticker` | Secondary text line — renders the ticker, and when both ticker and name are present appends `• ` followed by the name. |
| `CurrencyItem.RightSide` | Right-aligned column for balance values. |
| `CurrencyItem.MainBalance` | Primary balance number (top of `RightSide`). |
| `CurrencyItem.UnderBalance` | Secondary balance value (e.g., fiat) shown under `MainBalance`. |
**Example**
```tsx
// Top-level props give you the default layout in one line.
return (
console.log('Picked USDT')}
/>
);
```
#### CurrencySelect [#currencyselect]
Compound currency-select primitives — compose [`CurrencySelect.Modal`](#currencyselect) with a [`CurrencySelect.Search`](#currencyselect) and [`CurrencySelect.ListContainer`](#currencyselect) of [`CurrencySelect.Section`](#currencyselect) rows to build a custom token picker. For a ready-made implementation see [`TokenSelectModal`](#tokenselectmodal).
**Members**
| Member | Description |
| ------------------------------ | ----------------------------------------------- |
| `CurrencySelect.Modal` | Modal wrapper. |
| `CurrencySelect.Search` | Auto-focused search input row. |
| `CurrencySelect.ListContainer` | Scrollable list area with built-in empty state. |
| `CurrencySelect.SectionHeader` | Header label rendered above a section. |
| `CurrencySelect.Section` | Container for a group of currency rows. |
#### LowBalanceModal [#lowbalancemodal]
Modal shown when a transaction would leave insufficient TON to cover fees — adapts its body and buttons to the [`LowBalanceMode`](#lowbalancemode).
| Prop | Type | Description |
| --------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open`\* | `boolean` | Controls visibility of the modal. |
| `mode`\* | LowBalanceMode {
console.log('Reduce amount to fit balance');
setOpen(false);
}}
onCancel={() => setOpen(false)}
/>
);
```
#### OptionSwitcher [#optionswitcher]
Compact dropdown selector — renders the current option's label and a chevron, opening a [`Select`](#select) popover with the remaining choices. Falls back to the raw `value` or `"—"` when no option matches.
| Prop | Type | Description |
| ------------ | ------------------------------------------------------------------------ | ----------------------------------------------------- |
| `value`\* | `string \| undefined` | Currently selected option value. |
| `options`\* | OptionSwitcherOption \[] console.log('Open settings')} />;
```
#### TokenSelectModal [#tokenselectmodal]
Ready-made token picker modal — renders a search field and a sectioned list of [`CurrencyItem`](#currencyitem) rows backed by [`CurrencySelect`](#currencyselect). Search matches by symbol, name, or exact address. Selecting a row fires `onSelect`, closes the modal, and resets the search.
| Prop | Type | Description |
| ------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `open`\* | `boolean` | Controls modal visibility. |
| `onClose`\* | `() => void` | Called when the modal is dismissed (selection, backdrop click, or escape). |
| `tokens`\* | T = AppkitUIToken \[] | Full set of tokens available for selection and search. |
| `tokenSections` | TokenSectionConfig \[](token: T = AppkitUIToken ) => void | Called with the picked token. The modal closes and resets its search on selection. |
| `title`\* | `string` | Modal header title. |
| `searchPlaceholder` | `string` | Placeholder shown inside the search input. |
**Example**
```tsx
return (
setOpen(false)}
tokens={tokens}
title="Select a token"
searchPlaceholder="Search by name or address"
onSelect={(token) => {
console.log('Picked:', token.symbol);
setOpen(false);
}}
/>
);
```
#### TokenSelector [#tokenselector]
Compact pill button used as the trigger for a token picker — shows the token icon (optionally with a network badge), its symbol, and a chevron unless `readOnly` is set.
| Prop | Type | Description |
| -------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`\* | `string` | Label shown next to the icon — typically the token symbol. |
| `icon` | `string` | Token logo URL. |
| `iconFallback` | `string` | Single-character fallback used when `icon` fails to load. Defaults to the first character of `title`. |
| `networkIcon` | `string` | When provided, renders a network badge overlay on the icon. |
| `readOnly` | `boolean` | Hide chevron and suppress click handling — use when there's nothing to pick. |
| `size` | `ButtonSize` | Size class applied to the button. Pass `'unset'` to skip the size class entirely (no padding, no typography) — useful with `variant="unstyled"`. |
| `borderRadius` | `ButtonBorderRadius` | Border radius token. Defaults to a size-dependent value (`s` → `2xl`, `m` → `l`, `l` → `xl`). |
| `variant` | `ButtonVariant` | Visual variant. Use `'unstyled'` to opt out of all built-in styling — the consumer is fully responsible for visuals via `className`. The Button still provides ref forwarding, `disabled`/`loading` plumbing, and `icon`/`children` rendering. |
| `loading` | `boolean` | When true, renders a spinner instead of `icon`/`children` and disables the button. |
| `fullWidth` | `boolean` | When true, the button stretches to fill its container width. |
**Example**
```tsx
return (
console.log('Open token picker')}
/>
);
```
### Staking [#staking-1]
#### SelectUnstakeMode [#selectunstakemode]
Collapsible selector for the unstake mode (instant / round-end / when-available). Filters options by `providerMetadata.supportedUnstakeModes` and renders nothing when only one mode is supported. Annotates the instant option with the provider's current instant-unstake limit.
| Prop | Type | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `value`\* | UnstakeModes (mode: UnstakeModes ) => void | Called when the user picks a different mode. |
| `providerInfo`\* | StakingProviderInfo \| undefinedStakingProviderMetadata \| undefinedStakingProviderMetadata \| undefinedStakingQuoteDirection console.log('Use max balance')}
/>
);
```
#### StakingInfo [#stakinginfo]
Summary block rendered below the staking input. Shows the amount the user will receive, the provider's current APY, the stake-token to receive-token exchange rate (only when the provider has a receive token), and the provider name. The exchange-rate row always reads as `1 stakeToken = X receiveToken`, regardless of `direction`.
| Prop | Type | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `quote`\* | StakingQuote \| undefinedStakingProviderInfo \| undefinedStakingProviderMetadata \| undefinedStakingQuoteDirection StakingProvider \| undefinedStakingProvider \[]Network setOpen(false)}
provider={provider}
providers={providers}
onProviderChange={(id) => console.log('Switch to', id)}
network={Network.mainnet()}
/>
);
```
#### StakingWidget [#stakingwidget]
High-level staking widget that wires the full stake/unstake flow: pick a provider, enter an amount (with optional reverse input on supported providers), review the quote (APY, exchange rate, "you get"), then submit the transaction. Internally wraps [`StakingWidgetProvider`](#stakingwidgetprovider) around [`StakingWidgetUI`](#stakingwidgetui). Consumers can replace the UI by passing a render-prop `children` while keeping the widget's state, quoting, balance checks, and submission logic.
| Prop | Type | Description |
| ---------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children` | (props: StakingWidgetRenderProps ) => ReactNode | Optional render-prop. When provided, the default [`StakingWidgetUI`](#stakingwidgetui) is bypassed and this function is called with the full [`StakingWidgetRenderProps`](#stakingwidgetrenderprops) (context state + forwarded `` props), letting consumers build a custom UI on top of the widget's internal logic. |
| `network` |
Network | Network used for quote fetching, balance reads, and transactions. Falls back to the connected wallet's network when omitted. |
**Example**
```tsx
// Falls back to the connected wallet's network when `network` is omitted.
// Make sure a staking provider (e.g. Tonstakers) is registered on AppKit.
return
;
```
#### StakingWidgetProvider [#stakingwidgetprovider]
Headless provider that drives the staking-widget flow — owns the input state (amount, direction, unstake mode, reverse-input toggle), fetches quotes and balances, validates the input, and builds + submits the transaction with a low-balance guard. Children read everything through [`useStakingContext`](#usestakingcontext); pair with [`StakingWidgetUI`](#stakingwidgetui) (or pass a custom UI to [`StakingWidget`](#stakingwidget)'s `children`).
| Prop | Type | Description |
| --------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `network` |
Network | Network used for quote fetching, balance reads, and transactions. Falls back to the connected wallet's network when omitted. |
#### StakingWidgetUI [#stakingwidgetui]
Default staking-widget UI. Renders a stake/unstake tabbed layout: a centered amount input with optional reversed input, a [`StakingBalanceBlock`](#stakingbalanceblock) for the relevant balance, the submit button (wired through `ButtonWithConnect` so a disconnected user is prompted to connect first), a settings button that opens [`StakingSettingsModal`](#stakingsettingsmodal), the unstake-mode picker ([`SelectUnstakeMode`](#selectunstakemode), unstake tab only), and a [`StakingInfo`](#stakinginfo) summary. A [`LowBalanceModal`](#lowbalancemodal) surfaces when the built transaction would exceed the user's TON balance. All state is consumed from props — typically supplied by [`StakingWidgetProvider`](#stakingwidgetprovider).
| Prop | Type | Description |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`\* | `string` | Amount the user wants to stake (string to preserve input UX) |
| `canSubmit`\* | `boolean` | Whether the user can proceed with staking (checks balance, amount validity, etc.) |
| `quote`\* |
StakingQuote \| undefined | Raw staking quote from the provider |
| `isQuoteLoading`\* | `boolean` | True while the stake quote is being fetched |
| `error`\* | `string \| null` | Current validation/fetch error for staking, null when everything is ok |
| `providerInfo`\* |
StakingProviderInfo \| undefined | Staking provider dynamic info (APY, instant unstake availability, etc.) |
| `providerMetadata`\* |
StakingProviderMetadata \| undefined | Staking provider static metadata |
| `stakingProvider`\* |
StakingProvider \| undefined | Currently selected staking provider (defaults to the first registered one) |
| `stakingProviders`\* |
StakingProvider \[] | All registered staking providers |
| `setStakingProviderId`\* | `(providerId: string) => void` | Updates the selected staking provider |
| `network`\* |
Network \| undefined | Network the widget is operating on (resolved from prop or wallet) |
| `direction`\* |
StakingQuoteDirection | Current operation direction: 'stake' or 'unstake' |
| `isProviderInfoLoading`\* | `boolean` | True while provider info is being fetched |
| `balance`\* | `string \| undefined` | Base balance (native or jetton) available for staking |
| `isBalanceLoading`\* | `boolean` | True while base balance is being fetched |
| `stakedBalance`\* |
StakingBalance \| undefined | User's currently staked balance |
| `isStakedBalanceLoading`\* | `boolean` | True while staked balance is being fetched |
| `unstakeMode`\* |
UnstakeModes | Selected unstake-timing mode — `'INSTANT'`, `'WHEN_AVAILABLE'`, or `'ROUND_END'`. See [`UnstakeMode`](/applications/appkit/reference/appkit#unstakemode). |
| `setAmount`\* | `(amount: string) => void` | Sets the input amount |
| `setUnstakeMode`\* |
(mode: UnstakeModes ) => void | Sets the unstake mode |
| `sendTransaction`\* | `() => Promise
` | Triggers the staking/unstaking transaction |
| `onChangeDirection`\* | (direction: StakingQuoteDirection ) => void | Changes the direction (stake/unstake) |
| `isSendingTransaction`\* | `boolean` | True while a transaction is being processed |
| `isReversed`\* | `boolean` | True if the user is inputting the output amount ("I want to get X") |
| `toggleReversed`\* | `() => void` | Toggles between inputting from amount and output amount |
| `reversedAmount`\* | `string` | Amount displayed in the reversed (bottom) input |
| `onMaxClick`\* | `() => void` | Sets the input amount to the maximum available balance (leaves room for TON gas on native stake) |
| `isLowBalanceWarningOpen`\* | `boolean` | True when the built transaction outflow exceeds the user's TON balance |
| `lowBalanceMode`\* | `'reduce' \| 'topup'` | `reduce` when the outgoing token is TON (user can fix by changing amount), `topup` otherwise. |
| `lowBalanceRequiredTon`\* | `string` | Required TON amount for the pending operation, formatted as a decimal string. Empty when no pending op. |
| `onLowBalanceChange`\* | `() => void` | Replace the input with a value that fits within the current TON balance and close the warning. |
| `onLowBalanceCancel`\* | `() => void` | Dismiss the low-balance warning without changing the input. |
### Swap [#swap-1]
#### SwapField [#swapfield]
One row of the swap form. Renders the amount input, fiat conversion, balance line, and a token-selector chip. The `pay` variant is editable and exposes a "max" shortcut. The `receive` variant is read-only and shows the quote result.
| Prop | Type | Description | | |
| ---------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --- | ------------------------- |
| `type`\* | `'pay' \| 'receive'` | `pay` renders the editable source row with a "max" shortcut. `receive` renders the read-only target row. | | |
| `amount`\* | `string` | Current amount shown in the input as a human-readable decimal string. | | |
| `fiatSymbol` | `string` | Fiat currency symbol displayed in front of the converted value. Defaults to `"$"`. | | |
| `token` | AppkitUIToken setAmount('12.5')}
onTokenSelectorClick={() => console.log('Open token picker')}
/>
);
```
#### SwapFlipButton [#swapflipbutton]
Round button rendered between the source and target [`SwapField`](#swapfield) rows. Clicking it flips the selected tokens. Visual rotation is driven by `rotated`.
| Prop | Type | Description |
| --------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `onClick` | `() => void` | Called when the user clicks the button. Wire this to a handler that swaps the source/target tokens (e.g. `onFlip` from the swap context). |
| `rotated` | `boolean` | When true, the icon is drawn in its rotated state — used to animate between flips. |
**Example**
```tsx
// Drop it between the source and target `SwapField` rows. Wire `onClick` to your token-flip handler.
return setRotated((prev) => !prev)} />;
```
#### SwapInfo [#swapinfo]
Summary block rendered under the swap form. Shows the minimum amount the user is guaranteed to receive after slippage, the configured slippage tolerance, and the active [`SwapProvider`](/applications/appkit/reference/appkit#swapprovider).
| Prop | Type | Description |
| ---------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `toToken`\* | AppkitUIToken \| nullSwapProvider SwapQuote (props: SwapWidgetRenderProps ) => ReactNode | Optional render-prop receiving the full swap context plus the forwarded `` props. When supplied it replaces the default [`SwapWidgetUI`](#swapwidgetui). |
| `network` |
Network | Network used for quote fetching and balance reads. When omitted, falls back to the selected wallet's network via [`useNetwork`](#usenetwork). |
| `tokens`\* |
AppkitUIToken \[] | Full list of tokens available for swapping in the UI. Filtered to the active network internally. |
| `tokenSections` |
TokenSectionConfig \[] | Optional section configs for grouping tokens inside the `SwapTokenSelectModal`. |
| `defaultFromSymbol` | `string` | Symbol of the token pre-selected as the source on first mount (e.g. `"TON"`). |
| `defaultToSymbol` | `string` | Symbol of the token pre-selected as the target on first mount. |
| `fiatSymbol` | `string` | Fiat currency symbol displayed next to converted amounts. Defaults to `"$"`. |
| `defaultSlippage` | `number` | Initial slippage tolerance in basis points (`100` = 1%). Defaults to `100`. |
**Example**
```tsx
// Make sure a swap provider (e.g. DeDust / Omniston) is registered on AppKit.
return
;
```
#### SwapWidgetProvider [#swapwidgetprovider]
Provider that wires up the full swap state machine — debounces the entered amount, fetches the quote via [`useSwapQuote`](#useswapquote), reads source/target balances, validates the input, exposes the active [`SwapProvider`](/applications/appkit/reference/appkit#swapprovider), and offers `sendSwapTransaction` which builds the transaction with [`useBuildSwapTransaction`](#usebuildswaptransaction) and sends it (raising the low-balance warning when the outflow exceeds the user's TON balance). Children read everything through [`useSwapContext`](#useswapcontext).
| Prop | Type | Description |
| ------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `tokens`\* |
AppkitUIToken \[] | Full list of tokens available for swapping in the UI. Filtered to the active network internally. |
| `tokenSections` |
TokenSectionConfig \[] | Optional section configs for grouping tokens inside the `SwapTokenSelectModal`. |
| `defaultFromSymbol` | `string` | Symbol of the token pre-selected as the source on first mount (e.g. `"TON"`). |
| `defaultToSymbol` | `string` | Symbol of the token pre-selected as the target on first mount. |
| `network` |
Network | Network used for quote fetching and balance reads. When omitted, falls back to the selected wallet's network via [`useNetwork`](#usenetwork). |
| `fiatSymbol` | `string` | Fiat currency symbol displayed next to converted amounts. Defaults to `"$"`. |
| `defaultSlippage` | `number` | Initial slippage tolerance in basis points (`100` = 1%). Defaults to `100`. |
#### SwapWidgetUI [#swapwidgetui]
Default visual implementation of the swap widget — composes [`SwapField`](#swapfield) (source, then target), a [`SwapFlipButton`](#swapflipbutton) between them, the submit button (auto-prompts wallet connect when no wallet is selected), the settings trigger that opens `SwapSettingsModal`, a `SwapTokenSelectModal` for picking source/target tokens, the [`SwapInfo`](#swapinfo) summary, and a low-balance warning. Drives all state from the swap context props it receives — pair with [`SwapWidgetProvider`](#swapwidgetprovider), or use [`SwapWidget`](#swapwidget) which mounts both.
| Prop | Type | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `tokens`\* |
AppkitUIToken \[] | Full list of available tokens for swapping |
| `tokenSections` |
TokenSectionConfig \[] | Optional section configs for grouping tokens in the selector |
| `fromToken`\* |
AppkitUIToken \| null | Currently selected source token |
| `toToken`\* |
AppkitUIToken \| null | Currently selected target token |
| `fromAmount`\* | `string` | Amount the user wants to swap (string to preserve input UX) |
| `toAmount`\* | `string` | Calculated receive amount from the current quote |
| `fiatSymbol`\* | `string` | Fiat currency symbol for price display, e.g. "\$" |
| `fromBalance`\* | `string \| undefined` | User's balance of the "from" token |
| `toBalance`\* | `string \| undefined` | User's balance of the "to" token |
| `isFromBalanceLoading`\* | `boolean` | True while the "from" balance is being fetched |
| `isToBalanceLoading`\* | `boolean` | True while the "to" balance is being fetched |
| `canSubmit`\* | `boolean` | Whether the user can proceed with the swap (checks balance, amount, quote) |
| `quote`\* | `GetSwapQuoteData \| undefined` | Raw swap quote from the provider |
| `isQuoteLoading`\* | `boolean` | True while the quote is being fetched from the API |
| `error`\* | `string \| null` | Current validation or fetch error, null when everything is ok |
| `slippage`\* | `number` | Slippage tolerance in basis points (100 = 1%) |
| `swapProvider`\* |
SwapProvider \| undefined | Currently selected swap provider (defaults to the first registered one) |
| `swapProviders`\* |
SwapProvider \[] | All registered swap providers |
| `setSwapProviderId`\* | `(providerId: string) => void` | Updates the selected swap provider |
| `setFromToken`\* |
(token: AppkitUIToken ) => void | Updates the source token |
| `setToToken`\* |
(token: AppkitUIToken ) => void | Updates the target token |
| `setFromAmount`\* | `(amount: string) => void` | Updates the swap amount |
| `setSlippage`\* | `(slippage: number) => void` | Updates the slippage tolerance |
| `onFlip`\* | `() => void` | Swaps source and target tokens |
| `onMaxClick`\* | `() => void` | Sets the "from" amount to the maximum available balance |
| `sendSwapTransaction`\* | `() => Promise
` | Executes the swap transaction |
| `isSendingTransaction`\* | `boolean` | True while a transaction is being built or sent |
| `isLowBalanceWarningOpen`\* | `boolean` | True when the built transaction outflow exceeds the user's TON balance |
| `lowBalanceMode`\* | `'reduce' \| 'topup'` | `reduce` when the outgoing token is TON (user can fix by changing amount), `topup` otherwise. |
| `lowBalanceRequiredTon`\* | `string` | Required TON amount for the pending operation, formatted as a decimal string. Empty when no pending op. |
| `onLowBalanceChange`\* | `() => void` | Replace the input with a value that fits within the current TON balance and close the warning. |
| `onLowBalanceCancel`\* | `() => void` | Dismiss the low-balance warning without changing the input. |
### UI [#ui]
#### Block [#block]
Flex container primitive — renders a `` that lays its children out vertically (`'column'`) or horizontally (`'row'`).
| Prop | Type | Description |
| ----------- | ------------------- | ---------------------------------------------------- |
| `direction` | `'row' \| 'column'` | Flex direction of the block. Defaults to `'column'`. |
**Example**
```tsx
return (
Left
Right
);
```
#### Button [#button]
Themed `
` with size, border-radius, and variant tokens. Renders an optional leading `icon`, swaps content for a spinner while `loading`, and is disabled whenever `disabled` or `loading` is true.
| Prop | Type | Description |
| -------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `size` | `ButtonSize` | Size class applied to the button. Pass `'unset'` to skip the size class entirely (no padding, no typography) — useful with `variant="unstyled"`. |
| `borderRadius` | `ButtonBorderRadius` | Border radius token. Defaults to a size-dependent value (`s` → `2xl`, `m` → `l`, `l` → `xl`). |
| `variant` | `ButtonVariant` | Visual variant. Use `'unstyled'` to opt out of all built-in styling — the consumer is fully responsible for visuals via `className`. The Button still provides ref forwarding, `disabled`/`loading` plumbing, and `icon`/`children` rendering. |
| `loading` | `boolean` | When true, renders a spinner instead of `icon`/`children` and disables the button. |
| `fullWidth` | `boolean` | When true, the button stretches to fill its container width. |
| `icon` | `ReactNode` | Optional leading icon rendered before `children` when not loading. |
**Example**
```tsx
return (
console.log('Clicked')}>
Send transaction
);
```
#### CenteredAmountInput [#centeredamountinput]
Center-aligned, auto-resizing amount input with optional leading symbol and trailing ticker. Scales the font down to fit the container when the rendered text overflows, and clicking the wrapper focuses the input.
| Prop | Type | Description |
| ----------------- | ------------------------- | ------------------------------------------------------------- |
| `value`\* | `string` | Controlled input value (decimal string). |
| `onValueChange`\* | `(value: string) => void` | Called with the new string whenever the user edits the input. |
| `ticker` | `string` | Optional trailing ticker label (e.g., `'TON'`). |
| `symbol` | `string` | Optional leading currency symbol (e.g., `'$'`). |
| `placeholder` | `string` | Placeholder shown when `value` is empty. Defaults to `'0'`. |
| `disabled` | `boolean` | When true, the underlying `
setOpen((prev) => !prev)}>{open ? 'Hide details' : 'Show details'}
Hidden details about the transaction.
);
```
#### InfoBlock [#infoblock]
Compound component for rendering a stacked list of label/value rows (e.g., transaction details, settings summaries). Sub-components forward extra props to the underlying DOM element so callers can layer custom classes and handlers.
**Members**
| Member | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `InfoBlock.Container` | Outer wrapper — vertical container that hosts the rows. |
| `InfoBlock.Row` | Horizontal row that pairs a label with a value. |
| `InfoBlock.Label` | Label cell — typically the muted descriptor on the left. |
| `InfoBlock.Value` | Value cell — typically the emphasized content on the right. |
| `InfoBlock.LabelSkeleton` | Skeleton placeholder for a [`InfoBlock.Label`](#infoblock) while data is loading. Defaults to `width=64`, `height='1lh'`. |
| `InfoBlock.ValueSkeleton` | Skeleton placeholder for a [`InfoBlock.Value`](#infoblock) while data is loading. Defaults to `width=80`, `height='1lh'`. |
**Example**
```ts
return (
Rate
1 TON ≈ $5.43
Network fee
0.01 TON
);
```
#### Input [#input]
Compound text-input component. Use the default export as the outer wrapper (it is the [`Input.Container`](#input)) and compose sub-components for the header, field, slots, control, and caption. State flags (`disabled`, `error`, `loading`, `resizable`, `size`) live on the container and are read by the inner control via context.
**Members**
| Member | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------------------- |
| `Input.Container` | Outer wrapper that provides input context (size, variant, disabled, error, loading, resizable). |
| `Input.Header` | Header row above the field — holds the title and optional trailing controls. |
| `Input.Title` | Title text shown inside [`Input.Header`](#input). |
| `Input.Field` | Horizontal row that holds slots and the input control. |
| `Input.Slot` | Side-anchored slot used for adornments such as icons or buttons. |
| `Input.Input` | The actual `
Recipient
setValue(event.target.value)} placeholder="EQ..." />
Paste a TON wallet address.
);
```
#### Logo [#logo]
Square logo / avatar primitive — renders an `
setOpen(true)}>Open modal
Are you sure you want to proceed?
);
```
#### Select [#select]
Compound select / dropdown component with controlled or uncontrolled state. The content is portaled to `document.body` and positioned relative to the trigger. Closes on outside click, `Escape`, or item selection.
**Members**
| Member | Description |
| ---------------- | --------------------------------------------------------------------------------------------------------- |
| `Select.Root` | Provider that owns the selected value and open state, controlled or uncontrolled. |
| `Select.Trigger` | [`Button`](#button)-based trigger that toggles the popover and exposes `aria-expanded`. |
| `Select.Content` | Portaled popover that renders the list of items. Positioned under the trigger with optional `sideOffset`. |
| `Select.Item` | Selectable option row. Commits its `value` to the root on click. |
**Example**
```ts
return (
{value === 'mainnet' ? 'Mainnet' : 'Testnet'}
Mainnet
Testnet
);
```
#### Skeleton [#skeleton]
Animated placeholder block used while data is loading. Supply `width` / `height` to match the dimensions of the eventual content.
| Prop | Type | Description |
| -------- | ------------------ | -------------------------------------------------------------------------------------------- |
| `width` | `string \| number` | Width of the placeholder. Accepts any valid CSS length or a number (interpreted as pixels). |
| `height` | `string \| number` | Height of the placeholder. Accepts any valid CSS length or a number (interpreted as pixels). |
**Example**
```tsx
return
Stake
Unstake
Stake your TON to earn rewards.
Withdraw your staked TON.
);
```
#### TabsContent [#tabscontent]
Tab panel rendered with `role="tabpanel"`. Returns `null` unless its `value` matches the active [`Tabs`](#tabs) value.
| Prop | Type | Description |
| ------------ | ----------- | ----------------------------------------------------------------------------------------------------- |
| `value`\* | `string` | Value this panel is associated with — rendered only when the parent [`Tabs`](#tabs) is on this value. |
| `children`\* | `ReactNode` | Panel content. |
#### TabsList [#tabslist]
Horizontal list of tab triggers with `role="tablist"`.
| Prop | Type | Description |
| ------------ | ----------- | -------------------------------------------------------------------- |
| `children`\* | `ReactNode` | Tab triggers — typically one or more [`TabsTrigger`](#tabstrigger)s. |
#### TabsTrigger [#tabstrigger]
Tab trigger button with `role="tab"`. Activates its `value` on click and reflects active state via `aria-selected` and `data-state`.
| Prop | Type | Description |
| ------------ | ----------- | ----------------------------------------------------------------------------- |
| `value`\* | `string` | Value committed to the parent [`Tabs`](#tabs) when this trigger is activated. |
| `children`\* | `ReactNode` | Trigger label / content. |
#### TonIcon [#tonicon]
TON brand diamond glyph — solid, inherits color from `currentColor`.
| Prop | Type | Description |
| ------ | -------- | ----------------------------------------------------------------------------------------- |
| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
#### TonIconCircle [#toniconcircle]
TON brand glyph rendered inside a filled circle, using the TON brand color token.
| Prop | Type | Description |
| ------ | -------- | ----------------------------------------------------------------------------------------- |
| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
## Type [#type]
### Balances [#balances-2]
#### SendJettonButtonProps [#sendjettonbuttonprops]
Props accepted by [`SendJettonButton`](#sendjettonbutton) — extends the base `Send` button props (button text, sizing, callbacks) with the jetton-transfer details.
| Field | Type | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recipientAddress`\* | `string` | Recipient address. |
| `amount`\* | `string` | Amount in jetton units as a human-readable decimal string. Converted to raw smallest units via `jetton.decimals`. |
| `jetton`\* | `{ address: string; symbol: string; decimals: number; }` | Jetton master metadata — `address` (master contract), `symbol` (rendered in the button label) and `decimals` (used to format `amount`). |
| `comment` | `string` | Optional human-readable comment attached to the transfer. |
| `text` | `ReactNode` | Override the button label. Defaults to "Send". |
| `size` | `ButtonSize` | Size class applied to the button. Pass `'unset'` to skip the size class entirely (no padding, no typography) — useful with `variant="unstyled"`. |
| `borderRadius` | `ButtonBorderRadius` | Border radius token. Defaults to a size-dependent value (`s` → `2xl`, `m` → `l`, `l` → `xl`). |
| `variant` | `ButtonVariant` | Visual variant. Use `'unstyled'` to opt out of all built-in styling — the consumer is fully responsible for visuals via `className`. The Button still provides ref forwarding, `disabled`/`loading` plumbing, and `icon`/`children` rendering. |
| `loading` | `boolean` | When true, renders a spinner instead of `icon`/`children` and disables the button. |
| `fullWidth` | `boolean` | When true, the button stretches to fill its container width. |
| `icon` | `ReactNode` | Optional leading icon rendered before `children` when not loading. |
| `children` | `(props: SendRenderProps) => ReactNode` | Custom render function — replaces the default button with the caller's UI. Receives the current send state and click handler via [`SendRenderProps`](#sendrenderprops). |
| `onError` | `(error: Error) => void` | Called when the wallet rejects the request or the send fails. Receives the raised `Error`. |
| `onSuccess` | (response: SendTransactionReturnType ) => void | Called once the transaction is broadcast. Receives the wallet's [`SendTransactionReturnType`](/applications/appkit/reference/appkit#sendtransactionreturntype) (BoC + normalized hash). |
#### SendTonButtonProps [#sendtonbuttonprops]
Props accepted by [`SendTonButton`](#sendtonbutton) — extends the base `Send` button props (button text, sizing, callbacks) with the TON-transfer details.
| Field | Type | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recipientAddress`\* | `string` | Recipient address. |
| `amount`\* | `string` | Amount in TON as a human-readable decimal string (e.g., `"1.5"`). Converted to nano-TON internally. |
| `comment` | `string` | Optional human-readable comment attached to the transfer. |
| `text` | `ReactNode` | Override the button label. Defaults to "Send". |
| `size` | `ButtonSize` | Size class applied to the button. Pass `'unset'` to skip the size class entirely (no padding, no typography) — useful with `variant="unstyled"`. |
| `borderRadius` | `ButtonBorderRadius` | Border radius token. Defaults to a size-dependent value (`s` → `2xl`, `m` → `l`, `l` → `xl`). |
| `variant` | `ButtonVariant` | Visual variant. Use `'unstyled'` to opt out of all built-in styling — the consumer is fully responsible for visuals via `className`. The Button still provides ref forwarding, `disabled`/`loading` plumbing, and `icon`/`children` rendering. |
| `loading` | `boolean` | When true, renders a spinner instead of `icon`/`children` and disables the button. |
| `fullWidth` | `boolean` | When true, the button stretches to fill its container width. |
| `icon` | `ReactNode` | Optional leading icon rendered before `children` when not loading. |
| `children` | `(props: SendRenderProps) => ReactNode` | Custom render function — replaces the default button with the caller's UI. Receives the current send state and click handler via [`SendRenderProps`](#sendrenderprops). |
| `onError` | `(error: Error) => void` | Called when the wallet rejects the request or the send fails. Receives the raised `Error`. |
| `onSuccess` | (response: SendTransactionReturnType ) => void | Called once the transaction is broadcast. Receives the wallet's [`SendTransactionReturnType`](/applications/appkit/reference/appkit#sendtransactionreturntype) (BoC + normalized hash). |
#### UseBalanceByAddressParameters [#usebalancebyaddressparameters]
Parameters accepted by [`useBalanceByAddress`](#usebalancebyaddress) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the target address and optional network override.
| Field | Type | Description |
| --------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `address` | UserFriendlyAddress \| AddressNetwork UserFriendlyAddress \| AddressNetwork ;
```
#### UseWatchBalanceByAddressParameters [#usewatchbalancebyaddressparameters]
Parameters accepted by [`useWatchBalanceByAddress`](#usewatchbalancebyaddress) — same fields as [`WatchBalanceByAddressOptions`](/applications/appkit/reference/appkit#watchbalancebyaddressoptions), all optional so callers can render the hook before the address is known.
```ts
type UseWatchBalanceByAddressParameters = Partial;
```
#### UseWatchBalanceParameters [#usewatchbalanceparameters]
Parameters accepted by [`useWatchBalance`](#usewatchbalance) — same fields as [`UseWatchBalanceByAddressParameters`](#usewatchbalancebyaddressparameters) minus `address`, which the hook resolves from the selected wallet.
```ts
type UseWatchBalanceParameters = Omit;
```
### Connectors [#connectors-1]
#### UseConnectorsReturnType [#useconnectorsreturntype]
Return type of [`useConnectors`](#useconnectors) — same shape as [`GetConnectorsReturnType`](/applications/appkit/reference/appkit#getconnectorsreturntype).
```ts
type UseConnectorsReturnType = GetConnectorsReturnType;
```
### Crypto Onramp [#crypto-onramp-2]
#### ChainInfo [#chaininfo]
Display info for a CAIP-2 chain — used by the crypto onramp widget to render chain names and logos.
| Field | Type | Description |
| -------- | -------- | ---------------------------------------------------------------- |
| `name`\* | `string` | Human-readable chain name (e.g. `"Ethereum"`, `"Arbitrum One"`). |
| `logo` | `string` | Optional logo URL for the chain. |
#### CryptoAmountInputMode [#cryptoamountinputmode]
Which side the amount input is currently denominated in — `token` means the user is entering the target-token amount, `method` means they are entering the source payment-method amount.
```ts
type CryptoAmountInputMode = 'token' | 'method';
```
#### CryptoOnrampContextType [#cryptoonrampcontexttype]
Shape of the `CryptoOnrampContext` value — selection state, quote/deposit data and actions exposed by [`CryptoOnrampWidgetProvider`](#cryptoonrampwidgetprovider) to the widget UI (and to custom render callbacks passed to [`CryptoOnrampWidget`](#cryptoonrampwidget)).
| Field | Type | Description |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `tokens`\* | CryptoOnrampToken \[]CryptoOnrampTokenSectionConfig \[]CryptoOnrampToken \| null(token: CryptoOnrampToken ) => void | Updates `selectedToken`. |
| `paymentMethods`\* | CryptoPaymentMethod \[]PaymentMethodSectionConfig \[]CryptoPaymentMethod (method: CryptoPaymentMethod ) => void | Updates `selectedMethod`. |
| `chains`\* | Record\ChainInfo> | CAIP-2 → chain display info map (built-in defaults merged with consumer overrides). |
| `amount`\* | `string` | Current amount input value as a decimal string. |
| `setAmount`\* | `(value: string) => void` | Updates `amount`. |
| `amountInputMode`\* | CryptoAmountInputMode (mode: CryptoAmountInputMode ) => void | Updates `amountInputMode`. |
| `convertedAmount`\* | `string` | Other side of `amount` after applying the current quote's rate. |
| `presetAmounts`\* | OnrampAmountPreset \[]CryptoOnrampQuote \| nullCryptoOnrampDeposit \| nullCryptoOnrampStatus \| nullCryptoOnrampToken \[]CryptoOnrampTokenSectionConfig \[]CryptoPaymentMethod \[]PaymentMethodSectionConfig \[]Record\ChainInfo> | Custom CAIP-2 → chain display info overrides. Merged on top of the built-in defaults, so consumers only need to provide what they want to override or add — for example, a single entry keyed by `'eip155:42161'` with a `name` of `'Arbitrum'` and a `logo` URL. |
| `defaultTokenId` | `string` | ID of the target token pre-selected on mount. |
| `defaultMethodId` | `string` | ID of the source payment method pre-selected on mount. |
#### CryptoOnrampToken [#cryptoonramptoken]
Target token (what the user is buying on TON) in the crypto onramp widget. Kept separate from `AppkitUIToken` because `address` is the raw form expected by the onramp provider (e.g. `"0x0000000000000000000000000000000000000000"` for native TON, `"EQCx..."` for USDT jetton master).
| Field | Type | Description |
| ------------ | -------- | ------------------------------------------------------------------ |
| `id`\* | `string` | Stable identifier used by section configs and pre-selection props. |
| `symbol`\* | `string` | Token symbol, e.g. `"TON"`, `"USDT"`. |
| `name`\* | `string` | Full token name, e.g. `"Toncoin"`, `"Tether"`. |
| `decimals`\* | `number` | Number of decimals for the token. |
| `address`\* | `string` | Address as the onramp provider expects it. |
| `logo` | `string` | Optional logo URL. |
#### CryptoOnrampTokenSectionConfig [#cryptoonramptokensectionconfig]
Section configuration grouping [`CryptoOnrampToken`](#cryptoonramptoken) entries by id in a picker.
| Field | Type | Description |
| --------- | ---------- | ---------------------------------------------------------------------------------------------- |
| `title`\* | `string` | Section header (typically already localized by the caller). |
| `ids`\* | `string[]` | Ids of [`CryptoOnrampToken`](#cryptoonramptoken) entries to include in this section, in order. |
#### CryptoOnrampWidgetProps [#cryptoonrampwidgetprops]
Props for [`CryptoOnrampWidget`](#cryptoonrampwidget) — extends [`CryptoOnrampProviderProps`](#cryptoonrampproviderprops) (tokens, payment methods, defaults, chain overrides) plus the native `` props the widget root forwards.
| Field | Type | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children` |
(props: CryptoOnrampWidgetRenderProps ) => ReactNode | Custom render function. When provided, replaces the default [`CryptoOnrampWidgetUI`](#cryptoonrampwidgetui) and is called with the full [`CryptoOnrampWidgetRenderProps`](#cryptoonrampwidgetrenderprops) (context state, actions and forwarded `
` props), so callers can build a fully custom UI on top of the same provider. |
| `tokens` |
CryptoOnrampToken \[] | Target tokens (what the user buys on TON). Defaults to a built-in list. |
| `tokenSections` |
CryptoOnrampTokenSectionConfig \[] | Optional section configs grouping `tokens` in the picker. |
| `paymentMethods` |
CryptoPaymentMethod \[] | Source crypto payment methods (what the user pays with on another chain). Defaults to a built-in list. |
| `methodSections` |
PaymentMethodSectionConfig \[] | Optional section configs grouping `paymentMethods` in the picker. |
| `chains` |
Record\ChainInfo> | Custom CAIP-2 → chain display info overrides. Merged on top of the built-in defaults, so consumers only need to provide what they want to override or add — for example, a single entry keyed by `'eip155:42161'` with a `name` of `'Arbitrum'` and a `logo` URL. |
| `defaultTokenId` | `string` | ID of the target token pre-selected on mount. |
| `defaultMethodId` | `string` | ID of the source payment method pre-selected on mount. |
#### CryptoOnrampWidgetRenderProps [#cryptoonrampwidgetrenderprops]
Props for [`CryptoOnrampWidgetUI`](#cryptoonrampwidgetui) (and for the custom render callback on [`CryptoOnrampWidget`](#cryptoonrampwidget)) — the full [`CryptoOnrampContextType`](#cryptoonrampcontexttype) state and actions, plus the native `
` props the widget root forwards (`className`, `style`, etc.).
| Field | Type | Description |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `tokens`\* |
CryptoOnrampToken \[] | Full list of target tokens the user can buy. |
| `tokenSections` |
CryptoOnrampTokenSectionConfig \[] | Optional section configs grouping `tokens` in the picker. |
| `selectedToken`\* |
CryptoOnrampToken \| null | Currently selected target token to buy. `null` until tokens load. |
| `setSelectedToken`\* |
(token: CryptoOnrampToken ) => void | Updates `selectedToken`. |
| `paymentMethods`\* |
CryptoPaymentMethod \[] | Available source crypto payment methods. |
| `methodSections` |
PaymentMethodSectionConfig \[] | Optional section configs grouping `paymentMethods` in the picker. |
| `selectedMethod`\* |
CryptoPaymentMethod | Currently selected source payment method. |
| `setSelectedMethod`\* |
(method: CryptoPaymentMethod ) => void | Updates `selectedMethod`. |
| `chains`\* |
Record\ChainInfo> | CAIP-2 → chain display info map (built-in defaults merged with consumer overrides). |
| `amount`\* | `string` | Current amount input value as a decimal string. |
| `setAmount`\* | `(value: string) => void` | Updates `amount`. |
| `amountInputMode`\* |
CryptoAmountInputMode | Which side `amount` is denominated in — see [`CryptoAmountInputMode`](#cryptoamountinputmode). |
| `setAmountInputMode`\* |
(mode: CryptoAmountInputMode ) => void | Updates `amountInputMode`. |
| `convertedAmount`\* | `string` | Other side of `amount` after applying the current quote's rate. |
| `presetAmounts`\* |
OnrampAmountPreset \[] | Quick-pick amount buttons rendered in the widget. |
| `quote`\* |
CryptoOnrampQuote \| null | Current quote, or `null` if not yet fetched / invalidated. |
| `isLoadingQuote`\* | `boolean` | Whether a quote is in flight (includes the input-debounce window). |
| `quoteError`\* | `string \| null` | Quote-side validation/fetch error as an i18n key, or `null`. |
| `quoteProviderName`\* | `string \| null` | Display name of the provider behind the current quote, when available. |
| `deposit`\* |
CryptoOnrampDeposit \| null | Current deposit returned by the provider once `createDeposit` succeeded. |
| `isCreatingDeposit`\* | `boolean` | Whether `createDeposit` is in flight. |
| `depositError`\* | `string \| null` | Deposit-side error as an i18n key, or `null`. |
| `depositAmount`\* | `string` | Formatted deposit amount the user must send on the source chain. |
| `createDeposit`\* | `() => void` | Triggers deposit creation from the current quote. |
| `depositStatus`\* |
CryptoOnrampStatus \| null | Latest deposit status polled via [`useCryptoOnrampStatus`](#usecryptoonrampstatus), or `null`. |
| `isRefundAddressRequired`\* | `boolean` | Whether the current quote provider requires a refund address before deposit. |
| `isReversedAmountSupported`\* | `boolean` | Whether the current quote provider supports reversed (target-amount) input. |
| `refundAddress`\* | `string` | Refund address the user typed, if `isRefundAddressRequired`. |
| `setRefundAddress`\* | `(address: string) => void` | Updates `refundAddress`. |
| `targetBalance`\* | `string` | Connected wallet's balance of the selected target token (formatted, token units). |
| `isLoadingTargetBalance`\* | `boolean` | Whether the target token balance is being fetched. |
| `isWalletConnected`\* | `boolean` | Whether a TON wallet is currently connected. |
| `canContinue`\* | `boolean` | Whether the user can proceed — valid amount, quote available, and wallet connected. |
| `onReset`\* | `() => void` | Invalidates the active quote and clears the deposit, returning the widget to its initial state. |
#### CryptoPaymentMethod [#cryptopaymentmethod]
Source crypto payment method (what the user pays with on another chain) in the crypto onramp widget.
| Field | Type | Description |
| ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`\* | `string` | Stable identifier for the method — used for selection state and `methodSections.ids` |
| `symbol`\* | `string` | Token symbol, e.g. "USDC", "USDT". |
| `name`\* | `string` | Full token name shown in the picker, e.g. "USD Coin", "Tether". |
| `chain`\* | `string` | Source chain in CAIP-2 format, e.g. "eip155:8453", "eip155:56" — passed as `sourceChain` to the onramp provider. The widget resolves a display name and logo for it via the `chains` map (see `CryptoOnrampWidgetProvider`). |
| `decimals`\* | `number` | Number of decimals for the token (used to convert between display and base units) |
| `address`\* | `string` | Token contract address on the source network (empty string / zero address for native) |
| `logo` | `string` | Token logo URL shown in the picker and selectors. |
#### OnrampAmountPreset [#onrampamountpreset]
Quick-pick amount button shown above the crypto-onramp input (carried on [`CryptoOnrampContextType`](#cryptoonrampcontexttype)'s `presetAmounts`).
| Field | Type | Description |
| ---------- | -------- | ------------------------------------------------------- |
| `amount`\* | `string` | Amount value the preset sets on click (decimal string). |
| `label`\* | `string` | Button label shown to the user. |
#### PaymentMethodSectionConfig [#paymentmethodsectionconfig]
Section configuration grouping [`CryptoPaymentMethod`](#cryptopaymentmethod) entries by id in a picker.
| Field | Type | Description |
| --------- | ---------- | -------------------------------------------------------------------------------------------------- |
| `title`\* | `string` | Section header (typically already localized by the caller). |
| `ids`\* | `string[]` | Ids of [`CryptoPaymentMethod`](#cryptopaymentmethod) entries to include in this section, in order. |
#### UseCreateCryptoOnrampDepositParameters [#usecreatecryptoonrampdepositparameters]
Parameters accepted by [`useCreateCryptoOnrampDeposit`](#usecreatecryptoonrampdeposit) — TanStack Query mutation options forwarded via `parameters.mutation`.
```ts
type UseCreateCryptoOnrampDepositParameters = CreateCryptoOnrampDepositMutationOptions
;
```
#### UseCreateCryptoOnrampDepositReturnType [#usecreatecryptoonrampdepositreturntype]
Return type of [`useCreateCryptoOnrampDeposit`](#usecreatecryptoonrampdeposit) — TanStack Query mutation result.
```ts
type UseCreateCryptoOnrampDepositReturnType = UseMutationResult<
CreateCryptoOnrampDepositData,
CreateCryptoOnrampDepositErrorType,
CreateCryptoOnrampDepositVariables,
context
>;
```
#### UseCryptoOnrampProviderParameters [#usecryptoonrampproviderparameters]
Parameters accepted by [`useCryptoOnrampProvider`](#usecryptoonrampprovider) — optional provider id forwarded to [`getCryptoOnrampProvider`](/applications/appkit/reference/appkit#getcryptoonrampprovider).
```ts
type UseCryptoOnrampProviderParameters = GetCryptoOnrampProviderOptions;
```
#### UseCryptoOnrampProviderReturnType [#usecryptoonrampproviderreturntype]
Return type of [`useCryptoOnrampProvider`](#usecryptoonrampprovider) — the matching [`CryptoOnrampProviderInterface`](/applications/appkit/reference/appkit#cryptoonrampproviderinterface), or `undefined` when none is registered (the hook swallows the throw from [`getCryptoOnrampProvider`](/applications/appkit/reference/appkit#getcryptoonrampprovider)).
```ts
type UseCryptoOnrampProviderReturnType = GetCryptoOnrampProviderReturnType | undefined;
```
#### UseCryptoOnrampProvidersReturnType [#usecryptoonrampprovidersreturntype]
Return type of [`useCryptoOnrampProviders`](#usecryptoonrampproviders) — array of every [`CryptoOnrampProviderInterface`](/applications/appkit/reference/appkit#cryptoonrampproviderinterface) currently registered on the AppKit instance.
```ts
type UseCryptoOnrampProvidersReturnType = GetCryptoOnrampProvidersReturnType;
```
#### UseCryptoOnrampQuoteParameters [#usecryptoonrampquoteparameters]
Parameters accepted by [`useCryptoOnrampQuote`](#usecryptoonrampquote) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the source/target assets, amount and optional provider override forwarded to [`getCryptoOnrampQuote`](/applications/appkit/reference/appkit#getcryptoonrampquote).
| Field | Type | Description |
| ----------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount` | `string` | Amount to onramp (either source or target crypto, depending on isSourceAmount) |
| `sourceCurrencyAddress` | `string` | Source crypto currency address (contract address or 0x0... for native) |
| `sourceChain` | `string` | Source chain identifier in CAIP-2 format (e.g. 'eip155:1' for Ethereum mainnet, 'eip155:42161' for Arbitrum One). Providers map this to their own chain identifiers internally. |
| `targetCurrencyAddress` | `string` | Target crypto currency address on TON (contract address or 0x0... for native) |
| `recipientAddress` | `string` | TON address that will receive the target crypto. |
| `refundAddress` | `string` | Refund address for the source crypto. |
| `isSourceAmount` | `boolean` | If true, `amount` is the source amount to spend. If false, `amount` is the target amount to receive. Defaults to true when omitted. |
| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options. |
| `providerId` | `string` | Provider to quote against. Defaults to the registered default provider. |
| `query` | [`QueryOptionsOverride`](/applications/appkit/reference/appkit#queryoptionsoverride) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
#### UseCryptoOnrampQuoteReturnType [#usecryptoonrampquotereturntype]
Return type of [`useCryptoOnrampQuote`](#usecryptoonrampquote) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
```ts
type UseCryptoOnrampQuoteReturnType = UseQueryReturnType<
selectData,
GetCryptoOnrampQuoteErrorType
>;
```
#### UseCryptoOnrampStatusParameters [#usecryptoonrampstatusparameters]
Parameters accepted by [`useCryptoOnrampStatus`](#usecryptoonrampstatus) — TanStack Query options (`select`, `enabled`, `refetchInterval`, …) plus the deposit id, originating provider id and optional provider override forwarded to [`getCryptoOnrampStatus`](/applications/appkit/reference/appkit#getcryptoonrampstatus).
| Field | Type | Description |
| ------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `depositId` | `string` | Deposit id. |
| `providerId` | `string` | Identifier of the provider that issued this deposit. |
| `query` | [`QueryOptionsOverride`](/applications/appkit/reference/appkit#queryoptionsoverride) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
#### UseCryptoOnrampStatusReturnType [#usecryptoonrampstatusreturntype]
Return type of [`useCryptoOnrampStatus`](#usecryptoonrampstatus) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
```ts
type UseCryptoOnrampStatusReturnType = UseQueryReturnType<
selectData,
GetCryptoOnrampStatusErrorType
>;
```
### Jettons [#jettons-1]
#### UseJettonBalanceByAddressParameters [#usejettonbalancebyaddressparameters]
Parameters accepted by [`useJettonBalanceByAddress`](#usejettonbalancebyaddress) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the jetton master, owner address, decimals and optional network override.
| Field | Type | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jettonAddress` | UserFriendlyAddress UserFriendlyAddress Network UserFriendlyAddress Network UserFriendlyAddress UserFriendlyAddress Network UserFriendlyAddress \| AddressNetwork UserFriendlyAddress \| AddressNetwork ;
```
#### UseTransferJettonParameters [#usetransferjettonparameters]
Parameters accepted by [`useTransferJetton`](#usetransferjetton) — TanStack Query mutation options.
```ts
type UseTransferJettonParameters = TransferJettonOptions;
```
#### UseTransferJettonReturnType [#usetransferjettonreturntype]
Return type of [`useTransferJetton`](#usetransferjetton) — TanStack Query mutation result.
```ts
type UseTransferJettonReturnType = UseMutationReturnType<
TransferJettonData,
TransferJettonErrorType,
TransferJettonVariables,
context,
(
variables: TransferJettonVariables,
options?: MutateOptions,
) => void,
MutateFunction
>;
```
#### UseWatchJettonsByAddressParameters [#usewatchjettonsbyaddressparameters]
Parameters accepted by [`useWatchJettonsByAddress`](#usewatchjettonsbyaddress) — same fields as [`WatchJettonsByAddressOptions`](/applications/appkit/reference/appkit#watchjettonsbyaddressoptions), all optional so callers can render the hook before the address is known.
```ts
type UseWatchJettonsByAddressParameters = Partial;
```
#### UseWatchJettonsParameters [#usewatchjettonsparameters]
Parameters accepted by [`useWatchJettons`](#usewatchjettons) — update callback and optional network override. The hook resolves the address from the selected wallet.
```ts
type UseWatchJettonsParameters = Partial;
```
### NFTs [#nfts-2]
#### NftItemProps [#nftitemprops]
Props accepted by [`NftItem`](#nftitem) — extends the native `` props (`onClick`, `disabled`, `className`, …) with the NFT to render.
| Field | Type | Description |
| ------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `nft`\* | NFT UserFriendlyAddress \| AddressNetwork ;
```
#### UseNFTsParameters [#usenftsparameters]
Parameters accepted by [`useNfts`](#usenfts) — same shape as [`UseNFTsByAddressParameters`](#usenftsbyaddressparameters). The hook resolves `address` from the selected wallet and overrides any value supplied here.
| Field | Type | Description |
| --------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `address` | UserFriendlyAddress \| AddressNetwork ;
```
#### UseNftParameters [#usenftparameters]
Parameters accepted by [`useNft`](#usenft) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the NFT contract address and optional network override.
The `network` field defaults to the selected wallet's network. If no wallet is selected, falls back to AppKit's default network, or mainnet when none is set.
| Field | Type | Description |
| --------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `address` | UserFriendlyAddress \| AddressNetwork ;
```
#### UseTransferNftParameters [#usetransfernftparameters]
Parameters accepted by [`useTransferNft`](#usetransfernft) — TanStack Query mutation options.
```ts
type UseTransferNftParameters = TransferNftOptions;
```
#### UseTransferNftReturnType [#usetransfernftreturntype]
Return type of [`useTransferNft`](#usetransfernft) — TanStack Query mutation result.
```ts
type UseTransferNftReturnType = UseMutationReturnType<
TransferNftData,
TransferNftErrorType,
TransferNftVariables,
context,
(
variables: TransferNftVariables,
options?: MutateOptions,
) => void,
MutateFunction
>;
```
### Networks [#networks-1]
#### UseBlockNumberParameters [#useblocknumberparameters]
Parameters accepted by [`useBlockNumber`](#useblocknumber) — TanStack Query options plus an optional network override. Defaults to the selected wallet's network. If no wallet is selected, falls back to mainnet.
| Field | Type | Description |
| --------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `network` | Network ` | Translation dictionaries keyed by locale. Loaded into the underlying i18n instance on mount. |
### Settings [#settings-1]
#### AppKitTheme [#appkittheme]
Theme value accepted by [`useAppKitTheme`](#useappkittheme) — `'light'`, `'dark'`, or any custom string mapped to a `data-ta-theme` token in the host's CSS.
```ts
type AppKitTheme = 'light' | 'dark' | string;
```
### Shared [#shared-1]
#### AmountPreset [#amountpreset]
Single preset entry rendered as a button in [`AmountPresets`](#amountpresets).
| Field | Type | Description |
| ---------- | ------------ | ------------------------------------------------------------------------------------------------------ |
| `label`\* | `string` | Text shown inside the button (e.g., `"25%"`, `"Max"`, `"100"`). |
| `amount`\* | `string` | Value passed to [`AmountPresetsProps.onPresetSelect`](#amountpresetsprops) when the button is clicked. |
| `onSelect` | `() => void` | Optional custom click handler — when set, it runs instead of `onPresetSelect`. |
#### AmountPresetsProps [#amountpresetsprops]
Props accepted by [`AmountPresets`](#amountpresets).
| Field | Type | Description |
| ------------------ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `presets`\* | AmountPreset \[]Network LowBalanceMode OptionSwitcherOption \[]T = AppkitUIToken \[] | Full set of tokens available for selection and search. |
| `tokenSections` | TokenSectionConfig \[](token: T = AppkitUIToken ) => void | Called with the picked token. The modal closes and resets its search on selection. |
| `title`\* | `string` | Modal header title. |
| `searchPlaceholder` | `string` | Placeholder shown inside the search input. |
#### TokenSelectorProps [#tokenselectorprops]
Props accepted by [`TokenSelector`](#tokenselector) — extends the base [`Button`](#button) props.
| Field | Type | Description |
| -------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`\* | `string` | Label shown next to the icon — typically the token symbol. |
| `icon` | `string` | Token logo URL. |
| `iconFallback` | `string` | Single-character fallback used when `icon` fails to load. Defaults to the first character of `title`. |
| `networkIcon` | `string` | When provided, renders a network badge overlay on the icon. |
| `readOnly` | `boolean` | Hide chevron and suppress click handling — use when there's nothing to pick. |
| `size` | `ButtonSize` | Size class applied to the button. Pass `'unset'` to skip the size class entirely (no padding, no typography) — useful with `variant="unstyled"`. |
| `borderRadius` | `ButtonBorderRadius` | Border radius token. Defaults to a size-dependent value (`s` → `2xl`, `m` → `l`, `l` → `xl`). |
| `variant` | `ButtonVariant` | Visual variant. Use `'unstyled'` to opt out of all built-in styling — the consumer is fully responsible for visuals via `className`. The Button still provides ref forwarding, `disabled`/`loading` plumbing, and `icon`/`children` rendering. |
| `loading` | `boolean` | When true, renders a spinner instead of `icon`/`children` and disables the button. |
| `fullWidth` | `boolean` | When true, the button stretches to fill its container width. |
### Signing [#signing-1]
#### UseSignBinaryParameters [#usesignbinaryparameters]
Parameters accepted by [`useSignBinary`](#usesignbinary) — TanStack Query mutation options.
```ts
type UseSignBinaryParameters = SignBinaryOptions;
```
#### UseSignBinaryReturnType [#usesignbinaryreturntype]
Return type of [`useSignBinary`](#usesignbinary) — TanStack Query mutation result.
```ts
type UseSignBinaryReturnType = UseMutationResult<
SignBinaryData,
SignBinaryErrorType,
SignBinaryVariables,
context
>;
```
#### UseSignCellParameters [#usesigncellparameters]
Parameters accepted by [`useSignCell`](#usesigncell) — TanStack Query mutation options.
```ts
type UseSignCellParameters = SignCellOptions;
```
#### UseSignCellReturnType [#usesigncellreturntype]
Return type of [`useSignCell`](#usesigncell) — TanStack Query mutation result.
```ts
type UseSignCellReturnType = UseMutationResult<
SignCellData,
SignCellErrorType,
SignCellVariables,
context
>;
```
#### UseSignTextParameters [#usesigntextparameters]
Parameters accepted by [`useSignText`](#usesigntext) — TanStack Query mutation options.
```ts
type UseSignTextParameters = SignTextOptions;
```
#### UseSignTextReturnType [#usesigntextreturntype]
Return type of [`useSignText`](#usesigntext) — TanStack Query mutation result.
```ts
type UseSignTextReturnType = UseMutationResult<
SignTextData,
SignTextErrorType,
SignTextVariables,
context
>;
```
### Staking [#staking-2]
#### SelectUnstakeModeProps [#selectunstakemodeprops]
Props accepted by [`SelectUnstakeMode`](#selectunstakemode).
| Field | Type | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `value`\* | UnstakeModes (mode: UnstakeModes ) => void | Called when the user picks a different mode. |
| `providerInfo`\* | StakingProviderInfo \| undefinedStakingProviderMetadata \| undefinedStakingProviderMetadata \| undefinedStakingQuoteDirection StakingQuote \| undefinedStakingProviderInfo \| undefinedStakingProviderMetadata \| undefinedStakingProvider \| undefinedStakingProvider \[]Network \| undefinedStakingQuoteDirection StakingBalance \| undefinedUnstakeModes (mode: UnstakeModes ) => void | Sets the unstake mode |
| `sendTransaction`\* | `() => Promise` | Triggers the staking/unstaking transaction |
| `onChangeDirection`\* | (direction: StakingQuoteDirection ) => void | Changes the direction (stake/unstake) |
| `isSendingTransaction`\* | `boolean` | True while a transaction is being processed |
| `isReversed`\* | `boolean` | True if the user is inputting the output amount ("I want to get X") |
| `toggleReversed`\* | `() => void` | Toggles between inputting from amount and output amount |
| `reversedAmount`\* | `string` | Amount displayed in the reversed (bottom) input |
| `onMaxClick`\* | `() => void` | Sets the input amount to the maximum available balance (leaves room for TON gas on native stake) |
| `isLowBalanceWarningOpen`\* | `boolean` | True when the built transaction outflow exceeds the user's TON balance |
| `lowBalanceMode`\* | `'reduce' \| 'topup'` | `reduce` when the outgoing token is TON (user can fix by changing amount), `topup` otherwise. |
| `lowBalanceRequiredTon`\* | `string` | Required TON amount for the pending operation, formatted as a decimal string. Empty when no pending op. |
| `onLowBalanceChange`\* | `() => void` | Replace the input with a value that fits within the current TON balance and close the warning. |
| `onLowBalanceCancel`\* | `() => void` | Dismiss the low-balance warning without changing the input. |
#### StakingInfoProps [#stakinginfoprops]
Props accepted by [`StakingInfo`](#stakinginfo).
| Field | Type | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `quote`\* | StakingQuote \| undefinedStakingProviderInfo \| undefinedStakingProviderMetadata \| undefinedStakingQuoteDirection Network StakingProvider \| undefinedStakingProvider \[]Network ` props forwarded to the default UI.
| Field | Type | Description |
| ---------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children` |
(props: StakingWidgetRenderProps ) => ReactNode | Optional render-prop. When provided, the default [`StakingWidgetUI`](#stakingwidgetui) is bypassed and this function is called with the full [`StakingWidgetRenderProps`](#stakingwidgetrenderprops) (context state + forwarded `
` props), letting consumers build a custom UI on top of the widget's internal logic. |
| `network` |