FAQ & Troubleshooting

Use this page to answer common AppKit questions and triage the most common failure classes: connector issues, wallet rejection, network mismatch, provider gaps, and settlement confusion.

FAQ

What is AppKit?

AppKit is a TypeScript toolkit for TON wallet connection, transaction requests, asset reads, provider integrations, React hooks, and UI components.

Is AppKit a wallet?

No. Wallets hold keys and sign requests. AppKit prepares requests, tracks application state, and routes actions through connectors and providers.

Does AppKit store private keys?

No. Private keys stay in the user's wallet. AppKit stores runtime configuration, local state, and provider registrations.

Can AppKit be used without React?

Yes. The core package @ton/appkit works from plain TypeScript. React-specific hooks and components live in @ton/appkit-react.

How is transaction success confirmed?

A wallet transaction response only proves the user signed and the wallet submitted the request. Confirm success with getTransactionStatus, streaming updates, or backend verification before changing product state.

Why does a wallet reject a request?

Common causes include user rejection, expired requests, wrong network, missing wallet selection, malformed payloads, and insufficient balance for value plus fees.

Troubleshoot by symptom

The connect button opens, but no wallet connects

Check the connector configuration first:

confirm the TON Connect manifest URL is public and reachable
confirm at least one connector is registered on the AppKit instance
confirm the React tree is wrapped with AppKitProvider

If the UI is custom, confirm the code passes a valid connectorId to connect.

Reads work, but watch hooks never update

Streaming hooks need a streaming provider. Confirm that:

a streaming provider is registered for the active network
the network passed to the watcher matches the configured network
hasStreamingProvider(appKit, network) returns true

The wallet signs, but the app never sees settlement

Separate wallet acceptance from on-chain settlement:

treat the wallet response as a submission result, not finality
check getTransactionStatus with the returned boc
if streaming is used, remember that streaming finality uses pending, confirmed, finalized, and invalidated

Jetton or NFT data looks wrong

Treat off-chain metadata as display data:

read decimals from jetton metadata before building transfers
sanitize jetton and NFT names, images, and descriptions
route by contract addresses, not by display metadata

A transaction fails on the wrong network

Check both the selected wallet network and the AppKit default network. Block unsafe actions until the expected network and wallet-reported network match.

FAQ & Troubleshooting

On this page