AppKit

Action

Balances

getBalance

Read the Toncoin balance of the currently selected wallet, returning null when no wallet is selected (use getBalanceByAddress for an arbitrary address).

Returns: Promise<GetBalanceReturnType> — Balance in TON as a human-readable decimal string, or null when no wallet is selected.

Example

const balance = await getBalance(appKit);
if (balance) {
    console.log('Balance:', balance);
}

getBalanceByAddress

Read the Toncoin balance of an arbitrary address — useful for wallets that aren't selected in AppKit (use getBalance for the selected wallet).

Returns: Promise<GetBalanceByAddressReturnType> — Balance in TON as a human-readable decimal string.

Example

const balanceByAddress = await getBalanceByAddress(appKit, {
    address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
});
console.log('Balance by address:', balanceByAddress);

watchBalance

Subscribe to Toncoin balance updates for the currently selected wallet, automatically rebinding whenever the selected wallet changes or the connected-wallets list updates (use watchBalanceByAddress for a fixed address). Requires a streaming provider registered for the network — call throws when none is configured. Use hasStreamingProvider to check first.

Returns: WatchBalanceReturnType — Unsubscribe function — call it to stop receiving updates.

Example

const unsubscribe = watchBalance(appKit, {
    onChange: (update) => {
        console.log('Balance updated:', update.balance);
    },
});

// Later: unsubscribe();

watchBalanceByAddress

Subscribe to Toncoin balance updates for an arbitrary address — useful for monitoring wallets that aren't selected in AppKit (use watchBalance for the selected wallet). Requires a streaming provider registered for the network — call throws when none is configured. Use hasStreamingProvider to check first.

Returns: WatchBalanceByAddressReturnType — Unsubscribe function — call it to stop receiving updates.

Example

const unsubscribe = watchBalanceByAddress(appKit, {
    address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
    onChange: (update) => {
        console.log('Balance by address updated:', update.balance);
    },
});

// Later: unsubscribe();

Client

getApiClient

Read the ApiClient configured for a specific Network — throws when the network has no client registered.

Returns: GetApiClientReturnType — The configured ApiClient for the requested network.

Example

const apiClient = getApiClient(appKit, {
    network: Network.mainnet(),
});

console.log('API Client:', apiClient);

Connectors

addConnector

Register a wallet connector at runtime — equivalent to passing it via AppKitConfig's connectors at construction, but available after AppKit is up.

Returns: AddConnectorReturnType — Function that unregisters the connector when called.

Example

const unregister = addConnector(
    appKit,
    createTonConnectConnector({
        tonConnectOptions: {
            manifestUrl: 'https://tonconnect-sdk-demo-dapp.vercel.app/tonconnect-manifest.json',
        },
    }),
);

// Later: unregister();

connect

Trigger the connection flow on a registered connector by id — drives it against AppKit's default network (set via setDefaultNetwork). Throws when no connector with that id exists.

Returns: Promise<ConnectReturnType> — Resolves once the connector's connect flow completes. If a wallet was successfully connected, it becomes available via getSelectedWallet.

Example

await connect(appKit, {
    connectorId: 'tonconnect',
});

createConnector

Identity helper for typing a ConnectorFactory inline — returns the factory unchanged so authors get parameter inference without spelling the type out.

Returns: ConnectorFactory — The same factory, typed as ConnectorFactory.

createTonConnectConnector

Build a TonConnect-backed Connector for AppKit. Pass the result to AppKitConfig's connectors or addConnector.

Returns: ConnectorFactory — Factory function consumed by AppKit at registration time.

Example

// 1. Create TonConnectUI instance
const tonConnectUI = new TonConnectUI({
    manifestUrl: 'https://my-app.com/tonconnect-manifest.json',
});

// 2. Initialize AppKit
const appKit = new AppKit({
    networks: {
        [Network.mainnet().chainId]: {
            apiClient: {
                url: 'https://toncenter.com',
                key: 'your-key',
            },
        },
    },
    connectors: [createTonConnectConnector({ tonConnectUI })],
});

disconnect

Tear down the session on a registered connector — disconnects the wallet currently connected through it, if any. Throws when no connector with that id exists.

Returns: Promise<DisconnectReturnType> — Resolves once the connector tears down its session.

Example

await disconnect(appKit, {
    connectorId: 'tonconnect',
});

getConnectorById

Look up a registered connector by its id.

Returns: GetConnectorByIdReturnType — The matching Connector, or undefined if none with that id is registered.

Example

const connector = getConnectorById(appKit, {
    id: 'tonconnect',
});

if (connector) {
    console.log('Found connector:', connector.id);
}

getConnectors

List every connector registered on this AppKit instance — both those passed via AppKitConfig's connectors and those added later through addConnector.

Returns: GetConnectorsReturnType — Read-only array of registered Connectors.

Example

const connectors = getConnectors(appKit);
connectors.forEach((connector) => {
    console.log('Connector:', connector.id);
});

watchConnectorById

Subscribe to register/unregister events for a connector with the given id — the callback fires when the connector is added or removed, so callers can react to its presence. Use watchConnectedWallets if you want to react to wallet connect/disconnect events instead.

Returns: WatchConnectorByIdReturnType — Unsubscribe function — call it to stop receiving updates.

Example

const unsubscribe = watchConnectorById(appKit, {
    id: 'tonconnect',
    onChange: (connector) => {
        console.log('Connector updated:', connector);
    },
});

// Later: unsubscribe();

watchConnectors

Subscribe to changes in the registered-connectors list — the callback fires when a connector is added (via addConnector or AppKit's constructor) or removed, and receives the current list. Use watchConnectedWallets if you want to react to wallet connect/disconnect events instead.

Returns: WatchConnectorsReturnType — Unsubscribe function — call it to stop receiving updates.

Example

const unsubscribe = watchConnectors(appKit, {
    onChange: (connectors) => {
        console.log('Connectors updated:', connectors);
    },
});

// Later: unsubscribe();

Crypto Onramp

createCryptoOnrampDeposit

Create a crypto-onramp deposit from a quote previously obtained via getCryptoOnrampQuote — the returned CryptoOnrampDeposit carries the address and amount the user must send on the source chain.

Returns: CreateCryptoOnrampDepositReturnType — Deposit details the UI should show to the user (address, amount, optional memo/expiresAt).

createLayerswapProvider

Build a Layerswap-backed CryptoOnrampProvider for AppKit. Pass the result to AppKitConfig's providers or registerProvider.

Returns: ProviderFactory<LayerswapCryptoOnrampProvider>.

createSwapsXyzProvider

Build a swaps.xyz-backed CryptoOnrampProvider for AppKit. Pass the result to AppKitConfig's providers or registerProvider.

Returns: ProviderFactory<SwapsXyzCryptoOnrampProvider>.

getCryptoOnrampProvider

Get a registered crypto-onramp provider by id, or the default provider when no id is given. Throws when no provider matches — or when no id is passed and no default has been registered.

Returns: GetCryptoOnrampProviderReturnType — The matching CryptoOnrampProviderInterface.

Example

const provider = getCryptoOnrampProvider(appKit, { id: 'layerswap' });
console.log('Crypto onramp provider:', provider.providerId);

getCryptoOnrampProviders

List every crypto-onramp provider registered on this AppKit instance — both those passed via AppKitConfig's providers and those added later through registerProvider.

Returns: GetCryptoOnrampProvidersReturnType — Array of registered CryptoOnrampProviderInterfaces.

Example

const providers = getCryptoOnrampProviders(appKit);
console.log(
    'Registered crypto onramp providers:',
    providers.map((p) => p.providerId),
);

getCryptoOnrampQuote

Quote a crypto-to-TON onramp — given a source asset/chain and target TON asset, returns the rate, expected amount, and provider metadata needed to call createCryptoOnrampDeposit.

Returns: GetCryptoOnrampQuoteReturnType — Quote with pricing details and the provider metadata required to create a deposit.

getCryptoOnrampStatus

Read the current status of a crypto-onramp deposit by id — typically polled until the result is 'success' or 'failed'.

Returns: GetCryptoOnrampStatusReturnType — Current CryptoOnrampStatus of the deposit.

watchCryptoOnrampProviders

Subscribe to crypto-onramp provider lifecycle — fires onChange whenever a new provider is registered or the default crypto-onramp provider switches.

Returns: WatchCryptoOnrampProvidersReturnType — Unsubscribe function — call it to stop receiving updates.

DeFi

registerProvider

Register a DeFi / onramp provider at runtime — equivalent to passing it via AppKitConfig's providers at construction, but available after AppKit is up. AppKit emits provider:registered, picked up by domain-specific subscribers like watchSwapProviders and watchCryptoOnrampProviders.

Returns: void.

Example

registerProvider(
    appKit,
    createOmnistonProvider({
        defaultSlippageBps: 100, // 1%
    }),
);

Jettons

createTransferJettonTransaction

Build a jetton transfer TransactionRequest for the selected wallet without sending it — useful when the UI needs to inspect or batch transactions before signing. Throws Error('Wallet not connected') if no wallet is currently selected.

Returns: Promise<CreateTransferJettonTransactionReturnType> — Transaction request ready to pass to sendTransaction.

Example

const tx = await createTransferJettonTransaction(appKit, {
    jettonAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
    recipientAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
    amount: '100', // 100 USDT
    comment: 'Hello Jetton',
    jettonDecimals: 6,
});
console.log('Transfer Transaction:', tx);

getJettonBalance

Read a jetton balance for a given owner — derives the owner's jetton-wallet address from the master, then fetches and formats the balance using the supplied decimals.

Returns: Promise<GetJettonBalanceReturnType> — Balance as a human-readable decimal string in the jetton's units.

Example

const selectedWallet = getSelectedWallet(appKit);
if (!selectedWallet) {
    console.log('No wallet selected');
    return;
}

const balance = await getJettonBalance(appKit, {
    jettonAddress: 'EQDBE420tTQIkoWcZ9pEOTKY63WVmwyIl3hH6yWl0r_h51Tl',
    ownerAddress: selectedWallet.getAddress(),
    jettonDecimals: 6,
});
console.log('Jetton Balance:', balance);

getJettonInfo

Fetch token metadata for a jetton master — name, symbol, decimals, image and description as reported by the indexer. Returns null when the indexer has no record for that master address.

Returns: Promise<GetJettonInfoReturnType> — Jetton metadata, or null if the indexer has no record.

Example

const info = await getJettonInfo(appKit, {
    address: 'EQDBE420tTQIkoWcZ9pEOTKY63WVmwyIl3hH6yWl0r_h51Tl',
});
console.log('Jetton Info:', info);

getJettonWalletAddress

Derive the jetton-wallet address for a given owner — the per-owner contract that actually holds the jetton balance for jettonAddress.

Returns: Promise<GetJettonWalletAddressReturnType> — User-friendly address of the owner's jetton wallet.

Example

const selectedWallet = getSelectedWallet(appKit);
if (!selectedWallet) {
    console.log('No wallet selected');
    return;
}

const address = await getJettonWalletAddress(appKit, {
    jettonAddress: 'EQDBE420tTQIkoWcZ9pEOTKY63WVmwyIl3hH6yWl0r_h51Tl',
    ownerAddress: selectedWallet.getAddress(),
});
console.log('Jetton Wallet Address:', address);

getJettons

List jettons held by the currently selected wallet, returning null when no wallet is selected (use getJettonsByAddress for an arbitrary address).

Returns: Promise<GetJettonsReturnType> — Jettons response for the selected wallet, or null when none is selected.

Example

const response = await getJettons(appKit);
if (!response) {
    console.log('No wallet selected or no jettons found');
    return;
}
console.log('Jettons:', response.jettons.length);
response.jettons.forEach((j) => console.log(`- ${j.info.name}: ${j.balance}`));

getJettonsByAddress

List jettons held by an arbitrary address — useful for inspecting wallets that aren't selected in AppKit (use getJettons for the selected wallet). Raw balances are formatted with each jetton's declared decimals, and entries without decimals are dropped.

Returns: Promise<GetJettonsByAddressReturnType> — Jettons response with formatted balances.

Example

const selectedWallet = getSelectedWallet(appKit);
if (!selectedWallet) {
    console.log('No wallet selected');
    return;
}

const response = await getJettonsByAddress(appKit, {
    address: selectedWallet.getAddress(),
});
console.log('Jettons by Address:', response.jettons.length);
response.jettons.forEach((j) => console.log(`- ${j.info.name}: ${j.balance}`));

transferJetton

Build and send a jetton transfer from the selected wallet in one step (use createTransferJettonTransaction + sendTransaction if you need to inspect the transaction first). Throws Error('Wallet not connected') if no wallet is currently selected.

Returns: Promise<TransferJettonReturnType> — Wallet response carrying the BoC of the sent transaction.

Example

const result = await transferJetton(appKit, {
    jettonAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
    recipientAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
    amount: '100',
    jettonDecimals: 6,
});
console.log('Transfer Result:', result);

watchJettons

Subscribe to jetton-balance updates for the currently selected wallet, automatically rebinding when the user connects, switches, or disconnects (use watchJettonsByAddress for a fixed address). Requires a streaming provider registered for the network — call throws when none is configured. Use hasStreamingProvider to check first.

Returns: WatchJettonsReturnType — Unsubscribe function — call it to stop receiving updates.

watchJettonsByAddress

Subscribe to jetton-balance updates for an arbitrary owner address (use watchJettons for the selected wallet). Requires a streaming provider registered for the network — call throws when none is configured. Use hasStreamingProvider to check first.

Returns: WatchJettonsByAddressReturnType — Unsubscribe function — call it to stop receiving updates.

NFTs

createTransferNftTransaction

Build an NFT transfer TransactionRequest for the selected wallet without sending it — useful when the UI needs to inspect or batch transactions before signing. Throws Error('Wallet not connected') if no wallet is currently selected.

Returns: Promise<CreateTransferNftTransactionReturnType> — Transaction request ready to pass to sendTransaction.

Example

const tx = await createTransferNftTransaction(appKit, {
    nftAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
    recipientAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
    comment: 'Gift NFT',
});

console.log('NFT Transfer Transaction:', tx);

getNft

Fetch metadata and ownership for a single NFT by its contract address. Returns null when the indexer has no record.

Returns: Promise<GetNftReturnType> — NFT data, or null if the indexer has no record.

Example

const nft = await getNft(appKit, {
    address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
});

if (nft) {
    console.log('NFT Name:', nft.info?.name);
    console.log('NFT Collection:', nft.collection?.name);
}

getNfts

List NFTs held by the currently selected wallet, returning null when no wallet is selected (use getNftsByAddress for an arbitrary address).

Returns: Promise<GetNftsReturnType> — NFTs response for the selected wallet, or null when none is selected.

Example

const response = await getNfts(appKit);

if (response) {
    console.log('Total NFTs:', response.nfts.length);
    response.nfts.forEach((nft) => console.log(`- ${nft.info?.name}`));
}

getNftsByAddress

List NFTs held by an arbitrary address — useful for inspecting wallets that aren't selected in AppKit (use getNfts for the selected wallet).

Returns: Promise<GetNftsByAddressReturnType> — NFTs response with the owner's items.

Example

const response = await getNftsByAddress(appKit, {
    address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
});

console.log('NFTs by address:', response.nfts.length);

transferNft

Build and send an NFT transfer from the selected wallet in one step (use createTransferNftTransaction + sendTransaction if you need to inspect the transaction first). Throws Error('Wallet not connected') if no wallet is currently selected.

Returns: Promise<TransferNftReturnType> — Wallet response carrying the BoC of the sent transaction.

Example

const result = await transferNft(appKit, {
    nftAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
    recipientAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
});

console.log('NFT Transfer Result:', result);

Networks

getBlockNumber

Read the latest masterchain seqno (block number) for a network — useful for pagination cursors and freshness checks. Defaults to mainnet when no network is given.

Returns: Promise<GetBlockNumberReturnType> — Current masterchain seqno as a number.

Example

const blockNumber = await getBlockNumber(appKit);

console.log('Current block number:', blockNumber);

getDefaultNetwork

Read AppKit's currently configured default network — the one connectors enforce on new wallet connections. undefined means any registered network is allowed.

Returns: GetDefaultNetworkReturnType — The default Network, or undefined if none is set.

Example

const defaultNetwork = getDefaultNetwork(appKit);
console.log('Default network:', defaultNetwork);

getNetwork

Read the Network the selected wallet is connected to, or null when no wallet is selected (use getDefaultNetwork for AppKit's configured default).

Returns: GetNetworkReturnType — Network of the selected wallet, or null when none is selected.

Example

const network = getNetwork(appKit);

if (network) {
    console.log('Current network:', network);
}

getNetworks

List every network configured on this AppKit instance via AppKitConfig's networks.

Returns: GetNetworksReturnType — Array of configured Networks.

Example

const networks = getNetworks(appKit);

console.log('Configured networks:', networks);

hasStreamingProvider

Check whether a streaming provider is registered for a network — required by watchBalance, watchJettons and other live-update actions.

Returns: HasStreamingProviderReturnType — true when a streaming provider is registered for that network.

Example

const isSupported = hasStreamingProvider(appKit, Network.mainnet());
console.log('Mainnet streaming support:', isSupported);

setDefaultNetwork

Set or clear the default network — connectors enforce it on new wallet connections. Emits NETWORKS_EVENTS.DEFAULT_CHANGED so watchDefaultNetwork subscribers fire. Pass undefined to remove the constraint and allow any registered network.

Returns: SetDefaultNetworkReturnType.

Example

// Enforce testnet for all new wallet connections
setDefaultNetwork(appKit, { network: Network.testnet() });

// Allow any network (clear default)
setDefaultNetwork(appKit, { network: undefined });

watchDefaultNetwork

Subscribe to default-network changes — fires when setDefaultNetwork is called.

Returns: WatchDefaultNetworkReturnType — Unsubscribe function — call it to stop receiving updates.

Example

const unsubscribe = watchDefaultNetwork(appKit, {
    onChange: (network) => {
        console.log('Default network changed:', network);
    },
});

// Later: unsubscribe();

watchNetworks

Subscribe to changes of the configured-networks list — fires when AppKit's network manager registers or replaces a network's API client.

Returns: WatchNetworksReturnType — Unsubscribe function — call it to stop receiving updates.

Example

const unsubscribe = watchNetworks(appKit, {
    onChange: (networks) => {
        console.log('Networks updated:', networks);
    },
});

// Later: unsubscribe();

Signing

signBinary

Ask the selected wallet to sign a binary blob. Throws Error('Wallet not connected') if no wallet is currently selected.

Returns: Promise<SignBinaryReturnType> — Signature and signed payload, as returned by the wallet.

Example

// Example: sign "Hello" in base64
const result = await signBinary(appKit, {
    bytes: 'SGVsbG8=' as Base64String,
});

console.log('Binary Signature:', result.signature);

signCell

Ask the selected wallet to sign a TON cell — typically used so the signature can later be verified on-chain. Throws Error('Wallet not connected') if no wallet is currently selected.

Returns: Promise<SignCellReturnType> — Signature and signed payload, as returned by the wallet.

Example

const result = await signCell(appKit, {
    cell: 'te6ccgEBAQEAAgAAGA==' as Base64String, // Example BoC
    schema: 'transfer#abc123 amount:uint64 = Transfer',
});

console.log('Cell Signature:', result.signature);

signText

Ask the selected wallet to sign a plain text message. Throws Error('Wallet not connected') if no wallet is currently selected.

Returns: Promise<SignTextReturnType> — Signature and signed payload, as returned by the wallet.

Example

const result = await signText(appKit, {
    text: 'Hello, TON!',
});

console.log('Signature:', result.signature);

Staking

buildStakeTransaction

Build a TransactionRequest that executes a stake or unstake previously quoted by getStakingQuote — returns it without sending so the UI can inspect or batch before signing.

Returns: BuildStakeTransactionReturnType — Transaction request ready to pass to sendTransaction.

Example

const txRequest = await buildStakeTransaction(appKit, {
    quote,
    userAddress,
});
console.log('Stake Transaction:', txRequest);

createTonstakersProvider

Build a Tonstakers-backed StakingProvider for AppKit. Pass the result to AppKitConfig's providers or registerProvider.

Returns: (ctx: ProviderFactoryContext) => TonStakersStakingProvider.

getStakedBalance

Read a user's staked balance from a staking provider — total staked plus, depending on the provider, any instant-unstake balance available right now.

Returns: GetStakedBalanceReturnType — Staked-balance breakdown (StakingBalance) for the user on the resolved network/provider.

Example

const balance = await getStakedBalance(appKit, {
    userAddress,
});
console.log('Staked Balance:', balance);

getStakingManager

Read AppKit's StakingManager — the runtime that owns registered staking providers and dispatches quote/stake/balance calls. Apps usually use the higher-level actions (getStakingQuote, buildStakeTransaction, getStakedBalance) instead of touching the manager directly.

Returns: GetStakingManagerReturnType — The StakingManager bound to this AppKit instance.

getStakingProvider

Get a registered staking provider by id, or the default staking provider when no id is given. Throws when no provider matches — or when no id is passed and no default has been registered.

Returns: GetStakingProviderReturnType — The matching staking provider instance.

getStakingProviderInfo

Read live staking-pool info for a provider — APY, instant-unstake liquidity and (for liquid staking) the current exchange rate between stake and receive tokens. Use getStakingProviderMetadata for static metadata (display name, stake/receive tokens, supported unstake modes).

Returns: GetStakingProviderInfoReturnType — Live staking-provider info for the resolved network.

Example

const providerInfo = await getStakingProviderInfo(appKit, {
    providerId: 'tonstakers',
});
console.log('Provider Info:', providerInfo);

getStakingProviderMetadata

Read static metadata for a staking provider — display name, stake/receive tokens, supported unstake modes, contract address. Use getStakingProviderInfo for live values (APY, instant-unstake liquidity, exchange rate).

Returns: GetStakingProviderMetadataReturnType — Static StakingProviderMetadata for the resolved provider.

Example

const providerMetadata = getStakingProviderMetadata(appKit, {
    providerId: 'tonstakers',
});
console.log('Provider Metadata:', providerMetadata);

getStakingProviders

List every staking provider registered on this AppKit instance — both those passed via AppKitConfig's providers and those added later through registerProvider.

Returns: GetStakingProvidersReturnType — Array of registered staking providers.

Example

const providers = getStakingProviders(appKit);
console.log('Available Staking Providers:', providers);

getStakingQuote

Quote a stake or unstake — given the amount, direction and target asset, returns the rate, expected output and provider metadata needed to call buildStakeTransaction.

Returns: GetStakingQuoteReturnType — Quote with pricing details and provider metadata.

Example

const quote = await getStakingQuote(appKit, {
    amount: '1000000000',
    direction: 'stake',
});
console.log('Staking Quote:', quote);

setDefaultStakingProvider

Set the default staking provider — subsequent getStakingQuote and buildStakeTransaction calls without an explicit providerId route through it. Emits provider:default-changed, picked up by watchStakingProviders.

Returns: SetDefaultStakingProviderReturnType.

watchStakingProviders

Subscribe to staking provider lifecycle — fires onChange whenever a new provider is registered or the default staking provider switches.

Returns: WatchStakingProvidersReturnType — Unsubscribe function — call it to stop receiving updates.

Swap

buildSwapTransaction

Build a TransactionRequest that executes a swap previously quoted by getSwapQuote — returns it without sending so the UI can inspect or batch before signing.

Returns: BuildSwapTransactionReturnType — Transaction request ready to pass to sendTransaction.

Example

const transactionRequest = await buildSwapTransaction(appKit, {
    quote,
    userAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
    slippageBps: 100, // 1%
});
const transactionResponse = await sendTransaction(appKit, transactionRequest);
console.log('Swap Transaction:', transactionResponse);

createDeDustProvider

Build a DeDust-backed SwapProvider for AppKit. Pass the result to AppKitConfig's providers or registerProvider.

Returns: (ctx: ProviderFactoryContext) => DeDustSwapProvider.

createOmnistonProvider

Build an Omniston-backed SwapProvider for AppKit. Pass the result to AppKitConfig's providers or registerProvider.

Returns: (ctx: ProviderFactoryContext) => OmnistonSwapProvider.

getSwapManager

Read AppKit's SwapManager — the runtime that owns registered swap providers and dispatches quote/build calls. Apps usually use the higher-level actions (getSwapQuote, buildSwapTransaction) instead of touching the manager directly.

Returns: GetSwapManagerReturnType — The SwapManager bound to this AppKit instance.

Example

const swapManager = getSwapManager(appKit);

getSwapProvider

Get a registered swap provider by id, or the default swap provider when no id is given. Throws when no provider matches — or when no id is passed and no default has been registered.

Returns: GetSwapProviderReturnType — The matching swap provider instance.

Example

const swapProvider = getSwapProvider(appKit, { id: 'stonfi' });

getSwapProviders

List every swap provider registered on this AppKit instance — both those passed via AppKitConfig's providers and those added later through registerProvider.

Returns: GetSwapProvidersReturnType — Array of registered swap providers.

Example

const swapProviders = getSwapProviders(appKit);
console.log(
    'Registered providers:',
    swapProviders.map((p) => p.providerId),
);

getSwapQuote

Quote a swap — given source/target tokens and an amount, returns the rate, expected output and provider metadata needed to call buildSwapTransaction.

Returns: GetSwapQuoteReturnType — Quote with pricing details and the provider metadata required to build a transaction.

Example

const quote = await getSwapQuote(appKit, {
    from: {
        address: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
        decimals: 6,
    },
    to: { address: 'ton', decimals: 9 },
    amount: '1000000000', // nanotons as string
    network: Network.mainnet(),
});
console.log('Swap Quote:', quote);

setDefaultSwapProvider

Set the default swap provider — subsequent getSwapQuote and buildSwapTransaction calls without an explicit providerId route through it. Emits provider:default-changed, picked up by watchSwapProviders.

Returns: SetDefaultSwapProviderReturnType.

Example

setDefaultSwapProvider(appKit, { providerId: 'stonfi' });

watchSwapProviders

Subscribe to swap provider lifecycle — fires onChange whenever a new provider is registered or the default swap provider switches.

Returns: WatchSwapProvidersReturnType — Unsubscribe function — call it to stop receiving updates.

Example

const unsubscribe = watchSwapProviders(appKit, {
    onChange: () => console.log('Swap providers updated'),
});
unsubscribe();

Transactions

createTransferTonTransaction

Build a TON transfer TransactionRequest for the selected wallet without sending it — useful when the UI needs to inspect or batch transactions before signing. Throws Error('Wallet not connected') if no wallet is currently selected.

Returns: CreateTransferTonTransactionReturnType — Transaction request ready to pass to sendTransaction.

Example

const tx = createTransferTonTransaction(appKit, {
    recipientAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
    amount: '0.1', // 0.1 TON (human-readable format)
    comment: 'Draft transaction',
});

console.log('Transaction Request:', tx);

getTransactionStatus

Read the status of a sent transaction by its BoC or normalized hash. In TON a single external message triggers a tree of internal messages — the transaction is 'completed' only when the entire trace finishes. Until then it stays 'pending'. Throws when neither boc nor normalizedHash is provided.

Returns: Promise<GetTransactionStatusReturnType> — Status response with current state, completed/total message counts and trace details.

sendTransaction

Hand a pre-built TransactionRequest to the selected wallet for signing and broadcast — usually the second step after createTransferTonTransaction, buildSwapTransaction or buildStakeTransaction. Throws Error('Wallet not connected') if no wallet is currently selected.

Returns: Promise<SendTransactionReturnType> — Wallet response carrying the BoC of the sent transaction.

Example

const result = await sendTransaction(appKit, {
    messages: [
        {
            address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
            amount: '100000000', // 0.1 TON in nanotons (raw format)
        },
    ],
});

console.log('Transaction Result:', result);

transferTon

Build and send a TON transfer from the selected wallet in one step (use createTransferTonTransaction + sendTransaction if you need to inspect the transaction first). Throws Error('Wallet not connected') if no wallet is currently selected.

Returns: Promise<TransferTonReturnType> — Wallet response carrying the BoC of the sent transaction.

Example

const result = await transferTon(appKit, {
    recipientAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
    amount: '0.1', // 0.1 TON (human-readable format)
    comment: 'Hello from AppKit!',
});

console.log('Transfer Result:', result);

watchTransactions

Subscribe to incoming-transaction events for the currently selected wallet, automatically rebinding when the user connects, switches, or disconnects (use watchTransactionsByAddress for a fixed address). Requires a streaming provider registered for the network — call throws when none is configured. Use hasStreamingProvider to check first.

Returns: WatchTransactionsReturnType — Unsubscribe function — call it to stop receiving updates.

watchTransactionsByAddress

Subscribe to incoming-transaction events for an arbitrary address (use watchTransactions for the selected wallet). Requires a streaming provider registered for the network — call throws when none is configured. Use hasStreamingProvider to check first.

Returns: WatchTransactionsByAddressReturnType — Unsubscribe function — call it to stop receiving updates.

Wallets

getConnectedWallets

List every wallet currently connected through any registered Connector.

Returns: GetConnectedWalletsReturnType — Read-only array of WalletInterfaces.

Example

const wallets = getConnectedWallets(appKit);

console.log('Connected wallets:', wallets);

getSelectedWallet

Read the wallet AppKit treats as "active" — most actions (getBalance, signText, transferTon) target this wallet implicitly. Returns null when no wallet is connected or selected.

Returns: GetSelectedWalletReturnType — Selected WalletInterface, or null when none is selected.

Example

const wallet = getSelectedWallet(appKit);

if (wallet) {
    console.log('Selected wallet:', wallet.getWalletId());
    console.log('Address:', wallet.getAddress());
}

setSelectedWalletId

Switch which connected wallet AppKit treats as selected — emits WALLETS_EVENTS.SELECTION_CHANGED so watchSelectedWallet subscribers fire. Pass null to clear the selection.

Returns: SetSelectedWalletIdReturnType.

Example

setSelectedWalletId(appKit, {
    walletId: 'my-wallet-id',
});

watchConnectedWallets

Subscribe to the list of connected wallets — fires whenever a wallet connects or disconnects through any registered Connector.

Returns: WatchConnectedWalletsReturnType — Unsubscribe function — call it to stop receiving updates.

Example

const unsubscribe = watchConnectedWallets(appKit, {
    onChange: (wallets) => {
        console.log('Connected wallets updated:', wallets.length);
    },
});

// Later: unsubscribe();

watchSelectedWallet

Subscribe to selected-wallet changes — fires when setSelectedWalletId runs, when the wallet manager auto-selects the first wallet because no prior selection survived a connector update, or when it clears the selection because no connected wallets remain.

Returns: WatchSelectedWalletReturnType — Unsubscribe function — call it to stop receiving updates.

Example

const unsubscribe = watchSelectedWallet(appKit, {
    onChange: (wallet) => {
        if (wallet) {
            console.log('Selected wallet changed:', wallet.getWalletId());
        } else {
            console.log('Wallet deselected');
        }
    },
});

// Later: unsubscribe();

Class

Client

ApiClientTonApi

ApiClient implementation backed by the TonAPI indexer.

Constructor: new ApiClientTonApi(config)

ApiClientToncenter

ApiClient implementation backed by the Toncenter API.

Constructor: new ApiClientToncenter(config)

Core

AppKit

Runtime that wires connectors, networks, providers and the event emitter for a TON dApp. Construct once at startup and reuse for the app's lifetime.

Constructor: new AppKit(config)

Example

// Initialize AppKit
const appKit = new AppKit({
    networks: {
        [Network.mainnet().chainId]: {
            apiClient: {
                url: 'https://toncenter.com',
                key: 'your-key',
            },
        },
        // Optional: add testnet
        // [Network.testnet().chainId]: {
        //     apiClient: {
        //         url: 'https://testnet.toncenter.com',
        //         key: 'your-key',
        //     },
        // },
    },
    connectors: [
        createTonConnectConnector({
            tonConnectOptions: {
                manifestUrl: 'https://tonconnect-sdk-demo-dapp.vercel.app/tonconnect-manifest.json',
            },
        }),
    ],
});

EventEmitter

Strongly-typed event emitter built on a string event name → payload type map. Type of appKit.emitter and the base for any custom emitters apps create. See AppKitEvents for the full list of events AppKit emits. appKit.emitter.on(name, handler) returns an unsubscribe function.

Constructor: new EventEmitter()

Crypto Onramp

CryptoOnrampError

Error thrown by CryptoOnrampManager and crypto-onramp providers — extends DefiError with name: 'CryptoOnrampError' and a typed CryptoOnrampErrorCode on code.

Constructor: new CryptoOnrampError(message, code, details)

CryptoOnrampManager

Runtime that owns registered CryptoOnrampProviders and dispatches quote/deposit/status calls. Usually accessed through the higher-level actions (getCryptoOnrampQuote, createCryptoOnrampDeposit, getCryptoOnrampStatus).

Constructor: new CryptoOnrampManager()

CryptoOnrampProvider

Abstract base class implemented by crypto-onramp providers (Layerswap, swaps.xyz, custom integrations). Apps don't use it directly — they consume providers through CryptoOnrampManager and the getCryptoOnramp* / createCryptoOnrampDeposit actions.

Constructor: new CryptoOnrampProvider()

LayerswapCryptoOnrampProvider

CryptoOnrampProvider implementation backed by Layerswap. Prefer the createLayerswapProvider factory over instantiating this class directly — the factory returns a ProviderInput ready to pass to AppKitConfig's providers or registerProvider.

Constructor: new LayerswapCryptoOnrampProvider(config)

SwapsXyzCryptoOnrampProvider

CryptoOnrampProvider implementation backed by swaps.xyz. Prefer the createSwapsXyzProvider factory over instantiating this class directly — the factory returns a ProviderInput ready to pass to AppKitConfig's providers or registerProvider.

Constructor: new SwapsXyzCryptoOnrampProvider(config)

DeFi

DefiError

Base error thrown across all DeFi domains (swap, staking, onramp, crypto-onramp). Subclassed by SwapError, StakingError, CryptoOnrampError and the internal onramp error — catch the base when you don't care which domain produced the failure.

Constructor: new DefiError(message, code, details)

Networks

AppKitNetworkManager

Network manager that extends walletkit's KitNetworkManager with a default-network setter and AppKit event emission. Usually accessed through the higher-level actions (getDefaultNetwork, setDefaultNetwork, watchDefaultNetwork, getNetworks, watchNetworks).

Constructor: new AppKitNetworkManager(options, emitter)

KitNetworkManager

Walletkit-side network manager that AppKitNetworkManager extends, adding default-network state and AppKit event emission. Apps usually interact with the AppKitNetworkManager subclass.

Constructor: new KitNetworkManager(options)

Staking

StakingError

Error thrown by StakingManager and staking providers — extends DefiError with name: 'StakingError' and a typed StakingErrorCode on code.

Constructor: new StakingError(message, code, details)

StakingManager

Runtime that owns registered StakingProviders and dispatches quote/stake/balance calls. Usually accessed through the higher-level actions (getStakingQuote, buildStakeTransaction, getStakedBalance).

Constructor: new StakingManager(createFactoryContext)

StakingProvider

Abstract base class implemented by staking providers (Tonstakers, custom integrations, …). Apps don't use it directly — they consume providers through StakingManager and the getStaking* / buildStakeTransaction actions.

Constructor: new StakingProvider(providerId)

TonStakersStakingProvider

StakingProvider implementation backed by Tonstakers. The constructor is private — always go through the createTonstakersProvider factory and pass the result to AppKitConfig's providers or registerProvider.

Constructor: new TonStakersStakingProvider()

Swap

DeDustSwapProvider

SwapProvider implementation backed by DeDust. Prefer the createDeDustProvider factory over instantiating this class directly — the factory returns a ProviderInput ready to pass to AppKitConfig's providers or registerProvider.

Constructor: new DeDustSwapProvider(config)

Example

kit.registerProvider(
    createDeDustProvider({
        defaultSlippageBps: 100, // 1%
        referralAddress: 'EQ...',
        referralFeeBps: 50, // 0.5%
    }),
);

OmnistonSwapProvider

SwapProvider implementation backed by Omniston. Prefer the createOmnistonProvider factory over instantiating this class directly — the factory returns a ProviderInput ready to pass to AppKitConfig's providers or registerProvider.

Constructor: new OmnistonSwapProvider(config)

Example

kit.registerProvider(
    createOmnistonProvider({
        defaultSlippageBps: 100, // 1%
        quoteTimeoutMs: 10000,
    }),
);

SwapError

Error thrown by SwapManager and swap providers — extends DefiError with name: 'SwapError' and a typed SwapErrorCode on code.

Constructor: new SwapError(message, code, details)

SwapManager

Runtime that owns registered SwapProviders and dispatches quote/swap calls. Usually accessed through the higher-level actions (getSwapQuote, buildSwapTransaction).

Constructor: new SwapManager(createFactoryContext)

SwapProvider

Abstract base class implemented by swap providers (DeDust, Omniston, custom integrations). Apps don't use it directly — they consume providers through SwapManager and the getSwap* / buildSwapTransaction actions.

Constructor: new SwapProvider()

Wallets

TonConnectWalletAdapter

WalletInterface implementation backed by a TonConnect wallet. Prefer the createTonConnectConnector factory over instantiating this class directly — the connector builds the adapter for every wallet it tracks and apps interact with it through standard AppKit actions (sendTransaction, signText/signBinary/signCell). On-chain reads (balance, jettons, NFTs) live on separate actions (getBalance, getJettons, getNfts) and don't go through this adapter.

Constructor: new TonConnectWalletAdapter(config)

Type

Balances

BalanceUpdate

Update payload delivered to watchBalance / watchBalanceByAddress subscribers when the watched address's TON balance changes.

GetBalanceByAddressOptions

Options for getBalanceByAddress.

GetBalanceByAddressReturnType

Return type of getBalanceByAddress.

type GetBalanceByAddressReturnType = TokenAmount;

GetBalanceOptions

Options for getBalance.

GetBalanceReturnType

Return type of getBalance.

type GetBalanceReturnType = TokenAmount | null;

StreamingUpdateStatus

Finality stage carried by every streaming update — 'pending' (in mempool), 'confirmed' (included in a block), 'finalized' (irreversible), or 'invalidated' (rolled back).

type StreamingUpdateStatus = 'pending' | 'confirmed' | 'finalized' | 'invalidated';

WatchBalanceByAddressOptions

Options for watchBalanceByAddress.

WatchBalanceByAddressReturnType

Return type of watchBalanceByAddress — call to stop receiving updates.

type WatchBalanceByAddressReturnType = () => void;

WatchBalanceOptions

Options for watchBalance.

WatchBalanceReturnType

Return type of watchBalance — call to stop receiving updates.

type WatchBalanceReturnType = () => void;

Client

AddressBook

Map of raw addresses to their resolved metadata, returned alongside indexed lists (e.g. JettonsResponse, NFTsResponse) so consumers can render labels without extra lookups.

type AddressBook = {
    [key: UserFriendlyAddress]: AddressBookEntry;
};

AddressBookEntry