UserFriendlyAddress \| Address | Wallet address — pass a [`UserFriendlyAddress`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) string or an `Address` instance from `@ton/core`. |
| `parameters.network` | Network | Network to read the balance from. 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. |
| `parameters.query` | [`QueryOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
Returns: UseBalanceReturnType\ — TanStack Query result for the balance read.
**Example**
```tsx
const { data: balance, isLoading, error } = useBalance();
if (isLoading) {
return UserFriendlyAddress \| Address | Wallet address — pass a [`UserFriendlyAddress`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) string or an `Address` instance from `@ton/core`. |
| `parameters.network` | Network | Network to read the balance from. 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. |
| `parameters.query` | [`QueryOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
Returns: UseBalanceByAddressReturnType\ — TanStack Query result for the balance read.
**Example**
```tsx
const {
data: balance,
isLoading,
error,
} = useBalanceByAddress({
address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
});
if (isLoading) {
return (update: BalanceUpdate) => void | Callback fired on every balance update from the streaming provider. |
| `parameters.network` | Network | Network to watch on. 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. |
Returns: `void`.
**Example**
```tsx
const { data: balance } = useBalance();
useWatchBalance();
return UserFriendlyAddress \| Address | Wallet address — pass a [`UserFriendlyAddress`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) string or an `Address` instance from `@ton/core`. |
| `parameters.network` | Network | Network to watch on. 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. |
| `parameters.onChange` | (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 Connector | undefined — The matching [`Connector`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md), or `undefined` if none with that ID is registered.
#### `useConnectors` [#useconnectors]
Read the list of connectors registered on this AppKit instance. Updates when a connector is registered or unregistered (use [`useConnectedWallets`](#useconnectedwallets) to react to wallet connect/disconnect events).
Returns: UseConnectorsReturnType — Read-only array of registered [`Connector`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md)s.
### Crypto on-ramp [#crypto-on-ramp]
#### `useCreateCryptoOnrampDeposit` [#usecreatecryptoonrampdeposit]
Create a crypto-onramp deposit from a quote previously obtained via [`useCryptoOnrampQuote`](#usecryptoonrampquote). Call `mutate(options)` where `options` matches [`CreateCryptoOnrampDepositOptions`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) (quote, refund address, optional provider override). On success, `data` is the [`CryptoOnrampDeposit`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) carrying the address and amount the user must send on the source chain to complete the onramp. Pair with [`useCryptoOnrampStatus`](#usecryptoonrampstatus) to poll the deposit until it settles.
| Parameter | Type | Description |
| --------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseCreateCryptoOnrampDepositParameters`](#usecreatecryptoonrampdepositparameters) | TanStack Query mutation overrides (`parameters.mutation`). |
| `parameters.mutation` | [`MutationOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query mutation options forwarded to `useMutation` (`onSuccess`, `onError`, `onMutate`, `retry`, …). `mutationFn`, `mutationKey` and `throwOnError` are managed by the wrapper. |
Returns: UseCreateCryptoOnrampDepositReturnType\ — Mutation result for the deposit call.
#### `useCryptoOnrampContext` [#usecryptoonrampcontext]
Reads the `CryptoOnrampContext` populated by [`CryptoOnrampWidgetProvider`](#cryptoonrampwidgetprovider) — returns the widget's selection state, quote/deposit data and actions ([`CryptoOnrampContextType`](#cryptoonrampcontexttype)).
Returns: CryptoOnrampContextType.
#### `useCryptoOnrampProvider` [#usecryptoonrampprovider]
Read and change the default crypto-onramp provider. The hook takes no parameters and returns a `[provider, setProviderId]` tuple. `provider` is `undefined` when no default provider is registered.
Returns: UseCryptoOnrampProviderReturnType.
#### `useCryptoOnrampProviders` [#usecryptoonrampproviders]
List every crypto-onramp provider registered on the AppKit instance (both those passed via [`AppKitConfig`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md)'s `providers` and those added later through [`registerProvider`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md)). Subscribes to [`watchCryptoOnrampProviders`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) and re-reads via [`getCryptoOnrampProviders`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) so the array stays in sync.
Returns: UseCryptoOnrampProvidersReturnType — Array of registered crypto-onramp providers.
#### `useCryptoOnrampQuote` [#usecryptoonrampquote]
Quote a crypto-to-TON onramp — given a source asset/chain and the target TON asset, returns the rate, expected amount and the provider-specific metadata required to feed [`useCreateCryptoOnrampDeposit`](#usecreatecryptoonrampdeposit). `data` is the [`CryptoOnrampQuote`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) payload.
| Parameter | Type | Description |
| ---------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseCryptoOnrampQuoteParameters`](#usecryptoonrampquoteparameters) | Quote inputs and TanStack Query overrides. |
| `parameters.amount` | `string` | Amount to onramp (either source or target crypto, depending on isSourceAmount) |
| `parameters.sourceCurrencyAddress` | `string` | Source crypto currency address (contract address or 0x0... for native) |
| `parameters.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. |
| `parameters.targetCurrencyAddress` | `string` | Target crypto currency address on TON (contract address or 0x0... for native) |
| `parameters.recipientAddress` | `string` | TON address that will receive the target crypto. |
| `parameters.refundAddress` | `string` | Refund address for the source crypto. |
| `parameters.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. |
| `parameters.providerOptions` | `TProviderOptions = unknown` | Provider-specific options. |
| `parameters.providerId` | `string` | Provider to quote against. Defaults to the registered default provider. |
| `parameters.query` | [`QueryOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
Returns: UseCryptoOnrampQuoteReturnType\ — TanStack Query result for the quote read.
#### `useCryptoOnrampStatus` [#usecryptoonrampstatus]
Read the current status of a crypto-onramp deposit previously created via [`useCreateCryptoOnrampDeposit`](#usecreatecryptoonrampdeposit). Typically polled via `refetchInterval` until `data` reaches a terminal state — `'success'` (delivered to the recipient) or `'failed'` (provider could not complete the deposit).
| Parameter | Type | Description |
| ----------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseCryptoOnrampStatusParameters`](#usecryptoonrampstatusparameters) | Deposit ID, originating provider ID and TanStack Query overrides. |
| `parameters.depositId` | `string` | Deposit ID. |
| `parameters.providerId` | `string` | Identifier of the provider that issued this deposit. |
| `parameters.query` | [`QueryOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
Returns: UseCryptoOnrampStatusReturnType\ — TanStack Query result for the status read.
### Jettons [#jettons]
#### `useJettonBalanceByAddress` [#usejettonbalancebyaddress]
React hook reading a jetton balance for a given owner through TanStack Query — derives the owner's jetton-wallet address from the master and formats the balance using the supplied decimals.
| Parameter | Type | Description |
| --------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseJettonBalanceByAddressParameters`](#usejettonbalancebyaddressparameters) | Jetton master, owner address, decimals, optional network override and TanStack Query overrides. |
| `parameters.jettonAddress` | UserFriendlyAddress | Jetton master contract address (the token, not the user's wallet for it). |
| `parameters.ownerAddress` | UserFriendlyAddress | Owner of the jetton wallet — typically the connected user's address. |
| `parameters.jettonDecimals` | `number` | Decimals declared by the jetton master. Used to format the raw balance into a human-readable string. |
| `parameters.network` | Network | Network to read the balance from. 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. |
| `parameters.query` | [`QueryOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
Returns: UseJettonBalanceByAddressReturnType\ — TanStack Query result for the jetton balance read.
**Example**
```tsx
const {
data: balance,
isLoading,
error,
} = useJettonBalanceByAddress({
ownerAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
jettonAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiXme1Xc56Iwobkzgnjj',
});
if (isLoading) {
return UserFriendlyAddress | Jetton master contract address whose metadata is being fetched. |
| `parameters.network` | Network | Network to query. 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. |
| `parameters.query` | [`QueryOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
Returns: UseJettonInfoReturnType\ — TanStack Query result for the jetton info read.
**Example**
```tsx
const {
data: info,
isLoading,
error,
} = useJettonInfo({
address: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiXme1Xc56Iwobkzgnjj',
});
if (isLoading) {
return Name: {info?.name}
Symbol: {info?.symbol}
Decimals: {info?.decimals}
UserFriendlyAddress | Jetton master contract address. |
| `parameters.ownerAddress` | UserFriendlyAddress | Owner whose jetton wallet should be derived. |
| `parameters.network` | Network | Network to query. 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. |
| `parameters.query` | [`QueryOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
Returns: `UseQueryReturnTypeUserFriendlyAddress \| Address | Owner address — pass a [`UserFriendlyAddress`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) string or an `Address` instance from `@ton/core`. |
| `parameters.network` | Network | Network to read the jettons from. 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. |
| `parameters.limit` | `number` | Maximum number of jettons to return. |
| `parameters.offset` | `number` | Number of jettons to skip before returning results — used for pagination. |
| `parameters.query` | [`QueryOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
Returns: UseJettonsReturnType\ — TanStack Query result for the jettons list.
**Example**
```tsx
const { data: jettons, isLoading, error } = useJettons();
if (isLoading) {
return UserFriendlyAddress \| Address | Owner address — pass a [`UserFriendlyAddress`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) string or an `Address` instance from `@ton/core`. |
| `parameters.network` | Network | Network to read the jettons from. 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. |
| `parameters.limit` | `number` | Maximum number of jettons to return. |
| `parameters.offset` | `number` | Number of jettons to skip before returning results — used for pagination. |
| `parameters.query` | [`QueryOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
Returns: UseJettonsByAddressReturnType\ — TanStack Query result for the jettons list.
**Example**
```tsx
const {
data: jettons,
isLoading,
error,
} = useJettonsByAddress({
address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
});
if (isLoading) {
return UseTransferJettonReturnType\ — Mutation result for the jetton transfer call.
**Example**
```tsx
const { mutate: transfer, isPending, error } = useTransferJetton();
const handleTransfer = () => {
transfer({
recipientAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
amount: '100', // 100 USDT
jettonAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
jettonDecimals: 6,
});
};
return (
(update: JettonUpdate) => void | Callback fired on every jetton-balance update from the streaming provider. |
| `parameters.network` | Network | Network to watch on. Defaults to the selected wallet's network. |
Returns: `void`.
**Example**
```tsx
const { data: jettons } = useJettons();
useWatchJettons();
return (
UserFriendlyAddress \| Address | Owner address — pass a [`UserFriendlyAddress`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) string or an `Address` instance from `@ton/core`. |
| `parameters.onChange` | (update: JettonUpdate) => void | Callback fired on every jetton-balance update from the streaming provider. |
| `parameters.network` | Network | Network to watch on. 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. |
Returns: `void`.
**Example**
```tsx
const address = 'UQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJKZ';
const { data: jettons } = useJettonsByAddress({ address });
useWatchJettonsByAddress({ address });
return (
UserFriendlyAddress \| Address | NFT contract address — pass a [`UserFriendlyAddress`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) string or an `Address` instance from `@ton/core`. |
| `parameters.network` | Network | Network to query. 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. |
| `parameters.query` | [`QueryOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
Returns: UseNftReturnType\ — TanStack Query result for the NFT read.
**Example**
```tsx
const {
data: nft,
isLoading,
error,
} = useNft({
address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
});
if (isLoading) {
return Name: {nft?.info?.name}
Collection: {nft?.collection?.name}
Owner: {nft?.ownerAddress}
UserFriendlyAddress \| Address | Owner address — pass a [`UserFriendlyAddress`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) string or an `Address` instance from `@ton/core`. |
| `parameters.network` | Network | Network to read NFTs from. 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. |
| `parameters.limit` | `number` | Maximum number of NFTs to return. |
| `parameters.offset` | `number` | Number of NFTs to skip before returning results — used for pagination. |
| `parameters.query` | [`QueryOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
Returns: UseNFTsReturnType\ — TanStack Query result for the NFTs read.
**Example**
```tsx
const {
data: nfts,
isLoading,
error,
} = useNfts({
limit: 10,
});
if (isLoading) {
return UserFriendlyAddress \| Address | Owner address — pass a [`UserFriendlyAddress`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) string or an `Address` instance from `@ton/core`. |
| `parameters.network` | Network | Network to read NFTs from. 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. |
| `parameters.limit` | `number` | Maximum number of NFTs to return. |
| `parameters.offset` | `number` | Number of NFTs to skip before returning results — used for pagination. |
| `parameters.query` | [`QueryOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
Returns: UseNFTsByAddressReturnType\ — TanStack Query result for the NFTs read.
**Example**
```tsx
const {
data: nfts,
isLoading,
error,
} = useNftsByAddress({
address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
limit: 10,
});
if (isLoading) {
return UseTransferNftReturnType\ — Mutation result for the transfer call.
**Example**
```tsx
const { mutate: transfer, isPending, error } = useTransferNft();
const handleTransfer = () => {
transfer({
nftAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
recipientAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
comment: 'Gift for you',
});
};
return (
Network | Network to query. Defaults to mainnet when omitted. |
| `parameters.query` | [`QueryOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
Returns: UseBlockNumberReturnType\ — TanStack Query result for the seqno read.
#### `useDefaultNetwork` [#usedefaultnetwork]
Read and write AppKit's default network — the network connectors use for new wallet connections. Returns a `useState`-style tuple. The read side updates when the default changes through any source (this hook, [`setDefaultNetwork`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md), manager events).
Returns: UseDefaultNetworkReturnType — Tuple `[network, setNetwork]`.
#### `useNetwork` [#usenetwork]
Read the [`Network`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) the selected wallet is connected to. Updates when the wallet's network changes (e.g. user switches mainnet/testnet inside the wallet).
Returns: UseNetworkReturnType — Selected wallet's network, or `undefined` when no wallet is selected.
#### `useNetworks` [#usenetworks]
Read the list of networks configured on AppKit. Updates when [`AppKitNetworkManager`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) adds, replaces or drops a network.
Returns: UseNetworksReturnType — Array of configured [`Network`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md)s.
### Settings [#settings]
#### `useAppKit` [#useappkit]
Read the [`AppKit`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) instance hosted by [`AppKitProvider`](#appkitprovider). Throws when the hook is rendered outside the provider tree.
Returns: AppKit — The AppKit instance shared with descendant hooks/components.
#### `useAppKitTheme` [#useappkittheme]
State hook that mirrors the active `@ton/appkit-react` theme to `document.body[data-ta-theme]` — returns a `[theme, setTheme]` tuple just like `useState`.
Returns: `readonly [string, DispatchI18nContextType — The i18n context ([`I18nContextType`](#i18ncontexttype)) with `activeLocale`, `t`, `locale` and `addDict`.
### Signing [#signing]
#### `useSignBinary` [#usesignbinary]
Ask the selected wallet to sign an opaque binary blob (Base64-encoded), without on-chain structure. Call `mutate` from an event handler with the `bytes` to sign and an optional `network` override. On success, `data` carries the signature plus the signer address, timestamp and dApp domain the wallet bound to the signature. Throws `Error('Wallet not connected')` if no wallet is currently selected — TanStack Query surfaces it via the mutation's `error`.
| Parameter | Type | Description |
| --------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseSignBinaryParameters`](#usesignbinaryparameters) | TanStack Query mutation overrides. |
| `parameters.mutation` | [`MutationOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query mutation options forwarded to `useMutation` (`onSuccess`, `onError`, `onMutate`, `retry`, …). `mutationFn`, `mutationKey` and `throwOnError` are managed by the wrapper. |
Returns: UseSignBinaryReturnType\ — Mutation result for the signing call.
#### `useSignCell` [#usesigncell]
Ask the selected wallet to sign a TON cell — typically so the signature can later be verified on-chain by a contract. Call `mutate` from an event handler with the `cell` content, a TL-B-style `schema` (used by the wallet to render the payload to the user before signing) and an optional `network` override. On success, `data` carries the signature plus the signer address, timestamp and dApp domain. Throws `Error('Wallet not connected')` if no wallet is currently selected — TanStack Query surfaces it via the mutation's `error`.
| Parameter | Type | Description |
| --------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseSignCellParameters`](#usesigncellparameters) | TanStack Query mutation overrides. |
| `parameters.mutation` | [`MutationOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query mutation options forwarded to `useMutation` (`onSuccess`, `onError`, `onMutate`, `retry`, …). `mutationFn`, `mutationKey` and `throwOnError` are managed by the wrapper. |
Returns: UseSignCellReturnType\ — Mutation result for the signing call.
#### `useSignText` [#usesigntext]
Ask the selected wallet to sign a plain-text message — useful for off-chain login proofs and signed challenges. Call `mutate` from an event handler with the `text` to sign and an optional `network` override. On success, `data` carries the signature plus the canonicalized signer address, timestamp and dApp domain the wallet bound to the signature. Throws `Error('Wallet not connected')` if no wallet is currently selected — TanStack Query surfaces it via the mutation's `error`.
| Parameter | Type | Description |
| --------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseSignTextParameters`](#usesigntextparameters) | TanStack Query mutation overrides. |
| `parameters.mutation` | [`MutationOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query mutation options forwarded to `useMutation` (`onSuccess`, `onError`, `onMutate`, `retry`, …). `mutationFn`, `mutationKey` and `throwOnError` are managed by the wrapper. |
Returns: UseSignTextReturnType\ — Mutation result for the signing call.
### Staking [#staking]
#### `useBuildStakeTransaction` [#usebuildstaketransaction]
Build a stake/unstake [`TransactionRequest`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) from a [`StakingQuote`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) (obtained via [`useStakingQuote`](#usestakingquote)) without sending it — lets the UI inspect, batch, or pass the request to [`useSendTransaction`](#usesendtransaction) separately. Call `mutate(params)` where `params` matches [`BuildStakeTransactionOptions`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) (quote + user address, optional provider override). The resulting `TransactionRequest` is in `data` once the mutation resolves.
Returns: UseBuildStakeTransactionReturnType\ — Mutation result for the build call.
#### `useStakedBalance` [#usestakedbalance]
React hook reading a user's staked balance from a staking provider through TanStack Query — total staked plus, depending on the provider, any instant-unstake balance available right now. 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.
| Parameter | Type | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseStakedBalanceParameters`](#usestakedbalanceparameters) | Owner address, optional `providerId`, optional network override, and TanStack Query overrides. |
| `parameters.userAddress` | UserFriendlyAddress | Owner whose staked balance should be read. |
| `parameters.network` | Network | Network to query. 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. |
| `parameters.providerId` | `string` | Provider to query. Defaults to the registered default staking provider. |
| `parameters.query` | [`QueryOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
Returns: UseStakedBalanceReturnType\ — TanStack Query result for the staked-balance read.
#### `useStakingContext` [#usestakingcontext]
Reads the [`StakingContextType`](#stakingcontexttype) from the nearest [`StakingWidgetProvider`](#stakingwidgetprovider) (or [`StakingWidget`](#stakingwidget)). Outside a provider, returns the default context (empty inputs, no-op actions) so a custom UI can still mount without crashing.
Returns: StakingContextType.
#### `useStakingProvider` [#usestakingprovider]
React hook returning a registered staking provider. Subscribes to provider-registry changes via [`watchStakingProviders`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) and looks up by `id`, or returns the registered default when no ID is given. Returns `undefined` when no provider matches and no default has been registered (where the underlying [`getStakingProvider`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) action would throw).
| Parameter | Type | Description |
| --------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `parameters` | [`GetStakingProviderOptions`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | Optional provider ID. |
| `parameters.id` | `string` | Provider ID to look up. When omitted, returns the registered default staking provider. |
Returns: UseStakingProviderReturnType — Matching staking provider instance, or `undefined` when none resolves.
#### `useStakingProviderInfo` [#usestakingproviderinfo]
React hook reading live staking-pool info for a provider through TanStack Query — APY, instant-unstake liquidity and (for liquid staking) the current exchange rate. Use [`useStakingProviderMetadata`](#usestakingprovidermetadata) for static metadata (name, stake/receive tokens, supported unstake modes). 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.
| Parameter | Type | Description |
| ----------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseStakingProviderInfoParameters`](#usestakingproviderinfoparameters) | Optional `providerId`, network override, and TanStack Query overrides. |
| `parameters.network` | Network | Network whose staking pool should be inspected. 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. |
| `parameters.providerId` | `string` | Provider to query. Defaults to the registered default staking provider. |
| `parameters.query` | [`QueryOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
Returns: UseStakingProviderInfoReturnType\ — TanStack Query result for the live provider info.
#### `useStakingProviderMetadata` [#usestakingprovidermetadata]
Read static metadata for a staking provider — display name, stake/receive tokens, supported unstake modes and contract address. Returns `undefined` when no provider matches and no default is registered. Use [`useStakingProviderInfo`](#usestakingproviderinfo) for live values (APY, instant-unstake liquidity, exchange rate). 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.
| Parameter | Type | Description |
| ----------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseStakingProviderMetadataParameters`](#usestakingprovidermetadataparameters) | Optional `providerId` and network override. |
| `parameters.network` | Network | Network whose provider metadata should be read. 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. |
| `parameters.providerId` | `string` | Provider to query. Defaults to the registered default staking provider. |
Returns: StakingProviderMetadata | undefined — Static [`StakingProviderMetadata`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md), or `undefined` when the provider can't be resolved.
#### `useStakingProviders` [#usestakingproviders]
React hook returning every staking provider registered on the AppKit instance (both those passed via config and those added later). Subscribes to provider-registry changes via [`watchStakingProviders`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md).
Returns: UseStakingProvidersReturnType — Array of registered staking providers.
#### `useStakingQuote` [#usestakingquote]
Quote a stake or unstake — given an amount, direction (`'stake'` / `'unstake'`) and the target asset, returns the rate, expected output and the provider-specific metadata required to feed [`useBuildStakeTransaction`](#usebuildstaketransaction). `data` is the [`StakingQuote`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) payload. 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.
| Parameter | Type | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `parameters` | [`UseStakingQuoteParameters`](#usestakingquoteparameters) | Quote parameters, optional `providerId`, optional network override, and TanStack Query overrides. |
| `parameters.direction` | StakingQuoteDirection | Direction of the quote (stake or unstake) |
| `parameters.amount` | `string` | Amount of tokens to stake or unstake. |
| `parameters.userAddress` | UserFriendlyAddress | Address of the user. |
| `parameters.network` | Network | Network on which the staking will be executed. |
| `parameters.unstakeMode` | UnstakeModes | Unstake-timing mode the quote should target — see [`UnstakeMode`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) for the supported flavours (`'INSTANT'`, `'WHEN_AVAILABLE'`, `'ROUND_END'`). Only meaningful when `direction === 'unstake'` and the provider lists the mode in `supportedUnstakeModes`. |
| `parameters.isReversed` | `boolean` | If true, for unstake requests the amount is specified in the staking coin (e.g. GRAM) instead of the Liquid Staking Token (e.g. tsTON). |
| `parameters.providerOptions` | `TProviderOptions = unknown` | Provider-specific options. |
| `parameters.providerId` | `string` | Provider to quote against. Defaults to the registered default staking provider. |
| `parameters.query` | [`QueryOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
Returns: UseStakingQuoteReturnType\ — TanStack Query result for the quote read.
### Swap [#swap]
#### `useBuildSwapTransaction` [#usebuildswaptransaction]
Build a swap [`TransactionRequest`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) from a [`SwapQuote`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) (obtained via [`useSwapQuote`](#useswapquote)) without sending it — lets the UI inspect, batch, or pass the request to [`useSendTransaction`](#usesendtransaction) separately. Call `mutate(params)` where `params` matches [`BuildSwapTransactionOptions`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) (quote, user address, optional slippage/deadline overrides). The resulting `TransactionRequest` is in `data` once the mutation resolves.
| Parameter | Type | Description |
| --------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseBuildSwapTransactionParameters`](#usebuildswaptransactionparameters) | TanStack Query mutation overrides. |
| `parameters.mutation` | [`MutationOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query mutation options forwarded to `useMutation` (`onSuccess`, `onError`, `onMutate`, `retry`, …). `mutationFn`, `mutationKey` and `throwOnError` are managed by the wrapper. |
Returns: UseBuildSwapTransactionReturnType\ — Mutation result for the build call.
#### `useSwapContext` [#useswapcontext]
Reads the [`SwapContextType`](#swapcontexttype) populated by the nearest [`SwapWidgetProvider`](#swapwidgetprovider) (or the [`SwapWidget`](#swapwidget) that mounts one). Outside a provider it returns the no-op default value.
Returns: SwapContextType.
#### `useSwapProvider` [#useswapprovider]
Read and switch the default swap provider — subscribes to [`watchSwapProviders`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) and re-reads via [`getSwapProvider`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md). Returns a `useState`-style tuple. The read swallows the throw from [`getSwapProvider`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) (which throws when no provider matches — or when no ID is passed and no default has been registered) and yields `undefined` instead.
Returns: UseSwapProviderReturnType — Tuple `[provider, setProviderId]`.
#### `useSwapProviders` [#useswapproviders]
List every swap provider registered on the AppKit instance (both those passed via [`AppKitConfig`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md)'s `providers` and those added later through [`registerProvider`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md)). Subscribes to [`watchSwapProviders`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) and re-reads via [`getSwapProviders`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) so the array stays in sync.
Returns: UseSwapProvidersReturnType — Array of registered swap providers.
#### `useSwapQuote` [#useswapquote]
Quote a swap — given source/target tokens and an amount, returns the rate, expected output and the provider-specific metadata required to feed [`useBuildSwapTransaction`](#usebuildswaptransaction). `data` is the [`SwapQuote`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) payload. 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.
| Parameter | Type | Description |
| -------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseSwapQuoteParameters`](#useswapquoteparameters) | Source and target tokens, amount, optional network/provider override, and TanStack Query overrides. |
| `parameters.amount` | `string` | Amount of tokens to swap (incoming or outgoing depending on isReverseSwap) |
| `parameters.from` | SwapToken | Token to swap from. |
| `parameters.to` | SwapToken | Token to swap to. |
| `parameters.network` | Network | Network on which the swap will be executed. |
| `parameters.slippageBps` | `number` | Slippage tolerance in basis points (1 `bp` = 0.01%) |
| `parameters.maxOutgoingMessages` | `number` | Maximum number of outgoing messages |
| `parameters.providerOptions` | `TProviderOptions = unknown` | Provider-specific options. |
| `parameters.isReverseSwap` | `boolean` | If true, amount is the amount to receive (buy). If false, amount is the amount to spend (sell). |
| `parameters.providerId` | `string` | Provider to quote against. Defaults to the registered default swap provider. |
| `parameters.query` | [`QueryOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …). `queryKey` and `queryFn` are managed by the wrapper. |
Returns: UseSwapQuoteReturnType\ — TanStack Query result for the swap quote.
### Transactions [#transactions]
#### `useSendTransaction` [#usesendtransaction]
Hand a pre-built [`TransactionRequest`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) to the selected wallet for signing and broadcast — typically the second step after a `buildX` / `createX` action (e.g. [`useBuildSwapTransaction`](#usebuildswaptransaction), [`useBuildStakeTransaction`](#usebuildstaketransaction)) produces the request. Call `mutate(request)`. 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` | [`UseSendTransactionParameters`](#usesendtransactionparameters) | TanStack Query mutation overrides. |
| `parameters.mutation` | [`MutationOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query mutation options forwarded to `useMutation` (`onSuccess`, `onError`, `onMutate`, `retry`, …). `mutationFn`, `mutationKey` and `throwOnError` are managed by the wrapper. |
Returns: UseSendTransactionReturnType\ — Mutation result for the send call.
#### `useTransactionStatus` [#usetransactionstatus]
Poll the status of a sent transaction by its BoC or normalized hash. In TON, a single external message triggers a tree of internal messages, so the transaction is `'completed'` only once the entire trace finishes — pair with `refetchInterval` to keep polling until `data.status` is `'completed'` or `'failed'`. Pass either `boc` or `normalizedHash` (not both). The underlying action throws `Error('Either boc or normalizedHash must be provided')` when neither is supplied — TanStack Query surfaces it via the query's `error`.
| Parameter | Type | Description |
| -------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `parameters`\* | [`UseTransactionStatusParameters`](#usetransactionstatusparameters) | `boc` xor `normalizedHash`, optional network and TanStack Query overrides. |
Returns: UseTransactionStatusReturnType\ — TanStack Query result for the status read.
#### `useTransferTon` [#usetransferton]
Send Gram from the selected wallet in one step — builds the transfer message, hands it to the wallet for signing and broadcasts it. Call `mutate` with a `recipientAddress`, an `amount` (in Gram as a human-readable decimal, converted to nanograms internally) and any of the optional `comment` / `payload` / `stateInit` fields. On success, `data` carries the BoC and normalized hash of the broadcast transaction — pair with [`useTransactionStatus`](#usetransactionstatus) to poll the trace to completion. Throws `Error('Wallet not connected')` if no wallet is currently selected — TanStack Query surfaces it via the mutation's `error`.
| Parameter | Type | Description |
| --------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | [`UseTransferTonParameters`](#usetransfertonparameters) | TanStack Query mutation overrides. |
| `parameters.mutation` | [`MutationOptionsOverride`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) | TanStack Query mutation options forwarded to `useMutation` (`onSuccess`, `onError`, `onMutate`, `retry`, …). `mutationFn`, `mutationKey` and `throwOnError` are managed by the wrapper. |
Returns: UseTransferTonReturnType\ — Mutation result for the transfer call.
#### `useWatchTransactions` [#usewatchtransactions]
Subscribe to incoming-transaction events for the currently selected wallet (use [`useWatchTransactionsByAddress`](#usewatchtransactionsbyaddress) for a fixed address). Auto-rebinds when the user connects, switches or disconnects. Requires a streaming provider registered for the network — the hook exits silently with a console warning when none is configured.
| Parameter | Type | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| `parameters` | [`UseWatchTransactionsParameters`](#usewatchtransactionsparameters) | Update callback. |
| `parameters.onChange` | (update: TransactionsUpdate) => void | Callback fired on every transactions update from the streaming provider. |
Returns: `void`.
**Example**
```tsx
const [lastUpdate, setLastUpdate] = useStateUserFriendlyAddress \| Address | Address to watch — pass a [`UserFriendlyAddress`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) string or an `Address` instance from `@ton/core`. |
| `parameters.onChange` | (update: TransactionsUpdate) => void | Callback fired on every transactions update from the streaming provider. |
| `parameters.network` | Network | Network to watch on. 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. |
Returns: `void`.
**Example**
```tsx
const address = 'UQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJKZ';
const [lastUpdate, setLastUpdate] = useStateUseAddressReturnType — Selected wallet's address, or `undefined` when none is selected.
#### `useConnect` [#useconnect]
Open a registered connector's connection flow (e.g., the TON Connect modal) and await its completion. Call `mutate` from a Connect button with the `connectorId` of the connector to drive. Once the user finishes the flow the new wallet becomes available via [`useSelectedWallet`](#useselectedwallet) / [`useConnectedWallets`](#useconnectedwallets). Throws `Error('Connector with ID "UseConnectReturnType\ — Mutation result for the connect call.
#### `useConnectedWallets` [#useconnectedwallets]
Read the list of currently connected wallets across all registered connectors. Updates when a wallet connects or disconnects.
Returns: UseConnectedWalletsReturnType — Read-only array of [`WalletInterface`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md)s.
#### `useDisconnect` [#usedisconnect]
Tear down the session on a registered connector, disconnecting whichever wallet it currently holds. Call `mutate` from a Log out / Disconnect button with the `connectorId` of the connector to tear down. Once it resolves the wallet drops out of [`useSelectedWallet`](#useselectedwallet) / [`useConnectedWallets`](#useconnectedwallets). Throws `Error('Connector with ID "UseDisconnectReturnType\ — Mutation result for the disconnect call.
#### `useSelectedWallet` [#useselectedwallet]
Read and switch the wallet that AppKit treats as active — most action hooks ([`useBalance`](#usebalance), [`useSignText`](#usesigntext), [`useTransferTon`](#usetransferton)) target this wallet implicitly. Returns a `useState`-style tuple.
Returns: UseSelectedWalletReturnType — Tuple `[wallet, setWalletId]`.
## Component [#component]
### Balances [#balances-1]
#### `SendJettonButton` [#sendjettonbutton]
Pre-wired button that builds a jetton transfer with [`createTransferJettonTransaction`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) and dispatches it through the standard `Send` flow on click — disabled until `recipientAddress`, `amount`, `jetton.address` and `jetton.decimals` are all set. Throws inside the click handler when `jetton.address` or `jetton.decimals` is missing.
| Prop | 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`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) (BoC + normalized hash). |
**Example**
```tsx
return (
(response: SendTransactionReturnType) => void | Called once the transaction is broadcast. Receives the wallet's [`SendTransactionReturnType`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit/content.md) (BoC + normalized hash). |
**Example**
```tsx
return (
(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 `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 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 GRAM 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 AppKit | Runtime instance constructed at app startup. Shared across every `@ton/appkit-react` hook and component. |
**Example**
```tsx
return (
AmountPreset\[] | Preset buttons to render, in order. |
| `currencySymbol` | `string` | Optional symbol (e.g., `"$"`) prepended to each preset label. |
| `onPresetSelect`\* | `(value: string) => void` | Called with the selected preset's `amount` unless the preset defines its own `onSelect`. |
**Example**
```tsx
return (