diff --git a/.claude/skills/add-action-and-hook/SKILL.md b/.claude/skills/add-action-and-hook/SKILL.md
index 316eb3f3e..f1768b2cf 100644
--- a/.claude/skills/add-action-and-hook/SKILL.md
+++ b/.claude/skills/add-action-and-hook/SKILL.md
@@ -61,6 +61,10 @@ export {
 } from './<category>/get-xxx';
 ```
 
+### 1.4 Document the action
+
+Add `@public` JSDoc to the action and to `GetXxxOptions` so they show up in the auto-generated reference. Follow the [`document-public-api`](../document-public-api/SKILL.md) skill for the exact tag set, allowed `@category` values, and style rules (one-sentence summaries, `{@link X}` syntax for type cells, `@expand` for options-bag flattening, `@sample` for code examples).
+
 ---
 
 ## Step 2: Create the Query or Mutation in `appkit` (for get actions only)
@@ -219,12 +223,16 @@ Add to `packages/appkit-react/src/features/<category>/index.ts`:
 export { useXxx, type UseXxxParameters, type UseXxxReturnType } from './hooks/use-xxx';
 ```
 
+### Document the hook
+
+Tag the hook (and `UseXxxParameters` / `UseXxxReturnType` if useful) with `@public` JSDoc. Use `@category Hook` and `@section <Domain>`. The full ruleset (required tags, allowed values, `{@link}` linking, `@sample` placeholders) is in the [`document-public-api`](../document-public-api/SKILL.md) skill.
+
 ---
 
 ## Step 4: Add Examples and Tests
 
 ### 4.1 Action example
-Create `demo/examples/src/appkit/actions/<category>/get-xxx.ts`:
+Create `docs/examples/src/appkit/actions/<category>/get-xxx.ts`:
 ```ts
 import type { AppKit } from '@ton/appkit';
 import { getXxx } from '@ton/appkit';
@@ -237,10 +245,12 @@ export const getXxxExample = async (appKit: AppKit) => {
 };
 ```
 
-Export it in `demo/examples/src/appkit/actions/<category>/index.ts`.
+Export it in `docs/examples/src/appkit/actions/<category>/index.ts`.
+
+The `// SAMPLE_START: GET_XXX … // SAMPLE_END: GET_XXX` block is what `@sample docs/examples/src/appkit/actions/<category>#GET_XXX` in the action's JSDoc will pull into the reference (see [`document-public-api`](../document-public-api/SKILL.md)).
 
 ### 4.2 Hook example
-Create `demo/examples/src/appkit/hooks/<category>/use-xxx.tsx`:
+Create `docs/examples/src/appkit/hooks/<category>/use-xxx.tsx`:
 ```tsx
 import { useXxx } from '@ton/appkit-react';
 
@@ -252,7 +262,7 @@ export const UseXxxExample = () => {
 };
 ```
 
-Export it in `demo/examples/src/appkit/hooks/<category>/index.ts`.
+Export it in `docs/examples/src/appkit/hooks/<category>/index.ts`.
 
 ### 4.3 Write tests
 **Important:** Do NOT create a new test file per example. Add tests to the existing `<category>.test.ts` / `<category>.test.tsx` file in the same directory.
@@ -280,24 +290,26 @@ If the mock `appKit` in `beforeEach` doesn't have the required mocks (e.g., `get
 
 ## Step 5: Update Templates and Docs
 
-### 5.1 Update action template
-Edit `template/appkit-actions.md`, add after the nearest related action:
+The reference at `packages/<pkg>/docs/reference.md` is fully generated from `@public` JSDoc, so once Step 1.4 / Step 3.1 are done your action and hook are already in the reference. The two steps below update the older hand-curated `actions.md` / `hooks.md` listings.
+
+### 5.1 Update action listing
+Edit `docs/templates/packages/appkit/docs/actions.md`, add after the nearest related action:
 ```md
 ### `getXxx`
 
 Description of what the action does.
 
-%%demo/examples/src/appkit/actions/<category>#GET_XXX%%
+%%docs/examples/src/appkit/actions/<category>#GET_XXX%%
 ```
 
-### 5.2 Update hooks template
-Edit `template/appkit-hooks.md`, add after the nearest related hook:
+### 5.2 Update hooks listing
+Edit `docs/templates/packages/appkit-react/docs/hooks.md`, add after the nearest related hook:
 ```md
 ### `useXxx`
 
 Hook to ...
 
-%%demo/examples/src/appkit/hooks/<category>#USE_XXX%%
+%%docs/examples/src/appkit/hooks/<category>#USE_XXX%%
 ```
 
 ### 5.3 Run quality check
@@ -310,4 +322,4 @@ All tests and type checks must pass before continuing.
 ```bash
 pnpm docs:update
 ```
-Verify the relevant `.md` files in `packages/appkit/docs/` and `packages/appkit-react/docs/` were updated.
+Runs `docs:reference` (regenerates `reference.md` from `@public` JSDoc) followed by `docs:template` (resolves `%%path#SAMPLE%%` placeholders into real code blocks). Verify the resulting `.md` files in `packages/appkit/docs/` and `packages/appkit-react/docs/` were updated.
diff --git a/.claude/skills/add-ui-component/SKILL.md b/.claude/skills/add-ui-component/SKILL.md
index 99f9bc0f6..0ee5963c1 100644
--- a/.claude/skills/add-ui-component/SKILL.md
+++ b/.claude/skills/add-ui-component/SKILL.md
@@ -89,3 +89,13 @@ Use `packages/appkit-react/src/components/block` as the canonical reference for:
 - `block.tsx`
 - `block.module.css`
 - `block.stories.tsx`
+
+---
+
+## 5. Documentation
+
+If the component is meant to be part of the public API, tag it with `@public` JSDoc so it shows up in the auto-generated reference (`packages/appkit-react/docs/reference.md`). Use `@category Component` and `@section <Domain>`. The full ruleset (required tags, allowed values, `{@link X}` for type-cell links, single-sentence description style, `@sample` for usage examples) lives in the [`document-public-api`](../document-public-api/SKILL.md) skill.
+
+For compound components (`const Foo = { Container: …, Item: … }`), the same `@public` block on the namespace object is enough — the generator walks each member and renders them as `#### Foo.Container`, `#### Foo.Item`, etc.
+
+After editing JSDoc run `pnpm docs:update` to regenerate `packages/appkit-react/docs/reference.md`.
diff --git a/.claude/skills/document-public-api/SKILL.md b/.claude/skills/document-public-api/SKILL.md
new file mode 100644
index 000000000..a606a7248
--- /dev/null
+++ b/.claude/skills/document-public-api/SKILL.md
@@ -0,0 +1,227 @@
+---
+name: document-public-api
+description: How to write JSDoc for public symbols so they appear in the auto-generated reference (`packages/<pkg>/docs/reference.md`). Use whenever adding `@public` to an export or editing the surrounding doc-comment.
+---
+
+# Documenting public API for the reference generator
+
+The generator at `docs/reference-generator/` walks every export of `packages/appkit` and `packages/appkit-react`, picks the ones tagged `@public`, and renders them into `packages/<pkg>/docs/reference.md`. The output goes through `docs/template-resolver/` which resolves `%%path#NAME%%` placeholders into real code from `docs/examples/`.
+
+This skill describes exactly which JSDoc tags the generator understands, in what shape, and what the rendered output looks like.
+
+---
+
+## Required tags
+
+Every `@public` symbol **must** also declare:
+
+- `@public` — opt-in marker. Without it the symbol is invisible to the generator.
+- `@category <Class | Action | Hook | Component | Type | Constants>` — top-level group (`## Class`, `## Action`, …). The generator validates the value; anything else is an error.
+- `@section <Domain>` — second-level group (`### Balances`, `### Connectors and wallets`, …). Free-form string; symbols sharing the same value end up under one heading.
+
+If any of the three is missing, `pnpm docs:reference` aborts with a list of offending symbols.
+
+### Which declaration shape fits each `@category`
+
+| `@category` | Allowed declaration |
+| --- | --- |
+| `Class` | `export class X { }` |
+| `Action` / `Hook` | `export function name(...)` or `export const name = (...) => ...` |
+| `Component` | Function returning JSX **or** a `const X = { Sub: …, Sub2: … }` object of FCs (rendered as a compound component) |
+| `Type` | `export interface X { }` or `export type X = ...` |
+| `Constants` | `export const X = { ... } as const` (or any `export const X = literal`) |
+
+Putting `@category Class` on an interface raises `[X] @category Class requires the symbol to be a class declaration.` at generate time. `Type` and `Constants` are deliberately split so a `const X = {}` cannot accidentally land under "Type" — pick `Constants` for runtime values, `Type` for compile-time-only declarations.
+
+---
+
+## Optional tags
+
+- `@param <name> - <description>` — column row in the parameters table. Description should be a single self-contained sentence with a trailing period.
+- `@returns <description>` — appears as `Returns: \`Type\` — <description>.`
+- `@example` — inline TS/TSX code block printed under the entry.
+- `@sample <dir/path>#<SAMPLE_NAME>` — placeholder that `pnpm docs:template` replaces with the body of a `// SAMPLE_START: NAME … // SAMPLE_END: NAME` block under `docs/examples/`. Multiple `@sample` tags are allowed.
+- `@expand <paramName>` — for actions that take an options-bag (`getBalanceByAddress(appKit, options)`), expands the named parameter's fields into extra rows like `options.address`, `options.network`. Without `@expand`, the parameter is shown as one row.
+- `@extract` — for type aliases that re-export a type from another package (typically walletkit). The renderer follows the alias to the original `interface` / `type` and uses **its** structure (field table or code block). `@public`/`@category`/`@section` still live on the alias; the source's JSDoc supplies field-level descriptions. See "Re-exporting from walletkit" below.
+- `@title <Override>` — override the top-level heading for this single symbol. Rarely needed; usually omit.
+
+`@param` accepts a `{@link X}`-as-type-override at the very start of its description (see below); `@returns` does **not** — see the warning in that section.
+
+---
+
+## Cross-reference syntax: `{@link X}`
+
+`{@link X}` becomes a markdown link to the `#x` anchor in the same reference. It works in two places:
+
+1. **Anywhere in a description** (summary, field doc, `@param` description, `@returns` description). The text reads `... see {@link getBalance} ...` and renders `... see [\`getBalance\`](#getbalance) ...`.
+
+2. **At the very start of `@param` description** — the link is extracted and used as the **Type column** for that row. The text after the link goes into the Description column.
+
+   ```ts
+   @param config - {@link AppKitConfig} Networks, connectors, providers and runtime flags.
+   ```
+
+   renders as:
+
+   | Parameter | Type | Description |
+   | --- | --- | --- |
+   | `config`* | [`AppKitConfig`](#appkitconfig) | Networks, connectors, providers and runtime flags. |
+
+   The TS-inferred type is replaced by the link. Use this when the inferred type is verbose or you want a cleaner cell.
+
+   ⚠ **Don't put `{@link X}` at the start of `@returns`.** ts-morph's JSDoc parser interprets a leading `{…}` as a legacy type annotation (`@returns {Type} desc`) and silently drops it from the comment text — both the type-override and the description disappear. Write the description as plain prose; the inferred return type is auto-linked anyway. If you really want to mention a type, put `{@link X}` mid-sentence: `@returns The wallet response carrying …`.
+
+`X` must name another `@public` symbol in the same reference — the generator does not validate this, so a typo or an undocumented target produces a dead link.
+
+---
+
+## Style rules
+
+- **One sentence per description.** Summary, `@param` description, field doc, `@returns` description — all collapse onto one line in the rendered table. Multi-paragraph JSDoc reads as a long ugly run-on. If you need a second clause, join with `;` or `—`.
+- **Self-contained sentences after `{@link X}`.** Capitalize the first word, end with a period. Don't write `{@link X} with foo` (renders as Description = `with foo` — fragment); write `{@link X} Foo and bar.`.
+- **No bullet lists, no fenced code, no tables in JSDoc descriptions.** They survive the markdown but break table rendering.
+- **No outright fabrication.** Don't claim methods or behavior that don't exist in the code; the reference is pulled directly from the JSDoc and any error there ships to readers.
+
+---
+
+## Worked example
+
+```ts
+/**
+ * Read the Toncoin balance of an arbitrary address — useful for wallets that aren't selected in AppKit (use {@link getBalance} for the selected wallet).
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetBalanceByAddressOptions} Target address and optional network.
+ * @returns Balance in TON as a human-readable decimal string.
+ *
+ * @sample docs/examples/src/appkit/actions/balances#GET_BALANCE_BY_ADDRESS
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Balances
+ */
+export const getBalanceByAddress = async (
+    appKit: AppKit,
+    options: GetBalanceByAddressOptions,
+): Promise<GetBalanceByAddressReturnType> => { /* ... */ };
+```
+
+```ts
+/**
+ * Constructor options for {@link AppKit} — networks, connectors, providers and runtime flags.
+ *
+ * @public
+ * @category Type
+ * @section Core
+ */
+export interface AppKitConfig {
+    /** Map of chain id to api-client config; if omitted, AppKit defaults to mainnet only. */
+    networks?: NetworkAdapters;
+
+    /** Wallet connectors registered at startup. */
+    connectors?: ConnectorInput[];
+
+    /** Default network connectors enforce on new connections; `undefined` to allow any. */
+    defaultNetwork?: Network;
+
+    /** Defi/onramp providers registered at startup. */
+    providers?: ProviderInput[];
+
+    /** Set to `true` to enable server-side rendering support. */
+    ssr?: boolean;
+}
+```
+
+---
+
+## Re-exporting from walletkit (`@extract`)
+
+Some types live in `@ton/walletkit` but are part of the `@ton/appkit` public API (e.g. `Network`, `NetworkAdapters`, `NetworkConfig`, `ApiClientConfig`). A bare `export { Network } from '@ton/walletkit'` will **not** appear in the appkit reference — `collect.ts` filters out symbols whose declaration lives outside the package. Use a local type alias plus `@extract` to surface them:
+
+```ts
+// packages/appkit/src/types/network.ts
+import type { NetworkAdapters as WalletkitNetworkAdapters } from '@ton/walletkit';
+
+/**
+ * @extract
+ * @public
+ * @category Type
+ * @section Networks
+ */
+export type NetworkAdapters = WalletkitNetworkAdapters;
+```
+
+What happens at generate time:
+
+1. The alias declaration sits in `appkit/src/`, so the package-boundary filter passes it.
+2. `@extract` tells `extractType` to follow the alias to the underlying walletkit `interface`/`type` and reuse its shape — fields show up in the reference table, JSDoc on each field is pulled from walletkit.
+3. `@public`/`@category`/`@section` are read from the alias (you control where it appears in the appkit reference, not walletkit).
+4. If the alias has its own summary on the JSDoc block, that takes precedence over walletkit's.
+
+For declaration-merged symbols (a value + same-named interface, like `Network`), keep the value side as a separate `export const`:
+
+```ts
+import type { Network as WalletkitNetwork } from '@ton/walletkit';
+import { Network as WalletkitNetworkValue } from '@ton/walletkit';
+
+/**
+ * @extract
+ * @public
+ * @category Type
+ * @section Networks
+ */
+export type Network = WalletkitNetwork;
+
+// Value side — `Network.mainnet()` etc.
+export const Network = WalletkitNetworkValue;
+```
+
+The cleanest form is a JSDoc-tagged ExportDeclaration — one block tags every symbol inside the same `export { … }`:
+
+```ts
+/**
+ * @extract
+ * @public
+ * @category Class
+ * @section Swap
+ */
+export { SwapError, SwapProvider, SwapManager } from '@ton/walletkit';
+
+/**
+ * @extract
+ * @public
+ * @category Type
+ * @section Swap
+ */
+export type { SwapToken, TokenAmount, SwapParams } from '@ton/walletkit';
+```
+
+Group symbols by `(category, section)` — one ExportDeclaration per group keeps the JSDoc shared.
+
+**Rebuild walletkit after editing its JSDoc.** ts-morph resolves cross-package symbols through `dist/.../*.d.ts`, not the source `*.ts`, so JSDoc edits in `packages/walletkit/src/...` only land in the reference after `pnpm --filter @ton/walletkit build`. For appkit-only edits (no walletkit changes), `pnpm docs:update` alone is enough.
+
+**Important**: `@extract` does NOT make a wildcard `export * from '@ton/appkit'` (used in appkit-react) leak appkit symbols into appkit-react. Wildcard re-exports cannot carry JSDoc, so they cannot carry `@extract`, so the boundary filter still drops them. The opt-in is local and explicit.
+
+---
+
+## After editing JSDoc
+
+Run `pnpm docs:update` (alias for `pnpm docs:reference && pnpm docs:template`). The first step regenerates `docs/templates/packages/<pkg>/docs/reference.md`; the second resolves `@sample` placeholders into real code blocks and writes the final `packages/<pkg>/docs/reference.md`.
+
+If validation fails, the script prints every problem in one go — fix them all before re-running.
+
+---
+
+## Quick checklist
+
+- [ ] `@public` present
+- [ ] `@category` set to one of `Class`, `Action`, `Hook`, `Component`, `Type`, `Constants`
+- [ ] `@section` set to a domain string (matches existing entries where appropriate)
+- [ ] Summary is one sentence with a trailing period
+- [ ] Each `@param` description is one self-contained sentence
+- [ ] `{@link X}` only used for symbols that are themselves `@public`
+- [ ] `@expand` used for any options-bag parameter you want flattened
+- [ ] `@extract` used for type aliases that re-export a walletkit type
+- [ ] `@sample` points to a real `// SAMPLE_START: NAME` block in `docs/examples/`
+- [ ] `pnpm docs:update` runs cleanly
diff --git a/demo/examples/.gitignore b/docs/examples/.gitignore
similarity index 100%
rename from demo/examples/.gitignore
rename to docs/examples/.gitignore
diff --git a/demo/examples/env.d.ts b/docs/examples/env.d.ts
similarity index 100%
rename from demo/examples/env.d.ts
rename to docs/examples/env.d.ts
diff --git a/demo/examples/index.html b/docs/examples/index.html
similarity index 100%
rename from demo/examples/index.html
rename to docs/examples/index.html
diff --git a/demo/examples/package.json b/docs/examples/package.json
similarity index 100%
rename from demo/examples/package.json
rename to docs/examples/package.json
diff --git a/demo/examples/src/__mocks__/@ton/walletkit.ts b/docs/examples/src/__mocks__/@ton/walletkit.ts
similarity index 100%
rename from demo/examples/src/__mocks__/@ton/walletkit.ts
rename to docs/examples/src/__mocks__/@ton/walletkit.ts
diff --git a/demo/examples/src/__mocks__/@tonconnect/sdk.ts b/docs/examples/src/__mocks__/@tonconnect/sdk.ts
similarity index 100%
rename from demo/examples/src/__mocks__/@tonconnect/sdk.ts
rename to docs/examples/src/__mocks__/@tonconnect/sdk.ts
diff --git a/demo/examples/src/__mocks__/@tonconnect/ui-react.ts b/docs/examples/src/__mocks__/@tonconnect/ui-react.ts
similarity index 100%
rename from demo/examples/src/__mocks__/@tonconnect/ui-react.ts
rename to docs/examples/src/__mocks__/@tonconnect/ui-react.ts
diff --git a/demo/examples/src/__tests__/initialize.test.ts b/docs/examples/src/__tests__/initialize.test.ts
similarity index 100%
rename from demo/examples/src/__tests__/initialize.test.ts
rename to docs/examples/src/__tests__/initialize.test.ts
diff --git a/demo/examples/src/__tests__/jettons.test.ts b/docs/examples/src/__tests__/jettons.test.ts
similarity index 100%
rename from demo/examples/src/__tests__/jettons.test.ts
rename to docs/examples/src/__tests__/jettons.test.ts
diff --git a/demo/examples/src/__tests__/requests.test.ts b/docs/examples/src/__tests__/requests.test.ts
similarity index 100%
rename from demo/examples/src/__tests__/requests.test.ts
rename to docs/examples/src/__tests__/requests.test.ts
diff --git a/demo/examples/src/__tests__/setup.ts b/docs/examples/src/__tests__/setup.ts
similarity index 100%
rename from demo/examples/src/__tests__/setup.ts
rename to docs/examples/src/__tests__/setup.ts
diff --git a/demo/examples/src/__tests__/test-utils.tsx b/docs/examples/src/__tests__/test-utils.tsx
similarity index 100%
rename from demo/examples/src/__tests__/test-utils.tsx
rename to docs/examples/src/__tests__/test-utils.tsx
diff --git a/demo/examples/src/__tests__/transfers.test.ts b/docs/examples/src/__tests__/transfers.test.ts
similarity index 100%
rename from demo/examples/src/__tests__/transfers.test.ts
rename to docs/examples/src/__tests__/transfers.test.ts
diff --git a/demo/examples/src/__tests__/ui-state-wiring.test.ts b/docs/examples/src/__tests__/ui-state-wiring.test.ts
similarity index 100%
rename from demo/examples/src/__tests__/ui-state-wiring.test.ts
rename to docs/examples/src/__tests__/ui-state-wiring.test.ts
diff --git a/demo/examples/src/__tests__/ui.test.ts b/docs/examples/src/__tests__/ui.test.ts
similarity index 100%
rename from demo/examples/src/__tests__/ui.test.ts
rename to docs/examples/src/__tests__/ui.test.ts
diff --git a/demo/examples/src/__tests__/wallet-kit-initialize-sample.test.ts b/docs/examples/src/__tests__/wallet-kit-initialize-sample.test.ts
similarity index 100%
rename from demo/examples/src/__tests__/wallet-kit-initialize-sample.test.ts
rename to docs/examples/src/__tests__/wallet-kit-initialize-sample.test.ts
diff --git a/demo/examples/src/appkit/actions/balances/balances.test.ts b/docs/examples/src/appkit/actions/balances/balances.test.ts
similarity index 92%
rename from demo/examples/src/appkit/actions/balances/balances.test.ts
rename to docs/examples/src/appkit/actions/balances/balances.test.ts
index 625e0a859..08932e82a 100644
--- a/demo/examples/src/appkit/actions/balances/balances.test.ts
+++ b/docs/examples/src/appkit/actions/balances/balances.test.ts
@@ -63,11 +63,8 @@ describe('Balance Actions Examples (Integration)', () => {
 
             appKit.walletsManager.setWallets([mockWallet]);
 
-            // Setup balance response
-            // Using a simple object that mimics TokenAmount to avoid constructor issues if any,
-            // or we could use `new TokenAmount(1000000000n, 9)` if available.
-            // Since we test the example which calls .toString(), this is sufficient.
-            const balanceValue = { toString: () => '1000000000' } as TokenAmount;
+            // Setup balance response. TokenAmount is a string alias.
+            const balanceValue: TokenAmount = '1000000000';
             mockGetBalance.mockResolvedValue(balanceValue);
 
             await getBalanceExample(appKit);
diff --git a/demo/examples/src/appkit/actions/balances/get-balance-by-address.ts b/docs/examples/src/appkit/actions/balances/get-balance-by-address.ts
similarity index 86%
rename from demo/examples/src/appkit/actions/balances/get-balance-by-address.ts
rename to docs/examples/src/appkit/actions/balances/get-balance-by-address.ts
index 972f71e84..eb08ec524 100644
--- a/demo/examples/src/appkit/actions/balances/get-balance-by-address.ts
+++ b/docs/examples/src/appkit/actions/balances/get-balance-by-address.ts
@@ -12,8 +12,8 @@ import { getBalanceByAddress } from '@ton/appkit';
 export const getBalanceByAddressExample = async (appKit: AppKit) => {
     // SAMPLE_START: GET_BALANCE_BY_ADDRESS
     const balanceByAddress = await getBalanceByAddress(appKit, {
-        address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c', // Zero Address
+        address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
     });
-    console.log('Balance by address:', balanceByAddress.toString());
+    console.log('Balance by address:', balanceByAddress);
     // SAMPLE_END: GET_BALANCE_BY_ADDRESS
 };
diff --git a/demo/examples/src/appkit/actions/balances/get-balance.ts b/docs/examples/src/appkit/actions/balances/get-balance.ts
similarity index 89%
rename from demo/examples/src/appkit/actions/balances/get-balance.ts
rename to docs/examples/src/appkit/actions/balances/get-balance.ts
index 418c85f36..ed4ff847e 100644
--- a/demo/examples/src/appkit/actions/balances/get-balance.ts
+++ b/docs/examples/src/appkit/actions/balances/get-balance.ts
@@ -13,7 +13,7 @@ export const getBalanceExample = async (appKit: AppKit) => {
     // SAMPLE_START: GET_BALANCE
     const balance = await getBalance(appKit);
     if (balance) {
-        console.log('Balance:', balance.toString());
+        console.log('Balance:', balance);
     }
     // SAMPLE_END: GET_BALANCE
 };
diff --git a/demo/examples/src/appkit/actions/balances/watch-balance-by-address.ts b/docs/examples/src/appkit/actions/balances/watch-balance-by-address.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/balances/watch-balance-by-address.ts
rename to docs/examples/src/appkit/actions/balances/watch-balance-by-address.ts
diff --git a/demo/examples/src/appkit/actions/balances/watch-balance.ts b/docs/examples/src/appkit/actions/balances/watch-balance.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/balances/watch-balance.ts
rename to docs/examples/src/appkit/actions/balances/watch-balance.ts
diff --git a/demo/examples/src/appkit/actions/connectors/add-connector.ts b/docs/examples/src/appkit/actions/connectors/add-connector.ts
similarity index 87%
rename from demo/examples/src/appkit/actions/connectors/add-connector.ts
rename to docs/examples/src/appkit/actions/connectors/add-connector.ts
index 5318c3e51..9d76c9ec1 100644
--- a/demo/examples/src/appkit/actions/connectors/add-connector.ts
+++ b/docs/examples/src/appkit/actions/connectors/add-connector.ts
@@ -12,7 +12,7 @@ import { createTonConnectConnector } from '@ton/appkit';
 
 export const addConnectorExample = (appKit: AppKit) => {
     // SAMPLE_START: ADD_CONNECTOR
-    const stopWatching = addConnector(
+    const unregister = addConnector(
         appKit,
         createTonConnectConnector({
             tonConnectOptions: {
@@ -21,7 +21,7 @@ export const addConnectorExample = (appKit: AppKit) => {
         }),
     );
 
-    // Later: stopWatching();
+    // Later: unregister();
     // SAMPLE_END: ADD_CONNECTOR
-    return stopWatching;
+    return unregister;
 };
diff --git a/demo/examples/src/appkit/actions/connectors/connect.ts b/docs/examples/src/appkit/actions/connectors/connect.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/connectors/connect.ts
rename to docs/examples/src/appkit/actions/connectors/connect.ts
diff --git a/demo/examples/src/appkit/actions/connectors/connectors.test.ts b/docs/examples/src/appkit/actions/connectors/connectors.test.ts
similarity index 88%
rename from demo/examples/src/appkit/actions/connectors/connectors.test.ts
rename to docs/examples/src/appkit/actions/connectors/connectors.test.ts
index 223439185..1240ae912 100644
--- a/demo/examples/src/appkit/actions/connectors/connectors.test.ts
+++ b/docs/examples/src/appkit/actions/connectors/connectors.test.ts
@@ -94,14 +94,7 @@ describe('Connector Actions Examples (Integration)', () => {
             watchConnectorsExample(appKit);
 
             // Trigger event
-            appKit.emitter.emit(
-                CONNECTOR_EVENTS.CONNECTED,
-                {
-                    wallets: [],
-                    connectorId: 'test',
-                },
-                'test',
-            );
+            appKit.emitter.emit(CONNECTOR_EVENTS.ADDED, { connector: mockConnector }, 'test');
 
             expect(consoleSpy).toHaveBeenCalledWith('Connectors updated:', expect.arrayContaining([mockConnector]));
         });
@@ -112,14 +105,7 @@ describe('Connector Actions Examples (Integration)', () => {
             watchConnectorByIdExample(appKit);
 
             // Trigger event
-            appKit.emitter.emit(
-                CONNECTOR_EVENTS.CONNECTED,
-                {
-                    wallets: [],
-                    connectorId: 'test',
-                },
-                'test',
-            );
+            appKit.emitter.emit(CONNECTOR_EVENTS.ADDED, { connector: mockConnector }, 'test');
 
             expect(consoleSpy).toHaveBeenCalledWith('Connector updated:', mockConnector);
         });
diff --git a/demo/examples/src/appkit/actions/connectors/disconnect.ts b/docs/examples/src/appkit/actions/connectors/disconnect.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/connectors/disconnect.ts
rename to docs/examples/src/appkit/actions/connectors/disconnect.ts
diff --git a/demo/examples/src/appkit/actions/connectors/get-connector-by-id.ts b/docs/examples/src/appkit/actions/connectors/get-connector-by-id.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/connectors/get-connector-by-id.ts
rename to docs/examples/src/appkit/actions/connectors/get-connector-by-id.ts
diff --git a/demo/examples/src/appkit/actions/connectors/get-connectors.ts b/docs/examples/src/appkit/actions/connectors/get-connectors.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/connectors/get-connectors.ts
rename to docs/examples/src/appkit/actions/connectors/get-connectors.ts
diff --git a/demo/examples/src/appkit/actions/connectors/watch-connector-by-id.ts b/docs/examples/src/appkit/actions/connectors/watch-connector-by-id.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/connectors/watch-connector-by-id.ts
rename to docs/examples/src/appkit/actions/connectors/watch-connector-by-id.ts
diff --git a/demo/examples/src/appkit/actions/connectors/watch-connectors.ts b/docs/examples/src/appkit/actions/connectors/watch-connectors.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/connectors/watch-connectors.ts
rename to docs/examples/src/appkit/actions/connectors/watch-connectors.ts
diff --git a/demo/examples/src/appkit/actions/jettons/create-transfer-jetton-transaction.ts b/docs/examples/src/appkit/actions/jettons/create-transfer-jetton-transaction.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/jettons/create-transfer-jetton-transaction.ts
rename to docs/examples/src/appkit/actions/jettons/create-transfer-jetton-transaction.ts
diff --git a/demo/examples/src/appkit/actions/jettons/get-jetton-balance.ts b/docs/examples/src/appkit/actions/jettons/get-jetton-balance.ts
similarity index 93%
rename from demo/examples/src/appkit/actions/jettons/get-jetton-balance.ts
rename to docs/examples/src/appkit/actions/jettons/get-jetton-balance.ts
index 17219d3f6..c45daaec9 100644
--- a/demo/examples/src/appkit/actions/jettons/get-jetton-balance.ts
+++ b/docs/examples/src/appkit/actions/jettons/get-jetton-balance.ts
@@ -22,6 +22,6 @@ export const getJettonBalanceExample = async (appKit: AppKit) => {
         ownerAddress: selectedWallet.getAddress(),
         jettonDecimals: 6,
     });
-    console.log('Jetton Balance:', balance.toString());
+    console.log('Jetton Balance:', balance);
     // SAMPLE_END: GET_JETTON_BALANCE
 };
diff --git a/demo/examples/src/appkit/actions/jettons/get-jetton-info.ts b/docs/examples/src/appkit/actions/jettons/get-jetton-info.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/jettons/get-jetton-info.ts
rename to docs/examples/src/appkit/actions/jettons/get-jetton-info.ts
diff --git a/demo/examples/src/appkit/actions/jettons/get-jetton-wallet-address.ts b/docs/examples/src/appkit/actions/jettons/get-jetton-wallet-address.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/jettons/get-jetton-wallet-address.ts
rename to docs/examples/src/appkit/actions/jettons/get-jetton-wallet-address.ts
diff --git a/demo/examples/src/appkit/actions/jettons/get-jettons-by-address.ts b/docs/examples/src/appkit/actions/jettons/get-jettons-by-address.ts
similarity index 96%
rename from demo/examples/src/appkit/actions/jettons/get-jettons-by-address.ts
rename to docs/examples/src/appkit/actions/jettons/get-jettons-by-address.ts
index 4367b8b91..516fa322e 100644
--- a/demo/examples/src/appkit/actions/jettons/get-jettons-by-address.ts
+++ b/docs/examples/src/appkit/actions/jettons/get-jettons-by-address.ts
@@ -21,6 +21,6 @@ export const getJettonsByAddressExample = async (appKit: AppKit) => {
         address: selectedWallet.getAddress(),
     });
     console.log('Jettons by Address:', response.jettons.length);
-    response.jettons.forEach((j) => console.log(`- ${j.info.name}: ${j.balance.toString()}`));
+    response.jettons.forEach((j) => console.log(`- ${j.info.name}: ${j.balance}`));
     // SAMPLE_END: GET_JETTONS_BY_ADDRESS
 };
diff --git a/demo/examples/src/appkit/actions/jettons/get-jettons.ts b/docs/examples/src/appkit/actions/jettons/get-jettons.ts
similarity index 95%
rename from demo/examples/src/appkit/actions/jettons/get-jettons.ts
rename to docs/examples/src/appkit/actions/jettons/get-jettons.ts
index fcd63ac6e..abece18c1 100644
--- a/demo/examples/src/appkit/actions/jettons/get-jettons.ts
+++ b/docs/examples/src/appkit/actions/jettons/get-jettons.ts
@@ -17,6 +17,6 @@ export const getJettonsExample = async (appKit: AppKit) => {
         return;
     }
     console.log('Jettons:', response.jettons.length);
-    response.jettons.forEach((j) => console.log(`- ${j.info.name}: ${j.balance.toString()}`));
+    response.jettons.forEach((j) => console.log(`- ${j.info.name}: ${j.balance}`));
     // SAMPLE_END: GET_JETTONS
 };
diff --git a/demo/examples/src/appkit/actions/jettons/jettons.test.ts b/docs/examples/src/appkit/actions/jettons/jettons.test.ts
similarity index 98%
rename from demo/examples/src/appkit/actions/jettons/jettons.test.ts
rename to docs/examples/src/appkit/actions/jettons/jettons.test.ts
index 60816b075..0714c5f20 100644
--- a/demo/examples/src/appkit/actions/jettons/jettons.test.ts
+++ b/docs/examples/src/appkit/actions/jettons/jettons.test.ts
@@ -139,10 +139,7 @@ describe('Jetton Actions Examples (Integration)', () => {
                 'get_wallet_address',
                 expect.any(Array),
             );
-            expect(consoleSpy).toHaveBeenCalledWith(
-                'Jetton Wallet Address:',
-                Address.parse(JETTON_WALLET_ADDRESS).toString(),
-            );
+            expect(consoleSpy).toHaveBeenCalledWith('Jetton Wallet Address:', JETTON_WALLET_ADDRESS);
         });
 
         it('should log message if no wallet selected', async () => {
diff --git a/demo/examples/src/appkit/actions/jettons/transfer-jetton.ts b/docs/examples/src/appkit/actions/jettons/transfer-jetton.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/jettons/transfer-jetton.ts
rename to docs/examples/src/appkit/actions/jettons/transfer-jetton.ts
diff --git a/demo/examples/src/appkit/actions/network/get-api-client.ts b/docs/examples/src/appkit/actions/network/get-api-client.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/network/get-api-client.ts
rename to docs/examples/src/appkit/actions/network/get-api-client.ts
diff --git a/demo/examples/src/appkit/actions/network/get-block-number.ts b/docs/examples/src/appkit/actions/network/get-block-number.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/network/get-block-number.ts
rename to docs/examples/src/appkit/actions/network/get-block-number.ts
diff --git a/demo/examples/src/appkit/actions/network/get-default-network.ts b/docs/examples/src/appkit/actions/network/get-default-network.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/network/get-default-network.ts
rename to docs/examples/src/appkit/actions/network/get-default-network.ts
diff --git a/demo/examples/src/appkit/actions/network/get-network.ts b/docs/examples/src/appkit/actions/network/get-network.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/network/get-network.ts
rename to docs/examples/src/appkit/actions/network/get-network.ts
diff --git a/demo/examples/src/appkit/actions/network/get-networks.ts b/docs/examples/src/appkit/actions/network/get-networks.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/network/get-networks.ts
rename to docs/examples/src/appkit/actions/network/get-networks.ts
diff --git a/demo/examples/src/appkit/actions/network/has-streaming-provider.ts b/docs/examples/src/appkit/actions/network/has-streaming-provider.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/network/has-streaming-provider.ts
rename to docs/examples/src/appkit/actions/network/has-streaming-provider.ts
diff --git a/demo/examples/src/appkit/actions/network/network.test.ts b/docs/examples/src/appkit/actions/network/network.test.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/network/network.test.ts
rename to docs/examples/src/appkit/actions/network/network.test.ts
diff --git a/demo/examples/src/appkit/actions/network/set-default-network.ts b/docs/examples/src/appkit/actions/network/set-default-network.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/network/set-default-network.ts
rename to docs/examples/src/appkit/actions/network/set-default-network.ts
diff --git a/demo/examples/src/appkit/actions/network/watch-default-network.ts b/docs/examples/src/appkit/actions/network/watch-default-network.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/network/watch-default-network.ts
rename to docs/examples/src/appkit/actions/network/watch-default-network.ts
diff --git a/demo/examples/src/appkit/actions/network/watch-networks.ts b/docs/examples/src/appkit/actions/network/watch-networks.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/network/watch-networks.ts
rename to docs/examples/src/appkit/actions/network/watch-networks.ts
diff --git a/demo/examples/src/appkit/actions/nft/create-transfer-nft-transaction.ts b/docs/examples/src/appkit/actions/nft/create-transfer-nft-transaction.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/nft/create-transfer-nft-transaction.ts
rename to docs/examples/src/appkit/actions/nft/create-transfer-nft-transaction.ts
diff --git a/demo/examples/src/appkit/actions/nft/get-nft.ts b/docs/examples/src/appkit/actions/nft/get-nft.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/nft/get-nft.ts
rename to docs/examples/src/appkit/actions/nft/get-nft.ts
diff --git a/demo/examples/src/appkit/actions/nft/get-nfts-by-address.ts b/docs/examples/src/appkit/actions/nft/get-nfts-by-address.ts
similarity index 96%
rename from demo/examples/src/appkit/actions/nft/get-nfts-by-address.ts
rename to docs/examples/src/appkit/actions/nft/get-nfts-by-address.ts
index 0880e14e3..0283da8f0 100644
--- a/demo/examples/src/appkit/actions/nft/get-nfts-by-address.ts
+++ b/docs/examples/src/appkit/actions/nft/get-nfts-by-address.ts
@@ -12,7 +12,7 @@ import { getNftsByAddress } from '@ton/appkit';
 export const getNftsByAddressExample = async (appKit: AppKit) => {
     // SAMPLE_START: GET_NFTS_BY_ADDRESS
     const response = await getNftsByAddress(appKit, {
-        address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c', // Zero Address
+        address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
     });
 
     console.log('NFTs by address:', response.nfts.length);
diff --git a/demo/examples/src/appkit/actions/nft/get-nfts.ts b/docs/examples/src/appkit/actions/nft/get-nfts.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/nft/get-nfts.ts
rename to docs/examples/src/appkit/actions/nft/get-nfts.ts
diff --git a/demo/examples/src/appkit/actions/nft/nfts.test.ts b/docs/examples/src/appkit/actions/nft/nfts.test.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/nft/nfts.test.ts
rename to docs/examples/src/appkit/actions/nft/nfts.test.ts
diff --git a/demo/examples/src/appkit/actions/nft/transfer-nft.ts b/docs/examples/src/appkit/actions/nft/transfer-nft.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/nft/transfer-nft.ts
rename to docs/examples/src/appkit/actions/nft/transfer-nft.ts
diff --git a/demo/examples/src/appkit/actions/onramp/build-onramp-url.ts b/docs/examples/src/appkit/actions/onramp/build-onramp-url.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/onramp/build-onramp-url.ts
rename to docs/examples/src/appkit/actions/onramp/build-onramp-url.ts
diff --git a/demo/examples/src/appkit/actions/onramp/get-crypto-onramp-provider.ts b/docs/examples/src/appkit/actions/onramp/get-crypto-onramp-provider.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/onramp/get-crypto-onramp-provider.ts
rename to docs/examples/src/appkit/actions/onramp/get-crypto-onramp-provider.ts
diff --git a/demo/examples/src/appkit/actions/onramp/get-crypto-onramp-providers.ts b/docs/examples/src/appkit/actions/onramp/get-crypto-onramp-providers.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/onramp/get-crypto-onramp-providers.ts
rename to docs/examples/src/appkit/actions/onramp/get-crypto-onramp-providers.ts
diff --git a/demo/examples/src/appkit/actions/onramp/get-onramp-quote.ts b/docs/examples/src/appkit/actions/onramp/get-onramp-quote.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/onramp/get-onramp-quote.ts
rename to docs/examples/src/appkit/actions/onramp/get-onramp-quote.ts
diff --git a/demo/examples/src/appkit/actions/providers/register-provider.ts b/docs/examples/src/appkit/actions/providers/register-provider.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/providers/register-provider.ts
rename to docs/examples/src/appkit/actions/providers/register-provider.ts
diff --git a/demo/examples/src/appkit/actions/signing/sign-binary.ts b/docs/examples/src/appkit/actions/signing/sign-binary.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/signing/sign-binary.ts
rename to docs/examples/src/appkit/actions/signing/sign-binary.ts
diff --git a/demo/examples/src/appkit/actions/signing/sign-cell.ts b/docs/examples/src/appkit/actions/signing/sign-cell.ts
similarity index 99%
rename from demo/examples/src/appkit/actions/signing/sign-cell.ts
rename to docs/examples/src/appkit/actions/signing/sign-cell.ts
index cae624602..9b1e54f7b 100644
--- a/demo/examples/src/appkit/actions/signing/sign-cell.ts
+++ b/docs/examples/src/appkit/actions/signing/sign-cell.ts
@@ -12,7 +12,7 @@ import { signCell } from '@ton/appkit';
 export const signCellExample = async (appKit: AppKit) => {
     // SAMPLE_START: SIGN_CELL
     const result = await signCell(appKit, {
-        cell: 'te6ccgEBAQEAAgAAGA==' as Base64String, // Example BOC
+        cell: 'te6ccgEBAQEAAgAAGA==' as Base64String, // Example BoC
         schema: 'transfer#abc123 amount:uint64 = Transfer',
     });
 
diff --git a/demo/examples/src/appkit/actions/signing/sign-text.ts b/docs/examples/src/appkit/actions/signing/sign-text.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/signing/sign-text.ts
rename to docs/examples/src/appkit/actions/signing/sign-text.ts
diff --git a/demo/examples/src/appkit/actions/signing/signing.test.ts b/docs/examples/src/appkit/actions/signing/signing.test.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/signing/signing.test.ts
rename to docs/examples/src/appkit/actions/signing/signing.test.ts
diff --git a/demo/examples/src/appkit/actions/staking/staking-actions.ts b/docs/examples/src/appkit/actions/staking/staking-actions.ts
similarity index 97%
rename from demo/examples/src/appkit/actions/staking/staking-actions.ts
rename to docs/examples/src/appkit/actions/staking/staking-actions.ts
index 6c3d59c1a..774bbdee8 100644
--- a/demo/examples/src/appkit/actions/staking/staking-actions.ts
+++ b/docs/examples/src/appkit/actions/staking/staking-actions.ts
@@ -20,7 +20,7 @@ export const stakingExample = async (appKit: AppKit) => {
     const userAddress = 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c';
 
     // SAMPLE_START: GET_STAKING_PROVIDERS
-    const providers = await getStakingProviders(appKit);
+    const providers = getStakingProviders(appKit);
     console.log('Available Staking Providers:', providers);
     // SAMPLE_END: GET_STAKING_PROVIDERS
 
diff --git a/demo/examples/src/appkit/actions/staking/staking.test.ts b/docs/examples/src/appkit/actions/staking/staking.test.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/staking/staking.test.ts
rename to docs/examples/src/appkit/actions/staking/staking.test.ts
diff --git a/demo/examples/src/appkit/actions/swap/swap-actions.ts b/docs/examples/src/appkit/actions/swap/swap-actions.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/swap/swap-actions.ts
rename to docs/examples/src/appkit/actions/swap/swap-actions.ts
diff --git a/demo/examples/src/appkit/actions/swap/swap.test.ts b/docs/examples/src/appkit/actions/swap/swap.test.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/swap/swap.test.ts
rename to docs/examples/src/appkit/actions/swap/swap.test.ts
diff --git a/demo/examples/src/appkit/actions/transaction/create-transfer-ton-transaction.ts b/docs/examples/src/appkit/actions/transaction/create-transfer-ton-transaction.ts
similarity index 91%
rename from demo/examples/src/appkit/actions/transaction/create-transfer-ton-transaction.ts
rename to docs/examples/src/appkit/actions/transaction/create-transfer-ton-transaction.ts
index f2b47af87..1e18aa9d9 100644
--- a/demo/examples/src/appkit/actions/transaction/create-transfer-ton-transaction.ts
+++ b/docs/examples/src/appkit/actions/transaction/create-transfer-ton-transaction.ts
@@ -11,7 +11,7 @@ import { createTransferTonTransaction } from '@ton/appkit';
 
 export const createTransferTonTransactionExample = async (appKit: AppKit) => {
     // SAMPLE_START: CREATE_TRANSFER_TON_TRANSACTION
-    const tx = await createTransferTonTransaction(appKit, {
+    const tx = createTransferTonTransaction(appKit, {
         recipientAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
         amount: '0.1', // 0.1 TON (human-readable format)
         comment: 'Draft transaction',
diff --git a/demo/examples/src/appkit/actions/transaction/send-transaction.ts b/docs/examples/src/appkit/actions/transaction/send-transaction.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/transaction/send-transaction.ts
rename to docs/examples/src/appkit/actions/transaction/send-transaction.ts
diff --git a/demo/examples/src/appkit/actions/transaction/transaction.test.ts b/docs/examples/src/appkit/actions/transaction/transaction.test.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/transaction/transaction.test.ts
rename to docs/examples/src/appkit/actions/transaction/transaction.test.ts
diff --git a/demo/examples/src/appkit/actions/transaction/transfer-ton.ts b/docs/examples/src/appkit/actions/transaction/transfer-ton.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/transaction/transfer-ton.ts
rename to docs/examples/src/appkit/actions/transaction/transfer-ton.ts
diff --git a/demo/examples/src/appkit/actions/wallets/get-connected-wallets.ts b/docs/examples/src/appkit/actions/wallets/get-connected-wallets.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/wallets/get-connected-wallets.ts
rename to docs/examples/src/appkit/actions/wallets/get-connected-wallets.ts
diff --git a/demo/examples/src/appkit/actions/wallets/get-selected-wallet.ts b/docs/examples/src/appkit/actions/wallets/get-selected-wallet.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/wallets/get-selected-wallet.ts
rename to docs/examples/src/appkit/actions/wallets/get-selected-wallet.ts
diff --git a/demo/examples/src/appkit/actions/wallets/set-selected-wallet-id.ts b/docs/examples/src/appkit/actions/wallets/set-selected-wallet-id.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/wallets/set-selected-wallet-id.ts
rename to docs/examples/src/appkit/actions/wallets/set-selected-wallet-id.ts
diff --git a/demo/examples/src/appkit/actions/wallets/wallets.test.ts b/docs/examples/src/appkit/actions/wallets/wallets.test.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/wallets/wallets.test.ts
rename to docs/examples/src/appkit/actions/wallets/wallets.test.ts
diff --git a/demo/examples/src/appkit/actions/wallets/watch-connected-wallets.ts b/docs/examples/src/appkit/actions/wallets/watch-connected-wallets.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/wallets/watch-connected-wallets.ts
rename to docs/examples/src/appkit/actions/wallets/watch-connected-wallets.ts
diff --git a/demo/examples/src/appkit/actions/wallets/watch-selected-wallet.ts b/docs/examples/src/appkit/actions/wallets/watch-selected-wallet.ts
similarity index 100%
rename from demo/examples/src/appkit/actions/wallets/watch-selected-wallet.ts
rename to docs/examples/src/appkit/actions/wallets/watch-selected-wallet.ts
diff --git a/demo/examples/src/appkit/components/balances/balances.test.tsx b/docs/examples/src/appkit/components/balances/balances.test.tsx
similarity index 100%
rename from demo/examples/src/appkit/components/balances/balances.test.tsx
rename to docs/examples/src/appkit/components/balances/balances.test.tsx
diff --git a/demo/examples/src/appkit/components/balances/send-jetton-button.tsx b/docs/examples/src/appkit/components/balances/send-jetton-button.tsx
similarity index 100%
rename from demo/examples/src/appkit/components/balances/send-jetton-button.tsx
rename to docs/examples/src/appkit/components/balances/send-jetton-button.tsx
diff --git a/demo/examples/src/appkit/components/balances/send-ton-button.tsx b/docs/examples/src/appkit/components/balances/send-ton-button.tsx
similarity index 100%
rename from demo/examples/src/appkit/components/balances/send-ton-button.tsx
rename to docs/examples/src/appkit/components/balances/send-ton-button.tsx
diff --git a/demo/examples/src/appkit/components/providers/app-kit-provider.tsx b/docs/examples/src/appkit/components/providers/app-kit-provider.tsx
similarity index 100%
rename from demo/examples/src/appkit/components/providers/app-kit-provider.tsx
rename to docs/examples/src/appkit/components/providers/app-kit-provider.tsx
diff --git a/demo/examples/src/appkit/components/transaction/transaction.test.tsx b/docs/examples/src/appkit/components/transaction/transaction.test.tsx
similarity index 100%
rename from demo/examples/src/appkit/components/transaction/transaction.test.tsx
rename to docs/examples/src/appkit/components/transaction/transaction.test.tsx
diff --git a/demo/examples/src/appkit/components/transaction/transaction.tsx b/docs/examples/src/appkit/components/transaction/transaction.tsx
similarity index 100%
rename from demo/examples/src/appkit/components/transaction/transaction.tsx
rename to docs/examples/src/appkit/components/transaction/transaction.tsx
diff --git a/demo/examples/src/appkit/components/wallets/connect-button.tsx b/docs/examples/src/appkit/components/wallets/connect-button.tsx
similarity index 100%
rename from demo/examples/src/appkit/components/wallets/connect-button.tsx
rename to docs/examples/src/appkit/components/wallets/connect-button.tsx
diff --git a/demo/examples/src/appkit/connectors/tonconnect/connector.ts b/docs/examples/src/appkit/connectors/tonconnect/connector.ts
similarity index 100%
rename from demo/examples/src/appkit/connectors/tonconnect/connector.ts
rename to docs/examples/src/appkit/connectors/tonconnect/connector.ts
diff --git a/demo/examples/src/appkit/hooks/balances/balances.test.tsx b/docs/examples/src/appkit/hooks/balances/balances.test.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/balances/balances.test.tsx
rename to docs/examples/src/appkit/hooks/balances/balances.test.tsx
diff --git a/demo/examples/src/appkit/hooks/balances/use-balance-by-address.tsx b/docs/examples/src/appkit/hooks/balances/use-balance-by-address.tsx
similarity index 92%
rename from demo/examples/src/appkit/hooks/balances/use-balance-by-address.tsx
rename to docs/examples/src/appkit/hooks/balances/use-balance-by-address.tsx
index 1eafbf243..4847cec37 100644
--- a/demo/examples/src/appkit/hooks/balances/use-balance-by-address.tsx
+++ b/docs/examples/src/appkit/hooks/balances/use-balance-by-address.tsx
@@ -26,6 +26,6 @@ export const UseBalanceByAddressExample = () => {
         return <div>Error: {error.message}</div>;
     }
 
-    return <div>Balance: {balance?.toString()}</div>;
+    return <div>Balance: {balance}</div>;
     // SAMPLE_END: USE_BALANCE_BY_ADDRESS
 };
diff --git a/demo/examples/src/appkit/hooks/balances/use-balance.tsx b/docs/examples/src/appkit/hooks/balances/use-balance.tsx
similarity index 90%
rename from demo/examples/src/appkit/hooks/balances/use-balance.tsx
rename to docs/examples/src/appkit/hooks/balances/use-balance.tsx
index d924eda3d..213b7d90e 100644
--- a/demo/examples/src/appkit/hooks/balances/use-balance.tsx
+++ b/docs/examples/src/appkit/hooks/balances/use-balance.tsx
@@ -20,6 +20,6 @@ export const UseBalanceExample = () => {
         return <div>Error: {error.message}</div>;
     }
 
-    return <div>Balance: {balance?.toString()}</div>;
+    return <div>Balance: {balance}</div>;
     // SAMPLE_END: USE_BALANCE
 };
diff --git a/demo/examples/src/appkit/hooks/balances/use-watch-balance-by-address.tsx b/docs/examples/src/appkit/hooks/balances/use-watch-balance-by-address.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/balances/use-watch-balance-by-address.tsx
rename to docs/examples/src/appkit/hooks/balances/use-watch-balance-by-address.tsx
diff --git a/demo/examples/src/appkit/hooks/balances/use-watch-balance.tsx b/docs/examples/src/appkit/hooks/balances/use-watch-balance.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/balances/use-watch-balance.tsx
rename to docs/examples/src/appkit/hooks/balances/use-watch-balance.tsx
diff --git a/demo/examples/src/appkit/hooks/core/use-app-kit-theme.tsx b/docs/examples/src/appkit/hooks/core/use-app-kit-theme.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/core/use-app-kit-theme.tsx
rename to docs/examples/src/appkit/hooks/core/use-app-kit-theme.tsx
diff --git a/demo/examples/src/appkit/hooks/core/use-app-kit.tsx b/docs/examples/src/appkit/hooks/core/use-app-kit.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/core/use-app-kit.tsx
rename to docs/examples/src/appkit/hooks/core/use-app-kit.tsx
diff --git a/demo/examples/src/appkit/hooks/jettons/jettons.test.tsx b/docs/examples/src/appkit/hooks/jettons/jettons.test.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/jettons/jettons.test.tsx
rename to docs/examples/src/appkit/hooks/jettons/jettons.test.tsx
diff --git a/demo/examples/src/appkit/hooks/jettons/use-jetton-balance-by-address.tsx b/docs/examples/src/appkit/hooks/jettons/use-jetton-balance-by-address.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/jettons/use-jetton-balance-by-address.tsx
rename to docs/examples/src/appkit/hooks/jettons/use-jetton-balance-by-address.tsx
diff --git a/demo/examples/src/appkit/hooks/jettons/use-jetton-info.tsx b/docs/examples/src/appkit/hooks/jettons/use-jetton-info.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/jettons/use-jetton-info.tsx
rename to docs/examples/src/appkit/hooks/jettons/use-jetton-info.tsx
diff --git a/demo/examples/src/appkit/hooks/jettons/use-jetton-wallet-address.tsx b/docs/examples/src/appkit/hooks/jettons/use-jetton-wallet-address.tsx
similarity index 76%
rename from demo/examples/src/appkit/hooks/jettons/use-jetton-wallet-address.tsx
rename to docs/examples/src/appkit/hooks/jettons/use-jetton-wallet-address.tsx
index 06f1fbde4..fe6da79ef 100644
--- a/demo/examples/src/appkit/hooks/jettons/use-jetton-wallet-address.tsx
+++ b/docs/examples/src/appkit/hooks/jettons/use-jetton-wallet-address.tsx
@@ -6,14 +6,6 @@
  *
  */
 
-/**
- * Copyright (c) TonTech.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- *
- */
-
 import { useJettonWalletAddress } from '@ton/appkit-react';
 
 export const UseJettonWalletAddressExample = () => {
@@ -35,6 +27,6 @@ export const UseJettonWalletAddressExample = () => {
         return <div>Error: {error.message}</div>;
     }
 
-    return <div>Jetton Wallet Address: {walletAddress?.toString()}</div>;
+    return <div>Jetton Wallet Address: {walletAddress}</div>;
     // SAMPLE_END: USE_JETTON_WALLET_ADDRESS
 };
diff --git a/demo/examples/src/appkit/hooks/jettons/use-jettons-by-address.tsx b/docs/examples/src/appkit/hooks/jettons/use-jettons-by-address.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/jettons/use-jettons-by-address.tsx
rename to docs/examples/src/appkit/hooks/jettons/use-jettons-by-address.tsx
diff --git a/demo/examples/src/appkit/hooks/jettons/use-jettons.tsx b/docs/examples/src/appkit/hooks/jettons/use-jettons.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/jettons/use-jettons.tsx
rename to docs/examples/src/appkit/hooks/jettons/use-jettons.tsx
diff --git a/demo/examples/src/appkit/hooks/jettons/use-transfer-jetton.tsx b/docs/examples/src/appkit/hooks/jettons/use-transfer-jetton.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/jettons/use-transfer-jetton.tsx
rename to docs/examples/src/appkit/hooks/jettons/use-transfer-jetton.tsx
diff --git a/demo/examples/src/appkit/hooks/jettons/use-watch-jettons-by-address.tsx b/docs/examples/src/appkit/hooks/jettons/use-watch-jettons-by-address.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/jettons/use-watch-jettons-by-address.tsx
rename to docs/examples/src/appkit/hooks/jettons/use-watch-jettons-by-address.tsx
diff --git a/demo/examples/src/appkit/hooks/jettons/use-watch-jettons.tsx b/docs/examples/src/appkit/hooks/jettons/use-watch-jettons.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/jettons/use-watch-jettons.tsx
rename to docs/examples/src/appkit/hooks/jettons/use-watch-jettons.tsx
diff --git a/demo/examples/src/appkit/hooks/network/networks.test.tsx b/docs/examples/src/appkit/hooks/network/networks.test.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/network/networks.test.tsx
rename to docs/examples/src/appkit/hooks/network/networks.test.tsx
diff --git a/demo/examples/src/appkit/hooks/network/use-block-number.tsx b/docs/examples/src/appkit/hooks/network/use-block-number.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/network/use-block-number.tsx
rename to docs/examples/src/appkit/hooks/network/use-block-number.tsx
diff --git a/demo/examples/src/appkit/hooks/network/use-default-network.tsx b/docs/examples/src/appkit/hooks/network/use-default-network.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/network/use-default-network.tsx
rename to docs/examples/src/appkit/hooks/network/use-default-network.tsx
diff --git a/demo/examples/src/appkit/hooks/network/use-network.tsx b/docs/examples/src/appkit/hooks/network/use-network.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/network/use-network.tsx
rename to docs/examples/src/appkit/hooks/network/use-network.tsx
diff --git a/demo/examples/src/appkit/hooks/network/use-networks.tsx b/docs/examples/src/appkit/hooks/network/use-networks.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/network/use-networks.tsx
rename to docs/examples/src/appkit/hooks/network/use-networks.tsx
diff --git a/demo/examples/src/appkit/hooks/nft/nfts.test.tsx b/docs/examples/src/appkit/hooks/nft/nfts.test.tsx
similarity index 93%
rename from demo/examples/src/appkit/hooks/nft/nfts.test.tsx
rename to docs/examples/src/appkit/hooks/nft/nfts.test.tsx
index 249f640b9..78e2d935f 100644
--- a/demo/examples/src/appkit/hooks/nft/nfts.test.tsx
+++ b/docs/examples/src/appkit/hooks/nft/nfts.test.tsx
@@ -12,7 +12,6 @@ import React from 'react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { render, screen, fireEvent } from '@testing-library/react';
 import * as AppKitReact from '@ton/appkit-react';
-import { Address } from '@ton/core';
 
 import { UseNftExample } from './use-nft';
 import { UseNftsByAddressExample } from './use-nfts-by-address';
@@ -67,7 +66,7 @@ describe('NFT Hooks Examples', () => {
                 data: {
                     info: { name: 'Epic NFT' },
                     collection: { name: 'Epic Collection' },
-                    ownerAddress: Address.parse('EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c'),
+                    ownerAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
                 },
                 error: null,
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -87,7 +86,7 @@ describe('NFT Hooks Examples', () => {
                 data: {
                     nfts: [
                         {
-                            address: Address.parse('EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c'),
+                            address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
                             info: { name: 'NFT 1' },
                             collection: { name: 'Coll 1' },
                         },
@@ -110,7 +109,7 @@ describe('NFT Hooks Examples', () => {
                 data: {
                     nfts: [
                         {
-                            address: Address.parse('EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c'),
+                            address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
                             info: { name: 'My NFT' },
                             collection: { name: 'My Coll' },
                         },
diff --git a/demo/examples/src/appkit/hooks/nft/use-nft.tsx b/docs/examples/src/appkit/hooks/nft/use-nft.tsx
similarity index 93%
rename from demo/examples/src/appkit/hooks/nft/use-nft.tsx
rename to docs/examples/src/appkit/hooks/nft/use-nft.tsx
index 54b87f1de..2f9986290 100644
--- a/demo/examples/src/appkit/hooks/nft/use-nft.tsx
+++ b/docs/examples/src/appkit/hooks/nft/use-nft.tsx
@@ -31,7 +31,7 @@ export const UseNftExample = () => {
             <h3>NFT Details</h3>
             <p>Name: {nft?.info?.name}</p>
             <p>Collection: {nft?.collection?.name}</p>
-            <p>Owner: {nft?.ownerAddress?.toString()}</p>
+            <p>Owner: {nft?.ownerAddress}</p>
         </div>
     );
     // SAMPLE_END: USE_NFT
diff --git a/demo/examples/src/appkit/hooks/nft/use-nfts-by-address.tsx b/docs/examples/src/appkit/hooks/nft/use-nfts-by-address.tsx
similarity index 94%
rename from demo/examples/src/appkit/hooks/nft/use-nfts-by-address.tsx
rename to docs/examples/src/appkit/hooks/nft/use-nfts-by-address.tsx
index be0901907..a4d9f3c3c 100644
--- a/demo/examples/src/appkit/hooks/nft/use-nfts-by-address.tsx
+++ b/docs/examples/src/appkit/hooks/nft/use-nfts-by-address.tsx
@@ -32,7 +32,7 @@ export const UseNftsByAddressExample = () => {
             <h3>NFTs</h3>
             <ul>
                 {nfts?.nfts.map((nft) => (
-                    <li key={nft.address.toString()}>
+                    <li key={nft.address}>
                         {nft.info?.name} ({nft.collection?.name})
                     </li>
                 ))}
diff --git a/demo/examples/src/appkit/hooks/nft/use-nfts.tsx b/docs/examples/src/appkit/hooks/nft/use-nfts.tsx
similarity index 93%
rename from demo/examples/src/appkit/hooks/nft/use-nfts.tsx
rename to docs/examples/src/appkit/hooks/nft/use-nfts.tsx
index 8a710f252..d6005c172 100644
--- a/demo/examples/src/appkit/hooks/nft/use-nfts.tsx
+++ b/docs/examples/src/appkit/hooks/nft/use-nfts.tsx
@@ -31,7 +31,7 @@ export const UseNftsExample = () => {
             <h3>My NFTs</h3>
             <ul>
                 {nfts?.nfts.map((nft) => (
-                    <li key={nft.address.toString()}>
+                    <li key={nft.address}>
                         {nft.info?.name} ({nft.collection?.name})
                     </li>
                 ))}
diff --git a/demo/examples/src/appkit/hooks/nft/use-transfer-nft.tsx b/docs/examples/src/appkit/hooks/nft/use-transfer-nft.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/nft/use-transfer-nft.tsx
rename to docs/examples/src/appkit/hooks/nft/use-transfer-nft.tsx
diff --git a/demo/examples/src/appkit/hooks/onramp/use-crypto-onramp-provider.tsx b/docs/examples/src/appkit/hooks/onramp/use-crypto-onramp-provider.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/onramp/use-crypto-onramp-provider.tsx
rename to docs/examples/src/appkit/hooks/onramp/use-crypto-onramp-provider.tsx
diff --git a/demo/examples/src/appkit/hooks/onramp/use-crypto-onramp-providers.tsx b/docs/examples/src/appkit/hooks/onramp/use-crypto-onramp-providers.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/onramp/use-crypto-onramp-providers.tsx
rename to docs/examples/src/appkit/hooks/onramp/use-crypto-onramp-providers.tsx
diff --git a/demo/examples/src/appkit/hooks/signing/signing.test.tsx b/docs/examples/src/appkit/hooks/signing/signing.test.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/signing/signing.test.tsx
rename to docs/examples/src/appkit/hooks/signing/signing.test.tsx
diff --git a/demo/examples/src/appkit/hooks/signing/use-sign-binary.tsx b/docs/examples/src/appkit/hooks/signing/use-sign-binary.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/signing/use-sign-binary.tsx
rename to docs/examples/src/appkit/hooks/signing/use-sign-binary.tsx
diff --git a/demo/examples/src/appkit/hooks/signing/use-sign-cell.tsx b/docs/examples/src/appkit/hooks/signing/use-sign-cell.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/signing/use-sign-cell.tsx
rename to docs/examples/src/appkit/hooks/signing/use-sign-cell.tsx
diff --git a/demo/examples/src/appkit/hooks/signing/use-sign-text.tsx b/docs/examples/src/appkit/hooks/signing/use-sign-text.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/signing/use-sign-text.tsx
rename to docs/examples/src/appkit/hooks/signing/use-sign-text.tsx
diff --git a/demo/examples/src/appkit/hooks/staking/staking.test.tsx b/docs/examples/src/appkit/hooks/staking/staking.test.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/staking/staking.test.tsx
rename to docs/examples/src/appkit/hooks/staking/staking.test.tsx
diff --git a/demo/examples/src/appkit/hooks/staking/use-build-stake-transaction.tsx b/docs/examples/src/appkit/hooks/staking/use-build-stake-transaction.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/staking/use-build-stake-transaction.tsx
rename to docs/examples/src/appkit/hooks/staking/use-build-stake-transaction.tsx
diff --git a/demo/examples/src/appkit/hooks/staking/use-staked-balance.tsx b/docs/examples/src/appkit/hooks/staking/use-staked-balance.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/staking/use-staked-balance.tsx
rename to docs/examples/src/appkit/hooks/staking/use-staked-balance.tsx
diff --git a/demo/examples/src/appkit/hooks/staking/use-staking-provider-info.tsx b/docs/examples/src/appkit/hooks/staking/use-staking-provider-info.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/staking/use-staking-provider-info.tsx
rename to docs/examples/src/appkit/hooks/staking/use-staking-provider-info.tsx
diff --git a/demo/examples/src/appkit/hooks/staking/use-staking-provider-metadata.tsx b/docs/examples/src/appkit/hooks/staking/use-staking-provider-metadata.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/staking/use-staking-provider-metadata.tsx
rename to docs/examples/src/appkit/hooks/staking/use-staking-provider-metadata.tsx
diff --git a/demo/examples/src/appkit/hooks/staking/use-staking-provider.tsx b/docs/examples/src/appkit/hooks/staking/use-staking-provider.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/staking/use-staking-provider.tsx
rename to docs/examples/src/appkit/hooks/staking/use-staking-provider.tsx
diff --git a/demo/examples/src/appkit/hooks/staking/use-staking-providers.tsx b/docs/examples/src/appkit/hooks/staking/use-staking-providers.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/staking/use-staking-providers.tsx
rename to docs/examples/src/appkit/hooks/staking/use-staking-providers.tsx
diff --git a/demo/examples/src/appkit/hooks/staking/use-staking-quote.tsx b/docs/examples/src/appkit/hooks/staking/use-staking-quote.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/staking/use-staking-quote.tsx
rename to docs/examples/src/appkit/hooks/staking/use-staking-quote.tsx
diff --git a/demo/examples/src/appkit/hooks/swap/swap.test.tsx b/docs/examples/src/appkit/hooks/swap/swap.test.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/swap/swap.test.tsx
rename to docs/examples/src/appkit/hooks/swap/swap.test.tsx
diff --git a/demo/examples/src/appkit/hooks/swap/use-build-swap-transaction.tsx b/docs/examples/src/appkit/hooks/swap/use-build-swap-transaction.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/swap/use-build-swap-transaction.tsx
rename to docs/examples/src/appkit/hooks/swap/use-build-swap-transaction.tsx
diff --git a/demo/examples/src/appkit/hooks/swap/use-swap-provider.tsx b/docs/examples/src/appkit/hooks/swap/use-swap-provider.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/swap/use-swap-provider.tsx
rename to docs/examples/src/appkit/hooks/swap/use-swap-provider.tsx
diff --git a/demo/examples/src/appkit/hooks/swap/use-swap-providers.tsx b/docs/examples/src/appkit/hooks/swap/use-swap-providers.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/swap/use-swap-providers.tsx
rename to docs/examples/src/appkit/hooks/swap/use-swap-providers.tsx
diff --git a/demo/examples/src/appkit/hooks/swap/use-swap-quote.tsx b/docs/examples/src/appkit/hooks/swap/use-swap-quote.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/swap/use-swap-quote.tsx
rename to docs/examples/src/appkit/hooks/swap/use-swap-quote.tsx
diff --git a/demo/examples/src/appkit/hooks/transaction/transaction.test.tsx b/docs/examples/src/appkit/hooks/transaction/transaction.test.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/transaction/transaction.test.tsx
rename to docs/examples/src/appkit/hooks/transaction/transaction.test.tsx
diff --git a/demo/examples/src/appkit/hooks/transaction/use-send-transaction.tsx b/docs/examples/src/appkit/hooks/transaction/use-send-transaction.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/transaction/use-send-transaction.tsx
rename to docs/examples/src/appkit/hooks/transaction/use-send-transaction.tsx
diff --git a/demo/examples/src/appkit/hooks/transaction/use-transfer-ton.tsx b/docs/examples/src/appkit/hooks/transaction/use-transfer-ton.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/transaction/use-transfer-ton.tsx
rename to docs/examples/src/appkit/hooks/transaction/use-transfer-ton.tsx
diff --git a/demo/examples/src/appkit/hooks/transaction/use-watch-transactions-by-address.tsx b/docs/examples/src/appkit/hooks/transaction/use-watch-transactions-by-address.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/transaction/use-watch-transactions-by-address.tsx
rename to docs/examples/src/appkit/hooks/transaction/use-watch-transactions-by-address.tsx
diff --git a/demo/examples/src/appkit/hooks/transaction/use-watch-transactions.tsx b/docs/examples/src/appkit/hooks/transaction/use-watch-transactions.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/transaction/use-watch-transactions.tsx
rename to docs/examples/src/appkit/hooks/transaction/use-watch-transactions.tsx
diff --git a/demo/examples/src/appkit/hooks/wallets/use-address.tsx b/docs/examples/src/appkit/hooks/wallets/use-address.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/wallets/use-address.tsx
rename to docs/examples/src/appkit/hooks/wallets/use-address.tsx
diff --git a/demo/examples/src/appkit/hooks/wallets/use-connect.tsx b/docs/examples/src/appkit/hooks/wallets/use-connect.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/wallets/use-connect.tsx
rename to docs/examples/src/appkit/hooks/wallets/use-connect.tsx
diff --git a/demo/examples/src/appkit/hooks/wallets/use-connected-wallets.tsx b/docs/examples/src/appkit/hooks/wallets/use-connected-wallets.tsx
similarity index 97%
rename from demo/examples/src/appkit/hooks/wallets/use-connected-wallets.tsx
rename to docs/examples/src/appkit/hooks/wallets/use-connected-wallets.tsx
index 75c5bc24e..decf4f90e 100644
--- a/demo/examples/src/appkit/hooks/wallets/use-connected-wallets.tsx
+++ b/docs/examples/src/appkit/hooks/wallets/use-connected-wallets.tsx
@@ -18,7 +18,7 @@ export const UseConnectedWalletsExample = () => {
             <ul>
                 {connectedWallets.map((wallet) => (
                     <li key={wallet.getAddress()}>
-                        {wallet.getAddress()} ({wallet.getNetwork().toString()})
+                        {wallet.getAddress()} ({wallet.getNetwork().chainId})
                     </li>
                 ))}
             </ul>
diff --git a/demo/examples/src/appkit/hooks/wallets/use-connector-by-id.tsx b/docs/examples/src/appkit/hooks/wallets/use-connector-by-id.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/wallets/use-connector-by-id.tsx
rename to docs/examples/src/appkit/hooks/wallets/use-connector-by-id.tsx
diff --git a/demo/examples/src/appkit/hooks/wallets/use-connectors.tsx b/docs/examples/src/appkit/hooks/wallets/use-connectors.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/wallets/use-connectors.tsx
rename to docs/examples/src/appkit/hooks/wallets/use-connectors.tsx
diff --git a/demo/examples/src/appkit/hooks/wallets/use-disconnect.tsx b/docs/examples/src/appkit/hooks/wallets/use-disconnect.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/wallets/use-disconnect.tsx
rename to docs/examples/src/appkit/hooks/wallets/use-disconnect.tsx
diff --git a/demo/examples/src/appkit/hooks/wallets/use-selected-wallet.tsx b/docs/examples/src/appkit/hooks/wallets/use-selected-wallet.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/wallets/use-selected-wallet.tsx
rename to docs/examples/src/appkit/hooks/wallets/use-selected-wallet.tsx
diff --git a/demo/examples/src/appkit/hooks/wallets/wallets.test.tsx b/docs/examples/src/appkit/hooks/wallets/wallets.test.tsx
similarity index 100%
rename from demo/examples/src/appkit/hooks/wallets/wallets.test.tsx
rename to docs/examples/src/appkit/hooks/wallets/wallets.test.tsx
diff --git a/demo/examples/src/appkit/setup-react.tsx b/docs/examples/src/appkit/setup-react.tsx
similarity index 100%
rename from demo/examples/src/appkit/setup-react.tsx
rename to docs/examples/src/appkit/setup-react.tsx
diff --git a/demo/examples/src/appkit/setup.ts b/docs/examples/src/appkit/setup.ts
similarity index 100%
rename from demo/examples/src/appkit/setup.ts
rename to docs/examples/src/appkit/setup.ts
diff --git a/demo/examples/src/appkit/staking/staking-widget.tsx b/docs/examples/src/appkit/staking/staking-widget.tsx
similarity index 100%
rename from demo/examples/src/appkit/staking/staking-widget.tsx
rename to docs/examples/src/appkit/staking/staking-widget.tsx
diff --git a/demo/examples/src/appkit/staking/tonstakers.ts b/docs/examples/src/appkit/staking/tonstakers.ts
similarity index 100%
rename from demo/examples/src/appkit/staking/tonstakers.ts
rename to docs/examples/src/appkit/staking/tonstakers.ts
diff --git a/demo/examples/src/appkit/swap/dedust.ts b/docs/examples/src/appkit/swap/dedust.ts
similarity index 100%
rename from demo/examples/src/appkit/swap/dedust.ts
rename to docs/examples/src/appkit/swap/dedust.ts
diff --git a/demo/examples/src/appkit/swap/omniston.ts b/docs/examples/src/appkit/swap/omniston.ts
similarity index 100%
rename from demo/examples/src/appkit/swap/omniston.ts
rename to docs/examples/src/appkit/swap/omniston.ts
diff --git a/demo/examples/src/appkit/swap/swap-widget.tsx b/docs/examples/src/appkit/swap/swap-widget.tsx
similarity index 100%
rename from demo/examples/src/appkit/swap/swap-widget.tsx
rename to docs/examples/src/appkit/swap/swap-widget.tsx
diff --git a/demo/examples/src/initialize.ts b/docs/examples/src/initialize.ts
similarity index 100%
rename from demo/examples/src/initialize.ts
rename to docs/examples/src/initialize.ts
diff --git a/demo/examples/src/jettons.ts b/docs/examples/src/jettons.ts
similarity index 100%
rename from demo/examples/src/jettons.ts
rename to docs/examples/src/jettons.ts
diff --git a/demo/examples/src/lib/wallet-kit-initialize-sample.ts b/docs/examples/src/lib/wallet-kit-initialize-sample.ts
similarity index 100%
rename from demo/examples/src/lib/wallet-kit-initialize-sample.ts
rename to docs/examples/src/lib/wallet-kit-initialize-sample.ts
diff --git a/demo/examples/src/lib/wallet-manifest.ts b/docs/examples/src/lib/wallet-manifest.ts
similarity index 100%
rename from demo/examples/src/lib/wallet-manifest.ts
rename to docs/examples/src/lib/wallet-manifest.ts
diff --git a/demo/examples/src/requests.ts b/docs/examples/src/requests.ts
similarity index 99%
rename from demo/examples/src/requests.ts
rename to docs/examples/src/requests.ts
index 160b690d2..0ce6f5f82 100644
--- a/demo/examples/src/requests.ts
+++ b/docs/examples/src/requests.ts
@@ -42,7 +42,7 @@ export async function main() {
         }
         // Query balance
         const balance = await wallet.getBalance();
-        console.log('WalletBalance', wallet.getAddress(), balance.toString());
+        console.log('WalletBalance', wallet.getAddress(), balance);
         // SAMPLE_END: BASIC_WALLET_OPERATIONS_1
     }
 
diff --git a/demo/examples/src/send-jettons.ts b/docs/examples/src/send-jettons.ts
similarity index 100%
rename from demo/examples/src/send-jettons.ts
rename to docs/examples/src/send-jettons.ts
diff --git a/demo/examples/src/send-nft.ts b/docs/examples/src/send-nft.ts
similarity index 100%
rename from demo/examples/src/send-nft.ts
rename to docs/examples/src/send-nft.ts
diff --git a/demo/examples/src/send-ton.ts b/docs/examples/src/send-ton.ts
similarity index 100%
rename from demo/examples/src/send-ton.ts
rename to docs/examples/src/send-ton.ts
diff --git a/demo/examples/src/ui-state-wiring.ts b/docs/examples/src/ui-state-wiring.ts
similarity index 100%
rename from demo/examples/src/ui-state-wiring.ts
rename to docs/examples/src/ui-state-wiring.ts
diff --git a/demo/examples/src/ui/render-connect-preview.tsx b/docs/examples/src/ui/render-connect-preview.tsx
similarity index 100%
rename from demo/examples/src/ui/render-connect-preview.tsx
rename to docs/examples/src/ui/render-connect-preview.tsx
diff --git a/demo/examples/src/ui/render-money-flow.tsx b/docs/examples/src/ui/render-money-flow.tsx
similarity index 100%
rename from demo/examples/src/ui/render-money-flow.tsx
rename to docs/examples/src/ui/render-money-flow.tsx
diff --git a/demo/examples/src/ui/render-sign-data-preview.tsx b/docs/examples/src/ui/render-sign-data-preview.tsx
similarity index 100%
rename from demo/examples/src/ui/render-sign-data-preview.tsx
rename to docs/examples/src/ui/render-sign-data-preview.tsx
diff --git a/demo/examples/src/ui/summarize-transaction.tsx b/docs/examples/src/ui/summarize-transaction.tsx
similarity index 100%
rename from demo/examples/src/ui/summarize-transaction.tsx
rename to docs/examples/src/ui/summarize-transaction.tsx
diff --git a/demo/examples/tsconfig.json b/docs/examples/tsconfig.json
similarity index 100%
rename from demo/examples/tsconfig.json
rename to docs/examples/tsconfig.json
diff --git a/demo/examples/vitest.config.ts b/docs/examples/vitest.config.ts
similarity index 100%
rename from demo/examples/vitest.config.ts
rename to docs/examples/vitest.config.ts
diff --git a/docs/reference-generator/package.json b/docs/reference-generator/package.json
new file mode 100644
index 000000000..d8a3e054c
--- /dev/null
+++ b/docs/reference-generator/package.json
@@ -0,0 +1,18 @@
+{
+    "name": "@ton/reference-generator",
+    "version": "0.0.0",
+    "private": true,
+    "type": "module",
+    "description": "Generates Mintlify-flavored API reference for @ton/appkit and @ton/appkit-react",
+    "scripts": {
+        "generate": "tsx src/index.ts",
+        "typecheck": "tsc --noEmit"
+    },
+    "dependencies": {
+        "ts-morph": "^28.0.0"
+    },
+    "devDependencies": {
+        "tsx": "^4.21.0",
+        "typescript": "~5.9.3"
+    }
+}
diff --git a/docs/reference-generator/src/collect.ts b/docs/reference-generator/src/collect.ts
new file mode 100644
index 000000000..57c58fa63
--- /dev/null
+++ b/docs/reference-generator/src/collect.ts
@@ -0,0 +1,235 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { Node, Project, SymbolFlags } from 'ts-morph';
+import type { JSDoc, SourceFile, Symbol as TsSymbol } from 'ts-morph';
+
+export interface CollectedSymbol {
+    name: string;
+    /** Original declaration — used by extract.ts for shape (fields, members, signature). */
+    declaration: Node;
+    /** Declaration in the local package whose JSDoc tags drive this symbol's metadata.
+     * Equals `declaration` for symbols defined in this package, or the local
+     * alias-export when the symbol is re-exported from another workspace
+     * package via `@extract`. */
+    metadataDeclaration: Node;
+    /** True when the symbol arrived via `@extract` re-export from another package. */
+    extracted: boolean;
+    sourceFile: SourceFile;
+    /** Path relative to the package's src/ directory. e.g. "actions/balances/get-balance-by-address.ts" */
+    sourcePath: string;
+    /** Value of the `@section` JSDoc tag. Forms the top-level grouping (e.g. Action, Class, Type). */
+    section: string | null;
+    /** Value of the `@category` JSDoc tag. Forms the second-level grouping (e.g. Balances, Signing). */
+    category: string | null;
+}
+
+export interface CollectOptions {
+    packagePath: string;
+}
+
+export function collectPublicApi(options: CollectOptions): CollectedSymbol[] {
+    const { packagePath } = options;
+    const tsConfigFilePath = join(packagePath, 'tsconfig.json');
+
+    const project = new Project({ tsConfigFilePath });
+
+    const entryAbsPaths = readEntryPaths(packagePath);
+    const seenRealSymbols = new Set<TsSymbol>();
+    const collected: CollectedSymbol[] = [];
+
+    for (const entryAbsPath of entryAbsPaths) {
+        const sourceFile = project.getSourceFile(entryAbsPath);
+        if (!sourceFile) {
+            console.warn(`[collect] Entry not found in project: ${entryAbsPath}`);
+            continue;
+        }
+
+        const srcPrefix = `${packagePath}/src/`;
+
+        for (const exportSymbol of sourceFile.getExportSymbols()) {
+            const real = unwrapAlias(exportSymbol);
+            if (seenRealSymbols.has(real)) continue;
+
+            const realDecl = real.getDeclarations()[0];
+            if (!realDecl) continue;
+
+            const realDeclPath = realDecl.getSourceFile().getFilePath();
+            const realInPkg = realDeclPath.startsWith(srcPrefix);
+
+            // Where to read JSDoc tags from. Normally that's the declaration
+            // itself; for cross-package re-exports we read from the alias
+            // declaration in our package (the `export { … } from 'pkg'` line)
+            // and require an explicit `@extract` opt-in there. When a symbol
+            // is re-exported from multiple places, prefer the alias that
+            // carries `@extract` + `@public` so the chosen metadata is the
+            // documented one, regardless of traversal order.
+            let metadataDecl: Node = realDecl;
+            let extracted = false;
+
+            if (!realInPkg) {
+                const annotated = findAnnotatedAlias(exportSymbol, srcPrefix);
+                if (!annotated) continue;
+                metadataDecl = annotated;
+                extracted = true;
+            } else if (!hasPublicTag(metadataDecl)) {
+                continue;
+            }
+
+            seenRealSymbols.add(real);
+
+            const sourcePath = realInPkg
+                ? realDeclPath.slice(srcPrefix.length)
+                : metadataDecl.getSourceFile().getFilePath().slice(srcPrefix.length);
+
+            collected.push({
+                name: exportSymbol.getName(),
+                declaration: realDecl,
+                metadataDeclaration: metadataDecl,
+                extracted,
+                sourceFile: realDecl.getSourceFile(),
+                sourcePath,
+                section: readTagValue(metadataDecl, 'section'),
+                category: readTagValue(metadataDecl, 'category'),
+            });
+        }
+    }
+
+    return collected;
+}
+
+export function getJsDocs(decl: Node): JSDoc[] {
+    if (Node.isVariableDeclaration(decl)) {
+        return decl.getVariableStatement()?.getJsDocs() ?? [];
+    }
+    if (Node.isExportSpecifier(decl)) {
+        // JSDoc lives on the parent ExportDeclaration (`/** … */ export { Foo } from '…'`).
+        // ExportDeclaration is not JSDocable in ts-morph's mixin, so pull the JSDoc nodes from its children.
+        return decl
+            .getExportDeclaration()
+            .getChildren()
+            .filter((c): c is JSDoc => Node.isJSDoc(c));
+    }
+    return Node.isJSDocable(decl) ? decl.getJsDocs() : [];
+}
+
+function hasPublicTag(decl: Node): boolean {
+    for (const doc of getJsDocs(decl)) {
+        for (const tag of doc.getTags()) {
+            if (tag.getTagName() === 'public') return true;
+        }
+    }
+    return false;
+}
+
+function hasExtractTag(decl: Node): boolean {
+    for (const doc of getJsDocs(decl)) {
+        for (const tag of doc.getTags()) {
+            if (tag.getTagName() === 'extract') return true;
+        }
+    }
+    return false;
+}
+
+function readTagValue(decl: Node, tagName: string): string | null {
+    for (const doc of getJsDocs(decl)) {
+        for (const tag of doc.getTags()) {
+            if (tag.getTagName() !== tagName) continue;
+            const text = tag.getCommentText()?.trim();
+            if (text) return text;
+        }
+    }
+    return null;
+}
+
+function unwrapAlias(symbol: TsSymbol): TsSymbol {
+    let current = symbol;
+    let next = current.getAliasedSymbol();
+    while (next) {
+        current = next;
+        next = current.getAliasedSymbol();
+    }
+    return current;
+}
+
+/**
+ * Walks the alias chain looking for an alias declaration in our package whose
+ * parent `export { … } from '…'` carries both `@extract` and `@public`.
+ *
+ * `exportSymbol.getDeclarations()` only returns the immediate alias hop, so when
+ * a symbol is re-exported through multiple files (root → core/network → walletkit
+ * leaf) we have to follow each ExportSpecifier's own immediately-aliased symbol
+ * to find an annotated link further down the chain.
+ */
+function findAnnotatedAlias(exportSymbol: TsSymbol, srcPrefix: string): Node | null {
+    const visited = new Set<TsSymbol>();
+    let cursor: TsSymbol | undefined = exportSymbol;
+    while (cursor !== undefined && !visited.has(cursor)) {
+        const node: TsSymbol = cursor;
+        visited.add(node);
+
+        const localDecls = node.getDeclarations().filter((d) => d.getSourceFile().getFilePath().startsWith(srcPrefix));
+        const annotated = localDecls.find((d) => hasExtractTag(d) && hasPublicTag(d));
+        if (annotated) return annotated;
+
+        // Step one hop down the alias chain. `getImmediatelyAliasedSymbol` only
+        // works on alias-flagged symbols (export specifiers, imports, namespace
+        // imports); it asserts otherwise. Bail out cleanly when we've hit the
+        // real declaration and there's nowhere further to walk.
+        const isAlias = (node.getFlags() & SymbolFlags.Alias) !== 0;
+        cursor = isAlias ? node.getImmediatelyAliasedSymbol() : undefined;
+    }
+    return null;
+}
+
+interface ConditionalExport {
+    [condition: string]: string | ConditionalExport;
+}
+type ExportEntry = string | ConditionalExport;
+
+function readEntryPaths(packagePath: string): string[] {
+    const pkg = JSON.parse(readFileSync(join(packagePath, 'package.json'), 'utf-8')) as {
+        exports?: Record<string, ExportEntry>;
+    };
+    const exports = pkg.exports ?? {};
+    const entries = new Set<string>();
+
+    for (const [key, value] of Object.entries(exports)) {
+        if (key.endsWith('.css')) continue;
+
+        const distPath = pickEntryPath(value);
+        if (!distPath) continue;
+
+        const srcRelative = distPath
+            .replace(/^\.\//, '')
+            .replace(/^dist\/(esm|cjs|types)\//, 'src/')
+            .replace(/\.d\.ts$/, '.ts')
+            .replace(/\.js$/, '.ts');
+
+        entries.add(join(packagePath, srcRelative));
+    }
+
+    return [...entries];
+}
+
+function pickEntryPath(value: ExportEntry): string | null {
+    if (typeof value === 'string') {
+        return value.endsWith('.js') || value.endsWith('.d.ts') ? value : null;
+    }
+    if (value && typeof value === 'object') {
+        const candidates = [value['import'], value['default'], value['types']];
+        for (const c of candidates) {
+            if (typeof c === 'string') return pickEntryPath(c);
+            if (c && typeof c === 'object') return pickEntryPath(c);
+        }
+    }
+    return null;
+}
diff --git a/docs/reference-generator/src/extract.ts b/docs/reference-generator/src/extract.ts
new file mode 100644
index 000000000..9b05dc4b8
--- /dev/null
+++ b/docs/reference-generator/src/extract.ts
@@ -0,0 +1,905 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import { Node, TypeFormatFlags } from 'ts-morph';
+import type {
+    ClassDeclaration,
+    EnumDeclaration,
+    FunctionDeclaration,
+    InterfaceDeclaration,
+    JSDoc,
+    JSDocParameterTag,
+    ObjectLiteralExpression,
+    ParameterDeclaration,
+    Type,
+    TypeAliasDeclaration,
+    VariableDeclaration,
+} from 'ts-morph';
+
+import { getJsDocs } from './collect';
+import type { CollectedSymbol } from './collect';
+
+export type SymbolKind = 'function' | 'component' | 'componentNamespace' | 'type' | 'class';
+
+export const VALID_CATEGORIES = ['Class', 'Action', 'Hook', 'Component', 'Type', 'Constants'] as const;
+export type ValidCategory = (typeof VALID_CATEGORIES)[number];
+
+export interface ParamRow {
+    name: string;
+    typeText: string;
+    /** When set, the renderer uses this name (link if documented) instead of `typeText`. */
+    typeOverride: string | null;
+    required: boolean;
+    description: string | null;
+}
+
+export interface ExtractedFunction {
+    kind: 'function';
+    name: string;
+    sourcePath: string;
+    section: string;
+    category: string;
+    summary: string | null;
+    params: ParamRow[];
+    returnTypeText: string;
+    returnTypeOverride: string | null;
+    returnDescription: string | null;
+    examples: string[];
+    samples: string[];
+}
+
+export interface ExtractedComponent {
+    kind: 'component';
+    name: string;
+    sourcePath: string;
+    section: string;
+    category: string;
+    summary: string | null;
+    props: ParamRow[];
+    examples: string[];
+    samples: string[];
+}
+
+export interface ExtractedNamespaceComponent {
+    kind: 'componentNamespace';
+    name: string;
+    sourcePath: string;
+    section: string;
+    category: string;
+    summary: string | null;
+    members: { name: string; props: ParamRow[]; summary: string | null }[];
+}
+
+export interface ExtractedType {
+    kind: 'type';
+    name: string;
+    sourcePath: string;
+    section: string;
+    category: string;
+    summary: string | null;
+    fields: ParamRow[] | null;
+    typeText: string | null;
+    /** True for `const X = ...` declarations; renderer uses `const`-form code block. */
+    isConstant: boolean;
+}
+
+export interface ExtractedClass {
+    kind: 'class';
+    name: string;
+    sourcePath: string;
+    section: string;
+    category: string;
+    summary: string | null;
+    constructorParams: ParamRow[] | null;
+    examples: string[];
+    samples: string[];
+}
+
+export type Extracted =
+    | ExtractedFunction
+    | ExtractedComponent
+    | ExtractedNamespaceComponent
+    | ExtractedType
+    | ExtractedClass;
+
+const FORMAT_FLAGS =
+    TypeFormatFlags.NoTruncation |
+    TypeFormatFlags.UseAliasDefinedOutsideCurrentScope |
+    TypeFormatFlags.WriteArrayAsGenericType;
+
+type ExtractedWithoutMeta =
+    | Omit<ExtractedFunction, 'section' | 'category'>
+    | Omit<ExtractedComponent, 'section' | 'category'>
+    | Omit<ExtractedNamespaceComponent, 'section' | 'category'>
+    | Omit<ExtractedType, 'section' | 'category'>
+    | Omit<ExtractedClass, 'section' | 'category'>;
+
+export function extract(collected: CollectedSymbol): Extracted {
+    const { name, declaration, metadataDeclaration, sourcePath } = collected;
+    const category = collected.category ?? '';
+
+    if (!isValidCategory(category)) {
+        throw new Error(`[${name}] Invalid @category "${category}". Allowed values: ${VALID_CATEGORIES.join(', ')}.`);
+    }
+
+    const inner = extractByCategory(category, name, declaration, sourcePath);
+    const section = collected.section ?? '';
+
+    // For @extract re-exports, prefer the JSDoc summary from the local export comment
+    // over (often missing) JSDoc on the imported declaration in the other package.
+    const metadataSummary =
+        metadataDeclaration !== declaration ? readSummary(pickJsDoc(getJsDocs(metadataDeclaration))) : null;
+    if (metadataSummary && 'summary' in inner) {
+        return { ...inner, section, category, summary: metadataSummary } as Extracted;
+    }
+
+    return { ...inner, section, category } as Extracted;
+}
+
+function isValidCategory(value: string): value is ValidCategory {
+    return (VALID_CATEGORIES as readonly string[]).includes(value);
+}
+
+function extractByCategory(
+    category: ValidCategory,
+    name: string,
+    declaration: Node,
+    sourcePath: string,
+): ExtractedWithoutMeta {
+    switch (category) {
+        case 'Type':
+            if (Node.isInterfaceDeclaration(declaration) || Node.isTypeAliasDeclaration(declaration)) {
+                return extractType(name, declaration, sourcePath);
+            }
+            throw mismatch(name, category, 'interface or type alias');
+
+        case 'Constants':
+            if (Node.isVariableDeclaration(declaration) || Node.isEnumDeclaration(declaration)) {
+                return extractType(name, declaration, sourcePath);
+            }
+            throw mismatch(name, category, 'const or enum declaration');
+
+        case 'Class':
+            if (Node.isClassDeclaration(declaration)) {
+                return extractClass(name, declaration, sourcePath);
+            }
+            if (Node.isTypeAliasDeclaration(declaration) && hasExtractTag(declaration)) {
+                const expanded = expandClassThroughExtract(name, declaration, sourcePath);
+                if (expanded) return expanded;
+            }
+            throw mismatch(name, category, 'class declaration or @extract type alias targeting a class');
+
+        case 'Action':
+        case 'Hook':
+            if (Node.isFunctionDeclaration(declaration)) {
+                return extractFunctionLike(declaration, name, sourcePath);
+            }
+            if (Node.isVariableDeclaration(declaration)) {
+                return extractVariableFunction(declaration, name, sourcePath);
+            }
+            throw mismatch(name, category, 'function declaration or arrow/function variable');
+
+        case 'Component':
+            if (Node.isVariableDeclaration(declaration)) {
+                const init = declaration.getInitializer();
+                if (init && Node.isObjectLiteralExpression(init)) {
+                    return extractNamespaceComponent(name, declaration, init, sourcePath);
+                }
+                return extractVariableAsComponent(declaration, name, sourcePath);
+            }
+            if (Node.isFunctionDeclaration(declaration)) {
+                return extractFunctionAsComponent(declaration, name, sourcePath);
+            }
+            throw mismatch(name, category, 'function or variable declaration');
+    }
+}
+
+function mismatch(name: string, category: ValidCategory, expected: string): Error {
+    return new Error(`[${name}] @category ${category} requires the symbol to be a ${expected}.`);
+}
+
+function extractFunctionLike(
+    decl: FunctionDeclaration,
+    name: string,
+    sourcePath: string,
+): Omit<ExtractedFunction, 'section' | 'category'> {
+    const jsdoc = pickJsDoc(decl.getJsDocs());
+    const summary = readSummary(jsdoc);
+    const paramTags = readParamTags(jsdoc);
+    const returnInfo = readReturnInfo(jsdoc);
+    const examples = readExamples(jsdoc);
+    const samples = readSamples(jsdoc);
+    const expandNames = readExpandNames(jsdoc);
+
+    const params = expandParameters(decl.getParameters(), decl, paramTags, expandNames);
+    const fnTypeParams = collectTypeParamDefaults(decl);
+    const rawReturnNode = decl.getReturnTypeNode()?.getText();
+    const returnTypeText = rawReturnNode
+        ? substituteTypeParams(rawReturnNode, fnTypeParams)
+        : formatType(decl.getReturnType(), decl);
+
+    return {
+        kind: 'function',
+        name,
+        sourcePath,
+        summary,
+        params,
+        returnTypeText,
+        returnTypeOverride: returnInfo.typeOverride,
+        returnDescription: returnInfo.description,
+        examples,
+        samples,
+    };
+}
+
+function extractVariableFunction(
+    decl: VariableDeclaration,
+    name: string,
+    sourcePath: string,
+): Omit<ExtractedFunction, 'section' | 'category'> {
+    const stmt = decl.getVariableStatement();
+    const jsdoc = pickJsDoc(stmt?.getJsDocs() ?? []);
+    const summary = readSummary(jsdoc);
+    const paramTags = readParamTags(jsdoc);
+    const returnInfo = readReturnInfo(jsdoc);
+    const examples = readExamples(jsdoc);
+    const samples = readSamples(jsdoc);
+    const expandNames = readExpandNames(jsdoc);
+
+    const init = decl.getInitializer();
+
+    // Inline arrow / function-expression: read parameters and return type
+    // straight from the AST so authors get @sample-based examples and `@expand`
+    // flattening.
+    if (init && (Node.isArrowFunction(init) || Node.isFunctionExpression(init))) {
+        const params = expandParameters(init.getParameters(), decl, paramTags, expandNames);
+        const fnTypeParams = collectTypeParamDefaults(init);
+        const rawReturnNode = init.getReturnTypeNode()?.getText();
+        const returnTypeText = rawReturnNode
+            ? substituteTypeParams(rawReturnNode, fnTypeParams)
+            : formatType(init.getReturnType(), decl);
+
+        return {
+            kind: 'function',
+            name,
+            sourcePath,
+            summary,
+            params,
+            returnTypeText,
+            returnTypeOverride: returnInfo.typeOverride,
+            returnDescription: returnInfo.description,
+            examples,
+            samples,
+        };
+    }
+
+    // No inline initializer (e.g., `declare const fn: (...) => ...` re-exported
+    // from walletkit through `@extract`). Fall back to the variable's call
+    // signature — we lose parameter-name accuracy in some edge cases but it's
+    // the only signal available.
+    const callSig = decl.getType().getCallSignatures()[0];
+    if (callSig) {
+        const sigParams = callSig.getParameters();
+        const params: ParamRow[] = sigParams.map((p) => {
+            const valueDecl = p.getValueDeclaration();
+            const paramName = p.getName();
+            const tagInfo = paramTags.get(paramName);
+            const required =
+                valueDecl && Node.isParameterDeclaration(valueDecl)
+                    ? !valueDecl.hasQuestionToken() && !valueDecl.hasInitializer() && !valueDecl.isRestParameter()
+                    : true;
+            const typeText =
+                valueDecl && Node.isParameterDeclaration(valueDecl)
+                    ? (valueDecl.getTypeNode()?.getText() ?? formatType(p.getTypeAtLocation(decl), decl))
+                    : formatType(p.getTypeAtLocation(decl), decl);
+            return {
+                name: paramName,
+                typeText,
+                typeOverride: tagInfo?.typeOverride ?? null,
+                required,
+                description: tagInfo?.description ?? null,
+            };
+        });
+        const returnTypeText = formatType(callSig.getReturnType(), decl);
+        return {
+            kind: 'function',
+            name,
+            sourcePath,
+            summary,
+            params,
+            returnTypeText,
+            returnTypeOverride: returnInfo.typeOverride,
+            returnDescription: returnInfo.description,
+            examples,
+            samples,
+        };
+    }
+
+    return {
+        kind: 'function',
+        name,
+        sourcePath,
+        summary,
+        params: [],
+        returnTypeText: 'unknown',
+        returnTypeOverride: returnInfo.typeOverride,
+        returnDescription: returnInfo.description,
+        examples,
+        samples,
+    };
+}
+
+function extractFunctionAsComponent(
+    decl: FunctionDeclaration,
+    name: string,
+    sourcePath: string,
+): Omit<ExtractedComponent, 'section' | 'category'> {
+    const jsdoc = pickJsDoc(decl.getJsDocs());
+    const summary = readSummary(jsdoc);
+    const examples = readExamples(jsdoc);
+    const samples = readSamples(jsdoc);
+    const props = expandComponentProps(decl.getParameters(), decl);
+    return { kind: 'component', name, sourcePath, summary, props, examples, samples };
+}
+
+function extractVariableAsComponent(
+    decl: VariableDeclaration,
+    name: string,
+    sourcePath: string,
+): Omit<ExtractedComponent, 'section' | 'category'> {
+    const stmt = decl.getVariableStatement();
+    const jsdoc = pickJsDoc(stmt?.getJsDocs() ?? []);
+    const summary = readSummary(jsdoc);
+    const examples = readExamples(jsdoc);
+    const samples = readSamples(jsdoc);
+
+    const init = decl.getInitializer();
+    let propsType: Type | null = null;
+
+    if (init && (Node.isArrowFunction(init) || Node.isFunctionExpression(init))) {
+        const params = init.getParameters();
+        if (params.length > 0) propsType = params[0].getType();
+    } else {
+        const callSig = decl.getType().getCallSignatures()[0];
+        const propsParam = callSig?.getParameters()[0];
+        if (propsParam) {
+            propsType = propsParam.getValueDeclaration()?.getType() ?? null;
+        }
+    }
+
+    const props = propsType ? readPropsFromType(propsType, decl) : [];
+    return { kind: 'component', name, sourcePath, summary, props, examples, samples };
+}
+
+function extractNamespaceComponent(
+    name: string,
+    decl: VariableDeclaration,
+    init: ObjectLiteralExpression,
+    sourcePath: string,
+): Omit<ExtractedNamespaceComponent, 'section' | 'category'> {
+    const stmt = decl.getVariableStatement();
+    const jsdoc = pickJsDoc(stmt?.getJsDocs() ?? []);
+    const summary = readSummary(jsdoc);
+
+    const members: ExtractedNamespaceComponent['members'] = [];
+    for (const prop of init.getProperties()) {
+        if (!Node.isPropertyAssignment(prop) && !Node.isShorthandPropertyAssignment(prop)) continue;
+        const memberName = prop.getName();
+        const memberType = prop.getType();
+        const callSig = memberType.getCallSignatures()[0];
+        const propsParam = callSig?.getParameters()[0];
+        const propsType = propsParam?.getValueDeclaration()?.getType() ?? null;
+        const props = propsType ? readPropsFromType(propsType, decl) : [];
+        const memberSummary = readLeadingJsDocSummary(prop);
+        members.push({ name: memberName, props, summary: memberSummary });
+    }
+
+    return { kind: 'componentNamespace', name, sourcePath, summary, members };
+}
+
+function extractType(
+    name: string,
+    decl: InterfaceDeclaration | TypeAliasDeclaration | VariableDeclaration | EnumDeclaration,
+    sourcePath: string,
+): Omit<ExtractedType, 'section' | 'category'> {
+    if (Node.isVariableDeclaration(decl)) {
+        const stmt = decl.getVariableStatement();
+        const jsdoc = pickJsDoc(stmt?.getJsDocs() ?? []);
+        const summary = readSummary(jsdoc);
+        const init = decl.getInitializer();
+        const typeText = init ? init.getText() : decl.getType().getText(decl, FORMAT_FLAGS);
+        return { kind: 'type', name, sourcePath, summary, fields: null, typeText, isConstant: true };
+    }
+
+    if (Node.isEnumDeclaration(decl)) {
+        const summary = readSummary(pickJsDoc(decl.getJsDocs()));
+        const fields: ParamRow[] = decl.getMembers().map((member) => {
+            const init = member.getInitializer();
+            const valueText = init ? init.getText() : 'auto';
+            const desc = readSummary(pickJsDoc(member.getJsDocs()));
+            return {
+                name: member.getName(),
+                typeText: valueText,
+                typeOverride: null,
+                required: true,
+                description: desc,
+            };
+        });
+        return { kind: 'type', name, sourcePath, summary, fields, typeText: null, isConstant: true };
+    }
+
+    const jsdoc = pickJsDoc(decl.getJsDocs());
+    const summary = readSummary(jsdoc);
+
+    if (Node.isTypeAliasDeclaration(decl) && hasExtractTag(decl)) {
+        const expanded = expandThroughExtract(name, decl, sourcePath);
+        if (expanded) {
+            return { ...expanded, summary: summary ?? expanded.summary };
+        }
+    }
+
+    if (Node.isInterfaceDeclaration(decl)) {
+        const fields = readPropsFromType(decl.getType(), decl);
+        return { kind: 'type', name, sourcePath, summary, fields, typeText: null, isConstant: false };
+    }
+
+    const typeNode = decl.getTypeNode();
+    if (typeNode && Node.isTypeLiteral(typeNode)) {
+        const fields = readPropsFromType(decl.getType(), decl);
+        if (fields.length > 0) {
+            return { kind: 'type', name, sourcePath, summary, fields, typeText: null, isConstant: false };
+        }
+        // Type literal without named props (e.g. only an index signature) — fall back to the source text.
+        return {
+            kind: 'type',
+            name,
+            sourcePath,
+            summary,
+            fields: null,
+            typeText: typeNode.getText(),
+            isConstant: false,
+        };
+    }
+
+    // Resolved-shape intersection — `type X = A & B` or `type X = SomeAlias`
+    // that itself resolves to one. Flatten into a fields table when the merged
+    // properties form a clean object bag (catches our own `address`/`network`
+    // plus the `query` / `mutation` catch-all from `QueryParameter` /
+    // `MutationParameter` without hand-rolling a mirror interface).
+    const resolvedType = decl.getType();
+    if (resolvedType.isIntersection() && !resolvedType.isUnion()) {
+        const fields = readPropsFromType(resolvedType, decl);
+        if (fields.length > 0) {
+            return { kind: 'type', name, sourcePath, summary, fields, typeText: null, isConstant: false };
+        }
+    }
+
+    const typeText = typeNode ? typeNode.getText() : resolvedType.getText(decl, FORMAT_FLAGS);
+    return { kind: 'type', name, sourcePath, summary, fields: null, typeText, isConstant: false };
+}
+
+function hasExtractTag(decl: Node): boolean {
+    if (!Node.isJSDocable(decl)) return false;
+    for (const doc of decl.getJsDocs()) {
+        for (const tag of doc.getTags()) {
+            if (tag.getTagName() === 'extract') return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * Resolves a `@extract`-tagged type alias to its underlying interface or type
+ * declaration (typically in another package) and reuses its shape. Returns
+ * null if the alias does not point at something extractable.
+ */
+function expandClassThroughExtract(
+    name: string,
+    decl: TypeAliasDeclaration,
+    sourcePath: string,
+): Omit<ExtractedClass, 'section' | 'category'> | null {
+    const targetDecl = resolveExtractTarget(decl);
+    if (!targetDecl || !Node.isClassDeclaration(targetDecl)) return null;
+    const aliasJsDoc = pickJsDoc(decl.getJsDocs());
+    const aliasSummary = readSummary(aliasJsDoc);
+    const inner = extractClass(name, targetDecl, sourcePath);
+    return { ...inner, summary: aliasSummary ?? inner.summary };
+}
+
+function expandThroughExtract(
+    name: string,
+    decl: TypeAliasDeclaration,
+    sourcePath: string,
+): Omit<ExtractedType, 'section' | 'category'> | null {
+    const targetDecl = resolveExtractTarget(decl);
+    if (targetDecl && (Node.isInterfaceDeclaration(targetDecl) || Node.isTypeAliasDeclaration(targetDecl))) {
+        return extractType(name, targetDecl, sourcePath);
+    }
+    // No named target outside this declaration — fall back to the structural form.
+    const typeText = decl.getType().getText(decl, FORMAT_FLAGS);
+    return { kind: 'type', name, sourcePath, summary: null, fields: null, typeText, isConstant: false };
+}
+
+/**
+ * Resolves a `@extract`-tagged type alias to the underlying declaration.
+ * Returns null if the resolution would loop back to the alias itself
+ * (which can happen when ts-morph's symbol resolver returns the alias node
+ * for re-exported types — guarding here prevents infinite recursion).
+ */
+function resolveExtractTarget(decl: TypeAliasDeclaration): Node | null {
+    // Prefer the type-node's identifier when the alias is `type X = Y` or
+    // `type X = Y<…>` — `getDefinitionNodes()` follows TypeScript's resolver
+    // through `import type` aliases all the way to the original class /
+    // interface / type declaration, even across packages.
+    const typeNode = decl.getTypeNode();
+    if (typeNode && Node.isTypeReference(typeNode)) {
+        const typeName = typeNode.getTypeName();
+        if (Node.isIdentifier(typeName)) {
+            for (const definition of typeName.getDefinitionNodes()) {
+                if (definition === decl) continue;
+                if (
+                    Node.isClassDeclaration(definition) ||
+                    Node.isInterfaceDeclaration(definition) ||
+                    Node.isTypeAliasDeclaration(definition)
+                ) {
+                    return definition;
+                }
+            }
+        }
+    }
+    // Fallback: use the resolved type's symbol chain (works for inline types).
+    const aliasedType = decl.getType();
+    let symbol = aliasedType.getAliasSymbol() ?? aliasedType.getSymbol();
+    if (!symbol) return null;
+    let next = symbol.getAliasedSymbol();
+    while (next) {
+        symbol = next;
+        next = symbol.getAliasedSymbol();
+    }
+    const targetDecl = symbol.getDeclarations()[0];
+    if (!targetDecl || targetDecl === decl) return null;
+    return targetDecl;
+}
+
+function extractClass(
+    name: string,
+    decl: ClassDeclaration,
+    sourcePath: string,
+): Omit<ExtractedClass, 'section' | 'category'> {
+    const jsdoc = pickJsDoc(decl.getJsDocs());
+    const summary = readSummary(jsdoc);
+    const examples = readExamples(jsdoc);
+    const samples = readSamples(jsdoc);
+    const ctor = decl.getConstructors()[0];
+    if (!ctor) {
+        return { kind: 'class', name, sourcePath, summary, constructorParams: null, examples, samples };
+    }
+    const ctorJsDoc = pickJsDoc(ctor.getJsDocs());
+    const ctorParamTags = readParamTags(ctorJsDoc);
+    const ctorExpandNames = readExpandNames(ctorJsDoc);
+    const constructorParams = expandParameters(ctor.getParameters(), decl, ctorParamTags, ctorExpandNames);
+    return { kind: 'class', name, sourcePath, summary, constructorParams, examples, samples };
+}
+
+function expandParameters(
+    params: ParameterDeclaration[],
+    contextNode: Node,
+    paramTags: Map<string, ParamTagInfo>,
+    expandNames: Set<string>,
+): ParamRow[] {
+    const rows: ParamRow[] = [];
+
+    const fnTypeParams = collectTypeParamDefaults(contextNode);
+
+    for (const param of params) {
+        const paramName = param.getName();
+        const paramType = param.getType();
+        const required = !param.hasQuestionToken() && !param.hasInitializer() && !param.isRestParameter();
+        const tagInfo = paramTags.get(paramName);
+        const rawSyntactic = param.getTypeNode()?.getText();
+        const paramSyntactic = rawSyntactic
+            ? substituteTypeParams(rawSyntactic, fnTypeParams)
+            : formatType(paramType, contextNode);
+
+        const shouldFlatten = expandNames.has(paramName) && isFlattenableObjectType(paramType);
+
+        if (shouldFlatten) {
+            rows.push({
+                name: paramName,
+                typeText: paramSyntactic,
+                typeOverride: tagInfo?.typeOverride ?? null,
+                required,
+                description: tagInfo?.description ?? null,
+            });
+            const declaredFields = readPropsFromType(paramType, contextNode);
+            for (const field of declaredFields) {
+                const tagKey = `${paramName}.${field.name}`;
+                const fieldTagInfo = paramTags.get(tagKey);
+                rows.push({
+                    ...field,
+                    name: `${paramName}.${field.name}`,
+                    typeOverride: fieldTagInfo?.typeOverride ?? field.typeOverride,
+                    description: field.description ?? fieldTagInfo?.description ?? null,
+                });
+            }
+            continue;
+        }
+
+        rows.push({
+            name: paramName,
+            typeText: paramSyntactic,
+            typeOverride: tagInfo?.typeOverride ?? null,
+            required,
+            description: tagInfo?.description ?? null,
+        });
+    }
+
+    return rows;
+}
+
+function expandComponentProps(params: ParameterDeclaration[], contextNode: Node): ParamRow[] {
+    if (params.length === 0) return [];
+    const propsParam = params[0];
+    return readPropsFromType(propsParam.getType(), contextNode);
+}
+
+function readPropsFromType(type: Type, contextNode: Node): ParamRow[] {
+    const rows: ParamRow[] = [];
+    for (const prop of type.getProperties()) {
+        const propName = prop.getName();
+        if (propName.startsWith('__@')) continue;
+
+        const valueDecl = prop.getValueDeclaration() ?? prop.getDeclarations()[0];
+        if (!valueDecl) continue;
+
+        const declPath = valueDecl.getSourceFile().getFilePath();
+        if (declPath.includes('/node_modules/')) continue;
+        if (declPath.includes('/typescript/lib/lib.')) continue;
+
+        const propType = prop.getTypeAtLocation(contextNode);
+        const optional = (prop.getFlags() & 16777216) !== 0; // ts.SymbolFlags.Optional
+        const description = readPropertyJsDoc(valueDecl);
+        const rawSyntactic =
+            Node.isPropertySignature(valueDecl) || Node.isPropertyDeclaration(valueDecl)
+                ? valueDecl.getTypeNode()?.getText()
+                : undefined;
+        const syntacticType = rawSyntactic
+            ? substituteTypeParams(rawSyntactic, collectTypeParamDefaults(valueDecl))
+            : formatType(propType, contextNode);
+        rows.push({
+            name: prop.getName(),
+            typeText: syntacticType,
+            typeOverride: null,
+            required: !optional,
+            description,
+        });
+    }
+    return rows;
+}
+
+/**
+ * Walks up to the nearest declaration with type parameters (interface, type
+ * alias, class, function) and returns a map from each parameter's name to its
+ * `Name = Default` annotation — falling back to `Name = any` when no default
+ * was declared.
+ *
+ * Used to expand generics in property and parameter type texts so readers see
+ * both the original placeholder and what it falls back to. `metadata: TMetadata`
+ * becomes `metadata: TMetadata = unknown`, and `Promise<TMetadata>` becomes
+ * `Promise<TMetadata = unknown>` — preserving the slot name the user can
+ * substitute by passing an explicit type argument.
+ */
+function collectTypeParamDefaults(start: Node): Map<string, string> {
+    const map = new Map<string, string>();
+    let cursor: Node | undefined = start;
+    while (cursor) {
+        if (
+            Node.isInterfaceDeclaration(cursor) ||
+            Node.isTypeAliasDeclaration(cursor) ||
+            Node.isClassDeclaration(cursor) ||
+            Node.isFunctionDeclaration(cursor) ||
+            Node.isMethodSignature(cursor) ||
+            Node.isMethodDeclaration(cursor) ||
+            Node.isFunctionExpression(cursor) ||
+            Node.isArrowFunction(cursor)
+        ) {
+            for (const tp of cursor.getTypeParameters()) {
+                const name = tp.getName();
+                if (map.has(name)) continue;
+                const def = tp.getDefault()?.getText() ?? 'any';
+                map.set(name, `${name} = ${def}`);
+            }
+        }
+        cursor = cursor.getParent();
+    }
+    return map;
+}
+
+function substituteTypeParams(typeText: string, params: Map<string, string>): string {
+    if (params.size === 0) return typeText;
+    const names = [...params.keys()].sort((a, b) => b.length - a.length);
+    const pattern = new RegExp(`\\b(${names.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})\\b`, 'g');
+    return typeText.replace(pattern, (m) => params.get(m) ?? m);
+}
+
+function isFlattenableObjectType(type: Type): boolean {
+    if (type.isUnion()) return false;
+    // Intersections like `Params & { providerId?: string }` resolve to a clean property bag —
+    // flattening them is fine as long as `getProperties()` returns something usable.
+    if (type.isIntersection()) return type.getProperties().length > 0;
+    if (!type.isObject()) return false;
+    if (type.getCallSignatures().length > 0) return false;
+    if (type.getConstructSignatures().length > 0) return false;
+    return type.getProperties().length > 0;
+}
+
+function formatType(type: Type, contextNode: Node): string {
+    return type.getText(contextNode, FORMAT_FLAGS).replace(/\s+/g, ' ');
+}
+
+function pickJsDoc(jsDocs: JSDoc[]): JSDoc | null {
+    return jsDocs.length > 0 ? jsDocs[jsDocs.length - 1] : null;
+}
+
+/**
+ * Read the leading `/** ... *\/` JSDoc-style comment attached to a property
+ * assignment inside an object literal. ts-morph's `PropertyAssignment` is not
+ * JSDocable, so we walk the raw leading-comment trivia.
+ */
+function readLeadingJsDocSummary(prop: Node): string | null {
+    for (const cr of prop.getLeadingCommentRanges()) {
+        const text = cr.getText();
+        if (!text.startsWith('/**')) continue;
+        const inner = text
+            .replace(/^\/\*\*+/, '')
+            .replace(/\*+\/$/, '')
+            .split('\n')
+            .map((line) => line.replace(/^\s*\*\s?/, ''))
+            .join('\n')
+            .trim();
+        if (inner) return sanitizeJsDocText(inner);
+    }
+    return null;
+}
+
+function readSummary(jsdoc: JSDoc | null): string | null {
+    if (!jsdoc) return null;
+    const desc = sanitizeJsDocText(jsdoc.getDescription());
+    if (!desc) return null;
+    // ts-morph occasionally attaches the file-level license header to the first
+    // declaration in a file when nothing else sits between them. Skip those —
+    // there is never a real description that begins with "Copyright (c)".
+    if (/^\s*Copyright\s*\(c\)/i.test(desc)) return null;
+    return desc;
+}
+
+interface ParamTagInfo {
+    description: string | null;
+    typeOverride: string | null;
+}
+
+function readParamTags(jsdoc: JSDoc | null): Map<string, ParamTagInfo> {
+    const map = new Map<string, ParamTagInfo>();
+    if (!jsdoc) return map;
+    for (const tag of jsdoc.getTags()) {
+        if (tag.getTagName() !== 'param') continue;
+        const paramTag = tag as JSDocParameterTag;
+        const nameNode = paramTag.getNameNode();
+        if (!nameNode) continue;
+        const name = nameNode.getText();
+        const raw = sanitizeJsDocText(stripTsDocDash(paramTag.getCommentText() ?? ''));
+        map.set(name, splitLeadingLink(raw));
+    }
+    return map;
+}
+
+/**
+ * If the text starts with a `{@link X}` marker (planted by sanitizeJsDocText),
+ * extracts X as a type-override and returns the rest as the description.
+ */
+function splitLeadingLink(text: string): ParamTagInfo {
+    if (text.startsWith(LINK_MARKER_OPEN)) {
+        const end = text.indexOf(LINK_MARKER_CLOSE, LINK_MARKER_OPEN.length);
+        if (end !== -1) {
+            const target = text.slice(LINK_MARKER_OPEN.length, end).trim();
+            const remaining = text.slice(end + LINK_MARKER_CLOSE.length).trim();
+            return { typeOverride: target, description: remaining || null };
+        }
+    }
+    return { typeOverride: null, description: text || null };
+}
+
+/** TSDoc writes `@param name - description`; strip the leading dash. */
+function stripTsDocDash(text: string): string {
+    return text.replace(/^\s*[-–—]\s*/, '');
+}
+
+function readExamples(jsdoc: JSDoc | null): string[] {
+    if (!jsdoc) return [];
+    const out: string[] = [];
+    for (const tag of jsdoc.getTags()) {
+        if (tag.getTagName() !== 'example') continue;
+        const text = tag.getCommentText()?.trim();
+        if (text) out.push(text);
+    }
+    return out;
+}
+
+function readExpandNames(jsdoc: JSDoc | null): Set<string> {
+    const out = new Set<string>();
+    if (!jsdoc) return out;
+    for (const tag of jsdoc.getTags()) {
+        if (tag.getTagName() !== 'expand') continue;
+        const text = tag.getCommentText()?.trim();
+        if (text) out.add(text);
+    }
+    return out;
+}
+
+function readSamples(jsdoc: JSDoc | null): string[] {
+    if (!jsdoc) return [];
+    const out: string[] = [];
+    for (const tag of jsdoc.getTags()) {
+        if (tag.getTagName() !== 'sample') continue;
+        const text = tag.getCommentText()?.trim();
+        if (!text) continue;
+        if (!text.includes('#')) {
+            throw new Error(`Invalid @sample value: "${text}". Expected format \`dir/path#SAMPLE_NAME\`.`);
+        }
+        out.push(text);
+    }
+    return out;
+}
+
+function readReturnInfo(jsdoc: JSDoc | null): ParamTagInfo {
+    const empty: ParamTagInfo = { description: null, typeOverride: null };
+    if (!jsdoc) return empty;
+    for (const tag of jsdoc.getTags()) {
+        const tagName = tag.getTagName();
+        if (tagName !== 'returns' && tagName !== 'return') continue;
+        const raw = sanitizeJsDocText(stripTsDocDash(tag.getCommentText() ?? ''));
+        return splitLeadingLink(raw);
+    }
+    return empty;
+}
+
+function readPropertyJsDoc(node: Node): string | null {
+    if (!Node.isJSDocable(node)) return null;
+    const docs = node.getJsDocs();
+    if (docs.length === 0) return null;
+    const desc = sanitizeJsDocText(docs[docs.length - 1].getDescription());
+    return desc || null;
+}
+
+export const LINK_MARKER_OPEN = 'LINK:';
+export const LINK_MARKER_CLOSE = '
';
+
+/**
+ * Replaces JSDoc inline tags with sanitized text. {@link Foo} survives as a
+ * sentinel marker (LINK_MARKER_OPEN…LINK_MARKER_CLOSE) so the renderer can
+ * later turn it into a markdown link if `Foo` is itself documented in the
+ * same reference. Other inline tags ({@linkcode}, {@see}, …) collapse to
+ * their target/label text. Loose `{`/`}` are escaped so MDX doesn't treat
+ * them as JS expressions.
+ */
+function sanitizeJsDocText(text: string): string {
+    let result = text.replace(
+        /\{@link\s+([^}|]+?)(?:\s*\|\s*[^}]*)?\}/g,
+        (_, target: string) => `${LINK_MARKER_OPEN}${target.trim()}${LINK_MARKER_CLOSE}`,
+    );
+    result = result.replace(
+        /\{@(linkcode|linkplain|inheritDoc|see|tutorial|label)\s+([^}]*)\}/g,
+        (_, _tag: string, body: string) => {
+            const trimmed = body.trim();
+            const pipeIdx = trimmed.indexOf('|');
+            if (pipeIdx >= 0) return trimmed.slice(pipeIdx + 1).trim();
+            return trimmed;
+        },
+    );
+    return result.replace(/[{}]/g, (m) => `\\${m}`).trim();
+}
diff --git a/docs/reference-generator/src/index.ts b/docs/reference-generator/src/index.ts
new file mode 100644
index 000000000..fc5512c56
--- /dev/null
+++ b/docs/reference-generator/src/index.ts
@@ -0,0 +1,114 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { collectPublicApi } from './collect';
+import { extract } from './extract';
+import type { Extracted } from './extract';
+import { render } from './render';
+import type { PackageKey } from './render';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(HERE, '../../..');
+
+const PACKAGES: Record<PackageKey, string> = {
+    appkit: 'packages/appkit',
+    'appkit-react': 'packages/appkit-react',
+};
+
+/**
+ * URL prefixes used to point cross-package `{@link X}` references at sibling
+ * reference pages in the published docs. Keyed by `PackageKey`; appended
+ * before `#anchor` when a symbol resolves to a different package.
+ */
+const PUBLISHED_URL: Record<PackageKey, string> = {
+    appkit: '/ecosystem/appkit/reference/appkit',
+    'appkit-react': '/ecosystem/appkit/reference/appkit-react',
+};
+
+function parseTargets(argv: string[]): PackageKey[] {
+    const flag = argv.find((a) => a.startsWith('--package='));
+    const value = flag?.split('=')[1] ?? 'all';
+    if (value === 'all') return ['appkit', 'appkit-react'];
+    if (value === 'appkit' || value === 'appkit-react') return [value];
+    throw new Error(`Unknown --package value: ${value}`);
+}
+
+function collectForPackage(pkg: PackageKey): Extracted[] {
+    const packagePath = join(REPO_ROOT, PACKAGES[pkg]);
+    const collected = collectPublicApi({ packagePath });
+    const extracted: Extracted[] = collected.map(extract);
+
+    const missing = extracted
+        .map((e) => {
+            const tags: string[] = [];
+            if (!e.category) tags.push('@category');
+            if (!e.section) tags.push('@section');
+            return tags.length > 0 ? { name: e.name, sourcePath: e.sourcePath, tags } : null;
+        })
+        .filter((m): m is { name: string; sourcePath: string; tags: string[] } => m !== null);
+
+    if (missing.length > 0) {
+        const list = missing.map((m) => `  - ${m.name}  (${m.sourcePath}) — missing ${m.tags.join(', ')}`).join('\n');
+        throw new Error(
+            `[${pkg}] ${missing.length} public export(s) missing required JSDoc tags:\n${list}\n\n` +
+                `Every @public symbol must declare both @category (top-level group, e.g. \`@category Action\`) and @section (sub-group, e.g. \`@section Balances\`).`,
+        );
+    }
+
+    return extracted;
+}
+
+function main(): void {
+    const targets = parseTargets(process.argv.slice(2));
+
+    // Collect both packages first so each render pass knows which symbols live
+    // in the sibling document and can emit absolute URLs instead of dead local
+    // anchors for cross-package `{@link X}` references.
+    const collected: Record<PackageKey, Extracted[]> = {
+        appkit: collectForPackage('appkit'),
+        'appkit-react': collectForPackage('appkit-react'),
+    };
+
+    for (const pkg of targets) {
+        const externalRefs = new Map<string, string>();
+        for (const otherPkg of Object.keys(collected) as PackageKey[]) {
+            if (otherPkg === pkg) continue;
+            for (const entry of collected[otherPkg]) {
+                externalRefs.set(entry.name, PUBLISHED_URL[otherPkg]);
+            }
+        }
+
+        // Package prefixes for the explicit `{@link pkg:Name}` form. The
+        // current package maps to an empty prefix so authors can write
+        // qualified links from within their own package and still get local
+        // anchors instead of fully-qualified URLs.
+        const packagePrefixes = new Map<string, string>();
+        for (const otherPkg of Object.keys(collected) as PackageKey[]) {
+            packagePrefixes.set(otherPkg, otherPkg === pkg ? '' : PUBLISHED_URL[otherPkg]);
+        }
+
+        const output = render(collected[pkg], { externalRefs, packagePrefixes });
+        const entryCount = collected[pkg].length;
+
+        const outPath = join(REPO_ROOT, 'docs/templates/packages', pkg, 'docs/reference.md');
+        const target = `packages/${pkg}/docs/reference.md`;
+        const frontMatter = `---\ntarget: ${target}\n---\n\n`;
+
+        mkdirSync(dirname(outPath), { recursive: true });
+        writeFileSync(outPath, frontMatter + output);
+
+        const relativePath = outPath.slice(REPO_ROOT.length + 1);
+        console.log(`✓ ${relativePath} (${entryCount} entries) → target ${target}`);
+    }
+}
+
+main();
diff --git a/docs/reference-generator/src/render.ts b/docs/reference-generator/src/render.ts
new file mode 100644
index 000000000..02b7d588b
--- /dev/null
+++ b/docs/reference-generator/src/render.ts
@@ -0,0 +1,416 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import { LINK_MARKER_CLOSE, LINK_MARKER_OPEN } from './extract';
+import type {
+    Extracted,
+    ExtractedClass,
+    ExtractedComponent,
+    ExtractedFunction,
+    ExtractedNamespaceComponent,
+    ExtractedType,
+    ParamRow,
+} from './extract';
+
+export type PackageKey = 'appkit' | 'appkit-react';
+
+const TODO_MARKER = '_TODO: describe_';
+
+const CATEGORY_ORDER = ['Class', 'Action', 'Hook', 'Component', 'Type', 'Constants'];
+
+/**
+ * Symbol-name → URL-prefix map used to resolve unqualified `{@link X}`
+ * references and type-cell auto-links. Empty string means "local to this
+ * document" (the link resolves to `#anchor`); a non-empty prefix is
+ * prepended before `#anchor` so the reference points to a sibling reference
+ * page in the published docs.
+ */
+let LINKABLE: Map<string, string> = new Map();
+
+/**
+ * Package-prefix → URL map used to resolve qualified `{@link pkg:Name}`
+ * references. The current package is included with an empty prefix so authors
+ * can write `{@link appkit-react:Foo}` from inside appkit-react and still get
+ * a local anchor.
+ */
+let PACKAGE_PREFIX: Map<string, string> = new Map();
+
+export interface RenderOptions {
+    /** Symbols documented in other packages, keyed by name with their URL prefix as value. */
+    externalRefs?: Map<string, string>;
+    /** Map of package-key → URL prefix (current package's value should be `""`). Enables `{@link pkg:Name}` syntax. */
+    packagePrefixes?: Map<string, string>;
+}
+
+export function render(extracted: Extracted[], options: RenderOptions = {}): string {
+    const externalRefs = options.externalRefs ?? new Map();
+    PACKAGE_PREFIX = options.packagePrefixes ?? new Map();
+
+    LINKABLE = new Map();
+    for (const [name, prefix] of externalRefs) LINKABLE.set(name, prefix);
+    // Local entries override any external mapping with the same name.
+    for (const e of extracted) LINKABLE.set(e.name, '');
+
+    const parts: string[] = [];
+
+    const byCategory = groupByCategory(extracted);
+    const categories = sortCategories([...byCategory.keys()]);
+
+    for (const category of categories) {
+        const entries = byCategory.get(category)!;
+        appendCategoryBlock(parts, category, entries);
+    }
+
+    return (
+        parts
+            .join('\n')
+            .replace(/\n{3,}/g, '\n\n')
+            .trimEnd() + '\n'
+    );
+}
+
+function groupByCategory(extracted: Extracted[]): Map<string, Extracted[]> {
+    const grouped = new Map<string, Extracted[]>();
+    for (const item of extracted) {
+        const list = grouped.get(item.category) ?? [];
+        list.push(item);
+        grouped.set(item.category, list);
+    }
+    return grouped;
+}
+
+function sortCategories(categories: string[]): string[] {
+    const known = CATEGORY_ORDER.filter((t) => categories.includes(t));
+    const others = categories.filter((t) => !CATEGORY_ORDER.includes(t)).sort();
+    return [...known, ...others];
+}
+
+function appendCategoryBlock(parts: string[], category: string, entries: Extracted[]): void {
+    parts.push(`## ${category}`);
+    parts.push('');
+
+    const grouped = new Map<string, Extracted[]>();
+    for (const item of entries) {
+        const list = grouped.get(item.section) ?? [];
+        list.push(item);
+        grouped.set(item.section, list);
+    }
+    for (const list of grouped.values()) {
+        list.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    }
+
+    const orderedSections = [...grouped.keys()].sort();
+
+    for (const sectionTitle of orderedSections) {
+        const sectionEntries = grouped.get(sectionTitle)!;
+        parts.push(`### ${sectionTitle}`);
+        parts.push('');
+        for (const entry of sectionEntries) {
+            parts.push(renderEntry(entry, '####'));
+            parts.push('');
+        }
+    }
+}
+
+type HeadingLevel = '###' | '####';
+
+function renderEntry(entry: Extracted, level: HeadingLevel): string {
+    switch (entry.kind) {
+        case 'function':
+            return renderFunction(entry, level);
+        case 'component':
+            return renderComponent(entry, level);
+        case 'componentNamespace':
+            return renderNamespaceComponent(entry, level);
+        case 'type':
+            return renderType(entry, level);
+        case 'class':
+            return renderClass(entry, level);
+    }
+}
+
+function renderFunction(entry: ExtractedFunction, level: HeadingLevel): string {
+    const lines: string[] = [];
+    lines.push(`${level} ${entry.name}`);
+    lines.push('');
+    lines.push(resolveLinks(entry.summary ?? TODO_MARKER));
+    lines.push('');
+    if (entry.params.length > 0) {
+        lines.push(renderParamsTable(entry.params));
+        lines.push('');
+    }
+    const returnType = entry.returnTypeOverride
+        ? formatTypeOverride(entry.returnTypeOverride)
+        : formatTypeCell(entry.returnTypeText);
+    if (entry.returnDescription) {
+        const desc = resolveLinks(entry.returnDescription).replace(/\r?\n/g, ' ');
+        lines.push(`Returns: ${returnType} — ${desc}`);
+    } else {
+        lines.push(`Returns: ${returnType}.`);
+    }
+    appendExamples(lines, entry.examples, entry.samples);
+    return lines.join('\n');
+}
+
+function renderComponent(entry: ExtractedComponent, level: HeadingLevel): string {
+    const lines: string[] = [];
+    lines.push(`${level} ${entry.name}`);
+    lines.push('');
+    lines.push(resolveLinks(entry.summary ?? TODO_MARKER));
+    lines.push('');
+    if (entry.props.length > 0) {
+        lines.push(renderPropsTable(entry.props));
+    }
+    appendExamples(lines, entry.examples, entry.samples);
+    return lines.join('\n');
+}
+
+function renderNamespaceComponent(entry: ExtractedNamespaceComponent, level: HeadingLevel): string {
+    const memberLevel = level === '###' ? '####' : '#####';
+    const lines: string[] = [];
+    lines.push(`${level} ${entry.name}`);
+    lines.push('');
+    lines.push(resolveLinks(entry.summary ?? TODO_MARKER));
+    lines.push('');
+    lines.push(`Compound component. Members:`);
+    lines.push('');
+    for (const member of entry.members) {
+        lines.push(`${memberLevel} ${entry.name}.${member.name}`);
+        lines.push('');
+        lines.push(resolveLinks(member.summary ?? TODO_MARKER));
+        lines.push('');
+        if (member.props.length > 0) {
+            lines.push(renderPropsTable(member.props));
+            lines.push('');
+        }
+    }
+    return lines.join('\n').trimEnd();
+}
+
+function renderType(entry: ExtractedType, level: HeadingLevel): string {
+    const lines: string[] = [];
+    lines.push(`${level} ${entry.name}`);
+    lines.push('');
+    lines.push(resolveLinks(entry.summary ?? TODO_MARKER));
+    lines.push('');
+    if (entry.fields && entry.fields.length > 0) {
+        lines.push(renderFieldsTable(entry.fields));
+    } else if (entry.typeText) {
+        lines.push('```ts');
+        const keyword = entry.isConstant ? 'const' : 'type';
+        const operator = entry.isConstant ? '=' : '=';
+        lines.push(`${keyword} ${entry.name} ${operator} ${entry.typeText};`);
+        lines.push('```');
+    } else {
+        lines.push('_Empty type._');
+    }
+    return lines.join('\n');
+}
+
+function renderClass(entry: ExtractedClass, level: HeadingLevel): string {
+    const lines: string[] = [];
+    lines.push(`${level} ${entry.name}`);
+    lines.push('');
+    lines.push(resolveLinks(entry.summary ?? TODO_MARKER));
+    lines.push('');
+    if (entry.constructorParams && entry.constructorParams.length > 0) {
+        const topLevelNames = entry.constructorParams.filter((p) => !p.name.includes('.')).map((p) => p.name);
+        lines.push(`Constructor: \`new ${entry.name}(${topLevelNames.join(', ')})\``);
+        lines.push('');
+        lines.push(renderParamsTable(entry.constructorParams));
+    } else {
+        lines.push(`Constructor: \`new ${entry.name}()\``);
+    }
+    appendExamples(lines, entry.examples, entry.samples);
+    return lines.join('\n');
+}
+
+function appendExamples(lines: string[], examples: string[], samples: string[]): void {
+    const total = examples.length + samples.length;
+    if (total === 0) return;
+    lines.push('');
+    lines.push(total > 1 ? '**Examples**' : '**Example**');
+    lines.push('');
+    for (const example of examples) {
+        lines.push(example);
+        lines.push('');
+    }
+    for (const sample of samples) {
+        lines.push(`%%${sample}%%`);
+        lines.push('');
+    }
+}
+
+function renderParamsTable(rows: ParamRow[]): string {
+    return renderRowsTable('Parameter', rows);
+}
+
+function renderPropsTable(rows: ParamRow[]): string {
+    return renderRowsTable('Prop', rows);
+}
+
+function renderFieldsTable(rows: ParamRow[]): string {
+    return renderRowsTable('Field', rows);
+}
+
+function renderRowsTable(firstHeader: string, rows: ParamRow[]): string {
+    const headers = [firstHeader, 'Type', 'Description'];
+    return renderTable(
+        headers,
+        rows.map((r) => [
+            `\`${r.name}\`${r.required ? '\\*' : ''}`,
+            r.typeOverride ? formatTypeOverride(r.typeOverride) : formatTypeCell(r.typeText),
+            resolveLinks(r.description ?? TODO_MARKER),
+        ]),
+    );
+}
+
+function renderTable(headers: string[], rows: string[][]): string {
+    const lines: string[] = [];
+    lines.push(`| ${headers.join(' | ')} |`);
+    lines.push(`| ${headers.map(() => '---').join(' | ')} |`);
+    for (const row of rows) {
+        lines.push(`| ${row.map((cell) => cell.replace(/\r?\n/g, ' ')).join(' | ')} |`);
+    }
+    return lines.join('\n');
+}
+
+function escapeForCell(text: string): string {
+    return text.replace(/\|/g, '\\|');
+}
+
+/**
+ * Renders a type cell as a single `<code>` chip with linked names inlined as
+ * `<a>` children. The wrapping `<code>` keeps Mintlify's chip styling unified
+ * across the whole compound type (e.g., `ConnectorInput[]` stays one chip
+ * instead of fragmenting into a chip-link + plain chip combo), while the
+ * inline `<a>` preserves the precise link scope on the symbol name only.
+ */
+function formatTypeCell(typeText: string): string {
+    if (LINKABLE.size === 0) return '`' + escapeForCell(typeText) + '`';
+
+    const names = [...LINKABLE.keys()].sort((a, b) => b.length - a.length);
+    const pattern = new RegExp(`\\b(${names.map(escapeRegex).join('|')})\\b`, 'g');
+
+    let body = '';
+    let lastIndex = 0;
+    let match: RegExpExecArray | null;
+    let matched = false;
+    while ((match = pattern.exec(typeText)) !== null) {
+        matched = true;
+        if (match.index > lastIndex) {
+            body += escapeHtmlInCell(typeText.slice(lastIndex, match.index));
+        }
+        const prefix = LINKABLE.get(match[1]) ?? '';
+        body += `<a href="${prefix}#${slugify(match[1])}">${match[1]}</a>`;
+        lastIndex = pattern.lastIndex;
+    }
+    if (!matched) return '`' + escapeForCell(typeText) + '`';
+    if (lastIndex < typeText.length) {
+        body += escapeHtmlInCell(typeText.slice(lastIndex));
+    }
+    return `<code>${body}</code>`;
+}
+
+function escapeHtmlInCell(text: string): string {
+    // `{`/`}` need entity escapes because Mintlify's MDX parser treats them as
+    // JSX-expression delimiters even inside `<code>` blocks.
+    return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/\{/g, '&lbrace;')
+        .replace(/\}/g, '&rbrace;')
+        .replace(/\|/g, '\\|');
+}
+
+function escapeRegex(str: string): string {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Renders a type-override that the author requested via `{@link X}` (or
+ * `{@link pkg:X}`) at the start of a `@param` or `@returns` description.
+ * Qualified forms point at the matching sibling reference; unqualified forms
+ * use the LINKABLE lookup. Unknown package prefixes throw — same contract as
+ * `resolveLinks` — so authors can't accidentally ship a dead chip.
+ */
+function formatTypeOverride(raw: string): string {
+    const colon = raw.indexOf(':');
+    if (colon > 0) {
+        const pkg = raw.slice(0, colon).trim();
+        const name = raw.slice(colon + 1).trim();
+        if (!PACKAGE_PREFIX.has(pkg)) {
+            const known = [...PACKAGE_PREFIX.keys()].join(', ');
+            throw new Error(`Unknown package prefix in {@link ${raw}}. Got "${pkg}"; expected one of: ${known}.`);
+        }
+        const prefix = PACKAGE_PREFIX.get(pkg) ?? '';
+        return `[\`${name}\`](${prefix}#${slugify(name)})`;
+    }
+    if (LINKABLE.has(raw)) {
+        const prefix = LINKABLE.get(raw) ?? '';
+        return `[\`${raw}\`](${prefix}#${slugify(raw)})`;
+    }
+    return '`' + raw + '`';
+}
+
+function slugify(name: string): string {
+    return name.toLowerCase();
+}
+
+/**
+ * Resolves `{@link Foo}` markers (planted by sanitizeJsDocText) into markdown
+ * links. Two forms are recognized:
+ *
+ *  - **Qualified** `{@link pkg:Name}` — the prefix names a sibling package
+ *    from `PACKAGE_PREFIX`; the link gets that package's URL prefix. Unknown
+ *    package prefixes fall through to the unqualified path (treats the colon
+ *    as part of the symbol name and emits a dead local anchor).
+ *  - **Unqualified** `{@link Foo}` — looked up in `LINKABLE`: local names
+ *    resolve to `#anchor`, cross-package names get the sibling reference's
+ *    URL prefix, anything else emits a dead local anchor.
+ *
+ * In both cases the displayed text is the bare symbol name (without the
+ * package prefix), so qualified and unqualified forms render identically.
+ */
+function resolveLinks(text: string): string {
+    if (!text.includes(LINK_MARKER_OPEN)) return text;
+    const out: string[] = [];
+    let cursor = 0;
+    while (cursor < text.length) {
+        const start = text.indexOf(LINK_MARKER_OPEN, cursor);
+        if (start === -1) {
+            out.push(text.slice(cursor));
+            break;
+        }
+        out.push(text.slice(cursor, start));
+        const end = text.indexOf(LINK_MARKER_CLOSE, start + LINK_MARKER_OPEN.length);
+        if (end === -1) {
+            out.push(text.slice(start));
+            break;
+        }
+        const raw = text.slice(start + LINK_MARKER_OPEN.length, end).trim();
+
+        const colon = raw.indexOf(':');
+        if (colon > 0) {
+            const pkg = raw.slice(0, colon).trim();
+            const name = raw.slice(colon + 1).trim();
+            if (!PACKAGE_PREFIX.has(pkg)) {
+                const known = [...PACKAGE_PREFIX.keys()].join(', ');
+                throw new Error(`Unknown package prefix in {@link ${raw}}. Got "${pkg}"; expected one of: ${known}.`);
+            }
+            const prefix = PACKAGE_PREFIX.get(pkg) ?? '';
+            out.push(`[\`${name}\`](${prefix}#${slugify(name)})`);
+        } else {
+            const prefix = LINKABLE.get(raw) ?? '';
+            out.push(`[\`${raw}\`](${prefix}#${slugify(raw)})`);
+        }
+        cursor = end + LINK_MARKER_CLOSE.length;
+    }
+    return out.join('');
+}
diff --git a/docs/reference-generator/tsconfig.json b/docs/reference-generator/tsconfig.json
new file mode 100644
index 000000000..67fb71213
--- /dev/null
+++ b/docs/reference-generator/tsconfig.json
@@ -0,0 +1,15 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "module": "ESNext",
+        "moduleResolution": "Bundler",
+        "target": "ES2022",
+        "strict": true,
+        "noImplicitAny": true,
+        "skipLibCheck": true,
+        "esModuleInterop": true,
+        "resolveJsonModule": true,
+        "noEmit": true
+    },
+    "include": ["src/**/*"]
+}
diff --git a/docs/template-resolver/package.json b/docs/template-resolver/package.json
new file mode 100644
index 000000000..9679068f3
--- /dev/null
+++ b/docs/template-resolver/package.json
@@ -0,0 +1,19 @@
+{
+    "name": "@ton/template-resolver",
+    "version": "0.0.0",
+    "private": true,
+    "type": "module",
+    "description": "Resolves %%dir/path#SAMPLE_NAME%% placeholders in docs/templates/**/*.md by injecting code from SAMPLE_START/SAMPLE_END blocks in the source tree.",
+    "scripts": {
+        "resolve": "tsx src/index.ts",
+        "typecheck": "tsc --noEmit"
+    },
+    "dependencies": {
+        "eslint": "^9.39.4",
+        "prettier": "^3.6.2"
+    },
+    "devDependencies": {
+        "tsx": "^4.21.0",
+        "typescript": "~5.9.3"
+    }
+}
diff --git a/scripts/extract-samples.ts b/docs/template-resolver/src/extract-samples.ts
similarity index 100%
rename from scripts/extract-samples.ts
rename to docs/template-resolver/src/extract-samples.ts
diff --git a/scripts/update-docs.ts b/docs/template-resolver/src/index.ts
similarity index 90%
rename from scripts/update-docs.ts
rename to docs/template-resolver/src/index.ts
index ce49f84f8..706405fcd 100644
--- a/scripts/update-docs.ts
+++ b/docs/template-resolver/src/index.ts
@@ -8,12 +8,18 @@
 
 import fs from 'fs/promises';
 import path from 'path';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
 
 import { ESLint } from 'eslint';
 import * as prettier from 'prettier';
 
 import { extractSamplesFromFile } from './extract-samples';
 
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(HERE, '../../..');
+const TEMPLATES_DIR_NAME = 'docs/templates';
+
 type Placeholder = {
     raw: string;
     body: string;
@@ -35,7 +41,6 @@ function validateDirPath(dirPath: string): void {
 }
 
 function isJSXCode(code: string): boolean {
-    // Check if code contains JSX syntax (tags like <div>, <span>, etc.)
     const jsxPattern = /<[A-Za-z][A-Za-z0-9]*(\s|>)/;
     return jsxPattern.test(code);
 }
@@ -50,16 +55,16 @@ async function formatSampleCode(sample: string, filePath?: string): Promise<stri
     const parser = isJSX ? 'typescript' : 'typescript';
     const tempFilePath = filePath || (isJSX ? 'temp.tsx' : 'temp.ts');
 
-    const prettierConfig = await prettier.resolveConfig(process.cwd());
+    const prettierConfig = await prettier.resolveConfig(REPO_ROOT);
     let formatted = await prettier.format(trimmed, {
         ...prettierConfig,
         parser,
     });
     formatted = formatted.trimEnd();
 
-    const eslintConfigPath = path.resolve(process.cwd(), 'eslint.config.js');
+    const eslintConfigPath = path.resolve(REPO_ROOT, 'eslint.config.js');
     const eslint = new ESLint({
-        cwd: process.cwd(),
+        cwd: REPO_ROOT,
         overrideConfigFile: eslintConfigPath,
         overrideConfig: {
             rules: {
@@ -81,7 +86,7 @@ async function formatSampleCode(sample: string, filePath?: string): Promise<stri
 }
 
 async function findTemplateFiles(): Promise<string[]> {
-    const templateDir = path.resolve('template');
+    const templateDir = path.resolve(REPO_ROOT, TEMPLATES_DIR_NAME);
     try {
         const stat = await fs.stat(templateDir);
         if (!stat.isDirectory()) {
@@ -223,7 +228,6 @@ async function resolvePlaceholder(
         }
     }
 
-    // SAMPLE_NAME_1, SAMPLE_NAME_2, ..., SAMPLE_NAME_N
     let sample = allSamples.get(placeholder.sampleName);
 
     if (!sample) {
@@ -237,7 +241,6 @@ async function resolvePlaceholder(
                 if (!isNaN(index)) {
                     parts.push({ name, code, index });
                     if (!sourceFilePath) {
-                        // Find the file that contains this sample
                         for (const file of files) {
                             const fileSamples = sampleCache.get(file);
                             if (fileSamples?.has(name)) {
@@ -259,7 +262,6 @@ async function resolvePlaceholder(
         parts.sort((a, b) => a.index - b.index);
         sample = parts.map((p) => p.code).join('\n\n');
     } else {
-        // Find the file that contains this sample
         for (const file of files) {
             const fileSamples = sampleCache.get(file);
             if (fileSamples?.has(placeholder.sampleName)) {
@@ -277,7 +279,6 @@ async function resolvePlaceholder(
 }
 
 async function processTemplateFile(templatePath: string): Promise<void> {
-    const cwd = process.cwd();
     const templateContent = await fs.readFile(templatePath, 'utf8');
 
     const { params, body: templateBody } = parseTemplateParams(templateContent);
@@ -286,16 +287,14 @@ async function processTemplateFile(templatePath: string): Promise<void> {
 
     const sampleCache = new Map<string, Map<string, string>>();
 
-    // Replace placeholders
     let result = templateBody;
     for (const placeholder of placeholders) {
-        const injected = await resolvePlaceholder(cwd, placeholder, sampleCache);
+        const injected = await resolvePlaceholder(REPO_ROOT, placeholder, sampleCache);
         result = result.replace(placeholder.raw, injected);
     }
 
-    // Use target from template parameters
-    const outPath = path.resolve(cwd, params.target);
-    const sourceRelative = path.relative(cwd, templatePath);
+    const outPath = path.resolve(REPO_ROOT, params.target);
+    const sourceRelative = path.relative(REPO_ROOT, templatePath);
     const generatedHeader = `<!--
 This file is auto-generated. Do not edit manually.
 Changes will be overwritten when running the docs update script.
@@ -305,18 +304,20 @@ Source template: ${sourceRelative}
 `;
     await fs.mkdir(path.dirname(outPath), { recursive: true });
     await fs.writeFile(outPath, generatedHeader + result, 'utf8');
-    console.log(`Updated markdown: ${path.relative(cwd, outPath)} from ${path.relative(cwd, templatePath)}`);
+    console.log(
+        `Updated markdown: ${path.relative(REPO_ROOT, outPath)} from ${path.relative(REPO_ROOT, templatePath)}`,
+    );
 }
 
 async function main(): Promise<void> {
     const templates = await findTemplateFiles();
     if (templates.length === 0) {
-        console.log('No template/*.md files found, nothing to update.');
+        console.log(`No ${TEMPLATES_DIR_NAME}/**/*.md files found, nothing to update.`);
         return;
     }
 
     for (const templatePath of templates) {
-        console.log(`Processing template: ${templatePath}`);
+        console.log(`Processing template: ${path.relative(REPO_ROOT, templatePath)}`);
         await processTemplateFile(templatePath);
     }
 }
diff --git a/docs/template-resolver/tsconfig.json b/docs/template-resolver/tsconfig.json
new file mode 100644
index 000000000..67fb71213
--- /dev/null
+++ b/docs/template-resolver/tsconfig.json
@@ -0,0 +1,15 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "module": "ESNext",
+        "moduleResolution": "Bundler",
+        "target": "ES2022",
+        "strict": true,
+        "noImplicitAny": true,
+        "skipLibCheck": true,
+        "esModuleInterop": true,
+        "resolveJsonModule": true,
+        "noEmit": true
+    },
+    "include": ["src/**/*"]
+}
diff --git a/template/packages/appkit-react/README.md b/docs/templates/packages/appkit-react/README.md
similarity index 91%
rename from template/packages/appkit-react/README.md
rename to docs/templates/packages/appkit-react/README.md
index 9fcb11346..bf3b60587 100644
--- a/template/packages/appkit-react/README.md
+++ b/docs/templates/packages/appkit-react/README.md
@@ -38,7 +38,7 @@ Initialize `QueryClient` and `AppKit`, then wrap your application in `QueryClien
 > [!NOTE]
 > Don't forget to import styles from `@ton/appkit-react/styles.css`.
 
-%%demo/examples/src/appkit#APPKIT_REACT_INIT%%
+%%docs/examples/src/appkit#APPKIT_REACT_INIT%%
 [Read more about TanStack Query](https://tanstack.com/query/latest/docs/framework/react/overview)
 
 ### TonConnect Configuration
@@ -95,7 +95,7 @@ export const Balance = () => {
         return <div>Loading...</div>;
     }
 
-    return <div>Balance: {balance?.toString()} TON</div>;
+    return <div>Balance: {balance || 0} TON</div>;
 };
 ```
 
@@ -105,7 +105,7 @@ export const Balance = () => {
 
 Use the `Send` component to trigger a transaction from a button. It handles the entire send flow.
 
-%%demo/examples/src/appkit/components/transaction#TRANSACTION%%
+%%docs/examples/src/appkit/components/transaction#TRANSACTION%%
 
 For a custom UI, use `SendProvider` with `useSendContext` — see [Components Documentation](./docs/components.md#sendprovider).
 
@@ -125,7 +125,7 @@ npm install @ston-fi/omniston-sdk
 
 Initialize `AppKit` with `OmnistonSwapProvider`:
 
-%%demo/examples/src/appkit/swap#SWAP_PROVIDER_INIT%%
+%%docs/examples/src/appkit/swap#SWAP_PROVIDER_INIT%%
 
 ### Hooks
 
@@ -143,9 +143,9 @@ Use `useStakingQuote` to get a staking/unstaking quote and `useBuildStakeTransac
 
 [Read more about Staking](https://github.com/ton-connect/kit/tree/main/packages/appkit/docs/staking.md)
 
-%%demo/examples/src/appkit/hooks/staking#USE_STAKING_QUOTE%%
+%%docs/examples/src/appkit/hooks/staking#USE_STAKING_QUOTE%%
 
-%%demo/examples/src/appkit/hooks/staking#USE_BUILD_STAKE_TRANSACTION%%
+%%docs/examples/src/appkit/hooks/staking#USE_BUILD_STAKE_TRANSACTION%%
 
 ## Migration from TonConnect UI
 
@@ -153,7 +153,7 @@ Use `useStakingQuote` to get a staking/unstaking quote and `useBuildStakeTransac
 
 You can use standard TonConnect hooks in your components:
 
-%%demo/examples/src/appkit#APPKIT_REACT_TONCONNECT_HOOKS%%
+%%docs/examples/src/appkit#APPKIT_REACT_TONCONNECT_HOOKS%%
 
 ## License
 
diff --git a/template/packages/appkit-react/docs/components.md b/docs/templates/packages/appkit-react/docs/components.md
similarity index 69%
rename from template/packages/appkit-react/docs/components.md
rename to docs/templates/packages/appkit-react/docs/components.md
index fb087ab8b..8673ed69b 100644
--- a/template/packages/appkit-react/docs/components.md
+++ b/docs/templates/packages/appkit-react/docs/components.md
@@ -12,7 +12,7 @@ target: packages/appkit-react/docs/components.md
  
  The root provider for AppKit. It must wrap your application.
  
- %%demo/examples/src/appkit/components/providers#APP_KIT_PROVIDER%%
+ %%docs/examples/src/appkit/components/providers#APP_KIT_PROVIDER%%
  
  ## Balances
 
@@ -20,13 +20,13 @@ target: packages/appkit-react/docs/components.md
 
 A specialized button for sending TON. Pre-configured for TON transfers.
 
-%%demo/examples/src/appkit/components/balances#SEND_TON_BUTTON%%
+%%docs/examples/src/appkit/components/balances#SEND_TON_BUTTON%%
 
 ### `SendJettonButton`
 
 A specialized button for sending Jettons. Handles jetton-specific logic.
 
-%%demo/examples/src/appkit/components/balances#SEND_JETTON_BUTTON%%
+%%docs/examples/src/appkit/components/balances#SEND_JETTON_BUTTON%%
 
 ## Transactions
 
@@ -34,7 +34,7 @@ A specialized button for sending Jettons. Handles jetton-specific logic.
 
 A drop-in component that handles the entire transaction flow.
 
-%%demo/examples/src/appkit/components/transaction#TRANSACTION%%
+%%docs/examples/src/appkit/components/transaction#TRANSACTION%%
 
 ## Wallets
 
@@ -42,7 +42,7 @@ A drop-in component that handles the entire transaction flow.
 
 A button that triggers the wallet connection flow.
 
-%%demo/examples/src/appkit/components/wallets#CONNECT_BUTTON%%
+%%docs/examples/src/appkit/components/wallets#CONNECT_BUTTON%%
 
 ## Staking
 
@@ -50,13 +50,13 @@ A button that triggers the wallet connection flow.
 
 A high-level component that provides a complete staking interface. It handles quote fetching, transaction building, and user interactions.
 
-%%demo/examples/src/appkit/staking#STAKING_WIDGET_DEFAULT%%
+%%docs/examples/src/appkit/staking#STAKING_WIDGET_DEFAULT%%
 
 #### Custom UI
 
 You can also use a render function to build a completely custom UI while keeping the staking logic.
 
-%%demo/examples/src/appkit/staking#STAKING_WIDGET_CUSTOM%%
+%%docs/examples/src/appkit/staking#STAKING_WIDGET_CUSTOM%%
 
 ## Swap
 
@@ -64,10 +64,10 @@ You can also use a render function to build a completely custom UI while keeping
 
 A high-level component that provides a complete swap interface. It handles token selection, quote fetching, and transaction building.
 
-%%demo/examples/src/appkit/swap#SWAP_WIDGET_DEFAULT%%
+%%docs/examples/src/appkit/swap#SWAP_WIDGET_DEFAULT%%
 
 #### Custom UI
 
 You can also use a render function to build a completely custom UI while keeping the swap logic.
 
-%%demo/examples/src/appkit/swap#SWAP_WIDGET_CUSTOM%%
+%%docs/examples/src/appkit/swap#SWAP_WIDGET_CUSTOM%%
diff --git a/template/packages/appkit-react/docs/hooks.md b/docs/templates/packages/appkit-react/docs/hooks.md
similarity index 61%
rename from template/packages/appkit-react/docs/hooks.md
rename to docs/templates/packages/appkit-react/docs/hooks.md
index 86cf2effb..7e2ab0fde 100644
--- a/template/packages/appkit-react/docs/hooks.md
+++ b/docs/templates/packages/appkit-react/docs/hooks.md
@@ -12,13 +12,13 @@ AppKit React provides a set of hooks to interact with the blockchain and wallets
  
  Hook to access the `AppKit` instance.
  
- %%demo/examples/src/appkit/hooks/core#USE_APP_KIT%%
+ %%docs/examples/src/appkit/hooks/core#USE_APP_KIT%%
  
  ### `useAppKitTheme`
  
  Hook to access and toggle the current theme.
  
- %%demo/examples/src/appkit/hooks/core#USE_APP_KIT_THEME%%
+ %%docs/examples/src/appkit/hooks/core#USE_APP_KIT_THEME%%
  
  ## Balances
 
@@ -26,25 +26,25 @@ AppKit React provides a set of hooks to interact with the blockchain and wallets
 
 Hook to get the TON balance of the currently selected wallet.
 
-%%demo/examples/src/appkit/hooks/balances#USE_BALANCE%%
+%%docs/examples/src/appkit/hooks/balances#USE_BALANCE%%
 
 ### `useBalanceByAddress`
 
 Hook to fetch the TON balance of a specific address.
 
-%%demo/examples/src/appkit/hooks/balances#USE_BALANCE_BY_ADDRESS%%
+%%docs/examples/src/appkit/hooks/balances#USE_BALANCE_BY_ADDRESS%%
 
 ### `useWatchBalance`
 
 Hook to enable real-time balance updates for the currently selected wallet. It automatically updates the TanStack Query cache.
 
-%%demo/examples/src/appkit/hooks/balances#USE_WATCH_BALANCE%%
+%%docs/examples/src/appkit/hooks/balances#USE_WATCH_BALANCE%%
 
 ### `useWatchBalanceByAddress`
 
 Hook to enable real-time balance updates for a specific address.
 
-%%demo/examples/src/appkit/hooks/balances#USE_WATCH_BALANCE_BY_ADDRESS%%
+%%docs/examples/src/appkit/hooks/balances#USE_WATCH_BALANCE_BY_ADDRESS%%
 
 ## Jettons
 
@@ -52,49 +52,49 @@ Hook to enable real-time balance updates for a specific address.
 
 Hook to get all jettons owned by the currently selected wallet.
 
-%%demo/examples/src/appkit/hooks/jettons#USE_JETTONS%%
+%%docs/examples/src/appkit/hooks/jettons#USE_JETTONS%%
 
 ### `useJettonsByAddress`
 
 Hook to get all jettons owned by a specific address.
 
-%%demo/examples/src/appkit/hooks/jettons#USE_JETTONS_BY_ADDRESS%%
+%%docs/examples/src/appkit/hooks/jettons#USE_JETTONS_BY_ADDRESS%%
 
 ### `useJettonBalanceByAddress`
 
 Hook to get the balance of a specific jetton for a wallet address.
 
-%%demo/examples/src/appkit/hooks/jettons#USE_JETTON_BALANCE_BY_ADDRESS%%
+%%docs/examples/src/appkit/hooks/jettons#USE_JETTON_BALANCE_BY_ADDRESS%%
 
 ### `useJettonInfo`
 
 Hook to get information about a specific jetton by its address.
 
-%%demo/examples/src/appkit/hooks/jettons#USE_JETTON_INFO%%
+%%docs/examples/src/appkit/hooks/jettons#USE_JETTON_INFO%%
 
 ### `useJettonWalletAddress`
 
 Hook to get the jetton wallet address for a specific jetton and owner address.
 
-%%demo/examples/src/appkit/hooks/jettons#USE_JETTON_WALLET_ADDRESS%%
+%%docs/examples/src/appkit/hooks/jettons#USE_JETTON_WALLET_ADDRESS%%
 
 ### `useTransferJetton`
 
 Hook to transfer jettons to a recipient address.
 
-%%demo/examples/src/appkit/hooks/jettons#USE_TRANSFER_JETTON%%
+%%docs/examples/src/appkit/hooks/jettons#USE_TRANSFER_JETTON%%
 
 ### `useWatchJettons`
 
 Hook to enable real-time jetton updates for the currently selected wallet.
 
-%%demo/examples/src/appkit/hooks/jettons#USE_WATCH_JETTONS%%
+%%docs/examples/src/appkit/hooks/jettons#USE_WATCH_JETTONS%%
 
 ### `useWatchJettonsByAddress`
 
 Hook to enable real-time jetton updates for a specific address.
 
-%%demo/examples/src/appkit/hooks/jettons#USE_WATCH_JETTONS_BY_ADDRESS%%
+%%docs/examples/src/appkit/hooks/jettons#USE_WATCH_JETTONS_BY_ADDRESS%%
 
 ## Network
 
@@ -102,25 +102,25 @@ Hook to enable real-time jetton updates for a specific address.
 
 Hook to get network of the selected wallet.
 
-%%demo/examples/src/appkit/hooks/network#USE_NETWORK%%
+%%docs/examples/src/appkit/hooks/network#USE_NETWORK%%
 
 ### `useNetworks`
 
 Hook to get all configured networks.
 
-%%demo/examples/src/appkit/hooks/network#USE_NETWORKS%%
+%%docs/examples/src/appkit/hooks/network#USE_NETWORKS%%
 
 ### `useBlockNumber`
 
 Hook to get the current masterchain block number.
 
-%%demo/examples/src/appkit/hooks/network#USE_BLOCK_NUMBER%%
+%%docs/examples/src/appkit/hooks/network#USE_BLOCK_NUMBER%%
 
 ### `useDefaultNetwork`
 
 Hook to get and set the default network for wallet connections. Returns a tuple `[defaultNetwork, setDefaultNetwork]`.
 
-%%demo/examples/src/appkit/hooks/network#USE_DEFAULT_NETWORK%%
+%%docs/examples/src/appkit/hooks/network#USE_DEFAULT_NETWORK%%
 
 ## NFT
 
@@ -128,25 +128,25 @@ Hook to get and set the default network for wallet connections. Returns a tuple
 
 Hook to get a single NFT.
 
-%%demo/examples/src/appkit/hooks/nft#USE_NFT%%
+%%docs/examples/src/appkit/hooks/nft#USE_NFT%%
 
 ### `useNfts`
 
 Hook to get NFTs of the selected wallet.
 
-%%demo/examples/src/appkit/hooks/nft#USE_NFTS%%
+%%docs/examples/src/appkit/hooks/nft#USE_NFTS%%
 
 ### `useNftsByAddress`
 
 Hook to get NFTs of a specific address.
 
-%%demo/examples/src/appkit/hooks/nft#USE_NFTS_BY_ADDRESS%%
+%%docs/examples/src/appkit/hooks/nft#USE_NFTS_BY_ADDRESS%%
 
 ### `useTransferNft`
 
 Hook to transfer NFT to another wallet.
 
-%%demo/examples/src/appkit/hooks/nft#USE_TRANSFER_NFT%%
+%%docs/examples/src/appkit/hooks/nft#USE_TRANSFER_NFT%%
 
 ## Signing
 
@@ -154,19 +154,19 @@ Hook to transfer NFT to another wallet.
 
 Hook to sign binary data with the connected wallet.
 
-%%demo/examples/src/appkit/hooks/signing#USE_SIGN_BINARY%%
+%%docs/examples/src/appkit/hooks/signing#USE_SIGN_BINARY%%
 
 ### `useSignCell`
 
 Hook to sign TON Cell data with the connected wallet.
 
-%%demo/examples/src/appkit/hooks/signing#USE_SIGN_CELL%%
+%%docs/examples/src/appkit/hooks/signing#USE_SIGN_CELL%%
 
 ### `useSignText`
 
 Hook to sign text messages with the connected wallet.
 
-%%demo/examples/src/appkit/hooks/signing#USE_SIGN_TEXT%%
+%%docs/examples/src/appkit/hooks/signing#USE_SIGN_TEXT%%
 
 ## Swap
 
@@ -174,25 +174,25 @@ Hook to sign text messages with the connected wallet.
 
 Hook to get a swap quote for a token pair.
 
-%%demo/examples/src/appkit/hooks/swap#USE_SWAP_QUOTE%%
+%%docs/examples/src/appkit/hooks/swap#USE_SWAP_QUOTE%%
 
 ### `useBuildSwapTransaction`
 
 Hook to build a transaction for a swap operation based on a quote.
 
-%%demo/examples/src/appkit/hooks/swap#USE_BUILD_SWAP_TRANSACTION%%
+%%docs/examples/src/appkit/hooks/swap#USE_BUILD_SWAP_TRANSACTION%%
 
 ### `useSwapProvider`
 
 Hook to read and change the currently selected swap provider. Returns a tuple `[provider, setProviderId]` — mirrors `useSelectedWallet`.
 
-%%demo/examples/src/appkit/hooks/swap#USE_SWAP_PROVIDER%%
+%%docs/examples/src/appkit/hooks/swap#USE_SWAP_PROVIDER%%
 
 ### `useSwapProviders`
 
 Hook to get all registered swap providers. The returned array keeps a stable reference until the provider list changes, so it is safe to use with `useSyncExternalStore`.
 
-%%demo/examples/src/appkit/hooks/swap#USE_SWAP_PROVIDERS%%
+%%docs/examples/src/appkit/hooks/swap#USE_SWAP_PROVIDERS%%
 
 ## Crypto Onramp
 
@@ -200,13 +200,13 @@ Hook to get all registered swap providers. The returned array keeps a stable ref
 
 Hook to get a registered crypto-onramp provider by id, or the default one when no id is given.
 
-%%demo/examples/src/appkit/hooks/onramp#USE_CRYPTO_ONRAMP_PROVIDER%%
+%%docs/examples/src/appkit/hooks/onramp#USE_CRYPTO_ONRAMP_PROVIDER%%
 
 ### `useCryptoOnrampProviders`
 
 Hook to get all registered crypto-onramp providers.
 
-%%demo/examples/src/appkit/hooks/onramp#USE_CRYPTO_ONRAMP_PROVIDERS%%
+%%docs/examples/src/appkit/hooks/onramp#USE_CRYPTO_ONRAMP_PROVIDERS%%
 
 ## Staking
 
@@ -214,43 +214,43 @@ Hook to get all registered crypto-onramp providers.
 
 Hook to get all registered staking providers. The returned array keeps a stable reference until the provider list changes.
 
-%%demo/examples/src/appkit/hooks/staking#USE_STAKING_PROVIDERS%%
+%%docs/examples/src/appkit/hooks/staking#USE_STAKING_PROVIDERS%%
 
 ### `useStakingProvider`
 
 Hook to get a specific staking provider by id (or the default when no id is passed).
 
-%%demo/examples/src/appkit/hooks/staking#USE_STAKING_PROVIDER%%
+%%docs/examples/src/appkit/hooks/staking#USE_STAKING_PROVIDER%%
 
 ### `useStakingQuote`
 
 Hook to get a quote for staking or unstaking a given amount.
 
-%%demo/examples/src/appkit/hooks/staking#USE_STAKING_QUOTE%%
+%%docs/examples/src/appkit/hooks/staking#USE_STAKING_QUOTE%%
 
 ### `useStakedBalance`
 
 Hook to get the user's currently staked balance.
 
-%%demo/examples/src/appkit/hooks/staking#USE_STAKED_BALANCE%%
+%%docs/examples/src/appkit/hooks/staking#USE_STAKED_BALANCE%%
 
 ### `useStakingProviderInfo`
 
 Hook to get live info about a staking provider (APY, limits, etc.).
 
-%%demo/examples/src/appkit/hooks/staking#USE_STAKING_PROVIDER_INFO%%
+%%docs/examples/src/appkit/hooks/staking#USE_STAKING_PROVIDER_INFO%%
 
 ### `useStakingProviderMetadata`
 
 Hook to get static metadata about a staking provider (name, receive token, etc.).
 
-%%demo/examples/src/appkit/hooks/staking#USE_STAKING_PROVIDER_METADATA%%
+%%docs/examples/src/appkit/hooks/staking#USE_STAKING_PROVIDER_METADATA%%
 
 ### `useBuildStakeTransaction`
 
 Hook to build a stake transaction from a previously fetched quote.
 
-%%demo/examples/src/appkit/hooks/staking#USE_BUILD_STAKE_TRANSACTION%%
+%%docs/examples/src/appkit/hooks/staking#USE_BUILD_STAKE_TRANSACTION%%
 
 ## Transaction
 
@@ -258,25 +258,25 @@ Hook to build a stake transaction from a previously fetched quote.
 
 Hook to send a transaction to the blockchain.
 
-%%demo/examples/src/appkit/hooks/transaction#USE_SEND_TRANSACTION%%
+%%docs/examples/src/appkit/hooks/transaction#USE_SEND_TRANSACTION%%
 
 ### `useTransferTon`
 
 Hook to simplify transferring TON to another address.
 
-%%demo/examples/src/appkit/hooks/transaction#USE_TRANSFER_TON%%
+%%docs/examples/src/appkit/hooks/transaction#USE_TRANSFER_TON%%
 
 ### `useWatchTransactions`
 
 Hook to watch for new transactions for the currently selected wallet in real-time.
 
-%%demo/examples/src/appkit/hooks/transaction#USE_WATCH_TRANSACTIONS%%
+%%docs/examples/src/appkit/hooks/transaction#USE_WATCH_TRANSACTIONS%%
 
 ### `useWatchTransactionsByAddress`
 
 Hook to watch for new transactions for a specific address in real-time.
 
-%%demo/examples/src/appkit/hooks/transaction#USE_WATCH_TRANSACTIONS_BY_ADDRESS%%
+%%docs/examples/src/appkit/hooks/transaction#USE_WATCH_TRANSACTIONS_BY_ADDRESS%%
 
 ## Wallets
 
@@ -284,42 +284,42 @@ Hook to watch for new transactions for a specific address in real-time.
 
 Hook to get current wallet address.
 
-%%demo/examples/src/appkit/hooks/wallets#USE_ADDRESS%%
+%%docs/examples/src/appkit/hooks/wallets#USE_ADDRESS%%
 
 ### `useConnect`
 
 Hook to connect a wallet.
 
-%%demo/examples/src/appkit/hooks/wallets#USE_CONNECT%%
+%%docs/examples/src/appkit/hooks/wallets#USE_CONNECT%%
 
 ### `useConnectedWallets`
 
 Hook to get all connected wallets.
 
-%%demo/examples/src/appkit/hooks/wallets#USE_CONNECTED_WALLETS%%
+%%docs/examples/src/appkit/hooks/wallets#USE_CONNECTED_WALLETS%%
 
 ### `useConnectorById`
 
 Hook to get a connector by its ID.
 
-%%demo/examples/src/appkit/hooks/wallets#USE_CONNECTOR_BY_ID%%
+%%docs/examples/src/appkit/hooks/wallets#USE_CONNECTOR_BY_ID%%
 
 ### `useConnectors`
 
 Hook to get all available connectors.
 
-%%demo/examples/src/appkit/hooks/wallets#USE_CONNECTORS%%
+%%docs/examples/src/appkit/hooks/wallets#USE_CONNECTORS%%
 
 ### `useDisconnect`
 
 Hook to disconnect a wallet.
 
-%%demo/examples/src/appkit/hooks/wallets#USE_DISCONNECT%%
+%%docs/examples/src/appkit/hooks/wallets#USE_DISCONNECT%%
 
 ### `useSelectedWallet`
 
 Hook to get and set the currently selected wallet.
 
-%%demo/examples/src/appkit/hooks/wallets#USE_SELECTED_WALLET%%
+%%docs/examples/src/appkit/hooks/wallets#USE_SELECTED_WALLET%%
 
 
diff --git a/docs/templates/packages/appkit-react/docs/reference.md b/docs/templates/packages/appkit-react/docs/reference.md
new file mode 100644
index 000000000..7e799a74c
--- /dev/null
+++ b/docs/templates/packages/appkit-react/docs/reference.md
@@ -0,0 +1,3226 @@
+---
+target: packages/appkit-react/docs/reference.md
+---
+
+## Hook
+
+### Balances
+
+#### useBalance
+
+React hook reading the Toncoin balance of the currently selected wallet through TanStack Query — auto-resolves the wallet address (use [`useBalanceByAddress`](#usebalancebyaddress) for an arbitrary address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseBalanceParameters`](#usebalanceparameters) | TanStack Query overrides (`select`, `enabled`, `staleTime`, …) and an optional network override. |
+
+Returns: <code><a href="#usebalancereturntype">UseBalanceReturnType</a>&lt;selectData = GetBalanceByAddressData&gt;</code> — TanStack Query result for the balance read.
+
+**Example**
+
+%%docs/examples/src/appkit/hooks/balances#USE_BALANCE%%
+
+#### useBalanceByAddress
+
+React hook reading the Toncoin balance of an arbitrary address through TanStack Query — useful for addresses that aren't tied to the selected wallet (use [`useBalance`](#usebalance) for the selected wallet).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseBalanceByAddressParameters`](#usebalancebyaddressparameters) | Target address, optional network override, and TanStack Query overrides. |
+
+Returns: <code><a href="#usebalancebyaddressreturntype">UseBalanceByAddressReturnType</a>&lt;selectData = GetBalanceByAddressData&gt;</code> — TanStack Query result for the balance read.
+
+**Example**
+
+%%docs/examples/src/appkit/hooks/balances#USE_BALANCE_BY_ADDRESS%%
+
+#### useWatchBalance
+
+Subscribe to Toncoin balance updates for the currently selected wallet; updates flow into the TanStack Query cache so [`useBalance`](#usebalance) re-renders automatically (use [`useWatchBalanceByAddress`](#usewatchbalancebyaddress) for a fixed address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseWatchBalanceParameters`](#usewatchbalanceparameters) | Update callback and optional network override. |
+
+Returns: `void`.
+
+**Example**
+
+%%docs/examples/src/appkit/hooks/balances#USE_WATCH_BALANCE%%
+
+#### useWatchBalanceByAddress
+
+Subscribe to Toncoin balance updates for an arbitrary address — updates flow into the TanStack Query cache so [`useBalanceByAddress`](#usebalancebyaddress) re-renders automatically. No-ops with a console warning when no streaming provider is configured for the resolved network.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters`\* | [`UseWatchBalanceByAddressParameters`](#usewatchbalancebyaddressparameters) | Address, update callback and optional network override. |
+
+Returns: `void`.
+
+**Example**
+
+%%docs/examples/src/appkit/hooks/balances#USE_WATCH_BALANCE_BY_ADDRESS%%
+
+### Connectors
+
+#### useConnectorById
+
+Read a connector by id (wraps [`getConnectorById`](/ecosystem/appkit/reference/appkit#getconnectorbyid) + [`watchConnectorById`](/ecosystem/appkit/reference/appkit#watchconnectorbyid)); re-renders when the connector with that id is registered or unregistered (use [`useConnectedWallets`](#useconnectedwallets) to react to wallet connect/disconnect events).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `id`\* | `string` | ID of the connector to look up. |
+
+Returns: <code><a href="/ecosystem/appkit/reference/appkit#connector">Connector</a> \| undefined</code> — The matching [`Connector`](/ecosystem/appkit/reference/appkit#connector), or `undefined` if none with that id is registered.
+
+#### useConnectors
+
+Read the list of connectors registered on this AppKit instance; re-renders when a connector is registered or unregistered (use [`useConnectedWallets`](#useconnectedwallets) to react to wallet connect/disconnect events).
+
+Returns: <code><a href="#useconnectorsreturntype">UseConnectorsReturnType</a></code> — Read-only array of registered [`Connector`](/ecosystem/appkit/reference/appkit#connector)s.
+
+### Crypto Onramp
+
+#### useCreateCryptoOnrampDeposit
+
+React mutation hook that creates a crypto-onramp deposit from a quote previously obtained via [`useCryptoOnrampQuote`](#usecryptoonrampquote) (wraps [`createCryptoOnrampDeposit`](/ecosystem/appkit/reference/appkit#createcryptoonrampdeposit)) — the resolved [`CryptoOnrampDeposit`](/ecosystem/appkit/reference/appkit#cryptoonrampdeposit) carries the address and amount the user must send on the source chain.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseCreateCryptoOnrampDepositParameters`](#usecreatecryptoonrampdepositparameters) | TanStack Query mutation overrides (`parameters.mutation`). |
+
+Returns: <code><a href="#usecreatecryptoonrampdepositreturntype">UseCreateCryptoOnrampDepositReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the deposit call.
+
+#### useCryptoOnrampContext
+
+Reads the `CryptoOnrampContext` populated by [`CryptoOnrampWidgetProvider`](#cryptoonrampwidgetprovider) — returns the widget's selection state, quote/deposit data and actions ([`CryptoOnrampContextType`](#cryptoonrampcontexttype)).
+
+Returns: <code><a href="#cryptoonrampcontexttype">CryptoOnrampContextType</a></code>.
+
+#### useCryptoOnrampProvider
+
+Read a registered crypto-onramp provider by id, or the default provider when no id is given — subscribes to [`watchCryptoOnrampProviders`](/ecosystem/appkit/reference/appkit#watchcryptoonrampproviders) and re-reads via [`getCryptoOnrampProvider`](/ecosystem/appkit/reference/appkit#getcryptoonrampprovider) so the result stays in sync. The read swallows the throw from [`getCryptoOnrampProvider`](/ecosystem/appkit/reference/appkit#getcryptoonrampprovider) (which throws when no provider matches — or when no id is passed and no default has been registered) and yields `undefined` instead.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | [`GetCryptoOnrampProviderOptions`](/ecosystem/appkit/reference/appkit#getcryptoonrampprovideroptions) | Optional provider id. |
+
+Returns: <code><a href="#usecryptoonrampproviderreturntype">UseCryptoOnrampProviderReturnType</a></code> — The matching provider, or `undefined` when none is registered.
+
+#### useCryptoOnrampProviders
+
+List every crypto-onramp provider registered on the AppKit instance (both those passed via [`AppKitConfig`](/ecosystem/appkit/reference/appkit#appkitconfig)'s `providers` and those added later through [`registerProvider`](/ecosystem/appkit/reference/appkit#registerprovider)); subscribes to [`watchCryptoOnrampProviders`](/ecosystem/appkit/reference/appkit#watchcryptoonrampproviders) and re-reads via [`getCryptoOnrampProviders`](/ecosystem/appkit/reference/appkit#getcryptoonrampproviders) so the array stays in sync.
+
+Returns: <code><a href="#usecryptoonrampprovidersreturntype">UseCryptoOnrampProvidersReturnType</a></code> — Array of registered crypto-onramp providers.
+
+#### useCryptoOnrampQuote
+
+React hook quoting a crypto-to-TON onramp through TanStack Query (wraps [`getCryptoOnrampQuote`](/ecosystem/appkit/reference/appkit#getcryptoonrampquote)) — returns the rate, expected amount and provider metadata needed to call [`useCreateCryptoOnrampDeposit`](#usecreatecryptoonrampdeposit).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseCryptoOnrampQuoteParameters`](#usecryptoonrampquoteparameters) | Quote inputs and TanStack Query overrides. |
+
+Returns: <code><a href="#usecryptoonrampquotereturntype">UseCryptoOnrampQuoteReturnType</a>&lt;selectData = GetCryptoOnrampQuoteData&gt;</code> — TanStack Query result for the quote read.
+
+#### useCryptoOnrampStatus
+
+React hook reading the current status of a crypto-onramp deposit previously created via [`useCreateCryptoOnrampDeposit`](#usecreatecryptoonrampdeposit) through TanStack Query (wraps [`getCryptoOnrampStatus`](/ecosystem/appkit/reference/appkit#getcryptoonrampstatus)) — typically polled via `refetchInterval` until the status is `'success'` or `'failed'`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseCryptoOnrampStatusParameters`](#usecryptoonrampstatusparameters) | Deposit id, originating provider id and TanStack Query overrides. |
+
+Returns: <code><a href="#usecryptoonrampstatusreturntype">UseCryptoOnrampStatusReturnType</a>&lt;selectData = GetCryptoOnrampStatusData&gt;</code> — TanStack Query result for the status read.
+
+### Jettons
+
+#### 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. |
+
+Returns: <code><a href="#usejettonbalancebyaddressreturntype">UseJettonBalanceByAddressReturnType</a>&lt;selectData = GetJettonBalanceByAddressData&gt;</code> — TanStack Query result for the jetton balance read.
+
+**Example**
+
+%%docs/examples/src/appkit/hooks/jettons#USE_JETTON_BALANCE_BY_ADDRESS%%
+
+#### useJettonInfo
+
+React hook reading jetton-master metadata (name, symbol, decimals, image, description) through TanStack Query.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseJettonInfoParameters`](#usejettoninfoparameters) | Jetton master address, optional network override and TanStack Query overrides. |
+
+Returns: <code><a href="#usejettoninforeturntype">UseJettonInfoReturnType</a>&lt;selectData = GetJettonInfoData&gt;</code> — TanStack Query result for the jetton info read.
+
+**Example**
+
+%%docs/examples/src/appkit/hooks/jettons#USE_JETTON_INFO%%
+
+#### useJettonWalletAddress
+
+React hook deriving the owner's jetton-wallet address — the per-owner contract that actually holds the jetton balance for a given master — through TanStack Query.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseJettonWalletAddressParameters`](#usejettonwalletaddressparameters) | Jetton master, owner address, optional network override and TanStack Query overrides. |
+
+Returns: `UseQueryReturnType<selectData, Error>` — TanStack Query result for the jetton-wallet address read.
+
+**Example**
+
+%%docs/examples/src/appkit/hooks/jettons#USE_JETTON_WALLET_ADDRESS%%
+
+#### useJettons
+
+React hook listing jettons held by the currently selected wallet through TanStack Query — auto-resolves the wallet address (use [`useJettonsByAddress`](#usejettonsbyaddress) for an arbitrary address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseJettonsParameters`](#usejettonsparameters) | TanStack Query overrides (`select`, `enabled`, `staleTime`, …), pagination and an optional network override. |
+
+Returns: <code><a href="#usejettonsreturntype">UseJettonsReturnType</a>&lt;selectData = GetJettonsByAddressData&gt;</code> — TanStack Query result for the jettons list.
+
+**Example**
+
+%%docs/examples/src/appkit/hooks/jettons#USE_JETTONS%%
+
+#### useJettonsByAddress
+
+React hook listing jettons held by an arbitrary address through TanStack Query — useful for wallets that aren't selected in AppKit (use [`useJettons`](#usejettons) for the selected wallet).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseJettonsByAddressParameters`](#usejettonsbyaddressparameters) | Owner address, optional network override, pagination and TanStack Query overrides. |
+
+Returns: <code><a href="#usejettonsbyaddressreturntype">UseJettonsByAddressReturnType</a>&lt;selectData = GetJettonsByAddressData&gt;</code> — TanStack Query result for the jettons list.
+
+**Example**
+
+%%docs/examples/src/appkit/hooks/jettons#USE_JETTONS_BY_ADDRESS%%
+
+#### useTransferJetton
+
+React mutation hook that builds and sends a jetton transfer from the selected wallet in one step (wraps [`transferJetton`](/ecosystem/appkit/reference/appkit#transferjetton)); returns `mutate(\{ jettonAddress, recipientAddress, amount, jettonDecimals, comment? \})`. Throws `Error('Wallet not connected')` if no wallet is currently selected.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseTransferJettonParameters`](#usetransferjettonparameters) | TanStack Query mutation overrides. |
+
+Returns: <code><a href="#usetransferjettonreturntype">UseTransferJettonReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the jetton transfer call.
+
+**Example**
+
+%%docs/examples/src/appkit/hooks/jettons#USE_TRANSFER_JETTON%%
+
+#### useWatchJettons
+
+Subscribe to jetton-balance updates for the currently selected wallet; updates flow into the TanStack Query cache so [`useJettons`](#usejettons) re-renders automatically (use [`useWatchJettonsByAddress`](#usewatchjettonsbyaddress) for a fixed address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseWatchJettonsParameters`](#usewatchjettonsparameters) | Update callback and optional network override. |
+
+Returns: `void`.
+
+**Example**
+
+%%docs/examples/src/appkit/hooks/jettons#USE_WATCH_JETTONS%%
+
+#### useWatchJettonsByAddress
+
+Subscribe to jetton-balance updates for an arbitrary owner address; updates flow into the TanStack Query cache so [`useJettonsByAddress`](#usejettonsbyaddress) and [`useJettonBalanceByAddress`](#usejettonbalancebyaddress) re-render automatically. Logs a warning and exits when no streaming provider is configured for the resolved network.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters`\* | [`UseWatchJettonsByAddressParameters`](#usewatchjettonsbyaddressparameters) | Owner address, update callback and optional network override. |
+
+Returns: `void`.
+
+**Example**
+
+%%docs/examples/src/appkit/hooks/jettons#USE_WATCH_JETTONS_BY_ADDRESS%%
+
+### NFTs
+
+#### useNft
+
+React hook reading metadata and ownership for a single NFT through TanStack Query, keyed by its contract address; `data` is `null` when the indexer has no record.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseNftParameters`](#usenftparameters) | NFT address, optional network override, and TanStack Query overrides. |
+
+Returns: <code><a href="#usenftreturntype">UseNftReturnType</a>&lt;selectData = GetNftData&gt;</code> — TanStack Query result for the NFT read.
+
+**Example**
+
+%%docs/examples/src/appkit/hooks/nft#USE_NFT%%
+
+#### useNfts
+
+React hook that reads NFTs held by the currently selected wallet through TanStack Query — auto-resolves the wallet address (use [`useNftsByAddress`](#usenftsbyaddress) for an arbitrary address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseNFTsParameters`](#usenftsparameters) | Optional pagination, network override, and TanStack Query overrides. |
+
+Returns: <code><a href="#usenftsreturntype">UseNFTsReturnType</a>&lt;selectData = GetNFTsData&gt;</code> — TanStack Query result for the NFTs read.
+
+**Example**
+
+%%docs/examples/src/appkit/hooks/nft#USE_NFTS%%
+
+#### useNftsByAddress
+
+React hook that reads NFTs held by an arbitrary address through TanStack Query — useful for wallets that aren't selected in AppKit (use [`useNfts`](#usenfts) for the selected wallet).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseNFTsByAddressParameters`](#usenftsbyaddressparameters) | Owner address, optional pagination and network override, plus TanStack Query overrides. |
+
+Returns: <code><a href="#usenftsbyaddressreturntype">UseNFTsByAddressReturnType</a>&lt;selectData = GetNFTsData&gt;</code> — TanStack Query result for the NFTs read.
+
+**Example**
+
+%%docs/examples/src/appkit/hooks/nft#USE_NFTS_BY_ADDRESS%%
+
+#### useTransferNft
+
+React mutation hook that builds and sends an NFT transfer from the selected wallet in one step (wraps [`transferNft`](/ecosystem/appkit/reference/appkit#transfernft)); returns `mutate(\{ nftAddress, recipientAddress, amount?, comment? \})` and throws `Error('Wallet not connected')` if no wallet is currently selected.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseTransferNftParameters`](#usetransfernftparameters) | TanStack Query mutation overrides. |
+
+Returns: <code><a href="#usetransfernftreturntype">UseTransferNftReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the transfer call.
+
+**Example**
+
+%%docs/examples/src/appkit/hooks/nft#USE_TRANSFER_NFT%%
+
+### Networks
+
+#### useBlockNumber
+
+React hook reading the latest masterchain seqno through TanStack Query — useful for freshness checks and pagination cursors.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseBlockNumberParameters`](#useblocknumberparameters) | TanStack Query overrides and optional network. |
+
+Returns: <code><a href="#useblocknumberreturntype">UseBlockNumberReturnType</a>&lt;selectData = GetBlockNumberData&gt;</code> — TanStack Query result for the seqno read.
+
+#### useDefaultNetwork
+
+Read and write AppKit's default network — the network connectors use for new wallet connections. Returns a `useState`-style tuple; the read side re-renders when the default changes through any source (this hook, [`setDefaultNetwork`](/ecosystem/appkit/reference/appkit#setdefaultnetwork), manager events).
+
+Returns: <code><a href="#usedefaultnetworkreturntype">UseDefaultNetworkReturnType</a></code> — Tuple `[network, setNetwork]`.
+
+#### useNetwork
+
+Read the [`Network`](/ecosystem/appkit/reference/appkit#network) the selected wallet is connected to; re-renders when the wallet's network changes (e.g. user switches mainnet/testnet inside the wallet).
+
+Returns: <code><a href="#usenetworkreturntype">UseNetworkReturnType</a></code> — Selected wallet's network, or `undefined` when no wallet is selected.
+
+#### useNetworks
+
+Read the list of networks configured on AppKit; re-renders when [`AppKitNetworkManager`](/ecosystem/appkit/reference/appkit#appkitnetworkmanager) adds, replaces or drops a network.
+
+Returns: <code><a href="#usenetworksreturntype">UseNetworksReturnType</a></code> — Array of configured [`Network`](/ecosystem/appkit/reference/appkit#network)s.
+
+### Settings
+
+#### useAppKit
+
+Read the [`AppKit`](/ecosystem/appkit/reference/appkit#appkit) instance hosted by [`AppKitProvider`](#appkitprovider); throws when the hook is rendered outside the provider tree.
+
+Returns: <code><a href="/ecosystem/appkit/reference/appkit#appkit">AppKit</a></code> — The AppKit instance shared with descendant hooks/components.
+
+#### useAppKitTheme
+
+State hook that mirrors the active appkit-react theme to `document.body[data-ta-theme]` — returns a `[theme, setTheme]` tuple just like `useState`.
+
+Returns: `readonly [string, Dispatch<SetStateAction<string>>]` — Tuple `[theme, setTheme]` for reading and switching the active theme.
+
+#### useI18n
+
+Read the i18n context published by [`I18nProvider`](#i18nprovider) (or the wrapping [`AppKitProvider`](#appkitprovider)); returns the active locale, translation function and helpers to switch locales or merge dictionaries. Throws when rendered outside the provider tree.
+
+Returns: `I18nContextType` — The i18n context ([`I18nContextType`](#i18ncontexttype)) with `activeLocale`, `t`, `locale` and `addDict`.
+
+### Signing
+
+#### useSignBinary
+
+React mutation hook that asks the selected wallet to sign a binary blob (wraps [`signBinary`](/ecosystem/appkit/reference/appkit#signbinary)); returns `mutate(\{ bytes \})` you call from event handlers. The underlying action 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. |
+
+Returns: <code><a href="#usesignbinaryreturntype">UseSignBinaryReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the signing call.
+
+#### useSignCell
+
+React mutation hook that asks the selected wallet to sign a TON cell (wraps [`signCell`](/ecosystem/appkit/reference/appkit#signcell)); typically used so the signature can later be verified on-chain. Returns `mutate(\{ cell, schema \})` you call from event handlers. The underlying action 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. |
+
+Returns: <code><a href="#usesigncellreturntype">UseSignCellReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the signing call.
+
+#### useSignText
+
+React mutation hook that asks the selected wallet to sign a plain-text message (wraps [`signText`](/ecosystem/appkit/reference/appkit#signtext)); returns `mutate(\{ text \})` you call from event handlers. The underlying action 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. |
+
+Returns: <code><a href="#usesigntextreturntype">UseSignTextReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the signing call.
+
+### Staking
+
+#### useBuildStakeTransaction
+
+React mutation hook that wraps [`buildStakeTransaction`](/ecosystem/appkit/reference/appkit#buildstaketransaction) — turns a [`StakingQuote`](/ecosystem/appkit/reference/appkit#stakingquote) obtained via [`useStakingQuote`](#usestakingquote) into a [`TransactionRequest`](/ecosystem/appkit/reference/appkit#transactionrequest) without sending it, so the UI can inspect or batch before signing. Returns `mutate(params)` where `params` matches [`BuildStakeTransactionOptions`](/ecosystem/appkit/reference/appkit#buildstaketransactionoptions).
+
+Returns: <code><a href="#usebuildstaketransactionreturntype">UseBuildStakeTransactionReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the build call.
+
+#### 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. |
+
+Returns: <code><a href="#usestakedbalancereturntype">UseStakedBalanceReturnType</a>&lt;selectData = GetStakedBalanceData&gt;</code> — TanStack Query result for the staked-balance read.
+
+#### 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: <code><a href="#stakingcontexttype">StakingContextType</a></code>.
+
+#### useStakingProvider
+
+React hook returning a registered staking provider; subscribes to provider-registry changes via [`watchStakingProviders`](/ecosystem/appkit/reference/appkit#watchstakingproviders) 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`](/ecosystem/appkit/reference/appkit#getstakingprovider) action would throw).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | <code><a href="/ecosystem/appkit/reference/appkit#getstakingprovideroptions">GetStakingProviderOptions</a></code> | Optional provider `id`. |
+
+Returns: <code><a href="#usestakingproviderreturntype">UseStakingProviderReturnType</a></code> — Matching staking provider instance, or `undefined` when none resolves.
+
+#### 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. |
+
+Returns: <code><a href="#usestakingproviderinforeturntype">UseStakingProviderInfoReturnType</a>&lt;selectData = GetStakingProviderInfoData&gt;</code> — TanStack Query result for the live provider info.
+
+#### useStakingProviderMetadata
+
+React hook reading static metadata for a staking provider (wraps [`getStakingProviderMetadata`](/ecosystem/appkit/reference/appkit#getstakingprovidermetadata)) — 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. |
+
+Returns: <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> — Static [`StakingProviderMetadata`](/ecosystem/appkit/reference/appkit#stakingprovidermetadata), or `undefined` when the provider can't be resolved.
+
+#### 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`](/ecosystem/appkit/reference/appkit#watchstakingproviders).
+
+Returns: <code><a href="#usestakingprovidersreturntype">UseStakingProvidersReturnType</a></code> — Array of registered staking providers.
+
+#### useStakingQuote
+
+React hook quoting a stake or unstake through TanStack Query (wraps [`getStakingQuote`](/ecosystem/appkit/reference/appkit#getstakingquote)) — returns the rate, expected output and provider metadata needed to feed into [`useBuildStakeTransaction`](#usebuildstaketransaction). 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. |
+
+Returns: <code><a href="#usestakingquotereturntype">UseStakingQuoteReturnType</a>&lt;selectData = GetStakingQuoteData&gt;</code> — TanStack Query result for the quote read.
+
+### Swap
+
+#### useBuildSwapTransaction
+
+React mutation hook that wraps [`buildSwapTransaction`](/ecosystem/appkit/reference/appkit#buildswaptransaction) — turns a [`SwapQuote`](/ecosystem/appkit/reference/appkit#swapquote) obtained via [`useSwapQuote`](#useswapquote) into a [`TransactionRequest`](/ecosystem/appkit/reference/appkit#transactionrequest) without sending it, so the UI can inspect or batch before signing. Returns `mutate(params)` where `params` matches [`BuildSwapTransactionOptions`](/ecosystem/appkit/reference/appkit#buildswaptransactionoptions).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseBuildSwapTransactionParameters`](#usebuildswaptransactionparameters) | TanStack Query mutation overrides. |
+
+Returns: <code><a href="#usebuildswaptransactionreturntype">UseBuildSwapTransactionReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the build call.
+
+#### 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: <code><a href="#swapcontexttype">SwapContextType</a></code>.
+
+#### useSwapProvider
+
+Read and switch the default swap provider — subscribes to [`watchSwapProviders`](/ecosystem/appkit/reference/appkit#watchswapproviders) and re-reads via [`getSwapProvider`](/ecosystem/appkit/reference/appkit#getswapprovider). Returns a `useState`-style tuple; the read swallows the throw from [`getSwapProvider`](/ecosystem/appkit/reference/appkit#getswapprovider) (which throws when no provider matches — or when no id is passed and no default has been registered) and yields `undefined` instead.
+
+Returns: <code><a href="#useswapproviderreturntype">UseSwapProviderReturnType</a></code> — Tuple `[provider, setProviderId]`.
+
+#### useSwapProviders
+
+List every swap provider registered on the AppKit instance (both those passed via [`AppKitConfig`](/ecosystem/appkit/reference/appkit#appkitconfig)'s `providers` and those added later through [`registerProvider`](/ecosystem/appkit/reference/appkit#registerprovider)); subscribes to [`watchSwapProviders`](/ecosystem/appkit/reference/appkit#watchswapproviders) and re-reads via [`getSwapProviders`](/ecosystem/appkit/reference/appkit#getswapproviders) so the array stays in sync.
+
+Returns: <code><a href="#useswapprovidersreturntype">UseSwapProvidersReturnType</a></code> — Array of registered swap providers.
+
+#### useSwapQuote
+
+React hook fetching a swap quote through TanStack Query — wraps [`getSwapQuote`](/ecosystem/appkit/reference/appkit#getswapquote). The resulting `data` is the [`SwapQuote`](/ecosystem/appkit/reference/appkit#swapquote) payload required to call [`buildSwapTransaction`](/ecosystem/appkit/reference/appkit#buildswaptransaction) (see [`useBuildSwapTransaction`](#usebuildswaptransaction)). 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. |
+
+Returns: <code><a href="#useswapquotereturntype">UseSwapQuoteReturnType</a>&lt;selectData = GetSwapQuoteData&gt;</code> — TanStack Query result for the swap quote.
+
+### Transactions
+
+#### useSendTransaction
+
+React mutation hook that hands a pre-built [`TransactionRequest`](/ecosystem/appkit/reference/appkit#transactionrequest) to the selected wallet for signing and broadcast (wraps [`sendTransaction`](/ecosystem/appkit/reference/appkit#sendtransaction)); returns `mutate(request)`. The underlying action 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. |
+
+Returns: <code><a href="#usesendtransactionreturntype">UseSendTransactionReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the send call.
+
+#### useTransactionStatus
+
+React hook that reads the trace status of a sent transaction (wraps [`getTransactionStatus`](/ecosystem/appkit/reference/appkit#gettransactionstatus)); typically paired with `refetchInterval` to poll until the trace completes. The underlying action throws `Error('Either boc or normalizedHash must be provided')` when neither field 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: <code><a href="#usetransactionstatusreturntype">UseTransactionStatusReturnType</a>&lt;selectData = GetTransactionStatusData&gt;</code> — TanStack Query result for the status read.
+
+#### useTransferTon
+
+React mutation hook that builds and sends a TON transfer from the selected wallet in one step (wraps [`transferTon`](/ecosystem/appkit/reference/appkit#transferton)); returns `mutate(\{ recipientAddress, amount, comment?, payload?, stateInit? \})`. The underlying action 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. |
+
+Returns: <code><a href="#usetransfertonreturntype">UseTransferTonReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the transfer call.
+
+#### 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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseWatchTransactionsParameters`](#usewatchtransactionsparameters) | Update callback. |
+
+Returns: `void`.
+
+**Example**
+
+%%docs/examples/src/appkit/hooks/transaction#USE_WATCH_TRANSACTIONS%%
+
+#### useWatchTransactionsByAddress
+
+Subscribe to incoming-transaction events for an arbitrary address (use [`useWatchTransactions`](#usewatchtransactions) for the selected wallet); logs a warning and exits when no streaming provider is configured for the resolved network or no `onChange` callback was provided.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters`\* | [`UseWatchTransactionsByAddressParameters`](#usewatchtransactionsbyaddressparameters) | Address, update callback and optional network override. |
+
+Returns: `void`.
+
+**Example**
+
+%%docs/examples/src/appkit/hooks/transaction#USE_WATCH_TRANSACTIONS_BY_ADDRESS%%
+
+### Wallets
+
+#### useAddress
+
+Read the user-friendly address of the currently selected wallet; re-renders when the selection changes.
+
+Returns: <code><a href="#useaddressreturntype">UseAddressReturnType</a></code> — Selected wallet's address, or `undefined` when none is selected.
+
+#### useConnect
+
+React mutation hook that triggers the connection flow on a registered connector by id (wraps [`connect`](/ecosystem/appkit/reference/appkit#connect)); returns `mutate(\{ connectorId \})` you call from event handlers. The underlying action throws `Error('Connector with id "<id>" not found')` when no connector with that id is registered — TanStack Query surfaces it via the mutation's `error`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseConnectParameters`](#useconnectparameters) | TanStack Query mutation overrides. |
+
+Returns: <code><a href="#useconnectreturntype">UseConnectReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the connect call.
+
+#### useConnectedWallets
+
+Read the list of currently connected wallets across all registered connectors; re-renders when a wallet connects or disconnects.
+
+Returns: <code><a href="#useconnectedwalletsreturntype">UseConnectedWalletsReturnType</a></code> — Read-only array of [`WalletInterface`](/ecosystem/appkit/reference/appkit#walletinterface)s.
+
+#### useDisconnect
+
+React mutation hook that disconnects the wallet currently connected through a registered connector (wraps [`disconnect`](/ecosystem/appkit/reference/appkit#disconnect)); returns `mutate(\{ connectorId \})` you call from event handlers. The underlying action throws `Error('Connector with id "<id>" not found')` when no connector with that id is registered — TanStack Query surfaces it via the mutation's `error`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseDisconnectParameters`](#usedisconnectparameters) | TanStack Query mutation overrides. |
+
+Returns: <code><a href="#usedisconnectreturntype">UseDisconnectReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the disconnect call.
+
+#### 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: <code><a href="#useselectedwalletreturntype">UseSelectedWalletReturnType</a></code> — Tuple `[wallet, setWalletId]`.
+
+## Component
+
+### Balances
+
+#### BalanceBadge
+
+Compound component for rendering a token balance pill (icon + amount + symbol). Sub-components forward extra props to the underlying DOM element so callers can layer custom classes, click handlers, etc.
+
+Compound component. Members:
+
+##### BalanceBadge.Container
+
+Pill wrapper — renders a horizontal [`Block`](#block) that hosts the icon and balance block.
+
+##### BalanceBadge.Icon
+
+Token icon — re-exported [`Logo`](#logo) that draws the asset's image.
+
+##### BalanceBadge.BalanceBlock
+
+Block holding the balance amount and ticker symbol side by side.
+
+##### BalanceBadge.Symbol
+
+Ticker symbol cell rendered next to the amount (e.g., `TON`, `USDT`).
+
+##### BalanceBadge.Balance
+
+Formatted balance number; takes a raw `balance` and `decimals` and renders the human-readable amount.
+
+#### SendJettonButton
+
+Pre-wired button that builds a jetton transfer with [`createTransferJettonTransaction`](/ecosystem/appkit/reference/appkit#createtransferjettontransaction) and dispatches it through the standard `Send` flow on click — disabled until `recipientAddress`, `amount`, `jetton.address` and a non-zero `jetton.decimals` are all set; throws inside the click handler when `jetton.address` is missing or `jetton.decimals` is falsy. (A `0`-decimal jetton must be passed as a truthy value to avoid being treated as 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` | Custom button text |
+| `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 |
+| `onError` | `(error: Error) => void` | Callback when an error occurs |
+| `onSuccess` | <code>(response: <a href="/ecosystem/appkit/reference/appkit#sendtransactionreturntype">SendTransactionReturnType</a>) =&gt; void</code> | Callback when the transaction is successful |
+
+#### SendTonButton
+
+Pre-wired button that builds a TON transfer with [`createTransferTonTransaction`](/ecosystem/appkit/reference/appkit#createtransfertontransaction) and dispatches it through the standard `Send` flow on click — disabled until both `recipientAddress` and `amount` are set.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `recipientAddress`\* | `string` | Recipient address. |
+| `amount`\* | `string` | Amount in TON as a human-readable decimal string (e.g., `"1.5"`); converted to nano-TON internally. |
+| `comment` | `string` | Optional human-readable comment attached to the transfer. |
+| `text` | `ReactNode` | Custom button text |
+| `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 |
+| `onError` | `(error: Error) => void` | Callback when an error occurs |
+| `onSuccess` | <code>(response: <a href="/ecosystem/appkit/reference/appkit#sendtransactionreturntype">SendTransactionReturnType</a>) =&gt; void</code> | Callback when the transaction is successful |
+
+### Crypto Onramp
+
+#### CryptoOnrampWidget
+
+Drop-in widget for buying TON-side tokens with a crypto payment from another chain — wraps [`CryptoOnrampWidgetProvider`](#cryptoonrampwidgetprovider) (which drives token/method selection, quote fetching, deposit creation and status polling) around [`CryptoOnrampWidgetUI`](#cryptoonrampwidgetui). Pass a `children` render function to swap in a fully custom UI while keeping the same provider state.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `children` | <code>(props: <a href="#cryptoonrampwidgetrenderprops">CryptoOnrampWidgetRenderProps</a>) =&gt; ReactNode</code> | Custom render function. When provided, replaces the default [`CryptoOnrampWidgetUI`](#cryptoonrampwidgetui) and is called with the full [`CryptoOnrampWidgetRenderProps`](#cryptoonrampwidgetrenderprops) (context state, actions and forwarded `<div>` props), so callers can build a fully custom UI on top of the same provider. |
+| `tokens` | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a>[]</code> | Target tokens (what the user buys on TON). Defaults to a built-in list. |
+| `tokenSections` | <code><a href="#cryptoonramptokensectionconfig">CryptoOnrampTokenSectionConfig</a>[]</code> | Optional section configs grouping `tokens` in the picker. |
+| `paymentMethods` | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a>[]</code> | Source crypto payment methods (what the user pays with on another chain). Defaults to a built-in list. |
+| `methodSections` | <code><a href="#paymentmethodsectionconfig">PaymentMethodSectionConfig</a>[]</code> | Optional section configs grouping `paymentMethods` in the picker. |
+| `chains` | <code>Record&lt;string, <a href="#chaininfo">ChainInfo</a>&gt;</code> | 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 (e.g. `\{ 'eip155:42161': \{ name: 'Arbitrum', logo: '...' \} \}`). |
+| `defaultTokenId` | `string` | ID of the target token pre-selected on mount. |
+| `defaultMethodId` | `string` | ID of the source payment method pre-selected on mount. |
+
+#### CryptoOnrampWidgetProvider
+
+Context provider that powers the crypto-to-TON onramp widget — wires together token/method selection state, quote fetching ([`useCryptoOnrampQuote`](#usecryptoonrampquote)), deposit creation ([`useCreateCryptoOnrampDeposit`](#usecreatecryptoonrampdeposit)), deposit status polling ([`useCryptoOnrampStatus`](#usecryptoonrampstatus)), the target-token balance and validation. Consumers read the state via [`useCryptoOnrampContext`](#usecryptoonrampcontext).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `tokens` | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a>[]</code> | Target tokens (what the user buys on TON). Defaults to a built-in list. |
+| `tokenSections` | <code><a href="#cryptoonramptokensectionconfig">CryptoOnrampTokenSectionConfig</a>[]</code> | Optional section configs grouping `tokens` in the picker. |
+| `paymentMethods` | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a>[]</code> | Source crypto payment methods (what the user pays with on another chain). Defaults to a built-in list. |
+| `methodSections` | <code><a href="#paymentmethodsectionconfig">PaymentMethodSectionConfig</a>[]</code> | Optional section configs grouping `paymentMethods` in the picker. |
+| `chains` | <code>Record&lt;string, <a href="#chaininfo">ChainInfo</a>&gt;</code> | 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 (e.g. `\{ 'eip155:42161': \{ name: 'Arbitrum', logo: '...' \} \}`). |
+| `defaultTokenId` | `string` | ID of the target token pre-selected on mount. |
+| `defaultMethodId` | `string` | ID of the source payment method pre-selected on mount. |
+
+#### 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`\* | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a>[]</code> | Full list of target tokens the user can buy. |
+| `tokenSections` | <code><a href="#cryptoonramptokensectionconfig">CryptoOnrampTokenSectionConfig</a>[]</code> | Optional section configs grouping `tokens` in the picker. |
+| `selectedToken`\* | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a> \| null</code> | Currently selected target token to buy. `null` until tokens load. |
+| `setSelectedToken`\* | <code>(token: <a href="#cryptoonramptoken">CryptoOnrampToken</a>) =&gt; void</code> | Updates `selectedToken`. |
+| `paymentMethods`\* | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a>[]</code> | Available source crypto payment methods. |
+| `methodSections` | <code><a href="#paymentmethodsectionconfig">PaymentMethodSectionConfig</a>[]</code> | Optional section configs grouping `paymentMethods` in the picker. |
+| `selectedMethod`\* | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a></code> | Currently selected source payment method. |
+| `setSelectedMethod`\* | <code>(method: <a href="#cryptopaymentmethod">CryptoPaymentMethod</a>) =&gt; void</code> | Updates `selectedMethod`. |
+| `chains`\* | <code>Record&lt;string, <a href="#chaininfo">ChainInfo</a>&gt;</code> | 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`\* | <code><a href="#cryptoamountinputmode">CryptoAmountInputMode</a></code> | Which side `amount` is denominated in — see [`CryptoAmountInputMode`](#cryptoamountinputmode). |
+| `setAmountInputMode`\* | <code>(mode: <a href="#cryptoamountinputmode">CryptoAmountInputMode</a>) =&gt; void</code> | Updates `amountInputMode`. |
+| `convertedAmount`\* | `string` | Other side of `amount` after applying the current quote's rate. |
+| `presetAmounts`\* | <code><a href="#onrampamountpreset">OnrampAmountPreset</a>[]</code> | Quick-pick amount buttons rendered in the widget. |
+| `quote`\* | <code><a href="/ecosystem/appkit/reference/appkit#cryptoonrampquote">CryptoOnrampQuote</a> \| null</code> | 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`\* | <code><a href="/ecosystem/appkit/reference/appkit#cryptoonrampdeposit">CryptoOnrampDeposit</a> \| null</code> | 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`\* | <code><a href="/ecosystem/appkit/reference/appkit#cryptoonrampstatus">CryptoOnrampStatus</a> \| null</code> | Latest deposit status polled via [`useCryptoOnrampStatus`](#usecryptoonrampstatus), or `null`. |
+| `isRefundAddressRequired`\* | `boolean` | Whether the current quote provider requires a refund address before deposit. |
+| `isReversedAmountSupported`\* | `boolean` | Whether the current quote provider supports reversed (target-amount) input. |
+| `refundAddress`\* | `string` | Refund address the user typed, if `isRefundAddressRequired`. |
+| `setRefundAddress`\* | `(address: string) => void` | Updates `refundAddress`. |
+| `targetBalance`\* | `string` | Connected wallet's balance of the selected target token (formatted, token units). |
+| `isLoadingTargetBalance`\* | `boolean` | Whether the target token balance is being fetched. |
+| `isWalletConnected`\* | `boolean` | Whether a TON wallet is currently connected. |
+| `canContinue`\* | `boolean` | Whether the user can proceed — valid amount, quote available, and wallet connected. |
+| `onReset`\* | `() => void` | Invalidates the active quote and clears the deposit, returning the widget to its initial state. |
+
+### NFTs
+
+#### 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`\* | <code><a href="/ecosystem/appkit/reference/appkit#nft">NFT</a></code> | NFT to render — name, collection name, image and on-sale state are derived via `getFormattedNftInfo`. |
+
+### Providers
+
+#### AppKitProvider
+
+Top-level React provider that wires AppKit, the TonConnect bridge and i18n into the component tree — wrap your app once near the root so descendant hooks ([`useAppKit`](#useappkit), [`useBalance`](#usebalance), …) and components can resolve their context.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | <code><a href="/ecosystem/appkit/reference/appkit#appkit">AppKit</a></code> | Runtime instance constructed at app startup; shared across every appkit-react hook and component. |
+
+#### I18nProvider
+
+React provider that mounts the i18n context for [`useI18n`](#usei18n) and child components — already wrapped by [`AppKitProvider`](#appkitprovider), so apps usually only render it directly when they need to override the locale or dictionaries.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `locale` | `string` | Initial locale code; defaults to the i18n library's default when omitted. |
+| `lngDicts` | `Record<string, Dict>` | Translation dictionaries keyed by locale; loaded into the underlying i18n instance on mount. |
+
+### Shared
+
+#### AmountPresets
+
+Horizontal row of preset amount buttons — typically used next to an amount input to offer quick fills.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `presets`\* | <code><a href="#amountpreset">AmountPreset</a>[]</code> | 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`. |
+
+#### CopyButton
+
+Icon-only button that copies `value` to the clipboard on click and flips its icon to a checkmark for a short confirmation window.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Text written to the clipboard when the button is clicked. |
+| `aria-label`\* | `string` | Accessible label for screen readers. |
+
+#### CurrencyItem
+
+Compound row used inside currency/token select lists: shows a token logo, name + ticker, optional verified badge, and an optional balance / under-balance on the right. Pass top-level props for the default layout, or pass `children` made of the sub-components for full control.
+
+#### CurrencySelect
+
+Compound currency-select primitives — compose [`CurrencySelect.Modal`](#currencyselect.modal) with a [`CurrencySelect.Search`](#currencyselect.search) and [`CurrencySelect.ListContainer`](#currencyselect.listcontainer) of [`CurrencySelect.Section`](#currencyselect.section) rows to build a custom token picker. For a ready-made implementation see [`TokenSelectModal`](#tokenselectmodal).
+
+Compound component. Members:
+
+##### CurrencySelect.Modal
+
+Modal wrapper.
+
+##### CurrencySelect.Search
+
+Auto-focused search input row.
+
+##### CurrencySelect.ListContainer
+
+Scrollable list area with built-in empty state.
+
+##### CurrencySelect.SectionHeader
+
+Header label rendered above a section.
+
+##### CurrencySelect.Section
+
+Container for a group of currency rows.
+
+#### LowBalanceModal
+
+Modal shown when a transaction would leave insufficient TON to cover fees — adapts its body and buttons to the [`LowBalanceMode`](#lowbalancemode).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `open`\* | `boolean` | Controls visibility of the modal. |
+| `mode`\* | <code><a href="#lowbalancemode">LowBalanceMode</a></code> | `reduce` — user can fix it by reducing the amount (shows Change/Cancel). `topup`  — reducing doesn't help, user must top up TON (shows Close only). |
+| `requiredTon`\* | `string` | Required amount in TON, formatted as a decimal string (e.g. `"0.423"`). |
+| `onChange`\* | `() => void` | Called when the user clicks the primary "Change" action (only in `reduce` mode). |
+| `onCancel`\* | `() => void` | Called when the user dismisses the modal (Cancel, Close, or backdrop click). |
+
+#### OptionSwitcher
+
+Compact dropdown selector — renders the current option's label and a chevron, opening a [`Select`](#select) popover with the remaining choices. Falls back to the raw `value` or `"—"` when no option matches.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string \| undefined` | Currently selected option value. |
+| `options`\* | <code><a href="#optionswitcheroption">OptionSwitcherOption</a>[]</code> | Available options. |
+| `onChange`\* | `(value: string) => void` | Called when the user picks an option. |
+| `disabled` | `boolean` | When true, the trigger is non-interactive and dimmed. |
+| `className` | `string` | Extra class applied to the trigger button. |
+
+#### SettingsButton
+
+Icon-only secondary button with a sliders icon — drop-in trigger for opening settings panels.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `onClick` | `() => void` | Click handler — typically used to open a settings modal. |
+| `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. |
+
+#### TokenSelectModal
+
+Ready-made token picker modal — renders a search field and a sectioned list of [`CurrencyItem`](#currencyitem) rows backed by [`CurrencySelect`](#currencyselect). Search matches by symbol, name, or exact address; selecting a row fires `onSelect`, closes the modal, and resets the search.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `open`\* | `boolean` | Controls modal visibility. |
+| `onClose`\* | `() => void` | Called when the modal is dismissed (selection, backdrop click, or escape). |
+| `tokens`\* | `T = AppkitUIToken[]` | Full set of tokens available for selection and search. |
+| `tokenSections` | <code><a href="#tokensectionconfig">TokenSectionConfig</a>[]</code> | Optional sectioning rules; when omitted, all tokens render as a single untitled section. |
+| `onSelect`\* | `(token: T = AppkitUIToken) => void` | Called with the picked token; the modal closes and resets its search on selection. |
+| `title`\* | `string` | Modal header title. |
+| `searchPlaceholder` | `string` | Placeholder shown inside the search input. |
+
+#### TokenSelector
+
+Compact pill button used as the trigger for a token picker — shows the token icon (optionally with a network badge), its symbol, and a chevron unless `readOnly` is set.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `title`\* | `string` | Label shown next to the icon — typically the token symbol. |
+| `icon` | `string` | Token logo URL. |
+| `iconFallback` | `string` | Single-character fallback used when `icon` fails to load; defaults to the first character of `title`. |
+| `networkIcon` | `string` | When provided, renders a network badge overlay on the icon. |
+| `readOnly` | `boolean` | Hide chevron and suppress click handling — use when there's nothing to pick. |
+| `size` | `ButtonSize` | Size class applied to the button. Pass `'unset'` to skip the size class entirely (no padding, no typography) — useful with `variant="unstyled"`. |
+| `borderRadius` | `ButtonBorderRadius` | Border radius token; defaults to a size-dependent value (`s` → `2xl`, `m` → `l`, `l` → `xl`). |
+| `variant` | `ButtonVariant` | Visual variant. Use `'unstyled'` to opt out of all built-in styling — the consumer is fully responsible for visuals via `className`. The Button still provides ref forwarding, `disabled`/`loading` plumbing, and `icon`/`children` rendering. |
+| `loading` | `boolean` | When true, renders a spinner instead of `icon`/`children` and disables the button. |
+| `fullWidth` | `boolean` | When true, the button stretches to fill its container width. |
+
+### Staking
+
+#### SelectUnstakeMode
+
+Collapsible selector for the unstake mode (instant / round-end / when-available). Filters options by `providerMetadata.supportedUnstakeModes` and renders nothing when only one mode is supported. Annotates the instant option with the provider's current instant-unstake limit.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value`\* | <code><a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a></code> | Currently selected unstake mode (see [`UnstakeMode`](/ecosystem/appkit/reference/appkit#unstakemode)). |
+| `onValueChange`\* | <code>(mode: <a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a>) =&gt; void</code> | Called when the user picks a different mode. |
+| `providerInfo`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingproviderinfo">StakingProviderInfo</a> \| undefined</code> | Dynamic provider info — used to show the instant-unstake limit when available. |
+| `providerMetadata`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> | Static provider metadata — supplies `supportedUnstakeModes` and stake-token formatting. |
+
+#### StakingBalanceBlock
+
+Row showing the user's relevant balance for the current direction: wallet balance of the stake token when staking, staked balance when unstaking. Renders a token icon (native TON when the token address is `'ton'`, otherwise a jetton icon resolved via [`useJettonInfo`](#usejettoninfo)), a label, the formatted amount with ticker, and an optional `MAX` button.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `providerMetadata`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> | Provider metadata — supplies the stake/receive tokens (address, ticker, decimals). |
+| `direction`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a></code> | Operation direction; selects which token and balance to render. |
+| `stakedBalance` | `string` | User's currently staked amount, used when `direction === 'unstake'`. |
+| `isStakedBalanceLoading` | `boolean` | True while the staked balance is being fetched. |
+| `balance` | `string` | User's wallet balance of the stake token, used when `direction === 'stake'`. |
+| `isBalanceLoading` | `boolean` | True while the wallet balance is being fetched. |
+| `onMaxClick` | `() => void` | When provided, renders a `MAX` button that invokes this callback. |
+
+#### StakingInfo
+
+Summary block rendered below the staking input. Shows the amount the user will receive, the provider's current APY, the stake-token to receive-token exchange rate (only when the provider has a receive token), and the provider name. The exchange-rate row always reads as `1 stakeToken = X receiveToken`, regardless of `direction`.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `quote`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquote">StakingQuote</a> \| undefined</code> | Current staking quote — its `amountOut` is rendered in the "You get" row. |
+| `isQuoteLoading`\* | `boolean` | True while the quote is being fetched; swaps the "You get" value for a skeleton. |
+| `providerInfo`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingproviderinfo">StakingProviderInfo</a> \| undefined</code> | Dynamic provider info — supplies APY and exchange rate. |
+| `providerMetadata`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> | Static provider metadata — supplies token tickers/decimals and the provider name. |
+| `isProviderInfoLoading`\* | `boolean` | True while provider info is being fetched. |
+| `direction` | <code><a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a></code> | Operation direction — controls which token's decimals/ticker label the "You get" amount. Defaults to `'stake'`. |
+
+#### StakingSettingsModal
+
+Modal that lets the user pick the active staking provider. The selection is staged locally and only committed via `onProviderChange` when the user presses `Save`; closing the modal otherwise discards the change. Each option is labeled with the provider's metadata `name`, falling back to its `providerId` if metadata is unavailable on the given network.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `open`\* | `boolean` | Controls modal visibility. |
+| `onClose`\* | `() => void` | Called when the user dismisses the modal or after a successful save. |
+| `provider`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a> \| undefined</code> | Currently active staking provider — used to preselect the option when the modal opens. |
+| `providers`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a>[]</code> | All registered staking providers to choose from. |
+| `onProviderChange`\* | `(providerId: string) => void` | Invoked with the chosen `providerId` when the user saves a different selection. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used to resolve each provider's display name via its metadata. |
+
+#### StakingWidget
+
+High-level staking widget that wires the full stake/unstake flow: pick a provider, enter an amount (with optional reverse input on supported providers), review the quote (APY, exchange rate, "you get"), then submit the transaction. Internally wraps [`StakingWidgetProvider`](#stakingwidgetprovider) around [`StakingWidgetUI`](#stakingwidgetui); consumers can replace the UI by passing a render-prop `children` while keeping the widget's state, quoting, balance checks, and submission logic.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `children` | <code>(props: <a href="#stakingwidgetrenderprops">StakingWidgetRenderProps</a>) =&gt; ReactNode</code> | Optional render-prop. When provided, the default [`StakingWidgetUI`](#stakingwidgetui) is bypassed and this function is called with the full [`StakingWidgetRenderProps`](#stakingwidgetrenderprops) (context state + forwarded `<div>` props), letting consumers build a custom UI on top of the widget's internal logic. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used for quote fetching, balance reads, and transactions. Falls back to the connected wallet's network when omitted. |
+
+#### StakingWidgetProvider
+
+Headless provider that owns all staking-widget state. Tracks the input amount, direction (stake/unstake), unstake mode, and reverse-input toggle; resolves the selected provider via [`useStakingProvider`](#usestakingprovider) and its info/metadata via [`useStakingProviderInfo`](#usestakingproviderinfo) and [`useStakingProviderMetadata`](#usestakingprovidermetadata); reads the user's wallet balance (native TON or jetton) and staked balance; debounces inputs into [`useStakingQuote`](#usestakingquote); and submits via [`useBuildStakeTransaction`](#usebuildstaketransaction) + `useSendTransaction`, gating on a TON-shortfall check to surface a low-balance warning. Validation flags (`error`, `canSubmit`) come from `useStakingValidation`. Exposes everything through `StakingContext` for [`useStakingContext`](#usestakingcontext) consumers.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used for quote fetching, balance reads, and transactions. Falls back to the connected wallet's network when omitted. |
+
+#### StakingWidgetUI
+
+Default staking-widget UI. Renders a stake/unstake tabbed layout: a centered amount input with optional reversed input, a [`StakingBalanceBlock`](#stakingbalanceblock) for the relevant balance, the submit button (wired through `ButtonWithConnect` so a disconnected user is prompted to connect first), a settings button that opens [`StakingSettingsModal`](#stakingsettingsmodal), the unstake-mode picker ([`SelectUnstakeMode`](#selectunstakemode), unstake tab only), and a [`StakingInfo`](#stakinginfo) summary. A [`LowBalanceModal`](#lowbalancemodal) surfaces when the built transaction would exceed the user's TON balance. All state is consumed from props (typically supplied by [`StakingWidgetProvider`](#stakingwidgetprovider)); this component owns only the local `settings modal open` flag.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `amount`\* | `string` | Amount the user wants to stake (string to preserve input UX) |
+| `canSubmit`\* | `boolean` | Whether the user can proceed with staking (checks balance, amount validity, etc.) |
+| `quote`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquote">StakingQuote</a> \| undefined</code> | Raw staking quote from the provider |
+| `isQuoteLoading`\* | `boolean` | True while the stake quote is being fetched |
+| `error`\* | `string \| null` | Current validation/fetch error for staking, null when everything is ok |
+| `providerInfo`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingproviderinfo">StakingProviderInfo</a> \| undefined</code> | Staking provider dynamic info (APY, instant unstake availability, etc.) |
+| `providerMetadata`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> | Staking provider static metadata |
+| `stakingProvider`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a> \| undefined</code> | Currently selected staking provider (defaults to the first registered one) |
+| `stakingProviders`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a>[]</code> | All registered staking providers |
+| `setStakingProviderId`\* | `(providerId: string) => void` | Updates the selected staking provider |
+| `network`\* | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a> \| undefined</code> | Network the widget is operating on (resolved from prop or wallet) |
+| `direction`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a></code> | Current operation direction: 'stake' or 'unstake' |
+| `isProviderInfoLoading`\* | `boolean` | True while provider info is being fetched |
+| `balance`\* | `string \| undefined` | Base balance (native or jetton) available for staking |
+| `isBalanceLoading`\* | `boolean` | True while base balance is being fetched |
+| `stakedBalance`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingbalance">StakingBalance</a> \| undefined</code> | User's currently staked balance |
+| `isStakedBalanceLoading`\* | `boolean` | True while staked balance is being fetched |
+| `unstakeMode`\* | <code><a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a></code> | Selected unstake mode (e.g. instant or delayed) |
+| `setAmount`\* | `(amount: string) => void` | Sets the input amount |
+| `setUnstakeMode`\* | <code>(mode: <a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a>) =&gt; void</code> | Sets the unstake mode |
+| `sendTransaction`\* | `() => Promise<void>` | Triggers the staking/unstaking transaction |
+| `onChangeDirection`\* | <code>(direction: <a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a>) =&gt; void</code> | Changes the direction (stake/unstake) |
+| `isSendingTransaction`\* | `boolean` | True while a transaction is being processed |
+| `isReversed`\* | `boolean` | True if the user is inputting the output amount ("I want to get X") |
+| `toggleReversed`\* | `() => void` | Toggles between inputting from amount and output amount |
+| `reversedAmount`\* | `string` | Amount displayed in the reversed (bottom) input |
+| `onMaxClick`\* | `() => void` | Sets the input amount to the maximum available balance (leaves room for TON gas on native stake) |
+| `isLowBalanceWarningOpen`\* | `boolean` | True when the built transaction outflow exceeds the user's TON balance |
+| `lowBalanceMode`\* | `'reduce' \| 'topup'` | `reduce` when the outgoing token is TON (user can fix by changing amount), `topup` otherwise. |
+| `lowBalanceRequiredTon`\* | `string` | Required TON amount for the pending operation, formatted as a decimal string. Empty when no pending op. |
+| `onLowBalanceChange`\* | `() => void` | Replace the input with a value that fits into the current TON balance and close the warning |
+| `onLowBalanceCancel`\* | `() => void` | Dismiss the low-balance warning without changing the input |
+
+### Swap
+
+#### SwapField
+
+One row of the swap form. Renders the amount input, fiat conversion, balance line, and a token-selector chip. The `pay` variant is editable and exposes a "max" shortcut; the `receive` variant is read-only and shows the quote result.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `type`\* | `'pay' \| 'receive'` | `pay` renders the editable source row with a "max" shortcut; `receive` renders the read-only target row. |
+| `amount`\* | `string` | Current amount shown in the input as a human-readable decimal string. |
+| `fiatSymbol` | `string` | Fiat currency symbol displayed in front of the converted value. Defaults to `"$"`. |
+| `token` | `AppkitUIToken` | Currently selected token; controls the token selector label, balance formatting and fiat conversion. |
+| `onAmountChange` | `(value: string) => void` | Called with the raw input value when the user edits the amount. Only fired for `type: "pay"`. |
+| `balance` | `string` | Formatted balance of `token` for the active wallet, as a human-readable decimal string; rendered in the balance line beneath the input. |
+| `isBalanceLoading` | `boolean` | When true, the balance area renders a skeleton placeholder instead of the value. |
+| `loading` | `boolean` | When true, the underlying input renders its loading state — used while a fresh quote is in flight. |
+| `onMaxClick` | `() => void` | Called when the user clicks the "max" shortcut to fill the maximum spendable amount. |
+| `onTokenSelectorClick` | `() => void` | Called when the user clicks the token selector chip — typically opens a `SwapTokenSelectModal`. |
+| `isWalletConnected` | `boolean` | Reserved flag indicating whether a wallet is connected — currently accepted for API symmetry. |
+| `size` | `InputSize` | Size token applied to the input control(s) inside: `'s' | 'm' | 'l'`. Defaults to `'m'`. |
+| `variant` | `InputVariant` | Visual variant: `'default'` paints a filled field; `'unstyled'` drops the chrome. |
+| `disabled` | `boolean` | When true, descendant input controls are disabled. |
+| `error` | `boolean` | When true, the field renders in error styling and [`Input.Caption`](#input.caption) switches to error text. |
+| `resizable` | `boolean` | When true, [`Input.Input`](#input.input) scales its font down to fit the available width as the user types. |
+
+#### SwapFlipButton
+
+Round button rendered between the source and target [`SwapField`](#swapfield) rows. Clicking it flips the selected tokens; visual rotation is driven by `rotated`.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `onClick` | `() => void` | Called when the user clicks the button. Wire this to a handler that swaps the source/target tokens (e.g. `onFlip` from the swap context). |
+| `rotated` | `boolean` | When true, the icon is drawn in its rotated state — used to animate between flips. |
+
+#### SwapInfo
+
+Summary block rendered under the swap form. Shows the minimum amount the user is guaranteed to receive after slippage, the configured slippage tolerance, and the active [`SwapProvider`](/ecosystem/appkit/reference/appkit#swapprovider).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `toToken`\* | `AppkitUIToken \| null` | Target token the user is receiving; used to format `minReceived` with the right decimals and symbol. |
+| `slippage`\* | `number` | Slippage tolerance in basis points (`100` = 1%). Rendered as a percentage. |
+| `provider` | <code><a href="/ecosystem/appkit/reference/appkit#swapprovider">SwapProvider</a></code> | Current [`SwapProvider`](/ecosystem/appkit/reference/appkit#swapprovider); its display name is shown in the provider row. |
+| `quote` | <code><a href="/ecosystem/appkit/reference/appkit#swapquote">SwapQuote</a></code> | Quote whose `minReceived` value is displayed; when undefined the value falls back to `0` (still suffixed with the token symbol). |
+| `isQuoteLoading` | `boolean` | When true, the minimum-received value renders a skeleton placeholder instead of the formatted number. |
+
+#### SwapWidget
+
+Drop-in swap UI that walks the user through picking the source/target tokens, entering an amount, reviewing the quote (rate, min-received, slippage, provider), and confirming the swap — which builds the transaction via [`useBuildSwapTransaction`](#usebuildswaptransaction) and dispatches it through the standard send flow. Internally mounts a [`SwapWidgetProvider`](#swapwidgetprovider) so the rendered UI (default [`SwapWidgetUI`](#swapwidgetui) or a custom `children` render-prop) can read state through [`useSwapContext`](#useswapcontext).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `children` | <code>(props: <a href="#swapwidgetrenderprops">SwapWidgetRenderProps</a>) =&gt; ReactNode</code> | Optional render-prop receiving the full swap context plus the forwarded `<div>` props; when supplied it replaces the default [`SwapWidgetUI`](#swapwidgetui). |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used for quote fetching and balance reads. When omitted, falls back to the selected wallet's network via [`useNetwork`](#usenetwork). |
+| `tokens`\* | `AppkitUIToken[]` | Full list of tokens available for swapping in the UI. Filtered to the active network internally. |
+| `tokenSections` | <code><a href="#tokensectionconfig">TokenSectionConfig</a>[]</code> | Optional section configs for grouping tokens inside the `SwapTokenSelectModal`. |
+| `defaultFromSymbol` | `string` | Symbol of the token pre-selected as the source on first mount (e.g. `"TON"`). |
+| `defaultToSymbol` | `string` | Symbol of the token pre-selected as the target on first mount. |
+| `fiatSymbol` | `string` | Fiat currency symbol displayed next to converted amounts. Defaults to `"$"`. |
+| `defaultSlippage` | `number` | Initial slippage tolerance in basis points (`100` = 1%). Defaults to `100`. |
+
+#### SwapWidgetProvider
+
+Provider that wires up the full swap state machine — debounces the entered amount, fetches the quote via [`useSwapQuote`](#useswapquote), reads source/target balances, validates the input, exposes the active [`SwapProvider`](/ecosystem/appkit/reference/appkit#swapprovider), and offers `sendSwapTransaction` which builds the transaction with [`useBuildSwapTransaction`](#usebuildswaptransaction) and sends it (raising the low-balance warning when the outflow exceeds the user's TON balance). Children read everything through [`useSwapContext`](#useswapcontext).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `tokens`\* | `AppkitUIToken[]` | Full list of tokens available for swapping in the UI. Filtered to the active network internally. |
+| `tokenSections` | <code><a href="#tokensectionconfig">TokenSectionConfig</a>[]</code> | Optional section configs for grouping tokens inside the `SwapTokenSelectModal`. |
+| `defaultFromSymbol` | `string` | Symbol of the token pre-selected as the source on first mount (e.g. `"TON"`). |
+| `defaultToSymbol` | `string` | Symbol of the token pre-selected as the target on first mount. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used for quote fetching and balance reads. When omitted, falls back to the selected wallet's network via [`useNetwork`](#usenetwork). |
+| `fiatSymbol` | `string` | Fiat currency symbol displayed next to converted amounts. Defaults to `"$"`. |
+| `defaultSlippage` | `number` | Initial slippage tolerance in basis points (`100` = 1%). Defaults to `100`. |
+
+#### SwapWidgetUI
+
+Default visual implementation of the swap widget — composes [`SwapField`](#swapfield) (source, then target), a [`SwapFlipButton`](#swapflipbutton) between them, the submit button (auto-prompts wallet connect when no wallet is selected), the settings trigger that opens `SwapSettingsModal`, a `SwapTokenSelectModal` for picking source/target tokens, the [`SwapInfo`](#swapinfo) summary, and a low-balance warning. Drives all state from the swap context props it receives — pair with [`SwapWidgetProvider`](#swapwidgetprovider), or use [`SwapWidget`](#swapwidget) which mounts both.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `tokens`\* | `AppkitUIToken[]` | Full list of available tokens for swapping |
+| `tokenSections` | <code><a href="#tokensectionconfig">TokenSectionConfig</a>[]</code> | Optional section configs for grouping tokens in the selector |
+| `fromToken`\* | `AppkitUIToken \| null` | Currently selected source token |
+| `toToken`\* | `AppkitUIToken \| null` | Currently selected target token |
+| `fromAmount`\* | `string` | Amount the user wants to swap (string to preserve input UX) |
+| `toAmount`\* | `string` | Calculated receive amount from the current quote |
+| `fiatSymbol`\* | `string` | Fiat currency symbol for price display, e.g. "$" |
+| `fromBalance`\* | `string \| undefined` | User's balance of the "from" token |
+| `toBalance`\* | `string \| undefined` | User's balance of the "to" token |
+| `isFromBalanceLoading`\* | `boolean` | True while the "from" balance is being fetched |
+| `isToBalanceLoading`\* | `boolean` | True while the "to" balance is being fetched |
+| `canSubmit`\* | `boolean` | Whether the user can proceed with the swap (checks balance, amount, quote) |
+| `quote`\* | `GetSwapQuoteData \| undefined` | Raw swap quote from the provider |
+| `isQuoteLoading`\* | `boolean` | True while the quote is being fetched from the API |
+| `error`\* | `string \| null` | Current validation or fetch error, null when everything is ok |
+| `slippage`\* | `number` | Slippage tolerance in basis points (100 = 1%) |
+| `swapProvider`\* | <code><a href="/ecosystem/appkit/reference/appkit#swapprovider">SwapProvider</a> \| undefined</code> | Currently selected swap provider (defaults to the first registered one) |
+| `swapProviders`\* | <code><a href="/ecosystem/appkit/reference/appkit#swapprovider">SwapProvider</a>[]</code> | All registered swap providers |
+| `setSwapProviderId`\* | `(providerId: string) => void` | Updates the selected swap provider |
+| `setFromToken`\* | `(token: AppkitUIToken) => void` | Updates the source token |
+| `setToToken`\* | `(token: AppkitUIToken) => void` | Updates the target token |
+| `setFromAmount`\* | `(amount: string) => void` | Updates the swap amount |
+| `setSlippage`\* | `(slippage: number) => void` | Updates the slippage tolerance |
+| `onFlip`\* | `() => void` | Swaps source and target tokens |
+| `onMaxClick`\* | `() => void` | Sets the "from" amount to the maximum available balance |
+| `sendSwapTransaction`\* | `() => Promise<void>` | Executes the swap transaction |
+| `isSendingTransaction`\* | `boolean` | True while a transaction is being built or sent |
+| `isLowBalanceWarningOpen`\* | `boolean` | True when the built transaction outflow exceeds the user's TON balance |
+| `lowBalanceMode`\* | `'reduce' \| 'topup'` | `reduce` when the outgoing token is TON (user can fix by changing amount), `topup` otherwise. |
+| `lowBalanceRequiredTon`\* | `string` | Required TON amount for the pending operation, formatted as a decimal string. Empty when no pending op. |
+| `onLowBalanceChange`\* | `() => void` | Replace the input with a value that fits into the current TON balance and close the warning |
+| `onLowBalanceCancel`\* | `() => void` | Dismiss the low-balance warning without changing the input |
+
+### UI
+
+#### Block
+
+Flex container primitive — renders a `<div>` that lays its children out vertically (`'column'`) or horizontally (`'row'`).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `direction` | `'row' \| 'column'` | Flex direction of the block. Defaults to `'column'`. |
+
+#### Button
+
+Themed `<button>` with size, border-radius, and variant tokens. Renders an optional leading `icon`, swaps content for a spinner while `loading`, and is disabled whenever `disabled` or `loading` is true.
+
+#### CenteredAmountInput
+
+Center-aligned, auto-resizing amount input with optional leading symbol and trailing ticker. Scales the font down to fit the container when the rendered text overflows, and clicking the wrapper focuses the input.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Controlled input value (decimal string). |
+| `onValueChange`\* | `(value: string) => void` | Called with the new string whenever the user edits the input. |
+| `ticker` | `string` | Optional trailing ticker label (e.g., `'TON'`). |
+| `symbol` | `string` | Optional leading currency symbol (e.g., `'$'`). |
+| `placeholder` | `string` | Placeholder shown when `value` is empty. Defaults to `'0'`. |
+| `disabled` | `boolean` | When true, the underlying `<input>` is disabled. |
+
+#### CheckIcon
+
+Checkmark icon — a single stroked tick.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### ChevronDownIcon
+
+Downward-pointing chevron icon — typically used to indicate expandable content.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### ChevronsIcon
+
+Stacked up/down chevrons icon — used to signal select/dropdown affordance.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### CloseIcon
+
+Close (X) icon — used for dismiss buttons and modal close affordances.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### Collapsible
+
+Animated collapsible container — transitions its height between `0` and the content's natural height when `open` toggles. Sets `aria-hidden` to mirror the open state.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `open`\* | `boolean` | When true, the content is expanded; when false, it is collapsed to zero height. |
+
+#### CopyIcon
+
+Copy icon — two overlapping rectangles indicating clipboard copy.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### FailedIcon
+
+Failure icon — a circle with an X, used for error and failed-transaction states.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### FlipIcon
+
+Flip / swap icon — two opposing arrows used for swap and direction-toggle actions.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### ImageIcon
+
+Image / picture placeholder icon — used as a fallback for missing media.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### InfoBlock
+
+Compound component for rendering a stacked list of label/value rows (e.g., transaction details, settings summaries). Sub-components forward extra props to the underlying DOM element so callers can layer custom classes and handlers.
+
+Compound component. Members:
+
+##### InfoBlock.Container
+
+Outer wrapper — vertical container that hosts the rows.
+
+##### InfoBlock.Row
+
+Horizontal row that pairs a label with a value.
+
+##### InfoBlock.Label
+
+Label cell — typically the muted descriptor on the left.
+
+##### InfoBlock.Value
+
+Value cell — typically the emphasized content on the right.
+
+##### InfoBlock.LabelSkeleton
+
+Skeleton placeholder for a [`InfoBlock.Label`](#infoblock.label) while data is loading. Defaults to `width=64`, `height='1lh'`.
+
+##### InfoBlock.ValueSkeleton
+
+Skeleton placeholder for a [`InfoBlock.Value`](#infoblock.value) while data is loading. Defaults to `width=80`, `height='1lh'`.
+
+#### Input
+
+Compound text-input component. Use the default export as the outer wrapper (it is the [`Input.Container`](#input.container)) and compose sub-components for the header, field, slots, control, and caption. State flags (`disabled`, `error`, `loading`, `resizable`, `size`) live on the container and are read by the inner control via context.
+
+#### Logo
+
+Square logo / avatar primitive — renders an `<img>` when `src` loads successfully, otherwise shows a text fallback (after a brief delay to avoid flicker). Useful for token icons, wallet avatars, and project logos.
+
+#### LogoWithNetwork
+
+Token logo with an overlaid network badge — wraps [`Logo`](#logo) and renders a smaller secondary logo as a corner badge to indicate which network the asset belongs to.
+
+#### Modal
+
+Centered modal dialog with a header (optional title + close button) and a scrollable body. Clicking the overlay closes the modal; clicks on the content do not bubble through.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `open` | `boolean` | Controlled open state. |
+| `onOpenChange` | `(open: boolean) => void` | Called whenever the open state changes (e.g., via the close button, overlay click, or `Escape`). |
+| `title` | `string` | Optional title rendered in the modal header. |
+| `children` | `ReactNode` | Modal body content. |
+| `className` | `string` | Additional class name applied to the content container. |
+| `bodyClassName` | `string` | Additional class name applied to the body container. |
+
+#### SearchIcon
+
+Magnifying-glass search icon.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### Select
+
+Compound select / dropdown component with controlled or uncontrolled state. The content is portaled to `document.body` and positioned relative to the trigger; closes on outside click, `Escape`, or item selection.
+
+Compound component. Members:
+
+##### Select.Root
+
+Provider that owns the selected value and open state, controlled or uncontrolled.
+
+##### Select.Trigger
+
+[`Button`](#button)-based trigger that toggles the popover and exposes `aria-expanded`.
+
+##### Select.Content
+
+Portaled popover that renders the list of items; positioned under the trigger with optional `sideOffset`.
+
+##### Select.Item
+
+Selectable option row; commits its `value` to the root on click.
+
+#### Skeleton
+
+Animated placeholder block used while data is loading. Supply `width` / `height` to match the dimensions of the eventual content.
+
+#### SlidersIcon
+
+Sliders / settings icon — two horizontal tracks with adjustable handles.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### SpinnerIcon
+
+Loading spinner icon — a three-quarter circle stroke. Animation must be applied via CSS by the caller.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### SuccessIcon
+
+Success icon — a circle with an inner checkmark for confirmation states.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### Tabs
+
+Root tabs container — owns the active value (controlled or uncontrolled) and shares it with descendant [`TabsList`](#tabslist), [`TabsTrigger`](#tabstrigger), and [`TabsContent`](#tabscontent) via context.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value` | `string` | Controlled active tab value. |
+| `defaultValue` | `string` | Initial active tab when uncontrolled. Defaults to `''`. |
+| `onValueChange` | `(value: string) => void` | Called whenever the active tab changes. |
+| `children`\* | `ReactNode` | Compound sub-components — typically [`TabsList`](#tabslist) (with [`TabsTrigger`](#tabstrigger)s) followed by [`TabsContent`](#tabscontent)s. |
+
+#### TabsContent
+
+Tab panel rendered with `role="tabpanel"`. Returns `null` unless its `value` matches the active [`Tabs`](#tabs) value.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Value this panel is associated with — rendered only when the parent [`Tabs`](#tabs) is on this value. |
+| `children`\* | `ReactNode` | Panel content. |
+
+#### TabsList
+
+Horizontal list of tab triggers with `role="tablist"`.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `children`\* | `ReactNode` | Tab triggers — typically one or more [`TabsTrigger`](#tabstrigger)s. |
+
+#### TabsTrigger
+
+Tab trigger button with `role="tab"`. Activates its `value` on click and reflects active state via `aria-selected` and `data-state`.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Value committed to the parent [`Tabs`](#tabs) when this trigger is activated. |
+| `children`\* | `ReactNode` | Trigger label / content. |
+
+#### TonIcon
+
+TON brand diamond glyph — solid, inherits color from `currentColor`.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### TonIconCircle
+
+TON brand glyph rendered inside a filled circle, using the TON brand color token.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### VerifiedIcon
+
+Verified badge icon — scalloped seal with an inner checkmark.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+## Type
+
+### Balances
+
+#### SendJettonButtonProps
+
+Props accepted by [`SendJettonButton`](#sendjettonbutton) — extends the base `Send` button props (button text, sizing, callbacks) with the jetton-transfer details.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `recipientAddress`\* | `string` | Recipient address. |
+| `amount`\* | `string` | Amount in jetton units as a human-readable decimal string; converted to raw smallest units via `jetton.decimals`. |
+| `jetton`\* | `{         address: string;         symbol: string;         decimals: number;     }` | Jetton master metadata — `address` (master contract), `symbol` (rendered in the button label) and `decimals` (used to format `amount`). |
+| `comment` | `string` | Optional human-readable comment attached to the transfer. |
+| `text` | `ReactNode` | Custom button text |
+| `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 |
+| `onError` | `(error: Error) => void` | Callback when an error occurs |
+| `onSuccess` | <code>(response: <a href="/ecosystem/appkit/reference/appkit#sendtransactionreturntype">SendTransactionReturnType</a>) =&gt; void</code> | Callback when the transaction is successful |
+
+#### SendTonButtonProps
+
+Props accepted by [`SendTonButton`](#sendtonbutton) — extends the base `Send` button props (button text, sizing, callbacks) with the TON-transfer details.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `recipientAddress`\* | `string` | Recipient address. |
+| `amount`\* | `string` | Amount in TON as a human-readable decimal string (e.g., `"1.5"`); converted to nano-TON internally. |
+| `comment` | `string` | Optional human-readable comment attached to the transfer. |
+| `text` | `ReactNode` | Custom button text |
+| `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 |
+| `onError` | `(error: Error) => void` | Callback when an error occurs |
+| `onSuccess` | <code>(response: <a href="/ecosystem/appkit/reference/appkit#sendtransactionreturntype">SendTransactionReturnType</a>) =&gt; void</code> | Callback when the transaction is successful |
+
+#### UseBalanceByAddressParameters
+
+Parameters accepted by [`useBalanceByAddress`](#usebalancebyaddress) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the target address and optional network override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Wallet address — pass a [`UserFriendlyAddress`](/ecosystem/appkit/reference/appkit#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseBalanceByAddressReturnType
+
+Return type of [`useBalanceByAddress`](#usebalancebyaddress) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseBalanceByAddressReturnType = UseQueryReturnType<
+    selectData,
+    GetBalanceErrorType
+>;
+```
+
+#### UseBalanceParameters
+
+Parameters accepted by [`useBalance`](#usebalance) — same shape as [`UseBalanceByAddressParameters`](#usebalancebyaddressparameters); the hook resolves `address` from the selected wallet and overrides any value supplied here.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Wallet address — pass a [`UserFriendlyAddress`](/ecosystem/appkit/reference/appkit#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseBalanceReturnType
+
+Return type of [`useBalance`](#usebalance) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseBalanceReturnType = UseBalanceByAddressReturnType<selectData>;
+```
+
+#### UseWatchBalanceByAddressParameters
+
+Parameters accepted by [`useWatchBalanceByAddress`](#usewatchbalancebyaddress) — same fields as [`WatchBalanceByAddressOptions`](/ecosystem/appkit/reference/appkit#watchbalancebyaddressoptions), all optional so callers can render the hook before the address is known.
+
+```ts
+type UseWatchBalanceByAddressParameters = Partial<WatchBalanceByAddressOptions>;
+```
+
+#### UseWatchBalanceParameters
+
+Parameters accepted by [`useWatchBalance`](#usewatchbalance) — same fields as [`UseWatchBalanceByAddressParameters`](#usewatchbalancebyaddressparameters) minus `address`, which the hook resolves from the selected wallet.
+
+```ts
+type UseWatchBalanceParameters = Omit<UseWatchBalanceByAddressParameters, 'address'>;
+```
+
+### Connectors
+
+#### UseConnectorsReturnType
+
+Return type of [`useConnectors`](#useconnectors) — same shape as [`GetConnectorsReturnType`](/ecosystem/appkit/reference/appkit#getconnectorsreturntype).
+
+```ts
+type UseConnectorsReturnType = GetConnectorsReturnType;
+```
+
+### Crypto Onramp
+
+#### ChainInfo
+
+Display info for a CAIP-2 chain — used by the crypto onramp widget to render chain names and logos.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name`\* | `string` | Human-readable chain name (e.g. `"Ethereum"`, `"Arbitrum One"`). |
+| `logo` | `string` | Optional logo URL for the chain. |
+
+#### CryptoAmountInputMode
+
+Which side the amount input is currently denominated in — `token` means the user is entering the target-token amount, `method` means they are entering the source payment-method amount.
+
+```ts
+type CryptoAmountInputMode = 'token' | 'method';
+```
+
+#### CryptoOnrampContextType
+
+Shape of the `CryptoOnrampContext` value — selection state, quote/deposit data and actions exposed by [`CryptoOnrampWidgetProvider`](#cryptoonrampwidgetprovider) to the widget UI (and to custom render callbacks passed to [`CryptoOnrampWidget`](#cryptoonrampwidget)).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `tokens`\* | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a>[]</code> | Full list of target tokens the user can buy. |
+| `tokenSections` | <code><a href="#cryptoonramptokensectionconfig">CryptoOnrampTokenSectionConfig</a>[]</code> | Optional section configs grouping `tokens` in the picker. |
+| `selectedToken`\* | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a> \| null</code> | Currently selected target token to buy. `null` until tokens load. |
+| `setSelectedToken`\* | <code>(token: <a href="#cryptoonramptoken">CryptoOnrampToken</a>) =&gt; void</code> | Updates `selectedToken`. |
+| `paymentMethods`\* | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a>[]</code> | Available source crypto payment methods. |
+| `methodSections` | <code><a href="#paymentmethodsectionconfig">PaymentMethodSectionConfig</a>[]</code> | Optional section configs grouping `paymentMethods` in the picker. |
+| `selectedMethod`\* | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a></code> | Currently selected source payment method. |
+| `setSelectedMethod`\* | <code>(method: <a href="#cryptopaymentmethod">CryptoPaymentMethod</a>) =&gt; void</code> | Updates `selectedMethod`. |
+| `chains`\* | <code>Record&lt;string, <a href="#chaininfo">ChainInfo</a>&gt;</code> | 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`\* | <code><a href="#cryptoamountinputmode">CryptoAmountInputMode</a></code> | Which side `amount` is denominated in — see [`CryptoAmountInputMode`](#cryptoamountinputmode). |
+| `setAmountInputMode`\* | <code>(mode: <a href="#cryptoamountinputmode">CryptoAmountInputMode</a>) =&gt; void</code> | Updates `amountInputMode`. |
+| `convertedAmount`\* | `string` | Other side of `amount` after applying the current quote's rate. |
+| `presetAmounts`\* | <code><a href="#onrampamountpreset">OnrampAmountPreset</a>[]</code> | Quick-pick amount buttons rendered in the widget. |
+| `quote`\* | <code><a href="/ecosystem/appkit/reference/appkit#cryptoonrampquote">CryptoOnrampQuote</a> \| null</code> | 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`\* | <code><a href="/ecosystem/appkit/reference/appkit#cryptoonrampdeposit">CryptoOnrampDeposit</a> \| null</code> | 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`\* | <code><a href="/ecosystem/appkit/reference/appkit#cryptoonrampstatus">CryptoOnrampStatus</a> \| null</code> | Latest deposit status polled via [`useCryptoOnrampStatus`](#usecryptoonrampstatus), or `null`. |
+| `isRefundAddressRequired`\* | `boolean` | Whether the current quote provider requires a refund address before deposit. |
+| `isReversedAmountSupported`\* | `boolean` | Whether the current quote provider supports reversed (target-amount) input. |
+| `refundAddress`\* | `string` | Refund address the user typed, if `isRefundAddressRequired`. |
+| `setRefundAddress`\* | `(address: string) => void` | Updates `refundAddress`. |
+| `targetBalance`\* | `string` | Connected wallet's balance of the selected target token (formatted, token units). |
+| `isLoadingTargetBalance`\* | `boolean` | Whether the target token balance is being fetched. |
+| `isWalletConnected`\* | `boolean` | Whether a TON wallet is currently connected. |
+| `canContinue`\* | `boolean` | Whether the user can proceed — valid amount, quote available, and wallet connected. |
+| `onReset`\* | `() => void` | Invalidates the active quote and clears the deposit, returning the widget to its initial state. |
+
+#### CryptoOnrampProviderProps
+
+Props for [`CryptoOnrampWidgetProvider`](#cryptoonrampwidgetprovider) — configures the target tokens and payment methods exposed to the widget, plus optional chain display overrides.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `tokens` | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a>[]</code> | Target tokens (what the user buys on TON). Defaults to a built-in list. |
+| `tokenSections` | <code><a href="#cryptoonramptokensectionconfig">CryptoOnrampTokenSectionConfig</a>[]</code> | Optional section configs grouping `tokens` in the picker. |
+| `paymentMethods` | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a>[]</code> | Source crypto payment methods (what the user pays with on another chain). Defaults to a built-in list. |
+| `methodSections` | <code><a href="#paymentmethodsectionconfig">PaymentMethodSectionConfig</a>[]</code> | Optional section configs grouping `paymentMethods` in the picker. |
+| `chains` | <code>Record&lt;string, <a href="#chaininfo">ChainInfo</a>&gt;</code> | 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 (e.g. `\{ 'eip155:42161': \{ name: 'Arbitrum', logo: '...' \} \}`). |
+| `defaultTokenId` | `string` | ID of the target token pre-selected on mount. |
+| `defaultMethodId` | `string` | ID of the source payment method pre-selected on mount. |
+
+#### CryptoOnrampToken
+
+Target token (what the user is buying on TON) in the crypto onramp widget. Kept separate from `AppkitUIToken` because `address` is the raw form expected by the onramp provider (e.g. `"0x0000000000000000000000000000000000000000"` for native TON, `"EQCx..."` for USDT jetton master).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id`\* | `string` | Stable identifier used by section configs and pre-selection props. |
+| `symbol`\* | `string` | Token symbol, e.g. `"TON"`, `"USDT"`. |
+| `name`\* | `string` | Full token name, e.g. `"Toncoin"`, `"Tether"`. |
+| `decimals`\* | `number` | Number of decimals for the token. |
+| `address`\* | `string` | Address as the onramp provider expects it. |
+| `logo` | `string` | Optional logo URL. |
+
+#### CryptoOnrampTokenSectionConfig
+
+Section configuration grouping [`CryptoOnrampToken`](#cryptoonramptoken) entries by id in a picker.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `title`\* | `string` | Section header (typically already localized by the caller). |
+| `ids`\* | `string[]` | Ids of [`CryptoOnrampToken`](#cryptoonramptoken) entries to include in this section, in order. |
+
+#### CryptoOnrampWidgetProps
+
+Props for [`CryptoOnrampWidget`](#cryptoonrampwidget) — extends [`CryptoOnrampProviderProps`](#cryptoonrampproviderprops) (tokens, payment methods, defaults, chain overrides) plus the native `<div>` props the widget root forwards.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `children` | <code>(props: <a href="#cryptoonrampwidgetrenderprops">CryptoOnrampWidgetRenderProps</a>) =&gt; ReactNode</code> | Custom render function. When provided, replaces the default [`CryptoOnrampWidgetUI`](#cryptoonrampwidgetui) and is called with the full [`CryptoOnrampWidgetRenderProps`](#cryptoonrampwidgetrenderprops) (context state, actions and forwarded `<div>` props), so callers can build a fully custom UI on top of the same provider. |
+| `tokens` | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a>[]</code> | Target tokens (what the user buys on TON). Defaults to a built-in list. |
+| `tokenSections` | <code><a href="#cryptoonramptokensectionconfig">CryptoOnrampTokenSectionConfig</a>[]</code> | Optional section configs grouping `tokens` in the picker. |
+| `paymentMethods` | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a>[]</code> | Source crypto payment methods (what the user pays with on another chain). Defaults to a built-in list. |
+| `methodSections` | <code><a href="#paymentmethodsectionconfig">PaymentMethodSectionConfig</a>[]</code> | Optional section configs grouping `paymentMethods` in the picker. |
+| `chains` | <code>Record&lt;string, <a href="#chaininfo">ChainInfo</a>&gt;</code> | 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 (e.g. `\{ 'eip155:42161': \{ name: 'Arbitrum', logo: '...' \} \}`). |
+| `defaultTokenId` | `string` | ID of the target token pre-selected on mount. |
+| `defaultMethodId` | `string` | ID of the source payment method pre-selected on mount. |
+
+#### CryptoOnrampWidgetRenderProps
+
+Props for [`CryptoOnrampWidgetUI`](#cryptoonrampwidgetui) (and for the custom render callback on [`CryptoOnrampWidget`](#cryptoonrampwidget)) — the full [`CryptoOnrampContextType`](#cryptoonrampcontexttype) state and actions, plus the native `<div>` props the widget root forwards (`className`, `style`, etc.).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `tokens`\* | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a>[]</code> | Full list of target tokens the user can buy. |
+| `tokenSections` | <code><a href="#cryptoonramptokensectionconfig">CryptoOnrampTokenSectionConfig</a>[]</code> | Optional section configs grouping `tokens` in the picker. |
+| `selectedToken`\* | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a> \| null</code> | Currently selected target token to buy. `null` until tokens load. |
+| `setSelectedToken`\* | <code>(token: <a href="#cryptoonramptoken">CryptoOnrampToken</a>) =&gt; void</code> | Updates `selectedToken`. |
+| `paymentMethods`\* | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a>[]</code> | Available source crypto payment methods. |
+| `methodSections` | <code><a href="#paymentmethodsectionconfig">PaymentMethodSectionConfig</a>[]</code> | Optional section configs grouping `paymentMethods` in the picker. |
+| `selectedMethod`\* | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a></code> | Currently selected source payment method. |
+| `setSelectedMethod`\* | <code>(method: <a href="#cryptopaymentmethod">CryptoPaymentMethod</a>) =&gt; void</code> | Updates `selectedMethod`. |
+| `chains`\* | <code>Record&lt;string, <a href="#chaininfo">ChainInfo</a>&gt;</code> | 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`\* | <code><a href="#cryptoamountinputmode">CryptoAmountInputMode</a></code> | Which side `amount` is denominated in — see [`CryptoAmountInputMode`](#cryptoamountinputmode). |
+| `setAmountInputMode`\* | <code>(mode: <a href="#cryptoamountinputmode">CryptoAmountInputMode</a>) =&gt; void</code> | Updates `amountInputMode`. |
+| `convertedAmount`\* | `string` | Other side of `amount` after applying the current quote's rate. |
+| `presetAmounts`\* | <code><a href="#onrampamountpreset">OnrampAmountPreset</a>[]</code> | Quick-pick amount buttons rendered in the widget. |
+| `quote`\* | <code><a href="/ecosystem/appkit/reference/appkit#cryptoonrampquote">CryptoOnrampQuote</a> \| null</code> | 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`\* | <code><a href="/ecosystem/appkit/reference/appkit#cryptoonrampdeposit">CryptoOnrampDeposit</a> \| null</code> | 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`\* | <code><a href="/ecosystem/appkit/reference/appkit#cryptoonrampstatus">CryptoOnrampStatus</a> \| null</code> | Latest deposit status polled via [`useCryptoOnrampStatus`](#usecryptoonrampstatus), or `null`. |
+| `isRefundAddressRequired`\* | `boolean` | Whether the current quote provider requires a refund address before deposit. |
+| `isReversedAmountSupported`\* | `boolean` | Whether the current quote provider supports reversed (target-amount) input. |
+| `refundAddress`\* | `string` | Refund address the user typed, if `isRefundAddressRequired`. |
+| `setRefundAddress`\* | `(address: string) => void` | Updates `refundAddress`. |
+| `targetBalance`\* | `string` | Connected wallet's balance of the selected target token (formatted, token units). |
+| `isLoadingTargetBalance`\* | `boolean` | Whether the target token balance is being fetched. |
+| `isWalletConnected`\* | `boolean` | Whether a TON wallet is currently connected. |
+| `canContinue`\* | `boolean` | Whether the user can proceed — valid amount, quote available, and wallet connected. |
+| `onReset`\* | `() => void` | Invalidates the active quote and clears the deposit, returning the widget to its initial state. |
+
+#### CryptoPaymentMethod
+
+Source crypto payment method (what the user pays with on another chain) in the crypto onramp widget.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id`\* | `string` | Stable identifier for the method — used for selection state and `methodSections.ids` |
+| `symbol`\* | `string` | Token symbol, e.g. "USDC", "USDT" |
+| `name`\* | `string` | Full token name shown in the picker, e.g. "USD Coin", "Tether" |
+| `chain`\* | `string` | Source chain in CAIP-2 format, e.g. "eip155:8453", "eip155:56" — passed as `sourceChain` to the onramp provider. The widget resolves a display name and logo for it via the `chains` map (see `CryptoOnrampWidgetProvider`). |
+| `decimals`\* | `number` | Number of decimals for the token (used to convert between display and base units) |
+| `address`\* | `string` | Token contract address on the source network (empty string / zero address for native) |
+| `logo` | `string` | Token logo URL shown in the picker and selectors |
+
+#### OnrampAmountPreset
+
+Quick-pick amount button shown above the crypto-onramp input (carried on [`CryptoOnrampContextType`](#cryptoonrampcontexttype)'s `presetAmounts`).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `amount`\* | `string` | Amount value the preset sets on click (decimal string). |
+| `label`\* | `string` | Button label shown to the user. |
+
+#### PaymentMethodSectionConfig
+
+Section configuration grouping [`CryptoPaymentMethod`](#cryptopaymentmethod) entries by id in a picker.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `title`\* | `string` | Section header (typically already localized by the caller). |
+| `ids`\* | `string[]` | Ids of [`CryptoPaymentMethod`](#cryptopaymentmethod) entries to include in this section, in order. |
+
+#### UseCreateCryptoOnrampDepositParameters
+
+Parameters accepted by [`useCreateCryptoOnrampDeposit`](#usecreatecryptoonrampdeposit) — TanStack Query mutation options forwarded via `parameters.mutation`.
+
+```ts
+type UseCreateCryptoOnrampDepositParameters = CreateCryptoOnrampDepositMutationOptions<context>;
+```
+
+#### UseCreateCryptoOnrampDepositReturnType
+
+Return type of [`useCreateCryptoOnrampDeposit`](#usecreatecryptoonrampdeposit) — TanStack Query mutation result.
+
+```ts
+type UseCreateCryptoOnrampDepositReturnType = UseMutationResult<
+    CreateCryptoOnrampDepositData,
+    CreateCryptoOnrampDepositErrorType,
+    CreateCryptoOnrampDepositVariables,
+    context
+>;
+```
+
+#### UseCryptoOnrampProviderReturnType
+
+Return type of [`useCryptoOnrampProvider`](#usecryptoonrampprovider) — the matching [`CryptoOnrampProviderInterface`](/ecosystem/appkit/reference/appkit#cryptoonrampproviderinterface), or `undefined` when none is registered (the hook swallows the throw from [`getCryptoOnrampProvider`](/ecosystem/appkit/reference/appkit#getcryptoonrampprovider)).
+
+```ts
+type UseCryptoOnrampProviderReturnType = GetCryptoOnrampProviderReturnType | undefined;
+```
+
+#### UseCryptoOnrampProvidersReturnType
+
+Return type of [`useCryptoOnrampProviders`](#usecryptoonrampproviders) — array of every [`CryptoOnrampProviderInterface`](/ecosystem/appkit/reference/appkit#cryptoonrampproviderinterface) currently registered on the AppKit instance.
+
+```ts
+type UseCryptoOnrampProvidersReturnType = GetCryptoOnrampProvidersReturnType;
+```
+
+#### UseCryptoOnrampQuoteParameters
+
+Parameters accepted by [`useCryptoOnrampQuote`](#usecryptoonrampquote) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the source/target assets, amount and optional provider override forwarded to [`getCryptoOnrampQuote`](/ecosystem/appkit/reference/appkit#getcryptoonrampquote).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `amount` | `string` | Amount to onramp (either source or target crypto, depending on isSourceAmount) |
+| `sourceCurrencyAddress` | `string` | Source crypto currency address (contract address or 0x0... for native) |
+| `sourceChain` | `string` | Source chain identifier in CAIP-2 format (e.g. 'eip155:1' for Ethereum mainnet, 'eip155:42161' for Arbitrum One). Providers map this to their own chain identifiers internally. |
+| `targetCurrencyAddress` | `string` | Target crypto currency address on TON (contract address or 0x0... for native) |
+| `recipientAddress` | `string` | TON address that will receive the target crypto |
+| `refundAddress` | `string` | Refund address for the source crypto |
+| `isSourceAmount` | `boolean` | If true, `amount` is the source amount to spend. If false, `amount` is the target amount to receive. Defaults to true when omitted. |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `providerId` | `string` | Provider to quote against; defaults to the registered default provider. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseCryptoOnrampQuoteReturnType
+
+Return type of [`useCryptoOnrampQuote`](#usecryptoonrampquote) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseCryptoOnrampQuoteReturnType = UseQueryReturnType<
+    selectData,
+    GetCryptoOnrampQuoteErrorType
+>;
+```
+
+#### UseCryptoOnrampStatusParameters
+
+Parameters accepted by [`useCryptoOnrampStatus`](#usecryptoonrampstatus) — TanStack Query options (`select`, `enabled`, `refetchInterval`, …) plus the deposit id, originating provider id and optional provider override forwarded to [`getCryptoOnrampStatus`](/ecosystem/appkit/reference/appkit#getcryptoonrampstatus).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `depositId` | `string` | Deposit id |
+| `providerId` | `string` | Identifier of the provider that issued this deposit |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseCryptoOnrampStatusReturnType
+
+Return type of [`useCryptoOnrampStatus`](#usecryptoonrampstatus) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseCryptoOnrampStatusReturnType = UseQueryReturnType<
+    selectData,
+    GetCryptoOnrampStatusErrorType
+>;
+```
+
+### Jettons
+
+#### UseJettonBalanceByAddressParameters
+
+Parameters accepted by [`useJettonBalanceByAddress`](#usejettonbalancebyaddress) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the jetton master, owner address, decimals and optional network override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `jettonAddress` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address (the token, not the user's wallet for it). |
+| `ownerAddress` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a></code> | Owner of the jetton wallet — typically the connected user's address. |
+| `jettonDecimals` | `number` | Decimals declared by the jetton master; used to format the raw balance into a human-readable string. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseJettonBalanceByAddressReturnType
+
+Return type of [`useJettonBalanceByAddress`](#usejettonbalancebyaddress) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseJettonBalanceByAddressReturnType = UseQueryReturnType<
+    selectData,
+    GetJettonBalanceErrorType
+>;
+```
+
+#### UseJettonInfoParameters
+
+Parameters accepted by [`useJettonInfo`](#usejettoninfo) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the jetton master address and optional network override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address whose metadata is being fetched. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseJettonInfoReturnType
+
+Return type of [`useJettonInfo`](#usejettoninfo) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions; `data` is `null` when the indexer has no record for that master address.
+
+```ts
+type UseJettonInfoReturnType = UseQueryReturnType<
+    selectData,
+    GetJettonInfoErrorType
+>;
+```
+
+#### UseJettonWalletAddressParameters
+
+Parameters accepted by [`useJettonWalletAddress`](#usejettonwalletaddress) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the jetton master, owner address and optional network override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `jettonAddress` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address. |
+| `ownerAddress` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a></code> | Owner whose jetton wallet should be derived. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseJettonWalletAddressReturnType
+
+Return type of [`useJettonWalletAddress`](#usejettonwalletaddress) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseJettonWalletAddressReturnType = UseQueryReturnType<
+    selectData,
+    GetJettonWalletAddressErrorType
+>;
+```
+
+#### UseJettonsByAddressParameters
+
+Parameters accepted by [`useJettonsByAddress`](#usejettonsbyaddress) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the owner address, optional network override and pagination.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](/ecosystem/appkit/reference/appkit#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `limit` | `number` | Maximum number of jettons to return. |
+| `offset` | `number` | Number of jettons to skip before returning results — used for pagination. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseJettonsByAddressReturnType
+
+Return type of [`useJettonsByAddress`](#usejettonsbyaddress) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseJettonsByAddressReturnType = UseQueryReturnType<
+    selectData,
+    GetJettonsErrorType
+>;
+```
+
+#### UseJettonsParameters
+
+Parameters accepted by [`useJettons`](#usejettons) — same shape as [`UseJettonsByAddressParameters`](#usejettonsbyaddressparameters); the hook resolves `address` from the selected wallet and overrides any value supplied here.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](/ecosystem/appkit/reference/appkit#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `limit` | `number` | Maximum number of jettons to return. |
+| `offset` | `number` | Number of jettons to skip before returning results — used for pagination. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseJettonsReturnType
+
+Return type of [`useJettons`](#usejettons) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseJettonsReturnType = UseJettonsByAddressReturnType<selectData>;
+```
+
+#### UseTransferJettonParameters
+
+Parameters accepted by [`useTransferJetton`](#usetransferjetton) — TanStack Query mutation options.
+
+```ts
+type UseTransferJettonParameters = TransferJettonOptions<context>;
+```
+
+#### UseTransferJettonReturnType
+
+Return type of [`useTransferJetton`](#usetransferjetton) — TanStack Query mutation result.
+
+```ts
+type UseTransferJettonReturnType = UseMutationReturnType<
+    TransferJettonData,
+    TransferJettonErrorType,
+    TransferJettonVariables,
+    context,
+    (
+        variables: TransferJettonVariables,
+        options?: MutateOptions<TransferJettonData, TransferJettonErrorType, TransferJettonVariables, context>,
+    ) => void,
+    MutateFunction<TransferJettonData, TransferJettonErrorType, TransferJettonVariables, context>
+>;
+```
+
+#### UseWatchJettonsByAddressParameters
+
+Parameters accepted by [`useWatchJettonsByAddress`](#usewatchjettonsbyaddress) — same fields as [`WatchJettonsByAddressOptions`](/ecosystem/appkit/reference/appkit#watchjettonsbyaddressoptions), all optional so callers can render the hook before the address is known.
+
+```ts
+type UseWatchJettonsByAddressParameters = Partial<WatchJettonsByAddressOptions>;
+```
+
+#### UseWatchJettonsParameters
+
+Parameters accepted by [`useWatchJettons`](#usewatchjettons) — update callback and optional network override; the hook resolves the address from the selected wallet.
+
+```ts
+type UseWatchJettonsParameters = Partial<WatchJettonsOptions>;
+```
+
+### NFTs
+
+#### NftItemProps
+
+Props accepted by [`NftItem`](#nftitem) — extends the native `<button>` props (`onClick`, `disabled`, `className`, …) with the NFT to render.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `nft`\* | <code><a href="/ecosystem/appkit/reference/appkit#nft">NFT</a></code> | NFT to render — name, collection name, image and on-sale state are derived via `getFormattedNftInfo`. |
+
+#### UseNFTsByAddressParameters
+
+Parameters accepted by [`useNftsByAddress`](#usenftsbyaddress) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the owner address, optional pagination (`limit`, `offset`) and network override.
+
+The `network` field defaults to the selected wallet's network; if no wallet is selected, falls back to AppKit's default network, or mainnet when none is set.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](/ecosystem/appkit/reference/appkit#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `limit` | `number` | Maximum number of NFTs to return. |
+| `offset` | `number` | Number of NFTs to skip before returning results — used for pagination. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseNFTsByAddressReturnType
+
+Return type of [`useNftsByAddress`](#usenftsbyaddress) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseNFTsByAddressReturnType = UseQueryReturnType<selectData, GetNFTsErrorType>;
+```
+
+#### UseNFTsParameters
+
+Parameters accepted by [`useNfts`](#usenfts) — same shape as [`UseNFTsByAddressParameters`](#usenftsbyaddressparameters); the hook resolves `address` from the selected wallet and overrides any value supplied here.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](/ecosystem/appkit/reference/appkit#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `limit` | `number` | Maximum number of NFTs to return. |
+| `offset` | `number` | Number of NFTs to skip before returning results — used for pagination. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseNFTsReturnType
+
+Return type of [`useNfts`](#usenfts) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseNFTsReturnType = UseNFTsByAddressReturnType<selectData>;
+```
+
+#### UseNftParameters
+
+Parameters accepted by [`useNft`](#usenft) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the NFT contract address and optional network override.
+
+The `network` field defaults to the selected wallet's network; if no wallet is selected, falls back to AppKit's default network, or mainnet when none is set.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | NFT contract address — pass a [`UserFriendlyAddress`](/ecosystem/appkit/reference/appkit#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseNftReturnType
+
+Return type of [`useNft`](#usenft) — TanStack Query result carrying `data` (the NFT or `null` when the indexer has no record), `isLoading`, `error` and the standard companions.
+
+```ts
+type UseNftReturnType = UseQueryReturnType<selectData, GetNftErrorType>;
+```
+
+#### UseTransferNftParameters
+
+Parameters accepted by [`useTransferNft`](#usetransfernft) — TanStack Query mutation options.
+
+```ts
+type UseTransferNftParameters = TransferNftOptions<context>;
+```
+
+#### UseTransferNftReturnType
+
+Return type of [`useTransferNft`](#usetransfernft) — TanStack Query mutation result.
+
+```ts
+type UseTransferNftReturnType = UseMutationReturnType<
+    TransferNftData,
+    TransferNftErrorType,
+    TransferNftVariables,
+    context,
+    (
+        variables: TransferNftVariables,
+        options?: MutateOptions<TransferNftData, TransferNftErrorType, TransferNftVariables, context>,
+    ) => void,
+    MutateFunction<TransferNftData, TransferNftErrorType, TransferNftVariables, context>
+>;
+```
+
+### Networks
+
+#### UseBlockNumberParameters
+
+Parameters accepted by [`useBlockNumber`](#useblocknumber) — TanStack Query options plus an optional network override. Defaults to the selected wallet's network; if no wallet is selected, falls back to mainnet.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network to query. Defaults to mainnet when omitted. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseBlockNumberReturnType
+
+Return type of [`useBlockNumber`](#useblocknumber) — TanStack Query result.
+
+```ts
+type UseBlockNumberReturnType = UseQueryReturnType<
+    selectData,
+    GetBlockNumberErrorType
+>;
+```
+
+#### UseDefaultNetworkReturnType
+
+Return type of [`useDefaultNetwork`](#usedefaultnetwork) — `[network, setNetwork]` tuple. `network` is the current default (or `undefined`); `setNetwork` calls [`setDefaultNetwork`](/ecosystem/appkit/reference/appkit#setdefaultnetwork) and emits `networks:default-changed`.
+
+```ts
+type UseDefaultNetworkReturnType = [
+    network: GetDefaultNetworkReturnType,
+    setNetwork: (network: Network | undefined) => void,
+];
+```
+
+#### UseNetworkReturnType
+
+Return type of [`useNetwork`](#usenetwork) — `undefined` when no wallet is currently selected.
+
+```ts
+type UseNetworkReturnType = Network | undefined;
+```
+
+#### UseNetworksReturnType
+
+Return type of [`useNetworks`](#usenetworks) — same shape as [`GetNetworksReturnType`](/ecosystem/appkit/reference/appkit#getnetworksreturntype).
+
+```ts
+type UseNetworksReturnType = GetNetworksReturnType;
+```
+
+### Settings
+
+#### AppKitTheme
+
+Theme value accepted by [`useAppKitTheme`](#useappkittheme) — `'light'`, `'dark'`, or any custom string mapped to a `data-ta-theme` token in the host's CSS.
+
+```ts
+type AppKitTheme = 'light' | 'dark' | string;
+```
+
+### Shared
+
+#### AmountPreset
+
+Single preset entry rendered as a button in [`AmountPresets`](#amountpresets).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `label`\* | `string` | Text shown inside the button (e.g., `"25%"`, `"Max"`, `"100"`). |
+| `amount`\* | `string` | Value passed to [`AmountPresetsProps.onPresetSelect`](#amountpresetsprops.onpresetselect) when the button is clicked. |
+| `onSelect` | `() => void` | Optional custom click handler — when set, it runs instead of `onPresetSelect`. |
+
+#### AmountPresetsProps
+
+Props accepted by [`AmountPresets`](#amountpresets).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `presets`\* | <code><a href="#amountpreset">AmountPreset</a>[]</code> | 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`. |
+
+#### CopyButtonProps
+
+Props accepted by [`CopyButton`](#copybutton).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Text written to the clipboard when the button is clicked. |
+| `aria-label`\* | `string` | Accessible label for screen readers. |
+
+#### CurrencyItemProps
+
+Props accepted by [`CurrencyItem`](#currencyitem) when used as a single-shot button. Passing `children` switches it into compound mode and bypasses these fields.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `ticker` | `string` | Token symbol (e.g., `"TON"`) — also used as the icon fallback and rendered in the secondary line. |
+| `name` | `string` | Human-readable token name shown as the primary line; falls back to `ticker` when absent. |
+| `balance` | `string` | Main balance value shown on the right side (already-formatted string). |
+| `underBalance` | `string` | Optional secondary value (e.g., fiat equivalent) shown beneath the main balance. |
+| `icon` | `string` | URL of the token logo. |
+| `isVerified` | `boolean` | When true, renders a verified checkmark badge next to the name. |
+
+#### CurrencySelectListContainerProps
+
+Props accepted by [`CurrencySelect.ListContainer`](#currencyselect.listcontainer).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `isEmpty`\* | `boolean` | When true, renders the built-in empty state instead of `children`. |
+
+#### CurrencySelectSearchProps
+
+Props accepted by [`CurrencySelect.Search`](#currencyselect.search).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `searchValue`\* | `string` | Current search query. |
+| `onSearchChange`\* | `(value: string) => void` | Called whenever the user types in the search input. |
+| `placeholder` | `string` | Placeholder text shown when the input is empty. |
+| `size` | `InputSize` | Size token applied to the input control(s) inside: `'s' | 'm' | 'l'`. Defaults to `'m'`. |
+| `variant` | `InputVariant` | Visual variant: `'default'` paints a filled field; `'unstyled'` drops the chrome. |
+| `loading` | `boolean` | When true, [`Input.Input`](#input.input) renders a skeleton placeholder instead of an `<input>`. |
+| `disabled` | `boolean` | When true, descendant input controls are disabled. |
+| `error` | `boolean` | When true, the field renders in error styling and [`Input.Caption`](#input.caption) switches to error text. |
+| `resizable` | `boolean` | When true, [`Input.Input`](#input.input) scales its font down to fit the available width as the user types. |
+
+#### LowBalanceModalProps
+
+Props accepted by [`LowBalanceModal`](#lowbalancemodal).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `open`\* | `boolean` | Controls visibility of the modal. |
+| `mode`\* | <code><a href="#lowbalancemode">LowBalanceMode</a></code> | `reduce` — user can fix it by reducing the amount (shows Change/Cancel). `topup`  — reducing doesn't help, user must top up TON (shows Close only). |
+| `requiredTon`\* | `string` | Required amount in TON, formatted as a decimal string (e.g. `"0.423"`). |
+| `onChange`\* | `() => void` | Called when the user clicks the primary "Change" action (only in `reduce` mode). |
+| `onCancel`\* | `() => void` | Called when the user dismisses the modal (Cancel, Close, or backdrop click). |
+
+#### LowBalanceMode
+
+Behavior mode for [`LowBalanceModal`](#lowbalancemodal) — see [`LowBalanceModalProps.mode`](#lowbalancemodalprops.mode).
+
+```ts
+type LowBalanceMode = 'reduce' | 'topup';
+```
+
+#### OptionSwitcherOption
+
+Single entry rendered as an item inside [`OptionSwitcher`](#optionswitcher).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Stable value passed back to [`OptionSwitcherProps.onChange`](#optionswitcherprops.onchange) when selected. |
+| `label`\* | `string` | Human-readable label shown in the trigger and dropdown item. |
+
+#### OptionSwitcherProps
+
+Props accepted by [`OptionSwitcher`](#optionswitcher).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string \| undefined` | Currently selected option value. |
+| `options`\* | <code><a href="#optionswitcheroption">OptionSwitcherOption</a>[]</code> | Available options. |
+| `onChange`\* | `(value: string) => void` | Called when the user picks an option. |
+| `disabled` | `boolean` | When true, the trigger is non-interactive and dimmed. |
+| `className` | `string` | Extra class applied to the trigger button. |
+
+#### SettingsButtonProps
+
+Props accepted by [`SettingsButton`](#settingsbutton) — extends the base [`Button`](#button) props.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onClick` | `() => void` | Click handler — typically used to open a settings modal. |
+| `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. |
+
+#### TokenBase
+
+Minimal shape every token in [`TokenSelectModal`](#tokenselectmodal) must satisfy. Callers may use richer types (e.g., `AppkitUIToken`) — `TokenBase` only fixes the fields the modal reads.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id`\* | `string` | Stable identifier used to match tokens against [`TokenSectionConfig.ids`](#tokensectionconfig.ids). |
+| `symbol`\* | `string` | Ticker (e.g., `"TON"`) — used for display and search matching. |
+| `name`\* | `string` | Human-readable name — used for display and search matching. |
+| `address`\* | `string` | Token contract address — used for exact-address search matching and as the React `key`. |
+| `logo` | `string` | Optional logo URL. |
+
+#### TokenSectionConfig
+
+Configuration that maps token `id`s to a named section in [`TokenSelectModal`](#tokenselectmodal); tokens not covered are placed in an "Other tokens" trailing section.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `title`\* | `string` | Section header label. |
+| `ids`\* | `string[]` | [`TokenBase.id`](#tokenbase.id) values to include in this section, in render order. |
+
+#### TokenSelectModalProps
+
+Props accepted by [`TokenSelectModal`](#tokenselectmodal).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `open`\* | `boolean` | Controls modal visibility. |
+| `onClose`\* | `() => void` | Called when the modal is dismissed (selection, backdrop click, or escape). |
+| `tokens`\* | `T = AppkitUIToken[]` | Full set of tokens available for selection and search. |
+| `tokenSections` | <code><a href="#tokensectionconfig">TokenSectionConfig</a>[]</code> | Optional sectioning rules; when omitted, all tokens render as a single untitled section. |
+| `onSelect`\* | `(token: T = AppkitUIToken) => void` | Called with the picked token; the modal closes and resets its search on selection. |
+| `title`\* | `string` | Modal header title. |
+| `searchPlaceholder` | `string` | Placeholder shown inside the search input. |
+
+#### TokenSelectorProps
+
+Props accepted by [`TokenSelector`](#tokenselector) — extends the base [`Button`](#button) props.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `title`\* | `string` | Label shown next to the icon — typically the token symbol. |
+| `icon` | `string` | Token logo URL. |
+| `iconFallback` | `string` | Single-character fallback used when `icon` fails to load; defaults to the first character of `title`. |
+| `networkIcon` | `string` | When provided, renders a network badge overlay on the icon. |
+| `readOnly` | `boolean` | Hide chevron and suppress click handling — use when there's nothing to pick. |
+| `size` | `ButtonSize` | Size class applied to the button. Pass `'unset'` to skip the size class entirely (no padding, no typography) — useful with `variant="unstyled"`. |
+| `borderRadius` | `ButtonBorderRadius` | Border radius token; defaults to a size-dependent value (`s` → `2xl`, `m` → `l`, `l` → `xl`). |
+| `variant` | `ButtonVariant` | Visual variant. Use `'unstyled'` to opt out of all built-in styling — the consumer is fully responsible for visuals via `className`. The Button still provides ref forwarding, `disabled`/`loading` plumbing, and `icon`/`children` rendering. |
+| `loading` | `boolean` | When true, renders a spinner instead of `icon`/`children` and disables the button. |
+| `fullWidth` | `boolean` | When true, the button stretches to fill its container width. |
+
+### Signing
+
+#### UseSignBinaryParameters
+
+Parameters accepted by [`useSignBinary`](#usesignbinary) — TanStack Query mutation options.
+
+```ts
+type UseSignBinaryParameters = SignBinaryOptions<context>;
+```
+
+#### UseSignBinaryReturnType
+
+Return type of [`useSignBinary`](#usesignbinary) — TanStack Query mutation result.
+
+```ts
+type UseSignBinaryReturnType = UseMutationResult<
+    SignBinaryData,
+    SignBinaryErrorType,
+    SignBinaryVariables,
+    context
+>;
+```
+
+#### UseSignCellParameters
+
+Parameters accepted by [`useSignCell`](#usesigncell) — TanStack Query mutation options.
+
+```ts
+type UseSignCellParameters = SignCellOptions<context>;
+```
+
+#### UseSignCellReturnType
+
+Return type of [`useSignCell`](#usesigncell) — TanStack Query mutation result.
+
+```ts
+type UseSignCellReturnType = UseMutationResult<
+    SignCellData,
+    SignCellErrorType,
+    SignCellVariables,
+    context
+>;
+```
+
+#### UseSignTextParameters
+
+Parameters accepted by [`useSignText`](#usesigntext) — TanStack Query mutation options.
+
+```ts
+type UseSignTextParameters = SignTextOptions<context>;
+```
+
+#### UseSignTextReturnType
+
+Return type of [`useSignText`](#usesigntext) — TanStack Query mutation result.
+
+```ts
+type UseSignTextReturnType = UseMutationResult<
+    SignTextData,
+    SignTextErrorType,
+    SignTextVariables,
+    context
+>;
+```
+
+### Staking
+
+#### SelectUnstakeModeProps
+
+Props accepted by [`SelectUnstakeMode`](#selectunstakemode).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value`\* | <code><a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a></code> | Currently selected unstake mode (see [`UnstakeMode`](/ecosystem/appkit/reference/appkit#unstakemode)). |
+| `onValueChange`\* | <code>(mode: <a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a>) =&gt; void</code> | Called when the user picks a different mode. |
+| `providerInfo`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingproviderinfo">StakingProviderInfo</a> \| undefined</code> | Dynamic provider info — used to show the instant-unstake limit when available. |
+| `providerMetadata`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> | Static provider metadata — supplies `supportedUnstakeModes` and stake-token formatting. |
+
+#### StakingBalanceBlockProps
+
+Props accepted by [`StakingBalanceBlock`](#stakingbalanceblock).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `providerMetadata`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> | Provider metadata — supplies the stake/receive tokens (address, ticker, decimals). |
+| `direction`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a></code> | Operation direction; selects which token and balance to render. |
+| `stakedBalance` | `string` | User's currently staked amount, used when `direction === 'unstake'`. |
+| `isStakedBalanceLoading` | `boolean` | True while the staked balance is being fetched. |
+| `balance` | `string` | User's wallet balance of the stake token, used when `direction === 'stake'`. |
+| `isBalanceLoading` | `boolean` | True while the wallet balance is being fetched. |
+| `onMaxClick` | `() => void` | When provided, renders a `MAX` button that invokes this callback. |
+
+#### StakingContextType
+
+Shape of the staking context exposed by [`StakingWidgetProvider`](#stakingwidgetprovider) and read via [`useStakingContext`](#usestakingcontext). Aggregates inputs (amount, direction, unstake mode), fetched data (balances, quote, provider info/metadata), derived flags (`canSubmit`, `error`, loading states), and the actions used by [`StakingWidgetUI`](#stakingwidgetui) (send transaction, switch provider, max, low-balance handling).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `amount`\* | `string` | Amount the user wants to stake (string to preserve input UX) |
+| `canSubmit`\* | `boolean` | Whether the user can proceed with staking (checks balance, amount validity, etc.) |
+| `quote`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquote">StakingQuote</a> \| undefined</code> | Raw staking quote from the provider |
+| `isQuoteLoading`\* | `boolean` | True while the stake quote is being fetched |
+| `error`\* | `string \| null` | Current validation/fetch error for staking, null when everything is ok |
+| `providerInfo`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingproviderinfo">StakingProviderInfo</a> \| undefined</code> | Staking provider dynamic info (APY, instant unstake availability, etc.) |
+| `providerMetadata`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> | Staking provider static metadata |
+| `stakingProvider`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a> \| undefined</code> | Currently selected staking provider (defaults to the first registered one) |
+| `stakingProviders`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a>[]</code> | All registered staking providers |
+| `setStakingProviderId`\* | `(providerId: string) => void` | Updates the selected staking provider |
+| `network`\* | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a> \| undefined</code> | Network the widget is operating on (resolved from prop or wallet) |
+| `direction`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a></code> | Current operation direction: 'stake' or 'unstake' |
+| `isProviderInfoLoading`\* | `boolean` | True while provider info is being fetched |
+| `balance`\* | `string \| undefined` | Base balance (native or jetton) available for staking |
+| `isBalanceLoading`\* | `boolean` | True while base balance is being fetched |
+| `stakedBalance`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingbalance">StakingBalance</a> \| undefined</code> | User's currently staked balance |
+| `isStakedBalanceLoading`\* | `boolean` | True while staked balance is being fetched |
+| `unstakeMode`\* | <code><a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a></code> | Selected unstake mode (e.g. instant or delayed) |
+| `setAmount`\* | `(amount: string) => void` | Sets the input amount |
+| `setUnstakeMode`\* | <code>(mode: <a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a>) =&gt; void</code> | Sets the unstake mode |
+| `sendTransaction`\* | `() => Promise<void>` | Triggers the staking/unstaking transaction |
+| `onChangeDirection`\* | <code>(direction: <a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a>) =&gt; void</code> | Changes the direction (stake/unstake) |
+| `isSendingTransaction`\* | `boolean` | True while a transaction is being processed |
+| `isReversed`\* | `boolean` | True if the user is inputting the output amount ("I want to get X") |
+| `toggleReversed`\* | `() => void` | Toggles between inputting from amount and output amount |
+| `reversedAmount`\* | `string` | Amount displayed in the reversed (bottom) input |
+| `onMaxClick`\* | `() => void` | Sets the input amount to the maximum available balance (leaves room for TON gas on native stake) |
+| `isLowBalanceWarningOpen`\* | `boolean` | True when the built transaction outflow exceeds the user's TON balance |
+| `lowBalanceMode`\* | `'reduce' \| 'topup'` | `reduce` when the outgoing token is TON (user can fix by changing amount), `topup` otherwise. |
+| `lowBalanceRequiredTon`\* | `string` | Required TON amount for the pending operation, formatted as a decimal string. Empty when no pending op. |
+| `onLowBalanceChange`\* | `() => void` | Replace the input with a value that fits into the current TON balance and close the warning |
+| `onLowBalanceCancel`\* | `() => void` | Dismiss the low-balance warning without changing the input |
+
+#### StakingInfoProps
+
+Props accepted by [`StakingInfo`](#stakinginfo).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `quote`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquote">StakingQuote</a> \| undefined</code> | Current staking quote — its `amountOut` is rendered in the "You get" row. |
+| `isQuoteLoading`\* | `boolean` | True while the quote is being fetched; swaps the "You get" value for a skeleton. |
+| `providerInfo`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingproviderinfo">StakingProviderInfo</a> \| undefined</code> | Dynamic provider info — supplies APY and exchange rate. |
+| `providerMetadata`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> | Static provider metadata — supplies token tickers/decimals and the provider name. |
+| `isProviderInfoLoading`\* | `boolean` | True while provider info is being fetched. |
+| `direction` | <code><a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a></code> | Operation direction — controls which token's decimals/ticker label the "You get" amount. Defaults to `'stake'`. |
+
+#### StakingProviderProps
+
+Props accepted by [`StakingWidgetProvider`](#stakingwidgetprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used for quote fetching, balance reads, and transactions. Falls back to the connected wallet's network when omitted. |
+
+#### StakingSettingsModalProps
+
+Props accepted by [`StakingSettingsModal`](#stakingsettingsmodal).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `open`\* | `boolean` | Controls modal visibility. |
+| `onClose`\* | `() => void` | Called when the user dismisses the modal or after a successful save. |
+| `provider`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a> \| undefined</code> | Currently active staking provider — used to preselect the option when the modal opens. |
+| `providers`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a>[]</code> | All registered staking providers to choose from. |
+| `onProviderChange`\* | `(providerId: string) => void` | Invoked with the chosen `providerId` when the user saves a different selection. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used to resolve each provider's display name via its metadata. |
+
+#### StakingWidgetProps
+
+Props accepted by [`StakingWidget`](#stakingwidget). Extends [`StakingProviderProps`](#stakingproviderprops) (e.g. `network`) and standard `<div>` props forwarded to the default UI.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `children` | <code>(props: <a href="#stakingwidgetrenderprops">StakingWidgetRenderProps</a>) =&gt; ReactNode</code> | Optional render-prop. When provided, the default [`StakingWidgetUI`](#stakingwidgetui) is bypassed and this function is called with the full [`StakingWidgetRenderProps`](#stakingwidgetrenderprops) (context state + forwarded `<div>` props), letting consumers build a custom UI on top of the widget's internal logic. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used for quote fetching, balance reads, and transactions. Falls back to the connected wallet's network when omitted. |
+
+#### StakingWidgetRenderProps
+
+Props accepted by [`StakingWidgetUI`](#stakingwidgetui) (also the argument type for the `StakingWidget` render-prop). Combines the full [`StakingContextType`](#stakingcontexttype) with standard `<div>` props forwarded to the outer wrapper.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `amount`\* | `string` | Amount the user wants to stake (string to preserve input UX) |
+| `canSubmit`\* | `boolean` | Whether the user can proceed with staking (checks balance, amount validity, etc.) |
+| `quote`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquote">StakingQuote</a> \| undefined</code> | Raw staking quote from the provider |
+| `isQuoteLoading`\* | `boolean` | True while the stake quote is being fetched |
+| `error`\* | `string \| null` | Current validation/fetch error for staking, null when everything is ok |
+| `providerInfo`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingproviderinfo">StakingProviderInfo</a> \| undefined</code> | Staking provider dynamic info (APY, instant unstake availability, etc.) |
+| `providerMetadata`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> | Staking provider static metadata |
+| `stakingProvider`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a> \| undefined</code> | Currently selected staking provider (defaults to the first registered one) |
+| `stakingProviders`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a>[]</code> | All registered staking providers |
+| `setStakingProviderId`\* | `(providerId: string) => void` | Updates the selected staking provider |
+| `network`\* | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a> \| undefined</code> | Network the widget is operating on (resolved from prop or wallet) |
+| `direction`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a></code> | Current operation direction: 'stake' or 'unstake' |
+| `isProviderInfoLoading`\* | `boolean` | True while provider info is being fetched |
+| `balance`\* | `string \| undefined` | Base balance (native or jetton) available for staking |
+| `isBalanceLoading`\* | `boolean` | True while base balance is being fetched |
+| `stakedBalance`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingbalance">StakingBalance</a> \| undefined</code> | User's currently staked balance |
+| `isStakedBalanceLoading`\* | `boolean` | True while staked balance is being fetched |
+| `unstakeMode`\* | <code><a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a></code> | Selected unstake mode (e.g. instant or delayed) |
+| `setAmount`\* | `(amount: string) => void` | Sets the input amount |
+| `setUnstakeMode`\* | <code>(mode: <a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a>) =&gt; void</code> | Sets the unstake mode |
+| `sendTransaction`\* | `() => Promise<void>` | Triggers the staking/unstaking transaction |
+| `onChangeDirection`\* | <code>(direction: <a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a>) =&gt; void</code> | Changes the direction (stake/unstake) |
+| `isSendingTransaction`\* | `boolean` | True while a transaction is being processed |
+| `isReversed`\* | `boolean` | True if the user is inputting the output amount ("I want to get X") |
+| `toggleReversed`\* | `() => void` | Toggles between inputting from amount and output amount |
+| `reversedAmount`\* | `string` | Amount displayed in the reversed (bottom) input |
+| `onMaxClick`\* | `() => void` | Sets the input amount to the maximum available balance (leaves room for TON gas on native stake) |
+| `isLowBalanceWarningOpen`\* | `boolean` | True when the built transaction outflow exceeds the user's TON balance |
+| `lowBalanceMode`\* | `'reduce' \| 'topup'` | `reduce` when the outgoing token is TON (user can fix by changing amount), `topup` otherwise. |
+| `lowBalanceRequiredTon`\* | `string` | Required TON amount for the pending operation, formatted as a decimal string. Empty when no pending op. |
+| `onLowBalanceChange`\* | `() => void` | Replace the input with a value that fits into the current TON balance and close the warning |
+| `onLowBalanceCancel`\* | `() => void` | Dismiss the low-balance warning without changing the input |
+
+#### UseBuildStakeTransactionReturnType
+
+Return type of [`useBuildStakeTransaction`](#usebuildstaketransaction) — TanStack Query mutation result that resolves to a [`TransactionRequest`](/ecosystem/appkit/reference/appkit#transactionrequest).
+
+```ts
+type UseBuildStakeTransactionReturnType = UseMutationResult<
+    BuildStakeTransactionData,
+    BuildStakeTransactionErrorType,
+    BuildStakeTransactionVariables,
+    context
+>;
+```
+
+#### UseStakedBalanceParameters
+
+Parameters accepted by [`useStakedBalance`](#usestakedbalance) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the owner address, optional network override and optional `providerId`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `userAddress` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a></code> | Owner whose staked balance should be read. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `providerId` | `string` | Provider to query; defaults to the registered default staking provider. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseStakedBalanceReturnType
+
+Return type of [`useStakedBalance`](#usestakedbalance) — TanStack Query result carrying the user's staked balance.
+
+```ts
+type UseStakedBalanceReturnType = UseQueryReturnType<
+    selectData,
+    GetStakedBalanceErrorType
+>;
+```
+
+#### UseStakingProviderInfoParameters
+
+Parameters accepted by [`useStakingProviderInfo`](#usestakingproviderinfo) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus an optional `providerId` and network override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `providerId` | `string` | Provider to query; defaults to the registered default staking provider. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseStakingProviderInfoReturnType
+
+Return type of [`useStakingProviderInfo`](#usestakingproviderinfo) — TanStack Query result carrying live [`StakingProviderInfo`](/ecosystem/appkit/reference/appkit#stakingproviderinfo).
+
+```ts
+type UseStakingProviderInfoReturnType = UseQueryReturnType<
+    selectData,
+    GetStakingProviderInfoErrorType
+>;
+```
+
+#### UseStakingProviderMetadataParameters
+
+Parameters accepted by [`useStakingProviderMetadata`](#usestakingprovidermetadata) — optional `providerId` and network override.
+
+```ts
+type UseStakingProviderMetadataParameters = GetStakingProviderMetadataOptions;
+```
+
+#### UseStakingProviderMetadataReturnType
+
+Return type of [`useStakingProviderMetadata`](#usestakingprovidermetadata) — static [`StakingProviderMetadata`](/ecosystem/appkit/reference/appkit#stakingprovidermetadata) for the resolved provider, or `undefined` when no provider matches and no default is registered (the hook swallows the throw from [`getStakingProviderMetadata`](/ecosystem/appkit/reference/appkit#getstakingprovidermetadata)).
+
+```ts
+type UseStakingProviderMetadataReturnType = GetStakingProviderMetadataReturnType | undefined;
+```
+
+#### UseStakingProviderReturnType
+
+Return type of [`useStakingProvider`](#usestakingprovider) — the matching staking provider, or `undefined` when none resolves (the hook swallows the throw from [`getStakingProvider`](/ecosystem/appkit/reference/appkit#getstakingprovider)).
+
+```ts
+type UseStakingProviderReturnType = GetStakingProviderReturnType | undefined;
+```
+
+#### UseStakingProvidersReturnType
+
+Return type of [`useStakingProviders`](#usestakingproviders) — array of registered staking providers.
+
+```ts
+type UseStakingProvidersReturnType = GetStakingProvidersReturnType;
+```
+
+#### UseStakingQuoteParameters
+
+Parameters accepted by [`useStakingQuote`](#usestakingquote) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus stake/unstake amount, direction, target asset and optional `providerId`/network override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `direction` | <code><a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a></code> | Direction of the quote (stake or unstake) |
+| `amount` | `string` | Amount of tokens to stake or unstake |
+| `userAddress` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the user |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network on which the staking will be executed |
+| `unstakeMode` | <code><a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a></code> | Requested mode of unstaking |
+| `isReversed` | `boolean` | If true, for unstake requests the amount is specified in the staking coin (e.g. TON) instead of the Liquid Staking Token (e.g. tsTON). |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `providerId` | `string` | Provider to quote against; defaults to the registered default staking provider. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseStakingQuoteReturnType
+
+Return type of [`useStakingQuote`](#usestakingquote) — TanStack Query result carrying a [`StakingQuote`](/ecosystem/appkit/reference/appkit#stakingquote).
+
+```ts
+type UseStakingQuoteReturnType = UseQueryReturnType<
+    selectData,
+    GetStakingQuoteErrorType
+>;
+```
+
+### Swap
+
+#### SwapContextType
+
+Shape of the value exposed by [`useSwapContext`](#useswapcontext). Holds the selected source/target tokens, the entered amount and the latest quote, balance readouts, validation state, slippage / provider settings, and the callbacks needed to mutate them or to submit the swap transaction.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `tokens`\* | `AppkitUIToken[]` | Full list of available tokens for swapping |
+| `tokenSections` | <code><a href="#tokensectionconfig">TokenSectionConfig</a>[]</code> | Optional section configs for grouping tokens in the selector |
+| `fromToken`\* | `AppkitUIToken \| null` | Currently selected source token |
+| `toToken`\* | `AppkitUIToken \| null` | Currently selected target token |
+| `fromAmount`\* | `string` | Amount the user wants to swap (string to preserve input UX) |
+| `toAmount`\* | `string` | Calculated receive amount from the current quote |
+| `fiatSymbol`\* | `string` | Fiat currency symbol for price display, e.g. "$" |
+| `fromBalance`\* | `string \| undefined` | User's balance of the "from" token |
+| `toBalance`\* | `string \| undefined` | User's balance of the "to" token |
+| `isFromBalanceLoading`\* | `boolean` | True while the "from" balance is being fetched |
+| `isToBalanceLoading`\* | `boolean` | True while the "to" balance is being fetched |
+| `canSubmit`\* | `boolean` | Whether the user can proceed with the swap (checks balance, amount, quote) |
+| `quote`\* | `GetSwapQuoteData \| undefined` | Raw swap quote from the provider |
+| `isQuoteLoading`\* | `boolean` | True while the quote is being fetched from the API |
+| `error`\* | `string \| null` | Current validation or fetch error, null when everything is ok |
+| `slippage`\* | `number` | Slippage tolerance in basis points (100 = 1%) |
+| `swapProvider`\* | <code><a href="/ecosystem/appkit/reference/appkit#swapprovider">SwapProvider</a> \| undefined</code> | Currently selected swap provider (defaults to the first registered one) |
+| `swapProviders`\* | <code><a href="/ecosystem/appkit/reference/appkit#swapprovider">SwapProvider</a>[]</code> | All registered swap providers |
+| `setSwapProviderId`\* | `(providerId: string) => void` | Updates the selected swap provider |
+| `setFromToken`\* | `(token: AppkitUIToken) => void` | Updates the source token |
+| `setToToken`\* | `(token: AppkitUIToken) => void` | Updates the target token |
+| `setFromAmount`\* | `(amount: string) => void` | Updates the swap amount |
+| `setSlippage`\* | `(slippage: number) => void` | Updates the slippage tolerance |
+| `onFlip`\* | `() => void` | Swaps source and target tokens |
+| `onMaxClick`\* | `() => void` | Sets the "from" amount to the maximum available balance |
+| `sendSwapTransaction`\* | `() => Promise<void>` | Executes the swap transaction |
+| `isSendingTransaction`\* | `boolean` | True while a transaction is being built or sent |
+| `isLowBalanceWarningOpen`\* | `boolean` | True when the built transaction outflow exceeds the user's TON balance |
+| `lowBalanceMode`\* | `'reduce' \| 'topup'` | `reduce` when the outgoing token is TON (user can fix by changing amount), `topup` otherwise. |
+| `lowBalanceRequiredTon`\* | `string` | Required TON amount for the pending operation, formatted as a decimal string. Empty when no pending op. |
+| `onLowBalanceChange`\* | `() => void` | Replace the input with a value that fits into the current TON balance and close the warning |
+| `onLowBalanceCancel`\* | `() => void` | Dismiss the low-balance warning without changing the input |
+
+#### SwapFieldProps
+
+Props accepted by [`SwapField`](#swapfield) — a single source/target row inside the swap widget that hosts the amount input, token picker trigger, fiat conversion and balance line.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `type`\* | `'pay' \| 'receive'` | `pay` renders the editable source row with a "max" shortcut; `receive` renders the read-only target row. |
+| `amount`\* | `string` | Current amount shown in the input as a human-readable decimal string. |
+| `fiatSymbol` | `string` | Fiat currency symbol displayed in front of the converted value. Defaults to `"$"`. |
+| `token` | `AppkitUIToken` | Currently selected token; controls the token selector label, balance formatting and fiat conversion. |
+| `onAmountChange` | `(value: string) => void` | Called with the raw input value when the user edits the amount. Only fired for `type: "pay"`. |
+| `balance` | `string` | Formatted balance of `token` for the active wallet, as a human-readable decimal string; rendered in the balance line beneath the input. |
+| `isBalanceLoading` | `boolean` | When true, the balance area renders a skeleton placeholder instead of the value. |
+| `loading` | `boolean` | When true, the underlying input renders its loading state — used while a fresh quote is in flight. |
+| `onMaxClick` | `() => void` | Called when the user clicks the "max" shortcut to fill the maximum spendable amount. |
+| `onTokenSelectorClick` | `() => void` | Called when the user clicks the token selector chip — typically opens a `SwapTokenSelectModal`. |
+| `isWalletConnected` | `boolean` | Reserved flag indicating whether a wallet is connected — currently accepted for API symmetry. |
+| `size` | `InputSize` | Size token applied to the input control(s) inside: `'s' | 'm' | 'l'`. Defaults to `'m'`. |
+| `variant` | `InputVariant` | Visual variant: `'default'` paints a filled field; `'unstyled'` drops the chrome. |
+| `disabled` | `boolean` | When true, descendant input controls are disabled. |
+| `error` | `boolean` | When true, the field renders in error styling and [`Input.Caption`](#input.caption) switches to error text. |
+| `resizable` | `boolean` | When true, [`Input.Input`](#input.input) scales its font down to fit the available width as the user types. |
+
+#### SwapFlipButtonProps
+
+Props accepted by [`SwapFlipButton`](#swapflipbutton) — the round button placed between the two [`SwapField`](#swapfield) rows that swaps the source and target tokens.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onClick` | `() => void` | Called when the user clicks the button. Wire this to a handler that swaps the source/target tokens (e.g. `onFlip` from the swap context). |
+| `rotated` | `boolean` | When true, the icon is drawn in its rotated state — used to animate between flips. |
+
+#### SwapInfoProps
+
+Props accepted by [`SwapInfo`](#swapinfo) — the summary block under the swap form that surfaces minimum received, slippage and the chosen provider.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `toToken`\* | `AppkitUIToken \| null` | Target token the user is receiving; used to format `minReceived` with the right decimals and symbol. |
+| `slippage`\* | `number` | Slippage tolerance in basis points (`100` = 1%). Rendered as a percentage. |
+| `provider` | <code><a href="/ecosystem/appkit/reference/appkit#swapprovider">SwapProvider</a></code> | Current [`SwapProvider`](/ecosystem/appkit/reference/appkit#swapprovider); its display name is shown in the provider row. |
+| `quote` | <code><a href="/ecosystem/appkit/reference/appkit#swapquote">SwapQuote</a></code> | Quote whose `minReceived` value is displayed; when undefined the value falls back to `0` (still suffixed with the token symbol). |
+| `isQuoteLoading` | `boolean` | When true, the minimum-received value renders a skeleton placeholder instead of the formatted number. |
+
+#### SwapProviderProps
+
+Props accepted by [`SwapWidgetProvider`](#swapwidgetprovider) — the inputs that configure the swap flow (token universe, network override, defaults).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `tokens`\* | `AppkitUIToken[]` | Full list of tokens available for swapping in the UI. Filtered to the active network internally. |
+| `tokenSections` | <code><a href="#tokensectionconfig">TokenSectionConfig</a>[]</code> | Optional section configs for grouping tokens inside the `SwapTokenSelectModal`. |
+| `defaultFromSymbol` | `string` | Symbol of the token pre-selected as the source on first mount (e.g. `"TON"`). |
+| `defaultToSymbol` | `string` | Symbol of the token pre-selected as the target on first mount. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used for quote fetching and balance reads. When omitted, falls back to the selected wallet's network via [`useNetwork`](#usenetwork). |
+| `fiatSymbol` | `string` | Fiat currency symbol displayed next to converted amounts. Defaults to `"$"`. |
+| `defaultSlippage` | `number` | Initial slippage tolerance in basis points (`100` = 1%). Defaults to `100`. |
+
+#### SwapWidgetProps
+
+Props accepted by [`SwapWidget`](#swapwidget) — extend [`SwapProviderProps`](#swapproviderprops) (swap configuration: tokens, network, defaults) with the standard `<div>` attributes and an optional render-prop override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `children` | <code>(props: <a href="#swapwidgetrenderprops">SwapWidgetRenderProps</a>) =&gt; ReactNode</code> | Optional render-prop receiving the full swap context plus the forwarded `<div>` props; when supplied it replaces the default [`SwapWidgetUI`](#swapwidgetui). |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used for quote fetching and balance reads. When omitted, falls back to the selected wallet's network via [`useNetwork`](#usenetwork). |
+| `tokens`\* | `AppkitUIToken[]` | Full list of tokens available for swapping in the UI. Filtered to the active network internally. |
+| `tokenSections` | <code><a href="#tokensectionconfig">TokenSectionConfig</a>[]</code> | Optional section configs for grouping tokens inside the `SwapTokenSelectModal`. |
+| `defaultFromSymbol` | `string` | Symbol of the token pre-selected as the source on first mount (e.g. `"TON"`). |
+| `defaultToSymbol` | `string` | Symbol of the token pre-selected as the target on first mount. |
+| `fiatSymbol` | `string` | Fiat currency symbol displayed next to converted amounts. Defaults to `"$"`. |
+| `defaultSlippage` | `number` | Initial slippage tolerance in basis points (`100` = 1%). Defaults to `100`. |
+
+#### SwapWidgetRenderProps
+
+Props accepted by [`SwapWidgetUI`](#swapwidgetui) (and the `children` render-prop on [`SwapWidget`](#swapwidget)). Combines the full [`SwapContextType`](#swapcontexttype) with the standard `<div>` attributes forwarded to the wrapper element.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `tokens`\* | `AppkitUIToken[]` | Full list of available tokens for swapping |
+| `tokenSections` | <code><a href="#tokensectionconfig">TokenSectionConfig</a>[]</code> | Optional section configs for grouping tokens in the selector |
+| `fromToken`\* | `AppkitUIToken \| null` | Currently selected source token |
+| `toToken`\* | `AppkitUIToken \| null` | Currently selected target token |
+| `fromAmount`\* | `string` | Amount the user wants to swap (string to preserve input UX) |
+| `toAmount`\* | `string` | Calculated receive amount from the current quote |
+| `fiatSymbol`\* | `string` | Fiat currency symbol for price display, e.g. "$" |
+| `fromBalance`\* | `string \| undefined` | User's balance of the "from" token |
+| `toBalance`\* | `string \| undefined` | User's balance of the "to" token |
+| `isFromBalanceLoading`\* | `boolean` | True while the "from" balance is being fetched |
+| `isToBalanceLoading`\* | `boolean` | True while the "to" balance is being fetched |
+| `canSubmit`\* | `boolean` | Whether the user can proceed with the swap (checks balance, amount, quote) |
+| `quote`\* | `GetSwapQuoteData \| undefined` | Raw swap quote from the provider |
+| `isQuoteLoading`\* | `boolean` | True while the quote is being fetched from the API |
+| `error`\* | `string \| null` | Current validation or fetch error, null when everything is ok |
+| `slippage`\* | `number` | Slippage tolerance in basis points (100 = 1%) |
+| `swapProvider`\* | <code><a href="/ecosystem/appkit/reference/appkit#swapprovider">SwapProvider</a> \| undefined</code> | Currently selected swap provider (defaults to the first registered one) |
+| `swapProviders`\* | <code><a href="/ecosystem/appkit/reference/appkit#swapprovider">SwapProvider</a>[]</code> | All registered swap providers |
+| `setSwapProviderId`\* | `(providerId: string) => void` | Updates the selected swap provider |
+| `setFromToken`\* | `(token: AppkitUIToken) => void` | Updates the source token |
+| `setToToken`\* | `(token: AppkitUIToken) => void` | Updates the target token |
+| `setFromAmount`\* | `(amount: string) => void` | Updates the swap amount |
+| `setSlippage`\* | `(slippage: number) => void` | Updates the slippage tolerance |
+| `onFlip`\* | `() => void` | Swaps source and target tokens |
+| `onMaxClick`\* | `() => void` | Sets the "from" amount to the maximum available balance |
+| `sendSwapTransaction`\* | `() => Promise<void>` | Executes the swap transaction |
+| `isSendingTransaction`\* | `boolean` | True while a transaction is being built or sent |
+| `isLowBalanceWarningOpen`\* | `boolean` | True when the built transaction outflow exceeds the user's TON balance |
+| `lowBalanceMode`\* | `'reduce' \| 'topup'` | `reduce` when the outgoing token is TON (user can fix by changing amount), `topup` otherwise. |
+| `lowBalanceRequiredTon`\* | `string` | Required TON amount for the pending operation, formatted as a decimal string. Empty when no pending op. |
+| `onLowBalanceChange`\* | `() => void` | Replace the input with a value that fits into the current TON balance and close the warning |
+| `onLowBalanceCancel`\* | `() => void` | Dismiss the low-balance warning without changing the input |
+
+#### UseBuildSwapTransactionParameters
+
+Parameters accepted by [`useBuildSwapTransaction`](#usebuildswaptransaction) — TanStack Query mutation options.
+
+```ts
+type UseBuildSwapTransactionParameters = BuildSwapTransactionMutationOptions<context>;
+```
+
+#### UseBuildSwapTransactionReturnType
+
+Return type of [`useBuildSwapTransaction`](#usebuildswaptransaction) — TanStack Query mutation result.
+
+```ts
+type UseBuildSwapTransactionReturnType = UseMutationResult<
+    BuildSwapTransactionData,
+    BuildSwapTransactionErrorType,
+    BuildSwapTransactionVariables,
+    context
+>;
+```
+
+#### UseSwapProviderReturnType
+
+Return type of [`useSwapProvider`](#useswapprovider) — `[provider, setProviderId]` tuple. `provider` is the default `SwapProviderInterface` (or `undefined` when none is registered); `setProviderId` calls [`setDefaultSwapProvider`](/ecosystem/appkit/reference/appkit#setdefaultswapprovider) and emits `provider:default-changed`, which [`watchSwapProviders`](/ecosystem/appkit/reference/appkit#watchswapproviders) picks up.
+
+```ts
+type UseSwapProviderReturnType = readonly [GetSwapProviderReturnType | undefined, (providerId: string) => void];
+```
+
+#### UseSwapProvidersReturnType
+
+Return type of [`useSwapProviders`](#useswapproviders) — array of every `SwapProviderInterface` currently registered on the AppKit instance.
+
+```ts
+type UseSwapProvidersReturnType = GetSwapProvidersReturnType;
+```
+
+#### UseSwapQuoteParameters
+
+Parameters accepted by [`useSwapQuote`](#useswapquote) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the [`SwapQuoteParams`](/ecosystem/appkit/reference/appkit#swapquoteparams) fields (source/target tokens, amount, `isReverseSwap` flag) and an optional `providerId` / network override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `amount` | `string` | Amount of tokens to swap (incoming or outgoing depending on isReverseSwap) |
+| `from` | <code><a href="/ecosystem/appkit/reference/appkit#swaptoken">SwapToken</a></code> | Token to swap from |
+| `to` | <code><a href="/ecosystem/appkit/reference/appkit#swaptoken">SwapToken</a></code> | Token to swap to |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network on which the swap will be executed |
+| `slippageBps` | `number` | Slippage tolerance in basis points (1 bp = 0.01%) |
+| `maxOutgoingMessages` | `number` | Maximum number of outgoing messages |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `isReverseSwap` | `boolean` | If true, amount is the amount to receive (buy). If false, amount is the amount to spend (sell). |
+| `providerId` | `string` | Provider to quote against; defaults to the registered default swap provider. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseSwapQuoteReturnType
+
+Return type of [`useSwapQuote`](#useswapquote) — TanStack Query result carrying `data` ([`SwapQuote`](/ecosystem/appkit/reference/appkit#swapquote)), `isLoading`, `error` and the standard companions.
+
+```ts
+type UseSwapQuoteReturnType = UseQueryReturnType<
+    selectData,
+    GetSwapQuoteErrorType
+>;
+```
+
+### Transactions
+
+#### UseSendTransactionParameters
+
+Parameters accepted by [`useSendTransaction`](#usesendtransaction) — TanStack Query mutation options.
+
+```ts
+type UseSendTransactionParameters = SendTransactionOptions<context>;
+```
+
+#### UseSendTransactionReturnType
+
+Return type of [`useSendTransaction`](#usesendtransaction) — TanStack Query mutation result.
+
+```ts
+type UseSendTransactionReturnType = UseMutationReturnType<
+    SendTransactionData,
+    SendTransactionErrorType,
+    SendTransactionVariables,
+    context,
+    (
+        variables: SendTransactionVariables,
+        options?: MutateOptions<SendTransactionData, SendTransactionErrorType, SendTransactionVariables, context>,
+    ) => void,
+    MutateFunction<SendTransactionData, SendTransactionErrorType, SendTransactionVariables, context>
+>;
+```
+
+#### UseTransactionStatusParameters
+
+Parameters accepted by [`useTransactionStatus`](#usetransactionstatus) — `boc` xor `normalizedHash` plus optional network and TanStack Query overrides; pair with `query.refetchInterval` to poll until the transaction completes.
+
+```ts
+type UseTransactionStatusParameters = GetTransactionStatusParameters &
+    GetTransactionStatusQueryConfig<selectData>;
+```
+
+#### UseTransactionStatusReturnType
+
+Return type of [`useTransactionStatus`](#usetransactionstatus) — TanStack Query result for the status read.
+
+```ts
+type UseTransactionStatusReturnType = UseQueryReturnType<
+    selectData,
+    GetTransactionStatusErrorType
+>;
+```
+
+#### UseTransferTonParameters
+
+Parameters accepted by [`useTransferTon`](#usetransferton) — TanStack Query mutation options.
+
+```ts
+type UseTransferTonParameters = TransferTonOptions<context>;
+```
+
+#### UseTransferTonReturnType
+
+Return type of [`useTransferTon`](#usetransferton) — TanStack Query mutation result.
+
+```ts
+type UseTransferTonReturnType = UseMutationReturnType<
+    TransferTonData,
+    TransferTonErrorType,
+    TransferTonVariables,
+    context,
+    (
+        variables: TransferTonVariables,
+        options?: MutateOptions<TransferTonData, TransferTonErrorType, TransferTonVariables, context>,
+    ) => void,
+    MutateFunction<TransferTonData, TransferTonErrorType, TransferTonVariables, context>
+>;
+```
+
+#### UseWatchTransactionsByAddressParameters
+
+Parameters accepted by [`useWatchTransactionsByAddress`](#usewatchtransactionsbyaddress) — same fields as [`WatchTransactionsByAddressOptions`](/ecosystem/appkit/reference/appkit#watchtransactionsbyaddressoptions), all optional so callers can render the hook before the address is known.
+
+```ts
+type UseWatchTransactionsByAddressParameters = Partial<WatchTransactionsByAddressOptions>;
+```
+
+#### UseWatchTransactionsParameters
+
+Parameters accepted by [`useWatchTransactions`](#usewatchtransactions).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange` | <code>(update: <a href="/ecosystem/appkit/reference/appkit#transactionsupdate">TransactionsUpdate</a>) =&gt; void</code> | Callback fired on every transactions update from the streaming provider. |
+
+### UI
+
+#### BlockProps
+
+Props accepted by [`Block`](#block).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `direction` | `'row' \| 'column'` | Flex direction of the block. Defaults to `'column'`. |
+
+#### ButtonProps
+
+Props accepted by [`Button`](#button).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `size` | `ButtonSize` | Size class applied to the button. Pass `'unset'` to skip the size class entirely (no padding, no typography) — useful with `variant="unstyled"`. |
+| `borderRadius` | `ButtonBorderRadius` | Border radius token; defaults to a size-dependent value (`s` → `2xl`, `m` → `l`, `l` → `xl`). |
+| `variant` | `ButtonVariant` | Visual variant. Use `'unstyled'` to opt out of all built-in styling — the consumer is fully responsible for visuals via `className`. The Button still provides ref forwarding, `disabled`/`loading` plumbing, and `icon`/`children` rendering. |
+| `loading` | `boolean` | When true, renders a spinner instead of `icon`/`children` and disables the button. |
+| `fullWidth` | `boolean` | When true, the button stretches to fill its container width. |
+| `icon` | `ReactNode` | Optional leading icon rendered before `children` when not loading. |
+
+#### CenteredAmountInputProps
+
+Props accepted by [`CenteredAmountInput`](#centeredamountinput).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Controlled input value (decimal string). |
+| `onValueChange`\* | `(value: string) => void` | Called with the new string whenever the user edits the input. |
+| `ticker` | `string` | Optional trailing ticker label (e.g., `'TON'`). |
+| `symbol` | `string` | Optional leading currency symbol (e.g., `'$'`). |
+| `placeholder` | `string` | Placeholder shown when `value` is empty. Defaults to `'0'`. |
+| `disabled` | `boolean` | When true, the underlying `<input>` is disabled. |
+
+#### CollapsibleProps
+
+Props accepted by [`Collapsible`](#collapsible).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `open`\* | `boolean` | When true, the content is expanded; when false, it is collapsed to zero height. |
+
+#### IconProps
+
+Standard props for all icon components.
+
+Icons render an `<svg>` whose dimensions are controlled by `size`. Color is
+inherited from `currentColor`, so style icons by setting `color` on a parent.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### InputContainerProps
+
+Props accepted by [`Input.Container`](#input.container) (also used by [`Input`](#input) itself).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `size` | `InputSize` | Size token applied to the input control(s) inside: `'s' | 'm' | 'l'`. Defaults to `'m'`. |
+| `variant` | `InputVariant` | Visual variant: `'default'` paints a filled field; `'unstyled'` drops the chrome. |
+| `disabled` | `boolean` | When true, descendant input controls are disabled. |
+| `error` | `boolean` | When true, the field renders in error styling and [`Input.Caption`](#input.caption) switches to error text. |
+| `loading` | `boolean` | When true, [`Input.Input`](#input.input) renders a skeleton placeholder instead of an `<input>`. |
+| `resizable` | `boolean` | When true, [`Input.Input`](#input.input) scales its font down to fit the available width as the user types. |
+| `children`\* | `ReactNode` | Compound sub-components (header, field, control, caption). |
+
+#### InputControlProps
+
+Props accepted by [`Input.Input`](#input.input) — standard `<input>` props. Size, disabled, loading, and resizable behavior are inherited from the surrounding [`Input.Container`](#input.container).
+
+```ts
+type InputControlProps = ComponentProps<'input'>;
+```
+
+#### InputFieldProps
+
+Props accepted by [`Input.Field`](#input.field).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `children`\* | `ReactNode` | Field content — typically slots and the input control laid out horizontally. |
+
+#### InputHeaderProps
+
+Props accepted by [`Input.Header`](#input.header).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `children`\* | `ReactNode` | Header content — typically a [`Input.Title`](#input.title) and optional trailing controls. |
+
+#### InputSlotProps
+
+Props accepted by [`Input.Slot`](#input.slot).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `side` | `'left' \| 'right'` | Which edge of the field the slot adheres to. |
+
+#### LogoProps
+
+Props accepted by [`Logo`](#logo).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size in pixels for the rendered logo. Defaults to `30`. |
+| `src` | `string` | Image URL to render. While loading or on failure, the fallback is shown. |
+| `alt` | `string` | Alt text passed to the underlying `<img>`. When `fallback` is not provided, its first character is shown as the fallback; if both are missing, no fallback is rendered. |
+| `fallback` | `string` | Text shown in place of the image when `src` fails or is missing (defaults to the first character of `alt`). |
+
+#### LogoWithNetworkProps
+
+Props accepted by [`LogoWithNetwork`](#logowithnetwork).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Size of the main logo in pixels. Defaults to `30`. The network badge is sized to `size * 0.4`. |
+| `src` | `string` | Image source for the main logo. |
+| `alt` | `string` | Alt text for the main logo. |
+| `fallback` | `string` | Fallback text shown when the main logo image fails or is missing. |
+| `networkSrc` | `string` | Image source for the network badge overlay. When omitted, the badge is not rendered. |
+| `networkAlt` | `string` | Alt text for the network badge. |
+
+#### ModalProps
+
+Props accepted by [`Modal`](#modal).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `open` | `boolean` | Controlled open state. |
+| `onOpenChange` | `(open: boolean) => void` | Called whenever the open state changes (e.g., via the close button, overlay click, or `Escape`). |
+| `title` | `string` | Optional title rendered in the modal header. |
+| `children` | `ReactNode` | Modal body content. |
+| `className` | `string` | Additional class name applied to the content container. |
+| `bodyClassName` | `string` | Additional class name applied to the body container. |
+
+#### SelectContentProps
+
+Props accepted by [`Select.Content`](#select.content).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `align` | `'start' \| 'end'` | Horizontal alignment relative to the trigger. |
+| `sideOffset` | `number` | Gap between trigger and content in pixels. |
+
+#### SelectItemProps
+
+Props accepted by [`Select.Item`](#select.item).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Value committed to [`Select.Root`](#select.root) when this item is chosen. |
+| `disabled` | `boolean` | When true, the item is not selectable and is excluded from keyboard navigation. |
+
+#### SelectRootProps
+
+Props accepted by [`Select.Root`](#select.root).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value` | `string` | Controlled selected value. |
+| `defaultValue` | `string` | Initial value when uncontrolled. |
+| `onValueChange` | `(value: string) => void` | Called whenever the selected value changes. |
+| `open` | `boolean` | Controlled open state. |
+| `defaultOpen` | `boolean` | Initial open state when uncontrolled. |
+| `onOpenChange` | `(open: boolean) => void` | Called whenever the open state changes. |
+| `disabled` | `boolean` | When true, the trigger is non-interactive. |
+| `children`\* | `ReactNode` | Compound sub-components — [`Select.Trigger`](#select.trigger), [`Select.Content`](#select.content), [`Select.Item`](#select.item). |
+
+#### SelectTriggerProps
+
+Props accepted by [`Select.Trigger`](#select.trigger) — same as [`ButtonProps`](#buttonprops). The trigger inherits `disabled` from the surrounding root if set.
+
+```ts
+type SelectTriggerProps = ButtonProps;
+```
+
+#### SkeletonProps
+
+Props accepted by [`Skeleton`](#skeleton).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `width` | `string \| number` | Width of the placeholder. Accepts any valid CSS length or a number (interpreted as pixels). |
+| `height` | `string \| number` | Height of the placeholder. Accepts any valid CSS length or a number (interpreted as pixels). |
+
+#### TabsContentProps
+
+Props accepted by [`TabsContent`](#tabscontent).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Value this panel is associated with — rendered only when the parent [`Tabs`](#tabs) is on this value. |
+| `children`\* | `ReactNode` | Panel content. |
+
+#### TabsListProps
+
+Props accepted by [`TabsList`](#tabslist).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `children`\* | `ReactNode` | Tab triggers — typically one or more [`TabsTrigger`](#tabstrigger)s. |
+
+#### TabsProps
+
+Props accepted by [`Tabs`](#tabs).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value` | `string` | Controlled active tab value. |
+| `defaultValue` | `string` | Initial active tab when uncontrolled. Defaults to `''`. |
+| `onValueChange` | `(value: string) => void` | Called whenever the active tab changes. |
+| `children`\* | `ReactNode` | Compound sub-components — typically [`TabsList`](#tabslist) (with [`TabsTrigger`](#tabstrigger)s) followed by [`TabsContent`](#tabscontent)s. |
+
+#### TabsTriggerProps
+
+Props accepted by [`TabsTrigger`](#tabstrigger).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Value committed to the parent [`Tabs`](#tabs) when this trigger is activated. |
+| `children`\* | `ReactNode` | Trigger label / content. |
+
+### Wallets
+
+#### UseAddressReturnType
+
+Return type of [`useAddress`](#useaddress) — `undefined` when no wallet is selected.
+
+```ts
+type UseAddressReturnType = string | undefined;
+```
+
+#### UseConnectParameters
+
+Parameters accepted by [`useConnect`](#useconnect) — TanStack Query mutation options (`onSuccess`, `onError`, `onMutate`, `retry`, …).
+
+```ts
+type UseConnectParameters = ConnectOptions<context>;
+```
+
+#### UseConnectReturnType
+
+Return type of [`useConnect`](#useconnect) — TanStack Query mutation result with `mutate`/`mutateAsync` and the standard companions.
+
+```ts
+type UseConnectReturnType = UseMutationReturnType<
+    ConnectData,
+    ConnectErrorType,
+    ConnectVariables,
+    context,
+    (
+        variables: ConnectVariables,
+        options?: MutateOptions<ConnectData, ConnectErrorType, ConnectVariables, context>,
+    ) => void,
+    MutateFunction<ConnectData, ConnectErrorType, ConnectVariables, context>
+>;
+```
+
+#### UseConnectedWalletsReturnType
+
+Return type of [`useConnectedWallets`](#useconnectedwallets) — same shape as [`GetConnectedWalletsReturnType`](/ecosystem/appkit/reference/appkit#getconnectedwalletsreturntype).
+
+```ts
+type UseConnectedWalletsReturnType = GetConnectedWalletsReturnType;
+```
+
+#### UseDisconnectParameters
+
+Parameters accepted by [`useDisconnect`](#usedisconnect) — TanStack Query mutation options.
+
+```ts
+type UseDisconnectParameters = DisconnectOptions<context>;
+```
+
+#### UseDisconnectReturnType
+
+Return type of [`useDisconnect`](#usedisconnect) — TanStack Query mutation result.
+
+```ts
+type UseDisconnectReturnType = UseMutationReturnType<
+    DisconnectData,
+    DisconnectErrorType,
+    DisconnectVariables,
+    context,
+    (
+        variables: DisconnectVariables,
+        options?: MutateOptions<DisconnectData, DisconnectErrorType, DisconnectVariables, context>,
+    ) => void,
+    MutateFunction<DisconnectData, DisconnectErrorType, DisconnectVariables, context>
+>;
+```
+
+#### UseSelectedWalletReturnType
+
+Return type of [`useSelectedWallet`](#useselectedwallet) — `[wallet, setWalletId]` tuple. `wallet` is the active [`WalletInterface`](/ecosystem/appkit/reference/appkit#walletinterface) (or `null`); `setWalletId` calls [`setSelectedWalletId`](/ecosystem/appkit/reference/appkit#setselectedwalletid) and emits `wallets:selection-changed`.
+
+```ts
+type UseSelectedWalletReturnType = readonly [GetSelectedWalletReturnType, (walletId: string | null) => void];
+```
+
+## Constants
+
+### Crypto Onramp
+
+#### DEFAULT_CHAINS
+
+Default mapping of CAIP-2 chain identifiers to [`ChainInfo`](#chaininfo) used by the crypto onramp widget. Consumers can override or extend this map via the `chains` prop on [`CryptoOnrampWidgetProvider`](#cryptoonrampwidgetprovider).
+
+```ts
+const DEFAULT_CHAINS = {
+    'eip155:1': { name: 'Ethereum' },
+    'eip155:10': { name: 'Optimism' },
+    'eip155:56': { name: 'BSC' },
+    'eip155:137': { name: 'Polygon' },
+    'eip155:8453': { name: 'Base' },
+    'eip155:42161': {
+        name: 'Arbitrum One',
+        logo: 'https://cdn.layerswap.io/layerswap/networks/arbitrum_mainnet.png',
+    },
+    'eip155:43114': { name: 'Avalanche' },
+    'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp': { name: 'Solana' },
+    'bip122:000000000019d6689c085ae165831e93': { name: 'Bitcoin' },
+};
+```
+
+### UI
+
+#### DEFAULT_ICON_SIZE
+
+Default size in pixels (24) applied to icons when `size` is not provided.
+
+```ts
+const DEFAULT_ICON_SIZE = 24;
+```
diff --git a/template/packages/appkit/README.md b/docs/templates/packages/appkit/README.md
similarity index 93%
rename from template/packages/appkit/README.md
rename to docs/templates/packages/appkit/README.md
index dae80edc8..a2b7c868b 100644
--- a/template/packages/appkit/README.md
+++ b/docs/templates/packages/appkit/README.md
@@ -35,17 +35,17 @@ npm install @ton/appkit @ton/core @ton/crypto
 
 ## Initialize AppKit and wrap wallet
 
-%%demo/examples/src/appkit#APPKIT_INIT%%
+%%docs/examples/src/appkit#APPKIT_INIT%%
 
 ## Usage
  
 ### Get Balance
  
-%%demo/examples/src/appkit/actions/balances#GET_BALANCE%%
+%%docs/examples/src/appkit/actions/balances#GET_BALANCE%%
  
 ### Transfer TON
  
-%%demo/examples/src/appkit/actions/transaction#TRANSFER_TON%%
+%%docs/examples/src/appkit/actions/transaction#TRANSFER_TON%%
  
 > See all available actions in the [Actions Documentation](https://github.com/ton-connect/kit/tree/main/packages/appkit/docs/actions.md).
 
diff --git a/template/packages/appkit/docs/actions.md b/docs/templates/packages/appkit/docs/actions.md
similarity index 60%
rename from template/packages/appkit/docs/actions.md
rename to docs/templates/packages/appkit/docs/actions.md
index cf96cab61..b1bde1bf0 100644
--- a/template/packages/appkit/docs/actions.md
+++ b/docs/templates/packages/appkit/docs/actions.md
@@ -12,25 +12,25 @@ AppKit provides a set of actions to interact with the blockchain and wallets.
 
 Get the TON balance of the currently selected wallet.
 
-%%demo/examples/src/appkit/actions/balances#GET_BALANCE%%
+%%docs/examples/src/appkit/actions/balances#GET_BALANCE%%
 
 ### `getBalanceByAddress`
 
 Fetch the TON balance of a specific address.
 
-%%demo/examples/src/appkit/actions/balances#GET_BALANCE_BY_ADDRESS%%
+%%docs/examples/src/appkit/actions/balances#GET_BALANCE_BY_ADDRESS%%
 
 ### `watchBalance`
 
 Watch the TON balance of the currently selected wallet in real-time.
 
-%%demo/examples/src/appkit/actions/balances#WATCH_BALANCE%%
+%%docs/examples/src/appkit/actions/balances#WATCH_BALANCE%%
 
 ### `watchBalanceByAddress`
 
 Watch the TON balance of a specific address in real-time.
 
-%%demo/examples/src/appkit/actions/balances#WATCH_BALANCE_BY_ADDRESS%%
+%%docs/examples/src/appkit/actions/balances#WATCH_BALANCE_BY_ADDRESS%%
 
 ## Connectors
 
@@ -38,43 +38,43 @@ Watch the TON balance of a specific address in real-time.
 
 Connect a wallet using a specific connector.
 
-%%demo/examples/src/appkit/actions/connectors#CONNECT%%
+%%docs/examples/src/appkit/actions/connectors#CONNECT%%
 
 ### `addConnector`
 
 Add a wallet connector to AppKit (e.g., TonConnect).
 
-%%demo/examples/src/appkit/actions/connectors#ADD_CONNECTOR%%
+%%docs/examples/src/appkit/actions/connectors#ADD_CONNECTOR%%
 
 ### `disconnect`
 
 Disconnect a wallet using a specific connector.
 
-%%demo/examples/src/appkit/actions/connectors#DISCONNECT%%
+%%docs/examples/src/appkit/actions/connectors#DISCONNECT%%
 
 ### `getConnectors`
 
 Get all available connectors.
 
-%%demo/examples/src/appkit/actions/connectors#GET_CONNECTORS%%
+%%docs/examples/src/appkit/actions/connectors#GET_CONNECTORS%%
 
 ### `getConnectorById`
 
 Get a specific connector by its ID.
 
-%%demo/examples/src/appkit/actions/connectors#GET_CONNECTOR_BY_ID%%
+%%docs/examples/src/appkit/actions/connectors#GET_CONNECTOR_BY_ID%%
 
 ### `watchConnectors`
 
 Watch for changes in available connectors (e.g., when a wallet connects).
 
-%%demo/examples/src/appkit/actions/connectors#WATCH_CONNECTORS%%
+%%docs/examples/src/appkit/actions/connectors#WATCH_CONNECTORS%%
 
 ### `watchConnectorById`
 
 Watch for changes in a specific connector.
 
-%%demo/examples/src/appkit/actions/connectors#WATCH_CONNECTOR_BY_ID%%
+%%docs/examples/src/appkit/actions/connectors#WATCH_CONNECTOR_BY_ID%%
 
 ## Jettons
 
@@ -82,43 +82,43 @@ Watch for changes in a specific connector.
 
 Get all jettons owned by the currently selected wallet.
 
-%%demo/examples/src/appkit/actions/jettons#GET_JETTONS%%
+%%docs/examples/src/appkit/actions/jettons#GET_JETTONS%%
 
 ### `getJettonsByAddress`
 
 Get all jettons owned by a specific address.
 
-%%demo/examples/src/appkit/actions/jettons#GET_JETTONS_BY_ADDRESS%%
+%%docs/examples/src/appkit/actions/jettons#GET_JETTONS_BY_ADDRESS%%
 
 ### `getJettonBalance`
 
 Get the balance of a specific jetton for a wallet address.
 
-%%demo/examples/src/appkit/actions/jettons#GET_JETTON_BALANCE%%
+%%docs/examples/src/appkit/actions/jettons#GET_JETTON_BALANCE%%
 
 ### `getJettonInfo`
 
 Get information about a specific jetton by its address.
 
-%%demo/examples/src/appkit/actions/jettons#GET_JETTON_INFO%%
+%%docs/examples/src/appkit/actions/jettons#GET_JETTON_INFO%%
 
 ### `getJettonWalletAddress`
 
 Get the jetton wallet address for a specific jetton and owner address.
 
-%%demo/examples/src/appkit/actions/jettons#GET_JETTON_WALLET_ADDRESS%%
+%%docs/examples/src/appkit/actions/jettons#GET_JETTON_WALLET_ADDRESS%%
 
 ### `createTransferJettonTransaction`
 
 Create a transaction for transferring jettons without sending it.
 
-%%demo/examples/src/appkit/actions/jettons#CREATE_TRANSFER_JETTON_TRANSACTION%%
+%%docs/examples/src/appkit/actions/jettons#CREATE_TRANSFER_JETTON_TRANSACTION%%
 
 ### `transferJetton`
 
 Transfer jettons to a recipient address.
 
-%%demo/examples/src/appkit/actions/jettons#TRANSFER_JETTON%%
+%%docs/examples/src/appkit/actions/jettons#TRANSFER_JETTON%%
 
 ## Networks
 
@@ -126,55 +126,55 @@ Transfer jettons to a recipient address.
 
 Get the network of the currently selected wallet.
 
-%%demo/examples/src/appkit/actions/network#GET_NETWORK%%
+%%docs/examples/src/appkit/actions/network#GET_NETWORK%%
 
 ### `getNetworks`
 
 Get all configured networks.
 
-%%demo/examples/src/appkit/actions/network#GET_NETWORKS%%
+%%docs/examples/src/appkit/actions/network#GET_NETWORKS%%
 
 ### `getApiClient`
 
 Get the API client for a specific network.
 
-%%demo/examples/src/appkit/actions/network#GET_API_CLIENT%%
+%%docs/examples/src/appkit/actions/network#GET_API_CLIENT%%
 
 ### `watchNetworks`
 
 Watch configured networks.
 
-%%demo/examples/src/appkit/actions/network#WATCH_NETWORKS%%
+%%docs/examples/src/appkit/actions/network#WATCH_NETWORKS%%
 
 ### `hasStreamingProvider`
 
 Check if a real-time streaming provider is registered for a specific network.
 
-%%demo/examples/src/appkit/actions/network#HAS_STREAMING_PROVIDER%%
+%%docs/examples/src/appkit/actions/network#HAS_STREAMING_PROVIDER%%
 
 ### `getBlockNumber`
 
 Get the current masterchain block number.
 
-%%demo/examples/src/appkit/actions/network#GET_BLOCK_NUMBER%%
+%%docs/examples/src/appkit/actions/network#GET_BLOCK_NUMBER%%
 
 ### `getDefaultNetwork`
 
 Get the currently configured default network.
 
-%%demo/examples/src/appkit/actions/network#GET_DEFAULT_NETWORK%%
+%%docs/examples/src/appkit/actions/network#GET_DEFAULT_NETWORK%%
 
 ### `setDefaultNetwork`
 
 Set the default network for wallet connections. If set, connectors (e.g. TonConnect) will enforce this network when connecting a wallet. Pass `undefined` to allow any network.
 
-%%demo/examples/src/appkit/actions/network#SET_DEFAULT_NETWORK%%
+%%docs/examples/src/appkit/actions/network#SET_DEFAULT_NETWORK%%
 
 ### `watchDefaultNetwork`
 
 Watch for changes in the default network.
 
-%%demo/examples/src/appkit/actions/network#WATCH_DEFAULT_NETWORK%%
+%%docs/examples/src/appkit/actions/network#WATCH_DEFAULT_NETWORK%%
 
 ## NFTs
 
@@ -182,31 +182,31 @@ Watch for changes in the default network.
 
 Get all NFTs owned by the currently selected wallet.
 
-%%demo/examples/src/appkit/actions/nft#GET_NFTS%%
+%%docs/examples/src/appkit/actions/nft#GET_NFTS%%
 
 ### `getNftsByAddress`
 
 Get all NFTs owned by a specific address.
 
-%%demo/examples/src/appkit/actions/nft#GET_NFTS_BY_ADDRESS%%
+%%docs/examples/src/appkit/actions/nft#GET_NFTS_BY_ADDRESS%%
 
 ### `getNft`
 
 Get information about a specific NFT by its address.
 
-%%demo/examples/src/appkit/actions/nft#GET_NFT%%
+%%docs/examples/src/appkit/actions/nft#GET_NFT%%
 
 ### `createTransferNftTransaction`
 
 Create a transaction for transferring a NFT without sending it.
 
-%%demo/examples/src/appkit/actions/nft#CREATE_TRANSFER_NFT_TRANSACTION%%
+%%docs/examples/src/appkit/actions/nft#CREATE_TRANSFER_NFT_TRANSACTION%%
 
 ### `transferNft`
 
 Transfer a NFT to a recipient address.
 
-%%demo/examples/src/appkit/actions/nft#TRANSFER_NFT%%
+%%docs/examples/src/appkit/actions/nft#TRANSFER_NFT%%
 
 ## Onramp
 
@@ -230,13 +230,13 @@ Watch for new onramp providers registration.
 
 Get an onramp quote from registered providers.
 
-%%demo/examples/src/appkit/actions/onramp#GET_ONRAMP_QUOTE%%
+%%docs/examples/src/appkit/actions/onramp#GET_ONRAMP_QUOTE%%
 
 ### `buildOnrampUrl`
 
 Build an onramp URL for redirecting the user to the provider.
 
-%%demo/examples/src/appkit/actions/onramp#BUILD_ONRAMP_URL%%
+%%docs/examples/src/appkit/actions/onramp#BUILD_ONRAMP_URL%%
 
 ## Crypto Onramp
 
@@ -244,13 +244,13 @@ Build an onramp URL for redirecting the user to the provider.
 
 Get a registered crypto-onramp provider by id, or the default one when no id is given.
 
-%%demo/examples/src/appkit/actions/onramp#GET_CRYPTO_ONRAMP_PROVIDER%%
+%%docs/examples/src/appkit/actions/onramp#GET_CRYPTO_ONRAMP_PROVIDER%%
 
 ### `getCryptoOnrampProviders`
 
 Get all registered crypto-onramp providers.
 
-%%demo/examples/src/appkit/actions/onramp#GET_CRYPTO_ONRAMP_PROVIDERS%%
+%%docs/examples/src/appkit/actions/onramp#GET_CRYPTO_ONRAMP_PROVIDERS%%
 
 ### `watchCryptoOnrampProviders`
 
@@ -262,7 +262,7 @@ Watch for new crypto-onramp providers registration and default-provider changes.
 
 Register a custom provider in AppKit (e.g., Swap or Streaming).
 
-%%demo/examples/src/appkit/actions/providers#REGISTER_PROVIDER%%
+%%docs/examples/src/appkit/actions/providers#REGISTER_PROVIDER%%
 
 ## Signing
 
@@ -270,19 +270,19 @@ Register a custom provider in AppKit (e.g., Swap or Streaming).
 
 Sign a text message with the connected wallet.
 
-%%demo/examples/src/appkit/actions/signing#SIGN_TEXT%%
+%%docs/examples/src/appkit/actions/signing#SIGN_TEXT%%
 
 ### `signBinary`
 
 Sign binary data with the connected wallet.
 
-%%demo/examples/src/appkit/actions/signing#SIGN_BINARY%%
+%%docs/examples/src/appkit/actions/signing#SIGN_BINARY%%
 
 ### `signCell`
 
 Sign a TON Cell with the connected wallet. Used for on-chain signature verification.
 
-%%demo/examples/src/appkit/actions/signing#SIGN_CELL%%
+%%docs/examples/src/appkit/actions/signing#SIGN_CELL%%
 
 ## Swap
 
@@ -290,43 +290,43 @@ Sign a TON Cell with the connected wallet. Used for on-chain signature verificat
 
 Get the `SwapManager` instance to interact with swap providers directly.
 
-%%demo/examples/src/appkit/actions/swap#GET_SWAP_MANAGER%%
+%%docs/examples/src/appkit/actions/swap#GET_SWAP_MANAGER%%
 
 ### `getSwapProvider`
 
 Get a specific swap provider by its ID.
 
-%%demo/examples/src/appkit/actions/swap#GET_SWAP_PROVIDER%%
+%%docs/examples/src/appkit/actions/swap#GET_SWAP_PROVIDER%%
 
 ### `getSwapProviders`
 
 Get all registered swap providers. The returned array keeps a stable reference until the provider list changes.
 
-%%demo/examples/src/appkit/actions/swap#GET_SWAP_PROVIDERS%%
+%%docs/examples/src/appkit/actions/swap#GET_SWAP_PROVIDERS%%
 
 ### `setDefaultSwapProvider`
 
 Set the default swap provider. Subsequent quote and swap-transaction calls will use this provider when none is specified.
 
-%%demo/examples/src/appkit/actions/swap#SET_DEFAULT_SWAP_PROVIDER%%
+%%docs/examples/src/appkit/actions/swap#SET_DEFAULT_SWAP_PROVIDER%%
 
 ### `watchSwapProviders`
 
 Watch for new swap providers registration.
 
-%%demo/examples/src/appkit/actions/swap#WATCH_SWAP_PROVIDERS%%
+%%docs/examples/src/appkit/actions/swap#WATCH_SWAP_PROVIDERS%%
 
 ### `getSwapQuote`
 
 Get a swap quote from registered providers.
 
-%%demo/examples/src/appkit/actions/swap#GET_SWAP_QUOTE%%
+%%docs/examples/src/appkit/actions/swap#GET_SWAP_QUOTE%%
 
 ### `buildSwapTransaction`
 
 Build (assemble) a swap transaction based on a quote. After the transaction is built, you can use `sendTransaction` to execute it on the blockchain.
 
-%%demo/examples/src/appkit/actions/swap#BUILD_SWAP_TRANSACTION%%
+%%docs/examples/src/appkit/actions/swap#BUILD_SWAP_TRANSACTION%%
 
 ## Staking
 
@@ -334,37 +334,37 @@ Build (assemble) a swap transaction based on a quote. After the transaction is b
 
 Get all available staking provider IDs.
 
-%%demo/examples/src/appkit/actions/staking#GET_STAKING_PROVIDERS%%
+%%docs/examples/src/appkit/actions/staking#GET_STAKING_PROVIDERS%%
 
 ### `getStakingProviderInfo`
 
 Get dynamic information about a specific staking provider (e.g. APY, rate).
 
-%%demo/examples/src/appkit/actions/staking#GET_STAKING_PROVIDER_INFO%%
+%%docs/examples/src/appkit/actions/staking#GET_STAKING_PROVIDER_INFO%%
 
 ### `getStakingProviderMetadata`
 
 Get static metadata about a specific staking provider.
 
-%%demo/examples/src/appkit/actions/staking#GET_STAKING_PROVIDER_METADATA%%
+%%docs/examples/src/appkit/actions/staking#GET_STAKING_PROVIDER_METADATA%%
 
 ### `getStakingQuote`
 
 Get a staking or unstaking quote.
 
-%%demo/examples/src/appkit/actions/staking#GET_STAKING_QUOTE%%
+%%docs/examples/src/appkit/actions/staking#GET_STAKING_QUOTE%%
 
 ### `buildStakeTransaction`
 
 Build a stake transaction based on a quote.
 
-%%demo/examples/src/appkit/actions/staking#BUILD_STAKE_TRANSACTION%%
+%%docs/examples/src/appkit/actions/staking#BUILD_STAKE_TRANSACTION%%
 
 ### `getStakedBalance`
 
 Get the user's staked balance.
 
-%%demo/examples/src/appkit/actions/staking#GET_STAKED_BALANCE%%
+%%docs/examples/src/appkit/actions/staking#GET_STAKED_BALANCE%%
 
 ## Transaction
 
@@ -372,19 +372,19 @@ Get the user's staked balance.
  
 Create a TON transfer transaction request without sending it.
  
-%%demo/examples/src/appkit/actions/transaction#CREATE_TRANSFER_TON_TRANSACTION%%
+%%docs/examples/src/appkit/actions/transaction#CREATE_TRANSFER_TON_TRANSACTION%%
 
 ### `sendTransaction`
  
 Send a transaction to the blockchain.
  
-%%demo/examples/src/appkit/actions/transaction#SEND_TRANSACTION%%
+%%docs/examples/src/appkit/actions/transaction#SEND_TRANSACTION%%
  
 ### `transferTon`
  
 Transfer TON to a recipient address.
  
-%%demo/examples/src/appkit/actions/transaction#TRANSFER_TON%%
+%%docs/examples/src/appkit/actions/transaction#TRANSFER_TON%%
 
 ## Wallets
 
@@ -392,28 +392,28 @@ Transfer TON to a recipient address.
 
 Get all connected wallets.
 
-%%demo/examples/src/appkit/actions/wallets#GET_CONNECTED_WALLETS%%
+%%docs/examples/src/appkit/actions/wallets#GET_CONNECTED_WALLETS%%
 
 ### `getSelectedWallet`
 
 Get the currently selected wallet.
 
-%%demo/examples/src/appkit/actions/wallets#GET_SELECTED_WALLET%%
+%%docs/examples/src/appkit/actions/wallets#GET_SELECTED_WALLET%%
 
 ### `setSelectedWalletId`
 
 Set the currently selected wallet by its ID.
 
-%%demo/examples/src/appkit/actions/wallets#SET_SELECTED_WALLET_ID%%
+%%docs/examples/src/appkit/actions/wallets#SET_SELECTED_WALLET_ID%%
 
 ### `watchConnectedWallets`
 
 Watch for changes in the list of connected wallets.
 
-%%demo/examples/src/appkit/actions/wallets#WATCH_CONNECTED_WALLETS%%
+%%docs/examples/src/appkit/actions/wallets#WATCH_CONNECTED_WALLETS%%
 
 ### `watchSelectedWallet`
 
 Watch for changes in the selected wallet.
 
-%%demo/examples/src/appkit/actions/wallets#WATCH_SELECTED_WALLET%%
+%%docs/examples/src/appkit/actions/wallets#WATCH_SELECTED_WALLET%%
diff --git a/template/packages/appkit/docs/connectors.md b/docs/templates/packages/appkit/docs/connectors.md
similarity index 89%
rename from template/packages/appkit/docs/connectors.md
rename to docs/templates/packages/appkit/docs/connectors.md
index e28b96bd1..e5f0f0de3 100644
--- a/template/packages/appkit/docs/connectors.md
+++ b/docs/templates/packages/appkit/docs/connectors.md
@@ -28,17 +28,17 @@ import { TonConnectConnector } from '@ton/appkit/tonconnect';
 
 You can set up `TonConnectConnector` by passing `tonConnectOptions`. The connector will create the `TonConnectUI` instance internally.
 
-%%demo/examples/src/appkit/connectors/tonconnect#TON_CONNECT_OPTIONS%%
+%%docs/examples/src/appkit/connectors/tonconnect#TON_CONNECT_OPTIONS%%
 
 Alternatively, you can pass an existing `TonConnectUI` instance:
 
-%%demo/examples/src/appkit/connectors/tonconnect#TON_CONNECT_CONNECTOR%%
+%%docs/examples/src/appkit/connectors/tonconnect#TON_CONNECT_CONNECTOR%%
 
 ### Add Connector Dynamically
 
 In some cases, you may need to add a connector after initialization. You can use the `addConnector` method for this purpose.
 
-%%demo/examples/src/appkit/connectors/tonconnect#ADD_CONNECTOR%%
+%%docs/examples/src/appkit/connectors/tonconnect#ADD_CONNECTOR%%
 
 ### Configuration
 
diff --git a/docs/templates/packages/appkit/docs/reference.md b/docs/templates/packages/appkit/docs/reference.md
new file mode 100644
index 000000000..77e262c9f
--- /dev/null
+++ b/docs/templates/packages/appkit/docs/reference.md
@@ -0,0 +1,3962 @@
+---
+target: packages/appkit/docs/reference.md
+---
+
+## Class
+
+### Client
+
+#### ApiClientTonApi
+
+[`ApiClient`](#apiclient) implementation backed by the TonAPI indexer.
+
+Constructor: `new ApiClientTonApi(config)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config` | `BaseApiClientConfig` | TonAPI client config — endpoint URL and API key; defaults to TonAPI mainnet/testnet URLs based on `config.network`. |
+
+#### ApiClientToncenter
+
+[`ApiClient`](#apiclient) implementation backed by the Toncenter API.
+
+Constructor: `new ApiClientToncenter(config)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config` | <code><a href="#apiclientconfig">ApiClientConfig</a></code> | Toncenter client config — endpoint URL, API key and optional DNS resolver override; defaults to mainnet/testnet Toncenter URLs based on `config.network`. |
+
+### 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)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config`\* | [`AppKitConfig`](#appkitconfig) | Networks, connectors, providers and runtime flags. |
+| `config.networks` | <code><a href="#networkadapters">NetworkAdapters</a></code> | Map of chain ID to [`NetworkConfig`](#networkconfig) (which holds the api-client setup); if omitted, AppKit defaults to mainnet only. |
+| `config.connectors` | <code><a href="#connectorinput">ConnectorInput</a>[]</code> | Wallet connectors registered at startup. |
+| `config.defaultNetwork` | <code><a href="#network">Network</a></code> | Default network. |
+| `config.providers` | <code><a href="#providerinput">ProviderInput</a>[]</code> | Providers registered at startup. |
+| `config.ssr` | `boolean` | Set to `true` to enable server-side rendering support. |
+
+**Example**
+
+%%docs/examples/src/appkit#APPKIT_INIT%%
+
+#### EventEmitter
+
+Strongly-typed event emitter built on a string event name → payload type map; backs [`AppKit`](#appkit)'s `emitter` and any custom emitters apps create. `appKit.emitter.on(name, handler)` returns an unsubscribe function.
+
+Constructor: `new EventEmitter()`
+
+### Crypto Onramp
+
+#### CryptoOnrampError
+
+Error thrown by [`CryptoOnrampManager`](#cryptoonrampmanager) and crypto-onramp providers — extends [`DefiError`](#defierror) with `name: 'CryptoOnrampError'` and a stable `code` from the static `CryptoOnrampError.*` / `DefiError.*` constants.
+
+Constructor: `new CryptoOnrampError(message, code, details)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `message`\* | `string` | Human-readable description, forwarded to `Error`. |
+| `code`\* | `string` | Stable error code from the static `CryptoOnrampError.*` / `DefiError.*` constants. |
+| `details` | `unknown` | Optional provider-specific context for diagnostics. |
+
+#### CryptoOnrampManager
+
+Runtime that owns registered [`CryptoOnrampProvider`](#cryptoonrampprovider)s and dispatches quote/deposit/status calls. Exposed as [`AppKit`](#appkit)'s `cryptoOnrampManager`; usually accessed through the higher-level actions ([`getCryptoOnrampQuote`](#getcryptoonrampquote), [`createCryptoOnrampDeposit`](#createcryptoonrampdeposit), [`getCryptoOnrampStatus`](#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`](#cryptoonrampmanager) and the `getCryptoOnramp*` / [`createCryptoOnrampDeposit`](#createcryptoonrampdeposit) actions.
+
+Constructor: `new CryptoOnrampProvider()`
+
+**Example**
+
+```typescript
+class MyCryptoOnrampProvider extends CryptoOnrampProvider {
+  async getQuote(params: CryptoOnrampQuoteParams): Promise<CryptoOnrampQuote> {
+    // Implementation
+  }
+
+  async createDeposit(params: CryptoOnrampDepositParams): Promise<CryptoOnrampDeposit> {
+    // Implementation
+  }
+}
+```
+
+#### LayerswapCryptoOnrampProvider
+
+[`CryptoOnrampProvider`](#cryptoonrampprovider) implementation backed by Layerswap. Use [`createLayerswapProvider`](#createlayerswapprovider) to register it on AppKit; quote, deposit and status calls go through [`getCryptoOnrampQuote`](#getcryptoonrampquote) / [`createCryptoOnrampDeposit`](#createcryptoonrampdeposit) / [`getCryptoOnrampStatus`](#getcryptoonrampstatus) like any other crypto-onramp provider.
+
+Constructor: `new LayerswapCryptoOnrampProvider(config)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config` | <code><a href="#layerswapproviderconfig">LayerswapProviderConfig</a></code> | Optional [`LayerswapProviderConfig`](#layerswapproviderconfig); defaults are filled in for any field left undefined. |
+
+#### SwapsXyzCryptoOnrampProvider
+
+[`CryptoOnrampProvider`](#cryptoonrampprovider) implementation backed by swaps.xyz. Use [`createSwapsXyzProvider`](#createswapsxyzprovider) to register it on AppKit; quote, deposit and status calls go through [`getCryptoOnrampQuote`](#getcryptoonrampquote) / [`createCryptoOnrampDeposit`](#createcryptoonrampdeposit) / [`getCryptoOnrampStatus`](#getcryptoonrampstatus) like any other crypto-onramp provider.
+
+Constructor: `new SwapsXyzCryptoOnrampProvider(config)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config`\* | [`SwapsXyzProviderConfig`](#swapsxyzproviderconfig) | Configuration carrying the required `apiKey` plus optional URL/sender overrides. |
+
+### DeFi
+
+#### DefiError
+
+Base error thrown across all DeFi domains (swap, staking, onramp, crypto-onramp). Subclassed by [`SwapError`](#swaperror), [`StakingError`](#stakingerror), [`CryptoOnrampError`](#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)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `message`\* | `string` | Human-readable description, forwarded to `Error`. |
+| `code`\* | `string` | Stable error code from the `DefiError.*` constants. |
+| `details` | `unknown` | Optional provider-specific context for diagnostics. |
+
+### Networks
+
+#### AppKitNetworkManager
+
+Network manager exposed as [`AppKit`](#appkit)'s `networkManager` — extends walletkit's `KitNetworkManager` with a default-network setter and AppKit event emission.
+
+Constructor: `new AppKitNetworkManager(options, emitter)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options`\* | [`TonWalletKitOptions`](#tonwalletkitoptions) | Forwarded to the [`KitNetworkManager`](#kitnetworkmanager) base — chiefly the `networks` map keyed by chain ID. |
+| `emitter`\* | [`AppKitEmitter`](#appkitemitter) | Emitter the manager publishes `networks:default-changed` / `networks:updated` events through. |
+
+#### KitNetworkManager
+
+Walletkit-side network manager that [`AppKitNetworkManager`](#appkitnetworkmanager) extends, adding default-network state and AppKit event emission. Apps usually interact with the [`AppKitNetworkManager`](#appkitnetworkmanager) subclass via [`AppKit`](#appkit)'s `networkManager`.
+
+Constructor: `new KitNetworkManager(options)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options`\* | [`TonWalletKitOptions`](#tonwalletkitoptions) | Configuration carrying the `networks` map keyed by chain ID; at least one network must be configured. |
+
+### Staking
+
+#### StakingError
+
+Error thrown by [`StakingManager`](#stakingmanager) and staking providers — extends [`DefiError`](#defierror) with `name: 'StakingError'` and a typed [`StakingErrorCode`](#stakingerrorcode) on `code`.
+
+Constructor: `new StakingError(message, code, details)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `message`\* | `string` | Human-readable description, forwarded to `Error`. |
+| `code`\* | <code><a href="#stakingerrorcode">StakingErrorCode</a></code> | Stable [`StakingErrorCode`](#stakingerrorcode) for branching logic. |
+| `details` | `unknown` | Optional provider-specific context for diagnostics. |
+
+#### StakingManager
+
+Runtime that owns registered [`StakingProvider`](#stakingprovider)s and dispatches quote/stake/balance calls. Exposed as [`AppKit`](#appkit)'s `stakingManager`; usually accessed through the higher-level actions ([`getStakingQuote`](#getstakingquote), [`buildStakeTransaction`](#buildstaketransaction), [`getStakedBalance`](#getstakedbalance)).
+
+Constructor: `new StakingManager(createFactoryContext)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `createFactoryContext`\* | <code>() =&gt; <a href="#providerfactorycontext">ProviderFactoryContext</a></code> | Lazy provider of the [`ProviderFactoryContext`](#providerfactorycontext) the manager passes into provider factories at registration time. |
+
+#### StakingProvider
+
+Abstract base class implemented by staking providers (Tonstakers, custom integrations, …); apps don't use it directly — they consume providers through [`StakingManager`](#stakingmanager) and the `getStaking*` / `buildStakeTransaction` actions.
+
+Constructor: `new StakingProvider(providerId)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `providerId`\* | `string` | Stable id the provider registers with — must be unique within [`StakingManager`](#stakingmanager). |
+
+#### TonStakersStakingProvider
+
+[`StakingProvider`](#stakingprovider) implementation backed by Tonstakers. The constructor is private — use [`createTonstakersProvider`](#createtonstakersprovider) to register it on AppKit; quote and stake calls then go through [`getStakingQuote`](#getstakingquote) / [`buildStakeTransaction`](#buildstaketransaction) like any other staking provider.
+
+Constructor: `new TonStakersStakingProvider()`
+
+### Swap
+
+#### DeDustSwapProvider
+
+[`SwapProvider`](#swapprovider) implementation backed by DeDust. Use [`createDeDustProvider`](#creatededustprovider) to register it on AppKit; quote and swap calls go through [`getSwapQuote`](#getswapquote) / [`buildSwapTransaction`](#buildswaptransaction) like any other swap provider.
+
+Constructor: `new DeDustSwapProvider(config)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config` | <code><a href="#dedustswapproviderconfig">DeDustSwapProviderConfig</a></code> | Optional [`DeDustSwapProviderConfig`](#dedustswapproviderconfig); defaults are filled in for any field left undefined. |
+
+**Example**
+
+```typescript
+import { createDeDustProvider } from '@ton/walletkit/swap/dedust';
+
+kit.swap.registerProvider(
+    createDeDustProvider({
+        defaultSlippageBps: 100, // 1%
+        referralAddress: 'EQ...',
+        referralFeeBps: 50, // 0.5%
+    }),
+);
+```
+
+#### OmnistonSwapProvider
+
+[`SwapProvider`](#swapprovider) implementation backed by Omniston. Use [`createOmnistonProvider`](#createomnistonprovider) to register it on AppKit; quote and swap calls go through [`getSwapQuote`](#getswapquote) / [`buildSwapTransaction`](#buildswaptransaction) like any other swap provider.
+
+Constructor: `new OmnistonSwapProvider(config)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config` | <code><a href="#omnistonswapproviderconfig">OmnistonSwapProviderConfig</a></code> | Optional [`OmnistonSwapProviderConfig`](#omnistonswapproviderconfig); defaults are filled in for any field left undefined. |
+
+**Example**
+
+```typescript
+// Import from a separate entry point to avoid bundling the Omniston SDK
+import { createOmnistonProvider } from '@ton/walletkit/swap/omniston';
+
+kit.swap.registerProvider(
+    createOmnistonProvider({
+        apiUrl: 'wss://omni-ws.ston.fi',
+        defaultSlippageBps: 100, // 1%
+        referrerAddress: 'EQ...',
+        referrerFeeBps: 10, // 0.1%
+    }),
+);
+```
+
+#### SwapError
+
+Error thrown by [`SwapManager`](#swapmanager) and swap providers — extends [`DefiError`](#defierror) with `name: 'SwapError'` and a stable `code` from the static `SwapError.*` / `DefiError.*` constants.
+
+Constructor: `new SwapError(message, code, details)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `message`\* | `string` | Human-readable description, forwarded to `Error`. |
+| `code`\* | `string` | Stable error code from the static `SwapError.*` / `DefiError.*` constants. |
+| `details` | `unknown` | Optional provider-specific context for diagnostics. |
+
+#### SwapManager
+
+Runtime that owns registered [`SwapProvider`](#swapprovider)s and dispatches quote/swap calls. Exposed as [`AppKit`](#appkit)'s `swapManager`; usually accessed through the higher-level actions ([`getSwapQuote`](#getswapquote), [`buildSwapTransaction`](#buildswaptransaction)).
+
+Constructor: `new SwapManager(createFactoryContext)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `createFactoryContext`\* | <code>() =&gt; <a href="#providerfactorycontext">ProviderFactoryContext</a></code> | Lazy provider of the [`ProviderFactoryContext`](#providerfactorycontext) the manager passes into provider factories at registration time. |
+
+#### SwapProvider
+
+Abstract base class implemented by swap providers (DeDust, Omniston, custom integrations); apps don't use it directly — they consume providers through [`SwapManager`](#swapmanager) and the `getSwap*` / `buildSwapTransaction` actions.
+
+Constructor: `new SwapProvider()`
+
+**Example**
+
+```typescript
+class MySwapProvider extends SwapProvider {
+  async getQuote(params: SwapQuoteParams): Promise<SwapQuote> {
+    // Implementation
+  }
+
+  async buildSwapTransaction(params: SwapParams): Promise<TransactionRequest> {
+    // Implementation
+  }
+}
+```
+
+### Wallets
+
+#### TonConnectWalletAdapter
+
+[`WalletInterface`](#walletinterface) implementation backed by a TonConnect wallet. Built for you by [`createTonConnectConnector`](#createtonconnectconnector) — apps interact with it through standard AppKit actions ([`sendTransaction`](#sendtransaction), [`signText`](#signtext)/[`signBinary`](#signbinary)/[`signCell`](#signcell)); reads (balance, jettons, NFTs) go through AppKit actions using `appKit.networkManager`, not this adapter.
+
+Constructor: `new TonConnectWalletAdapter(config)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config`\* | [`TonConnectWalletAdapterConfig`](#tonconnectwalletadapterconfig) | TonConnect wallet + UI instance and the id of the connector that produced them. |
+
+## Action
+
+### Balances
+
+#### getBalance
+
+Read the Toncoin balance of the currently selected wallet, returning `null` when no wallet is selected (use [`getBalanceByAddress`](#getbalancebyaddress) for an arbitrary address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options` | [`GetBalanceOptions`](#getbalanceoptions) | Optional network override. |
+| `options.network` | <code><a href="#network">Network</a></code> | Network to read the balance from. Defaults to the selected wallet's network. |
+
+Returns: <code>Promise&lt;<a href="#getbalancereturntype">GetBalanceReturnType</a>&gt;</code> — Balance in TON as a human-readable decimal string, or `null` when no wallet is selected.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/balances#GET_BALANCE%%
+
+#### getBalanceByAddress
+
+Read the Toncoin balance of an arbitrary address — useful for wallets that aren't selected in AppKit (use [`getBalance`](#getbalance) for the selected wallet).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetBalanceByAddressOptions`](#getbalancebyaddressoptions) | Target address and optional network. |
+| `options.address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Wallet address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+
+Returns: <code>Promise&lt;<a href="#getbalancebyaddressreturntype">GetBalanceByAddressReturnType</a>&gt;</code> — Balance in TON as a human-readable decimal string.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/balances#GET_BALANCE_BY_ADDRESS%%
+
+#### 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`](#watchbalancebyaddress) for a fixed address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`WatchBalanceOptions`](#watchbalanceoptions) | Update callback and optional network override. |
+| `options.network` | <code><a href="#network">Network</a></code> | Network to watch on. Defaults to the selected wallet's network. |
+| `options.onChange`\* | <code>(update: <a href="#balanceupdate">BalanceUpdate</a>) =&gt; void</code> | Callback fired on every balance update from the streaming provider. |
+
+Returns: <code><a href="#watchbalancereturntype">WatchBalanceReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/balances#WATCH_BALANCE%%
+
+#### watchBalanceByAddress
+
+Subscribe to Toncoin balance updates for an arbitrary address — useful for monitoring wallets that aren't selected in AppKit (use [`watchBalance`](#watchbalance) for the selected wallet).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`WatchBalanceByAddressOptions`](#watchbalancebyaddressoptions) | Target address, update callback and optional network override. |
+| `options.address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Wallet address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+| `options.onChange`\* | <code>(update: <a href="#balanceupdate">BalanceUpdate</a>) =&gt; void</code> | Callback fired on every balance update from the streaming provider. |
+
+Returns: <code><a href="#watchbalancebyaddressreturntype">WatchBalanceByAddressReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/balances#WATCH_BALANCE_BY_ADDRESS%%
+
+### Client
+
+#### getApiClient
+
+Read the [`ApiClient`](#apiclient) configured for a specific [`Network`](#network) — throws when the network has no client registered.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetApiClientOptions`](#getapiclientoptions) | Network to look up. |
+| `options.network`\* | <code><a href="#network">Network</a></code> | Network whose configured [`ApiClient`](#apiclient) should be returned. |
+
+Returns: <code><a href="#getapiclientreturntype">GetApiClientReturnType</a></code> — The configured [`ApiClient`](#apiclient) for the requested network.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/network#GET_API_CLIENT%%
+
+### Connectors
+
+#### addConnector
+
+Register a wallet connector at runtime — equivalent to passing it via [`AppKitConfig`](#appkitconfig)'s `connectors` at construction, but available after AppKit is up.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `connectorFn`\* | [`AddConnectorParameters`](#addconnectorparameters) | Connector instance or factory to register. |
+
+Returns: <code><a href="#addconnectorreturntype">AddConnectorReturnType</a></code> — Function that unregisters the connector when called.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/connectors#ADD_CONNECTOR%%
+
+#### connect
+
+Trigger the connection flow on a registered connector by id — drives it against AppKit's default network (set via [`setDefaultNetwork`](#setdefaultnetwork)); throws when no connector with that id exists.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`ConnectParameters`](#connectparameters) | Connector to connect through. |
+| `parameters.connectorId`\* | `string` | ID of the registered connector to drive the connection through (e.g., `'tonconnect'`). |
+
+Returns: <code>Promise&lt;<a href="#connectreturntype">ConnectReturnType</a>&gt;</code> — Resolves once the connector's connect flow completes; if a wallet was successfully connected, it becomes available via [`getSelectedWallet`](#getselectedwallet).
+
+**Example**
+
+%%docs/examples/src/appkit/actions/connectors#CONNECT%%
+
+#### createConnector
+
+Identity helper for typing a [`ConnectorFactory`](#connectorfactory) inline — returns the factory unchanged so authors get parameter inference without spelling the type out.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `factory`\* | [`ConnectorFactory`](#connectorfactory) | Factory to wrap. |
+
+Returns: <code><a href="#connectorfactory">ConnectorFactory</a></code> — The same factory, typed as [`ConnectorFactory`](#connectorfactory).
+
+#### createTonConnectConnector
+
+Build a TonConnect-backed [`Connector`](#connector) for AppKit; pass the result to [`AppKitConfig`](#appkitconfig)'s `connectors` or [`addConnector`](#addconnector).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config`\* | [`TonConnectConnectorConfig`](#tonconnectconnectorconfig) | Connector ID, metadata override and TonConnect options or pre-built UI instance. |
+
+Returns: <code><a href="#connectorfactory">ConnectorFactory</a></code> — Factory function consumed by AppKit at registration time.
+
+**Example**
+
+%%docs/examples/src/appkit/connectors/tonconnect#TON_CONNECT_CONNECTOR%%
+
+#### 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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`DisconnectParameters`](#disconnectparameters) | Connector to disconnect. |
+| `parameters.connectorId`\* | `string` | ID of the registered connector whose wallet should be disconnected. |
+
+Returns: <code>Promise&lt;<a href="#disconnectreturntype">DisconnectReturnType</a>&gt;</code> — Resolves once the connector tears down its session.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/connectors#DISCONNECT%%
+
+#### getConnectorById
+
+Look up a registered connector by its id.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetConnectorByIdOptions`](#getconnectorbyidoptions) | ID of the connector to find. |
+| `options.id`\* | `string` | ID of the connector to look up. |
+
+Returns: <code><a href="#getconnectorbyidreturntype">GetConnectorByIdReturnType</a></code> — The matching [`Connector`](#connector), or `undefined` if none with that id is registered.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/connectors#GET_CONNECTOR_BY_ID%%
+
+#### getConnectors
+
+List every connector registered on this AppKit instance — both those passed via [`AppKitConfig`](#appkitconfig)'s `connectors` and those added later through [`addConnector`](#addconnector).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getconnectorsreturntype">GetConnectorsReturnType</a></code> — Read-only array of registered [`Connector`](#connector)s.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/connectors#GET_CONNECTORS%%
+
+#### 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`](#watchconnectedwallets) if you want to react to wallet connect/disconnect events instead.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`WatchConnectorByIdParameters`](#watchconnectorbyidparameters) | Connector ID and update callback. |
+| `parameters.id`\* | `string` | ID of the connector to watch. |
+| `parameters.onChange`\* | <code>(connector: <a href="#connector">Connector</a> \| undefined) =&gt; void</code> | Callback invoked when the connector with the watched id is registered or unregistered — receives the connector itself, or `undefined` when none is registered under that id. |
+
+Returns: <code><a href="#watchconnectorbyidreturntype">WatchConnectorByIdReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/connectors#WATCH_CONNECTOR_BY_ID%%
+
+#### watchConnectors
+
+Subscribe to changes in the registered-connectors list — the callback fires when a connector is added (via [`addConnector`](#addconnector) or AppKit's constructor) or removed, and receives the current list. Use [`watchConnectedWallets`](#watchconnectedwallets) if you want to react to wallet connect/disconnect events instead.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`WatchConnectorsParameters`](#watchconnectorsparameters) | Update callback. |
+| `parameters.onChange`\* | <code>(connectors: readonly <a href="#connector">Connector</a>[]) =&gt; void</code> | Callback invoked when the list of registered connectors changes — receives the current list. |
+
+Returns: <code><a href="#watchconnectorsreturntype">WatchConnectorsReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/connectors#WATCH_CONNECTORS%%
+
+### Crypto Onramp
+
+#### createCryptoOnrampDeposit
+
+Create a crypto-onramp deposit from a quote previously obtained via [`getCryptoOnrampQuote`](#getcryptoonrampquote) — the returned [`CryptoOnrampDeposit`](#cryptoonrampdeposit) carries the address and amount the user must send on the source chain.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`CreateCryptoOnrampDepositOptions`](#createcryptoonrampdepositoptions) | Quote, refund address, and optional provider override. |
+| `options.quote`\* | <code><a href="#cryptoonrampquote">CryptoOnrampQuote</a>&lt;TQuoteMetadata = unknown&gt;</code> | Quote to execute the deposit against (contains recipientAddress and provider metadata) |
+| `options.refundAddress`\* | `string` | Address to refund the crypto to in case of failure |
+| `options.providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `options.providerId` | `string` | Provider to create the deposit through; defaults to `quote.providerId`, then to the default provider. |
+
+Returns: <code><a href="#createcryptoonrampdepositreturntype">CreateCryptoOnrampDepositReturnType</a></code> — Deposit details the UI should show to the user (address, amount, optional `memo`/`expiresAt`).
+
+#### createLayerswapProvider
+
+Build a Layerswap-backed [`CryptoOnrampProvider`](#cryptoonrampprovider) for AppKit; pass the result to [`AppKitConfig`](#appkitconfig)'s `providers` or [`registerProvider`](#registerprovider).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config` | <code><a href="#layerswapproviderconfig">LayerswapProviderConfig</a></code> | Optional [`LayerswapProviderConfig`](#layerswapproviderconfig); defaults are filled in for any field left undefined. |
+
+Returns: <code>ProviderFactory&lt;<a href="#layerswapcryptoonrampprovider">LayerswapCryptoOnrampProvider</a>&gt;</code>.
+
+#### createSwapsXyzProvider
+
+Build a swaps.xyz-backed [`CryptoOnrampProvider`](#cryptoonrampprovider) for AppKit; pass the result to [`AppKitConfig`](#appkitconfig)'s `providers` or [`registerProvider`](#registerprovider).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config`\* | [`SwapsXyzProviderConfig`](#swapsxyzproviderconfig) | Configuration carrying the required `apiKey` plus optional URL/sender overrides. |
+
+Returns: <code>ProviderFactory&lt;<a href="#swapsxyzcryptoonrampprovider">SwapsXyzCryptoOnrampProvider</a>&gt;</code>.
+
+#### 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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options` | [`GetCryptoOnrampProviderOptions`](#getcryptoonrampprovideroptions) | Optional provider id. |
+| `options.id` | `string` | Provider ID to look up; when omitted, returns the registered default provider. |
+
+Returns: <code><a href="#getcryptoonrampproviderreturntype">GetCryptoOnrampProviderReturnType</a></code> — The matching [`CryptoOnrampProviderInterface`](#cryptoonrampproviderinterface).
+
+**Example**
+
+%%docs/examples/src/appkit/actions/onramp#GET_CRYPTO_ONRAMP_PROVIDER%%
+
+#### getCryptoOnrampProviders
+
+List every crypto-onramp provider registered on this AppKit instance — both those passed via [`AppKitConfig`](#appkitconfig)'s `providers` and those added later through [`registerProvider`](#registerprovider).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getcryptoonrampprovidersreturntype">GetCryptoOnrampProvidersReturnType</a></code> — Array of registered [`CryptoOnrampProviderInterface`](#cryptoonrampproviderinterface)s.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/onramp#GET_CRYPTO_ONRAMP_PROVIDERS%%
+
+#### 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`](#createcryptoonrampdeposit).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetCryptoOnrampQuoteOptions`](#getcryptoonrampquoteoptions) | Source asset, target asset, amount and optional provider override. |
+| `options.amount`\* | `string` | Amount to onramp (either source or target crypto, depending on isSourceAmount) |
+| `options.sourceCurrencyAddress`\* | `string` | Source crypto currency address (contract address or 0x0... for native) |
+| `options.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. |
+| `options.targetCurrencyAddress`\* | `string` | Target crypto currency address on TON (contract address or 0x0... for native) |
+| `options.recipientAddress`\* | `string` | TON address that will receive the target crypto |
+| `options.refundAddress` | `string` | Refund address for the source crypto |
+| `options.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. |
+| `options.providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `options.providerId` | `string` | Provider to quote against; defaults to the registered default provider. |
+
+Returns: <code><a href="#getcryptoonrampquotereturntype">GetCryptoOnrampQuoteReturnType</a></code> — 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'`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetCryptoOnrampStatusOptions`](#getcryptoonrampstatusoptions) | Deposit id, originating provider id and optional provider override. |
+| `options.depositId`\* | `string` | Deposit id |
+| `options.providerId`\* | `string` | Identifier of the provider that issued this deposit |
+
+Returns: <code><a href="#getcryptoonrampstatusreturntype">GetCryptoOnrampStatusReturnType</a></code> — Current [`CryptoOnrampStatus`](#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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`WatchCryptoOnrampProvidersParameters`](#watchcryptoonrampprovidersparameters) | Update callback. |
+| `parameters.onChange`\* | `() => void` | Callback fired whenever a crypto-onramp provider is registered or the default crypto-onramp provider changes. |
+
+Returns: <code><a href="#watchcryptoonrampprovidersreturntype">WatchCryptoOnrampProvidersReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+### DeFi
+
+#### registerProvider
+
+Register a DeFi / onramp provider at runtime — equivalent to passing it via [`AppKitConfig`](#appkitconfig)'s `providers` at construction, but available after AppKit is up. AppKit emits `provider:registered`, picked up by domain-specific subscribers like [`watchSwapProviders`](#watchswapproviders) and [`watchCryptoOnrampProviders`](#watchcryptoonrampproviders).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `provider`\* | [`RegisterProviderOptions`](#registerprovideroptions) | Provider instance or factory to register. |
+
+Returns: `void`.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/providers#REGISTER_PROVIDER%%
+
+### Jettons
+
+#### createTransferJettonTransaction
+
+Build a jetton transfer [`TransactionRequest`](#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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`CreateTransferJettonTransactionParameters`](#createtransferjettontransactionparameters) | Jetton, recipient, amount, decimals and optional comment. |
+| `parameters.jettonAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address being transferred. |
+| `parameters.recipientAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Recipient who should receive the jettons. |
+| `parameters.amount`\* | `string` | Amount in jetton units as a human-readable decimal string (e.g., `"1.5"`). |
+| `parameters.jettonDecimals`\* | `number` | Decimals declared by the jetton master; used to convert `amount` into raw smallest units. |
+| `parameters.comment` | `string` | Optional human-readable comment attached to the transfer. |
+
+Returns: <code>Promise&lt;<a href="#createtransferjettontransactionreturntype">CreateTransferJettonTransactionReturnType</a>&gt;</code> — Transaction request ready to pass to `sendTransaction`.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/jettons#CREATE_TRANSFER_JETTON_TRANSACTION%%
+
+#### 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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetJettonBalanceOptions`](#getjettonbalanceoptions) | Jetton master, owner address, decimals and optional network override. |
+| `options.jettonAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address (the token, not the user's wallet for it). |
+| `options.ownerAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Owner of the jetton wallet — typically the connected user's address. |
+| `options.jettonDecimals`\* | `number` | Decimals declared by the jetton master; used to format the raw balance into a human-readable string. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+
+Returns: <code>Promise&lt;<a href="#getjettonbalancereturntype">GetJettonBalanceReturnType</a>&gt;</code> — Balance as a human-readable decimal string in the jetton's units.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/jettons#GET_JETTON_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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetJettonInfoOptions`](#getjettoninfooptions) | Jetton master address and optional network override. |
+| `options.address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address whose metadata is being fetched. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+
+Returns: <code>Promise&lt;<a href="#getjettoninforeturntype">GetJettonInfoReturnType</a>&gt;</code> — Jetton metadata, or `null` if the indexer has no record.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/jettons#GET_JETTON_INFO%%
+
+#### getJettonWalletAddress
+
+Derive the jetton-wallet address for a given owner — the per-owner contract that actually holds the jetton balance for `jettonAddress`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetJettonWalletAddressOptions`](#getjettonwalletaddressoptions) | Jetton master, owner address and optional network override. |
+| `options.jettonAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address. |
+| `options.ownerAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Owner whose jetton wallet should be derived. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+
+Returns: <code>Promise&lt;<a href="#getjettonwalletaddressreturntype">GetJettonWalletAddressReturnType</a>&gt;</code> — User-friendly address of the owner's jetton wallet.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/jettons#GET_JETTON_WALLET_ADDRESS%%
+
+#### getJettons
+
+List jettons held by the currently selected wallet, returning `null` when no wallet is selected (use [`getJettonsByAddress`](#getjettonsbyaddress) for an arbitrary address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options` | [`GetJettonsOptions`](#getjettonsoptions) | Optional network override and pagination. |
+| `options.network` | <code><a href="#network">Network</a></code> | Network to read jettons from. Defaults to the selected wallet's network. |
+| `options.limit` | `number` | Maximum number of jettons to return. |
+| `options.offset` | `number` | Number of jettons to skip before returning results — used for pagination. |
+
+Returns: <code>Promise&lt;<a href="#getjettonsreturntype">GetJettonsReturnType</a>&gt;</code> — Jettons response for the selected wallet, or `null` when none is selected.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/jettons#GET_JETTONS%%
+
+#### getJettonsByAddress
+
+List jettons held by an arbitrary address — useful for inspecting wallets that aren't selected in AppKit (use [`getJettons`](#getjettons) for the selected wallet); raw balances are formatted with each jetton's declared decimals, and entries without decimals are dropped.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetJettonsByAddressOptions`](#getjettonsbyaddressoptions) | Owner address, optional network override and pagination. |
+| `options.address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+| `options.limit` | `number` | Maximum number of jettons to return. |
+| `options.offset` | `number` | Number of jettons to skip before returning results — used for pagination. |
+
+Returns: <code>Promise&lt;<a href="#getjettonsbyaddressreturntype">GetJettonsByAddressReturnType</a>&gt;</code> — Jettons response with formatted balances.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/jettons#GET_JETTONS_BY_ADDRESS%%
+
+#### transferJetton
+
+Build and send a jetton transfer from the selected wallet in one step (use [`createTransferJettonTransaction`](#createtransferjettontransaction) + [`sendTransaction`](#sendtransaction) if you need to inspect the transaction first); throws `Error('Wallet not connected')` if no wallet is currently selected.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`TransferJettonParameters`](#transferjettonparameters) | Jetton, recipient, amount, decimals and optional comment. |
+| `parameters.jettonAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address being transferred. |
+| `parameters.recipientAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Recipient who should receive the jettons. |
+| `parameters.amount`\* | `string` | Amount in jetton units as a human-readable decimal string (e.g., `"1.5"`). |
+| `parameters.jettonDecimals`\* | `number` | Decimals declared by the jetton master; used to convert `amount` into raw smallest units. |
+| `parameters.comment` | `string` | Optional human-readable comment attached to the transfer. |
+
+Returns: <code>Promise&lt;<a href="#transferjettonreturntype">TransferJettonReturnType</a>&gt;</code> — Wallet response carrying the BoC of the sent transaction.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/jettons#TRANSFER_JETTON%%
+
+#### watchJettons
+
+Subscribe to jetton-balance updates for the currently selected wallet, automatically rebinding when the user connects, switches, or disconnects (use [`watchJettonsByAddress`](#watchjettonsbyaddress) for a fixed address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`WatchJettonsOptions`](#watchjettonsoptions) | Update callback and optional network override. |
+| `options.onChange`\* | <code>(update: <a href="#jettonupdate">JettonUpdate</a>) =&gt; void</code> | Callback fired on every jetton-balance update from the streaming provider. |
+| `options.network` | <code><a href="#network">Network</a></code> | Network to watch on. Defaults to the selected wallet's network. |
+
+Returns: <code><a href="#watchjettonsreturntype">WatchJettonsReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+#### watchJettonsByAddress
+
+Subscribe to jetton-balance updates for an arbitrary owner address (use [`watchJettons`](#watchjettons) for the selected wallet).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`WatchJettonsByAddressOptions`](#watchjettonsbyaddressoptions) | Owner address, update callback and optional network override. |
+| `options.address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `options.onChange`\* | <code>(update: <a href="#jettonupdate">JettonUpdate</a>) =&gt; void</code> | Callback fired on every jetton-balance update from the streaming provider. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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: <code><a href="#watchjettonsbyaddressreturntype">WatchJettonsByAddressReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+### NFTs
+
+#### createTransferNftTransaction
+
+Build an NFT transfer [`TransactionRequest`](#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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`CreateTransferNftTransactionParameters`](#createtransfernfttransactionparameters) | NFT, recipient, optional gas amount and comment. |
+| `parameters.nftAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | NFT contract address to transfer. |
+| `parameters.recipientAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | New owner address. |
+| `parameters.amount` | `string` | Amount of TON to attach to the transfer for gas; defaults to AppKit's NFT gas-fee constant when omitted. |
+| `parameters.comment` | `string` | Optional human-readable comment attached to the transfer. |
+
+Returns: <code>Promise&lt;<a href="#createtransfernfttransactionreturntype">CreateTransferNftTransactionReturnType</a>&gt;</code> — Transaction request ready to pass to `sendTransaction`.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/nft#CREATE_TRANSFER_NFT_TRANSACTION%%
+
+#### getNft
+
+Fetch metadata and ownership for a single NFT by its contract address; returns `null` when the indexer has no record.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetNftOptions`](#getnftoptions) | NFT address and optional network override. |
+| `options.address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | NFT contract address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+
+Returns: <code>Promise&lt;<a href="#getnftreturntype">GetNftReturnType</a>&gt;</code> — NFT data, or `null` if the indexer has no record.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/nft#GET_NFT%%
+
+#### getNfts
+
+List NFTs held by the currently selected wallet, returning `null` when no wallet is selected (use [`getNftsByAddress`](#getnftsbyaddress) for an arbitrary address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options` | [`GetNftsOptions`](#getnftsoptions) | Optional network override and pagination. |
+| `options.network` | <code><a href="#network">Network</a></code> | Network to read NFTs from. Defaults to the selected wallet's network. |
+| `options.limit` | `number` | Maximum number of NFTs to return. |
+| `options.offset` | `number` | Number of NFTs to skip before returning results — used for pagination. |
+
+Returns: <code>Promise&lt;<a href="#getnftsreturntype">GetNftsReturnType</a>&gt;</code> — NFTs response for the selected wallet, or `null` when none is selected.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/nft#GET_NFTS%%
+
+#### getNftsByAddress
+
+List NFTs held by an arbitrary address — useful for inspecting wallets that aren't selected in AppKit (use [`getNfts`](#getnfts) for the selected wallet).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetNftsByAddressOptions`](#getnftsbyaddressoptions) | Owner address, optional network override and pagination. |
+| `options.address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+| `options.limit` | `number` | Maximum number of NFTs to return. |
+| `options.offset` | `number` | Number of NFTs to skip before returning results — used for pagination. |
+
+Returns: <code>Promise&lt;<a href="#getnftsbyaddressreturntype">GetNftsByAddressReturnType</a>&gt;</code> — NFTs response with the owner's items.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/nft#GET_NFTS_BY_ADDRESS%%
+
+#### transferNft
+
+Build and send an NFT transfer from the selected wallet in one step (use [`createTransferNftTransaction`](#createtransfernfttransaction) + [`sendTransaction`](#sendtransaction) if you need to inspect the transaction first); throws `Error('Wallet not connected')` if no wallet is currently selected.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`TransferNftParameters`](#transfernftparameters) | NFT, recipient, optional gas amount and comment. |
+| `parameters.nftAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | NFT contract address to transfer. |
+| `parameters.recipientAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | New owner address. |
+| `parameters.amount` | `string` | Amount of TON to attach to the transfer for gas; defaults to AppKit's NFT gas-fee constant when omitted. |
+| `parameters.comment` | `string` | Optional human-readable comment attached to the transfer. |
+
+Returns: <code>Promise&lt;<a href="#transfernftreturntype">TransferNftReturnType</a>&gt;</code> — Wallet response carrying the BoC of the sent transaction.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/nft#TRANSFER_NFT%%
+
+### 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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options` | [`GetBlockNumberOptions`](#getblocknumberoptions) | Optional network override. |
+| `options.network` | <code><a href="#network">Network</a></code> | Network to query. Defaults to mainnet when omitted. |
+
+Returns: <code>Promise&lt;<a href="#getblocknumberreturntype">GetBlockNumberReturnType</a>&gt;</code> — Current masterchain seqno as a number.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/network#GET_BLOCK_NUMBER%%
+
+#### getDefaultNetwork
+
+Read AppKit's currently configured default network — the one connectors enforce on new wallet connections; `undefined` means any registered network is allowed.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getdefaultnetworkreturntype">GetDefaultNetworkReturnType</a></code> — The default [`Network`](#network), or `undefined` if none is set.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/network#GET_DEFAULT_NETWORK%%
+
+#### getNetwork
+
+Read the [`Network`](#network) the selected wallet is connected to, or `null` when no wallet is selected (use [`getDefaultNetwork`](#getdefaultnetwork) for AppKit's configured default).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getnetworkreturntype">GetNetworkReturnType</a></code> — Network of the selected wallet, or `null` when none is selected.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/network#GET_NETWORK%%
+
+#### getNetworks
+
+List every network configured on this AppKit instance via [`AppKitConfig`](#appkitconfig)'s `networks`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getnetworksreturntype">GetNetworksReturnType</a></code> — Array of configured [`Network`](#network)s.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/network#GET_NETWORKS%%
+
+#### hasStreamingProvider
+
+Check whether a streaming provider is registered for a network — required by [`watchBalance`](#watchbalance), [`watchJettons`](#watchjettons) and other live-update actions.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `network`\* | [`Network`](#network) | Network to check. |
+
+Returns: <code><a href="#hasstreamingproviderreturntype">HasStreamingProviderReturnType</a></code> — `true` when a streaming provider is registered for that network.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/network#HAS_STREAMING_PROVIDER%%
+
+#### setDefaultNetwork
+
+Set or clear the default network — connectors enforce it on new wallet connections; emits `NETWORKS_EVENTS.DEFAULT_CHANGED` so [`watchDefaultNetwork`](#watchdefaultnetwork) subscribers fire. Pass `undefined` to remove the constraint and allow any registered network.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`SetDefaultNetworkParameters`](#setdefaultnetworkparameters) | Network to enforce, or `undefined` to clear. |
+| `parameters.network`\* | <code><a href="#network">Network</a> \| undefined</code> | Network to enforce on new wallet connections; pass `undefined` to allow any registered network. |
+
+Returns: <code><a href="#setdefaultnetworkreturntype">SetDefaultNetworkReturnType</a></code>.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/network#SET_DEFAULT_NETWORK%%
+
+#### watchDefaultNetwork
+
+Subscribe to default-network changes — fires when [`setDefaultNetwork`](#setdefaultnetwork) is called.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`WatchDefaultNetworkParameters`](#watchdefaultnetworkparameters) | Update callback. |
+| `parameters.onChange`\* | <code>(network: <a href="#network">Network</a> \| undefined) =&gt; void</code> | Callback fired whenever [`setDefaultNetwork`](#setdefaultnetwork) updates the default — receives the new value (or `undefined` when cleared). |
+
+Returns: <code><a href="#watchdefaultnetworkreturntype">WatchDefaultNetworkReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/network#WATCH_DEFAULT_NETWORK%%
+
+#### watchNetworks
+
+Subscribe to changes of the configured-networks list — fires when AppKit's network manager registers or replaces a network's API client.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`WatchNetworksParameters`](#watchnetworksparameters) | Update callback. |
+| `parameters.onChange`\* | <code>(networks: <a href="#network">Network</a>[]) =&gt; void</code> | Callback fired whenever the configured-networks list changes — receives the latest snapshot. |
+
+Returns: <code><a href="#watchnetworksreturntype">WatchNetworksReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/network#WATCH_NETWORKS%%
+
+### Signing
+
+#### signBinary
+
+Ask the selected wallet to sign a binary blob; throws `Error('Wallet not connected')` if no wallet is currently selected.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`SignBinaryParameters`](#signbinaryparameters) | Binary content and optional network override. |
+| `parameters.bytes`\* | <code><a href="#base64string">Base64String</a></code> | Binary blob the user is asked to sign, encoded as Base64. |
+| `parameters.network` | <code><a href="#network">Network</a></code> | Network to issue the sign request against. Defaults to AppKit's configured default network; when none is set, the wallet falls back to its current network. |
+
+Returns: <code>Promise&lt;<a href="#signbinaryreturntype">SignBinaryReturnType</a>&gt;</code> — Signature and signed payload, as returned by the wallet.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/signing#SIGN_BINARY%%
+
+#### 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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`SignCellParameters`](#signcellparameters) | Cell content, TL-B schema and optional network override. |
+| `parameters.cell`\* | <code><a href="#base64string">Base64String</a></code> | TON cell content encoded as Base64 (BoC). |
+| `parameters.schema`\* | `string` | TL-B-style schema describing the cell layout so the wallet can render the payload to the user. |
+| `parameters.network` | <code><a href="#network">Network</a></code> | Network to issue the sign request against. Defaults to AppKit's configured default network; when none is set, the wallet falls back to its current network. |
+
+Returns: <code>Promise&lt;<a href="#signcellreturntype">SignCellReturnType</a>&gt;</code> — Signature and signed payload, as returned by the wallet.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/signing#SIGN_CELL%%
+
+#### signText
+
+Ask the selected wallet to sign a plain text message; throws `Error('Wallet not connected')` if no wallet is currently selected.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`SignTextParameters`](#signtextparameters) | Text to sign and optional network override. |
+| `parameters.text`\* | `string` | UTF-8 text the user is asked to sign. |
+| `parameters.network` | <code><a href="#network">Network</a></code> | Network to issue the sign request against. Defaults to AppKit's configured default network; when none is set, the wallet falls back to its current network. |
+
+Returns: <code>Promise&lt;<a href="#signtextreturntype">SignTextReturnType</a>&gt;</code> — Signature and signed payload, as returned by the wallet.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/signing#SIGN_TEXT%%
+
+### Staking
+
+#### buildStakeTransaction
+
+Build a [`TransactionRequest`](#transactionrequest) that executes a stake or unstake previously quoted by [`getStakingQuote`](#getstakingquote) — returns it without sending so the UI can inspect or batch before signing.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`BuildStakeTransactionOptions`](#buildstaketransactionoptions) | Quote and optional provider override. |
+| `options.quote`\* | <code><a href="#stakingquote">StakingQuote</a></code> | The staking quote based on which the transaction is built |
+| `options.userAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the user performing the staking |
+| `options.providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `options.providerId` | `string` | Provider to stake/unstake through; defaults to the registered default staking provider. |
+
+Returns: <code><a href="#buildstaketransactionreturntype">BuildStakeTransactionReturnType</a></code> — Transaction request ready to pass to `sendTransaction`.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/staking#BUILD_STAKE_TRANSACTION%%
+
+#### createTonstakersProvider
+
+Build a Tonstakers-backed [`StakingProvider`](#stakingprovider) for AppKit; pass the result to [`AppKitConfig`](#appkitconfig)'s `providers` or [`registerProvider`](#registerprovider).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config` | <code><a href="#tonstakersproviderconfig">TonStakersProviderConfig</a></code> | Optional [`TonStakersProviderConfig`](#tonstakersproviderconfig); defaults are filled in for any field left undefined. |
+
+Returns: <code>(ctx: <a href="#providerfactorycontext">ProviderFactoryContext</a>) =&gt; <a href="#tonstakersstakingprovider">TonStakersStakingProvider</a></code>.
+
+#### 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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetStakedBalanceOptions`](#getstakedbalanceoptions) | Owner address and optional network/provider override. |
+| `options.userAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Owner whose staked balance should be read. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+| `options.providerId` | `string` | Provider to query; defaults to the registered default staking provider. |
+
+Returns: <code><a href="#getstakedbalancereturntype">GetStakedBalanceReturnType</a></code> — Staked-balance breakdown ([`StakingBalance`](#stakingbalance)) for the user on the resolved network/provider.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/staking#GET_STAKED_BALANCE%%
+
+#### getStakingManager
+
+Read AppKit's [`StakingManager`](#stakingmanager) — the runtime that owns registered staking providers and dispatches quote/stake/balance calls. Apps usually use the higher-level actions ([`getStakingQuote`](#getstakingquote), [`buildStakeTransaction`](#buildstaketransaction), [`getStakedBalance`](#getstakedbalance)) instead of touching the manager directly.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getstakingmanagerreturntype">GetStakingManagerReturnType</a></code> — The [`StakingManager`](#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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options` | [`GetStakingProviderOptions`](#getstakingprovideroptions) | Optional provider id. |
+| `options.id` | `string` | Provider ID to look up; when omitted, returns the registered default staking provider. |
+
+Returns: <code><a href="#getstakingproviderreturntype">GetStakingProviderReturnType</a></code> — 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`](#getstakingprovidermetadata) for static metadata (display name, stake/receive tokens, supported unstake modes).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options` | [`GetStakingProviderInfoOptions`](#getstakingproviderinfooptions) | Optional network and provider override. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+| `options.providerId` | `string` | Provider to query; defaults to the registered default staking provider. |
+
+Returns: <code><a href="#getstakingproviderinforeturntype">GetStakingProviderInfoReturnType</a></code> — Live staking-provider info for the resolved network.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/staking#GET_STAKING_PROVIDER_INFO%%
+
+#### getStakingProviderMetadata
+
+Read static metadata for a staking provider — display name, stake/receive tokens, supported unstake modes, contract address. Use [`getStakingProviderInfo`](#getstakingproviderinfo) for live values (APY, instant-unstake liquidity, exchange rate).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options` | [`GetStakingProviderMetadataOptions`](#getstakingprovidermetadataoptions) | Optional network and provider override. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+| `options.providerId` | `string` | Provider to query; defaults to the registered default staking provider. |
+
+Returns: <code><a href="#getstakingprovidermetadatareturntype">GetStakingProviderMetadataReturnType</a></code> — Static [`StakingProviderMetadata`](#stakingprovidermetadata) for the resolved provider.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/staking#GET_STAKING_PROVIDER_METADATA%%
+
+#### getStakingProviders
+
+List every staking provider registered on this AppKit instance — both those passed via [`AppKitConfig`](#appkitconfig)'s `providers` and those added later through [`registerProvider`](#registerprovider).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getstakingprovidersreturntype">GetStakingProvidersReturnType</a></code> — Array of registered staking providers.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/staking#GET_STAKING_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`](#buildstaketransaction).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetStakingQuoteOptions`](#getstakingquoteoptions) | Quote parameters and optional provider override. |
+| `options.direction`\* | <code><a href="#stakingquotedirection">StakingQuoteDirection</a></code> | Direction of the quote (stake or unstake) |
+| `options.amount`\* | `string` | Amount of tokens to stake or unstake |
+| `options.userAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the user |
+| `options.network` | <code><a href="#network">Network</a></code> | Network on which the staking will be executed |
+| `options.unstakeMode` | <code><a href="#unstakemodes">UnstakeModes</a></code> | Requested mode of unstaking |
+| `options.isReversed` | `boolean` | If true, for unstake requests the amount is specified in the staking coin (e.g. TON) instead of the Liquid Staking Token (e.g. tsTON). |
+| `options.providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `options.providerId` | `string` | Provider to quote against; defaults to the registered default staking provider. |
+
+Returns: <code><a href="#getstakingquotereturntype">GetStakingQuoteReturnType</a></code> — Quote with pricing details and provider metadata.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/staking#GET_STAKING_QUOTE%%
+
+#### setDefaultStakingProvider
+
+Set the default staking provider — subsequent [`getStakingQuote`](#getstakingquote) and [`buildStakeTransaction`](#buildstaketransaction) calls without an explicit `providerId` route through it. Emits `provider:default-changed`, picked up by [`watchStakingProviders`](#watchstakingproviders).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`SetDefaultStakingProviderParameters`](#setdefaultstakingproviderparameters) | ID of the provider to make default. |
+| `parameters.providerId`\* | `string` | ID of the provider to make default — must already be registered. |
+
+Returns: <code><a href="#setdefaultstakingproviderreturntype">SetDefaultStakingProviderReturnType</a></code>.
+
+#### watchStakingProviders
+
+Subscribe to staking provider lifecycle — fires `onChange` whenever a new provider is registered or the default staking provider switches.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`WatchStakingProvidersParameters`](#watchstakingprovidersparameters) | Update callback. |
+| `parameters.onChange`\* | `() => void` | Callback fired whenever a staking provider is registered or the default staking provider changes. |
+
+Returns: <code><a href="#watchstakingprovidersreturntype">WatchStakingProvidersReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+### Swap
+
+#### buildSwapTransaction
+
+Build a [`TransactionRequest`](#transactionrequest) that executes a swap previously quoted by [`getSwapQuote`](#getswapquote) — returns it without sending so the UI can inspect or batch before signing.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`BuildSwapTransactionOptions`](#buildswaptransactionoptions) | Quote and provider-specific options. |
+| `options.quote`\* | <code><a href="#swapquote">SwapQuote</a></code> | The swap quote based on which the transaction is built |
+| `options.userAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the user performing the swap |
+| `options.destinationAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address to receive the swapped tokens (defaults to userAddress) |
+| `options.slippageBps` | `number` | Slippage tolerance in basis points (1 bp = 0.01%) |
+| `options.deadline` | `number` | Transaction deadline in unix timestamp |
+| `options.providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+
+Returns: <code><a href="#buildswaptransactionreturntype">BuildSwapTransactionReturnType</a></code> — Transaction request ready to pass to `sendTransaction`.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/swap#BUILD_SWAP_TRANSACTION%%
+
+#### createDeDustProvider
+
+Build a DeDust-backed [`SwapProvider`](#swapprovider) for AppKit; pass the result to [`AppKitConfig`](#appkitconfig)'s `providers` or [`registerProvider`](#registerprovider).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config` | <code><a href="#dedustswapproviderconfig">DeDustSwapProviderConfig</a></code> | Optional [`DeDustSwapProviderConfig`](#dedustswapproviderconfig); defaults are filled in for any field left undefined. |
+
+Returns: <code>(ctx: <a href="#providerfactorycontext">ProviderFactoryContext</a>) =&gt; <a href="#dedustswapprovider">DeDustSwapProvider</a></code>.
+
+#### createOmnistonProvider
+
+Build an Omniston-backed [`SwapProvider`](#swapprovider) for AppKit; pass the result to [`AppKitConfig`](#appkitconfig)'s `providers` or [`registerProvider`](#registerprovider).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config` | <code><a href="#omnistonswapproviderconfig">OmnistonSwapProviderConfig</a></code> | Optional [`OmnistonSwapProviderConfig`](#omnistonswapproviderconfig); defaults are filled in for any field left undefined. |
+
+Returns: <code>(ctx: <a href="#providerfactorycontext">ProviderFactoryContext</a>) =&gt; <a href="#omnistonswapprovider">OmnistonSwapProvider</a></code>.
+
+#### getSwapManager
+
+Read AppKit's [`SwapManager`](#swapmanager) — the runtime that owns registered swap providers and dispatches quote/build calls. Apps usually use the higher-level actions ([`getSwapQuote`](#getswapquote), [`buildSwapTransaction`](#buildswaptransaction)) instead of touching the manager directly.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getswapmanagerreturntype">GetSwapManagerReturnType</a></code> — The [`SwapManager`](#swapmanager) bound to this AppKit instance.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/swap#GET_SWAP_MANAGER%%
+
+#### 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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options` | [`GetSwapProviderOptions`](#getswapprovideroptions) | Optional provider id. |
+| `options.id` | `string` | Provider ID to look up; when omitted, returns the registered default swap provider. |
+
+Returns: <code><a href="#getswapproviderreturntype">GetSwapProviderReturnType</a></code> — The matching swap provider instance.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/swap#GET_SWAP_PROVIDER%%
+
+#### getSwapProviders
+
+List every swap provider registered on this AppKit instance — both those passed via [`AppKitConfig`](#appkitconfig)'s `providers` and those added later through [`registerProvider`](#registerprovider).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getswapprovidersreturntype">GetSwapProvidersReturnType</a></code> — Array of registered swap providers.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/swap#GET_SWAP_PROVIDERS%%
+
+#### getSwapQuote
+
+Quote a swap — given source/target tokens and an amount, returns the rate, expected output and provider metadata needed to call [`buildSwapTransaction`](#buildswaptransaction).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetSwapQuoteOptions`](#getswapquoteoptions) | Source and target tokens, amount, optional network and provider override. |
+| `options.amount`\* | `string` | Amount of tokens to swap (incoming or outgoing depending on isReverseSwap) |
+| `options.from`\* | <code><a href="#swaptoken">SwapToken</a></code> | Token to swap from |
+| `options.to`\* | <code><a href="#swaptoken">SwapToken</a></code> | Token to swap to |
+| `options.network`\* | <code><a href="#network">Network</a></code> | Network on which the swap will be executed |
+| `options.slippageBps` | `number` | Slippage tolerance in basis points (1 bp = 0.01%) |
+| `options.maxOutgoingMessages` | `number` | Maximum number of outgoing messages |
+| `options.providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `options.isReverseSwap` | `boolean` | If true, amount is the amount to receive (buy). If false, amount is the amount to spend (sell). |
+| `options.providerId` | `string` | Provider to quote against; defaults to the registered default swap provider. |
+
+Returns: <code><a href="#getswapquotereturntype">GetSwapQuoteReturnType</a></code> — Quote with pricing details and the provider metadata required to build a transaction.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/swap#GET_SWAP_QUOTE%%
+
+#### setDefaultSwapProvider
+
+Set the default swap provider — subsequent [`getSwapQuote`](#getswapquote) and [`buildSwapTransaction`](#buildswaptransaction) calls without an explicit `providerId` route through it. Emits `provider:default-changed`, picked up by [`watchSwapProviders`](#watchswapproviders).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`SetDefaultSwapProviderParameters`](#setdefaultswapproviderparameters) | ID of the provider to make default. |
+| `parameters.providerId`\* | `string` | ID of the provider to make default — must already be registered. |
+
+Returns: <code><a href="#setdefaultswapproviderreturntype">SetDefaultSwapProviderReturnType</a></code>.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/swap#SET_DEFAULT_SWAP_PROVIDER%%
+
+#### watchSwapProviders
+
+Subscribe to swap provider lifecycle — fires `onChange` whenever a new provider is registered or the default swap provider switches.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`WatchSwapProvidersParameters`](#watchswapprovidersparameters) | Update callback. |
+| `parameters.onChange`\* | `() => void` | Callback fired whenever a swap provider is registered or the default swap provider changes. |
+
+Returns: <code><a href="#watchswapprovidersreturntype">WatchSwapProvidersReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/swap#WATCH_SWAP_PROVIDERS%%
+
+### Transactions
+
+#### createTransferTonTransaction
+
+Build a TON transfer [`TransactionRequest`](#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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`CreateTransferTonTransactionParameters`](#createtransfertontransactionparameters) | Recipient, amount and optional payload/comment/stateInit. |
+| `parameters.recipientAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Recipient address. |
+| `parameters.amount`\* | `string` | Amount in TON as a human-readable decimal string (e.g., `"1.5"`); converted to nano-TON internally. |
+| `parameters.comment` | `string` | Human-readable text comment; converted to a Base64 payload when no `payload` is supplied. |
+| `parameters.payload` | <code><a href="#base64string">Base64String</a></code> | Raw Base64 message payload — wins over `comment` when both are set. |
+| `parameters.stateInit` | <code><a href="#base64string">Base64String</a></code> | Initial state for deploying a new contract, encoded as Base64. |
+
+Returns: <code><a href="#createtransfertontransactionreturntype">CreateTransferTonTransactionReturnType</a></code> — Transaction request ready to pass to `sendTransaction`.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/transaction#CREATE_TRANSFER_TON_TRANSACTION%%
+
+#### 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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`GetTransactionStatusParameters`](#gettransactionstatusparameters) | `boc` xor `normalizedHash` and optional network override. |
+
+Returns: <code>Promise&lt;<a href="#gettransactionstatusreturntype">GetTransactionStatusReturnType</a>&gt;</code> — Status response with current state, completed/total message counts and trace details.
+
+#### sendTransaction
+
+Hand a pre-built [`TransactionRequest`](#transactionrequest) to the selected wallet for signing and broadcast — usually the second step after [`createTransferTonTransaction`](#createtransfertontransaction), [`buildSwapTransaction`](#buildswaptransaction) or [`buildStakeTransaction`](#buildstaketransaction); throws `Error('Wallet not connected')` if no wallet is currently selected.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`SendTransactionParameters`](#sendtransactionparameters) | Transaction request to broadcast. |
+
+Returns: <code>Promise&lt;<a href="#sendtransactionreturntype">SendTransactionReturnType</a>&gt;</code> — Wallet response carrying the BoC of the sent transaction.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/transaction#SEND_TRANSACTION%%
+
+#### transferTon
+
+Build and send a TON transfer from the selected wallet in one step (use [`createTransferTonTransaction`](#createtransfertontransaction) + [`sendTransaction`](#sendtransaction) if you need to inspect the transaction first); throws `Error('Wallet not connected')` if no wallet is currently selected.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`TransferTonParameters`](#transfertonparameters) | Recipient, amount and optional payload/comment/stateInit. |
+| `parameters.recipientAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Recipient address. |
+| `parameters.amount`\* | `string` | Amount in TON as a human-readable decimal string (e.g., `"1.5"`); converted to nano-TON internally. |
+| `parameters.comment` | `string` | Human-readable text comment; converted to a Base64 payload when no `payload` is supplied. |
+| `parameters.payload` | <code><a href="#base64string">Base64String</a></code> | Raw Base64 message payload — wins over `comment` when both are set. |
+| `parameters.stateInit` | <code><a href="#base64string">Base64String</a></code> | Initial state for deploying a new contract, encoded as Base64. |
+
+Returns: <code>Promise&lt;<a href="#transfertonreturntype">TransferTonReturnType</a>&gt;</code> — Wallet response carrying the BoC of the sent transaction.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/transaction#TRANSFER_TON%%
+
+#### watchTransactions
+
+Subscribe to incoming-transaction events for the currently selected wallet, automatically rebinding when the user connects, switches, or disconnects (use [`watchTransactionsByAddress`](#watchtransactionsbyaddress) for a fixed address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`WatchTransactionsOptions`](#watchtransactionsoptions) | Update callback and optional network override. |
+| `options.onChange`\* | <code>(update: <a href="#transactionsupdate">TransactionsUpdate</a>) =&gt; void</code> | Callback fired on every transactions update from the streaming provider. |
+| `options.network` | <code><a href="#network">Network</a></code> | Network to watch on. Defaults to the selected wallet's network. |
+
+Returns: <code><a href="#watchtransactionsreturntype">WatchTransactionsReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+#### watchTransactionsByAddress
+
+Subscribe to incoming-transaction events for an arbitrary address (use [`watchTransactions`](#watchtransactions) for the selected wallet).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`WatchTransactionsByAddressOptions`](#watchtransactionsbyaddressoptions) | Address, update callback and optional network override. |
+| `options.address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Address to watch — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `options.onChange`\* | <code>(update: <a href="#transactionsupdate">TransactionsUpdate</a>) =&gt; void</code> | Callback fired on every transactions update from the streaming provider. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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: <code><a href="#watchtransactionsbyaddressreturntype">WatchTransactionsByAddressReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+### Wallets
+
+#### getConnectedWallets
+
+List every wallet currently connected through any registered [`Connector`](#connector).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getconnectedwalletsreturntype">GetConnectedWalletsReturnType</a></code> — Read-only array of [`WalletInterface`](#walletinterface)s.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/wallets#GET_CONNECTED_WALLETS%%
+
+#### getSelectedWallet
+
+Read the wallet AppKit treats as "active" — most actions ([`getBalance`](#getbalance), [`signText`](#signtext), [`transferTon`](#transferton)) target this wallet implicitly. Returns `null` when no wallet is connected or selected.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getselectedwalletreturntype">GetSelectedWalletReturnType</a></code> — Selected [`WalletInterface`](#walletinterface), or `null` when none is selected.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/wallets#GET_SELECTED_WALLET%%
+
+#### setSelectedWalletId
+
+Switch which connected wallet AppKit treats as selected — emits `WALLETS_EVENTS.SELECTION_CHANGED` so [`watchSelectedWallet`](#watchselectedwallet) subscribers fire. Pass `null` to clear the selection.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`SetSelectedWalletIdParameters`](#setselectedwalletidparameters) | Wallet ID to select, or `null` to clear. |
+| `parameters.walletId`\* | `string \| null` | Wallet ID (as returned by [`WalletInterface`](#walletinterface)'s `getWalletId()`) to select; pass `null` to clear the selection. |
+
+Returns: <code><a href="#setselectedwalletidreturntype">SetSelectedWalletIdReturnType</a></code>.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/wallets#SET_SELECTED_WALLET_ID%%
+
+#### watchConnectedWallets
+
+Subscribe to the list of connected wallets — fires whenever a wallet connects or disconnects through any registered [`Connector`](#connector).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`WatchConnectedWalletsParameters`](#watchconnectedwalletsparameters) | Update callback. |
+| `parameters.onChange`\* | <code>(wallets: <a href="#walletinterface">WalletInterface</a>[]) =&gt; void</code> | Callback fired whenever the list of connected wallets changes — receives the latest snapshot. |
+
+Returns: <code><a href="#watchconnectedwalletsreturntype">WatchConnectedWalletsReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/wallets#WATCH_CONNECTED_WALLETS%%
+
+#### watchSelectedWallet
+
+Subscribe to selected-wallet changes — fires when [`setSelectedWalletId`](#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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`WatchSelectedWalletParameters`](#watchselectedwalletparameters) | Update callback. |
+| `parameters.onChange`\* | <code>(wallet: <a href="#walletinterface">WalletInterface</a> \| null) =&gt; void</code> | Callback fired whenever the selected wallet changes — receives the new wallet, or `null` when the selection was cleared. |
+
+Returns: <code><a href="#watchselectedwalletreturntype">WatchSelectedWalletReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+**Example**
+
+%%docs/examples/src/appkit/actions/wallets#WATCH_SELECTED_WALLET%%
+
+## Type
+
+### Balances
+
+#### BalanceUpdate
+
+Update payload delivered to [`watchBalance`](#watchbalance) / [`watchBalanceByAddress`](#watchbalancebyaddress) subscribers when the watched address's TON balance changes.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `type`\* | `'balance'` | The update type field |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The account address |
+| `rawBalance`\* | <code><a href="#tokenamount">TokenAmount</a></code> | The account balance in nano units |
+| `balance`\* | `string` | The formatted balance |
+| `status`\* | <code><a href="#streamingupdatestatus">StreamingUpdateStatus</a></code> | The finality of the update |
+
+#### GetBalanceByAddressOptions
+
+Options for [`getBalanceByAddress`](#getbalancebyaddress).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Wallet address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+
+#### GetBalanceByAddressReturnType
+
+Return type of [`getBalanceByAddress`](#getbalancebyaddress).
+
+```ts
+type GetBalanceByAddressReturnType = TokenAmount;
+```
+
+#### GetBalanceOptions
+
+Options for [`getBalance`](#getbalance).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="#network">Network</a></code> | Network to read the balance from. Defaults to the selected wallet's network. |
+
+#### GetBalanceReturnType
+
+Return type of [`getBalance`](#getbalance).
+
+```ts
+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).
+
+```ts
+type StreamingUpdateStatus = 'pending' | 'confirmed' | 'finalized' | 'invalidated';
+```
+
+#### WatchBalanceByAddressOptions
+
+Options for [`watchBalanceByAddress`](#watchbalancebyaddress).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Wallet address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+| `onChange`\* | <code>(update: <a href="#balanceupdate">BalanceUpdate</a>) =&gt; void</code> | Callback fired on every balance update from the streaming provider. |
+
+#### WatchBalanceByAddressReturnType
+
+Return type of [`watchBalanceByAddress`](#watchbalancebyaddress) — call to stop receiving updates.
+
+```ts
+type WatchBalanceByAddressReturnType = () => void;
+```
+
+#### WatchBalanceOptions
+
+Options for [`watchBalance`](#watchbalance).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="#network">Network</a></code> | Network to watch on. Defaults to the selected wallet's network. |
+| `onChange`\* | <code>(update: <a href="#balanceupdate">BalanceUpdate</a>) =&gt; void</code> | Callback fired on every balance update from the streaming provider. |
+
+#### WatchBalanceReturnType
+
+Return type of [`watchBalance`](#watchbalance) — call to stop receiving updates.
+
+```ts
+type WatchBalanceReturnType = () => void;
+```
+
+### Client
+
+#### AddressBook
+
+Map of raw addresses to their resolved metadata, returned alongside indexed lists (e.g. [`JettonsResponse`](#jettonsresponse), [`NFTsResponse`](#nftsresponse)) so consumers can render labels without extra lookups.
+
+```ts
+type AddressBook = {
+    [key: UserFriendlyAddress]: AddressBookEntry;
+};
+```
+
+#### AddressBookEntry
+
+Single entry inside an [`AddressBook`](#addressbook) — pairs the user-friendly address with optional domain name and the list of contract interfaces it implements.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The human-readable representation of the blockchain address |
+| `domain` | `string` | The domain name associated with the address if available |
+| `interfaces`\* | `string[]` | List of supported interfaces by the address |
+
+#### ApiClient
+
+Indexer/RPC client interface used by AppKit to read on-chain state — balance, jettons, NFTs, masterchain seqno, etc. Each [`Network`](#network) resolves to its own `ApiClient` via [`AppKitNetworkManager`](#appkitnetworkmanager); apps usually pull one through [`getApiClient`](#getapiclient) rather than constructing it directly.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `nftItemsByAddress`\* | <code>(request: NFTsRequest) =&gt; Promise&lt;<a href="#nftsresponse">NFTsResponse</a>&gt;</code> | Look up specific NFT items by address. |
+| `nftItemsByOwner`\* | <code>(request: UserNFTsRequest) =&gt; Promise&lt;<a href="#nftsresponse">NFTsResponse</a>&gt;</code> | List NFT items held by an owner; supports pagination. |
+| `fetchEmulation`\* | <code>(messageBoc: <a href="#base64string">Base64String</a>, ignoreSignature?: boolean) =&gt; Promise&lt;ToncenterEmulationResult&gt;</code> | Run an emulation pass on a Base64-encoded BoC; returns the predicted account-state changes and emitted events without sending the message. |
+| `sendBoc`\* | <code>(boc: <a href="#base64string">Base64String</a>) =&gt; Promise&lt;string&gt;</code> | Broadcast a signed BoC to the network and return the message hash. |
+| `runGetMethod`\* | <code>(address: <a href="#userfriendlyaddress">UserFriendlyAddress</a>, method: string, stack?: RawStackItem[], seqno?: number) =&gt; Promise&lt;GetMethodResult&gt;</code> | Run an on-chain `get` method against a contract and read its TVM stack output. |
+| `getAccountState`\* | <code>(address: <a href="#userfriendlyaddress">UserFriendlyAddress</a>, seqno?: number) =&gt; Promise&lt;FullAccountState&gt;</code> | Read the full on-chain account state (code, data, status, balance) for an address. |
+| `getBalance`\* | <code>(address: <a href="#userfriendlyaddress">UserFriendlyAddress</a>, seqno?: number) =&gt; Promise&lt;<a href="#tokenamount">TokenAmount</a>&gt;</code> | Read the TON balance of an address in raw nanotons. |
+| `getAccountTransactions`\* | `(request: TransactionsByAddressRequest) => Promise<TransactionsResponse>` | List transactions for an address; ordered newest-first, paginated via `LimitRequest`. |
+| `getTransactionsByHash`\* | `(request: GetTransactionByHashRequest) => Promise<TransactionsResponse>` | Fetch a transaction by its message or body hash. |
+| `getPendingTransactions`\* | `(request: GetPendingTransactionsRequest) => Promise<TransactionsResponse>` | List pending (unconfirmed) transactions by accounts or trace ids; useful for "in-flight" UIs. |
+| `getTrace`\* | `(request: GetTraceRequest) => Promise<ToncenterTracesResponse>` | Fetch a confirmed trace (the tree of internal messages spawned by an external one). |
+| `getPendingTrace`\* | `(request: GetPendingTraceRequest) => Promise<ToncenterTracesResponse>` | Fetch a pending trace by external-message hash, while it's still in flight. |
+| `resolveDnsWallet`\* | `(domain: string) => Promise<string \| null>` | Resolve a TON DNS domain to the wallet address it points at; `null` when unset. |
+| `backResolveDnsWallet`\* | <code>(address: <a href="#userfriendlyaddress">UserFriendlyAddress</a>) =&gt; Promise&lt;string \| null&gt;</code> | Reverse-resolve a wallet address to a TON DNS domain that points at it; `null` when none. |
+| `jettonsByAddress`\* | `(request: GetJettonsByAddressRequest) => Promise<ToncenterResponseJettonMasters>` | Look up jetton masters by address — returns indexer metadata for the requested jettons. |
+| `jettonsByOwnerAddress`\* | <code>(request: GetJettonsByOwnerRequest) =&gt; Promise&lt;<a href="#jettonsresponse">JettonsResponse</a>&gt;</code> | List jetton holdings owned by an address — returns balances + jetton-master metadata. |
+| `getEvents`\* | `(request: GetEventsRequest) => Promise<GetEventsResponse>` | List parsed account events (jetton transfers, NFT moves, swaps, …) for an address. |
+| `getMasterchainInfo`\* | `() => Promise<MasterchainInfo>` | Read the latest masterchain info — last seqno, shards, time. |
+
+#### ApiClientConfig
+
+Configuration accepted by [`NetworkConfig`](#networkconfig)'s `apiClient` — picks an [`ApiClient`](#apiclient) implementation (Toncenter / TonAPI) and supplies its endpoint URL plus optional API key.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `url` | `string` | Base URL of the indexer endpoint. Defaults to `'https://toncenter.com'` for mainnet, `'https://testnet.toncenter.com'` for testnet. |
+| `key` | `string` | API key forwarded to the indexer for higher rate limits. |
+
+#### GetApiClientOptions
+
+Options for [`getApiClient`](#getapiclient).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network`\* | <code><a href="#network">Network</a></code> | Network whose configured [`ApiClient`](#apiclient) should be returned. |
+
+#### GetApiClientReturnType
+
+Return type of [`getApiClient`](#getapiclient).
+
+```ts
+type GetApiClientReturnType = ApiClient;
+```
+
+#### TokenInfo
+
+Display metadata for a token (TON, jetton, or NFT) — name, symbol, image and animation as reported by the indexer; surfaced as [`Jetton`](#jetton)'s `info` and [`NFT`](#nft)'s `info`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Display name of the token |
+| `description` | `string` | Human-readable description of the token |
+| `image` | `TokenImage` | Token image in various sizes |
+| `animation` | `TokenAnimation` | Animated media associated with the token |
+| `symbol` | `string` | Ticker symbol of the token (e.g., "TON", "USDT") |
+
+### Connectors
+
+#### AddConnectorParameters
+
+Connector instance or factory accepted by [`addConnector`](#addconnector) — same shape used in [`AppKitConfig`](#appkitconfig)'s `connectors`.
+
+```ts
+type AddConnectorParameters = ConnectorInput;
+```
+
+#### AddConnectorReturnType
+
+Return type of [`addConnector`](#addconnector) — call to remove the connector from AppKit.
+
+```ts
+type AddConnectorReturnType = () => void;
+```
+
+#### ConnectParameters
+
+Parameters accepted by [`connect`](#connect).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `connectorId`\* | `string` | ID of the registered connector to drive the connection through (e.g., `'tonconnect'`). |
+
+#### ConnectReturnType
+
+Return type of [`connect`](#connect).
+
+```ts
+type ConnectReturnType = void;
+```
+
+#### Connector
+
+Wallet connector contract — the protocol-specific bridge (TonConnect, embedded wallet, …) AppKit drives once you register it via [`AppKitConfig`](#appkitconfig)'s `connectors`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id`\* | `string` | Stable connector identifier, unique within an AppKit instance. |
+| `type`\* | `string` | Protocol type (e.g. `'tonconnect'`). Multiple connectors can share the same type. |
+| `metadata`\* | <code><a href="#connectormetadata">ConnectorMetadata</a></code> | Display metadata (name, icon) shown in connect UIs. |
+| `destroy`\* | `() => void` | Release any resources held by the connector. Call on app teardown. |
+| `connectWallet`\* | <code>(network?: <a href="#network">Network</a>) =&gt; Promise&lt;void&gt;</code> | Initiate a wallet connection flow on the given network. |
+| `disconnectWallet`\* | `() => Promise<void>` | Disconnect the currently connected wallet, if any. |
+| `getConnectedWallets`\* | <code>() =&gt; <a href="#walletinterface">WalletInterface</a>[]</code> | Wallets currently connected through this connector. |
+
+#### ConnectorFactory
+
+Factory that builds a [`Connector`](#connector) from [`ConnectorFactoryContext`](#connectorfactorycontext); AppKit calls it at registration time.
+
+```ts
+type ConnectorFactory = (ctx: ConnectorFactoryContext) => Connector;
+```
+
+#### ConnectorFactoryContext
+
+Context that AppKit injects into a [`ConnectorFactory`](#connectorfactory) when building the connector at registration time.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `networkManager`\* | <code><a href="#appkitnetworkmanager">AppKitNetworkManager</a></code> | Network manager the connector should use for client lookups and default-network reads. |
+| `eventEmitter`\* | <code><a href="#appkitemitter">AppKitEmitter</a></code> | Event emitter the connector should publish wallet/connection events to. |
+| `ssr` | `boolean` | `true` when the connector is constructed during server-side rendering — connectors may skip browser-only setup. |
+
+#### ConnectorInput
+
+Either a ready-made [`Connector`](#connector) or a [`ConnectorFactory`](#connectorfactory) that produces one — the value accepted by [`addConnector`](#addconnector) and [`AppKitConfig`](#appkitconfig)'s `connectors`.
+
+```ts
+type ConnectorInput = Connector | ConnectorFactory;
+```
+
+#### ConnectorMetadata
+
+Display metadata for a [`Connector`](#connector), surfaced in connect UIs to help users pick the right wallet.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name`\* | `string` | Human-readable connector name (e.g., `'TonConnect'`). |
+| `iconUrl` | `string` | Optional URL of an icon shown next to the name. |
+
+#### DisconnectParameters
+
+Parameters accepted by [`disconnect`](#disconnect).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `connectorId`\* | `string` | ID of the registered connector whose wallet should be disconnected. |
+
+#### DisconnectReturnType
+
+Return type of [`disconnect`](#disconnect).
+
+```ts
+type DisconnectReturnType = void;
+```
+
+#### GetConnectorByIdOptions
+
+Options for [`getConnectorById`](#getconnectorbyid).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id`\* | `string` | ID of the connector to look up. |
+
+#### GetConnectorByIdReturnType
+
+Return type of [`getConnectorById`](#getconnectorbyid) — `undefined` when no connector with that id is registered.
+
+```ts
+type GetConnectorByIdReturnType = Connector | undefined;
+```
+
+#### GetConnectorsReturnType
+
+Return type of [`getConnectors`](#getconnectors) — read-only view of the registered-connectors array.
+
+```ts
+type GetConnectorsReturnType = readonly Connector[];
+```
+
+#### TonConnectConnector
+
+[`Connector`](#connector) produced by [`createTonConnectConnector`](#createtonconnectconnector) — extends the base interface with the underlying `TonConnectUI` instance for advanced flows that need direct access (e.g., custom modals).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id`\* | `string` | Stable connector identifier, unique within an AppKit instance. |
+| `type`\* | `string` | Protocol type (e.g. `'tonconnect'`). Multiple connectors can share the same type. |
+| `metadata`\* | <code><a href="#connectormetadata">ConnectorMetadata</a></code> | Display metadata (name, icon) shown in connect UIs. |
+| `destroy`\* | `() => void` | Release any resources held by the connector. Call on app teardown. |
+| `connectWallet`\* | <code>(network?: <a href="#network">Network</a>) =&gt; Promise&lt;void&gt;</code> | Initiate a wallet connection flow on the given network. |
+| `disconnectWallet`\* | `() => Promise<void>` | Disconnect the currently connected wallet, if any. |
+| `getConnectedWallets`\* | <code>() =&gt; <a href="#walletinterface">WalletInterface</a>[]</code> | Wallets currently connected through this connector. |
+| `tonConnectUI`\* | `TonConnectUI \| null` | Underlying `TonConnectUI` instance — `null` during SSR or before the connector has been initialised. Apps that need to drive the modal directly (e.g. custom UI flows) can read this and call its methods. |
+
+#### TonConnectConnectorConfig
+
+Configuration accepted by [`createTonConnectConnector`](#createtonconnectconnector).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Connector ID. Defaults to [`TONCONNECT_DEFAULT_CONNECTOR_ID`](#tonconnect_default_connector_id) (`'tonconnect'`); set this when you need to register multiple TonConnect-flavoured connectors side by side. |
+| `metadata` | <code><a href="#connectormetadata">ConnectorMetadata</a></code> | Display metadata override; merged on top of TonConnect's default name and icon. |
+| `tonConnectOptions` | `TonConnectUiCreateOptions` | Options forwarded to the underlying `TonConnectUI` constructor (manifest URL, etc.). Ignored when `tonConnectUI` is supplied. |
+| `tonConnectUI` | `TonConnectUI` | Pre-built `TonConnectUI` instance to reuse; when set, the connector skips its own instantiation and `tonConnectOptions` is ignored. |
+
+#### WatchConnectorByIdParameters
+
+Parameters accepted by [`watchConnectorById`](#watchconnectorbyid).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id`\* | `string` | ID of the connector to watch. |
+| `onChange`\* | <code>(connector: <a href="#connector">Connector</a> \| undefined) =&gt; void</code> | Callback invoked when the connector with the watched id is registered or unregistered — receives the connector itself, or `undefined` when none is registered under that id. |
+
+#### WatchConnectorByIdReturnType
+
+Return type of [`watchConnectorById`](#watchconnectorbyid) — call to stop receiving updates.
+
+```ts
+type WatchConnectorByIdReturnType = () => void;
+```
+
+#### WatchConnectorsParameters
+
+Parameters accepted by [`watchConnectors`](#watchconnectors).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | <code>(connectors: readonly <a href="#connector">Connector</a>[]) =&gt; void</code> | Callback invoked when the list of registered connectors changes — receives the current list. |
+
+#### WatchConnectorsReturnType
+
+Return type of [`watchConnectors`](#watchconnectors) — call to stop receiving updates.
+
+```ts
+type WatchConnectorsReturnType = () => void;
+```
+
+### Core
+
+#### AppKitConfig
+
+Constructor options for [`AppKit`](#appkit) — networks, connectors, providers and runtime flags.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `networks` | <code><a href="#networkadapters">NetworkAdapters</a></code> | Map of chain ID to [`NetworkConfig`](#networkconfig) (which holds the api-client setup); if omitted, AppKit defaults to mainnet only. |
+| `connectors` | <code><a href="#connectorinput">ConnectorInput</a>[]</code> | Wallet connectors registered at startup. |
+| `defaultNetwork` | <code><a href="#network">Network</a></code> | Default network. |
+| `providers` | <code><a href="#providerinput">ProviderInput</a>[]</code> | Providers registered at startup. |
+| `ssr` | `boolean` | Set to `true` to enable server-side rendering support. |
+
+#### AppKitEmitter
+
+Strongly-typed event emitter exposed as [`AppKit`](#appkit)'s `emitter`; `appKit.emitter.on(name, handler)` returns an unsubscribe function.
+
+```ts
+type AppKitEmitter = EventEmitter<AppKitEvents>;
+```
+
+#### AppKitEvents
+
+Map of every event name AppKit can emit to its payload type, used to type listeners on [`AppKitEmitter`](#appkitemitter).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `connector:added`\* | <code><a href="#connectoraddedpayload">ConnectorAddedPayload</a></code> | Fired by [`addConnector`](#addconnector) when a connector is registered with AppKit. |
+| `connector:removed`\* | <code><a href="#connectorremovedpayload">ConnectorRemovedPayload</a></code> | Fired by `removeConnector` when a connector is unregistered from AppKit. |
+| `connector:wallets-updated`\* | <code><a href="#connectorwalletsupdatedpayload">ConnectorWalletsUpdatedPayload</a></code> | Fired by a connector whenever its connected-wallets list changes (connect, disconnect, or account switch inside the wallet). |
+| `wallets:updated`\* | <code>&lbrace; wallets: <a href="#walletinterface">WalletInterface</a>[] &rbrace;</code> | Fired by AppKit's wallet manager after re-aggregating connectors — `wallets` is the full current set. |
+| `wallets:selection-changed`\* | `{ walletId: string \| null }` | Fired when the selected wallet changes — `walletId` is the new selection, or `null` when cleared. |
+| `networks:updated`\* | `Record<string, never>` | Fired by the network manager when a network's API client is registered or replaced via `setClient`. |
+| `networks:default-changed`\* | <code><a href="#defaultnetworkchangedpayload">DefaultNetworkChangedPayload</a></code> | Fired by [`setDefaultNetwork`](#setdefaultnetwork) — carries the new default network, or `undefined` when the constraint was cleared. |
+| `streaming:balance-update`\* | <code><a href="#balanceupdate">BalanceUpdate</a></code> | Fired by a streaming provider when a watched address's TON balance changes. |
+| `streaming:transactions`\* | <code><a href="#transactionsupdate">TransactionsUpdate</a></code> | Fired by a streaming provider when new transactions land for a watched address. |
+| `streaming:jettons-update`\* | <code><a href="#jettonupdate">JettonUpdate</a></code> | Fired by a streaming provider when a watched address's jetton holdings change. |
+| `provider:registered`\* | `BaseProviderUpdate` | Fired by a DeFi manager when a provider is registered through it (carries the provider's id and kind). |
+| `provider:default-changed`\* | `BaseProviderUpdate` | Fired by a DeFi manager when its default provider is set or cleared (carries the new default's id and kind). |
+
+#### ConnectorAddedPayload
+
+Payload of `connector:added` events — the connector that was just registered.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `connector`\* | <code><a href="#connector">Connector</a></code> | [`Connector`](#connector) just registered with AppKit. |
+
+#### ConnectorRemovedPayload
+
+Payload of `connector:removed` events — the connector that was just unregistered.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `connector`\* | <code><a href="#connector">Connector</a></code> | [`Connector`](#connector) just unregistered from AppKit (already torn down via `destroy()`). |
+
+#### ConnectorWalletsUpdatedPayload
+
+Payload of `connector:wallets-updated` events — fired by a connector when its connected-wallets list changes (connect, disconnect, or account switch inside the wallet).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `connectorId`\* | `string` | ID of the [`Connector`](#connector) whose wallets just changed. |
+| `wallets`\* | <code><a href="#walletinterface">WalletInterface</a>[]</code> | Wallets currently exposed by the connector — empty when the wallet was just disconnected. |
+
+#### DefaultNetworkChangedPayload
+
+Payload of `networks:default-changed` events — the new default network, or `undefined` when cleared.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network`\* | <code><a href="#network">Network</a> \| undefined</code> | New default network, or `undefined` when the constraint is cleared. |
+
+#### EventListener
+
+Listener callback signature accepted by [`EventEmitter`](#eventemitter)'s `on` — receives a [`KitEvent`](#kitevent) for the given event type and may return a Promise the emitter awaits.
+
+```ts
+type EventListener = (event: KitEvent<T>) => void | Promise<void>;
+```
+
+#### EventPayload
+
+Generic event-payload constraint — an `object` that the typed event-name → payload map maps to.
+
+```ts
+type EventPayload = object;
+```
+
+#### KitEvent
+
+Envelope every [`EventEmitter`](#eventemitter) listener receives — `type` is the event name, `payload` is the event-specific data, `source` identifies who emitted it, and `timestamp` is the wall-clock millisecond mark.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `type`\* | `string` | Event name (e.g., `'connector:wallets-updated'`). |
+| `payload`\* | `T = any` | Event-specific payload — typed via the emitter's event-name → payload map. |
+| `source` | `string` | Identifier of the component that emitted the event (connector id, manager name, etc.); useful for filtering listeners. |
+| `timestamp`\* | `number` | Wall-clock timestamp in milliseconds when the event was emitted. |
+
+#### SharedKitEvents
+
+Event-name → payload map shared between AppKit and walletkit; AppKit extends it with its own connector, wallet and network events to type [`AppKitEmitter`](#appkitemitter).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `streaming:balance-update`\* | <code><a href="#balanceupdate">BalanceUpdate</a></code> | Fired by a streaming provider when a watched address's TON balance changes. |
+| `streaming:transactions`\* | <code><a href="#transactionsupdate">TransactionsUpdate</a></code> | Fired by a streaming provider when new transactions land for a watched address. |
+| `streaming:jettons-update`\* | <code><a href="#jettonupdate">JettonUpdate</a></code> | Fired by a streaming provider when a watched address's jetton holdings change. |
+| `provider:registered`\* | `BaseProviderUpdate` | Fired by a DeFi manager when a provider is registered through it (carries the provider's id and kind). |
+| `provider:default-changed`\* | `BaseProviderUpdate` | Fired by a DeFi manager when its default provider is set or cleared (carries the new default's id and kind). |
+
+### Crypto Onramp
+
+#### CreateCryptoOnrampDepositOptions
+
+Options for [`createCryptoOnrampDeposit`](#createcryptoonrampdeposit) — extends [`CryptoOnrampDepositParams`](#cryptoonrampdepositparams) with an optional provider override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `quote`\* | <code><a href="#cryptoonrampquote">CryptoOnrampQuote</a>&lt;TQuoteMetadata = unknown&gt;</code> | Quote to execute the deposit against (contains recipientAddress and provider metadata) |
+| `refundAddress`\* | `string` | Address to refund the crypto to in case of failure |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `providerId` | `string` | Provider to create the deposit through; defaults to `quote.providerId`, then to the default provider. |
+
+#### CreateCryptoOnrampDepositReturnType
+
+Return type of [`createCryptoOnrampDeposit`](#createcryptoonrampdeposit).
+
+```ts
+type CreateCryptoOnrampDepositReturnType = Promise<CryptoOnrampDeposit>;
+```
+
+#### CryptoOnrampDeposit
+
+Deposit details returned by a crypto onramp provider.
+
+The user must send `amount` of `sourceCurrencyAddress` to `address` on `sourceChain`
+to complete the onramp; the provider then delivers the target crypto to the
+user's TON address.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `depositId`\* | `string` | Deposit id |
+| `address`\* | `string` | Deposit address on the source chain |
+| `amount`\* | `string` | Exact amount of source crypto the user must send |
+| `sourceCurrencyAddress`\* | `string` | Source crypto currency address (contract address or 0x0... for native) |
+| `sourceChain`\* | `string` | Source chain identifier in CAIP-2 format (e.g. 'eip155:42161'). |
+| `memo` | `string` | Optional memo / tag required by some chains (e.g. XRP, TON comment) |
+| `expiresAt` | `number` | Unix timestamp (ms) after which the deposit offer is no longer valid |
+| `chainWarning` | `string` | Chain-specific warning to show the user (e.g. "send only on Solana") |
+| `providerId`\* | `string` | Identifier of the provider that issued this deposit |
+
+#### CryptoOnrampDepositParams
+
+Parameters for creating a crypto onramp deposit.
+
+The recipient is taken from `quote.recipientAddress` set at quote time.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `quote`\* | <code><a href="#cryptoonrampquote">CryptoOnrampQuote</a>&lt;TQuoteMetadata = unknown&gt;</code> | Quote to execute the deposit against (contains recipientAddress and provider metadata) |
+| `refundAddress`\* | `string` | Address to refund the crypto to in case of failure |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+
+#### CryptoOnrampProviderInterface
+
+Interface that all crypto onramp providers must implement
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `type`\* | `'crypto-onramp'` | Provider kind discriminator pinned to `'crypto-onramp'` so [`registerProvider`](#registerprovider) routes it to the crypto-onramp manager. |
+| `providerId`\* | `string` | Unique identifier for the provider |
+| `getMetadata`\* | <code>() =&gt; <a href="#cryptoonrampprovidermetadata">CryptoOnrampProviderMetadata</a></code> | Get static metadata for the provider (display name, logo, url). |
+| `getQuote`\* | <code>(params: <a href="#cryptoonrampquoteparams">CryptoOnrampQuoteParams</a>&lt;TQuoteOptions&gt;) =&gt; Promise&lt;<a href="#cryptoonrampquote">CryptoOnrampQuote</a>&gt;</code> | Get a quote for onramping from another crypto asset into a TON asset |
+| `createDeposit`\* | <code>(params: <a href="#cryptoonrampdepositparams">CryptoOnrampDepositParams</a>&lt;TDepositOptions&gt;) =&gt; Promise&lt;<a href="#cryptoonrampdeposit">CryptoOnrampDeposit</a>&gt;</code> | Create a deposit for a previously obtained quote |
+| `getStatus`\* | <code>(params: <a href="#cryptoonrampstatusparams">CryptoOnrampStatusParams</a>) =&gt; Promise&lt;<a href="#cryptoonrampstatus">CryptoOnrampStatus</a>&gt;</code> | Get the status of a deposit |
+| `getSupportedNetworks`\* | <code>() =&gt; <a href="#network">Network</a>[]</code> | Networks this provider can operate on. Consumers should check before calling provider methods. Implementations may return a static list or compute it dynamically (e.g. from runtime config). |
+
+#### CryptoOnrampProviderMetadata
+
+Static metadata for a crypto-onramp provider.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name`\* | `string` | Human-readable provider name (e.g. 'Swaps.xyz') |
+| `logo` | `string` | URL to the provider's logo image |
+| `url` | `string` | URL to the provider's website |
+| `isRefundAddressRequired` | `boolean` | Whether this provider requires a refund address on the source chain. When true, the UI must collect a refund address before creating a deposit. |
+| `isReversedAmountSupported` | `boolean` | Whether this provider supports reversed (target-amount) quotes. When false, the UI should hide the direction toggle and only allow source-amount input. |
+
+#### CryptoOnrampProviderMetadataOverride
+
+Used in provider configuration to override fields of the provider's metadata.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Override the provider's display name |
+| `logo` | `string` | Override the provider's logo URL |
+| `url` | `string` | Override the provider's website URL |
+
+#### CryptoOnrampQuote
+
+Crypto onramp quote response with pricing information
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `sourceCurrencyAddress`\* | `string` | Source crypto currency address (contract address or 0x0... for native) |
+| `sourceChain`\* | `string` | Source chain identifier in CAIP-2 format (e.g. 'eip155:42161'). |
+| `targetCurrencyAddress`\* | `string` | Target crypto currency address on TON (contract address or 0x0... for native) |
+| `sourceAmount`\* | `string` | Amount of source crypto to send |
+| `targetAmount`\* | `string` | Amount of target crypto to receive |
+| `rate`\* | `string` | Exchange rate (amount of target per 1 unit of source) |
+| `recipientAddress`\* | `string` | TON address that will receive the target crypto |
+| `providerId`\* | `string` | Identifier of the crypto onramp provider |
+| `metadata` | `TMetadata = unknown` | Provider-specific metadata for the quote (e.g. raw response needed to execute) |
+
+#### CryptoOnrampQuoteParams
+
+Parameters for requesting a crypto-to-crypto onramp quote.
+
+The target network is always TON, so only the source side is parameterised.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `amount`\* | `string` | Amount to onramp (either source or target crypto, depending on isSourceAmount) |
+| `sourceCurrencyAddress`\* | `string` | Source crypto currency address (contract address or 0x0... for native) |
+| `sourceChain`\* | `string` | Source chain identifier in CAIP-2 format (e.g. 'eip155:1' for Ethereum mainnet, 'eip155:42161' for Arbitrum One). Providers map this to their own chain identifiers internally. |
+| `targetCurrencyAddress`\* | `string` | Target crypto currency address on TON (contract address or 0x0... for native) |
+| `recipientAddress`\* | `string` | TON address that will receive the target crypto |
+| `refundAddress` | `string` | Refund address for the source crypto |
+| `isSourceAmount` | `boolean` | If true, `amount` is the source amount to spend. If false, `amount` is the target amount to receive. Defaults to true when omitted. |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+
+#### CryptoOnrampStatus
+
+Final state of a crypto-onramp deposit returned by [`getCryptoOnrampStatus`](#getcryptoonrampstatus) — `'success'` (delivered to the recipient), `'pending'` (still in flight), or `'failed'` (provider could not complete the deposit).
+
+```ts
+type CryptoOnrampStatus = 'success' | 'pending' | 'failed';
+```
+
+#### CryptoOnrampStatusParams
+
+Parameters accepted by [`getCryptoOnrampStatus`](#getcryptoonrampstatus) — identifies a previously created deposit and the provider that issued it.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `depositId`\* | `string` | Deposit id |
+| `providerId`\* | `string` | Identifier of the provider that issued this deposit |
+
+#### GetCryptoOnrampProviderOptions
+
+Options for [`getCryptoOnrampProvider`](#getcryptoonrampprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Provider ID to look up; when omitted, returns the registered default provider. |
+
+#### GetCryptoOnrampProviderReturnType
+
+Return type of [`getCryptoOnrampProvider`](#getcryptoonrampprovider).
+
+```ts
+type GetCryptoOnrampProviderReturnType = CryptoOnrampProviderInterface;
+```
+
+#### GetCryptoOnrampProvidersReturnType
+
+Return type of [`getCryptoOnrampProviders`](#getcryptoonrampproviders).
+
+```ts
+type GetCryptoOnrampProvidersReturnType = CryptoOnrampProviderInterface[];
+```
+
+#### GetCryptoOnrampQuoteOptions
+
+Options for [`getCryptoOnrampQuote`](#getcryptoonrampquote) — extends [`CryptoOnrampQuoteParams`](#cryptoonrampquoteparams) with an optional provider override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `amount`\* | `string` | Amount to onramp (either source or target crypto, depending on isSourceAmount) |
+| `sourceCurrencyAddress`\* | `string` | Source crypto currency address (contract address or 0x0... for native) |
+| `sourceChain`\* | `string` | Source chain identifier in CAIP-2 format (e.g. 'eip155:1' for Ethereum mainnet, 'eip155:42161' for Arbitrum One). Providers map this to their own chain identifiers internally. |
+| `targetCurrencyAddress`\* | `string` | Target crypto currency address on TON (contract address or 0x0... for native) |
+| `recipientAddress`\* | `string` | TON address that will receive the target crypto |
+| `refundAddress` | `string` | Refund address for the source crypto |
+| `isSourceAmount` | `boolean` | If true, `amount` is the source amount to spend. If false, `amount` is the target amount to receive. Defaults to true when omitted. |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `providerId` | `string` | Provider to quote against; defaults to the registered default provider. |
+
+#### GetCryptoOnrampQuoteReturnType
+
+Return type of [`getCryptoOnrampQuote`](#getcryptoonrampquote).
+
+```ts
+type GetCryptoOnrampQuoteReturnType = Promise<CryptoOnrampQuote>;
+```
+
+#### GetCryptoOnrampStatusOptions
+
+Options for [`getCryptoOnrampStatus`](#getcryptoonrampstatus) — extends [`CryptoOnrampStatusParams`](#cryptoonrampstatusparams) with an optional provider override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `depositId`\* | `string` | Deposit id |
+| `providerId`\* | `string` | Identifier of the provider that issued this deposit |
+
+#### GetCryptoOnrampStatusReturnType
+
+Return type of [`getCryptoOnrampStatus`](#getcryptoonrampstatus).
+
+```ts
+type GetCryptoOnrampStatusReturnType = Promise<CryptoOnrampStatus>;
+```
+
+#### LayerswapProviderConfig
+
+Configuration accepted by [`createLayerswapProvider`](#createlayerswapprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `apiKey` | `string` | Optional API key. Forwarded as `X-LS-APIKEY` when provided. |
+| `apiUrl` | `string` | Override the base API URL. Defaults to https://api.layerswap.io/api/v2 |
+
+#### LayerswapQuoteMetadata
+
+Provider-specific metadata returned on a [`CryptoOnrampQuote`](#cryptoonrampquote)'s `metadata` from Layerswap — carries the swap id and deposit action that [`createCryptoOnrampDeposit`](#createcryptoonrampdeposit) reads to build the deposit.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `swapId`\* | `string` | Layerswap swap id created at quote time and reused by `createDeposit` / `getStatus`. |
+| `depositAddress`\* | `string` | Pre-computed deposit address on the source chain that the user must send funds to. |
+| `sourceAmountBaseUnits`\* | `string` | Source-chain amount the user must send, in raw base units (e.g., wei). |
+| `targetAmountBaseUnits`\* | `string` | Target-chain amount the user receives, in raw base units (e.g., nanotons). |
+
+#### SwapsXyzProviderConfig
+
+Configuration accepted by [`createSwapsXyzProvider`](#createswapsxyzprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `apiKey`\* | `string` | API key issued by swaps.xyz (passed as `x-api-key`) |
+| `apiUrl` | `string` | Override the base API URL. Defaults to https://api-v2.swaps.xyz/api |
+| `defaultSender` | `string` | EVM address used as `sender` on getAction requests. Required by the API even for deposit flows where the actual payer is unknown. Defaults to a null address when omitted. |
+
+#### SwapsXyzQuoteMetadata
+
+Provider-specific metadata returned on a [`CryptoOnrampQuote`](#cryptoonrampquote)'s `metadata` from swaps.xyz — carries the resolved action and bridge route that [`createCryptoOnrampDeposit`](#createcryptoonrampdeposit) needs.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `sender`\* | `string` | EVM sender address swaps.xyz was quoted for; required when later calling `createDeposit`. |
+| `response`\* | `SwapsXyzGetActionResponse` | Raw `getAction` response cached at quote time so `createDeposit` doesn't need an extra round-trip. |
+
+#### SwapsXyzQuoteOptions
+
+swaps.xyz-specific options forwarded through `providerOptions` on [`CryptoOnrampQuoteParams`](#cryptoonrampquoteparams).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `slippageBps` | `number` | Slippage tolerance in basis points (0-10000). Defaults to 100 (1%). |
+
+#### WatchCryptoOnrampProvidersParameters
+
+Parameters accepted by [`watchCryptoOnrampProviders`](#watchcryptoonrampproviders).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | `() => void` | Callback fired whenever a crypto-onramp provider is registered or the default crypto-onramp provider changes. |
+
+#### WatchCryptoOnrampProvidersReturnType
+
+Return type of [`watchCryptoOnrampProviders`](#watchcryptoonrampproviders) — call to stop receiving updates.
+
+```ts
+type WatchCryptoOnrampProvidersReturnType = () => void;
+```
+
+### DeFi
+
+#### DefiManagerAPI
+
+Shape every DeFi domain manager (swap, staking, onramp, crypto-onramp) satisfies — provider registration, default-provider selection and lookups; mostly relevant when authoring a new domain manager.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `createFactoryContext`\* | <code>() =&gt; <a href="#providerfactorycontext">ProviderFactoryContext</a></code> | Build a fresh [`ProviderFactoryContext`](#providerfactorycontext) the manager hands to provider factories at registration time. |
+| `registerProvider`\* | <code>(provider: <a href="#providerinput">ProviderInput</a>&lt;T&gt;) =&gt; void</code> | Register a new provider. If a provider with the same id is already registered, it is replaced. |
+| `removeProvider`\* | `(provider: T) => void` | Remove a previously registered provider. No-op if the provider was not registered. |
+| `setDefaultProvider`\* | `(providerId: string) => void` | Set the default provider |
+| `getProvider`\* | `(providerId?: string) => T` | Get a registered provider |
+| `getProviders`\* | `() => T[]` | Get all registered providers. The returned array keeps a stable reference until the provider list changes. |
+| `hasProvider`\* | `(providerId: string) => boolean` | Check if a provider is registered |
+
+#### DefiProvider
+
+Base interface implemented by every DeFi provider (swap, staking, onramp, crypto-onramp) — exposes `providerId`, `type` and `getSupportedNetworks`. Domain-specific provider interfaces extend this with quote/build/status methods.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `type`\* | <code><a href="#defiprovidertype">DefiProviderType</a></code> | Provider kind discriminator narrowed to the DeFi-domain literals so the right manager picks it up at registration time. |
+| `getSupportedNetworks`\* | <code>() =&gt; <a href="#network">Network</a>[]</code> | Networks this provider can operate on. Consumers should check before calling provider methods. Implementations may return a static list or compute it dynamically (e.g. from runtime config). |
+| `providerId`\* | `string` | Stable provider identifier, unique within the manager that registered it. |
+
+#### DefiProviderType
+
+Discriminator that tags every [`DefiProvider`](#defiprovider) with its kind — `'swap'`, `'staking'`, `'onramp'`, or `'crypto-onramp'`; used by [`registerProvider`](#registerprovider) to dispatch to the right manager.
+
+```ts
+type DefiProviderType = 'swap' | 'staking' | 'onramp' | 'crypto-onramp';
+```
+
+#### ProviderFactoryContext
+
+Context that AppKit's DeFi managers inject into a [`ProviderInput`](#providerinput) factory at registration time — gives the provider access to AppKit's network manager and event emitter, plus an `ssr` flag for server-side initialisation.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `networkManager`\* | `NetworkManager` | Network manager the provider should use for client lookups and default-network reads. |
+| `eventEmitter`\* | <code><a href="#eventemitter">EventEmitter</a>&lt;Events = <a href="#sharedkitevents">SharedKitEvents</a>&gt;</code> | Event emitter the provider should publish its events to. |
+| `ssr` | `boolean` | `true` when the provider is constructed during server-side rendering — factories may skip browser-only setup. |
+
+#### ProviderInput
+
+Either a ready-made DeFi/onramp provider instance or a factory that produces one — the value accepted by [`AppKitConfig`](#appkitconfig)'s `providers` and [`registerProvider`](#registerprovider).
+
+```ts
+type ProviderInput = T | ProviderFactory<T>;
+```
+
+#### RegisterProviderOptions
+
+Provider instance or factory accepted by [`registerProvider`](#registerprovider) — same shape used in [`AppKitConfig`](#appkitconfig)'s `providers`. AppKit dispatches it to the right manager based on `provider.type` (`'swap'`, `'staking'`, `'onramp'`, `'crypto-onramp'`).
+
+```ts
+type RegisterProviderOptions = ProviderInput;
+```
+
+### Jettons
+
+#### CreateTransferJettonTransactionParameters
+
+Parameters accepted by [`createTransferJettonTransaction`](#createtransferjettontransaction) and [`transferJetton`](#transferjetton).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `jettonAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address being transferred. |
+| `recipientAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Recipient who should receive the jettons. |
+| `amount`\* | `string` | Amount in jetton units as a human-readable decimal string (e.g., `"1.5"`). |
+| `jettonDecimals`\* | `number` | Decimals declared by the jetton master; used to convert `amount` into raw smallest units. |
+| `comment` | `string` | Optional human-readable comment attached to the transfer. |
+
+#### CreateTransferJettonTransactionReturnType
+
+Return type of [`createTransferJettonTransaction`](#createtransferjettontransaction).
+
+```ts
+type CreateTransferJettonTransactionReturnType = TransactionRequest;
+```
+
+#### GetJettonBalanceOptions
+
+Options for [`getJettonBalance`](#getjettonbalance).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `jettonAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address (the token, not the user's wallet for it). |
+| `ownerAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Owner of the jetton wallet — typically the connected user's address. |
+| `jettonDecimals`\* | `number` | Decimals declared by the jetton master; used to format the raw balance into a human-readable string. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+
+#### GetJettonBalanceReturnType
+
+Return type of [`getJettonBalance`](#getjettonbalance).
+
+```ts
+type GetJettonBalanceReturnType = TokenAmount;
+```
+
+#### GetJettonInfoOptions
+
+Options for [`getJettonInfo`](#getjettoninfo).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address whose metadata is being fetched. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+
+#### GetJettonInfoReturnType
+
+Return type of [`getJettonInfo`](#getjettoninfo) — `null` when the indexer has no record for that master address.
+
+```ts
+type GetJettonInfoReturnType = JettonInfo | null;
+```
+
+#### GetJettonWalletAddressOptions
+
+Options for [`getJettonWalletAddress`](#getjettonwalletaddress).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `jettonAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address. |
+| `ownerAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Owner whose jetton wallet should be derived. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+
+#### GetJettonWalletAddressReturnType
+
+Return type of [`getJettonWalletAddress`](#getjettonwalletaddress).
+
+```ts
+type GetJettonWalletAddressReturnType = UserFriendlyAddress;
+```
+
+#### GetJettonsByAddressOptions
+
+Options for [`getJettonsByAddress`](#getjettonsbyaddress).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+| `limit` | `number` | Maximum number of jettons to return. |
+| `offset` | `number` | Number of jettons to skip before returning results — used for pagination. |
+
+#### GetJettonsByAddressReturnType
+
+Return type of [`getJettonsByAddress`](#getjettonsbyaddress).
+
+```ts
+type GetJettonsByAddressReturnType = JettonsResponse;
+```
+
+#### GetJettonsOptions
+
+Options for [`getJettons`](#getjettons).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="#network">Network</a></code> | Network to read jettons from. Defaults to the selected wallet's network. |
+| `limit` | `number` | Maximum number of jettons to return. |
+| `offset` | `number` | Number of jettons to skip before returning results — used for pagination. |
+
+#### GetJettonsReturnType
+
+Return type of [`getJettons`](#getjettons) — `null` when no wallet is currently selected.
+
+```ts
+type GetJettonsReturnType = JettonsResponse | null;
+```
+
+#### Jetton
+
+Fungible TEP-74 token held in the user's TON wallet — carries the master contract address, the user's jetton-wallet address, current balance, and token metadata.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The jetton master contract address (the token itself). |
+| `walletAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The owner's jetton-wallet contract address — the per-owner contract that actually holds this balance. |
+| `balance`\* | <code><a href="#tokenamount">TokenAmount</a></code> | The current jetton balance |
+| `info`\* | <code><a href="#tokeninfo">TokenInfo</a></code> | Information about the token |
+| `decimalsNumber` | `number` | The number of decimal places used by the token |
+| `isVerified`\* | `boolean` | Indicates if the jetton is verified |
+| `prices`\* | `JettonPrice[]` | Current prices of the jetton in various currencies |
+| `extra` | `{         [key: string]: unknown;     }` | Additional arbitrary data related to the jetton |
+
+#### JettonInfo
+
+Token metadata for a jetton master — name, symbol, decimals, image, and verification status as reported by the indexer.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | `string` | Jetton master contract address. |
+| `name`\* | `string` | Display name of the jetton (e.g., `"Tether USD"`). |
+| `symbol`\* | `string` | Ticker symbol (e.g., `"USDT"`). |
+| `description`\* | `string` | Free-form description set by the issuer. |
+| `decimals` | `number` | Number of decimal places used to format raw amounts (e.g., `6` for USDT). |
+| `totalSupply` | `string` | Total supply in raw smallest units. |
+| `image` | `string` | URL of the jetton's image. |
+| `image_data` | `string` | Inline image data (Base64) when no `image` URL is published. |
+| `uri` | `string` | Off-chain metadata URI (TEP-64). |
+| `verification` | <code><a href="#jettonverification">JettonVerification</a></code> | Verification status reported by the indexer. |
+| `metadata` | `Record<string, unknown>` | Additional indexer-supplied metadata that doesn't fit the canonical fields. |
+
+#### JettonUpdate
+
+Update payload delivered to [`watchJettons`](#watchjettons) / [`watchJettonsByAddress`](#watchjettonsbyaddress) subscribers when the watched owner's jetton balance changes.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `type`\* | `'jettons'` | The update type field |
+| `masterAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The master jetton contract address |
+| `walletAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The jetton wallet contract address |
+| `ownerAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The owner of the jetton wallet |
+| `rawBalance`\* | <code><a href="#tokenamount">TokenAmount</a></code> | Balance in raw smallest units (e.g. nano) |
+| `decimals` | `number` | Decimals mapped from metadata if available |
+| `balance` | `string` | Human readable formatted balance if decimals are known |
+| `status`\* | <code><a href="#streamingupdatestatus">StreamingUpdateStatus</a></code> | The finality of the update |
+
+#### JettonVerification
+
+Verification metadata reported by the indexer for a [`JettonInfo`](#jettoninfo) — `verified` flag plus optional verifier source.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `verified`\* | `boolean` | `true` when the indexer has verified this jetton against an allow-list. |
+| `source` | `'toncenter' \| 'community' \| 'manual'` | Origin of the verification claim. |
+| `warnings` | `string[]` | Free-form warnings the UI should surface (e.g., scam indicators). |
+
+#### JettonsResponse
+
+Response payload of [`getJettons`](#getjettons) / [`getJettonsByAddress`](#getjettonsbyaddress) — the list of [`Jetton`](#jetton)s plus the address book that resolves raw addresses inside it.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `addressBook`\* | <code><a href="#addressbook">AddressBook</a></code> | Address book mapping |
+| `jettons`\* | <code><a href="#jetton">Jetton</a>[]</code> | List of Jettons |
+
+#### TransferJettonParameters
+
+Parameters accepted by [`transferJetton`](#transferjetton) — same shape as [`CreateTransferJettonTransactionParameters`](#createtransferjettontransactionparameters).
+
+```ts
+type TransferJettonParameters = CreateTransferJettonTransactionParameters;
+```
+
+#### TransferJettonReturnType
+
+Return type of [`transferJetton`](#transferjetton).
+
+```ts
+type TransferJettonReturnType = SendTransactionResponse;
+```
+
+#### WatchJettonsByAddressOptions
+
+Options for [`watchJettonsByAddress`](#watchjettonsbyaddress).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `onChange`\* | <code>(update: <a href="#jettonupdate">JettonUpdate</a>) =&gt; void</code> | Callback fired on every jetton-balance update from the streaming provider. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+
+#### WatchJettonsByAddressReturnType
+
+Return type of [`watchJettonsByAddress`](#watchjettonsbyaddress) — call to stop receiving updates.
+
+```ts
+type WatchJettonsByAddressReturnType = () => void;
+```
+
+#### WatchJettonsOptions
+
+Options for [`watchJettons`](#watchjettons).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | <code>(update: <a href="#jettonupdate">JettonUpdate</a>) =&gt; void</code> | Callback fired on every jetton-balance update from the streaming provider. |
+| `network` | <code><a href="#network">Network</a></code> | Network to watch on. Defaults to the selected wallet's network. |
+
+#### WatchJettonsReturnType
+
+Return type of [`watchJettons`](#watchjettons) — call to stop receiving updates.
+
+```ts
+type WatchJettonsReturnType = () => void;
+```
+
+### NFTs
+
+#### CreateTransferNftTransactionParameters
+
+Parameters accepted by [`createTransferNftTransaction`](#createtransfernfttransaction) and [`transferNft`](#transfernft).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `nftAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | NFT contract address to transfer. |
+| `recipientAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | New owner address. |
+| `amount` | `string` | Amount of TON to attach to the transfer for gas; defaults to AppKit's NFT gas-fee constant when omitted. |
+| `comment` | `string` | Optional human-readable comment attached to the transfer. |
+
+#### CreateTransferNftTransactionReturnType
+
+Return type of [`createTransferNftTransaction`](#createtransfernfttransaction).
+
+```ts
+type CreateTransferNftTransactionReturnType = TransactionRequest;
+```
+
+#### GetNftOptions
+
+Options for [`getNft`](#getnft).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | NFT contract address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+
+#### GetNftReturnType
+
+Return type of [`getNft`](#getnft) — `null` when the indexer has no record for that address.
+
+```ts
+type GetNftReturnType = NFT | null;
+```
+
+#### GetNftsByAddressOptions
+
+Options for [`getNftsByAddress`](#getnftsbyaddress).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+| `limit` | `number` | Maximum number of NFTs to return. |
+| `offset` | `number` | Number of NFTs to skip before returning results — used for pagination. |
+
+#### GetNftsByAddressReturnType
+
+Return type of [`getNftsByAddress`](#getnftsbyaddress).
+
+```ts
+type GetNftsByAddressReturnType = NFTsResponse;
+```
+
+#### GetNftsOptions
+
+Options for [`getNfts`](#getnfts).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="#network">Network</a></code> | Network to read NFTs from. Defaults to the selected wallet's network. |
+| `limit` | `number` | Maximum number of NFTs to return. |
+| `offset` | `number` | Number of NFTs to skip before returning results — used for pagination. |
+
+#### GetNftsReturnType
+
+Return type of [`getNfts`](#getnfts) — `null` when no wallet is currently selected.
+
+```ts
+type GetNftsReturnType = NFTsResponse | null;
+```
+
+#### NFT
+
+Non-fungible TEP-62 token held in the user's TON wallet — carries the contract address, optional collection link, owner, sale state, and on-chain metadata.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Contract address of the NFT item |
+| `index` | `string` | Index of the item within its collection |
+| `info` | <code><a href="#tokeninfo">TokenInfo</a></code> | Display information about the NFT (name, description, images) |
+| `attributes` | <code><a href="#nftattribute">NFTAttribute</a>[]</code> | Custom attributes/traits of the NFT (e.g., rarity, properties) |
+| `collection` | <code><a href="#nftcollection">NFTCollection</a></code> | Information about the collection this item belongs to |
+| `auctionContractAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the auction contract, if the NFT is being auctioned |
+| `codeHash` | <code><a href="#hex">Hex</a></code> | Hash of the NFT smart contract code |
+| `dataHash` | <code><a href="#hex">Hex</a></code> | Hash of the NFT's on-chain data |
+| `isInited` | `boolean` | Whether the NFT contract has been initialized |
+| `isSoulbound` | `boolean` | Whether the NFT is soulbound (non-transferable) |
+| `isOnSale` | `boolean` | Whether the NFT is currently listed for sale |
+| `ownerAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Current owner address of the NFT |
+| `realOwnerAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Real owner address when NFT is on sale (sale contract becomes temporary owner) |
+| `saleContractAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the sale contract, if the NFT is listed for sale |
+| `extra` | `{         [key: string]: unknown;     }` | Additional arbitrary data related to the NFT. |
+
+#### NFTAttribute
+
+Single trait of an [`NFT`](#nft) — `traitType` names the category (e.g., `"Background"`), `value` carries the trait's value (e.g., `"Blue"`).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `traitType` | `string` | Category or type of the trait (e.g., "Background", "Eyes") |
+| `displayType` | `string` | Indexer-supplied hint for how the attribute should be rendered. Optional and indexer-specific. |
+| `value` | `string` | Value of the attribute (e.g., "Blue", "Rare") |
+
+#### NFTCollection
+
+NFT collection (TEP-62) — surfaced as [`NFT`](#nft)'s `collection` and carries the collection's name, image, owner and minting cursor.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The blockchain address of the NFT collection contract |
+| `name` | `string` | The name of the NFT collection |
+| `image` | `TokenImage` | The image representing the NFT collection |
+| `description` | `string` | A brief description of the NFT collection |
+| `nextItemIndex` | `string` | The index value for the next item to be minted in the collection |
+| `codeHash` | <code><a href="#hex">Hex</a></code> | The hash of the collection's smart contract code |
+| `dataHash` | <code><a href="#hex">Hex</a></code> | The hash of the collection's data in the blockchain |
+| `ownerAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The blockchain address of the collection owner |
+| `extra` | `{         [key: string]: unknown;     }` | Additional arbitrary data related to the NFT collection |
+
+#### NFTsResponse
+
+Response payload of [`getNfts`](#getnfts) / [`getNftsByAddress`](#getnftsbyaddress) — the list of [`NFT`](#nft)s plus an address book that resolves raw addresses inside it.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `addressBook` | <code><a href="#addressbook">AddressBook</a></code> | Address book entries related to the NFTs |
+| `nfts`\* | <code><a href="#nft">NFT</a>[]</code> | List of NFTs |
+
+#### TransferNftParameters
+
+Parameters accepted by [`transferNft`](#transfernft) — same shape as [`CreateTransferNftTransactionParameters`](#createtransfernfttransactionparameters).
+
+```ts
+type TransferNftParameters = CreateTransferNftTransactionParameters;
+```
+
+#### TransferNftReturnType
+
+Return type of [`transferNft`](#transfernft).
+
+```ts
+type TransferNftReturnType = SendTransactionResponse;
+```
+
+### Networks
+
+#### GetBlockNumberOptions
+
+Options for [`getBlockNumber`](#getblocknumber).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="#network">Network</a></code> | Network to query. Defaults to mainnet when omitted. |
+
+#### GetBlockNumberReturnType
+
+Return type of [`getBlockNumber`](#getblocknumber).
+
+```ts
+type GetBlockNumberReturnType = number;
+```
+
+#### GetDefaultNetworkReturnType
+
+Return type of [`getDefaultNetwork`](#getdefaultnetwork) — `undefined` when no default has been set (apps may operate on any registered network).
+
+```ts
+type GetDefaultNetworkReturnType = Network | undefined;
+```
+
+#### GetNetworkReturnType
+
+Return type of [`getNetwork`](#getnetwork) — `null` when no wallet is currently selected.
+
+```ts
+type GetNetworkReturnType = Network | null;
+```
+
+#### GetNetworksReturnType
+
+Return type of [`getNetworks`](#getnetworks).
+
+```ts
+type GetNetworksReturnType = Network[];
+```
+
+#### HasStreamingProviderReturnType
+
+Return type of [`hasStreamingProvider`](#hasstreamingprovider).
+
+```ts
+type HasStreamingProviderReturnType = boolean;
+```
+
+#### Network
+
+TON blockchain network identifier.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `chainId`\* | `string` | Chain ID of the network (e.g., "-239" for mainnet, "-3" for testnet) |
+
+#### NetworkAdapters
+
+Multi-network configuration keyed by chain ID
+Example: \{ [Network.mainnet().chainId]: \{ apiClient: \{...\} \}, [Network.testnet().chainId]: \{ apiClient: \{...\} \} \}
+
+```ts
+type NetworkAdapters = {
+    [key: string]: NetworkConfig | undefined;
+};
+```
+
+#### NetworkConfig
+
+Network configuration for a specific chain
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `apiClient` | <code><a href="#apiclientconfig">ApiClientConfig</a> \| <a href="#apiclient">ApiClient</a></code> | API client configuration or instance |
+
+#### SetDefaultNetworkParameters
+
+Parameters accepted by [`setDefaultNetwork`](#setdefaultnetwork).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network`\* | <code><a href="#network">Network</a> \| undefined</code> | Network to enforce on new wallet connections; pass `undefined` to allow any registered network. |
+
+#### SetDefaultNetworkReturnType
+
+Return type of [`setDefaultNetwork`](#setdefaultnetwork).
+
+```ts
+type SetDefaultNetworkReturnType = void;
+```
+
+#### TonWalletKitOptions
+
+Walletkit-side options shape consumed by [`KitNetworkManager`](#kitnetworkmanager)'s constructor — chiefly the `networks` map keyed by chain ID. [`AppKit`](#appkit) constructs the manager for you, so apps rarely instantiate this directly.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `walletManifest` | `WalletInfo` | TonConnect wallet manifest published by the dApp; required for the wallet to recognize the integration. |
+| `deviceInfo` | `DeviceInfo` | Device fingerprint forwarded with TonConnect requests so wallets can recognize the host. |
+| `sessionManager` | `TONConnectSessionManager` | Custom session manager implementation. If not provided, TONConnectStoredSessionManager will be used. |
+| `networks` | <code><a href="#networkadapters">NetworkAdapters</a></code> | Network configuration |
+| `bridge` | `BridgeConfig` | Bridge settings |
+| `storage` | `StorageConfig \| StorageAdapter` | Storage settings |
+| `validation` | `{         strictMode?: boolean;         allowUnknownWalletVersions?: boolean;     }` | Validation settings |
+| `eventProcessor` | `EventProcessorConfig` | Event processor settings |
+| `analytics` | `AnalyticsManagerOptions & {         enabled?: boolean;     }` | Analytics manager options merged with an `enabled` toggle; off by default. |
+| `dev` | `{         disableNetworkSend?: boolean;         disableManifestDomainCheck?: boolean;     }` | Diagnostic toggles useful during local development; should not be set in production builds. |
+
+#### WatchDefaultNetworkParameters
+
+Parameters accepted by [`watchDefaultNetwork`](#watchdefaultnetwork).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | <code>(network: <a href="#network">Network</a> \| undefined) =&gt; void</code> | Callback fired whenever [`setDefaultNetwork`](#setdefaultnetwork) updates the default — receives the new value (or `undefined` when cleared). |
+
+#### WatchDefaultNetworkReturnType
+
+Return type of [`watchDefaultNetwork`](#watchdefaultnetwork) — call to stop receiving updates.
+
+```ts
+type WatchDefaultNetworkReturnType = () => void;
+```
+
+#### WatchNetworksParameters
+
+Parameters accepted by [`watchNetworks`](#watchnetworks).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | <code>(networks: <a href="#network">Network</a>[]) =&gt; void</code> | Callback fired whenever the configured-networks list changes — receives the latest snapshot. |
+
+#### WatchNetworksReturnType
+
+Return type of [`watchNetworks`](#watchnetworks) — call to stop receiving updates.
+
+```ts
+type WatchNetworksReturnType = () => void;
+```
+
+### Primitives
+
+#### Base64String
+
+Base64-encoded byte string — used for transaction payloads, BoCs, signatures, and other opaque binary blobs that travel through TonConnect and the indexer APIs.
+
+```ts
+type Base64String = string & {
+    readonly [base64StringBrand]: never;
+};
+```
+
+#### ExtraCurrencies
+
+Map of extra-currency ids to raw amounts attached to a transaction message — TON's mechanism for transferring non-jetton native tokens (e.g., wrapped or testnet currencies). Keys are the extra-currency ids defined by the masterchain configuration.
+
+```ts
+type ExtraCurrencies = {
+    [key: string]: string;
+};
+```
+
+#### Hex
+
+`0x`-prefixed hexadecimal string used for public keys and other hashes.
+
+```ts
+type Hex = `0x${string}` & {
+    readonly [hashBrand]: never;
+};
+```
+
+#### TokenAmount
+
+Decimal string carrying a token amount; preserves precision and avoids floating-point rounding (e.g., `"1.5"` TON, or raw nano units depending on the API).
+
+```ts
+type TokenAmount = string;
+```
+
+#### UserFriendlyAddress
+
+User-friendly TON wallet address as a base64url string (e.g., `"EQDtFp...4q2"`).
+
+```ts
+type UserFriendlyAddress = string;
+```
+
+### Signing
+
+#### SignBinaryParameters
+
+Parameters accepted by [`signBinary`](#signbinary).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `bytes`\* | <code><a href="#base64string">Base64String</a></code> | Binary blob the user is asked to sign, encoded as Base64. |
+| `network` | <code><a href="#network">Network</a></code> | Network to issue the sign request against. Defaults to AppKit's configured default network; when none is set, the wallet falls back to its current network. |
+
+#### SignBinaryReturnType
+
+Return type of [`signBinary`](#signbinary).
+
+```ts
+type SignBinaryReturnType = SignDataResponse;
+```
+
+#### SignCellParameters
+
+Parameters accepted by [`signCell`](#signcell).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `cell`\* | <code><a href="#base64string">Base64String</a></code> | TON cell content encoded as Base64 (BoC). |
+| `schema`\* | `string` | TL-B-style schema describing the cell layout so the wallet can render the payload to the user. |
+| `network` | <code><a href="#network">Network</a></code> | Network to issue the sign request against. Defaults to AppKit's configured default network; when none is set, the wallet falls back to its current network. |
+
+#### SignCellReturnType
+
+Return type of [`signCell`](#signcell).
+
+```ts
+type SignCellReturnType = SignDataResponse;
+```
+
+#### SignData
+
+Payload the user is asked to sign — discriminated union over `'text'`, `'binary'`, and `'cell'`; nested under [`SignDataRequest`](#signdatarequest)'s `data`.
+
+```ts
+type SignData = | { type: 'text'; value: SignDataText }
+    | { type: 'binary'; value: SignDataBinary }
+    | { type: 'cell'; value: SignDataCell };
+```
+
+#### SignDataBinary
+
+Binary variant of [`SignData`](#signdata) — opaque byte content the user is asked to sign.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `content`\* | <code><a href="#base64string">Base64String</a></code> | Raw binary content encoded as Base64. |
+
+#### SignDataCell
+
+TON cell variant of [`SignData`](#signdata) — Base64-encoded cell payload paired with the schema needed to parse it.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `schema`\* | `string` | TL-B-style schema describing the cell layout so the wallet can render the payload to the user. |
+| `content`\* | <code><a href="#base64string">Base64String</a></code> | Cell content encoded as Base64. |
+
+#### SignDataRequest
+
+Sign-data payload sent to [`WalletInterface`](#walletinterface)'s `signData` — discriminated by `data.type` (`'text'`, `'binary'`, or `'cell'`).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="#network">Network</a></code> | Network to issue the sign request against; defaults to the wallet's current network. |
+| `from` | `string` | Sender address in raw format; usually omitted, the wallet fills it in. |
+| `data`\* | <code><a href="#signdata">SignData</a></code> | Payload the user is asked to sign. |
+
+#### SignDataResponse
+
+Wallet response to a [`SignDataRequest`](#signdatarequest) — carries the signature plus the canonicalized address, timestamp, and domain the wallet committed to.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `signature`\* | `string` | Base64-encoded signature. |
+| `address`\* | `string` | Wallet address that signed, in user-friendly format. |
+| `timestamp`\* | `number` | Unix timestamp the wallet stamped onto the signature. |
+| `domain`\* | `string` | dApp domain the wallet bound the signature to. |
+| `payload`\* | <code><a href="#signdatarequest">SignDataRequest</a></code> | Original payload that was signed, echoed back for binding. |
+
+#### SignDataText
+
+Plain-text variant of [`SignData`](#signdata) — UTF-8 string the user is asked to sign.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `content`\* | `string` | UTF-8 text the user signs. |
+
+#### SignTextParameters
+
+Parameters accepted by [`signText`](#signtext).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `text`\* | `string` | UTF-8 text the user is asked to sign. |
+| `network` | <code><a href="#network">Network</a></code> | Network to issue the sign request against. Defaults to AppKit's configured default network; when none is set, the wallet falls back to its current network. |
+
+#### SignTextReturnType
+
+Return type of [`signText`](#signtext).
+
+```ts
+type SignTextReturnType = SignDataResponse;
+```
+
+### Staking
+
+#### BuildStakeTransactionOptions
+
+Options for [`buildStakeTransaction`](#buildstaketransaction) — extends [`StakeParams`](#stakeparams) with an optional provider override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `quote`\* | <code><a href="#stakingquote">StakingQuote</a></code> | The staking quote based on which the transaction is built |
+| `userAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the user performing the staking |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `providerId` | `string` | Provider to stake/unstake through; defaults to the registered default staking provider. |
+
+#### BuildStakeTransactionReturnType
+
+Return type of [`buildStakeTransaction`](#buildstaketransaction).
+
+```ts
+type BuildStakeTransactionReturnType = Promise<TransactionRequest>;
+```
+
+#### GetStakedBalanceOptions
+
+Options for [`getStakedBalance`](#getstakedbalance).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `userAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Owner whose staked balance should be read. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+| `providerId` | `string` | Provider to query; defaults to the registered default staking provider. |
+
+#### GetStakedBalanceReturnType
+
+Return type of [`getStakedBalance`](#getstakedbalance).
+
+```ts
+type GetStakedBalanceReturnType = Promise<StakingBalance>;
+```
+
+#### GetStakingManagerReturnType
+
+Return type of [`getStakingManager`](#getstakingmanager).
+
+```ts
+type GetStakingManagerReturnType = StakingManager;
+```
+
+#### GetStakingProviderInfoOptions
+
+Options for [`getStakingProviderInfo`](#getstakingproviderinfo).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+| `providerId` | `string` | Provider to query; defaults to the registered default staking provider. |
+
+#### GetStakingProviderInfoReturnType
+
+Return type of [`getStakingProviderInfo`](#getstakingproviderinfo).
+
+```ts
+type GetStakingProviderInfoReturnType = Promise<StakingProviderInfo>;
+```
+
+#### GetStakingProviderMetadataOptions
+
+Options for [`getStakingProviderMetadata`](#getstakingprovidermetadata).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+| `providerId` | `string` | Provider to query; defaults to the registered default staking provider. |
+
+#### GetStakingProviderMetadataReturnType
+
+Return type of [`getStakingProviderMetadata`](#getstakingprovidermetadata).
+
+```ts
+type GetStakingProviderMetadataReturnType = StakingProviderMetadata;
+```
+
+#### GetStakingProviderOptions
+
+Options for [`getStakingProvider`](#getstakingprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Provider ID to look up; when omitted, returns the registered default staking provider. |
+
+#### GetStakingProviderReturnType
+
+Return type of [`getStakingProvider`](#getstakingprovider).
+
+```ts
+type GetStakingProviderReturnType = StakingProviderInterface;
+```
+
+#### GetStakingProvidersReturnType
+
+Return type of [`getStakingProviders`](#getstakingproviders).
+
+```ts
+type GetStakingProvidersReturnType = StakingProviderInterface[];
+```
+
+#### GetStakingQuoteOptions
+
+Options for [`getStakingQuote`](#getstakingquote) — extends [`StakingQuoteParams`](#stakingquoteparams) with an optional provider override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `direction`\* | <code><a href="#stakingquotedirection">StakingQuoteDirection</a></code> | Direction of the quote (stake or unstake) |
+| `amount`\* | `string` | Amount of tokens to stake or unstake |
+| `userAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the user |
+| `network` | <code><a href="#network">Network</a></code> | Network on which the staking will be executed |
+| `unstakeMode` | <code><a href="#unstakemodes">UnstakeModes</a></code> | Requested mode of unstaking |
+| `isReversed` | `boolean` | If true, for unstake requests the amount is specified in the staking coin (e.g. TON) instead of the Liquid Staking Token (e.g. tsTON). |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `providerId` | `string` | Provider to quote against; defaults to the registered default staking provider. |
+
+#### GetStakingQuoteReturnType
+
+Return type of [`getStakingQuote`](#getstakingquote).
+
+```ts
+type GetStakingQuoteReturnType = Promise<StakingQuote>;
+```
+
+#### SetDefaultStakingProviderParameters
+
+Parameters accepted by [`setDefaultStakingProvider`](#setdefaultstakingprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `providerId`\* | `string` | ID of the provider to make default — must already be registered. |
+
+#### SetDefaultStakingProviderReturnType
+
+Return type of [`setDefaultStakingProvider`](#setdefaultstakingprovider).
+
+```ts
+type SetDefaultStakingProviderReturnType = void;
+```
+
+#### StakeParams
+
+Parameters for staking TON
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `quote`\* | <code><a href="#stakingquote">StakingQuote</a></code> | The staking quote based on which the transaction is built |
+| `userAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the user performing the staking |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+
+#### StakingAPI
+
+Staking API interface exposed by StakingManager
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `getQuote`\* | <code>(params: <a href="#stakingquoteparams">StakingQuoteParams</a>, providerId?: string) =&gt; Promise&lt;<a href="#stakingquote">StakingQuote</a>&gt;</code> | Get a quote for staking or unstaking |
+| `buildStakeTransaction`\* | <code>(params: <a href="#stakeparams">StakeParams</a>, providerId?: string) =&gt; Promise&lt;<a href="#transactionrequest">TransactionRequest</a>&gt;</code> | Build a transaction for staking |
+| `getStakedBalance`\* | <code>(userAddress: <a href="#userfriendlyaddress">UserFriendlyAddress</a>, network?: <a href="#network">Network</a>, providerId?: string) =&gt; Promise&lt;<a href="#stakingbalance">StakingBalance</a>&gt;</code> | Get user's staked balance |
+| `getStakingProviderInfo`\* | <code>(network?: <a href="#network">Network</a>, providerId?: string) =&gt; Promise&lt;<a href="#stakingproviderinfo">StakingProviderInfo</a>&gt;</code> | Get staking provider information |
+| `getStakingProviderMetadata`\* | <code>(network?: <a href="#network">Network</a>, providerId?: string) =&gt; <a href="#stakingprovidermetadata">StakingProviderMetadata</a></code> | Get static metadata for a staking provider |
+| `createFactoryContext`\* | <code>() =&gt; <a href="#providerfactorycontext">ProviderFactoryContext</a></code> | Build a fresh [`ProviderFactoryContext`](#providerfactorycontext) the manager hands to provider factories at registration time. |
+| `registerProvider`\* | <code>(provider: <a href="#providerinput">ProviderInput</a>&lt;StakingProviderInterface&gt;) =&gt; void</code> | Register a new provider. If a provider with the same id is already registered, it is replaced. |
+| `removeProvider`\* | `(provider: StakingProviderInterface) => void` | Remove a previously registered provider. No-op if the provider was not registered. |
+| `setDefaultProvider`\* | `(providerId: string) => void` | Set the default provider |
+| `getProvider`\* | `(providerId?: string) => StakingProviderInterface` | Get a registered provider |
+| `getProviders`\* | `() => Array<StakingProviderInterface>` | Get all registered providers. The returned array keeps a stable reference until the provider list changes. |
+| `hasProvider`\* | `(providerId: string) => boolean` | Check if a provider is registered |
+
+#### StakingBalance
+
+Staking balance information for a user
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `rawStakedBalance`\* | <code><a href="#tokenamount">TokenAmount</a></code> | Amount currently staked |
+| `stakedBalance`\* | `string` | Amount currently staked |
+| `rawInstantUnstakeAvailable`\* | <code><a href="#tokenamount">TokenAmount</a></code> | Amount available for instant unstake |
+| `instantUnstakeAvailable`\* | `string` | Amount available for instant unstake |
+| `providerId`\* | `string` | Identifier of the staking provider |
+
+#### StakingProviderInfo
+
+Dynamic staking information for a provider
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `apy`\* | `number` | Annual Percentage Yield in basis points (100 = 1%) |
+| `rawInstantUnstakeAvailable` | <code><a href="#tokenamount">TokenAmount</a></code> | Amount available for instant unstake |
+| `instantUnstakeAvailable` | `string` | Amount available for instant unstake |
+| `exchangeRate` | `string` | Exchange rate between stakeToken and receiveToken (e.g. 1 TON = 0.95 tsTON). Undefined when there is no receiveToken (direct/custodial staking). |
+
+#### StakingProviderMetadata
+
+Static metadata for a staking provider
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name`\* | `string` | Human-readable provider name (e.g. "Tonstakers") |
+| `supportedUnstakeModes`\* | <code><a href="#unstakemodes">UnstakeModes</a>[]</code> | Supported unstake modes for this provider |
+| `supportsReversedQuote`\* | `boolean` | Whether provider supports reversed quote format (e.g., passing TON instead of tsTON for unstake) |
+| `stakeToken`\* | <code><a href="#stakingtokeninfo">StakingTokenInfo</a></code> | Token that the user sends when staking (e.g. TON) |
+| `receiveToken` | <code><a href="#stakingtokeninfo">StakingTokenInfo</a></code> | Token that the user receives when staking (e.g. tsTON for liquid staking). Absent for direct/custodial staking. |
+| `contractAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Provider contract address (optional — custodial providers may not have one) |
+
+#### StakingQuote
+
+Staking quote response with pricing information
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `direction`\* | <code><a href="#stakingquotedirection">StakingQuoteDirection</a></code> | Direction of the quote (stake or unstake) |
+| `rawAmountIn`\* | <code><a href="#tokenamount">TokenAmount</a></code> | Amount of tokens being provided |
+| `rawAmountOut`\* | <code><a href="#tokenamount">TokenAmount</a></code> | Estimated amount of tokens to be received |
+| `amountIn`\* | `string` | Formatted amount of tokens being provided |
+| `amountOut`\* | `string` | Formatted estimated amount of tokens to be received |
+| `network`\* | <code><a href="#network">Network</a></code> | Network on which the staking will be executed |
+| `providerId`\* | `string` | Identifier of the staking provider |
+| `unstakeMode` | <code><a href="#unstakemodes">UnstakeModes</a></code> | Mode of unstaking (if applicable) |
+| `metadata` | `unknown` | Provider-specific metadata for the quote |
+
+#### StakingQuoteDirection
+
+Direction of the staking quote
+
+```ts
+type StakingQuoteDirection = 'stake' | 'unstake';
+```
+
+#### StakingQuoteParams
+
+Parameters for getting a staking quote
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `direction`\* | <code><a href="#stakingquotedirection">StakingQuoteDirection</a></code> | Direction of the quote (stake or unstake) |
+| `amount`\* | `string` | Amount of tokens to stake or unstake |
+| `userAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the user |
+| `network` | <code><a href="#network">Network</a></code> | Network on which the staking will be executed |
+| `unstakeMode` | <code><a href="#unstakemodes">UnstakeModes</a></code> | Requested mode of unstaking |
+| `isReversed` | `boolean` | If true, for unstake requests the amount is specified in the staking coin (e.g. TON) instead of the Liquid Staking Token (e.g. tsTON). |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+
+#### StakingTokenInfo
+
+Display metadata for a staking-pool token — `ticker`, `decimals` and `address` (or `'ton'` for native TON); carried on [`StakingProviderMetadata`](#stakingprovidermetadata)'s `stakeToken` and `receiveToken` so the UI can render the pool's input/output assets.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `ticker`\* | `string` | Ticker symbol (e.g., `"TON"`, `"tsTON"`). |
+| `decimals`\* | `number` | Number of decimal places used to format raw amounts. |
+| `address`\* | `string` | `'ton'` for native TON, otherwise the token contract address in user-friendly format. |
+
+#### TonStakersProviderConfig
+
+Configuration accepted by [`createTonstakersProvider`](#createtonstakersprovider).
+
+_Empty type._
+
+#### UnstakeModes
+
+Mode of unstaking
+
+```ts
+type UnstakeModes = (typeof UnstakeMode)[keyof typeof UnstakeMode];
+```
+
+#### WatchStakingProvidersParameters
+
+Parameters accepted by [`watchStakingProviders`](#watchstakingproviders).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | `() => void` | Callback fired whenever a staking provider is registered or the default staking provider changes. |
+
+#### WatchStakingProvidersReturnType
+
+Return type of [`watchStakingProviders`](#watchstakingproviders) — call to stop receiving updates.
+
+```ts
+type WatchStakingProvidersReturnType = () => void;
+```
+
+### Swap
+
+#### BuildSwapTransactionOptions
+
+Options for [`buildSwapTransaction`](#buildswaptransaction) — same shape as [`SwapParams`](#swapparams).
+
+```ts
+type BuildSwapTransactionOptions = SwapParams<T>;
+```
+
+#### BuildSwapTransactionReturnType
+
+Return type of [`buildSwapTransaction`](#buildswaptransaction).
+
+```ts
+type BuildSwapTransactionReturnType = Promise<TransactionRequest>;
+```
+
+#### DeDustProviderOptions
+
+DeDust-specific options forwarded through `providerOptions` on [`SwapQuoteParams`](#swapquoteparams) / [`SwapParams`](#swapparams).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `protocols` | `string[]` | Protocols to use for routing Available: 'dedust', 'dedust_v3', 'dedust_v3_memepad', 'stonfi_v1', 'stonfi_v2', 'tonco', 'memeslab', 'tonfun' |
+| `excludeProtocols` | `string[]` | Protocols to exclude from routing |
+| `onlyVerifiedPools` | `boolean` | Only use verified pools |
+| `maxSplits` | `number` | Maximum number of route splits |
+| `maxLength` | `number` | Maximum route length (hops) |
+| `excludeVolatilePools` | `boolean` | Exclude volatile pools |
+| `referralAddress` | `string` | The address of the referrer |
+| `referralFeeBps` | `number` | Referral fee in basis points (max 100 = 1%) |
+
+#### DeDustQuoteMetadata
+
+Provider-specific metadata returned on a [`SwapQuote`](#swapquote)'s `metadata` from DeDust — carries the resolved route, fees and `swapData` payload that [`buildSwapTransaction`](#buildswaptransaction) needs.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `quoteResponse`\* | `DeDustQuoteResponse` | Raw quote response from API |
+| `slippageBps`\* | `number` | Slippage used for the quote in basis points |
+
+#### DeDustReferralOptions
+
+Optional referral metadata attached to DeDust swaps so the provider can attribute them.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `referralAddress` | `string` | The address of the referrer |
+| `referralFeeBps` | `number` | Referral fee in basis points (max 100 = 1%) |
+
+#### DeDustSwapProviderConfig
+
+Configuration accepted by [`createDeDustProvider`](#creatededustprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `providerId` | `string` | Custom provider ID (defaults to 'dedust') |
+| `defaultSlippageBps` | `number` | Default slippage tolerance in basis points (1 bp = 0.01%) |
+| `apiUrl` | `string` | API base URL |
+| `onlyVerifiedPools` | `boolean` | Only use verified pools |
+| `maxSplits` | `number` | Maximum number of route splits |
+| `maxLength` | `number` | Maximum route length (hops) |
+| `minPoolUsdTvl` | `string` | Minimum pool TVL in USD |
+| `metadata` | `SwapProviderMetadataOverride` | Custom metadata for the provider |
+| `referralAddress` | `string` | The address of the referrer |
+| `referralFeeBps` | `number` | Referral fee in basis points (max 100 = 1%) |
+
+#### GetSwapManagerReturnType
+
+Return type of [`getSwapManager`](#getswapmanager).
+
+```ts
+type GetSwapManagerReturnType = SwapManager;
+```
+
+#### GetSwapProviderOptions
+
+Options for [`getSwapProvider`](#getswapprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Provider ID to look up; when omitted, returns the registered default swap provider. |
+
+#### GetSwapProviderReturnType
+
+Return type of [`getSwapProvider`](#getswapprovider).
+
+```ts
+type GetSwapProviderReturnType = SwapProviderInterface;
+```
+
+#### GetSwapProvidersReturnType
+
+Return type of [`getSwapProviders`](#getswapproviders).
+
+```ts
+type GetSwapProvidersReturnType = SwapProviderInterface[];
+```
+
+#### GetSwapQuoteOptions
+
+Options for [`getSwapQuote`](#getswapquote) — extends [`SwapQuoteParams`](#swapquoteparams) with an optional provider override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `amount`\* | `string` | Amount of tokens to swap (incoming or outgoing depending on isReverseSwap) |
+| `from`\* | <code><a href="#swaptoken">SwapToken</a></code> | Token to swap from |
+| `to`\* | <code><a href="#swaptoken">SwapToken</a></code> | Token to swap to |
+| `network`\* | <code><a href="#network">Network</a></code> | Network on which the swap will be executed |
+| `slippageBps` | `number` | Slippage tolerance in basis points (1 bp = 0.01%) |
+| `maxOutgoingMessages` | `number` | Maximum number of outgoing messages |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `isReverseSwap` | `boolean` | If true, amount is the amount to receive (buy). If false, amount is the amount to spend (sell). |
+| `providerId` | `string` | Provider to quote against; defaults to the registered default swap provider. |
+
+#### GetSwapQuoteReturnType
+
+Return type of [`getSwapQuote`](#getswapquote).
+
+```ts
+type GetSwapQuoteReturnType = Promise<SwapQuote>;
+```
+
+#### OmnistonProviderOptions
+
+Omniston-specific options forwarded through `providerOptions` on [`SwapQuoteParams`](#swapquoteparams) / [`SwapParams`](#swapparams).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `settlementMethods` | `SettlementMethodValue[]` | Settlement methods to use for the swap |
+| `referrerAddress` | `string` | The address of the referrer |
+| `referrerFeeBps` | `number` | Referrer fee in basis points (1 bp = 0.01%) |
+| `flexibleReferrerFee` | `boolean` | Whether a flexible referrer fee is allowed |
+
+#### OmnistonQuoteMetadata
+
+Provider-specific metadata returned on a [`SwapQuote`](#swapquote)'s `metadata` from Omniston — carries the resolved route and signed quote payload that [`buildSwapTransaction`](#buildswaptransaction) needs.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `omnistonQuote`\* | `Quote` | The actual Omniston quote object |
+
+#### OmnistonReferrerOptions
+
+Optional referrer metadata attached to Omniston swaps so the provider can attribute them.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `referrerAddress` | `string` | The address of the referrer |
+| `referrerFeeBps` | `number` | Referrer fee in basis points (1 bp = 0.01%) |
+| `flexibleReferrerFee` | `boolean` | Whether a flexible referrer fee is allowed |
+
+#### OmnistonSwapProviderConfig
+
+Configuration accepted by [`createOmnistonProvider`](#createomnistonprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `apiUrl` | `string` | Optional URL for the Omniston API |
+| `defaultSlippageBps` | `number` | Default slippage tolerance in basis points (1 bp = 0.01%) |
+| `quoteTimeoutMs` | `number` | Timeout for quote requests in milliseconds |
+| `providerId` | `string` | Identifier for the provider |
+| `metadata` | `SwapProviderMetadataOverride` | Custom metadata for the provider |
+| `referrerAddress` | `string` | The address of the referrer |
+| `referrerFeeBps` | `number` | Referrer fee in basis points (1 bp = 0.01%) |
+| `flexibleReferrerFee` | `boolean` | Whether a flexible referrer fee is allowed |
+
+#### SetDefaultSwapProviderParameters
+
+Parameters accepted by [`setDefaultSwapProvider`](#setdefaultswapprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `providerId`\* | `string` | ID of the provider to make default — must already be registered. |
+
+#### SetDefaultSwapProviderReturnType
+
+Return type of [`setDefaultSwapProvider`](#setdefaultswapprovider).
+
+```ts
+type SetDefaultSwapProviderReturnType = void;
+```
+
+#### SwapAPI
+
+API surface exposed by [`SwapManager`](#swapmanager) — quote and build-transaction calls (plus the provider-management methods inherited from [`DefiManagerAPI`](#defimanagerapi)). Mostly relevant when authoring a swap manager replacement.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `getQuote`\* | <code>(params: <a href="#swapquoteparams">SwapQuoteParams</a>, providerId?: string) =&gt; Promise&lt;<a href="#swapquote">SwapQuote</a>&gt;</code> | Get a quote for swapping tokens |
+| `buildSwapTransaction`\* | <code>(params: <a href="#swapparams">SwapParams</a>) =&gt; Promise&lt;<a href="#transactionrequest">TransactionRequest</a>&gt;</code> | Build a transaction for a swap. Provider is taken from `params.quote.providerId`, or the manager default. |
+| `createFactoryContext`\* | <code>() =&gt; <a href="#providerfactorycontext">ProviderFactoryContext</a></code> | Build a fresh [`ProviderFactoryContext`](#providerfactorycontext) the manager hands to provider factories at registration time. |
+| `registerProvider`\* | <code>(provider: <a href="#providerinput">ProviderInput</a>&lt;SwapProviderInterface&lt;unknown, unknown&gt;&gt;) =&gt; void</code> | Register a new provider. If a provider with the same id is already registered, it is replaced. |
+| `removeProvider`\* | `(provider: SwapProviderInterface<unknown, unknown>) => void` | Remove a previously registered provider. No-op if the provider was not registered. |
+| `setDefaultProvider`\* | `(providerId: string) => void` | Set the default provider |
+| `getProvider`\* | `(providerId?: string) => SwapProviderInterface<unknown, unknown>` | Get a registered provider |
+| `getProviders`\* | `() => Array<SwapProviderInterface<unknown, unknown>>` | Get all registered providers. The returned array keeps a stable reference until the provider list changes. |
+| `hasProvider`\* | `(providerId: string) => boolean` | Check if a provider is registered |
+
+#### SwapParams
+
+Parameters consumed by [`buildSwapTransaction`](#buildswaptransaction) — the previously obtained [`SwapQuote`](#swapquote) plus optional provider-specific options (`TProviderOptions`).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `quote`\* | <code><a href="#swapquote">SwapQuote</a></code> | The swap quote based on which the transaction is built |
+| `userAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the user performing the swap |
+| `destinationAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address to receive the swapped tokens (defaults to userAddress) |
+| `slippageBps` | `number` | Slippage tolerance in basis points (1 bp = 0.01%) |
+| `deadline` | `number` | Transaction deadline in unix timestamp |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+
+#### SwapQuote
+
+Quote returned by [`getSwapQuote`](#getswapquote) — source/target tokens, expected amounts, rate, slippage, fees and the provider-specific `metadata` that [`buildSwapTransaction`](#buildswaptransaction) needs to construct the transaction.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `fromToken`\* | <code><a href="#swaptoken">SwapToken</a></code> | Token being sold |
+| `toToken`\* | <code><a href="#swaptoken">SwapToken</a></code> | Token being bought |
+| `rawFromAmount`\* | <code><a href="#tokenamount">TokenAmount</a></code> | Amount of tokens to sell |
+| `rawToAmount`\* | <code><a href="#tokenamount">TokenAmount</a></code> | Amount of tokens to buy |
+| `fromAmount`\* | `string` | Amount of tokens to sell |
+| `toAmount`\* | `string` | Amount of tokens to buy |
+| `rawMinReceived`\* | <code><a href="#tokenamount">TokenAmount</a></code> | Minimum amount of tokens to receive (after slippage) |
+| `minReceived`\* | `string` | Minimum amount of tokens to receive (after slippage) |
+| `network`\* | <code><a href="#network">Network</a></code> | Network on which the swap will be executed |
+| `priceImpact` | `number` | Price impact of the swap in basis points (100 = 1%) |
+| `providerId`\* | `string` | Identifier of the swap provider |
+| `expiresAt` | `number` | Unix timestamp in seconds when the quote expires |
+| `metadata` | `unknown` | Provider-specific metadata for the quote |
+
+#### SwapQuoteParams
+
+Parameters consumed by [`getSwapQuote`](#getswapquote) — source/target tokens and an amount that is interpreted as either the spend side or the receive side (`isReverseSwap` flag), plus optional slippage and provider-specific options.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `amount`\* | `string` | Amount of tokens to swap (incoming or outgoing depending on isReverseSwap) |
+| `from`\* | <code><a href="#swaptoken">SwapToken</a></code> | Token to swap from |
+| `to`\* | <code><a href="#swaptoken">SwapToken</a></code> | Token to swap to |
+| `network`\* | <code><a href="#network">Network</a></code> | Network on which the swap will be executed |
+| `slippageBps` | `number` | Slippage tolerance in basis points (1 bp = 0.01%) |
+| `maxOutgoingMessages` | `number` | Maximum number of outgoing messages |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `isReverseSwap` | `boolean` | If true, amount is the amount to receive (buy). If false, amount is the amount to spend (sell). |
+
+#### SwapToken
+
+Token descriptor passed to [`getSwapQuote`](#getswapquote) via [`SwapQuoteParams`](#swapquoteparams)'s `from` and `to` fields (and surfaced on the resulting [`SwapQuote`](#swapquote)) — address, decimals plus optional symbol/name/image used by swap-input UIs.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | `string` | Token contract address; `'ton'` is used for native TON on the TON chain. |
+| `decimals`\* | `number` | Number of decimal places used to format raw amounts. |
+| `name` | `string` | Display name (e.g., `"Tether USD"`). |
+| `symbol` | `string` | Ticker symbol (e.g., `"USDT"`). |
+| `image` | `string` | URL of the token's image. |
+| `chainId` | `string` | Chain id in CAIP-2 format when the token lives outside TON. |
+
+#### WatchSwapProvidersParameters
+
+Parameters accepted by [`watchSwapProviders`](#watchswapproviders).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | `() => void` | Callback fired whenever a swap provider is registered or the default swap provider changes. |
+
+#### WatchSwapProvidersReturnType
+
+Return type of [`watchSwapProviders`](#watchswapproviders) — call to stop receiving updates.
+
+```ts
+type WatchSwapProvidersReturnType = () => void;
+```
+
+### Transactions
+
+#### CreateTransferTonTransactionParameters
+
+Parameters accepted by [`createTransferTonTransaction`](#createtransfertontransaction) and [`transferTon`](#transferton).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `recipientAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Recipient address. |
+| `amount`\* | `string` | Amount in TON as a human-readable decimal string (e.g., `"1.5"`); converted to nano-TON internally. |
+| `comment` | `string` | Human-readable text comment; converted to a Base64 payload when no `payload` is supplied. |
+| `payload` | <code><a href="#base64string">Base64String</a></code> | Raw Base64 message payload — wins over `comment` when both are set. |
+| `stateInit` | <code><a href="#base64string">Base64String</a></code> | Initial state for deploying a new contract, encoded as Base64. |
+
+#### CreateTransferTonTransactionReturnType
+
+Return type of [`createTransferTonTransaction`](#createtransfertontransaction).
+
+```ts
+type CreateTransferTonTransactionReturnType = TransactionRequest;
+```
+
+#### GetTransactionStatusParameters
+
+Parameters accepted by [`getTransactionStatus`](#gettransactionstatus) — must carry exactly one of `boc` or `normalizedHash`, plus an optional network override.
+
+```ts
+type GetTransactionStatusParameters = {
+    /** Network to check the transaction 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. */
+    network?: Network;
+} & (
+    | {
+          /** Base64-encoded BoC of the sent transaction (returned by {@link sendTransaction}). */
+          boc: string;
+          normalizedHash?: never;
+      }
+    | {
+          boc?: never;
+          /** Hex-encoded normalized hash of the external-in message (returned by {@link sendTransaction} as `normalizedHash`). */
+          normalizedHash: string;
+      }
+);
+```
+
+#### GetTransactionStatusReturnType
+
+Return type of [`getTransactionStatus`](#gettransactionstatus).
+
+```ts
+type GetTransactionStatusReturnType = TransactionStatusResponse;
+```
+
+#### SendTransactionParameters
+
+Parameters accepted by [`sendTransaction`](#sendtransaction) — same shape as [`TransactionRequest`](#transactionrequest).
+
+```ts
+type SendTransactionParameters = TransactionRequest;
+```
+
+#### SendTransactionResponse
+
+Wallet response carrying the BoC (bag of cells) of the external message that was signed and broadcast — used to track or hash the resulting transaction.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `boc`\* | <code><a href="#base64string">Base64String</a></code> | BoC of the sent transaction |
+| `normalizedBoc`\* | <code><a href="#base64string">Base64String</a></code> | Normalized BoC of the external-in message |
+| `normalizedHash`\* | <code><a href="#hex">Hex</a></code> | Hash of the normalized external-in message |
+
+#### SendTransactionReturnType
+
+Return type of [`sendTransaction`](#sendtransaction).
+
+```ts
+type SendTransactionReturnType = SendTransactionResponse;
+```
+
+#### Transaction
+
+Single transaction record carried inside [`TransactionsUpdate`](#transactionsupdate)'s `transactions` — account, lt/hash, in/out messages and emulation result.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `account`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Account of the transaction |
+| `accountStateBefore` | `AccountState` | The state of the account before the transaction was executed |
+| `accountStateAfter` | `AccountState` | The state of the account after the transaction has been applied |
+| `description` | `TransactionDescription` | The detailed breakdown of the transaction execution |
+| `hash`\* | <code><a href="#hex">Hex</a></code> | Hash of the transaction |
+| `logicalTime`\* | `LogicalTime` | The logical time of the transaction |
+| `now`\* | `number` | Unix timestamp of the transaction |
+| `mcBlockSeqno`\* | `number` | Masterchain block sequence number |
+| `traceExternalHash`\* | <code><a href="#hex">Hex</a></code> | External hash of the trace |
+| `traceId` | `string` | ID of the trace |
+| `previousTransactionHash` | `string` | The hash of the previous transaction |
+| `previousTransactionLogicalTime` | `LogicalTime` | The logical time of the previous transaction |
+| `origStatus` | `AccountStatus` | Original status of the transaction |
+| `endStatus` | `AccountStatus` | End status of the transaction |
+| `totalFees` | <code><a href="#tokenamount">TokenAmount</a></code> | Total fees of the transaction |
+| `totalFeesExtraCurrencies` | <code><a href="#extracurrencies">ExtraCurrencies</a></code> | Extra currencies in the total fees |
+| `blockRef` | `TransactionBlockRef` | The reference to the block in which the transaction was included |
+| `inMessage` | `TransactionMessage` | The incoming message associated with the transaction |
+| `outMessages`\* | `TransactionMessage[]` | The list of outgoing messages produced by the transaction |
+| `isEmulated`\* | `boolean` | Emulated state of the transaction |
+
+#### TransactionRequest
+
+Transaction payload passed to [`WalletInterface`](#walletinterface)'s `sendTransaction` — one or more messages, optional network override and `validUntil` deadline.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `messages`\* | <code><a href="#transactionrequestmessage">TransactionRequestMessage</a>[]</code> | Messages to include in the transaction. |
+| `network` | <code><a href="#network">Network</a></code> | Network to execute the transaction on. |
+| `validUntil` | `number` | Unix timestamp (seconds) after which the transaction becomes invalid. |
+| `fromAddress` | `string` | Sender wallet address — accepts either raw or user-friendly format. |
+
+#### TransactionRequestMessage
+
+Individual message inside a [`TransactionRequest`](#transactionrequest) — recipient, amount, optional payload and contract `stateInit`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | `string` | Recipient wallet address — accepts either raw or user-friendly format. |
+| `amount`\* | <code><a href="#tokenamount">TokenAmount</a></code> | Amount to transfer, in nano-TON (1 TON = 10⁹ nano-TON). |
+| `extraCurrency` | <code><a href="#extracurrencies">ExtraCurrencies</a></code> | Additional currencies to include in the transfer. |
+| `stateInit` | `string` | Initial state for deploying a new contract, encoded as Base64. |
+| `payload` | `string` | Message payload, encoded as Base64. |
+
+#### TransactionsUpdate
+
+Update payload delivered to [`watchTransactions`](#watchtransactions) / [`watchTransactionsByAddress`](#watchtransactionsbyaddress) subscribers when transactions land for the watched address.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `type`\* | `'transactions'` | The update type field |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The account address |
+| `transactions`\* | <code><a href="#transaction">Transaction</a>[]</code> | The array of transactions |
+| `traceHash`\* | <code><a href="#hex">Hex</a></code> | The hash of the trace |
+| `addressBook` | <code><a href="#addressbook">AddressBook</a></code> | Address book from streaming v2 notification |
+| `metadata` | `TransactionAddressMetadata` | Metadata from streaming v2 notification |
+| `status`\* | <code><a href="#streamingupdatestatus">StreamingUpdateStatus</a></code> | The finality of the update |
+
+#### TransferTonParameters
+
+Parameters accepted by [`transferTon`](#transferton) — same shape as [`CreateTransferTonTransactionParameters`](#createtransfertontransactionparameters).
+
+```ts
+type TransferTonParameters = CreateTransferTonTransactionParameters;
+```
+
+#### TransferTonReturnType
+
+Return type of [`transferTon`](#transferton).
+
+```ts
+type TransferTonReturnType = SendTransactionResponse;
+```
+
+#### WatchTransactionsByAddressOptions
+
+Options for [`watchTransactionsByAddress`](#watchtransactionsbyaddress).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Address to watch — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `onChange`\* | <code>(update: <a href="#transactionsupdate">TransactionsUpdate</a>) =&gt; void</code> | Callback fired on every transactions update from the streaming provider. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+
+#### WatchTransactionsByAddressReturnType
+
+Return type of [`watchTransactionsByAddress`](#watchtransactionsbyaddress) — call to stop receiving updates.
+
+```ts
+type WatchTransactionsByAddressReturnType = () => void;
+```
+
+#### WatchTransactionsOptions
+
+Options for [`watchTransactions`](#watchtransactions).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | <code>(update: <a href="#transactionsupdate">TransactionsUpdate</a>) =&gt; void</code> | Callback fired on every transactions update from the streaming provider. |
+| `network` | <code><a href="#network">Network</a></code> | Network to watch on. Defaults to the selected wallet's network. |
+
+#### WatchTransactionsReturnType
+
+Return type of [`watchTransactions`](#watchtransactions) — call to stop receiving updates.
+
+```ts
+type WatchTransactionsReturnType = () => void;
+```
+
+### Wallets
+
+#### GetConnectedWalletsReturnType
+
+Return type of [`getConnectedWallets`](#getconnectedwallets) — read-only view of the connected-wallets array.
+
+```ts
+type GetConnectedWalletsReturnType = readonly WalletInterface[];
+```
+
+#### GetSelectedWalletReturnType
+
+Return type of [`getSelectedWallet`](#getselectedwallet) — `null` when no wallet is currently selected.
+
+```ts
+type GetSelectedWalletReturnType = WalletInterface | null;
+```
+
+#### SetSelectedWalletIdParameters
+
+Parameters accepted by [`setSelectedWalletId`](#setselectedwalletid).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `walletId`\* | `string \| null` | Wallet ID (as returned by [`WalletInterface`](#walletinterface)'s `getWalletId()`) to select; pass `null` to clear the selection. |
+
+#### SetSelectedWalletIdReturnType
+
+Return type of [`setSelectedWalletId`](#setselectedwalletid).
+
+```ts
+type SetSelectedWalletIdReturnType = void;
+```
+
+#### TonConnectWalletAdapterConfig
+
+Configuration accepted by [`TonConnectWalletAdapter`](#tonconnectwalletadapter) when wrapping a TonConnect wallet for AppKit.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `connectorId`\* | `string` | ID of the connector that produced this wallet — surfaced as `WalletInterface.connectorId`. |
+| `tonConnectWallet`\* | `TonConnectWallet` | Underlying TonConnect wallet object. |
+| `tonConnectUI`\* | `TonConnectUI` | TonConnect UI instance used to drive `sendTransaction` and `signData` calls. |
+
+#### WalletInterface
+
+Wallet contract surfaced by every [`Connector`](#connector) — covers identity (address, public key, network) and signing operations; reads (balance, jettons, NFTs) go through AppKit actions instead.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `connectorId`\* | `string` | ID of the [`Connector`](#connector) that produced this wallet. |
+| `getAddress`\* | <code>() =&gt; <a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Wallet address as a user-friendly base64url string. |
+| `getPublicKey`\* | <code>() =&gt; <a href="#hex">Hex</a></code> | Wallet public key as a `0x`-prefixed hex string. |
+| `getNetwork`\* | <code>() =&gt; <a href="#network">Network</a></code> | Network the wallet is currently connected to. |
+| `getWalletId`\* | `() => string` | Stable identifier combining address and network — unique across AppKit's connected wallets. |
+| `sendTransaction`\* | <code>(request: <a href="#transactionrequest">TransactionRequest</a>) =&gt; Promise&lt;<a href="#sendtransactionresponse">SendTransactionResponse</a>&gt;</code> | Send a transaction — the wallet signs and broadcasts it. |
+| `signData`\* | <code>(payload: <a href="#signdatarequest">SignDataRequest</a>) =&gt; Promise&lt;<a href="#signdataresponse">SignDataResponse</a>&gt;</code> | Sign arbitrary data — text, binary or TON cell — through the wallet's sign-data flow. |
+
+#### WatchConnectedWalletsParameters
+
+Parameters accepted by [`watchConnectedWallets`](#watchconnectedwallets).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | <code>(wallets: <a href="#walletinterface">WalletInterface</a>[]) =&gt; void</code> | Callback fired whenever the list of connected wallets changes — receives the latest snapshot. |
+
+#### WatchConnectedWalletsReturnType
+
+Return type of [`watchConnectedWallets`](#watchconnectedwallets) — call to stop receiving updates.
+
+```ts
+type WatchConnectedWalletsReturnType = () => void;
+```
+
+#### WatchSelectedWalletParameters
+
+Parameters accepted by [`watchSelectedWallet`](#watchselectedwallet).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | <code>(wallet: <a href="#walletinterface">WalletInterface</a> \| null) =&gt; void</code> | Callback fired whenever the selected wallet changes — receives the new wallet, or `null` when the selection was cleared. |
+
+#### WatchSelectedWalletReturnType
+
+Return type of [`watchSelectedWallet`](#watchselectedwallet) — call to stop receiving updates.
+
+```ts
+type WatchSelectedWalletReturnType = () => void;
+```
+
+## Constants
+
+### Connectors
+
+#### CONNECTOR_EVENTS
+
+Event names AppKit emits for connector-list and connector-wallet changes; payloads are [`ConnectorAddedPayload`](#connectoraddedpayload), [`ConnectorRemovedPayload`](#connectorremovedpayload) and [`ConnectorWalletsUpdatedPayload`](#connectorwalletsupdatedpayload).
+
+```ts
+const CONNECTOR_EVENTS = {
+    /** A connector was registered via {@link addConnector} (or AppKit's constructor). */
+    ADDED: 'connector:added',
+    /** A connector was unregistered via `removeConnector` or its own teardown. */
+    REMOVED: 'connector:removed',
+    /** A connector's connected-wallets list changed (connect, disconnect, or account switch inside the wallet). */
+    WALLETS_UPDATED: 'connector:wallets-updated',
+} as const;
+```
+
+#### TONCONNECT_DEFAULT_CONNECTOR_ID
+
+Default id assigned to the TonConnect connector when none is supplied to [`createTonConnectConnector`](#createtonconnectconnector); pass this to [`connect`](#connect) / [`disconnect`](#disconnect) to drive the TonConnect flow without hard-coding the literal.
+
+```ts
+const TONCONNECT_DEFAULT_CONNECTOR_ID = 'tonconnect';
+```
+
+### Networks
+
+#### NETWORKS_EVENTS
+
+Event names AppKit emits on network changes; `DEFAULT_CHANGED` carries a [`DefaultNetworkChangedPayload`](#defaultnetworkchangedpayload).
+
+```ts
+const NETWORKS_EVENTS = {
+    UPDATED: 'networks:updated',
+    DEFAULT_CHANGED: 'networks:default-changed',
+} as const;
+```
+
+### Staking
+
+#### StakingErrorCode
+
+Discriminator carried on every [`StakingError`](#stakingerror)'s `code` — `'INVALID_PARAMS'` (the request was malformed) or `'UNSUPPORTED_OPERATION'` (the provider doesn't support this call).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `InvalidParams`\* | `"INVALID_PARAMS"` | Caller passed parameters that fail provider-level validation. |
+| `UnsupportedOperation`\* | `"UNSUPPORTED_OPERATION"` | Provider doesn't support the requested operation (e.g., reversed quote on a unidirectional pool). |
+
+#### UnstakeMode
+
+Allowed unstake-timing flavours referenced by [`UnstakeModes`](#unstakemodes) and [`StakingProviderMetadata`](#stakingprovidermetadata)'s `supportedUnstakeModes` — `'INSTANT'` (immediate withdrawal when the pool has liquidity, otherwise the funds are returned), `'WHEN_AVAILABLE'` (paid out as soon as liquidity is available — instantly or at round end), `'ROUND_END'` (paid out at the end of the staking round, typically for the best rate).
+
+```ts
+const UnstakeMode = { readonly INSTANT: "INSTANT"; readonly WHEN_AVAILABLE: "WHEN_AVAILABLE"; readonly ROUND_END: "ROUND_END"; };
+```
+
+### Wallets
+
+#### WALLETS_EVENTS
+
+Event names AppKit emits when the available wallet list (`UPDATED`) or the active wallet (`SELECTION_CHANGED`) changes.
+
+```ts
+const WALLETS_EVENTS = {
+    UPDATED: 'wallets:updated',
+    SELECTION_CHANGED: 'wallets:selection-changed',
+} as const;
+```
diff --git a/template/packages/appkit/docs/staking.md b/docs/templates/packages/appkit/docs/staking.md
similarity index 86%
rename from template/packages/appkit/docs/staking.md
rename to docs/templates/packages/appkit/docs/staking.md
index 155ad0a82..32abd139f 100644
--- a/template/packages/appkit/docs/staking.md
+++ b/docs/templates/packages/appkit/docs/staking.md
@@ -16,13 +16,13 @@ Staking providers are included in the `@ton/appkit` package. No extra dependenci
 
 You can set up staking providers by passing them to the `AppKit` constructor.
 
-%%demo/examples/src/appkit/staking#STAKING_PROVIDER_INIT%%
+%%docs/examples/src/appkit/staking#STAKING_PROVIDER_INIT%%
 
 ### Register Dynamically
 
 Alternatively, you can register providers dynamically using `registerProvider`:
 
-%%demo/examples/src/appkit/staking#STAKING_PROVIDER_REGISTER%%
+%%docs/examples/src/appkit/staking#STAKING_PROVIDER_REGISTER%%
 
 ## Configuration
 
diff --git a/template/packages/appkit/docs/swap.md b/docs/templates/packages/appkit/docs/swap.md
similarity index 91%
rename from template/packages/appkit/docs/swap.md
rename to docs/templates/packages/appkit/docs/swap.md
index 0030cd991..024be56ba 100644
--- a/template/packages/appkit/docs/swap.md
+++ b/docs/templates/packages/appkit/docs/swap.md
@@ -23,13 +23,13 @@ npm install @ston-fi/omniston-sdk
 
 You can set up swap providers by passing them to the `AppKit` constructor.
 
-%%demo/examples/src/appkit/swap#SWAP_PROVIDER_INIT%%
+%%docs/examples/src/appkit/swap#SWAP_PROVIDER_INIT%%
 
 ### Register Dynamically
 
 Alternatively, you can register providers dynamically using `registerProvider`:
 
-%%demo/examples/src/appkit/swap#SWAP_PROVIDER_REGISTER%%
+%%docs/examples/src/appkit/swap#SWAP_PROVIDER_REGISTER%%
 
 ## Configuration
 
diff --git a/template/packages/walletkit/README.md b/docs/templates/packages/walletkit/README.md
similarity index 93%
rename from template/packages/walletkit/README.md
rename to docs/templates/packages/walletkit/README.md
index 863548d95..34467d760 100644
--- a/template/packages/walletkit/README.md
+++ b/docs/templates/packages/walletkit/README.md
@@ -48,7 +48,7 @@ npm install @ton/walletkit
 
 ## Initialize the kit
 
-%%demo/examples/src#INIT_KIT%%
+%%docs/examples/src#INIT_KIT%%
 
 ## Understanding previews (for your UI)
 
@@ -64,18 +64,18 @@ You can display these previews directly in your confirmation modals.
 
 Register callbacks that show UI and then approve or reject via kit methods. Note: `getSelectedWalletAddress()` is a placeholder for your own wallet selection logic.
 
-%%demo/examples/src#LISTEN_FOR_REQUESTS%%
+%%docs/examples/src#LISTEN_FOR_REQUESTS%%
 
 
 ### Handle TON Connect links
 
 When users scan a QR code or click a deep link from a dApp, pass the TON Connect URL to the kit. This will trigger your `onConnectRequest` callback.
 
-%%demo/examples/src#ON_TON_CONNECT_LINK%%
+%%docs/examples/src#ON_TON_CONNECT_LINK%%
 
 ### Basic wallet operations
 
-%%demo/examples/src#BASIC_WALLET_OPERATIONS%%
+%%docs/examples/src#BASIC_WALLET_OPERATIONS%%
 
 ### Rendering previews (reference)
 
@@ -83,23 +83,23 @@ The snippets below mirror how the demo wallet renders previews in its modals. Ad
 
 Render Connect preview:
 
-%%demo/examples/src#RENDER_CONNECT_PREVIEW%%
+%%docs/examples/src#RENDER_CONNECT_PREVIEW%%
 
 Render Transaction preview (money flow overview):
 
-%%demo/examples/src#SUMMARIZE_TRANSACTION%%
+%%docs/examples/src#SUMMARIZE_TRANSACTION%%
 
 Example UI rendering:
 
-%%demo/examples/src#RENDER_MONEY_FLOW%%
+%%docs/examples/src#RENDER_MONEY_FLOW%%
 
 Render Sign-Data preview:
 
-%%demo/examples/src#RENDER_SIGN_DATA_PREVIEW%%
+%%docs/examples/src#RENDER_SIGN_DATA_PREVIEW%%
 
 **Tip:** For jetton names/symbols and images in transaction previews, you can enrich the UI using:
 
-%%demo/examples/src#GET_JETTON_INFO%%
+%%docs/examples/src#GET_JETTON_INFO%%
 
 ## Sending assets programmatically
 
@@ -107,11 +107,11 @@ You can create transactions from your wallet app (not from dApps) and feed them
 
 ### Send TON
 
-%%demo/examples/src#SEND_TON%%
+%%docs/examples/src#SEND_TON%%
 
 ### Send Jettons (fungible tokens)
 
-%%demo/examples/src#SEND_JETTONS%%
+%%docs/examples/src#SEND_JETTONS%%
 
 **Notes:**
 - `amount` is the raw integer amount (apply jetton decimals yourself)
@@ -119,17 +119,17 @@ You can create transactions from your wallet app (not from dApps) and feed them
 
 ### Send NFTs
 
-%%demo/examples/src#SEND_NFTS%%
+%%docs/examples/src#SEND_NFTS%%
 
 **Fetching NFTs:**
 
-%%demo/examples/src#FETCHING_NFTS%%
+%%docs/examples/src#FETCHING_NFTS%%
 
 Note: The `getNfts` method returns `NFTsResponse` with a `nfts` field (not `items`).
 
 ## Example: minimal UI state wiring
 
-%%demo/examples/src#MINIMAL_UI_STATE_WIRING%%
+%%docs/examples/src#MINIMAL_UI_STATE_WIRING%%
 
 ## Demo wallet reference
 
diff --git a/template/packages/walletkit/src/defi/crypto-onramp/README.md b/docs/templates/packages/walletkit/src/defi/crypto-onramp/README.md
similarity index 100%
rename from template/packages/walletkit/src/defi/crypto-onramp/README.md
rename to docs/templates/packages/walletkit/src/defi/crypto-onramp/README.md
diff --git a/template/packages/walletkit/src/defi/crypto-onramp/layerswap/README.md b/docs/templates/packages/walletkit/src/defi/crypto-onramp/layerswap/README.md
similarity index 100%
rename from template/packages/walletkit/src/defi/crypto-onramp/layerswap/README.md
rename to docs/templates/packages/walletkit/src/defi/crypto-onramp/layerswap/README.md
diff --git a/template/packages/walletkit/src/defi/crypto-onramp/swaps-xyz/README.md b/docs/templates/packages/walletkit/src/defi/crypto-onramp/swaps-xyz/README.md
similarity index 100%
rename from template/packages/walletkit/src/defi/crypto-onramp/swaps-xyz/README.md
rename to docs/templates/packages/walletkit/src/defi/crypto-onramp/swaps-xyz/README.md
diff --git a/template/packages/walletkit/src/defi/staking/README.md b/docs/templates/packages/walletkit/src/defi/staking/README.md
similarity index 100%
rename from template/packages/walletkit/src/defi/staking/README.md
rename to docs/templates/packages/walletkit/src/defi/staking/README.md
diff --git a/template/packages/walletkit/src/defi/staking/tonstakers/README.md b/docs/templates/packages/walletkit/src/defi/staking/tonstakers/README.md
similarity index 100%
rename from template/packages/walletkit/src/defi/staking/tonstakers/README.md
rename to docs/templates/packages/walletkit/src/defi/staking/tonstakers/README.md
diff --git a/template/packages/walletkit/src/defi/swap/README.md b/docs/templates/packages/walletkit/src/defi/swap/README.md
similarity index 100%
rename from template/packages/walletkit/src/defi/swap/README.md
rename to docs/templates/packages/walletkit/src/defi/swap/README.md
diff --git a/template/packages/walletkit/src/defi/swap/dedust/README.md b/docs/templates/packages/walletkit/src/defi/swap/dedust/README.md
similarity index 87%
rename from template/packages/walletkit/src/defi/swap/dedust/README.md
rename to docs/templates/packages/walletkit/src/defi/swap/dedust/README.md
index a332e8c58..bfc34829b 100644
--- a/template/packages/walletkit/src/defi/swap/dedust/README.md
+++ b/docs/templates/packages/walletkit/src/defi/swap/dedust/README.md
@@ -10,7 +10,7 @@ For detailed information about DeDust Router, see the [official documentation](h
 
 ## Quick Start
 
-%%demo/examples/src/appkit/swap#DEDUST_QUICK_START%%
+%%docs/examples/src/appkit/swap#DEDUST_QUICK_START%%
 
 ## Configuration
 
@@ -32,15 +32,15 @@ interface DeDustSwapProviderConfig {
 
 ## Protocol Routing
 
-%%demo/examples/src/appkit/swap#DEDUST_PROTOCOL_ROUTING%%
+%%docs/examples/src/appkit/swap#DEDUST_PROTOCOL_ROUTING%%
 
 ## Referral Fees
 
-%%demo/examples/src/appkit/swap#DEDUST_REFERRAL_FEES%%
+%%docs/examples/src/appkit/swap#DEDUST_REFERRAL_FEES%%
 
 ### Overriding Referral Settings
 
-%%demo/examples/src/appkit/swap#DEDUST_OVERRIDING_REFERRAL%%
+%%docs/examples/src/appkit/swap#DEDUST_OVERRIDING_REFERRAL%%
 
 ## Resources
 
diff --git a/template/packages/walletkit/src/defi/swap/omniston/README.md b/docs/templates/packages/walletkit/src/defi/swap/omniston/README.md
similarity index 87%
rename from template/packages/walletkit/src/defi/swap/omniston/README.md
rename to docs/templates/packages/walletkit/src/defi/swap/omniston/README.md
index 2e305d059..2bbdccee0 100644
--- a/template/packages/walletkit/src/defi/swap/omniston/README.md
+++ b/docs/templates/packages/walletkit/src/defi/swap/omniston/README.md
@@ -10,7 +10,7 @@ For detailed information about Omniston features and capabilities, see the [offi
 
 ## Quick Start
 
-%%demo/examples/src/appkit/swap#OMNISTON_QUICK_START%%
+%%docs/examples/src/appkit/swap#OMNISTON_QUICK_START%%
 
 ## Configuration
 
@@ -30,15 +30,15 @@ interface OmnistonSwapProviderConfig {
 
 ### Usage Example
 
-%%demo/examples/src/appkit/swap#OMNISTON_USAGE_EXAMPLE%%
+%%docs/examples/src/appkit/swap#OMNISTON_USAGE_EXAMPLE%%
 
 ## Referral Fees
 
-%%demo/examples/src/appkit/swap#OMNISTON_REFERRAL_FEES%%
+%%docs/examples/src/appkit/swap#OMNISTON_REFERRAL_FEES%%
 
 ### Overriding Referral Settings
 
-%%demo/examples/src/appkit/swap#OMNISTON_OVERRIDING_REFERRAL%%
+%%docs/examples/src/appkit/swap#OMNISTON_OVERRIDING_REFERRAL%%
 
 ## Resources
 
diff --git a/eslint.config.js b/eslint.config.js
index b95d7f44e..b735ddb8c 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -57,7 +57,7 @@ module.exports = [
         },
     },
     {
-        files: ['demo/examples/**/*.ts', 'scripts/**/*.ts'],
+        files: ['docs/**/*.ts'],
         rules: {
             'no-console': 'off',
         },
diff --git a/package.json b/package.json
index 67dcb9790..6128f2b75 100644
--- a/package.json
+++ b/package.json
@@ -8,7 +8,9 @@
     "appkit-react": "pnpm --filter @ton/appkit-react",
     "walletkit": "pnpm --filter @ton/walletkit",
     "examples": "pnpm --filter @ton/walletkit-examples",
-    "docs:update": "tsx scripts/update-docs.ts",
+    "docs:update": "pnpm docs:reference && pnpm docs:template",
+    "docs:template": "pnpm --filter @ton/template-resolver resolve",
+    "docs:reference": "pnpm --filter @ton/reference-generator generate",
     "demo-wallet": "pnpm --filter demo-wallet",
     "demo-wallet-native": "pnpm --filter demo-wallet-native",
     "appkit-minter": "pnpm --filter appkit-minter",
diff --git a/packages/appkit-react/README.md b/packages/appkit-react/README.md
index 46ad5d6ee..0ff4271e6 100644
--- a/packages/appkit-react/README.md
+++ b/packages/appkit-react/README.md
@@ -1,7 +1,7 @@
 <!--
 This file is auto-generated. Do not edit manually.
 Changes will be overwritten when running the docs update script.
-Source template: template/packages/appkit-react/README.md
+Source template: docs/templates/packages/appkit-react/README.md
 -->
 
 # @ton/appkit-react
@@ -148,7 +148,7 @@ export const Balance = () => {
         return <div>Loading...</div>;
     }
 
-    return <div>Balance: {balance?.toString()} TON</div>;
+    return <div>Balance: {balance || 0} TON</div>;
 };
 ```
 
diff --git a/packages/appkit-react/docs/components.md b/packages/appkit-react/docs/components.md
index d63760fbf..d7b47e4ff 100644
--- a/packages/appkit-react/docs/components.md
+++ b/packages/appkit-react/docs/components.md
@@ -1,7 +1,7 @@
 <!--
 This file is auto-generated. Do not edit manually.
 Changes will be overwritten when running the docs update script.
-Source template: template/packages/appkit-react/docs/components.md
+Source template: docs/templates/packages/appkit-react/docs/components.md
 -->
 
 # Components
diff --git a/packages/appkit-react/docs/hooks.md b/packages/appkit-react/docs/hooks.md
index dbce1b294..bdec20e9a 100644
--- a/packages/appkit-react/docs/hooks.md
+++ b/packages/appkit-react/docs/hooks.md
@@ -1,7 +1,7 @@
 <!--
 This file is auto-generated. Do not edit manually.
 Changes will be overwritten when running the docs update script.
-Source template: template/packages/appkit-react/docs/hooks.md
+Source template: docs/templates/packages/appkit-react/docs/hooks.md
 -->
 
 # Hooks
@@ -51,7 +51,7 @@ if (error) {
     return <div>Error: {error.message}</div>;
 }
 
-return <div>Balance: {balance?.toString()}</div>;
+return <div>Balance: {balance}</div>;
 ```
 
 ### `useBalanceByAddress`
@@ -75,7 +75,7 @@ if (error) {
     return <div>Error: {error.message}</div>;
 }
 
-return <div>Balance: {balance?.toString()}</div>;
+return <div>Balance: {balance}</div>;
 ```
 
 ### `useWatchBalance`
@@ -248,7 +248,7 @@ if (error) {
     return <div>Error: {error.message}</div>;
 }
 
-return <div>Jetton Wallet Address: {walletAddress?.toString()}</div>;
+return <div>Jetton Wallet Address: {walletAddress}</div>;
 ```
 
 ### `useTransferJetton`
@@ -413,7 +413,7 @@ return (
         <h3>NFT Details</h3>
         <p>Name: {nft?.info?.name}</p>
         <p>Collection: {nft?.collection?.name}</p>
-        <p>Owner: {nft?.ownerAddress?.toString()}</p>
+        <p>Owner: {nft?.ownerAddress}</p>
     </div>
 );
 ```
@@ -444,7 +444,7 @@ return (
         <h3>My NFTs</h3>
         <ul>
             {nfts?.nfts.map((nft) => (
-                <li key={nft.address.toString()}>
+                <li key={nft.address}>
                     {nft.info?.name} ({nft.collection?.name})
                 </li>
             ))}
@@ -480,7 +480,7 @@ return (
         <h3>NFTs</h3>
         <ul>
             {nfts?.nfts.map((nft) => (
-                <li key={nft.address.toString()}>
+                <li key={nft.address}>
                     {nft.info?.name} ({nft.collection?.name})
                 </li>
             ))}
@@ -1063,7 +1063,7 @@ return (
         <ul>
             {connectedWallets.map((wallet) => (
                 <li key={wallet.getAddress()}>
-                    {wallet.getAddress()} ({wallet.getNetwork().toString()})
+                    {wallet.getAddress()} ({wallet.getNetwork().chainId})
                 </li>
             ))}
         </ul>
diff --git a/packages/appkit-react/docs/reference.md b/packages/appkit-react/docs/reference.md
new file mode 100644
index 000000000..9b26c7b86
--- /dev/null
+++ b/packages/appkit-react/docs/reference.md
@@ -0,0 +1,3591 @@
+<!--
+This file is auto-generated. Do not edit manually.
+Changes will be overwritten when running the docs update script.
+Source template: docs/templates/packages/appkit-react/docs/reference.md
+-->
+
+## Hook
+
+### Balances
+
+#### useBalance
+
+React hook reading the Toncoin balance of the currently selected wallet through TanStack Query — auto-resolves the wallet address (use [`useBalanceByAddress`](#usebalancebyaddress) for an arbitrary address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseBalanceParameters`](#usebalanceparameters) | TanStack Query overrides (`select`, `enabled`, `staleTime`, …) and an optional network override. |
+
+Returns: <code><a href="#usebalancereturntype">UseBalanceReturnType</a>&lt;selectData = GetBalanceByAddressData&gt;</code> — TanStack Query result for the balance read.
+
+**Example**
+
+```tsx
+const { data: balance, isLoading, error } = useBalance();
+
+if (isLoading) {
+    return <div>Loading...</div>;
+}
+
+if (error) {
+    return <div>Error: {error.message}</div>;
+}
+
+return <div>Balance: {balance}</div>;
+```
+
+#### useBalanceByAddress
+
+React hook reading the Toncoin balance of an arbitrary address through TanStack Query — useful for addresses that aren't tied to the selected wallet (use [`useBalance`](#usebalance) for the selected wallet).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseBalanceByAddressParameters`](#usebalancebyaddressparameters) | Target address, optional network override, and TanStack Query overrides. |
+
+Returns: <code><a href="#usebalancebyaddressreturntype">UseBalanceByAddressReturnType</a>&lt;selectData = GetBalanceByAddressData&gt;</code> — TanStack Query result for the balance read.
+
+**Example**
+
+```tsx
+const {
+    data: balance,
+    isLoading,
+    error,
+} = useBalanceByAddress({
+    address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
+});
+
+if (isLoading) {
+    return <div>Loading...</div>;
+}
+
+if (error) {
+    return <div>Error: {error.message}</div>;
+}
+
+return <div>Balance: {balance}</div>;
+```
+
+#### useWatchBalance
+
+Subscribe to Toncoin balance updates for the currently selected wallet; updates flow into the TanStack Query cache so [`useBalance`](#usebalance) re-renders automatically (use [`useWatchBalanceByAddress`](#usewatchbalancebyaddress) for a fixed address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseWatchBalanceParameters`](#usewatchbalanceparameters) | Update callback and optional network override. |
+
+Returns: `void`.
+
+**Example**
+
+```tsx
+const { data: balance } = useBalance();
+
+useWatchBalance();
+
+return <div>Current balance: {balance}</div>;
+```
+
+#### useWatchBalanceByAddress
+
+Subscribe to Toncoin balance updates for an arbitrary address — updates flow into the TanStack Query cache so [`useBalanceByAddress`](#usebalancebyaddress) re-renders automatically. No-ops with a console warning when no streaming provider is configured for the resolved network.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters`\* | [`UseWatchBalanceByAddressParameters`](#usewatchbalancebyaddressparameters) | Address, update callback and optional network override. |
+
+Returns: `void`.
+
+**Example**
+
+```tsx
+const address = 'UQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJKZ';
+const network = Network.mainnet();
+const { data: balance } = useBalanceByAddress({ address, network });
+
+useWatchBalanceByAddress({ address, network });
+
+return <div>Current balance: {balance}</div>;
+```
+
+### Connectors
+
+#### useConnectorById
+
+Read a connector by id (wraps [`getConnectorById`](/ecosystem/appkit/reference/appkit#getconnectorbyid) + [`watchConnectorById`](/ecosystem/appkit/reference/appkit#watchconnectorbyid)); re-renders when the connector with that id is registered or unregistered (use [`useConnectedWallets`](#useconnectedwallets) to react to wallet connect/disconnect events).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `id`\* | `string` | ID of the connector to look up. |
+
+Returns: <code><a href="/ecosystem/appkit/reference/appkit#connector">Connector</a> \| undefined</code> — The matching [`Connector`](/ecosystem/appkit/reference/appkit#connector), or `undefined` if none with that id is registered.
+
+#### useConnectors
+
+Read the list of connectors registered on this AppKit instance; re-renders when a connector is registered or unregistered (use [`useConnectedWallets`](#useconnectedwallets) to react to wallet connect/disconnect events).
+
+Returns: <code><a href="#useconnectorsreturntype">UseConnectorsReturnType</a></code> — Read-only array of registered [`Connector`](/ecosystem/appkit/reference/appkit#connector)s.
+
+### Crypto Onramp
+
+#### useCreateCryptoOnrampDeposit
+
+React mutation hook that creates a crypto-onramp deposit from a quote previously obtained via [`useCryptoOnrampQuote`](#usecryptoonrampquote) (wraps [`createCryptoOnrampDeposit`](/ecosystem/appkit/reference/appkit#createcryptoonrampdeposit)) — the resolved [`CryptoOnrampDeposit`](/ecosystem/appkit/reference/appkit#cryptoonrampdeposit) carries the address and amount the user must send on the source chain.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseCreateCryptoOnrampDepositParameters`](#usecreatecryptoonrampdepositparameters) | TanStack Query mutation overrides (`parameters.mutation`). |
+
+Returns: <code><a href="#usecreatecryptoonrampdepositreturntype">UseCreateCryptoOnrampDepositReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the deposit call.
+
+#### useCryptoOnrampContext
+
+Reads the `CryptoOnrampContext` populated by [`CryptoOnrampWidgetProvider`](#cryptoonrampwidgetprovider) — returns the widget's selection state, quote/deposit data and actions ([`CryptoOnrampContextType`](#cryptoonrampcontexttype)).
+
+Returns: <code><a href="#cryptoonrampcontexttype">CryptoOnrampContextType</a></code>.
+
+#### useCryptoOnrampProvider
+
+Read a registered crypto-onramp provider by id, or the default provider when no id is given — subscribes to [`watchCryptoOnrampProviders`](/ecosystem/appkit/reference/appkit#watchcryptoonrampproviders) and re-reads via [`getCryptoOnrampProvider`](/ecosystem/appkit/reference/appkit#getcryptoonrampprovider) so the result stays in sync. The read swallows the throw from [`getCryptoOnrampProvider`](/ecosystem/appkit/reference/appkit#getcryptoonrampprovider) (which throws when no provider matches — or when no id is passed and no default has been registered) and yields `undefined` instead.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | [`GetCryptoOnrampProviderOptions`](/ecosystem/appkit/reference/appkit#getcryptoonrampprovideroptions) | Optional provider id. |
+
+Returns: <code><a href="#usecryptoonrampproviderreturntype">UseCryptoOnrampProviderReturnType</a></code> — The matching provider, or `undefined` when none is registered.
+
+#### useCryptoOnrampProviders
+
+List every crypto-onramp provider registered on the AppKit instance (both those passed via [`AppKitConfig`](/ecosystem/appkit/reference/appkit#appkitconfig)'s `providers` and those added later through [`registerProvider`](/ecosystem/appkit/reference/appkit#registerprovider)); subscribes to [`watchCryptoOnrampProviders`](/ecosystem/appkit/reference/appkit#watchcryptoonrampproviders) and re-reads via [`getCryptoOnrampProviders`](/ecosystem/appkit/reference/appkit#getcryptoonrampproviders) so the array stays in sync.
+
+Returns: <code><a href="#usecryptoonrampprovidersreturntype">UseCryptoOnrampProvidersReturnType</a></code> — Array of registered crypto-onramp providers.
+
+#### useCryptoOnrampQuote
+
+React hook quoting a crypto-to-TON onramp through TanStack Query (wraps [`getCryptoOnrampQuote`](/ecosystem/appkit/reference/appkit#getcryptoonrampquote)) — returns the rate, expected amount and provider metadata needed to call [`useCreateCryptoOnrampDeposit`](#usecreatecryptoonrampdeposit).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseCryptoOnrampQuoteParameters`](#usecryptoonrampquoteparameters) | Quote inputs and TanStack Query overrides. |
+
+Returns: <code><a href="#usecryptoonrampquotereturntype">UseCryptoOnrampQuoteReturnType</a>&lt;selectData = GetCryptoOnrampQuoteData&gt;</code> — TanStack Query result for the quote read.
+
+#### useCryptoOnrampStatus
+
+React hook reading the current status of a crypto-onramp deposit previously created via [`useCreateCryptoOnrampDeposit`](#usecreatecryptoonrampdeposit) through TanStack Query (wraps [`getCryptoOnrampStatus`](/ecosystem/appkit/reference/appkit#getcryptoonrampstatus)) — typically polled via `refetchInterval` until the status is `'success'` or `'failed'`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseCryptoOnrampStatusParameters`](#usecryptoonrampstatusparameters) | Deposit id, originating provider id and TanStack Query overrides. |
+
+Returns: <code><a href="#usecryptoonrampstatusreturntype">UseCryptoOnrampStatusReturnType</a>&lt;selectData = GetCryptoOnrampStatusData&gt;</code> — TanStack Query result for the status read.
+
+### Jettons
+
+#### 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. |
+
+Returns: <code><a href="#usejettonbalancebyaddressreturntype">UseJettonBalanceByAddressReturnType</a>&lt;selectData = GetJettonBalanceByAddressData&gt;</code> — TanStack Query result for the jetton balance read.
+
+**Example**
+
+```tsx
+const {
+    data: balance,
+    isLoading,
+    error,
+} = useJettonBalanceByAddress({
+    ownerAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
+    jettonAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiXme1Xc56Iwobkzgnjj',
+});
+
+if (isLoading) {
+    return <div>Loading...</div>;
+}
+
+if (error) {
+    return <div>Error: {error.message}</div>;
+}
+
+return <div>Jetton Balance: {balance}</div>;
+```
+
+#### useJettonInfo
+
+React hook reading jetton-master metadata (name, symbol, decimals, image, description) through TanStack Query.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseJettonInfoParameters`](#usejettoninfoparameters) | Jetton master address, optional network override and TanStack Query overrides. |
+
+Returns: <code><a href="#usejettoninforeturntype">UseJettonInfoReturnType</a>&lt;selectData = GetJettonInfoData&gt;</code> — TanStack Query result for the jetton info read.
+
+**Example**
+
+```tsx
+const {
+    data: info,
+    isLoading,
+    error,
+} = useJettonInfo({
+    address: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiXme1Xc56Iwobkzgnjj',
+});
+
+if (isLoading) {
+    return <div>Loading...</div>;
+}
+
+if (error) {
+    return <div>Error: {error.message}</div>;
+}
+
+return (
+    <div>
+        <h3>Jetton Info</h3>
+        <p>Name: {info?.name}</p>
+        <p>Symbol: {info?.symbol}</p>
+        <p>Decimals: {info?.decimals}</p>
+    </div>
+);
+```
+
+#### useJettonWalletAddress
+
+React hook deriving the owner's jetton-wallet address — the per-owner contract that actually holds the jetton balance for a given master — through TanStack Query.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseJettonWalletAddressParameters`](#usejettonwalletaddressparameters) | Jetton master, owner address, optional network override and TanStack Query overrides. |
+
+Returns: `UseQueryReturnType<selectData, Error>` — TanStack Query result for the jetton-wallet address read.
+
+**Example**
+
+```tsx
+const {
+    data: walletAddress,
+    isLoading,
+    error,
+} = useJettonWalletAddress({
+    ownerAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
+    jettonAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiXme1Xc56Iwobkzgnjj',
+});
+
+if (isLoading) {
+    return <div>Loading...</div>;
+}
+
+if (error) {
+    return <div>Error: {error.message}</div>;
+}
+
+return <div>Jetton Wallet Address: {walletAddress}</div>;
+```
+
+#### useJettons
+
+React hook listing jettons held by the currently selected wallet through TanStack Query — auto-resolves the wallet address (use [`useJettonsByAddress`](#usejettonsbyaddress) for an arbitrary address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseJettonsParameters`](#usejettonsparameters) | TanStack Query overrides (`select`, `enabled`, `staleTime`, …), pagination and an optional network override. |
+
+Returns: <code><a href="#usejettonsreturntype">UseJettonsReturnType</a>&lt;selectData = GetJettonsByAddressData&gt;</code> — TanStack Query result for the jettons list.
+
+**Example**
+
+```tsx
+const { data: jettons, isLoading, error } = useJettons();
+
+if (isLoading) {
+    return <div>Loading...</div>;
+}
+
+if (error) {
+    return <div>Error: {error.message}</div>;
+}
+
+return (
+    <div>
+        <h3>Jettons</h3>
+        <ul>
+            {jettons?.jettons.map((jetton) => (
+                <li key={jetton.walletAddress}>
+                    {jetton.info.name}: {jetton.balance}
+                </li>
+            ))}
+        </ul>
+    </div>
+);
+```
+
+#### useJettonsByAddress
+
+React hook listing jettons held by an arbitrary address through TanStack Query — useful for wallets that aren't selected in AppKit (use [`useJettons`](#usejettons) for the selected wallet).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseJettonsByAddressParameters`](#usejettonsbyaddressparameters) | Owner address, optional network override, pagination and TanStack Query overrides. |
+
+Returns: <code><a href="#usejettonsbyaddressreturntype">UseJettonsByAddressReturnType</a>&lt;selectData = GetJettonsByAddressData&gt;</code> — TanStack Query result for the jettons list.
+
+**Example**
+
+```tsx
+const {
+    data: jettons,
+    isLoading,
+    error,
+} = useJettonsByAddress({
+    address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
+});
+
+if (isLoading) {
+    return <div>Loading...</div>;
+}
+
+if (error) {
+    return <div>Error: {error.message}</div>;
+}
+
+return (
+    <div>
+        <h3>Jettons</h3>
+        <ul>
+            {jettons?.jettons.map((jetton) => (
+                <li key={jetton.walletAddress}>
+                    {jetton.info.name}: {jetton.balance}
+                </li>
+            ))}
+        </ul>
+    </div>
+);
+```
+
+#### useTransferJetton
+
+React mutation hook that builds and sends a jetton transfer from the selected wallet in one step (wraps [`transferJetton`](/ecosystem/appkit/reference/appkit#transferjetton)); returns `mutate(\{ jettonAddress, recipientAddress, amount, jettonDecimals, comment? \})`. Throws `Error('Wallet not connected')` if no wallet is currently selected.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseTransferJettonParameters`](#usetransferjettonparameters) | TanStack Query mutation overrides. |
+
+Returns: <code><a href="#usetransferjettonreturntype">UseTransferJettonReturnType</a>&lt;context = unknown&gt;</code> — 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 (
+    <div>
+        <button onClick={handleTransfer} disabled={isPending}>
+            {isPending ? 'Transferring...' : 'Transfer Jetton'}
+        </button>
+        {error && <div>Error: {error.message}</div>}
+    </div>
+);
+```
+
+#### useWatchJettons
+
+Subscribe to jetton-balance updates for the currently selected wallet; updates flow into the TanStack Query cache so [`useJettons`](#usejettons) re-renders automatically (use [`useWatchJettonsByAddress`](#usewatchjettonsbyaddress) for a fixed address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseWatchJettonsParameters`](#usewatchjettonsparameters) | Update callback and optional network override. |
+
+Returns: `void`.
+
+**Example**
+
+```tsx
+const { data: jettons } = useJettons();
+
+useWatchJettons();
+
+return (
+    <div>
+        <h3>Your Jettons:</h3>
+        <ul>
+            {jettons?.jettons.map((j) => (
+                <li key={j.walletAddress}>
+                    {j.info.name}: {j.balance}
+                </li>
+            ))}
+        </ul>
+    </div>
+);
+```
+
+#### useWatchJettonsByAddress
+
+Subscribe to jetton-balance updates for an arbitrary owner address; updates flow into the TanStack Query cache so [`useJettonsByAddress`](#usejettonsbyaddress) and [`useJettonBalanceByAddress`](#usejettonbalancebyaddress) re-render automatically. Logs a warning and exits when no streaming provider is configured for the resolved network.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters`\* | [`UseWatchJettonsByAddressParameters`](#usewatchjettonsbyaddressparameters) | Owner address, update callback and optional network override. |
+
+Returns: `void`.
+
+**Example**
+
+```tsx
+const address = 'UQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJKZ';
+const { data: jettons } = useJettonsByAddress({ address });
+
+useWatchJettonsByAddress({ address });
+
+return (
+    <div>
+        <h3>Jettons for {address}:</h3>
+        <ul>
+            {jettons?.jettons.map((j) => (
+                <li key={j.walletAddress}>
+                    {j.info.name}: {j.balance}
+                </li>
+            ))}
+        </ul>
+    </div>
+);
+```
+
+### NFTs
+
+#### useNft
+
+React hook reading metadata and ownership for a single NFT through TanStack Query, keyed by its contract address; `data` is `null` when the indexer has no record.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseNftParameters`](#usenftparameters) | NFT address, optional network override, and TanStack Query overrides. |
+
+Returns: <code><a href="#usenftreturntype">UseNftReturnType</a>&lt;selectData = GetNftData&gt;</code> — TanStack Query result for the NFT read.
+
+**Example**
+
+```tsx
+const {
+    data: nft,
+    isLoading,
+    error,
+} = useNft({
+    address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
+});
+
+if (isLoading) {
+    return <div>Loading...</div>;
+}
+
+if (error) {
+    return <div>Error: {error.message}</div>;
+}
+
+return (
+    <div>
+        <h3>NFT Details</h3>
+        <p>Name: {nft?.info?.name}</p>
+        <p>Collection: {nft?.collection?.name}</p>
+        <p>Owner: {nft?.ownerAddress}</p>
+    </div>
+);
+```
+
+#### useNfts
+
+React hook that reads NFTs held by the currently selected wallet through TanStack Query — auto-resolves the wallet address (use [`useNftsByAddress`](#usenftsbyaddress) for an arbitrary address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseNFTsParameters`](#usenftsparameters) | Optional pagination, network override, and TanStack Query overrides. |
+
+Returns: <code><a href="#usenftsreturntype">UseNFTsReturnType</a>&lt;selectData = GetNFTsData&gt;</code> — TanStack Query result for the NFTs read.
+
+**Example**
+
+```tsx
+const {
+    data: nfts,
+    isLoading,
+    error,
+} = useNfts({
+    limit: 10,
+});
+
+if (isLoading) {
+    return <div>Loading...</div>;
+}
+
+if (error) {
+    return <div>Error: {error.message}</div>;
+}
+
+return (
+    <div>
+        <h3>My NFTs</h3>
+        <ul>
+            {nfts?.nfts.map((nft) => (
+                <li key={nft.address}>
+                    {nft.info?.name} ({nft.collection?.name})
+                </li>
+            ))}
+        </ul>
+    </div>
+);
+```
+
+#### useNftsByAddress
+
+React hook that reads NFTs held by an arbitrary address through TanStack Query — useful for wallets that aren't selected in AppKit (use [`useNfts`](#usenfts) for the selected wallet).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseNFTsByAddressParameters`](#usenftsbyaddressparameters) | Owner address, optional pagination and network override, plus TanStack Query overrides. |
+
+Returns: <code><a href="#usenftsbyaddressreturntype">UseNFTsByAddressReturnType</a>&lt;selectData = GetNFTsData&gt;</code> — TanStack Query result for the NFTs read.
+
+**Example**
+
+```tsx
+const {
+    data: nfts,
+    isLoading,
+    error,
+} = useNftsByAddress({
+    address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
+    limit: 10,
+});
+
+if (isLoading) {
+    return <div>Loading...</div>;
+}
+
+if (error) {
+    return <div>Error: {error.message}</div>;
+}
+
+return (
+    <div>
+        <h3>NFTs</h3>
+        <ul>
+            {nfts?.nfts.map((nft) => (
+                <li key={nft.address}>
+                    {nft.info?.name} ({nft.collection?.name})
+                </li>
+            ))}
+        </ul>
+    </div>
+);
+```
+
+#### useTransferNft
+
+React mutation hook that builds and sends an NFT transfer from the selected wallet in one step (wraps [`transferNft`](/ecosystem/appkit/reference/appkit#transfernft)); returns `mutate(\{ nftAddress, recipientAddress, amount?, comment? \})` and throws `Error('Wallet not connected')` if no wallet is currently selected.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseTransferNftParameters`](#usetransfernftparameters) | TanStack Query mutation overrides. |
+
+Returns: <code><a href="#usetransfernftreturntype">UseTransferNftReturnType</a>&lt;context = unknown&gt;</code> — 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 (
+    <div>
+        <button onClick={handleTransfer} disabled={isPending}>
+            {isPending ? 'Transferring...' : 'Transfer NFT'}
+        </button>
+        {error && <div>Error: {error.message}</div>}
+    </div>
+);
+```
+
+### Networks
+
+#### useBlockNumber
+
+React hook reading the latest masterchain seqno through TanStack Query — useful for freshness checks and pagination cursors.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseBlockNumberParameters`](#useblocknumberparameters) | TanStack Query overrides and optional network. |
+
+Returns: <code><a href="#useblocknumberreturntype">UseBlockNumberReturnType</a>&lt;selectData = GetBlockNumberData&gt;</code> — TanStack Query result for the seqno read.
+
+#### useDefaultNetwork
+
+Read and write AppKit's default network — the network connectors use for new wallet connections. Returns a `useState`-style tuple; the read side re-renders when the default changes through any source (this hook, [`setDefaultNetwork`](/ecosystem/appkit/reference/appkit#setdefaultnetwork), manager events).
+
+Returns: <code><a href="#usedefaultnetworkreturntype">UseDefaultNetworkReturnType</a></code> — Tuple `[network, setNetwork]`.
+
+#### useNetwork
+
+Read the [`Network`](/ecosystem/appkit/reference/appkit#network) the selected wallet is connected to; re-renders when the wallet's network changes (e.g. user switches mainnet/testnet inside the wallet).
+
+Returns: <code><a href="#usenetworkreturntype">UseNetworkReturnType</a></code> — Selected wallet's network, or `undefined` when no wallet is selected.
+
+#### useNetworks
+
+Read the list of networks configured on AppKit; re-renders when [`AppKitNetworkManager`](/ecosystem/appkit/reference/appkit#appkitnetworkmanager) adds, replaces or drops a network.
+
+Returns: <code><a href="#usenetworksreturntype">UseNetworksReturnType</a></code> — Array of configured [`Network`](/ecosystem/appkit/reference/appkit#network)s.
+
+### Settings
+
+#### useAppKit
+
+Read the [`AppKit`](/ecosystem/appkit/reference/appkit#appkit) instance hosted by [`AppKitProvider`](#appkitprovider); throws when the hook is rendered outside the provider tree.
+
+Returns: <code><a href="/ecosystem/appkit/reference/appkit#appkit">AppKit</a></code> — The AppKit instance shared with descendant hooks/components.
+
+#### useAppKitTheme
+
+State hook that mirrors the active appkit-react theme to `document.body[data-ta-theme]` — returns a `[theme, setTheme]` tuple just like `useState`.
+
+Returns: `readonly [string, Dispatch<SetStateAction<string>>]` — Tuple `[theme, setTheme]` for reading and switching the active theme.
+
+#### useI18n
+
+Read the i18n context published by [`I18nProvider`](#i18nprovider) (or the wrapping [`AppKitProvider`](#appkitprovider)); returns the active locale, translation function and helpers to switch locales or merge dictionaries. Throws when rendered outside the provider tree.
+
+Returns: `I18nContextType` — The i18n context ([`I18nContextType`](#i18ncontexttype)) with `activeLocale`, `t`, `locale` and `addDict`.
+
+### Signing
+
+#### useSignBinary
+
+React mutation hook that asks the selected wallet to sign a binary blob (wraps [`signBinary`](/ecosystem/appkit/reference/appkit#signbinary)); returns `mutate(\{ bytes \})` you call from event handlers. The underlying action 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. |
+
+Returns: <code><a href="#usesignbinaryreturntype">UseSignBinaryReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the signing call.
+
+#### useSignCell
+
+React mutation hook that asks the selected wallet to sign a TON cell (wraps [`signCell`](/ecosystem/appkit/reference/appkit#signcell)); typically used so the signature can later be verified on-chain. Returns `mutate(\{ cell, schema \})` you call from event handlers. The underlying action 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. |
+
+Returns: <code><a href="#usesigncellreturntype">UseSignCellReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the signing call.
+
+#### useSignText
+
+React mutation hook that asks the selected wallet to sign a plain-text message (wraps [`signText`](/ecosystem/appkit/reference/appkit#signtext)); returns `mutate(\{ text \})` you call from event handlers. The underlying action 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. |
+
+Returns: <code><a href="#usesigntextreturntype">UseSignTextReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the signing call.
+
+### Staking
+
+#### useBuildStakeTransaction
+
+React mutation hook that wraps [`buildStakeTransaction`](/ecosystem/appkit/reference/appkit#buildstaketransaction) — turns a [`StakingQuote`](/ecosystem/appkit/reference/appkit#stakingquote) obtained via [`useStakingQuote`](#usestakingquote) into a [`TransactionRequest`](/ecosystem/appkit/reference/appkit#transactionrequest) without sending it, so the UI can inspect or batch before signing. Returns `mutate(params)` where `params` matches [`BuildStakeTransactionOptions`](/ecosystem/appkit/reference/appkit#buildstaketransactionoptions).
+
+Returns: <code><a href="#usebuildstaketransactionreturntype">UseBuildStakeTransactionReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the build call.
+
+#### 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. |
+
+Returns: <code><a href="#usestakedbalancereturntype">UseStakedBalanceReturnType</a>&lt;selectData = GetStakedBalanceData&gt;</code> — TanStack Query result for the staked-balance read.
+
+#### 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: <code><a href="#stakingcontexttype">StakingContextType</a></code>.
+
+#### useStakingProvider
+
+React hook returning a registered staking provider; subscribes to provider-registry changes via [`watchStakingProviders`](/ecosystem/appkit/reference/appkit#watchstakingproviders) 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`](/ecosystem/appkit/reference/appkit#getstakingprovider) action would throw).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | <code><a href="/ecosystem/appkit/reference/appkit#getstakingprovideroptions">GetStakingProviderOptions</a></code> | Optional provider `id`. |
+
+Returns: <code><a href="#usestakingproviderreturntype">UseStakingProviderReturnType</a></code> — Matching staking provider instance, or `undefined` when none resolves.
+
+#### 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. |
+
+Returns: <code><a href="#usestakingproviderinforeturntype">UseStakingProviderInfoReturnType</a>&lt;selectData = GetStakingProviderInfoData&gt;</code> — TanStack Query result for the live provider info.
+
+#### useStakingProviderMetadata
+
+React hook reading static metadata for a staking provider (wraps [`getStakingProviderMetadata`](/ecosystem/appkit/reference/appkit#getstakingprovidermetadata)) — 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. |
+
+Returns: <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> — Static [`StakingProviderMetadata`](/ecosystem/appkit/reference/appkit#stakingprovidermetadata), or `undefined` when the provider can't be resolved.
+
+#### 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`](/ecosystem/appkit/reference/appkit#watchstakingproviders).
+
+Returns: <code><a href="#usestakingprovidersreturntype">UseStakingProvidersReturnType</a></code> — Array of registered staking providers.
+
+#### useStakingQuote
+
+React hook quoting a stake or unstake through TanStack Query (wraps [`getStakingQuote`](/ecosystem/appkit/reference/appkit#getstakingquote)) — returns the rate, expected output and provider metadata needed to feed into [`useBuildStakeTransaction`](#usebuildstaketransaction). 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. |
+
+Returns: <code><a href="#usestakingquotereturntype">UseStakingQuoteReturnType</a>&lt;selectData = GetStakingQuoteData&gt;</code> — TanStack Query result for the quote read.
+
+### Swap
+
+#### useBuildSwapTransaction
+
+React mutation hook that wraps [`buildSwapTransaction`](/ecosystem/appkit/reference/appkit#buildswaptransaction) — turns a [`SwapQuote`](/ecosystem/appkit/reference/appkit#swapquote) obtained via [`useSwapQuote`](#useswapquote) into a [`TransactionRequest`](/ecosystem/appkit/reference/appkit#transactionrequest) without sending it, so the UI can inspect or batch before signing. Returns `mutate(params)` where `params` matches [`BuildSwapTransactionOptions`](/ecosystem/appkit/reference/appkit#buildswaptransactionoptions).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseBuildSwapTransactionParameters`](#usebuildswaptransactionparameters) | TanStack Query mutation overrides. |
+
+Returns: <code><a href="#usebuildswaptransactionreturntype">UseBuildSwapTransactionReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the build call.
+
+#### 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: <code><a href="#swapcontexttype">SwapContextType</a></code>.
+
+#### useSwapProvider
+
+Read and switch the default swap provider — subscribes to [`watchSwapProviders`](/ecosystem/appkit/reference/appkit#watchswapproviders) and re-reads via [`getSwapProvider`](/ecosystem/appkit/reference/appkit#getswapprovider). Returns a `useState`-style tuple; the read swallows the throw from [`getSwapProvider`](/ecosystem/appkit/reference/appkit#getswapprovider) (which throws when no provider matches — or when no id is passed and no default has been registered) and yields `undefined` instead.
+
+Returns: <code><a href="#useswapproviderreturntype">UseSwapProviderReturnType</a></code> — Tuple `[provider, setProviderId]`.
+
+#### useSwapProviders
+
+List every swap provider registered on the AppKit instance (both those passed via [`AppKitConfig`](/ecosystem/appkit/reference/appkit#appkitconfig)'s `providers` and those added later through [`registerProvider`](/ecosystem/appkit/reference/appkit#registerprovider)); subscribes to [`watchSwapProviders`](/ecosystem/appkit/reference/appkit#watchswapproviders) and re-reads via [`getSwapProviders`](/ecosystem/appkit/reference/appkit#getswapproviders) so the array stays in sync.
+
+Returns: <code><a href="#useswapprovidersreturntype">UseSwapProvidersReturnType</a></code> — Array of registered swap providers.
+
+#### useSwapQuote
+
+React hook fetching a swap quote through TanStack Query — wraps [`getSwapQuote`](/ecosystem/appkit/reference/appkit#getswapquote). The resulting `data` is the [`SwapQuote`](/ecosystem/appkit/reference/appkit#swapquote) payload required to call [`buildSwapTransaction`](/ecosystem/appkit/reference/appkit#buildswaptransaction) (see [`useBuildSwapTransaction`](#usebuildswaptransaction)). 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. |
+
+Returns: <code><a href="#useswapquotereturntype">UseSwapQuoteReturnType</a>&lt;selectData = GetSwapQuoteData&gt;</code> — TanStack Query result for the swap quote.
+
+### Transactions
+
+#### useSendTransaction
+
+React mutation hook that hands a pre-built [`TransactionRequest`](/ecosystem/appkit/reference/appkit#transactionrequest) to the selected wallet for signing and broadcast (wraps [`sendTransaction`](/ecosystem/appkit/reference/appkit#sendtransaction)); returns `mutate(request)`. The underlying action 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. |
+
+Returns: <code><a href="#usesendtransactionreturntype">UseSendTransactionReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the send call.
+
+#### useTransactionStatus
+
+React hook that reads the trace status of a sent transaction (wraps [`getTransactionStatus`](/ecosystem/appkit/reference/appkit#gettransactionstatus)); typically paired with `refetchInterval` to poll until the trace completes. The underlying action throws `Error('Either boc or normalizedHash must be provided')` when neither field 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: <code><a href="#usetransactionstatusreturntype">UseTransactionStatusReturnType</a>&lt;selectData = GetTransactionStatusData&gt;</code> — TanStack Query result for the status read.
+
+#### useTransferTon
+
+React mutation hook that builds and sends a TON transfer from the selected wallet in one step (wraps [`transferTon`](/ecosystem/appkit/reference/appkit#transferton)); returns `mutate(\{ recipientAddress, amount, comment?, payload?, stateInit? \})`. The underlying action 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. |
+
+Returns: <code><a href="#usetransfertonreturntype">UseTransferTonReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the transfer call.
+
+#### 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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseWatchTransactionsParameters`](#usewatchtransactionsparameters) | Update callback. |
+
+Returns: `void`.
+
+**Example**
+
+```tsx
+const [lastUpdate, setLastUpdate] = useState<TransactionsUpdate | null>(null);
+
+useWatchTransactions({
+    onChange: (update) => {
+        setLastUpdate(update);
+    },
+});
+
+return (
+    <div>
+        {lastUpdate ? (
+            <div>
+                Last update for: {lastUpdate.address}
+                <br />
+                Transactions count: {lastUpdate.transactions.length}
+            </div>
+        ) : (
+            'Waiting for transactions...'
+        )}
+    </div>
+);
+```
+
+#### useWatchTransactionsByAddress
+
+Subscribe to incoming-transaction events for an arbitrary address (use [`useWatchTransactions`](#usewatchtransactions) for the selected wallet); logs a warning and exits when no streaming provider is configured for the resolved network or no `onChange` callback was provided.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters`\* | [`UseWatchTransactionsByAddressParameters`](#usewatchtransactionsbyaddressparameters) | Address, update callback and optional network override. |
+
+Returns: `void`.
+
+**Example**
+
+```tsx
+const address = 'UQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJKZ';
+const [lastUpdate, setLastUpdate] = useState<TransactionsUpdate | null>(null);
+
+useWatchTransactionsByAddress({
+    address,
+    onChange: (update) => {
+        setLastUpdate(update);
+    },
+});
+
+return (
+    <div>
+        {lastUpdate ? (
+            <div>
+                New transactions for: {lastUpdate.address}
+                <br />
+                Count: {lastUpdate.transactions.length}
+            </div>
+        ) : (
+            'Waiting for transactions...'
+        )}
+    </div>
+);
+```
+
+### Wallets
+
+#### useAddress
+
+Read the user-friendly address of the currently selected wallet; re-renders when the selection changes.
+
+Returns: <code><a href="#useaddressreturntype">UseAddressReturnType</a></code> — Selected wallet's address, or `undefined` when none is selected.
+
+#### useConnect
+
+React mutation hook that triggers the connection flow on a registered connector by id (wraps [`connect`](/ecosystem/appkit/reference/appkit#connect)); returns `mutate(\{ connectorId \})` you call from event handlers. The underlying action throws `Error('Connector with id "<id>" not found')` when no connector with that id is registered — TanStack Query surfaces it via the mutation's `error`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseConnectParameters`](#useconnectparameters) | TanStack Query mutation overrides. |
+
+Returns: <code><a href="#useconnectreturntype">UseConnectReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the connect call.
+
+#### useConnectedWallets
+
+Read the list of currently connected wallets across all registered connectors; re-renders when a wallet connects or disconnects.
+
+Returns: <code><a href="#useconnectedwalletsreturntype">UseConnectedWalletsReturnType</a></code> — Read-only array of [`WalletInterface`](/ecosystem/appkit/reference/appkit#walletinterface)s.
+
+#### useDisconnect
+
+React mutation hook that disconnects the wallet currently connected through a registered connector (wraps [`disconnect`](/ecosystem/appkit/reference/appkit#disconnect)); returns `mutate(\{ connectorId \})` you call from event handlers. The underlying action throws `Error('Connector with id "<id>" not found')` when no connector with that id is registered — TanStack Query surfaces it via the mutation's `error`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameters` | [`UseDisconnectParameters`](#usedisconnectparameters) | TanStack Query mutation overrides. |
+
+Returns: <code><a href="#usedisconnectreturntype">UseDisconnectReturnType</a>&lt;context = unknown&gt;</code> — Mutation result for the disconnect call.
+
+#### 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: <code><a href="#useselectedwalletreturntype">UseSelectedWalletReturnType</a></code> — Tuple `[wallet, setWalletId]`.
+
+## Component
+
+### Balances
+
+#### BalanceBadge
+
+Compound component for rendering a token balance pill (icon + amount + symbol). Sub-components forward extra props to the underlying DOM element so callers can layer custom classes, click handlers, etc.
+
+Compound component. Members:
+
+##### BalanceBadge.Container
+
+Pill wrapper — renders a horizontal [`Block`](#block) that hosts the icon and balance block.
+
+##### BalanceBadge.Icon
+
+Token icon — re-exported [`Logo`](#logo) that draws the asset's image.
+
+##### BalanceBadge.BalanceBlock
+
+Block holding the balance amount and ticker symbol side by side.
+
+##### BalanceBadge.Symbol
+
+Ticker symbol cell rendered next to the amount (e.g., `TON`, `USDT`).
+
+##### BalanceBadge.Balance
+
+Formatted balance number; takes a raw `balance` and `decimals` and renders the human-readable amount.
+
+#### SendJettonButton
+
+Pre-wired button that builds a jetton transfer with [`createTransferJettonTransaction`](/ecosystem/appkit/reference/appkit#createtransferjettontransaction) and dispatches it through the standard `Send` flow on click — disabled until `recipientAddress`, `amount`, `jetton.address` and a non-zero `jetton.decimals` are all set; throws inside the click handler when `jetton.address` is missing or `jetton.decimals` is falsy. (A `0`-decimal jetton must be passed as a truthy value to avoid being treated as 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` | Custom button text |
+| `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 |
+| `onError` | `(error: Error) => void` | Callback when an error occurs |
+| `onSuccess` | <code>(response: <a href="/ecosystem/appkit/reference/appkit#sendtransactionreturntype">SendTransactionReturnType</a>) =&gt; void</code> | Callback when the transaction is successful |
+
+#### SendTonButton
+
+Pre-wired button that builds a TON transfer with [`createTransferTonTransaction`](/ecosystem/appkit/reference/appkit#createtransfertontransaction) and dispatches it through the standard `Send` flow on click — disabled until both `recipientAddress` and `amount` are set.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `recipientAddress`\* | `string` | Recipient address. |
+| `amount`\* | `string` | Amount in TON as a human-readable decimal string (e.g., `"1.5"`); converted to nano-TON internally. |
+| `comment` | `string` | Optional human-readable comment attached to the transfer. |
+| `text` | `ReactNode` | Custom button text |
+| `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 |
+| `onError` | `(error: Error) => void` | Callback when an error occurs |
+| `onSuccess` | <code>(response: <a href="/ecosystem/appkit/reference/appkit#sendtransactionreturntype">SendTransactionReturnType</a>) =&gt; void</code> | Callback when the transaction is successful |
+
+### Crypto Onramp
+
+#### CryptoOnrampWidget
+
+Drop-in widget for buying TON-side tokens with a crypto payment from another chain — wraps [`CryptoOnrampWidgetProvider`](#cryptoonrampwidgetprovider) (which drives token/method selection, quote fetching, deposit creation and status polling) around [`CryptoOnrampWidgetUI`](#cryptoonrampwidgetui). Pass a `children` render function to swap in a fully custom UI while keeping the same provider state.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `children` | <code>(props: <a href="#cryptoonrampwidgetrenderprops">CryptoOnrampWidgetRenderProps</a>) =&gt; ReactNode</code> | Custom render function. When provided, replaces the default [`CryptoOnrampWidgetUI`](#cryptoonrampwidgetui) and is called with the full [`CryptoOnrampWidgetRenderProps`](#cryptoonrampwidgetrenderprops) (context state, actions and forwarded `<div>` props), so callers can build a fully custom UI on top of the same provider. |
+| `tokens` | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a>[]</code> | Target tokens (what the user buys on TON). Defaults to a built-in list. |
+| `tokenSections` | <code><a href="#cryptoonramptokensectionconfig">CryptoOnrampTokenSectionConfig</a>[]</code> | Optional section configs grouping `tokens` in the picker. |
+| `paymentMethods` | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a>[]</code> | Source crypto payment methods (what the user pays with on another chain). Defaults to a built-in list. |
+| `methodSections` | <code><a href="#paymentmethodsectionconfig">PaymentMethodSectionConfig</a>[]</code> | Optional section configs grouping `paymentMethods` in the picker. |
+| `chains` | <code>Record&lt;string, <a href="#chaininfo">ChainInfo</a>&gt;</code> | 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 (e.g. `\{ 'eip155:42161': \{ name: 'Arbitrum', logo: '...' \} \}`). |
+| `defaultTokenId` | `string` | ID of the target token pre-selected on mount. |
+| `defaultMethodId` | `string` | ID of the source payment method pre-selected on mount. |
+
+#### CryptoOnrampWidgetProvider
+
+Context provider that powers the crypto-to-TON onramp widget — wires together token/method selection state, quote fetching ([`useCryptoOnrampQuote`](#usecryptoonrampquote)), deposit creation ([`useCreateCryptoOnrampDeposit`](#usecreatecryptoonrampdeposit)), deposit status polling ([`useCryptoOnrampStatus`](#usecryptoonrampstatus)), the target-token balance and validation. Consumers read the state via [`useCryptoOnrampContext`](#usecryptoonrampcontext).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `tokens` | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a>[]</code> | Target tokens (what the user buys on TON). Defaults to a built-in list. |
+| `tokenSections` | <code><a href="#cryptoonramptokensectionconfig">CryptoOnrampTokenSectionConfig</a>[]</code> | Optional section configs grouping `tokens` in the picker. |
+| `paymentMethods` | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a>[]</code> | Source crypto payment methods (what the user pays with on another chain). Defaults to a built-in list. |
+| `methodSections` | <code><a href="#paymentmethodsectionconfig">PaymentMethodSectionConfig</a>[]</code> | Optional section configs grouping `paymentMethods` in the picker. |
+| `chains` | <code>Record&lt;string, <a href="#chaininfo">ChainInfo</a>&gt;</code> | 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 (e.g. `\{ 'eip155:42161': \{ name: 'Arbitrum', logo: '...' \} \}`). |
+| `defaultTokenId` | `string` | ID of the target token pre-selected on mount. |
+| `defaultMethodId` | `string` | ID of the source payment method pre-selected on mount. |
+
+#### 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`\* | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a>[]</code> | Full list of target tokens the user can buy. |
+| `tokenSections` | <code><a href="#cryptoonramptokensectionconfig">CryptoOnrampTokenSectionConfig</a>[]</code> | Optional section configs grouping `tokens` in the picker. |
+| `selectedToken`\* | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a> \| null</code> | Currently selected target token to buy. `null` until tokens load. |
+| `setSelectedToken`\* | <code>(token: <a href="#cryptoonramptoken">CryptoOnrampToken</a>) =&gt; void</code> | Updates `selectedToken`. |
+| `paymentMethods`\* | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a>[]</code> | Available source crypto payment methods. |
+| `methodSections` | <code><a href="#paymentmethodsectionconfig">PaymentMethodSectionConfig</a>[]</code> | Optional section configs grouping `paymentMethods` in the picker. |
+| `selectedMethod`\* | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a></code> | Currently selected source payment method. |
+| `setSelectedMethod`\* | <code>(method: <a href="#cryptopaymentmethod">CryptoPaymentMethod</a>) =&gt; void</code> | Updates `selectedMethod`. |
+| `chains`\* | <code>Record&lt;string, <a href="#chaininfo">ChainInfo</a>&gt;</code> | 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`\* | <code><a href="#cryptoamountinputmode">CryptoAmountInputMode</a></code> | Which side `amount` is denominated in — see [`CryptoAmountInputMode`](#cryptoamountinputmode). |
+| `setAmountInputMode`\* | <code>(mode: <a href="#cryptoamountinputmode">CryptoAmountInputMode</a>) =&gt; void</code> | Updates `amountInputMode`. |
+| `convertedAmount`\* | `string` | Other side of `amount` after applying the current quote's rate. |
+| `presetAmounts`\* | <code><a href="#onrampamountpreset">OnrampAmountPreset</a>[]</code> | Quick-pick amount buttons rendered in the widget. |
+| `quote`\* | <code><a href="/ecosystem/appkit/reference/appkit#cryptoonrampquote">CryptoOnrampQuote</a> \| null</code> | 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`\* | <code><a href="/ecosystem/appkit/reference/appkit#cryptoonrampdeposit">CryptoOnrampDeposit</a> \| null</code> | 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`\* | <code><a href="/ecosystem/appkit/reference/appkit#cryptoonrampstatus">CryptoOnrampStatus</a> \| null</code> | Latest deposit status polled via [`useCryptoOnrampStatus`](#usecryptoonrampstatus), or `null`. |
+| `isRefundAddressRequired`\* | `boolean` | Whether the current quote provider requires a refund address before deposit. |
+| `isReversedAmountSupported`\* | `boolean` | Whether the current quote provider supports reversed (target-amount) input. |
+| `refundAddress`\* | `string` | Refund address the user typed, if `isRefundAddressRequired`. |
+| `setRefundAddress`\* | `(address: string) => void` | Updates `refundAddress`. |
+| `targetBalance`\* | `string` | Connected wallet's balance of the selected target token (formatted, token units). |
+| `isLoadingTargetBalance`\* | `boolean` | Whether the target token balance is being fetched. |
+| `isWalletConnected`\* | `boolean` | Whether a TON wallet is currently connected. |
+| `canContinue`\* | `boolean` | Whether the user can proceed — valid amount, quote available, and wallet connected. |
+| `onReset`\* | `() => void` | Invalidates the active quote and clears the deposit, returning the widget to its initial state. |
+
+### NFTs
+
+#### 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`\* | <code><a href="/ecosystem/appkit/reference/appkit#nft">NFT</a></code> | NFT to render — name, collection name, image and on-sale state are derived via `getFormattedNftInfo`. |
+
+### Providers
+
+#### AppKitProvider
+
+Top-level React provider that wires AppKit, the TonConnect bridge and i18n into the component tree — wrap your app once near the root so descendant hooks ([`useAppKit`](#useappkit), [`useBalance`](#usebalance), …) and components can resolve their context.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | <code><a href="/ecosystem/appkit/reference/appkit#appkit">AppKit</a></code> | Runtime instance constructed at app startup; shared across every appkit-react hook and component. |
+
+#### I18nProvider
+
+React provider that mounts the i18n context for [`useI18n`](#usei18n) and child components — already wrapped by [`AppKitProvider`](#appkitprovider), so apps usually only render it directly when they need to override the locale or dictionaries.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `locale` | `string` | Initial locale code; defaults to the i18n library's default when omitted. |
+| `lngDicts` | `Record<string, Dict>` | Translation dictionaries keyed by locale; loaded into the underlying i18n instance on mount. |
+
+### Shared
+
+#### AmountPresets
+
+Horizontal row of preset amount buttons — typically used next to an amount input to offer quick fills.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `presets`\* | <code><a href="#amountpreset">AmountPreset</a>[]</code> | 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`. |
+
+#### CopyButton
+
+Icon-only button that copies `value` to the clipboard on click and flips its icon to a checkmark for a short confirmation window.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Text written to the clipboard when the button is clicked. |
+| `aria-label`\* | `string` | Accessible label for screen readers. |
+
+#### CurrencyItem
+
+Compound row used inside currency/token select lists: shows a token logo, name + ticker, optional verified badge, and an optional balance / under-balance on the right. Pass top-level props for the default layout, or pass `children` made of the sub-components for full control.
+
+#### CurrencySelect
+
+Compound currency-select primitives — compose [`CurrencySelect.Modal`](#currencyselect.modal) with a [`CurrencySelect.Search`](#currencyselect.search) and [`CurrencySelect.ListContainer`](#currencyselect.listcontainer) of [`CurrencySelect.Section`](#currencyselect.section) rows to build a custom token picker. For a ready-made implementation see [`TokenSelectModal`](#tokenselectmodal).
+
+Compound component. Members:
+
+##### CurrencySelect.Modal
+
+Modal wrapper.
+
+##### CurrencySelect.Search
+
+Auto-focused search input row.
+
+##### CurrencySelect.ListContainer
+
+Scrollable list area with built-in empty state.
+
+##### CurrencySelect.SectionHeader
+
+Header label rendered above a section.
+
+##### CurrencySelect.Section
+
+Container for a group of currency rows.
+
+#### LowBalanceModal
+
+Modal shown when a transaction would leave insufficient TON to cover fees — adapts its body and buttons to the [`LowBalanceMode`](#lowbalancemode).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `open`\* | `boolean` | Controls visibility of the modal. |
+| `mode`\* | <code><a href="#lowbalancemode">LowBalanceMode</a></code> | `reduce` — user can fix it by reducing the amount (shows Change/Cancel). `topup`  — reducing doesn't help, user must top up TON (shows Close only). |
+| `requiredTon`\* | `string` | Required amount in TON, formatted as a decimal string (e.g. `"0.423"`). |
+| `onChange`\* | `() => void` | Called when the user clicks the primary "Change" action (only in `reduce` mode). |
+| `onCancel`\* | `() => void` | Called when the user dismisses the modal (Cancel, Close, or backdrop click). |
+
+#### OptionSwitcher
+
+Compact dropdown selector — renders the current option's label and a chevron, opening a [`Select`](#select) popover with the remaining choices. Falls back to the raw `value` or `"—"` when no option matches.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string \| undefined` | Currently selected option value. |
+| `options`\* | <code><a href="#optionswitcheroption">OptionSwitcherOption</a>[]</code> | Available options. |
+| `onChange`\* | `(value: string) => void` | Called when the user picks an option. |
+| `disabled` | `boolean` | When true, the trigger is non-interactive and dimmed. |
+| `className` | `string` | Extra class applied to the trigger button. |
+
+#### SettingsButton
+
+Icon-only secondary button with a sliders icon — drop-in trigger for opening settings panels.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `onClick` | `() => void` | Click handler — typically used to open a settings modal. |
+| `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. |
+
+#### TokenSelectModal
+
+Ready-made token picker modal — renders a search field and a sectioned list of [`CurrencyItem`](#currencyitem) rows backed by [`CurrencySelect`](#currencyselect). Search matches by symbol, name, or exact address; selecting a row fires `onSelect`, closes the modal, and resets the search.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `open`\* | `boolean` | Controls modal visibility. |
+| `onClose`\* | `() => void` | Called when the modal is dismissed (selection, backdrop click, or escape). |
+| `tokens`\* | `T = AppkitUIToken[]` | Full set of tokens available for selection and search. |
+| `tokenSections` | <code><a href="#tokensectionconfig">TokenSectionConfig</a>[]</code> | Optional sectioning rules; when omitted, all tokens render as a single untitled section. |
+| `onSelect`\* | `(token: T = AppkitUIToken) => void` | Called with the picked token; the modal closes and resets its search on selection. |
+| `title`\* | `string` | Modal header title. |
+| `searchPlaceholder` | `string` | Placeholder shown inside the search input. |
+
+#### TokenSelector
+
+Compact pill button used as the trigger for a token picker — shows the token icon (optionally with a network badge), its symbol, and a chevron unless `readOnly` is set.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `title`\* | `string` | Label shown next to the icon — typically the token symbol. |
+| `icon` | `string` | Token logo URL. |
+| `iconFallback` | `string` | Single-character fallback used when `icon` fails to load; defaults to the first character of `title`. |
+| `networkIcon` | `string` | When provided, renders a network badge overlay on the icon. |
+| `readOnly` | `boolean` | Hide chevron and suppress click handling — use when there's nothing to pick. |
+| `size` | `ButtonSize` | Size class applied to the button. Pass `'unset'` to skip the size class entirely (no padding, no typography) — useful with `variant="unstyled"`. |
+| `borderRadius` | `ButtonBorderRadius` | Border radius token; defaults to a size-dependent value (`s` → `2xl`, `m` → `l`, `l` → `xl`). |
+| `variant` | `ButtonVariant` | Visual variant. Use `'unstyled'` to opt out of all built-in styling — the consumer is fully responsible for visuals via `className`. The Button still provides ref forwarding, `disabled`/`loading` plumbing, and `icon`/`children` rendering. |
+| `loading` | `boolean` | When true, renders a spinner instead of `icon`/`children` and disables the button. |
+| `fullWidth` | `boolean` | When true, the button stretches to fill its container width. |
+
+### Staking
+
+#### SelectUnstakeMode
+
+Collapsible selector for the unstake mode (instant / round-end / when-available). Filters options by `providerMetadata.supportedUnstakeModes` and renders nothing when only one mode is supported. Annotates the instant option with the provider's current instant-unstake limit.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value`\* | <code><a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a></code> | Currently selected unstake mode (see [`UnstakeMode`](/ecosystem/appkit/reference/appkit#unstakemode)). |
+| `onValueChange`\* | <code>(mode: <a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a>) =&gt; void</code> | Called when the user picks a different mode. |
+| `providerInfo`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingproviderinfo">StakingProviderInfo</a> \| undefined</code> | Dynamic provider info — used to show the instant-unstake limit when available. |
+| `providerMetadata`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> | Static provider metadata — supplies `supportedUnstakeModes` and stake-token formatting. |
+
+#### StakingBalanceBlock
+
+Row showing the user's relevant balance for the current direction: wallet balance of the stake token when staking, staked balance when unstaking. Renders a token icon (native TON when the token address is `'ton'`, otherwise a jetton icon resolved via [`useJettonInfo`](#usejettoninfo)), a label, the formatted amount with ticker, and an optional `MAX` button.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `providerMetadata`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> | Provider metadata — supplies the stake/receive tokens (address, ticker, decimals). |
+| `direction`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a></code> | Operation direction; selects which token and balance to render. |
+| `stakedBalance` | `string` | User's currently staked amount, used when `direction === 'unstake'`. |
+| `isStakedBalanceLoading` | `boolean` | True while the staked balance is being fetched. |
+| `balance` | `string` | User's wallet balance of the stake token, used when `direction === 'stake'`. |
+| `isBalanceLoading` | `boolean` | True while the wallet balance is being fetched. |
+| `onMaxClick` | `() => void` | When provided, renders a `MAX` button that invokes this callback. |
+
+#### StakingInfo
+
+Summary block rendered below the staking input. Shows the amount the user will receive, the provider's current APY, the stake-token to receive-token exchange rate (only when the provider has a receive token), and the provider name. The exchange-rate row always reads as `1 stakeToken = X receiveToken`, regardless of `direction`.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `quote`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquote">StakingQuote</a> \| undefined</code> | Current staking quote — its `amountOut` is rendered in the "You get" row. |
+| `isQuoteLoading`\* | `boolean` | True while the quote is being fetched; swaps the "You get" value for a skeleton. |
+| `providerInfo`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingproviderinfo">StakingProviderInfo</a> \| undefined</code> | Dynamic provider info — supplies APY and exchange rate. |
+| `providerMetadata`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> | Static provider metadata — supplies token tickers/decimals and the provider name. |
+| `isProviderInfoLoading`\* | `boolean` | True while provider info is being fetched. |
+| `direction` | <code><a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a></code> | Operation direction — controls which token's decimals/ticker label the "You get" amount. Defaults to `'stake'`. |
+
+#### StakingSettingsModal
+
+Modal that lets the user pick the active staking provider. The selection is staged locally and only committed via `onProviderChange` when the user presses `Save`; closing the modal otherwise discards the change. Each option is labeled with the provider's metadata `name`, falling back to its `providerId` if metadata is unavailable on the given network.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `open`\* | `boolean` | Controls modal visibility. |
+| `onClose`\* | `() => void` | Called when the user dismisses the modal or after a successful save. |
+| `provider`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a> \| undefined</code> | Currently active staking provider — used to preselect the option when the modal opens. |
+| `providers`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a>[]</code> | All registered staking providers to choose from. |
+| `onProviderChange`\* | `(providerId: string) => void` | Invoked with the chosen `providerId` when the user saves a different selection. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used to resolve each provider's display name via its metadata. |
+
+#### StakingWidget
+
+High-level staking widget that wires the full stake/unstake flow: pick a provider, enter an amount (with optional reverse input on supported providers), review the quote (APY, exchange rate, "you get"), then submit the transaction. Internally wraps [`StakingWidgetProvider`](#stakingwidgetprovider) around [`StakingWidgetUI`](#stakingwidgetui); consumers can replace the UI by passing a render-prop `children` while keeping the widget's state, quoting, balance checks, and submission logic.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `children` | <code>(props: <a href="#stakingwidgetrenderprops">StakingWidgetRenderProps</a>) =&gt; ReactNode</code> | Optional render-prop. When provided, the default [`StakingWidgetUI`](#stakingwidgetui) is bypassed and this function is called with the full [`StakingWidgetRenderProps`](#stakingwidgetrenderprops) (context state + forwarded `<div>` props), letting consumers build a custom UI on top of the widget's internal logic. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used for quote fetching, balance reads, and transactions. Falls back to the connected wallet's network when omitted. |
+
+#### StakingWidgetProvider
+
+Headless provider that owns all staking-widget state. Tracks the input amount, direction (stake/unstake), unstake mode, and reverse-input toggle; resolves the selected provider via [`useStakingProvider`](#usestakingprovider) and its info/metadata via [`useStakingProviderInfo`](#usestakingproviderinfo) and [`useStakingProviderMetadata`](#usestakingprovidermetadata); reads the user's wallet balance (native TON or jetton) and staked balance; debounces inputs into [`useStakingQuote`](#usestakingquote); and submits via [`useBuildStakeTransaction`](#usebuildstaketransaction) + `useSendTransaction`, gating on a TON-shortfall check to surface a low-balance warning. Validation flags (`error`, `canSubmit`) come from `useStakingValidation`. Exposes everything through `StakingContext` for [`useStakingContext`](#usestakingcontext) consumers.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used for quote fetching, balance reads, and transactions. Falls back to the connected wallet's network when omitted. |
+
+#### StakingWidgetUI
+
+Default staking-widget UI. Renders a stake/unstake tabbed layout: a centered amount input with optional reversed input, a [`StakingBalanceBlock`](#stakingbalanceblock) for the relevant balance, the submit button (wired through `ButtonWithConnect` so a disconnected user is prompted to connect first), a settings button that opens [`StakingSettingsModal`](#stakingsettingsmodal), the unstake-mode picker ([`SelectUnstakeMode`](#selectunstakemode), unstake tab only), and a [`StakingInfo`](#stakinginfo) summary. A [`LowBalanceModal`](#lowbalancemodal) surfaces when the built transaction would exceed the user's TON balance. All state is consumed from props (typically supplied by [`StakingWidgetProvider`](#stakingwidgetprovider)); this component owns only the local `settings modal open` flag.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `amount`\* | `string` | Amount the user wants to stake (string to preserve input UX) |
+| `canSubmit`\* | `boolean` | Whether the user can proceed with staking (checks balance, amount validity, etc.) |
+| `quote`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquote">StakingQuote</a> \| undefined</code> | Raw staking quote from the provider |
+| `isQuoteLoading`\* | `boolean` | True while the stake quote is being fetched |
+| `error`\* | `string \| null` | Current validation/fetch error for staking, null when everything is ok |
+| `providerInfo`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingproviderinfo">StakingProviderInfo</a> \| undefined</code> | Staking provider dynamic info (APY, instant unstake availability, etc.) |
+| `providerMetadata`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> | Staking provider static metadata |
+| `stakingProvider`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a> \| undefined</code> | Currently selected staking provider (defaults to the first registered one) |
+| `stakingProviders`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a>[]</code> | All registered staking providers |
+| `setStakingProviderId`\* | `(providerId: string) => void` | Updates the selected staking provider |
+| `network`\* | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a> \| undefined</code> | Network the widget is operating on (resolved from prop or wallet) |
+| `direction`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a></code> | Current operation direction: 'stake' or 'unstake' |
+| `isProviderInfoLoading`\* | `boolean` | True while provider info is being fetched |
+| `balance`\* | `string \| undefined` | Base balance (native or jetton) available for staking |
+| `isBalanceLoading`\* | `boolean` | True while base balance is being fetched |
+| `stakedBalance`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingbalance">StakingBalance</a> \| undefined</code> | User's currently staked balance |
+| `isStakedBalanceLoading`\* | `boolean` | True while staked balance is being fetched |
+| `unstakeMode`\* | <code><a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a></code> | Selected unstake mode (e.g. instant or delayed) |
+| `setAmount`\* | `(amount: string) => void` | Sets the input amount |
+| `setUnstakeMode`\* | <code>(mode: <a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a>) =&gt; void</code> | Sets the unstake mode |
+| `sendTransaction`\* | `() => Promise<void>` | Triggers the staking/unstaking transaction |
+| `onChangeDirection`\* | <code>(direction: <a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a>) =&gt; void</code> | Changes the direction (stake/unstake) |
+| `isSendingTransaction`\* | `boolean` | True while a transaction is being processed |
+| `isReversed`\* | `boolean` | True if the user is inputting the output amount ("I want to get X") |
+| `toggleReversed`\* | `() => void` | Toggles between inputting from amount and output amount |
+| `reversedAmount`\* | `string` | Amount displayed in the reversed (bottom) input |
+| `onMaxClick`\* | `() => void` | Sets the input amount to the maximum available balance (leaves room for TON gas on native stake) |
+| `isLowBalanceWarningOpen`\* | `boolean` | True when the built transaction outflow exceeds the user's TON balance |
+| `lowBalanceMode`\* | `'reduce' \| 'topup'` | `reduce` when the outgoing token is TON (user can fix by changing amount), `topup` otherwise. |
+| `lowBalanceRequiredTon`\* | `string` | Required TON amount for the pending operation, formatted as a decimal string. Empty when no pending op. |
+| `onLowBalanceChange`\* | `() => void` | Replace the input with a value that fits into the current TON balance and close the warning |
+| `onLowBalanceCancel`\* | `() => void` | Dismiss the low-balance warning without changing the input |
+
+### Swap
+
+#### SwapField
+
+One row of the swap form. Renders the amount input, fiat conversion, balance line, and a token-selector chip. The `pay` variant is editable and exposes a "max" shortcut; the `receive` variant is read-only and shows the quote result.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `type`\* | `'pay' \| 'receive'` | `pay` renders the editable source row with a "max" shortcut; `receive` renders the read-only target row. |
+| `amount`\* | `string` | Current amount shown in the input as a human-readable decimal string. |
+| `fiatSymbol` | `string` | Fiat currency symbol displayed in front of the converted value. Defaults to `"$"`. |
+| `token` | `AppkitUIToken` | Currently selected token; controls the token selector label, balance formatting and fiat conversion. |
+| `onAmountChange` | `(value: string) => void` | Called with the raw input value when the user edits the amount. Only fired for `type: "pay"`. |
+| `balance` | `string` | Formatted balance of `token` for the active wallet, as a human-readable decimal string; rendered in the balance line beneath the input. |
+| `isBalanceLoading` | `boolean` | When true, the balance area renders a skeleton placeholder instead of the value. |
+| `loading` | `boolean` | When true, the underlying input renders its loading state — used while a fresh quote is in flight. |
+| `onMaxClick` | `() => void` | Called when the user clicks the "max" shortcut to fill the maximum spendable amount. |
+| `onTokenSelectorClick` | `() => void` | Called when the user clicks the token selector chip — typically opens a `SwapTokenSelectModal`. |
+| `isWalletConnected` | `boolean` | Reserved flag indicating whether a wallet is connected — currently accepted for API symmetry. |
+| `size` | `InputSize` | Size token applied to the input control(s) inside: `'s' | 'm' | 'l'`. Defaults to `'m'`. |
+| `variant` | `InputVariant` | Visual variant: `'default'` paints a filled field; `'unstyled'` drops the chrome. |
+| `disabled` | `boolean` | When true, descendant input controls are disabled. |
+| `error` | `boolean` | When true, the field renders in error styling and [`Input.Caption`](#input.caption) switches to error text. |
+| `resizable` | `boolean` | When true, [`Input.Input`](#input.input) scales its font down to fit the available width as the user types. |
+
+#### SwapFlipButton
+
+Round button rendered between the source and target [`SwapField`](#swapfield) rows. Clicking it flips the selected tokens; visual rotation is driven by `rotated`.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `onClick` | `() => void` | Called when the user clicks the button. Wire this to a handler that swaps the source/target tokens (e.g. `onFlip` from the swap context). |
+| `rotated` | `boolean` | When true, the icon is drawn in its rotated state — used to animate between flips. |
+
+#### SwapInfo
+
+Summary block rendered under the swap form. Shows the minimum amount the user is guaranteed to receive after slippage, the configured slippage tolerance, and the active [`SwapProvider`](/ecosystem/appkit/reference/appkit#swapprovider).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `toToken`\* | `AppkitUIToken \| null` | Target token the user is receiving; used to format `minReceived` with the right decimals and symbol. |
+| `slippage`\* | `number` | Slippage tolerance in basis points (`100` = 1%). Rendered as a percentage. |
+| `provider` | <code><a href="/ecosystem/appkit/reference/appkit#swapprovider">SwapProvider</a></code> | Current [`SwapProvider`](/ecosystem/appkit/reference/appkit#swapprovider); its display name is shown in the provider row. |
+| `quote` | <code><a href="/ecosystem/appkit/reference/appkit#swapquote">SwapQuote</a></code> | Quote whose `minReceived` value is displayed; when undefined the value falls back to `0` (still suffixed with the token symbol). |
+| `isQuoteLoading` | `boolean` | When true, the minimum-received value renders a skeleton placeholder instead of the formatted number. |
+
+#### SwapWidget
+
+Drop-in swap UI that walks the user through picking the source/target tokens, entering an amount, reviewing the quote (rate, min-received, slippage, provider), and confirming the swap — which builds the transaction via [`useBuildSwapTransaction`](#usebuildswaptransaction) and dispatches it through the standard send flow. Internally mounts a [`SwapWidgetProvider`](#swapwidgetprovider) so the rendered UI (default [`SwapWidgetUI`](#swapwidgetui) or a custom `children` render-prop) can read state through [`useSwapContext`](#useswapcontext).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `children` | <code>(props: <a href="#swapwidgetrenderprops">SwapWidgetRenderProps</a>) =&gt; ReactNode</code> | Optional render-prop receiving the full swap context plus the forwarded `<div>` props; when supplied it replaces the default [`SwapWidgetUI`](#swapwidgetui). |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used for quote fetching and balance reads. When omitted, falls back to the selected wallet's network via [`useNetwork`](#usenetwork). |
+| `tokens`\* | `AppkitUIToken[]` | Full list of tokens available for swapping in the UI. Filtered to the active network internally. |
+| `tokenSections` | <code><a href="#tokensectionconfig">TokenSectionConfig</a>[]</code> | Optional section configs for grouping tokens inside the `SwapTokenSelectModal`. |
+| `defaultFromSymbol` | `string` | Symbol of the token pre-selected as the source on first mount (e.g. `"TON"`). |
+| `defaultToSymbol` | `string` | Symbol of the token pre-selected as the target on first mount. |
+| `fiatSymbol` | `string` | Fiat currency symbol displayed next to converted amounts. Defaults to `"$"`. |
+| `defaultSlippage` | `number` | Initial slippage tolerance in basis points (`100` = 1%). Defaults to `100`. |
+
+#### SwapWidgetProvider
+
+Provider that wires up the full swap state machine — debounces the entered amount, fetches the quote via [`useSwapQuote`](#useswapquote), reads source/target balances, validates the input, exposes the active [`SwapProvider`](/ecosystem/appkit/reference/appkit#swapprovider), and offers `sendSwapTransaction` which builds the transaction with [`useBuildSwapTransaction`](#usebuildswaptransaction) and sends it (raising the low-balance warning when the outflow exceeds the user's TON balance). Children read everything through [`useSwapContext`](#useswapcontext).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `tokens`\* | `AppkitUIToken[]` | Full list of tokens available for swapping in the UI. Filtered to the active network internally. |
+| `tokenSections` | <code><a href="#tokensectionconfig">TokenSectionConfig</a>[]</code> | Optional section configs for grouping tokens inside the `SwapTokenSelectModal`. |
+| `defaultFromSymbol` | `string` | Symbol of the token pre-selected as the source on first mount (e.g. `"TON"`). |
+| `defaultToSymbol` | `string` | Symbol of the token pre-selected as the target on first mount. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used for quote fetching and balance reads. When omitted, falls back to the selected wallet's network via [`useNetwork`](#usenetwork). |
+| `fiatSymbol` | `string` | Fiat currency symbol displayed next to converted amounts. Defaults to `"$"`. |
+| `defaultSlippage` | `number` | Initial slippage tolerance in basis points (`100` = 1%). Defaults to `100`. |
+
+#### SwapWidgetUI
+
+Default visual implementation of the swap widget — composes [`SwapField`](#swapfield) (source, then target), a [`SwapFlipButton`](#swapflipbutton) between them, the submit button (auto-prompts wallet connect when no wallet is selected), the settings trigger that opens `SwapSettingsModal`, a `SwapTokenSelectModal` for picking source/target tokens, the [`SwapInfo`](#swapinfo) summary, and a low-balance warning. Drives all state from the swap context props it receives — pair with [`SwapWidgetProvider`](#swapwidgetprovider), or use [`SwapWidget`](#swapwidget) which mounts both.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `tokens`\* | `AppkitUIToken[]` | Full list of available tokens for swapping |
+| `tokenSections` | <code><a href="#tokensectionconfig">TokenSectionConfig</a>[]</code> | Optional section configs for grouping tokens in the selector |
+| `fromToken`\* | `AppkitUIToken \| null` | Currently selected source token |
+| `toToken`\* | `AppkitUIToken \| null` | Currently selected target token |
+| `fromAmount`\* | `string` | Amount the user wants to swap (string to preserve input UX) |
+| `toAmount`\* | `string` | Calculated receive amount from the current quote |
+| `fiatSymbol`\* | `string` | Fiat currency symbol for price display, e.g. "$" |
+| `fromBalance`\* | `string \| undefined` | User's balance of the "from" token |
+| `toBalance`\* | `string \| undefined` | User's balance of the "to" token |
+| `isFromBalanceLoading`\* | `boolean` | True while the "from" balance is being fetched |
+| `isToBalanceLoading`\* | `boolean` | True while the "to" balance is being fetched |
+| `canSubmit`\* | `boolean` | Whether the user can proceed with the swap (checks balance, amount, quote) |
+| `quote`\* | `GetSwapQuoteData \| undefined` | Raw swap quote from the provider |
+| `isQuoteLoading`\* | `boolean` | True while the quote is being fetched from the API |
+| `error`\* | `string \| null` | Current validation or fetch error, null when everything is ok |
+| `slippage`\* | `number` | Slippage tolerance in basis points (100 = 1%) |
+| `swapProvider`\* | <code><a href="/ecosystem/appkit/reference/appkit#swapprovider">SwapProvider</a> \| undefined</code> | Currently selected swap provider (defaults to the first registered one) |
+| `swapProviders`\* | <code><a href="/ecosystem/appkit/reference/appkit#swapprovider">SwapProvider</a>[]</code> | All registered swap providers |
+| `setSwapProviderId`\* | `(providerId: string) => void` | Updates the selected swap provider |
+| `setFromToken`\* | `(token: AppkitUIToken) => void` | Updates the source token |
+| `setToToken`\* | `(token: AppkitUIToken) => void` | Updates the target token |
+| `setFromAmount`\* | `(amount: string) => void` | Updates the swap amount |
+| `setSlippage`\* | `(slippage: number) => void` | Updates the slippage tolerance |
+| `onFlip`\* | `() => void` | Swaps source and target tokens |
+| `onMaxClick`\* | `() => void` | Sets the "from" amount to the maximum available balance |
+| `sendSwapTransaction`\* | `() => Promise<void>` | Executes the swap transaction |
+| `isSendingTransaction`\* | `boolean` | True while a transaction is being built or sent |
+| `isLowBalanceWarningOpen`\* | `boolean` | True when the built transaction outflow exceeds the user's TON balance |
+| `lowBalanceMode`\* | `'reduce' \| 'topup'` | `reduce` when the outgoing token is TON (user can fix by changing amount), `topup` otherwise. |
+| `lowBalanceRequiredTon`\* | `string` | Required TON amount for the pending operation, formatted as a decimal string. Empty when no pending op. |
+| `onLowBalanceChange`\* | `() => void` | Replace the input with a value that fits into the current TON balance and close the warning |
+| `onLowBalanceCancel`\* | `() => void` | Dismiss the low-balance warning without changing the input |
+
+### UI
+
+#### Block
+
+Flex container primitive — renders a `<div>` that lays its children out vertically (`'column'`) or horizontally (`'row'`).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `direction` | `'row' \| 'column'` | Flex direction of the block. Defaults to `'column'`. |
+
+#### Button
+
+Themed `<button>` with size, border-radius, and variant tokens. Renders an optional leading `icon`, swaps content for a spinner while `loading`, and is disabled whenever `disabled` or `loading` is true.
+
+#### CenteredAmountInput
+
+Center-aligned, auto-resizing amount input with optional leading symbol and trailing ticker. Scales the font down to fit the container when the rendered text overflows, and clicking the wrapper focuses the input.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Controlled input value (decimal string). |
+| `onValueChange`\* | `(value: string) => void` | Called with the new string whenever the user edits the input. |
+| `ticker` | `string` | Optional trailing ticker label (e.g., `'TON'`). |
+| `symbol` | `string` | Optional leading currency symbol (e.g., `'$'`). |
+| `placeholder` | `string` | Placeholder shown when `value` is empty. Defaults to `'0'`. |
+| `disabled` | `boolean` | When true, the underlying `<input>` is disabled. |
+
+#### CheckIcon
+
+Checkmark icon — a single stroked tick.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### ChevronDownIcon
+
+Downward-pointing chevron icon — typically used to indicate expandable content.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### ChevronsIcon
+
+Stacked up/down chevrons icon — used to signal select/dropdown affordance.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### CloseIcon
+
+Close (X) icon — used for dismiss buttons and modal close affordances.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### Collapsible
+
+Animated collapsible container — transitions its height between `0` and the content's natural height when `open` toggles. Sets `aria-hidden` to mirror the open state.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `open`\* | `boolean` | When true, the content is expanded; when false, it is collapsed to zero height. |
+
+#### CopyIcon
+
+Copy icon — two overlapping rectangles indicating clipboard copy.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### FailedIcon
+
+Failure icon — a circle with an X, used for error and failed-transaction states.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### FlipIcon
+
+Flip / swap icon — two opposing arrows used for swap and direction-toggle actions.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### ImageIcon
+
+Image / picture placeholder icon — used as a fallback for missing media.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### InfoBlock
+
+Compound component for rendering a stacked list of label/value rows (e.g., transaction details, settings summaries). Sub-components forward extra props to the underlying DOM element so callers can layer custom classes and handlers.
+
+Compound component. Members:
+
+##### InfoBlock.Container
+
+Outer wrapper — vertical container that hosts the rows.
+
+##### InfoBlock.Row
+
+Horizontal row that pairs a label with a value.
+
+##### InfoBlock.Label
+
+Label cell — typically the muted descriptor on the left.
+
+##### InfoBlock.Value
+
+Value cell — typically the emphasized content on the right.
+
+##### InfoBlock.LabelSkeleton
+
+Skeleton placeholder for a [`InfoBlock.Label`](#infoblock.label) while data is loading. Defaults to `width=64`, `height='1lh'`.
+
+##### InfoBlock.ValueSkeleton
+
+Skeleton placeholder for a [`InfoBlock.Value`](#infoblock.value) while data is loading. Defaults to `width=80`, `height='1lh'`.
+
+#### Input
+
+Compound text-input component. Use the default export as the outer wrapper (it is the [`Input.Container`](#input.container)) and compose sub-components for the header, field, slots, control, and caption. State flags (`disabled`, `error`, `loading`, `resizable`, `size`) live on the container and are read by the inner control via context.
+
+#### Logo
+
+Square logo / avatar primitive — renders an `<img>` when `src` loads successfully, otherwise shows a text fallback (after a brief delay to avoid flicker). Useful for token icons, wallet avatars, and project logos.
+
+#### LogoWithNetwork
+
+Token logo with an overlaid network badge — wraps [`Logo`](#logo) and renders a smaller secondary logo as a corner badge to indicate which network the asset belongs to.
+
+#### Modal
+
+Centered modal dialog with a header (optional title + close button) and a scrollable body. Clicking the overlay closes the modal; clicks on the content do not bubble through.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `open` | `boolean` | Controlled open state. |
+| `onOpenChange` | `(open: boolean) => void` | Called whenever the open state changes (e.g., via the close button, overlay click, or `Escape`). |
+| `title` | `string` | Optional title rendered in the modal header. |
+| `children` | `ReactNode` | Modal body content. |
+| `className` | `string` | Additional class name applied to the content container. |
+| `bodyClassName` | `string` | Additional class name applied to the body container. |
+
+#### SearchIcon
+
+Magnifying-glass search icon.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### Select
+
+Compound select / dropdown component with controlled or uncontrolled state. The content is portaled to `document.body` and positioned relative to the trigger; closes on outside click, `Escape`, or item selection.
+
+Compound component. Members:
+
+##### Select.Root
+
+Provider that owns the selected value and open state, controlled or uncontrolled.
+
+##### Select.Trigger
+
+[`Button`](#button)-based trigger that toggles the popover and exposes `aria-expanded`.
+
+##### Select.Content
+
+Portaled popover that renders the list of items; positioned under the trigger with optional `sideOffset`.
+
+##### Select.Item
+
+Selectable option row; commits its `value` to the root on click.
+
+#### Skeleton
+
+Animated placeholder block used while data is loading. Supply `width` / `height` to match the dimensions of the eventual content.
+
+#### SlidersIcon
+
+Sliders / settings icon — two horizontal tracks with adjustable handles.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### SpinnerIcon
+
+Loading spinner icon — a three-quarter circle stroke. Animation must be applied via CSS by the caller.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### SuccessIcon
+
+Success icon — a circle with an inner checkmark for confirmation states.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### Tabs
+
+Root tabs container — owns the active value (controlled or uncontrolled) and shares it with descendant [`TabsList`](#tabslist), [`TabsTrigger`](#tabstrigger), and [`TabsContent`](#tabscontent) via context.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value` | `string` | Controlled active tab value. |
+| `defaultValue` | `string` | Initial active tab when uncontrolled. Defaults to `''`. |
+| `onValueChange` | `(value: string) => void` | Called whenever the active tab changes. |
+| `children`\* | `ReactNode` | Compound sub-components — typically [`TabsList`](#tabslist) (with [`TabsTrigger`](#tabstrigger)s) followed by [`TabsContent`](#tabscontent)s. |
+
+#### TabsContent
+
+Tab panel rendered with `role="tabpanel"`. Returns `null` unless its `value` matches the active [`Tabs`](#tabs) value.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Value this panel is associated with — rendered only when the parent [`Tabs`](#tabs) is on this value. |
+| `children`\* | `ReactNode` | Panel content. |
+
+#### TabsList
+
+Horizontal list of tab triggers with `role="tablist"`.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `children`\* | `ReactNode` | Tab triggers — typically one or more [`TabsTrigger`](#tabstrigger)s. |
+
+#### TabsTrigger
+
+Tab trigger button with `role="tab"`. Activates its `value` on click and reflects active state via `aria-selected` and `data-state`.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Value committed to the parent [`Tabs`](#tabs) when this trigger is activated. |
+| `children`\* | `ReactNode` | Trigger label / content. |
+
+#### TonIcon
+
+TON brand diamond glyph — solid, inherits color from `currentColor`.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### TonIconCircle
+
+TON brand glyph rendered inside a filled circle, using the TON brand color token.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### VerifiedIcon
+
+Verified badge icon — scalloped seal with an inner checkmark.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+## Type
+
+### Balances
+
+#### SendJettonButtonProps
+
+Props accepted by [`SendJettonButton`](#sendjettonbutton) — extends the base `Send` button props (button text, sizing, callbacks) with the jetton-transfer details.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `recipientAddress`\* | `string` | Recipient address. |
+| `amount`\* | `string` | Amount in jetton units as a human-readable decimal string; converted to raw smallest units via `jetton.decimals`. |
+| `jetton`\* | `{         address: string;         symbol: string;         decimals: number;     }` | Jetton master metadata — `address` (master contract), `symbol` (rendered in the button label) and `decimals` (used to format `amount`). |
+| `comment` | `string` | Optional human-readable comment attached to the transfer. |
+| `text` | `ReactNode` | Custom button text |
+| `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 |
+| `onError` | `(error: Error) => void` | Callback when an error occurs |
+| `onSuccess` | <code>(response: <a href="/ecosystem/appkit/reference/appkit#sendtransactionreturntype">SendTransactionReturnType</a>) =&gt; void</code> | Callback when the transaction is successful |
+
+#### SendTonButtonProps
+
+Props accepted by [`SendTonButton`](#sendtonbutton) — extends the base `Send` button props (button text, sizing, callbacks) with the TON-transfer details.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `recipientAddress`\* | `string` | Recipient address. |
+| `amount`\* | `string` | Amount in TON as a human-readable decimal string (e.g., `"1.5"`); converted to nano-TON internally. |
+| `comment` | `string` | Optional human-readable comment attached to the transfer. |
+| `text` | `ReactNode` | Custom button text |
+| `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 |
+| `onError` | `(error: Error) => void` | Callback when an error occurs |
+| `onSuccess` | <code>(response: <a href="/ecosystem/appkit/reference/appkit#sendtransactionreturntype">SendTransactionReturnType</a>) =&gt; void</code> | Callback when the transaction is successful |
+
+#### UseBalanceByAddressParameters
+
+Parameters accepted by [`useBalanceByAddress`](#usebalancebyaddress) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the target address and optional network override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Wallet address — pass a [`UserFriendlyAddress`](/ecosystem/appkit/reference/appkit#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseBalanceByAddressReturnType
+
+Return type of [`useBalanceByAddress`](#usebalancebyaddress) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseBalanceByAddressReturnType = UseQueryReturnType<
+    selectData,
+    GetBalanceErrorType
+>;
+```
+
+#### UseBalanceParameters
+
+Parameters accepted by [`useBalance`](#usebalance) — same shape as [`UseBalanceByAddressParameters`](#usebalancebyaddressparameters); the hook resolves `address` from the selected wallet and overrides any value supplied here.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Wallet address — pass a [`UserFriendlyAddress`](/ecosystem/appkit/reference/appkit#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseBalanceReturnType
+
+Return type of [`useBalance`](#usebalance) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseBalanceReturnType = UseBalanceByAddressReturnType<selectData>;
+```
+
+#### UseWatchBalanceByAddressParameters
+
+Parameters accepted by [`useWatchBalanceByAddress`](#usewatchbalancebyaddress) — same fields as [`WatchBalanceByAddressOptions`](/ecosystem/appkit/reference/appkit#watchbalancebyaddressoptions), all optional so callers can render the hook before the address is known.
+
+```ts
+type UseWatchBalanceByAddressParameters = Partial<WatchBalanceByAddressOptions>;
+```
+
+#### UseWatchBalanceParameters
+
+Parameters accepted by [`useWatchBalance`](#usewatchbalance) — same fields as [`UseWatchBalanceByAddressParameters`](#usewatchbalancebyaddressparameters) minus `address`, which the hook resolves from the selected wallet.
+
+```ts
+type UseWatchBalanceParameters = Omit<UseWatchBalanceByAddressParameters, 'address'>;
+```
+
+### Connectors
+
+#### UseConnectorsReturnType
+
+Return type of [`useConnectors`](#useconnectors) — same shape as [`GetConnectorsReturnType`](/ecosystem/appkit/reference/appkit#getconnectorsreturntype).
+
+```ts
+type UseConnectorsReturnType = GetConnectorsReturnType;
+```
+
+### Crypto Onramp
+
+#### ChainInfo
+
+Display info for a CAIP-2 chain — used by the crypto onramp widget to render chain names and logos.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name`\* | `string` | Human-readable chain name (e.g. `"Ethereum"`, `"Arbitrum One"`). |
+| `logo` | `string` | Optional logo URL for the chain. |
+
+#### CryptoAmountInputMode
+
+Which side the amount input is currently denominated in — `token` means the user is entering the target-token amount, `method` means they are entering the source payment-method amount.
+
+```ts
+type CryptoAmountInputMode = 'token' | 'method';
+```
+
+#### CryptoOnrampContextType
+
+Shape of the `CryptoOnrampContext` value — selection state, quote/deposit data and actions exposed by [`CryptoOnrampWidgetProvider`](#cryptoonrampwidgetprovider) to the widget UI (and to custom render callbacks passed to [`CryptoOnrampWidget`](#cryptoonrampwidget)).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `tokens`\* | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a>[]</code> | Full list of target tokens the user can buy. |
+| `tokenSections` | <code><a href="#cryptoonramptokensectionconfig">CryptoOnrampTokenSectionConfig</a>[]</code> | Optional section configs grouping `tokens` in the picker. |
+| `selectedToken`\* | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a> \| null</code> | Currently selected target token to buy. `null` until tokens load. |
+| `setSelectedToken`\* | <code>(token: <a href="#cryptoonramptoken">CryptoOnrampToken</a>) =&gt; void</code> | Updates `selectedToken`. |
+| `paymentMethods`\* | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a>[]</code> | Available source crypto payment methods. |
+| `methodSections` | <code><a href="#paymentmethodsectionconfig">PaymentMethodSectionConfig</a>[]</code> | Optional section configs grouping `paymentMethods` in the picker. |
+| `selectedMethod`\* | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a></code> | Currently selected source payment method. |
+| `setSelectedMethod`\* | <code>(method: <a href="#cryptopaymentmethod">CryptoPaymentMethod</a>) =&gt; void</code> | Updates `selectedMethod`. |
+| `chains`\* | <code>Record&lt;string, <a href="#chaininfo">ChainInfo</a>&gt;</code> | 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`\* | <code><a href="#cryptoamountinputmode">CryptoAmountInputMode</a></code> | Which side `amount` is denominated in — see [`CryptoAmountInputMode`](#cryptoamountinputmode). |
+| `setAmountInputMode`\* | <code>(mode: <a href="#cryptoamountinputmode">CryptoAmountInputMode</a>) =&gt; void</code> | Updates `amountInputMode`. |
+| `convertedAmount`\* | `string` | Other side of `amount` after applying the current quote's rate. |
+| `presetAmounts`\* | <code><a href="#onrampamountpreset">OnrampAmountPreset</a>[]</code> | Quick-pick amount buttons rendered in the widget. |
+| `quote`\* | <code><a href="/ecosystem/appkit/reference/appkit#cryptoonrampquote">CryptoOnrampQuote</a> \| null</code> | 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`\* | <code><a href="/ecosystem/appkit/reference/appkit#cryptoonrampdeposit">CryptoOnrampDeposit</a> \| null</code> | 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`\* | <code><a href="/ecosystem/appkit/reference/appkit#cryptoonrampstatus">CryptoOnrampStatus</a> \| null</code> | Latest deposit status polled via [`useCryptoOnrampStatus`](#usecryptoonrampstatus), or `null`. |
+| `isRefundAddressRequired`\* | `boolean` | Whether the current quote provider requires a refund address before deposit. |
+| `isReversedAmountSupported`\* | `boolean` | Whether the current quote provider supports reversed (target-amount) input. |
+| `refundAddress`\* | `string` | Refund address the user typed, if `isRefundAddressRequired`. |
+| `setRefundAddress`\* | `(address: string) => void` | Updates `refundAddress`. |
+| `targetBalance`\* | `string` | Connected wallet's balance of the selected target token (formatted, token units). |
+| `isLoadingTargetBalance`\* | `boolean` | Whether the target token balance is being fetched. |
+| `isWalletConnected`\* | `boolean` | Whether a TON wallet is currently connected. |
+| `canContinue`\* | `boolean` | Whether the user can proceed — valid amount, quote available, and wallet connected. |
+| `onReset`\* | `() => void` | Invalidates the active quote and clears the deposit, returning the widget to its initial state. |
+
+#### CryptoOnrampProviderProps
+
+Props for [`CryptoOnrampWidgetProvider`](#cryptoonrampwidgetprovider) — configures the target tokens and payment methods exposed to the widget, plus optional chain display overrides.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `tokens` | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a>[]</code> | Target tokens (what the user buys on TON). Defaults to a built-in list. |
+| `tokenSections` | <code><a href="#cryptoonramptokensectionconfig">CryptoOnrampTokenSectionConfig</a>[]</code> | Optional section configs grouping `tokens` in the picker. |
+| `paymentMethods` | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a>[]</code> | Source crypto payment methods (what the user pays with on another chain). Defaults to a built-in list. |
+| `methodSections` | <code><a href="#paymentmethodsectionconfig">PaymentMethodSectionConfig</a>[]</code> | Optional section configs grouping `paymentMethods` in the picker. |
+| `chains` | <code>Record&lt;string, <a href="#chaininfo">ChainInfo</a>&gt;</code> | 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 (e.g. `\{ 'eip155:42161': \{ name: 'Arbitrum', logo: '...' \} \}`). |
+| `defaultTokenId` | `string` | ID of the target token pre-selected on mount. |
+| `defaultMethodId` | `string` | ID of the source payment method pre-selected on mount. |
+
+#### CryptoOnrampToken
+
+Target token (what the user is buying on TON) in the crypto onramp widget. Kept separate from `AppkitUIToken` because `address` is the raw form expected by the onramp provider (e.g. `"0x0000000000000000000000000000000000000000"` for native TON, `"EQCx..."` for USDT jetton master).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id`\* | `string` | Stable identifier used by section configs and pre-selection props. |
+| `symbol`\* | `string` | Token symbol, e.g. `"TON"`, `"USDT"`. |
+| `name`\* | `string` | Full token name, e.g. `"Toncoin"`, `"Tether"`. |
+| `decimals`\* | `number` | Number of decimals for the token. |
+| `address`\* | `string` | Address as the onramp provider expects it. |
+| `logo` | `string` | Optional logo URL. |
+
+#### CryptoOnrampTokenSectionConfig
+
+Section configuration grouping [`CryptoOnrampToken`](#cryptoonramptoken) entries by id in a picker.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `title`\* | `string` | Section header (typically already localized by the caller). |
+| `ids`\* | `string[]` | Ids of [`CryptoOnrampToken`](#cryptoonramptoken) entries to include in this section, in order. |
+
+#### CryptoOnrampWidgetProps
+
+Props for [`CryptoOnrampWidget`](#cryptoonrampwidget) — extends [`CryptoOnrampProviderProps`](#cryptoonrampproviderprops) (tokens, payment methods, defaults, chain overrides) plus the native `<div>` props the widget root forwards.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `children` | <code>(props: <a href="#cryptoonrampwidgetrenderprops">CryptoOnrampWidgetRenderProps</a>) =&gt; ReactNode</code> | Custom render function. When provided, replaces the default [`CryptoOnrampWidgetUI`](#cryptoonrampwidgetui) and is called with the full [`CryptoOnrampWidgetRenderProps`](#cryptoonrampwidgetrenderprops) (context state, actions and forwarded `<div>` props), so callers can build a fully custom UI on top of the same provider. |
+| `tokens` | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a>[]</code> | Target tokens (what the user buys on TON). Defaults to a built-in list. |
+| `tokenSections` | <code><a href="#cryptoonramptokensectionconfig">CryptoOnrampTokenSectionConfig</a>[]</code> | Optional section configs grouping `tokens` in the picker. |
+| `paymentMethods` | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a>[]</code> | Source crypto payment methods (what the user pays with on another chain). Defaults to a built-in list. |
+| `methodSections` | <code><a href="#paymentmethodsectionconfig">PaymentMethodSectionConfig</a>[]</code> | Optional section configs grouping `paymentMethods` in the picker. |
+| `chains` | <code>Record&lt;string, <a href="#chaininfo">ChainInfo</a>&gt;</code> | 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 (e.g. `\{ 'eip155:42161': \{ name: 'Arbitrum', logo: '...' \} \}`). |
+| `defaultTokenId` | `string` | ID of the target token pre-selected on mount. |
+| `defaultMethodId` | `string` | ID of the source payment method pre-selected on mount. |
+
+#### CryptoOnrampWidgetRenderProps
+
+Props for [`CryptoOnrampWidgetUI`](#cryptoonrampwidgetui) (and for the custom render callback on [`CryptoOnrampWidget`](#cryptoonrampwidget)) — the full [`CryptoOnrampContextType`](#cryptoonrampcontexttype) state and actions, plus the native `<div>` props the widget root forwards (`className`, `style`, etc.).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `tokens`\* | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a>[]</code> | Full list of target tokens the user can buy. |
+| `tokenSections` | <code><a href="#cryptoonramptokensectionconfig">CryptoOnrampTokenSectionConfig</a>[]</code> | Optional section configs grouping `tokens` in the picker. |
+| `selectedToken`\* | <code><a href="#cryptoonramptoken">CryptoOnrampToken</a> \| null</code> | Currently selected target token to buy. `null` until tokens load. |
+| `setSelectedToken`\* | <code>(token: <a href="#cryptoonramptoken">CryptoOnrampToken</a>) =&gt; void</code> | Updates `selectedToken`. |
+| `paymentMethods`\* | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a>[]</code> | Available source crypto payment methods. |
+| `methodSections` | <code><a href="#paymentmethodsectionconfig">PaymentMethodSectionConfig</a>[]</code> | Optional section configs grouping `paymentMethods` in the picker. |
+| `selectedMethod`\* | <code><a href="#cryptopaymentmethod">CryptoPaymentMethod</a></code> | Currently selected source payment method. |
+| `setSelectedMethod`\* | <code>(method: <a href="#cryptopaymentmethod">CryptoPaymentMethod</a>) =&gt; void</code> | Updates `selectedMethod`. |
+| `chains`\* | <code>Record&lt;string, <a href="#chaininfo">ChainInfo</a>&gt;</code> | 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`\* | <code><a href="#cryptoamountinputmode">CryptoAmountInputMode</a></code> | Which side `amount` is denominated in — see [`CryptoAmountInputMode`](#cryptoamountinputmode). |
+| `setAmountInputMode`\* | <code>(mode: <a href="#cryptoamountinputmode">CryptoAmountInputMode</a>) =&gt; void</code> | Updates `amountInputMode`. |
+| `convertedAmount`\* | `string` | Other side of `amount` after applying the current quote's rate. |
+| `presetAmounts`\* | <code><a href="#onrampamountpreset">OnrampAmountPreset</a>[]</code> | Quick-pick amount buttons rendered in the widget. |
+| `quote`\* | <code><a href="/ecosystem/appkit/reference/appkit#cryptoonrampquote">CryptoOnrampQuote</a> \| null</code> | 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`\* | <code><a href="/ecosystem/appkit/reference/appkit#cryptoonrampdeposit">CryptoOnrampDeposit</a> \| null</code> | 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`\* | <code><a href="/ecosystem/appkit/reference/appkit#cryptoonrampstatus">CryptoOnrampStatus</a> \| null</code> | Latest deposit status polled via [`useCryptoOnrampStatus`](#usecryptoonrampstatus), or `null`. |
+| `isRefundAddressRequired`\* | `boolean` | Whether the current quote provider requires a refund address before deposit. |
+| `isReversedAmountSupported`\* | `boolean` | Whether the current quote provider supports reversed (target-amount) input. |
+| `refundAddress`\* | `string` | Refund address the user typed, if `isRefundAddressRequired`. |
+| `setRefundAddress`\* | `(address: string) => void` | Updates `refundAddress`. |
+| `targetBalance`\* | `string` | Connected wallet's balance of the selected target token (formatted, token units). |
+| `isLoadingTargetBalance`\* | `boolean` | Whether the target token balance is being fetched. |
+| `isWalletConnected`\* | `boolean` | Whether a TON wallet is currently connected. |
+| `canContinue`\* | `boolean` | Whether the user can proceed — valid amount, quote available, and wallet connected. |
+| `onReset`\* | `() => void` | Invalidates the active quote and clears the deposit, returning the widget to its initial state. |
+
+#### CryptoPaymentMethod
+
+Source crypto payment method (what the user pays with on another chain) in the crypto onramp widget.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id`\* | `string` | Stable identifier for the method — used for selection state and `methodSections.ids` |
+| `symbol`\* | `string` | Token symbol, e.g. "USDC", "USDT" |
+| `name`\* | `string` | Full token name shown in the picker, e.g. "USD Coin", "Tether" |
+| `chain`\* | `string` | Source chain in CAIP-2 format, e.g. "eip155:8453", "eip155:56" — passed as `sourceChain` to the onramp provider. The widget resolves a display name and logo for it via the `chains` map (see `CryptoOnrampWidgetProvider`). |
+| `decimals`\* | `number` | Number of decimals for the token (used to convert between display and base units) |
+| `address`\* | `string` | Token contract address on the source network (empty string / zero address for native) |
+| `logo` | `string` | Token logo URL shown in the picker and selectors |
+
+#### OnrampAmountPreset
+
+Quick-pick amount button shown above the crypto-onramp input (carried on [`CryptoOnrampContextType`](#cryptoonrampcontexttype)'s `presetAmounts`).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `amount`\* | `string` | Amount value the preset sets on click (decimal string). |
+| `label`\* | `string` | Button label shown to the user. |
+
+#### PaymentMethodSectionConfig
+
+Section configuration grouping [`CryptoPaymentMethod`](#cryptopaymentmethod) entries by id in a picker.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `title`\* | `string` | Section header (typically already localized by the caller). |
+| `ids`\* | `string[]` | Ids of [`CryptoPaymentMethod`](#cryptopaymentmethod) entries to include in this section, in order. |
+
+#### UseCreateCryptoOnrampDepositParameters
+
+Parameters accepted by [`useCreateCryptoOnrampDeposit`](#usecreatecryptoonrampdeposit) — TanStack Query mutation options forwarded via `parameters.mutation`.
+
+```ts
+type UseCreateCryptoOnrampDepositParameters = CreateCryptoOnrampDepositMutationOptions<context>;
+```
+
+#### UseCreateCryptoOnrampDepositReturnType
+
+Return type of [`useCreateCryptoOnrampDeposit`](#usecreatecryptoonrampdeposit) — TanStack Query mutation result.
+
+```ts
+type UseCreateCryptoOnrampDepositReturnType = UseMutationResult<
+    CreateCryptoOnrampDepositData,
+    CreateCryptoOnrampDepositErrorType,
+    CreateCryptoOnrampDepositVariables,
+    context
+>;
+```
+
+#### UseCryptoOnrampProviderReturnType
+
+Return type of [`useCryptoOnrampProvider`](#usecryptoonrampprovider) — the matching [`CryptoOnrampProviderInterface`](/ecosystem/appkit/reference/appkit#cryptoonrampproviderinterface), or `undefined` when none is registered (the hook swallows the throw from [`getCryptoOnrampProvider`](/ecosystem/appkit/reference/appkit#getcryptoonrampprovider)).
+
+```ts
+type UseCryptoOnrampProviderReturnType = GetCryptoOnrampProviderReturnType | undefined;
+```
+
+#### UseCryptoOnrampProvidersReturnType
+
+Return type of [`useCryptoOnrampProviders`](#usecryptoonrampproviders) — array of every [`CryptoOnrampProviderInterface`](/ecosystem/appkit/reference/appkit#cryptoonrampproviderinterface) currently registered on the AppKit instance.
+
+```ts
+type UseCryptoOnrampProvidersReturnType = GetCryptoOnrampProvidersReturnType;
+```
+
+#### UseCryptoOnrampQuoteParameters
+
+Parameters accepted by [`useCryptoOnrampQuote`](#usecryptoonrampquote) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the source/target assets, amount and optional provider override forwarded to [`getCryptoOnrampQuote`](/ecosystem/appkit/reference/appkit#getcryptoonrampquote).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `amount` | `string` | Amount to onramp (either source or target crypto, depending on isSourceAmount) |
+| `sourceCurrencyAddress` | `string` | Source crypto currency address (contract address or 0x0... for native) |
+| `sourceChain` | `string` | Source chain identifier in CAIP-2 format (e.g. 'eip155:1' for Ethereum mainnet, 'eip155:42161' for Arbitrum One). Providers map this to their own chain identifiers internally. |
+| `targetCurrencyAddress` | `string` | Target crypto currency address on TON (contract address or 0x0... for native) |
+| `recipientAddress` | `string` | TON address that will receive the target crypto |
+| `refundAddress` | `string` | Refund address for the source crypto |
+| `isSourceAmount` | `boolean` | If true, `amount` is the source amount to spend. If false, `amount` is the target amount to receive. Defaults to true when omitted. |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `providerId` | `string` | Provider to quote against; defaults to the registered default provider. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseCryptoOnrampQuoteReturnType
+
+Return type of [`useCryptoOnrampQuote`](#usecryptoonrampquote) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseCryptoOnrampQuoteReturnType = UseQueryReturnType<
+    selectData,
+    GetCryptoOnrampQuoteErrorType
+>;
+```
+
+#### UseCryptoOnrampStatusParameters
+
+Parameters accepted by [`useCryptoOnrampStatus`](#usecryptoonrampstatus) — TanStack Query options (`select`, `enabled`, `refetchInterval`, …) plus the deposit id, originating provider id and optional provider override forwarded to [`getCryptoOnrampStatus`](/ecosystem/appkit/reference/appkit#getcryptoonrampstatus).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `depositId` | `string` | Deposit id |
+| `providerId` | `string` | Identifier of the provider that issued this deposit |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseCryptoOnrampStatusReturnType
+
+Return type of [`useCryptoOnrampStatus`](#usecryptoonrampstatus) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseCryptoOnrampStatusReturnType = UseQueryReturnType<
+    selectData,
+    GetCryptoOnrampStatusErrorType
+>;
+```
+
+### Jettons
+
+#### UseJettonBalanceByAddressParameters
+
+Parameters accepted by [`useJettonBalanceByAddress`](#usejettonbalancebyaddress) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the jetton master, owner address, decimals and optional network override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `jettonAddress` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address (the token, not the user's wallet for it). |
+| `ownerAddress` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a></code> | Owner of the jetton wallet — typically the connected user's address. |
+| `jettonDecimals` | `number` | Decimals declared by the jetton master; used to format the raw balance into a human-readable string. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseJettonBalanceByAddressReturnType
+
+Return type of [`useJettonBalanceByAddress`](#usejettonbalancebyaddress) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseJettonBalanceByAddressReturnType = UseQueryReturnType<
+    selectData,
+    GetJettonBalanceErrorType
+>;
+```
+
+#### UseJettonInfoParameters
+
+Parameters accepted by [`useJettonInfo`](#usejettoninfo) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the jetton master address and optional network override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address whose metadata is being fetched. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseJettonInfoReturnType
+
+Return type of [`useJettonInfo`](#usejettoninfo) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions; `data` is `null` when the indexer has no record for that master address.
+
+```ts
+type UseJettonInfoReturnType = UseQueryReturnType<
+    selectData,
+    GetJettonInfoErrorType
+>;
+```
+
+#### UseJettonWalletAddressParameters
+
+Parameters accepted by [`useJettonWalletAddress`](#usejettonwalletaddress) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the jetton master, owner address and optional network override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `jettonAddress` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address. |
+| `ownerAddress` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a></code> | Owner whose jetton wallet should be derived. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseJettonWalletAddressReturnType
+
+Return type of [`useJettonWalletAddress`](#usejettonwalletaddress) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseJettonWalletAddressReturnType = UseQueryReturnType<
+    selectData,
+    GetJettonWalletAddressErrorType
+>;
+```
+
+#### UseJettonsByAddressParameters
+
+Parameters accepted by [`useJettonsByAddress`](#usejettonsbyaddress) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the owner address, optional network override and pagination.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](/ecosystem/appkit/reference/appkit#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `limit` | `number` | Maximum number of jettons to return. |
+| `offset` | `number` | Number of jettons to skip before returning results — used for pagination. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseJettonsByAddressReturnType
+
+Return type of [`useJettonsByAddress`](#usejettonsbyaddress) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseJettonsByAddressReturnType = UseQueryReturnType<
+    selectData,
+    GetJettonsErrorType
+>;
+```
+
+#### UseJettonsParameters
+
+Parameters accepted by [`useJettons`](#usejettons) — same shape as [`UseJettonsByAddressParameters`](#usejettonsbyaddressparameters); the hook resolves `address` from the selected wallet and overrides any value supplied here.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](/ecosystem/appkit/reference/appkit#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `limit` | `number` | Maximum number of jettons to return. |
+| `offset` | `number` | Number of jettons to skip before returning results — used for pagination. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseJettonsReturnType
+
+Return type of [`useJettons`](#usejettons) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseJettonsReturnType = UseJettonsByAddressReturnType<selectData>;
+```
+
+#### UseTransferJettonParameters
+
+Parameters accepted by [`useTransferJetton`](#usetransferjetton) — TanStack Query mutation options.
+
+```ts
+type UseTransferJettonParameters = TransferJettonOptions<context>;
+```
+
+#### UseTransferJettonReturnType
+
+Return type of [`useTransferJetton`](#usetransferjetton) — TanStack Query mutation result.
+
+```ts
+type UseTransferJettonReturnType = UseMutationReturnType<
+    TransferJettonData,
+    TransferJettonErrorType,
+    TransferJettonVariables,
+    context,
+    (
+        variables: TransferJettonVariables,
+        options?: MutateOptions<TransferJettonData, TransferJettonErrorType, TransferJettonVariables, context>,
+    ) => void,
+    MutateFunction<TransferJettonData, TransferJettonErrorType, TransferJettonVariables, context>
+>;
+```
+
+#### UseWatchJettonsByAddressParameters
+
+Parameters accepted by [`useWatchJettonsByAddress`](#usewatchjettonsbyaddress) — same fields as [`WatchJettonsByAddressOptions`](/ecosystem/appkit/reference/appkit#watchjettonsbyaddressoptions), all optional so callers can render the hook before the address is known.
+
+```ts
+type UseWatchJettonsByAddressParameters = Partial<WatchJettonsByAddressOptions>;
+```
+
+#### UseWatchJettonsParameters
+
+Parameters accepted by [`useWatchJettons`](#usewatchjettons) — update callback and optional network override; the hook resolves the address from the selected wallet.
+
+```ts
+type UseWatchJettonsParameters = Partial<WatchJettonsOptions>;
+```
+
+### NFTs
+
+#### NftItemProps
+
+Props accepted by [`NftItem`](#nftitem) — extends the native `<button>` props (`onClick`, `disabled`, `className`, …) with the NFT to render.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `nft`\* | <code><a href="/ecosystem/appkit/reference/appkit#nft">NFT</a></code> | NFT to render — name, collection name, image and on-sale state are derived via `getFormattedNftInfo`. |
+
+#### UseNFTsByAddressParameters
+
+Parameters accepted by [`useNftsByAddress`](#usenftsbyaddress) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the owner address, optional pagination (`limit`, `offset`) and network override.
+
+The `network` field defaults to the selected wallet's network; if no wallet is selected, falls back to AppKit's default network, or mainnet when none is set.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](/ecosystem/appkit/reference/appkit#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `limit` | `number` | Maximum number of NFTs to return. |
+| `offset` | `number` | Number of NFTs to skip before returning results — used for pagination. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseNFTsByAddressReturnType
+
+Return type of [`useNftsByAddress`](#usenftsbyaddress) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseNFTsByAddressReturnType = UseQueryReturnType<selectData, GetNFTsErrorType>;
+```
+
+#### UseNFTsParameters
+
+Parameters accepted by [`useNfts`](#usenfts) — same shape as [`UseNFTsByAddressParameters`](#usenftsbyaddressparameters); the hook resolves `address` from the selected wallet and overrides any value supplied here.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](/ecosystem/appkit/reference/appkit#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `limit` | `number` | Maximum number of NFTs to return. |
+| `offset` | `number` | Number of NFTs to skip before returning results — used for pagination. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseNFTsReturnType
+
+Return type of [`useNfts`](#usenfts) — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+
+```ts
+type UseNFTsReturnType = UseNFTsByAddressReturnType<selectData>;
+```
+
+#### UseNftParameters
+
+Parameters accepted by [`useNft`](#usenft) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the NFT contract address and optional network override.
+
+The `network` field defaults to the selected wallet's network; if no wallet is selected, falls back to AppKit's default network, or mainnet when none is set.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | NFT contract address — pass a [`UserFriendlyAddress`](/ecosystem/appkit/reference/appkit#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseNftReturnType
+
+Return type of [`useNft`](#usenft) — TanStack Query result carrying `data` (the NFT or `null` when the indexer has no record), `isLoading`, `error` and the standard companions.
+
+```ts
+type UseNftReturnType = UseQueryReturnType<selectData, GetNftErrorType>;
+```
+
+#### UseTransferNftParameters
+
+Parameters accepted by [`useTransferNft`](#usetransfernft) — TanStack Query mutation options.
+
+```ts
+type UseTransferNftParameters = TransferNftOptions<context>;
+```
+
+#### UseTransferNftReturnType
+
+Return type of [`useTransferNft`](#usetransfernft) — TanStack Query mutation result.
+
+```ts
+type UseTransferNftReturnType = UseMutationReturnType<
+    TransferNftData,
+    TransferNftErrorType,
+    TransferNftVariables,
+    context,
+    (
+        variables: TransferNftVariables,
+        options?: MutateOptions<TransferNftData, TransferNftErrorType, TransferNftVariables, context>,
+    ) => void,
+    MutateFunction<TransferNftData, TransferNftErrorType, TransferNftVariables, context>
+>;
+```
+
+### Networks
+
+#### UseBlockNumberParameters
+
+Parameters accepted by [`useBlockNumber`](#useblocknumber) — TanStack Query options plus an optional network override. Defaults to the selected wallet's network; if no wallet is selected, falls back to mainnet.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network to query. Defaults to mainnet when omitted. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseBlockNumberReturnType
+
+Return type of [`useBlockNumber`](#useblocknumber) — TanStack Query result.
+
+```ts
+type UseBlockNumberReturnType = UseQueryReturnType<
+    selectData,
+    GetBlockNumberErrorType
+>;
+```
+
+#### UseDefaultNetworkReturnType
+
+Return type of [`useDefaultNetwork`](#usedefaultnetwork) — `[network, setNetwork]` tuple. `network` is the current default (or `undefined`); `setNetwork` calls [`setDefaultNetwork`](/ecosystem/appkit/reference/appkit#setdefaultnetwork) and emits `networks:default-changed`.
+
+```ts
+type UseDefaultNetworkReturnType = [
+    network: GetDefaultNetworkReturnType,
+    setNetwork: (network: Network | undefined) => void,
+];
+```
+
+#### UseNetworkReturnType
+
+Return type of [`useNetwork`](#usenetwork) — `undefined` when no wallet is currently selected.
+
+```ts
+type UseNetworkReturnType = Network | undefined;
+```
+
+#### UseNetworksReturnType
+
+Return type of [`useNetworks`](#usenetworks) — same shape as [`GetNetworksReturnType`](/ecosystem/appkit/reference/appkit#getnetworksreturntype).
+
+```ts
+type UseNetworksReturnType = GetNetworksReturnType;
+```
+
+### Settings
+
+#### AppKitTheme
+
+Theme value accepted by [`useAppKitTheme`](#useappkittheme) — `'light'`, `'dark'`, or any custom string mapped to a `data-ta-theme` token in the host's CSS.
+
+```ts
+type AppKitTheme = 'light' | 'dark' | string;
+```
+
+### Shared
+
+#### AmountPreset
+
+Single preset entry rendered as a button in [`AmountPresets`](#amountpresets).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `label`\* | `string` | Text shown inside the button (e.g., `"25%"`, `"Max"`, `"100"`). |
+| `amount`\* | `string` | Value passed to [`AmountPresetsProps.onPresetSelect`](#amountpresetsprops.onpresetselect) when the button is clicked. |
+| `onSelect` | `() => void` | Optional custom click handler — when set, it runs instead of `onPresetSelect`. |
+
+#### AmountPresetsProps
+
+Props accepted by [`AmountPresets`](#amountpresets).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `presets`\* | <code><a href="#amountpreset">AmountPreset</a>[]</code> | 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`. |
+
+#### CopyButtonProps
+
+Props accepted by [`CopyButton`](#copybutton).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Text written to the clipboard when the button is clicked. |
+| `aria-label`\* | `string` | Accessible label for screen readers. |
+
+#### CurrencyItemProps
+
+Props accepted by [`CurrencyItem`](#currencyitem) when used as a single-shot button. Passing `children` switches it into compound mode and bypasses these fields.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `ticker` | `string` | Token symbol (e.g., `"TON"`) — also used as the icon fallback and rendered in the secondary line. |
+| `name` | `string` | Human-readable token name shown as the primary line; falls back to `ticker` when absent. |
+| `balance` | `string` | Main balance value shown on the right side (already-formatted string). |
+| `underBalance` | `string` | Optional secondary value (e.g., fiat equivalent) shown beneath the main balance. |
+| `icon` | `string` | URL of the token logo. |
+| `isVerified` | `boolean` | When true, renders a verified checkmark badge next to the name. |
+
+#### CurrencySelectListContainerProps
+
+Props accepted by [`CurrencySelect.ListContainer`](#currencyselect.listcontainer).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `isEmpty`\* | `boolean` | When true, renders the built-in empty state instead of `children`. |
+
+#### CurrencySelectSearchProps
+
+Props accepted by [`CurrencySelect.Search`](#currencyselect.search).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `searchValue`\* | `string` | Current search query. |
+| `onSearchChange`\* | `(value: string) => void` | Called whenever the user types in the search input. |
+| `placeholder` | `string` | Placeholder text shown when the input is empty. |
+| `size` | `InputSize` | Size token applied to the input control(s) inside: `'s' | 'm' | 'l'`. Defaults to `'m'`. |
+| `variant` | `InputVariant` | Visual variant: `'default'` paints a filled field; `'unstyled'` drops the chrome. |
+| `loading` | `boolean` | When true, [`Input.Input`](#input.input) renders a skeleton placeholder instead of an `<input>`. |
+| `disabled` | `boolean` | When true, descendant input controls are disabled. |
+| `error` | `boolean` | When true, the field renders in error styling and [`Input.Caption`](#input.caption) switches to error text. |
+| `resizable` | `boolean` | When true, [`Input.Input`](#input.input) scales its font down to fit the available width as the user types. |
+
+#### LowBalanceModalProps
+
+Props accepted by [`LowBalanceModal`](#lowbalancemodal).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `open`\* | `boolean` | Controls visibility of the modal. |
+| `mode`\* | <code><a href="#lowbalancemode">LowBalanceMode</a></code> | `reduce` — user can fix it by reducing the amount (shows Change/Cancel). `topup`  — reducing doesn't help, user must top up TON (shows Close only). |
+| `requiredTon`\* | `string` | Required amount in TON, formatted as a decimal string (e.g. `"0.423"`). |
+| `onChange`\* | `() => void` | Called when the user clicks the primary "Change" action (only in `reduce` mode). |
+| `onCancel`\* | `() => void` | Called when the user dismisses the modal (Cancel, Close, or backdrop click). |
+
+#### LowBalanceMode
+
+Behavior mode for [`LowBalanceModal`](#lowbalancemodal) — see [`LowBalanceModalProps.mode`](#lowbalancemodalprops.mode).
+
+```ts
+type LowBalanceMode = 'reduce' | 'topup';
+```
+
+#### OptionSwitcherOption
+
+Single entry rendered as an item inside [`OptionSwitcher`](#optionswitcher).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Stable value passed back to [`OptionSwitcherProps.onChange`](#optionswitcherprops.onchange) when selected. |
+| `label`\* | `string` | Human-readable label shown in the trigger and dropdown item. |
+
+#### OptionSwitcherProps
+
+Props accepted by [`OptionSwitcher`](#optionswitcher).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string \| undefined` | Currently selected option value. |
+| `options`\* | <code><a href="#optionswitcheroption">OptionSwitcherOption</a>[]</code> | Available options. |
+| `onChange`\* | `(value: string) => void` | Called when the user picks an option. |
+| `disabled` | `boolean` | When true, the trigger is non-interactive and dimmed. |
+| `className` | `string` | Extra class applied to the trigger button. |
+
+#### SettingsButtonProps
+
+Props accepted by [`SettingsButton`](#settingsbutton) — extends the base [`Button`](#button) props.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onClick` | `() => void` | Click handler — typically used to open a settings modal. |
+| `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. |
+
+#### TokenBase
+
+Minimal shape every token in [`TokenSelectModal`](#tokenselectmodal) must satisfy. Callers may use richer types (e.g., `AppkitUIToken`) — `TokenBase` only fixes the fields the modal reads.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id`\* | `string` | Stable identifier used to match tokens against [`TokenSectionConfig.ids`](#tokensectionconfig.ids). |
+| `symbol`\* | `string` | Ticker (e.g., `"TON"`) — used for display and search matching. |
+| `name`\* | `string` | Human-readable name — used for display and search matching. |
+| `address`\* | `string` | Token contract address — used for exact-address search matching and as the React `key`. |
+| `logo` | `string` | Optional logo URL. |
+
+#### TokenSectionConfig
+
+Configuration that maps token `id`s to a named section in [`TokenSelectModal`](#tokenselectmodal); tokens not covered are placed in an "Other tokens" trailing section.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `title`\* | `string` | Section header label. |
+| `ids`\* | `string[]` | [`TokenBase.id`](#tokenbase.id) values to include in this section, in render order. |
+
+#### TokenSelectModalProps
+
+Props accepted by [`TokenSelectModal`](#tokenselectmodal).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `open`\* | `boolean` | Controls modal visibility. |
+| `onClose`\* | `() => void` | Called when the modal is dismissed (selection, backdrop click, or escape). |
+| `tokens`\* | `T = AppkitUIToken[]` | Full set of tokens available for selection and search. |
+| `tokenSections` | <code><a href="#tokensectionconfig">TokenSectionConfig</a>[]</code> | Optional sectioning rules; when omitted, all tokens render as a single untitled section. |
+| `onSelect`\* | `(token: T = AppkitUIToken) => void` | Called with the picked token; the modal closes and resets its search on selection. |
+| `title`\* | `string` | Modal header title. |
+| `searchPlaceholder` | `string` | Placeholder shown inside the search input. |
+
+#### TokenSelectorProps
+
+Props accepted by [`TokenSelector`](#tokenselector) — extends the base [`Button`](#button) props.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `title`\* | `string` | Label shown next to the icon — typically the token symbol. |
+| `icon` | `string` | Token logo URL. |
+| `iconFallback` | `string` | Single-character fallback used when `icon` fails to load; defaults to the first character of `title`. |
+| `networkIcon` | `string` | When provided, renders a network badge overlay on the icon. |
+| `readOnly` | `boolean` | Hide chevron and suppress click handling — use when there's nothing to pick. |
+| `size` | `ButtonSize` | Size class applied to the button. Pass `'unset'` to skip the size class entirely (no padding, no typography) — useful with `variant="unstyled"`. |
+| `borderRadius` | `ButtonBorderRadius` | Border radius token; defaults to a size-dependent value (`s` → `2xl`, `m` → `l`, `l` → `xl`). |
+| `variant` | `ButtonVariant` | Visual variant. Use `'unstyled'` to opt out of all built-in styling — the consumer is fully responsible for visuals via `className`. The Button still provides ref forwarding, `disabled`/`loading` plumbing, and `icon`/`children` rendering. |
+| `loading` | `boolean` | When true, renders a spinner instead of `icon`/`children` and disables the button. |
+| `fullWidth` | `boolean` | When true, the button stretches to fill its container width. |
+
+### Signing
+
+#### UseSignBinaryParameters
+
+Parameters accepted by [`useSignBinary`](#usesignbinary) — TanStack Query mutation options.
+
+```ts
+type UseSignBinaryParameters = SignBinaryOptions<context>;
+```
+
+#### UseSignBinaryReturnType
+
+Return type of [`useSignBinary`](#usesignbinary) — TanStack Query mutation result.
+
+```ts
+type UseSignBinaryReturnType = UseMutationResult<
+    SignBinaryData,
+    SignBinaryErrorType,
+    SignBinaryVariables,
+    context
+>;
+```
+
+#### UseSignCellParameters
+
+Parameters accepted by [`useSignCell`](#usesigncell) — TanStack Query mutation options.
+
+```ts
+type UseSignCellParameters = SignCellOptions<context>;
+```
+
+#### UseSignCellReturnType
+
+Return type of [`useSignCell`](#usesigncell) — TanStack Query mutation result.
+
+```ts
+type UseSignCellReturnType = UseMutationResult<
+    SignCellData,
+    SignCellErrorType,
+    SignCellVariables,
+    context
+>;
+```
+
+#### UseSignTextParameters
+
+Parameters accepted by [`useSignText`](#usesigntext) — TanStack Query mutation options.
+
+```ts
+type UseSignTextParameters = SignTextOptions<context>;
+```
+
+#### UseSignTextReturnType
+
+Return type of [`useSignText`](#usesigntext) — TanStack Query mutation result.
+
+```ts
+type UseSignTextReturnType = UseMutationResult<
+    SignTextData,
+    SignTextErrorType,
+    SignTextVariables,
+    context
+>;
+```
+
+### Staking
+
+#### SelectUnstakeModeProps
+
+Props accepted by [`SelectUnstakeMode`](#selectunstakemode).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value`\* | <code><a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a></code> | Currently selected unstake mode (see [`UnstakeMode`](/ecosystem/appkit/reference/appkit#unstakemode)). |
+| `onValueChange`\* | <code>(mode: <a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a>) =&gt; void</code> | Called when the user picks a different mode. |
+| `providerInfo`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingproviderinfo">StakingProviderInfo</a> \| undefined</code> | Dynamic provider info — used to show the instant-unstake limit when available. |
+| `providerMetadata`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> | Static provider metadata — supplies `supportedUnstakeModes` and stake-token formatting. |
+
+#### StakingBalanceBlockProps
+
+Props accepted by [`StakingBalanceBlock`](#stakingbalanceblock).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `providerMetadata`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> | Provider metadata — supplies the stake/receive tokens (address, ticker, decimals). |
+| `direction`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a></code> | Operation direction; selects which token and balance to render. |
+| `stakedBalance` | `string` | User's currently staked amount, used when `direction === 'unstake'`. |
+| `isStakedBalanceLoading` | `boolean` | True while the staked balance is being fetched. |
+| `balance` | `string` | User's wallet balance of the stake token, used when `direction === 'stake'`. |
+| `isBalanceLoading` | `boolean` | True while the wallet balance is being fetched. |
+| `onMaxClick` | `() => void` | When provided, renders a `MAX` button that invokes this callback. |
+
+#### StakingContextType
+
+Shape of the staking context exposed by [`StakingWidgetProvider`](#stakingwidgetprovider) and read via [`useStakingContext`](#usestakingcontext). Aggregates inputs (amount, direction, unstake mode), fetched data (balances, quote, provider info/metadata), derived flags (`canSubmit`, `error`, loading states), and the actions used by [`StakingWidgetUI`](#stakingwidgetui) (send transaction, switch provider, max, low-balance handling).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `amount`\* | `string` | Amount the user wants to stake (string to preserve input UX) |
+| `canSubmit`\* | `boolean` | Whether the user can proceed with staking (checks balance, amount validity, etc.) |
+| `quote`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquote">StakingQuote</a> \| undefined</code> | Raw staking quote from the provider |
+| `isQuoteLoading`\* | `boolean` | True while the stake quote is being fetched |
+| `error`\* | `string \| null` | Current validation/fetch error for staking, null when everything is ok |
+| `providerInfo`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingproviderinfo">StakingProviderInfo</a> \| undefined</code> | Staking provider dynamic info (APY, instant unstake availability, etc.) |
+| `providerMetadata`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> | Staking provider static metadata |
+| `stakingProvider`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a> \| undefined</code> | Currently selected staking provider (defaults to the first registered one) |
+| `stakingProviders`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a>[]</code> | All registered staking providers |
+| `setStakingProviderId`\* | `(providerId: string) => void` | Updates the selected staking provider |
+| `network`\* | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a> \| undefined</code> | Network the widget is operating on (resolved from prop or wallet) |
+| `direction`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a></code> | Current operation direction: 'stake' or 'unstake' |
+| `isProviderInfoLoading`\* | `boolean` | True while provider info is being fetched |
+| `balance`\* | `string \| undefined` | Base balance (native or jetton) available for staking |
+| `isBalanceLoading`\* | `boolean` | True while base balance is being fetched |
+| `stakedBalance`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingbalance">StakingBalance</a> \| undefined</code> | User's currently staked balance |
+| `isStakedBalanceLoading`\* | `boolean` | True while staked balance is being fetched |
+| `unstakeMode`\* | <code><a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a></code> | Selected unstake mode (e.g. instant or delayed) |
+| `setAmount`\* | `(amount: string) => void` | Sets the input amount |
+| `setUnstakeMode`\* | <code>(mode: <a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a>) =&gt; void</code> | Sets the unstake mode |
+| `sendTransaction`\* | `() => Promise<void>` | Triggers the staking/unstaking transaction |
+| `onChangeDirection`\* | <code>(direction: <a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a>) =&gt; void</code> | Changes the direction (stake/unstake) |
+| `isSendingTransaction`\* | `boolean` | True while a transaction is being processed |
+| `isReversed`\* | `boolean` | True if the user is inputting the output amount ("I want to get X") |
+| `toggleReversed`\* | `() => void` | Toggles between inputting from amount and output amount |
+| `reversedAmount`\* | `string` | Amount displayed in the reversed (bottom) input |
+| `onMaxClick`\* | `() => void` | Sets the input amount to the maximum available balance (leaves room for TON gas on native stake) |
+| `isLowBalanceWarningOpen`\* | `boolean` | True when the built transaction outflow exceeds the user's TON balance |
+| `lowBalanceMode`\* | `'reduce' \| 'topup'` | `reduce` when the outgoing token is TON (user can fix by changing amount), `topup` otherwise. |
+| `lowBalanceRequiredTon`\* | `string` | Required TON amount for the pending operation, formatted as a decimal string. Empty when no pending op. |
+| `onLowBalanceChange`\* | `() => void` | Replace the input with a value that fits into the current TON balance and close the warning |
+| `onLowBalanceCancel`\* | `() => void` | Dismiss the low-balance warning without changing the input |
+
+#### StakingInfoProps
+
+Props accepted by [`StakingInfo`](#stakinginfo).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `quote`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquote">StakingQuote</a> \| undefined</code> | Current staking quote — its `amountOut` is rendered in the "You get" row. |
+| `isQuoteLoading`\* | `boolean` | True while the quote is being fetched; swaps the "You get" value for a skeleton. |
+| `providerInfo`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingproviderinfo">StakingProviderInfo</a> \| undefined</code> | Dynamic provider info — supplies APY and exchange rate. |
+| `providerMetadata`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> | Static provider metadata — supplies token tickers/decimals and the provider name. |
+| `isProviderInfoLoading`\* | `boolean` | True while provider info is being fetched. |
+| `direction` | <code><a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a></code> | Operation direction — controls which token's decimals/ticker label the "You get" amount. Defaults to `'stake'`. |
+
+#### StakingProviderProps
+
+Props accepted by [`StakingWidgetProvider`](#stakingwidgetprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used for quote fetching, balance reads, and transactions. Falls back to the connected wallet's network when omitted. |
+
+#### StakingSettingsModalProps
+
+Props accepted by [`StakingSettingsModal`](#stakingsettingsmodal).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `open`\* | `boolean` | Controls modal visibility. |
+| `onClose`\* | `() => void` | Called when the user dismisses the modal or after a successful save. |
+| `provider`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a> \| undefined</code> | Currently active staking provider — used to preselect the option when the modal opens. |
+| `providers`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a>[]</code> | All registered staking providers to choose from. |
+| `onProviderChange`\* | `(providerId: string) => void` | Invoked with the chosen `providerId` when the user saves a different selection. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used to resolve each provider's display name via its metadata. |
+
+#### StakingWidgetProps
+
+Props accepted by [`StakingWidget`](#stakingwidget). Extends [`StakingProviderProps`](#stakingproviderprops) (e.g. `network`) and standard `<div>` props forwarded to the default UI.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `children` | <code>(props: <a href="#stakingwidgetrenderprops">StakingWidgetRenderProps</a>) =&gt; ReactNode</code> | Optional render-prop. When provided, the default [`StakingWidgetUI`](#stakingwidgetui) is bypassed and this function is called with the full [`StakingWidgetRenderProps`](#stakingwidgetrenderprops) (context state + forwarded `<div>` props), letting consumers build a custom UI on top of the widget's internal logic. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used for quote fetching, balance reads, and transactions. Falls back to the connected wallet's network when omitted. |
+
+#### StakingWidgetRenderProps
+
+Props accepted by [`StakingWidgetUI`](#stakingwidgetui) (also the argument type for the `StakingWidget` render-prop). Combines the full [`StakingContextType`](#stakingcontexttype) with standard `<div>` props forwarded to the outer wrapper.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `amount`\* | `string` | Amount the user wants to stake (string to preserve input UX) |
+| `canSubmit`\* | `boolean` | Whether the user can proceed with staking (checks balance, amount validity, etc.) |
+| `quote`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquote">StakingQuote</a> \| undefined</code> | Raw staking quote from the provider |
+| `isQuoteLoading`\* | `boolean` | True while the stake quote is being fetched |
+| `error`\* | `string \| null` | Current validation/fetch error for staking, null when everything is ok |
+| `providerInfo`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingproviderinfo">StakingProviderInfo</a> \| undefined</code> | Staking provider dynamic info (APY, instant unstake availability, etc.) |
+| `providerMetadata`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovidermetadata">StakingProviderMetadata</a> \| undefined</code> | Staking provider static metadata |
+| `stakingProvider`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a> \| undefined</code> | Currently selected staking provider (defaults to the first registered one) |
+| `stakingProviders`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingprovider">StakingProvider</a>[]</code> | All registered staking providers |
+| `setStakingProviderId`\* | `(providerId: string) => void` | Updates the selected staking provider |
+| `network`\* | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a> \| undefined</code> | Network the widget is operating on (resolved from prop or wallet) |
+| `direction`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a></code> | Current operation direction: 'stake' or 'unstake' |
+| `isProviderInfoLoading`\* | `boolean` | True while provider info is being fetched |
+| `balance`\* | `string \| undefined` | Base balance (native or jetton) available for staking |
+| `isBalanceLoading`\* | `boolean` | True while base balance is being fetched |
+| `stakedBalance`\* | <code><a href="/ecosystem/appkit/reference/appkit#stakingbalance">StakingBalance</a> \| undefined</code> | User's currently staked balance |
+| `isStakedBalanceLoading`\* | `boolean` | True while staked balance is being fetched |
+| `unstakeMode`\* | <code><a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a></code> | Selected unstake mode (e.g. instant or delayed) |
+| `setAmount`\* | `(amount: string) => void` | Sets the input amount |
+| `setUnstakeMode`\* | <code>(mode: <a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a>) =&gt; void</code> | Sets the unstake mode |
+| `sendTransaction`\* | `() => Promise<void>` | Triggers the staking/unstaking transaction |
+| `onChangeDirection`\* | <code>(direction: <a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a>) =&gt; void</code> | Changes the direction (stake/unstake) |
+| `isSendingTransaction`\* | `boolean` | True while a transaction is being processed |
+| `isReversed`\* | `boolean` | True if the user is inputting the output amount ("I want to get X") |
+| `toggleReversed`\* | `() => void` | Toggles between inputting from amount and output amount |
+| `reversedAmount`\* | `string` | Amount displayed in the reversed (bottom) input |
+| `onMaxClick`\* | `() => void` | Sets the input amount to the maximum available balance (leaves room for TON gas on native stake) |
+| `isLowBalanceWarningOpen`\* | `boolean` | True when the built transaction outflow exceeds the user's TON balance |
+| `lowBalanceMode`\* | `'reduce' \| 'topup'` | `reduce` when the outgoing token is TON (user can fix by changing amount), `topup` otherwise. |
+| `lowBalanceRequiredTon`\* | `string` | Required TON amount for the pending operation, formatted as a decimal string. Empty when no pending op. |
+| `onLowBalanceChange`\* | `() => void` | Replace the input with a value that fits into the current TON balance and close the warning |
+| `onLowBalanceCancel`\* | `() => void` | Dismiss the low-balance warning without changing the input |
+
+#### UseBuildStakeTransactionReturnType
+
+Return type of [`useBuildStakeTransaction`](#usebuildstaketransaction) — TanStack Query mutation result that resolves to a [`TransactionRequest`](/ecosystem/appkit/reference/appkit#transactionrequest).
+
+```ts
+type UseBuildStakeTransactionReturnType = UseMutationResult<
+    BuildStakeTransactionData,
+    BuildStakeTransactionErrorType,
+    BuildStakeTransactionVariables,
+    context
+>;
+```
+
+#### UseStakedBalanceParameters
+
+Parameters accepted by [`useStakedBalance`](#usestakedbalance) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the owner address, optional network override and optional `providerId`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `userAddress` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a></code> | Owner whose staked balance should be read. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `providerId` | `string` | Provider to query; defaults to the registered default staking provider. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseStakedBalanceReturnType
+
+Return type of [`useStakedBalance`](#usestakedbalance) — TanStack Query result carrying the user's staked balance.
+
+```ts
+type UseStakedBalanceReturnType = UseQueryReturnType<
+    selectData,
+    GetStakedBalanceErrorType
+>;
+```
+
+#### UseStakingProviderInfoParameters
+
+Parameters accepted by [`useStakingProviderInfo`](#usestakingproviderinfo) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus an optional `providerId` and network override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | 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. |
+| `providerId` | `string` | Provider to query; defaults to the registered default staking provider. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseStakingProviderInfoReturnType
+
+Return type of [`useStakingProviderInfo`](#usestakingproviderinfo) — TanStack Query result carrying live [`StakingProviderInfo`](/ecosystem/appkit/reference/appkit#stakingproviderinfo).
+
+```ts
+type UseStakingProviderInfoReturnType = UseQueryReturnType<
+    selectData,
+    GetStakingProviderInfoErrorType
+>;
+```
+
+#### UseStakingProviderMetadataParameters
+
+Parameters accepted by [`useStakingProviderMetadata`](#usestakingprovidermetadata) — optional `providerId` and network override.
+
+```ts
+type UseStakingProviderMetadataParameters = GetStakingProviderMetadataOptions;
+```
+
+#### UseStakingProviderMetadataReturnType
+
+Return type of [`useStakingProviderMetadata`](#usestakingprovidermetadata) — static [`StakingProviderMetadata`](/ecosystem/appkit/reference/appkit#stakingprovidermetadata) for the resolved provider, or `undefined` when no provider matches and no default is registered (the hook swallows the throw from [`getStakingProviderMetadata`](/ecosystem/appkit/reference/appkit#getstakingprovidermetadata)).
+
+```ts
+type UseStakingProviderMetadataReturnType = GetStakingProviderMetadataReturnType | undefined;
+```
+
+#### UseStakingProviderReturnType
+
+Return type of [`useStakingProvider`](#usestakingprovider) — the matching staking provider, or `undefined` when none resolves (the hook swallows the throw from [`getStakingProvider`](/ecosystem/appkit/reference/appkit#getstakingprovider)).
+
+```ts
+type UseStakingProviderReturnType = GetStakingProviderReturnType | undefined;
+```
+
+#### UseStakingProvidersReturnType
+
+Return type of [`useStakingProviders`](#usestakingproviders) — array of registered staking providers.
+
+```ts
+type UseStakingProvidersReturnType = GetStakingProvidersReturnType;
+```
+
+#### UseStakingQuoteParameters
+
+Parameters accepted by [`useStakingQuote`](#usestakingquote) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus stake/unstake amount, direction, target asset and optional `providerId`/network override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `direction` | <code><a href="/ecosystem/appkit/reference/appkit#stakingquotedirection">StakingQuoteDirection</a></code> | Direction of the quote (stake or unstake) |
+| `amount` | `string` | Amount of tokens to stake or unstake |
+| `userAddress` | <code><a href="/ecosystem/appkit/reference/appkit#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the user |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network on which the staking will be executed |
+| `unstakeMode` | <code><a href="/ecosystem/appkit/reference/appkit#unstakemodes">UnstakeModes</a></code> | Requested mode of unstaking |
+| `isReversed` | `boolean` | If true, for unstake requests the amount is specified in the staking coin (e.g. TON) instead of the Liquid Staking Token (e.g. tsTON). |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `providerId` | `string` | Provider to quote against; defaults to the registered default staking provider. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseStakingQuoteReturnType
+
+Return type of [`useStakingQuote`](#usestakingquote) — TanStack Query result carrying a [`StakingQuote`](/ecosystem/appkit/reference/appkit#stakingquote).
+
+```ts
+type UseStakingQuoteReturnType = UseQueryReturnType<
+    selectData,
+    GetStakingQuoteErrorType
+>;
+```
+
+### Swap
+
+#### SwapContextType
+
+Shape of the value exposed by [`useSwapContext`](#useswapcontext). Holds the selected source/target tokens, the entered amount and the latest quote, balance readouts, validation state, slippage / provider settings, and the callbacks needed to mutate them or to submit the swap transaction.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `tokens`\* | `AppkitUIToken[]` | Full list of available tokens for swapping |
+| `tokenSections` | <code><a href="#tokensectionconfig">TokenSectionConfig</a>[]</code> | Optional section configs for grouping tokens in the selector |
+| `fromToken`\* | `AppkitUIToken \| null` | Currently selected source token |
+| `toToken`\* | `AppkitUIToken \| null` | Currently selected target token |
+| `fromAmount`\* | `string` | Amount the user wants to swap (string to preserve input UX) |
+| `toAmount`\* | `string` | Calculated receive amount from the current quote |
+| `fiatSymbol`\* | `string` | Fiat currency symbol for price display, e.g. "$" |
+| `fromBalance`\* | `string \| undefined` | User's balance of the "from" token |
+| `toBalance`\* | `string \| undefined` | User's balance of the "to" token |
+| `isFromBalanceLoading`\* | `boolean` | True while the "from" balance is being fetched |
+| `isToBalanceLoading`\* | `boolean` | True while the "to" balance is being fetched |
+| `canSubmit`\* | `boolean` | Whether the user can proceed with the swap (checks balance, amount, quote) |
+| `quote`\* | `GetSwapQuoteData \| undefined` | Raw swap quote from the provider |
+| `isQuoteLoading`\* | `boolean` | True while the quote is being fetched from the API |
+| `error`\* | `string \| null` | Current validation or fetch error, null when everything is ok |
+| `slippage`\* | `number` | Slippage tolerance in basis points (100 = 1%) |
+| `swapProvider`\* | <code><a href="/ecosystem/appkit/reference/appkit#swapprovider">SwapProvider</a> \| undefined</code> | Currently selected swap provider (defaults to the first registered one) |
+| `swapProviders`\* | <code><a href="/ecosystem/appkit/reference/appkit#swapprovider">SwapProvider</a>[]</code> | All registered swap providers |
+| `setSwapProviderId`\* | `(providerId: string) => void` | Updates the selected swap provider |
+| `setFromToken`\* | `(token: AppkitUIToken) => void` | Updates the source token |
+| `setToToken`\* | `(token: AppkitUIToken) => void` | Updates the target token |
+| `setFromAmount`\* | `(amount: string) => void` | Updates the swap amount |
+| `setSlippage`\* | `(slippage: number) => void` | Updates the slippage tolerance |
+| `onFlip`\* | `() => void` | Swaps source and target tokens |
+| `onMaxClick`\* | `() => void` | Sets the "from" amount to the maximum available balance |
+| `sendSwapTransaction`\* | `() => Promise<void>` | Executes the swap transaction |
+| `isSendingTransaction`\* | `boolean` | True while a transaction is being built or sent |
+| `isLowBalanceWarningOpen`\* | `boolean` | True when the built transaction outflow exceeds the user's TON balance |
+| `lowBalanceMode`\* | `'reduce' \| 'topup'` | `reduce` when the outgoing token is TON (user can fix by changing amount), `topup` otherwise. |
+| `lowBalanceRequiredTon`\* | `string` | Required TON amount for the pending operation, formatted as a decimal string. Empty when no pending op. |
+| `onLowBalanceChange`\* | `() => void` | Replace the input with a value that fits into the current TON balance and close the warning |
+| `onLowBalanceCancel`\* | `() => void` | Dismiss the low-balance warning without changing the input |
+
+#### SwapFieldProps
+
+Props accepted by [`SwapField`](#swapfield) — a single source/target row inside the swap widget that hosts the amount input, token picker trigger, fiat conversion and balance line.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `type`\* | `'pay' \| 'receive'` | `pay` renders the editable source row with a "max" shortcut; `receive` renders the read-only target row. |
+| `amount`\* | `string` | Current amount shown in the input as a human-readable decimal string. |
+| `fiatSymbol` | `string` | Fiat currency symbol displayed in front of the converted value. Defaults to `"$"`. |
+| `token` | `AppkitUIToken` | Currently selected token; controls the token selector label, balance formatting and fiat conversion. |
+| `onAmountChange` | `(value: string) => void` | Called with the raw input value when the user edits the amount. Only fired for `type: "pay"`. |
+| `balance` | `string` | Formatted balance of `token` for the active wallet, as a human-readable decimal string; rendered in the balance line beneath the input. |
+| `isBalanceLoading` | `boolean` | When true, the balance area renders a skeleton placeholder instead of the value. |
+| `loading` | `boolean` | When true, the underlying input renders its loading state — used while a fresh quote is in flight. |
+| `onMaxClick` | `() => void` | Called when the user clicks the "max" shortcut to fill the maximum spendable amount. |
+| `onTokenSelectorClick` | `() => void` | Called when the user clicks the token selector chip — typically opens a `SwapTokenSelectModal`. |
+| `isWalletConnected` | `boolean` | Reserved flag indicating whether a wallet is connected — currently accepted for API symmetry. |
+| `size` | `InputSize` | Size token applied to the input control(s) inside: `'s' | 'm' | 'l'`. Defaults to `'m'`. |
+| `variant` | `InputVariant` | Visual variant: `'default'` paints a filled field; `'unstyled'` drops the chrome. |
+| `disabled` | `boolean` | When true, descendant input controls are disabled. |
+| `error` | `boolean` | When true, the field renders in error styling and [`Input.Caption`](#input.caption) switches to error text. |
+| `resizable` | `boolean` | When true, [`Input.Input`](#input.input) scales its font down to fit the available width as the user types. |
+
+#### SwapFlipButtonProps
+
+Props accepted by [`SwapFlipButton`](#swapflipbutton) — the round button placed between the two [`SwapField`](#swapfield) rows that swaps the source and target tokens.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onClick` | `() => void` | Called when the user clicks the button. Wire this to a handler that swaps the source/target tokens (e.g. `onFlip` from the swap context). |
+| `rotated` | `boolean` | When true, the icon is drawn in its rotated state — used to animate between flips. |
+
+#### SwapInfoProps
+
+Props accepted by [`SwapInfo`](#swapinfo) — the summary block under the swap form that surfaces minimum received, slippage and the chosen provider.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `toToken`\* | `AppkitUIToken \| null` | Target token the user is receiving; used to format `minReceived` with the right decimals and symbol. |
+| `slippage`\* | `number` | Slippage tolerance in basis points (`100` = 1%). Rendered as a percentage. |
+| `provider` | <code><a href="/ecosystem/appkit/reference/appkit#swapprovider">SwapProvider</a></code> | Current [`SwapProvider`](/ecosystem/appkit/reference/appkit#swapprovider); its display name is shown in the provider row. |
+| `quote` | <code><a href="/ecosystem/appkit/reference/appkit#swapquote">SwapQuote</a></code> | Quote whose `minReceived` value is displayed; when undefined the value falls back to `0` (still suffixed with the token symbol). |
+| `isQuoteLoading` | `boolean` | When true, the minimum-received value renders a skeleton placeholder instead of the formatted number. |
+
+#### SwapProviderProps
+
+Props accepted by [`SwapWidgetProvider`](#swapwidgetprovider) — the inputs that configure the swap flow (token universe, network override, defaults).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `tokens`\* | `AppkitUIToken[]` | Full list of tokens available for swapping in the UI. Filtered to the active network internally. |
+| `tokenSections` | <code><a href="#tokensectionconfig">TokenSectionConfig</a>[]</code> | Optional section configs for grouping tokens inside the `SwapTokenSelectModal`. |
+| `defaultFromSymbol` | `string` | Symbol of the token pre-selected as the source on first mount (e.g. `"TON"`). |
+| `defaultToSymbol` | `string` | Symbol of the token pre-selected as the target on first mount. |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used for quote fetching and balance reads. When omitted, falls back to the selected wallet's network via [`useNetwork`](#usenetwork). |
+| `fiatSymbol` | `string` | Fiat currency symbol displayed next to converted amounts. Defaults to `"$"`. |
+| `defaultSlippage` | `number` | Initial slippage tolerance in basis points (`100` = 1%). Defaults to `100`. |
+
+#### SwapWidgetProps
+
+Props accepted by [`SwapWidget`](#swapwidget) — extend [`SwapProviderProps`](#swapproviderprops) (swap configuration: tokens, network, defaults) with the standard `<div>` attributes and an optional render-prop override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `children` | <code>(props: <a href="#swapwidgetrenderprops">SwapWidgetRenderProps</a>) =&gt; ReactNode</code> | Optional render-prop receiving the full swap context plus the forwarded `<div>` props; when supplied it replaces the default [`SwapWidgetUI`](#swapwidgetui). |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network used for quote fetching and balance reads. When omitted, falls back to the selected wallet's network via [`useNetwork`](#usenetwork). |
+| `tokens`\* | `AppkitUIToken[]` | Full list of tokens available for swapping in the UI. Filtered to the active network internally. |
+| `tokenSections` | <code><a href="#tokensectionconfig">TokenSectionConfig</a>[]</code> | Optional section configs for grouping tokens inside the `SwapTokenSelectModal`. |
+| `defaultFromSymbol` | `string` | Symbol of the token pre-selected as the source on first mount (e.g. `"TON"`). |
+| `defaultToSymbol` | `string` | Symbol of the token pre-selected as the target on first mount. |
+| `fiatSymbol` | `string` | Fiat currency symbol displayed next to converted amounts. Defaults to `"$"`. |
+| `defaultSlippage` | `number` | Initial slippage tolerance in basis points (`100` = 1%). Defaults to `100`. |
+
+#### SwapWidgetRenderProps
+
+Props accepted by [`SwapWidgetUI`](#swapwidgetui) (and the `children` render-prop on [`SwapWidget`](#swapwidget)). Combines the full [`SwapContextType`](#swapcontexttype) with the standard `<div>` attributes forwarded to the wrapper element.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `tokens`\* | `AppkitUIToken[]` | Full list of available tokens for swapping |
+| `tokenSections` | <code><a href="#tokensectionconfig">TokenSectionConfig</a>[]</code> | Optional section configs for grouping tokens in the selector |
+| `fromToken`\* | `AppkitUIToken \| null` | Currently selected source token |
+| `toToken`\* | `AppkitUIToken \| null` | Currently selected target token |
+| `fromAmount`\* | `string` | Amount the user wants to swap (string to preserve input UX) |
+| `toAmount`\* | `string` | Calculated receive amount from the current quote |
+| `fiatSymbol`\* | `string` | Fiat currency symbol for price display, e.g. "$" |
+| `fromBalance`\* | `string \| undefined` | User's balance of the "from" token |
+| `toBalance`\* | `string \| undefined` | User's balance of the "to" token |
+| `isFromBalanceLoading`\* | `boolean` | True while the "from" balance is being fetched |
+| `isToBalanceLoading`\* | `boolean` | True while the "to" balance is being fetched |
+| `canSubmit`\* | `boolean` | Whether the user can proceed with the swap (checks balance, amount, quote) |
+| `quote`\* | `GetSwapQuoteData \| undefined` | Raw swap quote from the provider |
+| `isQuoteLoading`\* | `boolean` | True while the quote is being fetched from the API |
+| `error`\* | `string \| null` | Current validation or fetch error, null when everything is ok |
+| `slippage`\* | `number` | Slippage tolerance in basis points (100 = 1%) |
+| `swapProvider`\* | <code><a href="/ecosystem/appkit/reference/appkit#swapprovider">SwapProvider</a> \| undefined</code> | Currently selected swap provider (defaults to the first registered one) |
+| `swapProviders`\* | <code><a href="/ecosystem/appkit/reference/appkit#swapprovider">SwapProvider</a>[]</code> | All registered swap providers |
+| `setSwapProviderId`\* | `(providerId: string) => void` | Updates the selected swap provider |
+| `setFromToken`\* | `(token: AppkitUIToken) => void` | Updates the source token |
+| `setToToken`\* | `(token: AppkitUIToken) => void` | Updates the target token |
+| `setFromAmount`\* | `(amount: string) => void` | Updates the swap amount |
+| `setSlippage`\* | `(slippage: number) => void` | Updates the slippage tolerance |
+| `onFlip`\* | `() => void` | Swaps source and target tokens |
+| `onMaxClick`\* | `() => void` | Sets the "from" amount to the maximum available balance |
+| `sendSwapTransaction`\* | `() => Promise<void>` | Executes the swap transaction |
+| `isSendingTransaction`\* | `boolean` | True while a transaction is being built or sent |
+| `isLowBalanceWarningOpen`\* | `boolean` | True when the built transaction outflow exceeds the user's TON balance |
+| `lowBalanceMode`\* | `'reduce' \| 'topup'` | `reduce` when the outgoing token is TON (user can fix by changing amount), `topup` otherwise. |
+| `lowBalanceRequiredTon`\* | `string` | Required TON amount for the pending operation, formatted as a decimal string. Empty when no pending op. |
+| `onLowBalanceChange`\* | `() => void` | Replace the input with a value that fits into the current TON balance and close the warning |
+| `onLowBalanceCancel`\* | `() => void` | Dismiss the low-balance warning without changing the input |
+
+#### UseBuildSwapTransactionParameters
+
+Parameters accepted by [`useBuildSwapTransaction`](#usebuildswaptransaction) — TanStack Query mutation options.
+
+```ts
+type UseBuildSwapTransactionParameters = BuildSwapTransactionMutationOptions<context>;
+```
+
+#### UseBuildSwapTransactionReturnType
+
+Return type of [`useBuildSwapTransaction`](#usebuildswaptransaction) — TanStack Query mutation result.
+
+```ts
+type UseBuildSwapTransactionReturnType = UseMutationResult<
+    BuildSwapTransactionData,
+    BuildSwapTransactionErrorType,
+    BuildSwapTransactionVariables,
+    context
+>;
+```
+
+#### UseSwapProviderReturnType
+
+Return type of [`useSwapProvider`](#useswapprovider) — `[provider, setProviderId]` tuple. `provider` is the default `SwapProviderInterface` (or `undefined` when none is registered); `setProviderId` calls [`setDefaultSwapProvider`](/ecosystem/appkit/reference/appkit#setdefaultswapprovider) and emits `provider:default-changed`, which [`watchSwapProviders`](/ecosystem/appkit/reference/appkit#watchswapproviders) picks up.
+
+```ts
+type UseSwapProviderReturnType = readonly [GetSwapProviderReturnType | undefined, (providerId: string) => void];
+```
+
+#### UseSwapProvidersReturnType
+
+Return type of [`useSwapProviders`](#useswapproviders) — array of every `SwapProviderInterface` currently registered on the AppKit instance.
+
+```ts
+type UseSwapProvidersReturnType = GetSwapProvidersReturnType;
+```
+
+#### UseSwapQuoteParameters
+
+Parameters accepted by [`useSwapQuote`](#useswapquote) — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the [`SwapQuoteParams`](/ecosystem/appkit/reference/appkit#swapquoteparams) fields (source/target tokens, amount, `isReverseSwap` flag) and an optional `providerId` / network override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `amount` | `string` | Amount of tokens to swap (incoming or outgoing depending on isReverseSwap) |
+| `from` | <code><a href="/ecosystem/appkit/reference/appkit#swaptoken">SwapToken</a></code> | Token to swap from |
+| `to` | <code><a href="/ecosystem/appkit/reference/appkit#swaptoken">SwapToken</a></code> | Token to swap to |
+| `network` | <code><a href="/ecosystem/appkit/reference/appkit#network">Network</a></code> | Network on which the swap will be executed |
+| `slippageBps` | `number` | Slippage tolerance in basis points (1 bp = 0.01%) |
+| `maxOutgoingMessages` | `number` | Maximum number of outgoing messages |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `isReverseSwap` | `boolean` | If true, amount is the amount to receive (buy). If false, amount is the amount to spend (sell). |
+| `providerId` | `string` | Provider to quote against; defaults to the registered default swap provider. |
+| `query` | `UnionLooseOmit<QueryOptions<queryFnData = unknown, error = Query.DefaultError, data = queryFnData, queryKey = Query.QueryKey>, 'queryKey = Query.QueryKey' \| 'queryFn'> \| undefined` | TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. |
+
+#### UseSwapQuoteReturnType
+
+Return type of [`useSwapQuote`](#useswapquote) — TanStack Query result carrying `data` ([`SwapQuote`](/ecosystem/appkit/reference/appkit#swapquote)), `isLoading`, `error` and the standard companions.
+
+```ts
+type UseSwapQuoteReturnType = UseQueryReturnType<
+    selectData,
+    GetSwapQuoteErrorType
+>;
+```
+
+### Transactions
+
+#### UseSendTransactionParameters
+
+Parameters accepted by [`useSendTransaction`](#usesendtransaction) — TanStack Query mutation options.
+
+```ts
+type UseSendTransactionParameters = SendTransactionOptions<context>;
+```
+
+#### UseSendTransactionReturnType
+
+Return type of [`useSendTransaction`](#usesendtransaction) — TanStack Query mutation result.
+
+```ts
+type UseSendTransactionReturnType = UseMutationReturnType<
+    SendTransactionData,
+    SendTransactionErrorType,
+    SendTransactionVariables,
+    context,
+    (
+        variables: SendTransactionVariables,
+        options?: MutateOptions<SendTransactionData, SendTransactionErrorType, SendTransactionVariables, context>,
+    ) => void,
+    MutateFunction<SendTransactionData, SendTransactionErrorType, SendTransactionVariables, context>
+>;
+```
+
+#### UseTransactionStatusParameters
+
+Parameters accepted by [`useTransactionStatus`](#usetransactionstatus) — `boc` xor `normalizedHash` plus optional network and TanStack Query overrides; pair with `query.refetchInterval` to poll until the transaction completes.
+
+```ts
+type UseTransactionStatusParameters = GetTransactionStatusParameters &
+    GetTransactionStatusQueryConfig<selectData>;
+```
+
+#### UseTransactionStatusReturnType
+
+Return type of [`useTransactionStatus`](#usetransactionstatus) — TanStack Query result for the status read.
+
+```ts
+type UseTransactionStatusReturnType = UseQueryReturnType<
+    selectData,
+    GetTransactionStatusErrorType
+>;
+```
+
+#### UseTransferTonParameters
+
+Parameters accepted by [`useTransferTon`](#usetransferton) — TanStack Query mutation options.
+
+```ts
+type UseTransferTonParameters = TransferTonOptions<context>;
+```
+
+#### UseTransferTonReturnType
+
+Return type of [`useTransferTon`](#usetransferton) — TanStack Query mutation result.
+
+```ts
+type UseTransferTonReturnType = UseMutationReturnType<
+    TransferTonData,
+    TransferTonErrorType,
+    TransferTonVariables,
+    context,
+    (
+        variables: TransferTonVariables,
+        options?: MutateOptions<TransferTonData, TransferTonErrorType, TransferTonVariables, context>,
+    ) => void,
+    MutateFunction<TransferTonData, TransferTonErrorType, TransferTonVariables, context>
+>;
+```
+
+#### UseWatchTransactionsByAddressParameters
+
+Parameters accepted by [`useWatchTransactionsByAddress`](#usewatchtransactionsbyaddress) — same fields as [`WatchTransactionsByAddressOptions`](/ecosystem/appkit/reference/appkit#watchtransactionsbyaddressoptions), all optional so callers can render the hook before the address is known.
+
+```ts
+type UseWatchTransactionsByAddressParameters = Partial<WatchTransactionsByAddressOptions>;
+```
+
+#### UseWatchTransactionsParameters
+
+Parameters accepted by [`useWatchTransactions`](#usewatchtransactions).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange` | <code>(update: <a href="/ecosystem/appkit/reference/appkit#transactionsupdate">TransactionsUpdate</a>) =&gt; void</code> | Callback fired on every transactions update from the streaming provider. |
+
+### UI
+
+#### BlockProps
+
+Props accepted by [`Block`](#block).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `direction` | `'row' \| 'column'` | Flex direction of the block. Defaults to `'column'`. |
+
+#### ButtonProps
+
+Props accepted by [`Button`](#button).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `size` | `ButtonSize` | Size class applied to the button. Pass `'unset'` to skip the size class entirely (no padding, no typography) — useful with `variant="unstyled"`. |
+| `borderRadius` | `ButtonBorderRadius` | Border radius token; defaults to a size-dependent value (`s` → `2xl`, `m` → `l`, `l` → `xl`). |
+| `variant` | `ButtonVariant` | Visual variant. Use `'unstyled'` to opt out of all built-in styling — the consumer is fully responsible for visuals via `className`. The Button still provides ref forwarding, `disabled`/`loading` plumbing, and `icon`/`children` rendering. |
+| `loading` | `boolean` | When true, renders a spinner instead of `icon`/`children` and disables the button. |
+| `fullWidth` | `boolean` | When true, the button stretches to fill its container width. |
+| `icon` | `ReactNode` | Optional leading icon rendered before `children` when not loading. |
+
+#### CenteredAmountInputProps
+
+Props accepted by [`CenteredAmountInput`](#centeredamountinput).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Controlled input value (decimal string). |
+| `onValueChange`\* | `(value: string) => void` | Called with the new string whenever the user edits the input. |
+| `ticker` | `string` | Optional trailing ticker label (e.g., `'TON'`). |
+| `symbol` | `string` | Optional leading currency symbol (e.g., `'$'`). |
+| `placeholder` | `string` | Placeholder shown when `value` is empty. Defaults to `'0'`. |
+| `disabled` | `boolean` | When true, the underlying `<input>` is disabled. |
+
+#### CollapsibleProps
+
+Props accepted by [`Collapsible`](#collapsible).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `open`\* | `boolean` | When true, the content is expanded; when false, it is collapsed to zero height. |
+
+#### IconProps
+
+Standard props for all icon components.
+
+Icons render an `<svg>` whose dimensions are controlled by `size`. Color is
+inherited from `currentColor`, so style icons by setting `color` on a parent.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size of the icon in pixels. Defaults to [`DEFAULT_ICON_SIZE`](#default_icon_size). |
+
+#### InputContainerProps
+
+Props accepted by [`Input.Container`](#input.container) (also used by [`Input`](#input) itself).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `size` | `InputSize` | Size token applied to the input control(s) inside: `'s' | 'm' | 'l'`. Defaults to `'m'`. |
+| `variant` | `InputVariant` | Visual variant: `'default'` paints a filled field; `'unstyled'` drops the chrome. |
+| `disabled` | `boolean` | When true, descendant input controls are disabled. |
+| `error` | `boolean` | When true, the field renders in error styling and [`Input.Caption`](#input.caption) switches to error text. |
+| `loading` | `boolean` | When true, [`Input.Input`](#input.input) renders a skeleton placeholder instead of an `<input>`. |
+| `resizable` | `boolean` | When true, [`Input.Input`](#input.input) scales its font down to fit the available width as the user types. |
+| `children`\* | `ReactNode` | Compound sub-components (header, field, control, caption). |
+
+#### InputControlProps
+
+Props accepted by [`Input.Input`](#input.input) — standard `<input>` props. Size, disabled, loading, and resizable behavior are inherited from the surrounding [`Input.Container`](#input.container).
+
+```ts
+type InputControlProps = ComponentProps<'input'>;
+```
+
+#### InputFieldProps
+
+Props accepted by [`Input.Field`](#input.field).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `children`\* | `ReactNode` | Field content — typically slots and the input control laid out horizontally. |
+
+#### InputHeaderProps
+
+Props accepted by [`Input.Header`](#input.header).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `children`\* | `ReactNode` | Header content — typically a [`Input.Title`](#input.title) and optional trailing controls. |
+
+#### InputSlotProps
+
+Props accepted by [`Input.Slot`](#input.slot).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `side` | `'left' \| 'right'` | Which edge of the field the slot adheres to. |
+
+#### LogoProps
+
+Props accepted by [`Logo`](#logo).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Square size in pixels for the rendered logo. Defaults to `30`. |
+| `src` | `string` | Image URL to render. While loading or on failure, the fallback is shown. |
+| `alt` | `string` | Alt text passed to the underlying `<img>`. When `fallback` is not provided, its first character is shown as the fallback; if both are missing, no fallback is rendered. |
+| `fallback` | `string` | Text shown in place of the image when `src` fails or is missing (defaults to the first character of `alt`). |
+
+#### LogoWithNetworkProps
+
+Props accepted by [`LogoWithNetwork`](#logowithnetwork).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `size` | `number` | Size of the main logo in pixels. Defaults to `30`. The network badge is sized to `size * 0.4`. |
+| `src` | `string` | Image source for the main logo. |
+| `alt` | `string` | Alt text for the main logo. |
+| `fallback` | `string` | Fallback text shown when the main logo image fails or is missing. |
+| `networkSrc` | `string` | Image source for the network badge overlay. When omitted, the badge is not rendered. |
+| `networkAlt` | `string` | Alt text for the network badge. |
+
+#### ModalProps
+
+Props accepted by [`Modal`](#modal).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `open` | `boolean` | Controlled open state. |
+| `onOpenChange` | `(open: boolean) => void` | Called whenever the open state changes (e.g., via the close button, overlay click, or `Escape`). |
+| `title` | `string` | Optional title rendered in the modal header. |
+| `children` | `ReactNode` | Modal body content. |
+| `className` | `string` | Additional class name applied to the content container. |
+| `bodyClassName` | `string` | Additional class name applied to the body container. |
+
+#### SelectContentProps
+
+Props accepted by [`Select.Content`](#select.content).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `align` | `'start' \| 'end'` | Horizontal alignment relative to the trigger. |
+| `sideOffset` | `number` | Gap between trigger and content in pixels. |
+
+#### SelectItemProps
+
+Props accepted by [`Select.Item`](#select.item).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Value committed to [`Select.Root`](#select.root) when this item is chosen. |
+| `disabled` | `boolean` | When true, the item is not selectable and is excluded from keyboard navigation. |
+
+#### SelectRootProps
+
+Props accepted by [`Select.Root`](#select.root).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value` | `string` | Controlled selected value. |
+| `defaultValue` | `string` | Initial value when uncontrolled. |
+| `onValueChange` | `(value: string) => void` | Called whenever the selected value changes. |
+| `open` | `boolean` | Controlled open state. |
+| `defaultOpen` | `boolean` | Initial open state when uncontrolled. |
+| `onOpenChange` | `(open: boolean) => void` | Called whenever the open state changes. |
+| `disabled` | `boolean` | When true, the trigger is non-interactive. |
+| `children`\* | `ReactNode` | Compound sub-components — [`Select.Trigger`](#select.trigger), [`Select.Content`](#select.content), [`Select.Item`](#select.item). |
+
+#### SelectTriggerProps
+
+Props accepted by [`Select.Trigger`](#select.trigger) — same as [`ButtonProps`](#buttonprops). The trigger inherits `disabled` from the surrounding root if set.
+
+```ts
+type SelectTriggerProps = ButtonProps;
+```
+
+#### SkeletonProps
+
+Props accepted by [`Skeleton`](#skeleton).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `width` | `string \| number` | Width of the placeholder. Accepts any valid CSS length or a number (interpreted as pixels). |
+| `height` | `string \| number` | Height of the placeholder. Accepts any valid CSS length or a number (interpreted as pixels). |
+
+#### TabsContentProps
+
+Props accepted by [`TabsContent`](#tabscontent).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Value this panel is associated with — rendered only when the parent [`Tabs`](#tabs) is on this value. |
+| `children`\* | `ReactNode` | Panel content. |
+
+#### TabsListProps
+
+Props accepted by [`TabsList`](#tabslist).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `children`\* | `ReactNode` | Tab triggers — typically one or more [`TabsTrigger`](#tabstrigger)s. |
+
+#### TabsProps
+
+Props accepted by [`Tabs`](#tabs).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value` | `string` | Controlled active tab value. |
+| `defaultValue` | `string` | Initial active tab when uncontrolled. Defaults to `''`. |
+| `onValueChange` | `(value: string) => void` | Called whenever the active tab changes. |
+| `children`\* | `ReactNode` | Compound sub-components — typically [`TabsList`](#tabslist) (with [`TabsTrigger`](#tabstrigger)s) followed by [`TabsContent`](#tabscontent)s. |
+
+#### TabsTriggerProps
+
+Props accepted by [`TabsTrigger`](#tabstrigger).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value`\* | `string` | Value committed to the parent [`Tabs`](#tabs) when this trigger is activated. |
+| `children`\* | `ReactNode` | Trigger label / content. |
+
+### Wallets
+
+#### UseAddressReturnType
+
+Return type of [`useAddress`](#useaddress) — `undefined` when no wallet is selected.
+
+```ts
+type UseAddressReturnType = string | undefined;
+```
+
+#### UseConnectParameters
+
+Parameters accepted by [`useConnect`](#useconnect) — TanStack Query mutation options (`onSuccess`, `onError`, `onMutate`, `retry`, …).
+
+```ts
+type UseConnectParameters = ConnectOptions<context>;
+```
+
+#### UseConnectReturnType
+
+Return type of [`useConnect`](#useconnect) — TanStack Query mutation result with `mutate`/`mutateAsync` and the standard companions.
+
+```ts
+type UseConnectReturnType = UseMutationReturnType<
+    ConnectData,
+    ConnectErrorType,
+    ConnectVariables,
+    context,
+    (
+        variables: ConnectVariables,
+        options?: MutateOptions<ConnectData, ConnectErrorType, ConnectVariables, context>,
+    ) => void,
+    MutateFunction<ConnectData, ConnectErrorType, ConnectVariables, context>
+>;
+```
+
+#### UseConnectedWalletsReturnType
+
+Return type of [`useConnectedWallets`](#useconnectedwallets) — same shape as [`GetConnectedWalletsReturnType`](/ecosystem/appkit/reference/appkit#getconnectedwalletsreturntype).
+
+```ts
+type UseConnectedWalletsReturnType = GetConnectedWalletsReturnType;
+```
+
+#### UseDisconnectParameters
+
+Parameters accepted by [`useDisconnect`](#usedisconnect) — TanStack Query mutation options.
+
+```ts
+type UseDisconnectParameters = DisconnectOptions<context>;
+```
+
+#### UseDisconnectReturnType
+
+Return type of [`useDisconnect`](#usedisconnect) — TanStack Query mutation result.
+
+```ts
+type UseDisconnectReturnType = UseMutationReturnType<
+    DisconnectData,
+    DisconnectErrorType,
+    DisconnectVariables,
+    context,
+    (
+        variables: DisconnectVariables,
+        options?: MutateOptions<DisconnectData, DisconnectErrorType, DisconnectVariables, context>,
+    ) => void,
+    MutateFunction<DisconnectData, DisconnectErrorType, DisconnectVariables, context>
+>;
+```
+
+#### UseSelectedWalletReturnType
+
+Return type of [`useSelectedWallet`](#useselectedwallet) — `[wallet, setWalletId]` tuple. `wallet` is the active [`WalletInterface`](/ecosystem/appkit/reference/appkit#walletinterface) (or `null`); `setWalletId` calls [`setSelectedWalletId`](/ecosystem/appkit/reference/appkit#setselectedwalletid) and emits `wallets:selection-changed`.
+
+```ts
+type UseSelectedWalletReturnType = readonly [GetSelectedWalletReturnType, (walletId: string | null) => void];
+```
+
+## Constants
+
+### Crypto Onramp
+
+#### DEFAULT_CHAINS
+
+Default mapping of CAIP-2 chain identifiers to [`ChainInfo`](#chaininfo) used by the crypto onramp widget. Consumers can override or extend this map via the `chains` prop on [`CryptoOnrampWidgetProvider`](#cryptoonrampwidgetprovider).
+
+```ts
+const DEFAULT_CHAINS = {
+    'eip155:1': { name: 'Ethereum' },
+    'eip155:10': { name: 'Optimism' },
+    'eip155:56': { name: 'BSC' },
+    'eip155:137': { name: 'Polygon' },
+    'eip155:8453': { name: 'Base' },
+    'eip155:42161': {
+        name: 'Arbitrum One',
+        logo: 'https://cdn.layerswap.io/layerswap/networks/arbitrum_mainnet.png',
+    },
+    'eip155:43114': { name: 'Avalanche' },
+    'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp': { name: 'Solana' },
+    'bip122:000000000019d6689c085ae165831e93': { name: 'Bitcoin' },
+};
+```
+
+### UI
+
+#### DEFAULT_ICON_SIZE
+
+Default size in pixels (24) applied to icons when `size` is not provided.
+
+```ts
+const DEFAULT_ICON_SIZE = 24;
+```
diff --git a/packages/appkit-react/src/components/shared/amount-presets/amount-presets.tsx b/packages/appkit-react/src/components/shared/amount-presets/amount-presets.tsx
index 9fa85baff..c4d3c2c3f 100644
--- a/packages/appkit-react/src/components/shared/amount-presets/amount-presets.tsx
+++ b/packages/appkit-react/src/components/shared/amount-presets/amount-presets.tsx
@@ -12,18 +12,45 @@ import clsx from 'clsx';
 import { Button } from '../../ui/button';
 import styles from './amount-presets.module.css';
 
+/**
+ * Single preset entry rendered as a button in {@link AmountPresets}.
+ *
+ * @public
+ * @category Type
+ * @section Shared
+ */
 export interface AmountPreset {
+    /** Text shown inside the button (e.g., `"25%"`, `"Max"`, `"100"`). */
     label: string;
+    /** Value passed to {@link AmountPresetsProps.onPresetSelect} when the button is clicked. */
     amount: string;
+    /** Optional custom click handler — when set, it runs instead of `onPresetSelect`. */
     onSelect?: () => void;
 }
 
+/**
+ * Props accepted by {@link AmountPresets}.
+ *
+ * @public
+ * @category Type
+ * @section Shared
+ */
 export interface AmountPresetsProps extends ComponentProps<'div'> {
+    /** Preset buttons to render, in order. */
     presets: AmountPreset[];
+    /** Optional symbol (e.g., `"$"`) prepended to each preset label. */
     currencySymbol?: string;
+    /** Called with the selected preset's `amount` unless the preset defines its own `onSelect`. */
     onPresetSelect: (value: string) => void;
 }
 
+/**
+ * Horizontal row of preset amount buttons — typically used next to an amount input to offer quick fills.
+ *
+ * @public
+ * @category Component
+ * @section Shared
+ */
 export const AmountPresets: FC<AmountPresetsProps> = ({
     presets,
     currencySymbol,
diff --git a/packages/appkit-react/src/components/shared/copy-button/copy-button.tsx b/packages/appkit-react/src/components/shared/copy-button/copy-button.tsx
index 400e0857b..ce7564235 100644
--- a/packages/appkit-react/src/components/shared/copy-button/copy-button.tsx
+++ b/packages/appkit-react/src/components/shared/copy-button/copy-button.tsx
@@ -13,13 +13,27 @@ import { CheckIcon, CopyIcon } from '../../ui/icons';
 import { useCopy } from '../../../hooks/use-copy';
 import styles from './copy-button.module.css';
 
+/**
+ * Props accepted by {@link CopyButton}.
+ *
+ * @public
+ * @category Type
+ * @section Shared
+ */
 export interface CopyButtonProps extends Omit<ComponentProps<'button'>, 'value' | 'children' | 'onClick'> {
-    /** The text written to the clipboard when the button is clicked. */
+    /** Text written to the clipboard when the button is clicked. */
     value: string;
     /** Accessible label for screen readers. */
     'aria-label': string;
 }
 
+/**
+ * Icon-only button that copies `value` to the clipboard on click and flips its icon to a checkmark for a short confirmation window.
+ *
+ * @public
+ * @category Component
+ * @section Shared
+ */
 export const CopyButton: FC<CopyButtonProps> = ({ value, className, type = 'button', ...props }) => {
     const [copied, copy] = useCopy(value);
 
diff --git a/packages/appkit-react/src/components/shared/currency-item/currency-item.tsx b/packages/appkit-react/src/components/shared/currency-item/currency-item.tsx
index 87ceef566..796d571fa 100644
--- a/packages/appkit-react/src/components/shared/currency-item/currency-item.tsx
+++ b/packages/appkit-react/src/components/shared/currency-item/currency-item.tsx
@@ -13,12 +13,25 @@ import { Logo } from '../../ui/logo';
 import type { LogoProps } from '../../ui/logo';
 import styles from './currency-item.module.css';
 
+/**
+ * Props accepted by {@link CurrencyItem} when used as a single-shot button. Passing `children` switches it into compound mode and bypasses these fields.
+ *
+ * @public
+ * @category Type
+ * @section Shared
+ */
 export interface CurrencyItemProps extends ComponentProps<'button'> {
+    /** Token symbol (e.g., `"TON"`) — also used as the icon fallback and rendered in the secondary line. */
     ticker?: string;
+    /** Human-readable token name shown as the primary line; falls back to `ticker` when absent. */
     name?: string;
+    /** Main balance value shown on the right side (already-formatted string). */
     balance?: string;
+    /** Optional secondary value (e.g., fiat equivalent) shown beneath the main balance. */
     underBalance?: string;
+    /** URL of the token logo. */
     icon?: string;
+    /** When true, renders a verified checkmark badge next to the name. */
     isVerified?: boolean;
 }
 
@@ -123,15 +136,32 @@ const CurrencyItemRoot: FC<CurrencyItemProps> = ({
     );
 };
 
+/**
+ * Compound row used inside currency/token select lists: shows a token logo, name + ticker, optional verified badge, and an optional balance / under-balance on the right. Pass top-level props for the default layout, or pass `children` made of the sub-components for full control.
+ *
+ * @public
+ * @category Component
+ * @section Shared
+ */
 export const CurrencyItem = Object.assign(CurrencyItemRoot, {
+    /** Root `<button>` wrapper — receives all native button props. */
     Container,
+    /** Token logo cell rendered as a 40px {@link Logo}. */
     Logo: LogoWrapper,
+    /** Vertical block holding the {@link Header} and {@link Ticker}. */
     Info,
+    /** Verified checkmark badge — rendered next to the name when `isVerified` is set. */
     VerifiedBadge,
+    /** Top line of `Info` (name + verified badge). */
     Header,
+    /** Primary text line — defaults to the token name, falling back to the ticker when no name is provided. */
     Name,
+    /** Secondary text line — renders the ticker and, when both ticker and name are present, appends `• {name}`. */
     Ticker,
+    /** Right-aligned column for balance values. */
     RightSide,
+    /** Primary balance number (top of `RightSide`). */
     MainBalance,
+    /** Secondary balance value (e.g., fiat) shown under `MainBalance`. */
     UnderBalance,
 });
diff --git a/packages/appkit-react/src/components/shared/currency-select-modal/currency-select-modal.tsx b/packages/appkit-react/src/components/shared/currency-select-modal/currency-select-modal.tsx
index 1bb2b8cf3..a38bcd449 100644
--- a/packages/appkit-react/src/components/shared/currency-select-modal/currency-select-modal.tsx
+++ b/packages/appkit-react/src/components/shared/currency-select-modal/currency-select-modal.tsx
@@ -16,12 +16,29 @@ import { Modal } from '../../ui/modal';
 import { SearchIcon } from '../../ui/icons';
 import styles from './currency-select-modal.module.css';
 
+/**
+ * Props accepted by {@link CurrencySelect.Search}.
+ *
+ * @public
+ * @category Type
+ * @section Shared
+ */
 export interface CurrencySelectSearchProps extends Omit<InputContainerProps, 'children'> {
+    /** Current search query. */
     searchValue: string;
+    /** Called whenever the user types in the search input. */
     onSearchChange: (value: string) => void;
+    /** Placeholder text shown when the input is empty. */
     placeholder?: string;
 }
 
+/**
+ * Search input row for the {@link CurrencySelect.Modal} — auto-focuses on mount and shows a magnifier icon.
+ *
+ * @public
+ * @category Component
+ * @section Shared
+ */
 export const CurrencySelectSearch: FC<CurrencySelectSearchProps> = ({
     searchValue,
     onSearchChange,
@@ -47,10 +64,25 @@ export const CurrencySelectSearch: FC<CurrencySelectSearchProps> = ({
     );
 };
 
+/**
+ * Props accepted by {@link CurrencySelect.ListContainer}.
+ *
+ * @public
+ * @category Type
+ * @section Shared
+ */
 export interface CurrencySelectListContainerProps extends ComponentProps<'div'> {
+    /** When true, renders the built-in empty state instead of `children`. */
     isEmpty: boolean;
 }
 
+/**
+ * Scrollable list area for {@link CurrencySelect.Modal} content; swaps `children` for a built-in empty state when `isEmpty` is true.
+ *
+ * @public
+ * @category Component
+ * @section Shared
+ */
 export const CurrencySelectListContainer: FC<CurrencySelectListContainerProps> = ({
     isEmpty,
     children,
@@ -71,26 +103,59 @@ export const CurrencySelectListContainer: FC<CurrencySelectListContainerProps> =
     );
 };
 
+/**
+ * Section header label rendered at the top of a {@link CurrencySelect.Section}.
+ *
+ * @public
+ * @category Component
+ * @section Shared
+ */
 export const CurrencySelectSectionHeader: FC<ComponentProps<'p'>> = ({ className, children, ...props }) => (
     <p className={clsx(styles.sectionHeader, className)} {...props}>
         {children}
     </p>
 );
 
+/**
+ * Container for a group of currency rows inside {@link CurrencySelect.ListContainer}.
+ *
+ * @public
+ * @category Component
+ * @section Shared
+ */
 export const CurrencySelectSection: FC<ComponentProps<'div'>> = ({ className, children, ...props }) => (
     <div className={clsx(styles.section, className)} {...props}>
         {children}
     </div>
 );
 
+/**
+ * Underlying {@link Modal} with currency-select styling — the same `open` / `onOpenChange` / `title` props as the standard modal.
+ *
+ * @public
+ * @category Component
+ * @section Shared
+ */
 export const CurrencySelectModal: FC<ModalProps> = ({ className, ...props }) => {
     return <Modal className={clsx(styles.body, className)} {...props} />;
 };
 
+/**
+ * Compound currency-select primitives — compose {@link CurrencySelect.Modal} with a {@link CurrencySelect.Search} and {@link CurrencySelect.ListContainer} of {@link CurrencySelect.Section} rows to build a custom token picker. For a ready-made implementation see {@link TokenSelectModal}.
+ *
+ * @public
+ * @category Component
+ * @section Shared
+ */
 export const CurrencySelect = {
+    /** Modal wrapper. */
     Modal: CurrencySelectModal,
+    /** Auto-focused search input row. */
     Search: CurrencySelectSearch,
+    /** Scrollable list area with built-in empty state. */
     ListContainer: CurrencySelectListContainer,
+    /** Header label rendered above a section. */
     SectionHeader: CurrencySelectSectionHeader,
+    /** Container for a group of currency rows. */
     Section: CurrencySelectSection,
 };
diff --git a/packages/appkit-react/src/components/shared/low-balance-modal/low-balance-modal.tsx b/packages/appkit-react/src/components/shared/low-balance-modal/low-balance-modal.tsx
index 68841ca9c..0114a5e66 100644
--- a/packages/appkit-react/src/components/shared/low-balance-modal/low-balance-modal.tsx
+++ b/packages/appkit-react/src/components/shared/low-balance-modal/low-balance-modal.tsx
@@ -13,21 +13,45 @@ import { Button } from '../../ui/button';
 import { useI18n } from '../../../features/settings/hooks/use-i18n';
 import styles from './low-balance-modal.module.css';
 
+/**
+ * Behavior mode for {@link LowBalanceModal} — see {@link LowBalanceModalProps.mode}.
+ *
+ * @public
+ * @category Type
+ * @section Shared
+ */
 export type LowBalanceMode = 'reduce' | 'topup';
 
+/**
+ * Props accepted by {@link LowBalanceModal}.
+ *
+ * @public
+ * @category Type
+ * @section Shared
+ */
 export interface LowBalanceModalProps {
+    /** Controls visibility of the modal. */
     open: boolean;
     /**
      * `reduce` — user can fix it by reducing the amount (shows Change/Cancel).
      * `topup`  — reducing doesn't help, user must top up TON (shows Close only).
      */
     mode: LowBalanceMode;
-    /** Required amount in TON, formatted as a decimal string (e.g. "0.423"). */
+    /** Required amount in TON, formatted as a decimal string (e.g. `"0.423"`). */
     requiredTon: string;
+    /** Called when the user clicks the primary "Change" action (only in `reduce` mode). */
     onChange: () => void;
+    /** Called when the user dismisses the modal (Cancel, Close, or backdrop click). */
     onCancel: () => void;
 }
 
+/**
+ * Modal shown when a transaction would leave insufficient TON to cover fees — adapts its body and buttons to the {@link LowBalanceMode}.
+ *
+ * @public
+ * @category Component
+ * @section Shared
+ */
 export const LowBalanceModal: FC<LowBalanceModalProps> = ({ open, mode, requiredTon, onChange, onCancel }) => {
     const { t } = useI18n();
 
diff --git a/packages/appkit-react/src/components/shared/option-switcher/option-switcher.tsx b/packages/appkit-react/src/components/shared/option-switcher/option-switcher.tsx
index 5225213bc..bcc235694 100644
--- a/packages/appkit-react/src/components/shared/option-switcher/option-switcher.tsx
+++ b/packages/appkit-react/src/components/shared/option-switcher/option-switcher.tsx
@@ -13,11 +13,27 @@ import { ChevronsIcon } from '../../ui/icons';
 import { Select } from '../../ui/select';
 import styles from './option-switcher.module.css';
 
+/**
+ * Single entry rendered as an item inside {@link OptionSwitcher}.
+ *
+ * @public
+ * @category Type
+ * @section Shared
+ */
 export interface OptionSwitcherOption {
+    /** Stable value passed back to {@link OptionSwitcherProps.onChange} when selected. */
     value: string;
+    /** Human-readable label shown in the trigger and dropdown item. */
     label: string;
 }
 
+/**
+ * Props accepted by {@link OptionSwitcher}.
+ *
+ * @public
+ * @category Type
+ * @section Shared
+ */
 export interface OptionSwitcherProps {
     /** Currently selected option value. */
     value: string | undefined;
@@ -27,11 +43,16 @@ export interface OptionSwitcherProps {
     onChange: (value: string) => void;
     /** When true, the trigger is non-interactive and dimmed. */
     disabled?: boolean;
+    /** Extra class applied to the trigger button. */
     className?: string;
 }
 
 /**
- * Compact selector used inside settings modals next to a label.
+ * Compact dropdown selector — renders the current option's label and a chevron, opening a {@link Select} popover with the remaining choices. Falls back to the raw `value` or `"—"` when no option matches.
+ *
+ * @public
+ * @category Component
+ * @section Shared
  */
 export const OptionSwitcher: FC<OptionSwitcherProps> = ({ value, options, onChange, disabled, className }) => {
     const current = options.find((option) => option.value === value);
diff --git a/packages/appkit-react/src/components/shared/settings-button/settings-button.tsx b/packages/appkit-react/src/components/shared/settings-button/settings-button.tsx
index b87a55949..f12b0aa40 100644
--- a/packages/appkit-react/src/components/shared/settings-button/settings-button.tsx
+++ b/packages/appkit-react/src/components/shared/settings-button/settings-button.tsx
@@ -13,10 +13,25 @@ import { Button } from '../../ui/button';
 import { SlidersIcon } from '../../ui/icons';
 import styles from './settings-button.module.css';
 
+/**
+ * Props accepted by {@link SettingsButton} — extends the base {@link Button} props.
+ *
+ * @public
+ * @category Type
+ * @section Shared
+ */
 export interface SettingsButtonProps extends ComponentProps<typeof Button> {
+    /** Click handler — typically used to open a settings modal. */
     onClick?: () => void;
 }
 
+/**
+ * Icon-only secondary button with a sliders icon — drop-in trigger for opening settings panels.
+ *
+ * @public
+ * @category Component
+ * @section Shared
+ */
 export const SettingsButton: FC<SettingsButtonProps> = ({ onClick, className, ...props }) => {
     return (
         <Button
diff --git a/packages/appkit-react/src/components/shared/token-select-modal/token-select-modal.tsx b/packages/appkit-react/src/components/shared/token-select-modal/token-select-modal.tsx
index 4f803fb45..536aa0916 100644
--- a/packages/appkit-react/src/components/shared/token-select-modal/token-select-modal.tsx
+++ b/packages/appkit-react/src/components/shared/token-select-modal/token-select-modal.tsx
@@ -15,34 +15,85 @@ import type { AppkitUIToken } from '../../../types/appkit-ui-token';
 import { useI18n } from '../../../features/settings/hooks/use-i18n';
 import { filterTokens, groupTokenSections } from './utils';
 
+/**
+ * Minimal shape every token in {@link TokenSelectModal} must satisfy. Callers may use richer types (e.g., `AppkitUIToken`) — `TokenBase` only fixes the fields the modal reads.
+ *
+ * @public
+ * @category Type
+ * @section Shared
+ */
 export interface TokenBase {
+    /** Stable identifier used to match tokens against {@link TokenSectionConfig.ids}. */
     id: string;
+    /** Ticker (e.g., `"TON"`) — used for display and search matching. */
     symbol: string;
+    /** Human-readable name — used for display and search matching. */
     name: string;
+    /** Token contract address — used for exact-address search matching and as the React `key`. */
     address: string;
+    /** Optional logo URL. */
     logo?: string;
 }
 
+/**
+ * Pre-grouped section of tokens as it appears inside {@link TokenSelectModal}.
+ *
+ * @public
+ * @category Type
+ * @section Shared
+ */
 export interface TokenSection<T extends TokenBase = AppkitUIToken> {
+    /** Header label rendered above the section; falsy values hide the header. */
     title: string;
+    /** Tokens belonging to this section, in render order. */
     tokens: T[];
 }
 
+/**
+ * Configuration that maps token `id`s to a named section in {@link TokenSelectModal}; tokens not covered are placed in an "Other tokens" trailing section.
+ *
+ * @public
+ * @category Type
+ * @section Shared
+ */
 export interface TokenSectionConfig {
+    /** Section header label. */
     title: string;
+    /** {@link TokenBase.id} values to include in this section, in render order. */
     ids: string[];
 }
 
+/**
+ * Props accepted by {@link TokenSelectModal}.
+ *
+ * @public
+ * @category Type
+ * @section Shared
+ */
 export interface TokenSelectModalProps<T extends TokenBase = AppkitUIToken> {
+    /** Controls modal visibility. */
     open: boolean;
+    /** Called when the modal is dismissed (selection, backdrop click, or escape). */
     onClose: () => void;
+    /** Full set of tokens available for selection and search. */
     tokens: T[];
+    /** Optional sectioning rules; when omitted, all tokens render as a single untitled section. */
     tokenSections?: TokenSectionConfig[];
+    /** Called with the picked token; the modal closes and resets its search on selection. */
     onSelect: (token: T) => void;
+    /** Modal header title. */
     title: string;
+    /** Placeholder shown inside the search input. */
     searchPlaceholder?: string;
 }
 
+/**
+ * Ready-made token picker modal — renders a search field and a sectioned list of {@link CurrencyItem} rows backed by {@link CurrencySelect}. Search matches by symbol, name, or exact address; selecting a row fires `onSelect`, closes the modal, and resets the search.
+ *
+ * @public
+ * @category Component
+ * @section Shared
+ */
 export const TokenSelectModal = <T extends TokenBase = AppkitUIToken>({
     open,
     onClose,
diff --git a/packages/appkit-react/src/components/shared/token-selector/token-selector.tsx b/packages/appkit-react/src/components/shared/token-selector/token-selector.tsx
index 20331f5f2..8e7e816b5 100644
--- a/packages/appkit-react/src/components/shared/token-selector/token-selector.tsx
+++ b/packages/appkit-react/src/components/shared/token-selector/token-selector.tsx
@@ -15,16 +15,33 @@ import type { ButtonProps } from '../../ui/button';
 import { Logo } from '../../ui/logo';
 import { LogoWithNetwork } from '../../ui/logo-with-network';
 
+/**
+ * Props accepted by {@link TokenSelector} — extends the base {@link Button} props.
+ *
+ * @public
+ * @category Type
+ * @section Shared
+ */
 export interface TokenSelectorProps extends ButtonProps {
+    /** Label shown next to the icon — typically the token symbol. */
     title: string;
+    /** Token logo URL. */
     icon?: string;
+    /** Single-character fallback used when `icon` fails to load; defaults to the first character of `title`. */
     iconFallback?: string;
-    /** When provided, renders a network badge overlay on the icon */
+    /** When provided, renders a network badge overlay on the icon. */
     networkIcon?: string;
-    /** Hide chevron and suppress click handling — use when there's nothing to pick */
+    /** Hide chevron and suppress click handling — use when there's nothing to pick. */
     readOnly?: boolean;
 }
 
+/**
+ * Compact pill button used as the trigger for a token picker — shows the token icon (optionally with a network badge), its symbol, and a chevron unless `readOnly` is set.
+ *
+ * @public
+ * @category Component
+ * @section Shared
+ */
 export const TokenSelector: FC<TokenSelectorProps> = ({
     title,
     icon,
diff --git a/packages/appkit-react/src/components/ui/block/block.tsx b/packages/appkit-react/src/components/ui/block/block.tsx
index 54f5ba6e9..d8d2238eb 100644
--- a/packages/appkit-react/src/components/ui/block/block.tsx
+++ b/packages/appkit-react/src/components/ui/block/block.tsx
@@ -11,10 +11,25 @@ import clsx from 'clsx';
 
 import styles from './block.module.css';
 
+/**
+ * Props accepted by {@link Block}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface BlockProps extends ComponentProps<'div'> {
+    /** Flex direction of the block. Defaults to `'column'`. */
     direction?: 'row' | 'column';
 }
 
+/**
+ * Flex container primitive — renders a `<div>` that lays its children out vertically (`'column'`) or horizontally (`'row'`).
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const Block: FC<BlockProps> = ({ className, direction = 'column', ...props }) => {
     return <div className={clsx(styles.block, direction === 'row' && styles.row, className)} {...props} />;
 };
diff --git a/packages/appkit-react/src/components/ui/button/button.tsx b/packages/appkit-react/src/components/ui/button/button.tsx
index 5b868b76d..22653502d 100644
--- a/packages/appkit-react/src/components/ui/button/button.tsx
+++ b/packages/appkit-react/src/components/ui/button/button.tsx
@@ -12,16 +12,47 @@ import clsx from 'clsx';
 
 import styles from './button.module.css';
 
+/**
+ * Size token for {@link Button}: `'s' | 'm' | 'l' | 'unset'`. `'unset'` skips the size class entirely.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export type ButtonSize = 's' | 'm' | 'l' | 'unset';
+
+/**
+ * Border-radius token for {@link Button}: `'s' | 'm' | 'l' | 'xl' | '2xl' | 'full'`.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export type ButtonBorderRadius = 's' | 'm' | 'l' | 'xl' | '2xl' | 'full';
+
+/**
+ * Visual variant for {@link Button}: `'fill' | 'secondary' | 'bezeled' | 'gray' | 'ghost' | 'unstyled'`.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export type ButtonVariant = 'fill' | 'secondary' | 'bezeled' | 'gray' | 'ghost' | 'unstyled';
 
+/**
+ * Props accepted by {@link Button}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface ButtonProps extends ComponentProps<'button'> {
     /**
      * Size class applied to the button. Pass `'unset'` to skip the size class
      * entirely (no padding, no typography) — useful with `variant="unstyled"`.
      */
     size?: ButtonSize;
+    /** Border radius token; defaults to a size-dependent value (`s` → `2xl`, `m` → `l`, `l` → `xl`). */
     borderRadius?: ButtonBorderRadius;
     /**
      * Visual variant. Use `'unstyled'` to opt out of all built-in styling —
@@ -30,8 +61,11 @@ export interface ButtonProps extends ComponentProps<'button'> {
      * and `icon`/`children` rendering.
      */
     variant?: ButtonVariant;
+    /** When true, renders a spinner instead of `icon`/`children` and disables the button. */
     loading?: boolean;
+    /** When true, the button stretches to fill its container width. */
     fullWidth?: boolean;
+    /** Optional leading icon rendered before `children` when not loading. */
     icon?: ReactNode;
 }
 
@@ -50,6 +84,13 @@ const RADIUS_CLASS: Record<ButtonBorderRadius, string> = {
     full: 'radiusFull',
 };
 
+/**
+ * Themed `<button>` with size, border-radius, and variant tokens. Renders an optional leading `icon`, swaps content for a spinner while `loading`, and is disabled whenever `disabled` or `loading` is true.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
     (
         {
diff --git a/packages/appkit-react/src/components/ui/centered-amount-input/centered-amount-input.tsx b/packages/appkit-react/src/components/ui/centered-amount-input/centered-amount-input.tsx
index c30e497f2..312aaf6a7 100644
--- a/packages/appkit-react/src/components/ui/centered-amount-input/centered-amount-input.tsx
+++ b/packages/appkit-react/src/components/ui/centered-amount-input/centered-amount-input.tsx
@@ -14,15 +14,35 @@ import styles from './centered-amount-input.module.css';
 
 const MIN_FONT_SCALE = 0.5;
 
+/**
+ * Props accepted by {@link CenteredAmountInput}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface CenteredAmountInputProps extends ComponentProps<'div'> {
+    /** Controlled input value (decimal string). */
     value: string;
+    /** Called with the new string whenever the user edits the input. */
     onValueChange: (value: string) => void;
+    /** Optional trailing ticker label (e.g., `'TON'`). */
     ticker?: string;
+    /** Optional leading currency symbol (e.g., `'$'`). */
     symbol?: string;
+    /** Placeholder shown when `value` is empty. Defaults to `'0'`. */
     placeholder?: string;
+    /** When true, the underlying `<input>` is disabled. */
     disabled?: boolean;
 }
 
+/**
+ * Center-aligned, auto-resizing amount input with optional leading symbol and trailing ticker. Scales the font down to fit the container when the rendered text overflows, and clicking the wrapper focuses the input.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const CenteredAmountInput: FC<CenteredAmountInputProps> = ({
     value,
     onValueChange,
diff --git a/packages/appkit-react/src/components/ui/collapsible/collapsible.tsx b/packages/appkit-react/src/components/ui/collapsible/collapsible.tsx
index bce384715..14b578a6d 100644
--- a/packages/appkit-react/src/components/ui/collapsible/collapsible.tsx
+++ b/packages/appkit-react/src/components/ui/collapsible/collapsible.tsx
@@ -11,10 +11,25 @@ import type { FC, ComponentProps } from 'react';
 
 import styles from './collapsible.module.css';
 
+/**
+ * Props accepted by {@link Collapsible}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface CollapsibleProps extends ComponentProps<'div'> {
+    /** When true, the content is expanded; when false, it is collapsed to zero height. */
     open: boolean;
 }
 
+/**
+ * Animated collapsible container — transitions its height between `0` and the content's natural height when `open` toggles. Sets `aria-hidden` to mirror the open state.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const Collapsible: FC<CollapsibleProps> = ({ open, children, ...props }) => {
     const contentRef = useRef<HTMLDivElement>(null);
     const [height, setHeight] = useState<number | undefined>(open ? undefined : 0);
diff --git a/packages/appkit-react/src/components/ui/icons/check-icon.tsx b/packages/appkit-react/src/components/ui/icons/check-icon.tsx
index de9f70b0c..b48e585d0 100644
--- a/packages/appkit-react/src/components/ui/icons/check-icon.tsx
+++ b/packages/appkit-react/src/components/ui/icons/check-icon.tsx
@@ -11,6 +11,13 @@ import type { FC } from 'react';
 import { DEFAULT_ICON_SIZE } from './types';
 import type { IconProps } from './types';
 
+/**
+ * Checkmark icon — a single stroked tick.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const CheckIcon: FC<IconProps> = ({ size = DEFAULT_ICON_SIZE, ...props }) => (
     <svg
         width={size}
diff --git a/packages/appkit-react/src/components/ui/icons/chevron-down-icon.tsx b/packages/appkit-react/src/components/ui/icons/chevron-down-icon.tsx
index b29ecc8aa..971c71031 100644
--- a/packages/appkit-react/src/components/ui/icons/chevron-down-icon.tsx
+++ b/packages/appkit-react/src/components/ui/icons/chevron-down-icon.tsx
@@ -11,6 +11,13 @@ import type { FC } from 'react';
 import { DEFAULT_ICON_SIZE } from './types';
 import type { IconProps } from './types';
 
+/**
+ * Downward-pointing chevron icon — typically used to indicate expandable content.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const ChevronDownIcon: FC<IconProps> = ({ size = DEFAULT_ICON_SIZE, ...props }) => (
     <svg
         width={size}
diff --git a/packages/appkit-react/src/components/ui/icons/chevrons-icon.tsx b/packages/appkit-react/src/components/ui/icons/chevrons-icon.tsx
index 27e037621..cfdcd9238 100644
--- a/packages/appkit-react/src/components/ui/icons/chevrons-icon.tsx
+++ b/packages/appkit-react/src/components/ui/icons/chevrons-icon.tsx
@@ -11,6 +11,13 @@ import type { FC } from 'react';
 import { DEFAULT_ICON_SIZE } from './types';
 import type { IconProps } from './types';
 
+/**
+ * Stacked up/down chevrons icon — used to signal select/dropdown affordance.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const ChevronsIcon: FC<IconProps> = ({ size = DEFAULT_ICON_SIZE, ...props }) => (
     <svg
         width={size}
diff --git a/packages/appkit-react/src/components/ui/icons/close-icon.tsx b/packages/appkit-react/src/components/ui/icons/close-icon.tsx
index 3fc3e9a68..6351f32f9 100644
--- a/packages/appkit-react/src/components/ui/icons/close-icon.tsx
+++ b/packages/appkit-react/src/components/ui/icons/close-icon.tsx
@@ -11,6 +11,13 @@ import type { FC } from 'react';
 import { DEFAULT_ICON_SIZE } from './types';
 import type { IconProps } from './types';
 
+/**
+ * Close (X) icon — used for dismiss buttons and modal close affordances.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const CloseIcon: FC<IconProps> = ({ size = DEFAULT_ICON_SIZE, ...props }) => (
     <svg
         width={size}
diff --git a/packages/appkit-react/src/components/ui/icons/copy-icon.tsx b/packages/appkit-react/src/components/ui/icons/copy-icon.tsx
index cb7413c5a..8ec05fb5c 100644
--- a/packages/appkit-react/src/components/ui/icons/copy-icon.tsx
+++ b/packages/appkit-react/src/components/ui/icons/copy-icon.tsx
@@ -11,6 +11,13 @@ import type { FC } from 'react';
 import { DEFAULT_ICON_SIZE } from './types';
 import type { IconProps } from './types';
 
+/**
+ * Copy icon — two overlapping rectangles indicating clipboard copy.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const CopyIcon: FC<IconProps> = ({ size = DEFAULT_ICON_SIZE, ...props }) => (
     <svg
         width={size}
diff --git a/packages/appkit-react/src/components/ui/icons/failed-icon.tsx b/packages/appkit-react/src/components/ui/icons/failed-icon.tsx
index 0d7aeb3f2..51ac56e48 100644
--- a/packages/appkit-react/src/components/ui/icons/failed-icon.tsx
+++ b/packages/appkit-react/src/components/ui/icons/failed-icon.tsx
@@ -11,6 +11,13 @@ import type { FC } from 'react';
 import { DEFAULT_ICON_SIZE } from './types';
 import type { IconProps } from './types';
 
+/**
+ * Failure icon — a circle with an X, used for error and failed-transaction states.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const FailedIcon: FC<IconProps> = ({ size = DEFAULT_ICON_SIZE, ...props }) => (
     <svg
         width={size}
diff --git a/packages/appkit-react/src/components/ui/icons/flip-icon.tsx b/packages/appkit-react/src/components/ui/icons/flip-icon.tsx
index 59a700752..7df2f4f06 100644
--- a/packages/appkit-react/src/components/ui/icons/flip-icon.tsx
+++ b/packages/appkit-react/src/components/ui/icons/flip-icon.tsx
@@ -11,6 +11,13 @@ import type { FC } from 'react';
 import { DEFAULT_ICON_SIZE } from './types';
 import type { IconProps } from './types';
 
+/**
+ * Flip / swap icon — two opposing arrows used for swap and direction-toggle actions.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const FlipIcon: FC<IconProps> = ({ size = DEFAULT_ICON_SIZE, ...props }) => (
     <svg
         width={size}
diff --git a/packages/appkit-react/src/components/ui/icons/image-icon.tsx b/packages/appkit-react/src/components/ui/icons/image-icon.tsx
index 66c0e8f4d..d572e8809 100644
--- a/packages/appkit-react/src/components/ui/icons/image-icon.tsx
+++ b/packages/appkit-react/src/components/ui/icons/image-icon.tsx
@@ -11,6 +11,13 @@ import type { FC } from 'react';
 import { DEFAULT_ICON_SIZE } from './types';
 import type { IconProps } from './types';
 
+/**
+ * Image / picture placeholder icon — used as a fallback for missing media.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const ImageIcon: FC<IconProps> = ({ size = DEFAULT_ICON_SIZE, ...props }) => (
     <svg
         width={size}
diff --git a/packages/appkit-react/src/components/ui/icons/search-icon.tsx b/packages/appkit-react/src/components/ui/icons/search-icon.tsx
index e0351c4a5..358b8a17e 100644
--- a/packages/appkit-react/src/components/ui/icons/search-icon.tsx
+++ b/packages/appkit-react/src/components/ui/icons/search-icon.tsx
@@ -11,6 +11,13 @@ import type { FC } from 'react';
 import { DEFAULT_ICON_SIZE } from './types';
 import type { IconProps } from './types';
 
+/**
+ * Magnifying-glass search icon.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const SearchIcon: FC<IconProps> = ({ size = DEFAULT_ICON_SIZE, ...props }) => (
     <svg
         width={size}
diff --git a/packages/appkit-react/src/components/ui/icons/sliders-icon.tsx b/packages/appkit-react/src/components/ui/icons/sliders-icon.tsx
index b7e19310b..60eb64875 100644
--- a/packages/appkit-react/src/components/ui/icons/sliders-icon.tsx
+++ b/packages/appkit-react/src/components/ui/icons/sliders-icon.tsx
@@ -11,6 +11,13 @@ import type { FC } from 'react';
 import { DEFAULT_ICON_SIZE } from './types';
 import type { IconProps } from './types';
 
+/**
+ * Sliders / settings icon — two horizontal tracks with adjustable handles.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const SlidersIcon: FC<IconProps> = ({ size = DEFAULT_ICON_SIZE, ...props }) => (
     <svg
         width={size}
diff --git a/packages/appkit-react/src/components/ui/icons/spinner-icon.tsx b/packages/appkit-react/src/components/ui/icons/spinner-icon.tsx
index cdc180b98..d28a2360b 100644
--- a/packages/appkit-react/src/components/ui/icons/spinner-icon.tsx
+++ b/packages/appkit-react/src/components/ui/icons/spinner-icon.tsx
@@ -11,6 +11,13 @@ import type { FC } from 'react';
 import { DEFAULT_ICON_SIZE } from './types';
 import type { IconProps } from './types';
 
+/**
+ * Loading spinner icon — a three-quarter circle stroke. Animation must be applied via CSS by the caller.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const SpinnerIcon: FC<IconProps> = ({ size = DEFAULT_ICON_SIZE, ...props }) => (
     <svg
         width={size}
diff --git a/packages/appkit-react/src/components/ui/icons/success-icon.tsx b/packages/appkit-react/src/components/ui/icons/success-icon.tsx
index d09427208..122e547a6 100644
--- a/packages/appkit-react/src/components/ui/icons/success-icon.tsx
+++ b/packages/appkit-react/src/components/ui/icons/success-icon.tsx
@@ -11,6 +11,13 @@ import type { FC } from 'react';
 import { DEFAULT_ICON_SIZE } from './types';
 import type { IconProps } from './types';
 
+/**
+ * Success icon — a circle with an inner checkmark for confirmation states.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const SuccessIcon: FC<IconProps> = ({ size = DEFAULT_ICON_SIZE, ...props }) => (
     <svg
         width={size}
diff --git a/packages/appkit-react/src/components/ui/icons/ton-icon.tsx b/packages/appkit-react/src/components/ui/icons/ton-icon.tsx
index c0be8c16f..554df2ff7 100644
--- a/packages/appkit-react/src/components/ui/icons/ton-icon.tsx
+++ b/packages/appkit-react/src/components/ui/icons/ton-icon.tsx
@@ -11,6 +11,13 @@ import type { FC } from 'react';
 import { DEFAULT_ICON_SIZE } from './types';
 import type { IconProps } from './types';
 
+/**
+ * TON brand diamond glyph — solid, inherits color from `currentColor`.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const TonIcon: FC<IconProps> = ({ size = DEFAULT_ICON_SIZE, ...props }) => (
     <svg
         width={size}
@@ -28,6 +35,13 @@ export const TonIcon: FC<IconProps> = ({ size = DEFAULT_ICON_SIZE, ...props }) =
     </svg>
 );
 
+/**
+ * TON brand glyph rendered inside a filled circle, using the TON brand color token.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const TonIconCircle: FC<IconProps> = ({ size = DEFAULT_ICON_SIZE, ...props }) => (
     <svg
         width={size}
diff --git a/packages/appkit-react/src/components/ui/icons/types.ts b/packages/appkit-react/src/components/ui/icons/types.ts
index 43e24564d..c029781d4 100644
--- a/packages/appkit-react/src/components/ui/icons/types.ts
+++ b/packages/appkit-react/src/components/ui/icons/types.ts
@@ -13,10 +13,21 @@ import type { ComponentProps } from 'react';
  *
  * Icons render an `<svg>` whose dimensions are controlled by `size`. Color is
  * inherited from `currentColor`, so style icons by setting `color` on a parent.
+ *
+ * @public
+ * @category Type
+ * @section UI
  */
 export interface IconProps extends Omit<ComponentProps<'svg'>, 'width' | 'height'> {
+    /** Square size of the icon in pixels. Defaults to {@link DEFAULT_ICON_SIZE}. */
     size?: number;
 }
 
-/** Default size in pixels for all icons. Override via the `size` prop. */
+/**
+ * Default size in pixels (24) applied to icons when `size` is not provided.
+ *
+ * @public
+ * @category Constants
+ * @section UI
+ */
 export const DEFAULT_ICON_SIZE = 24;
diff --git a/packages/appkit-react/src/components/ui/icons/verified-icon.tsx b/packages/appkit-react/src/components/ui/icons/verified-icon.tsx
index a339e84f4..1aafbb7c6 100644
--- a/packages/appkit-react/src/components/ui/icons/verified-icon.tsx
+++ b/packages/appkit-react/src/components/ui/icons/verified-icon.tsx
@@ -11,6 +11,13 @@ import type { FC } from 'react';
 import { DEFAULT_ICON_SIZE } from './types';
 import type { IconProps } from './types';
 
+/**
+ * Verified badge icon — scalloped seal with an inner checkmark.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const VerifiedIcon: FC<IconProps> = ({ size = DEFAULT_ICON_SIZE, ...props }) => (
     <svg
         width={size}
diff --git a/packages/appkit-react/src/components/ui/info-block/info-block.tsx b/packages/appkit-react/src/components/ui/info-block/info-block.tsx
index 47b287d9e..ae6cbc1b6 100644
--- a/packages/appkit-react/src/components/ui/info-block/info-block.tsx
+++ b/packages/appkit-react/src/components/ui/info-block/info-block.tsx
@@ -37,11 +37,24 @@ const ValueSkeleton: FC<SkeletonProps> = ({ width = 80, height = '1lh', ...props
     return <Skeleton width={width} height={height} {...props} />;
 };
 
+/**
+ * Compound component for rendering a stacked list of label/value rows (e.g., transaction details, settings summaries). Sub-components forward extra props to the underlying DOM element so callers can layer custom classes and handlers.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const InfoBlock = {
+    /** Outer wrapper — vertical container that hosts the rows. */
     Container,
+    /** Horizontal row that pairs a label with a value. */
     Row,
+    /** Label cell — typically the muted descriptor on the left. */
     Label,
+    /** Value cell — typically the emphasized content on the right. */
     Value,
+    /** Skeleton placeholder for a {@link InfoBlock.Label} while data is loading. Defaults to `width=64`, `height='1lh'`. */
     LabelSkeleton,
+    /** Skeleton placeholder for a {@link InfoBlock.Value} while data is loading. Defaults to `width=80`, `height='1lh'`. */
     ValueSkeleton,
 };
diff --git a/packages/appkit-react/src/components/ui/input/input.tsx b/packages/appkit-react/src/components/ui/input/input.tsx
index 98b99b081..b099dbc4a 100644
--- a/packages/appkit-react/src/components/ui/input/input.tsx
+++ b/packages/appkit-react/src/components/ui/input/input.tsx
@@ -36,13 +36,27 @@ const useInputContext = () => {
     return context;
 };
 
+/**
+ * Props accepted by {@link Input.Container} (also used by {@link Input} itself).
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface InputContainerProps extends ComponentProps<'div'> {
+    /** Size token applied to the input control(s) inside: `'s' | 'm' | 'l'`. Defaults to `'m'`. */
     size?: InputSize;
+    /** Visual variant: `'default'` paints a filled field; `'unstyled'` drops the chrome. */
     variant?: InputVariant;
+    /** When true, descendant input controls are disabled. */
     disabled?: boolean;
+    /** When true, the field renders in error styling and {@link Input.Caption} switches to error text. */
     error?: boolean;
+    /** When true, {@link Input.Input} renders a skeleton placeholder instead of an `<input>`. */
     loading?: boolean;
+    /** When true, {@link Input.Input} scales its font down to fit the available width as the user types. */
     resizable?: boolean;
+    /** Compound sub-components (header, field, control, caption). */
     children: ReactNode;
 }
 
@@ -81,7 +95,15 @@ const Container: FC<InputContainerProps> = ({
     );
 };
 
+/**
+ * Props accepted by {@link Input.Header}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface InputHeaderProps extends ComponentProps<'div'> {
+    /** Header content — typically a {@link Input.Title} and optional trailing controls. */
     children: ReactNode;
 }
 
@@ -97,7 +119,15 @@ const Title: FC<ComponentProps<'span'>> = ({ className, children, ...props }) =>
     </span>
 );
 
+/**
+ * Props accepted by {@link Input.Field}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface InputFieldProps extends ComponentProps<'div'> {
+    /** Field content — typically slots and the input control laid out horizontally. */
     children: ReactNode;
 }
 
@@ -107,7 +137,15 @@ const Field: FC<InputFieldProps> = ({ className, children, ...props }) => (
     </div>
 );
 
+/**
+ * Props accepted by {@link Input.Slot}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface InputSlotProps extends ComponentProps<'div'> {
+    /** Which edge of the field the slot adheres to. */
     side?: 'left' | 'right';
 }
 
@@ -117,6 +155,13 @@ const Slot: FC<InputSlotProps> = ({ side, className, children, ...props }) => (
     </div>
 );
 
+/**
+ * Props accepted by {@link Input.Input} — standard `<input>` props. Size, disabled, loading, and resizable behavior are inherited from the surrounding {@link Input.Container}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export type InputControlProps = ComponentProps<'input'>;
 
 const InputControl: FC<InputControlProps> = ({ className, disabled: propsDisabled, onChange, ...props }) => {
@@ -183,12 +228,26 @@ const Caption: FC<ComponentProps<'span'>> = ({ className, children, ...props })
     );
 };
 
+/**
+ * Compound text-input component. Use the default export as the outer wrapper (it is the {@link Input.Container}) and compose sub-components for the header, field, slots, control, and caption. State flags (`disabled`, `error`, `loading`, `resizable`, `size`) live on the container and are read by the inner control via context.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const Input = Object.assign(Container, {
+    /** Outer wrapper that provides input context (size, variant, disabled, error, loading, resizable). */
     Container,
+    /** Header row above the field — holds the title and optional trailing controls. */
     Header,
+    /** Title text shown inside {@link Input.Header}. */
     Title,
+    /** Horizontal row that holds slots and the input control. */
     Field,
+    /** Side-anchored slot used for adornments such as icons or buttons. */
     Slot,
+    /** The actual `<input>` control; respects context flags and reads its size/variant from {@link Input.Container}. */
     Input: InputControl,
+    /** Caption / helper text below the field; switches to error styling when the container has `error` set. */
     Caption,
 });
diff --git a/packages/appkit-react/src/components/ui/logo-with-network/logo-with-network.tsx b/packages/appkit-react/src/components/ui/logo-with-network/logo-with-network.tsx
index c62f53c74..c48457e9e 100644
--- a/packages/appkit-react/src/components/ui/logo-with-network/logo-with-network.tsx
+++ b/packages/appkit-react/src/components/ui/logo-with-network/logo-with-network.tsx
@@ -13,21 +13,35 @@ import clsx from 'clsx';
 import { Logo } from '../logo';
 import styles from './logo-with-network.module.css';
 
+/**
+ * Props accepted by {@link LogoWithNetwork}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface LogoWithNetworkProps extends ComponentPropsWithoutRef<'span'> {
-    /** Size of the main logo in pixels */
+    /** Size of the main logo in pixels. Defaults to `30`. The network badge is sized to `size * 0.4`. */
     size?: number;
-    /** Image source for the main logo */
+    /** Image source for the main logo. */
     src?: string;
-    /** Alt text for the main logo */
+    /** Alt text for the main logo. */
     alt?: string;
-    /** Fallback text for the main logo */
+    /** Fallback text shown when the main logo image fails or is missing. */
     fallback?: string;
-    /** Image source for the network badge */
+    /** Image source for the network badge overlay. When omitted, the badge is not rendered. */
     networkSrc?: string;
-    /** Alt text for the network badge */
+    /** Alt text for the network badge. */
     networkAlt?: string;
 }
 
+/**
+ * Token logo with an overlaid network badge — wraps {@link Logo} and renders a smaller secondary logo as a corner badge to indicate which network the asset belongs to.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const LogoWithNetwork = forwardRef<ComponentRef<'span'>, LogoWithNetworkProps>(
     ({ size = 30, src, alt, fallback, networkSrc, networkAlt, className, ...props }, ref) => {
         return (
diff --git a/packages/appkit-react/src/components/ui/logo/logo.tsx b/packages/appkit-react/src/components/ui/logo/logo.tsx
index 1a2bf3c04..d28beea21 100644
--- a/packages/appkit-react/src/components/ui/logo/logo.tsx
+++ b/packages/appkit-react/src/components/ui/logo/logo.tsx
@@ -86,13 +86,31 @@ const LogoFallback = forwardRef<ComponentRef<'span'>, LogoFallbackProps>(({ dela
 
 LogoFallback.displayName = 'LogoFallback';
 
+/**
+ * Props accepted by {@link Logo}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface LogoProps extends ComponentPropsWithoutRef<'span'> {
+    /** Square size in pixels for the rendered logo. Defaults to `30`. */
     size?: number;
+    /** Image URL to render. While loading or on failure, the fallback is shown. */
     src?: string;
+    /** Alt text passed to the underlying `<img>`. When `fallback` is not provided, its first character is shown as the fallback; if both are missing, no fallback is rendered. */
     alt?: string;
+    /** Text shown in place of the image when `src` fails or is missing (defaults to the first character of `alt`). */
     fallback?: string;
 }
 
+/**
+ * Square logo / avatar primitive — renders an `<img>` when `src` loads successfully, otherwise shows a text fallback (after a brief delay to avoid flicker). Useful for token icons, wallet avatars, and project logos.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const Logo = forwardRef<ComponentRef<'span'>, LogoProps>(({ size = 30, src, alt, fallback, ...props }, ref) => {
     return (
         <LogoRoot
diff --git a/packages/appkit-react/src/components/ui/modal/modal.tsx b/packages/appkit-react/src/components/ui/modal/modal.tsx
index d090e4dd6..69bf08a70 100644
--- a/packages/appkit-react/src/components/ui/modal/modal.tsx
+++ b/packages/appkit-react/src/components/ui/modal/modal.tsx
@@ -13,33 +13,35 @@ import { Dialog } from '../dialog';
 import { CloseIcon } from '../icons';
 import styles from './modal.module.css';
 
+/**
+ * Props accepted by {@link Modal}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface ModalProps {
-    /**
-     * Controlled open state.
-     */
+    /** Controlled open state. */
     open?: boolean;
-    /**
-     * Event handler called when the open state changes.
-     */
+    /** Called whenever the open state changes (e.g., via the close button, overlay click, or `Escape`). */
     onOpenChange?: (open: boolean) => void;
-    /**
-     * Modal title.
-     */
+    /** Optional title rendered in the modal header. */
     title?: string;
-    /**
-     * Modal content.
-     */
+    /** Modal body content. */
     children?: ReactNode;
-    /**
-     * Additional class name for the content container.
-     */
+    /** Additional class name applied to the content container. */
     className?: string;
-    /**
-     * Additional class name for the body container.
-     */
+    /** Additional class name applied to the body container. */
     bodyClassName?: string;
 }
 
+/**
+ * Centered modal dialog with a header (optional title + close button) and a scrollable body. Clicking the overlay closes the modal; clicks on the content do not bubble through.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const Modal: FC<ModalProps> = ({ open, onOpenChange, title, children, className, bodyClassName }) => {
     return (
         <Dialog.Root open={open} onOpenChange={onOpenChange}>
diff --git a/packages/appkit-react/src/components/ui/select/select.tsx b/packages/appkit-react/src/components/ui/select/select.tsx
index 46258752f..4697fcf0a 100644
--- a/packages/appkit-react/src/components/ui/select/select.tsx
+++ b/packages/appkit-react/src/components/ui/select/select.tsx
@@ -16,6 +16,13 @@ import type { ButtonProps } from '../button';
 import styles from './select.module.css';
 import { SelectContext, useSelectContext } from './use-select-context';
 
+/**
+ * Props accepted by {@link Select.Root}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface SelectRootProps {
     /** Controlled selected value. */
     value?: string;
@@ -31,6 +38,7 @@ export interface SelectRootProps {
     onOpenChange?: (open: boolean) => void;
     /** When true, the trigger is non-interactive. */
     disabled?: boolean;
+    /** Compound sub-components — {@link Select.Trigger}, {@link Select.Content}, {@link Select.Item}. */
     children: ReactNode;
 }
 
@@ -87,6 +95,13 @@ const SelectRoot: FC<SelectRootProps> = ({
     return <SelectContext.Provider value={ctx}>{children}</SelectContext.Provider>;
 };
 
+/**
+ * Props accepted by {@link Select.Trigger} — same as {@link ButtonProps}. The trigger inherits `disabled` from the surrounding root if set.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export type SelectTriggerProps = ButtonProps;
 
 const SelectTrigger = forwardRef<ComponentRef<'button'>, SelectTriggerProps>(
@@ -125,6 +140,13 @@ const SelectTrigger = forwardRef<ComponentRef<'button'>, SelectTriggerProps>(
 
 SelectTrigger.displayName = 'SelectTrigger';
 
+/**
+ * Props accepted by {@link Select.Content}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface SelectContentProps extends ComponentPropsWithoutRef<'div'> {
     /** Horizontal alignment relative to the trigger. */
     align?: 'start' | 'end';
@@ -230,8 +252,17 @@ const SelectContent: FC<SelectContentProps> = ({
     );
 };
 
+/**
+ * Props accepted by {@link Select.Item}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface SelectItemProps extends ComponentPropsWithoutRef<'div'> {
+    /** Value committed to {@link Select.Root} when this item is chosen. */
     value: string;
+    /** When true, the item is not selectable and is excluded from keyboard navigation. */
     disabled?: boolean;
 }
 
@@ -266,9 +297,20 @@ const SelectItem = forwardRef<ComponentRef<'div'>, SelectItemProps>(
 
 SelectItem.displayName = 'SelectItem';
 
+/**
+ * Compound select / dropdown component with controlled or uncontrolled state. The content is portaled to `document.body` and positioned relative to the trigger; closes on outside click, `Escape`, or item selection.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const Select = {
+    /** Provider that owns the selected value and open state, controlled or uncontrolled. */
     Root: SelectRoot,
+    /** {@link Button}-based trigger that toggles the popover and exposes `aria-expanded`. */
     Trigger: SelectTrigger,
+    /** Portaled popover that renders the list of items; positioned under the trigger with optional `sideOffset`. */
     Content: SelectContent,
+    /** Selectable option row; commits its `value` to the root on click. */
     Item: SelectItem,
 };
diff --git a/packages/appkit-react/src/components/ui/skeleton/skeleton.tsx b/packages/appkit-react/src/components/ui/skeleton/skeleton.tsx
index 7a27f5926..7e6f6f864 100644
--- a/packages/appkit-react/src/components/ui/skeleton/skeleton.tsx
+++ b/packages/appkit-react/src/components/ui/skeleton/skeleton.tsx
@@ -12,11 +12,27 @@ import clsx from 'clsx';
 
 import styles from './skeleton.module.css';
 
+/**
+ * Props accepted by {@link Skeleton}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface SkeletonProps extends ComponentProps<'div'> {
+    /** Width of the placeholder. Accepts any valid CSS length or a number (interpreted as pixels). */
     width?: string | number;
+    /** Height of the placeholder. Accepts any valid CSS length or a number (interpreted as pixels). */
     height?: string | number;
 }
 
+/**
+ * Animated placeholder block used while data is loading. Supply `width` / `height` to match the dimensions of the eventual content.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const Skeleton = forwardRef<HTMLDivElement, SkeletonProps>(
     ({ className, width, height, style, ...props }, ref) => {
         return (
diff --git a/packages/appkit-react/src/components/ui/tabs/tabs.tsx b/packages/appkit-react/src/components/ui/tabs/tabs.tsx
index ebe89d887..37fae9776 100644
--- a/packages/appkit-react/src/components/ui/tabs/tabs.tsx
+++ b/packages/appkit-react/src/components/ui/tabs/tabs.tsx
@@ -22,13 +22,31 @@ const TabsContext = createContext<TabsContextValue>({
     onValueChange: () => {},
 });
 
+/**
+ * Props accepted by {@link Tabs}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface TabsProps extends ComponentProps<'div'> {
+    /** Controlled active tab value. */
     value?: string;
+    /** Initial active tab when uncontrolled. Defaults to `''`. */
     defaultValue?: string;
+    /** Called whenever the active tab changes. */
     onValueChange?: (value: string) => void;
+    /** Compound sub-components — typically {@link TabsList} (with {@link TabsTrigger}s) followed by {@link TabsContent}s. */
     children: ReactNode;
 }
 
+/**
+ * Root tabs container — owns the active value (controlled or uncontrolled) and shares it with descendant {@link TabsList}, {@link TabsTrigger}, and {@link TabsContent} via context.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const Tabs: FC<TabsProps> = ({
     value: controlledValue,
     defaultValue = '',
@@ -61,10 +79,25 @@ export const Tabs: FC<TabsProps> = ({
     );
 };
 
+/**
+ * Props accepted by {@link TabsList}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface TabsListProps extends ComponentProps<'div'> {
+    /** Tab triggers — typically one or more {@link TabsTrigger}s. */
     children: ReactNode;
 }
 
+/**
+ * Horizontal list of tab triggers with `role="tablist"`.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const TabsList: FC<TabsListProps> = ({ children, className, ...props }) => {
     return (
         <div role="tablist" className={clsx(styles.list, className)} {...props}>
@@ -73,11 +106,27 @@ export const TabsList: FC<TabsListProps> = ({ children, className, ...props }) =
     );
 };
 
+/**
+ * Props accepted by {@link TabsTrigger}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface TabsTriggerProps extends ComponentProps<'button'> {
+    /** Value committed to the parent {@link Tabs} when this trigger is activated. */
     value: string;
+    /** Trigger label / content. */
     children: ReactNode;
 }
 
+/**
+ * Tab trigger button with `role="tab"`. Activates its `value` on click and reflects active state via `aria-selected` and `data-state`.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const TabsTrigger: FC<TabsTriggerProps> = ({ value, children, className, ...props }) => {
     const ctx = useContext(TabsContext);
     const isActive = ctx.value === value;
@@ -97,11 +146,27 @@ export const TabsTrigger: FC<TabsTriggerProps> = ({ value, children, className,
     );
 };
 
+/**
+ * Props accepted by {@link TabsContent}.
+ *
+ * @public
+ * @category Type
+ * @section UI
+ */
 export interface TabsContentProps extends ComponentProps<'div'> {
+    /** Value this panel is associated with — rendered only when the parent {@link Tabs} is on this value. */
     value: string;
+    /** Panel content. */
     children: ReactNode;
 }
 
+/**
+ * Tab panel rendered with `role="tabpanel"`. Returns `null` unless its `value` matches the active {@link Tabs} value.
+ *
+ * @public
+ * @category Component
+ * @section UI
+ */
 export const TabsContent: FC<TabsContentProps> = ({ value, children, className, ...props }) => {
     const ctx = useContext(TabsContext);
     const isActive = ctx.value === value;
diff --git a/packages/appkit-react/src/features/balances/components/balance-badge/balance-badge.tsx b/packages/appkit-react/src/features/balances/components/balance-badge/balance-badge.tsx
index e3b6942b3..07b8cccb3 100644
--- a/packages/appkit-react/src/features/balances/components/balance-badge/balance-badge.tsx
+++ b/packages/appkit-react/src/features/balances/components/balance-badge/balance-badge.tsx
@@ -38,10 +38,22 @@ const BalanceSymbol: FC<ComponentProps<'span'> & { symbol: string }> = ({ classN
     );
 };
 
+/**
+ * Compound component for rendering a token balance pill (icon + amount + symbol). Sub-components forward extra props to the underlying DOM element so callers can layer custom classes, click handlers, etc.
+ *
+ * @public
+ * @category Component
+ * @section Balances
+ */
 export const BalanceBadge = {
+    /** Pill wrapper — renders a horizontal {@link Block} that hosts the icon and balance block. */
     Container: BalanceBadgeContainer,
+    /** Token icon — re-exported {@link Logo} that draws the asset's image. */
     Icon: Logo,
+    /** Block holding the balance amount and ticker symbol side by side. */
     BalanceBlock: BalanceBlock,
+    /** Ticker symbol cell rendered next to the amount (e.g., `TON`, `USDT`). */
     Symbol: BalanceSymbol,
+    /** Formatted balance number; takes a raw `balance` and `decimals` and renders the human-readable amount. */
     Balance: Balance,
 };
diff --git a/packages/appkit-react/src/features/balances/components/send-jetton-button/send-jetton-button.tsx b/packages/appkit-react/src/features/balances/components/send-jetton-button/send-jetton-button.tsx
index d9d8cd399..81f578de7 100644
--- a/packages/appkit-react/src/features/balances/components/send-jetton-button/send-jetton-button.tsx
+++ b/packages/appkit-react/src/features/balances/components/send-jetton-button/send-jetton-button.tsx
@@ -14,17 +14,35 @@ import { useI18n, useAppKit } from '../../../settings';
 import type { SendProps } from '../../../transaction';
 import { Send } from '../../../transaction';
 
+/**
+ * Props accepted by {@link SendJettonButton} — extends the base `Send` button props (button text, sizing, callbacks) with the jetton-transfer details.
+ *
+ * @public
+ * @category Type
+ * @section Balances
+ */
 export interface SendJettonButtonProps extends Omit<SendProps, 'request'> {
+    /** Recipient address. */
     recipientAddress: string;
+    /** Amount in jetton units as a human-readable decimal string; converted to raw smallest units via `jetton.decimals`. */
     amount: string;
+    /** Jetton master metadata — `address` (master contract), `symbol` (rendered in the button label) and `decimals` (used to format `amount`). */
     jetton: {
         address: string;
         symbol: string;
         decimals: number;
     };
+    /** Optional human-readable comment attached to the transfer. */
     comment?: string;
 }
 
+/**
+ * Pre-wired button that builds a jetton transfer with {@link appkit:createTransferJettonTransaction} and dispatches it through the standard `Send` flow on click — disabled until `recipientAddress`, `amount`, `jetton.address` and a non-zero `jetton.decimals` are all set; throws inside the click handler when `jetton.address` is missing or `jetton.decimals` is falsy. (A `0`-decimal jetton must be passed as a truthy value to avoid being treated as missing.)
+ *
+ * @public
+ * @category Component
+ * @section Balances
+ */
 export const SendJettonButton: FC<SendJettonButtonProps> = ({
     recipientAddress,
     amount,
diff --git a/packages/appkit-react/src/features/balances/components/send-ton-button/send-ton-button.tsx b/packages/appkit-react/src/features/balances/components/send-ton-button/send-ton-button.tsx
index 30201ae49..9fdc1c2dc 100644
--- a/packages/appkit-react/src/features/balances/components/send-ton-button/send-ton-button.tsx
+++ b/packages/appkit-react/src/features/balances/components/send-ton-button/send-ton-button.tsx
@@ -14,12 +14,29 @@ import { useI18n, useAppKit } from '../../../settings';
 import type { SendProps } from '../../../transaction';
 import { Send } from '../../../transaction';
 
+/**
+ * Props accepted by {@link SendTonButton} — extends the base `Send` button props (button text, sizing, callbacks) with the TON-transfer details.
+ *
+ * @public
+ * @category Type
+ * @section Balances
+ */
 export interface SendTonButtonProps extends Omit<SendProps, 'request'> {
+    /** Recipient address. */
     recipientAddress: string;
+    /** Amount in TON as a human-readable decimal string (e.g., `"1.5"`); converted to nano-TON internally. */
     amount: string;
+    /** Optional human-readable comment attached to the transfer. */
     comment?: string;
 }
 
+/**
+ * Pre-wired button that builds a TON transfer with {@link appkit:createTransferTonTransaction} and dispatches it through the standard `Send` flow on click — disabled until both `recipientAddress` and `amount` are set.
+ *
+ * @public
+ * @category Component
+ * @section Balances
+ */
 export const SendTonButton: FC<SendTonButtonProps> = ({ recipientAddress, amount, comment, ...props }) => {
     const appKit = useAppKit();
     const { t } = useI18n();
diff --git a/packages/appkit-react/src/features/balances/hooks/use-balance-by-address.ts b/packages/appkit-react/src/features/balances/hooks/use-balance-by-address.ts
index e43423235..ac118b8dd 100644
--- a/packages/appkit-react/src/features/balances/hooks/use-balance-by-address.ts
+++ b/packages/appkit-react/src/features/balances/hooks/use-balance-by-address.ts
@@ -14,16 +14,39 @@ import { useQuery } from '../../../libs/query';
 import type { UseQueryReturnType } from '../../../libs/query';
 import { useNetwork } from '../../network';
 
+/**
+ * Parameters accepted by {@link useBalanceByAddress} — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the target address and optional network override.
+ *
+ * @public
+ * @category Type
+ * @section Balances
+ */
 export type UseBalanceByAddressParameters<selectData = GetBalanceByAddressData> =
     GetBalanceByAddressQueryConfig<selectData>;
 
+/**
+ * Return type of {@link useBalanceByAddress} — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+ *
+ * @public
+ * @category Type
+ * @section Balances
+ */
 export type UseBalanceByAddressReturnType<selectData = GetBalanceByAddressData> = UseQueryReturnType<
     selectData,
     GetBalanceErrorType
 >;
 
 /**
- * Hook to get balance
+ * React hook reading the Toncoin balance of an arbitrary address through TanStack Query — useful for addresses that aren't tied to the selected wallet (use {@link useBalance} for the selected wallet).
+ *
+ * @param parameters - {@link UseBalanceByAddressParameters} Target address, optional network override, and TanStack Query overrides.
+ * @returns TanStack Query result for the balance read.
+ *
+ * @sample docs/examples/src/appkit/hooks/balances#USE_BALANCE_BY_ADDRESS
+ *
+ * @public
+ * @category Hook
+ * @section Balances
  */
 export const useBalanceByAddress = <selectData = GetBalanceByAddressData>(
     parameters: UseBalanceByAddressParameters<selectData> = {},
diff --git a/packages/appkit-react/src/features/balances/hooks/use-balance.ts b/packages/appkit-react/src/features/balances/hooks/use-balance.ts
index b4d6a1dd6..46feaf63a 100644
--- a/packages/appkit-react/src/features/balances/hooks/use-balance.ts
+++ b/packages/appkit-react/src/features/balances/hooks/use-balance.ts
@@ -12,12 +12,35 @@ import { useAddress } from '../../wallets/hooks/use-address';
 import { useBalanceByAddress } from './use-balance-by-address';
 import type { UseBalanceByAddressParameters, UseBalanceByAddressReturnType } from './use-balance-by-address';
 
+/**
+ * Parameters accepted by {@link useBalance} — same shape as {@link UseBalanceByAddressParameters}; the hook resolves `address` from the selected wallet and overrides any value supplied here.
+ *
+ * @public
+ * @category Type
+ * @section Balances
+ */
 export type UseBalanceParameters<selectData = GetBalanceByAddressData> = UseBalanceByAddressParameters<selectData>;
 
+/**
+ * Return type of {@link useBalance} — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+ *
+ * @public
+ * @category Type
+ * @section Balances
+ */
 export type UseBalanceReturnType<selectData = GetBalanceByAddressData> = UseBalanceByAddressReturnType<selectData>;
 
 /**
- * Hook to get balance of the selected wallet
+ * React hook reading the Toncoin balance of the currently selected wallet through TanStack Query — auto-resolves the wallet address (use {@link useBalanceByAddress} for an arbitrary address).
+ *
+ * @param parameters - {@link UseBalanceParameters} TanStack Query overrides (`select`, `enabled`, `staleTime`, …) and an optional network override.
+ * @returns TanStack Query result for the balance read.
+ *
+ * @sample docs/examples/src/appkit/hooks/balances#USE_BALANCE
+ *
+ * @public
+ * @category Hook
+ * @section Balances
  */
 export const useBalance = <selectData = GetBalanceByAddressData>(
     parameters: UseBalanceParameters<selectData> = {},
diff --git a/packages/appkit-react/src/features/balances/hooks/use-watch-balance-by-address.ts b/packages/appkit-react/src/features/balances/hooks/use-watch-balance-by-address.ts
index d03d8ec42..59e8d4d69 100644
--- a/packages/appkit-react/src/features/balances/hooks/use-watch-balance-by-address.ts
+++ b/packages/appkit-react/src/features/balances/hooks/use-watch-balance-by-address.ts
@@ -14,11 +14,25 @@ import { handleBalanceUpdate } from '@ton/appkit/queries';
 
 import { useAppKit } from '../../settings';
 
+/**
+ * Parameters accepted by {@link useWatchBalanceByAddress} — same fields as {@link appkit:WatchBalanceByAddressOptions}, all optional so callers can render the hook before the address is known.
+ *
+ * @public
+ * @category Type
+ * @section Balances
+ */
 export type UseWatchBalanceByAddressParameters = Partial<WatchBalanceByAddressOptions>;
 
 /**
- * Hook to watch balance of a specific address in real-time.
- * Automatically updates the TanStack Query cache for `useBalanceByAddress`.
+ * Subscribe to Toncoin balance updates for an arbitrary address — updates flow into the TanStack Query cache so {@link useBalanceByAddress} re-renders automatically. No-ops with a console warning when no streaming provider is configured for the resolved network.
+ *
+ * @param parameters - {@link UseWatchBalanceByAddressParameters} Address, update callback and optional network override.
+ *
+ * @sample docs/examples/src/appkit/hooks/balances#USE_WATCH_BALANCE_BY_ADDRESS
+ *
+ * @public
+ * @category Hook
+ * @section Balances
  */
 export const useWatchBalanceByAddress = (parameters: UseWatchBalanceByAddressParameters): void => {
     const { address, network, onChange } = parameters;
diff --git a/packages/appkit-react/src/features/balances/hooks/use-watch-balance.ts b/packages/appkit-react/src/features/balances/hooks/use-watch-balance.ts
index 3c3351316..5e85428f8 100644
--- a/packages/appkit-react/src/features/balances/hooks/use-watch-balance.ts
+++ b/packages/appkit-react/src/features/balances/hooks/use-watch-balance.ts
@@ -11,11 +11,25 @@ import { useNetwork } from '../../network/hooks/use-network';
 import { useWatchBalanceByAddress } from './use-watch-balance-by-address';
 import type { UseWatchBalanceByAddressParameters } from './use-watch-balance-by-address';
 
+/**
+ * Parameters accepted by {@link useWatchBalance} — same fields as {@link UseWatchBalanceByAddressParameters} minus `address`, which the hook resolves from the selected wallet.
+ *
+ * @public
+ * @category Type
+ * @section Balances
+ */
 export type UseWatchBalanceParameters = Omit<UseWatchBalanceByAddressParameters, 'address'>;
 
 /**
- * Hook to watch balance of the currently selected wallet in real-time.
- * Automatically updates the TanStack Query cache for `useBalance`.
+ * Subscribe to Toncoin balance updates for the currently selected wallet; updates flow into the TanStack Query cache so {@link useBalance} re-renders automatically (use {@link useWatchBalanceByAddress} for a fixed address).
+ *
+ * @param parameters - {@link UseWatchBalanceParameters} Update callback and optional network override.
+ *
+ * @sample docs/examples/src/appkit/hooks/balances#USE_WATCH_BALANCE
+ *
+ * @public
+ * @category Hook
+ * @section Balances
  */
 export const useWatchBalance = (parameters: UseWatchBalanceParameters = {}): void => {
     const address = useAddress();
diff --git a/packages/appkit-react/src/features/jettons/hooks/use-jetton-balance-by-address.ts b/packages/appkit-react/src/features/jettons/hooks/use-jetton-balance-by-address.ts
index f779d472a..3c8a28d29 100644
--- a/packages/appkit-react/src/features/jettons/hooks/use-jetton-balance-by-address.ts
+++ b/packages/appkit-react/src/features/jettons/hooks/use-jetton-balance-by-address.ts
@@ -18,16 +18,39 @@ import { useQuery } from '../../../libs/query';
 import type { UseQueryReturnType } from '../../../libs/query';
 import { useNetwork } from '../../network';
 
+/**
+ * Parameters accepted by {@link useJettonBalanceByAddress} — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the jetton master, owner address, decimals and optional network override.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type UseJettonBalanceByAddressParameters<selectData = GetJettonBalanceByAddressData> =
     GetJettonBalanceByAddressQueryConfig<selectData>;
 
+/**
+ * Return type of {@link useJettonBalanceByAddress} — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type UseJettonBalanceByAddressReturnType<selectData = GetJettonBalanceByAddressData> = UseQueryReturnType<
     selectData,
     GetJettonBalanceErrorType
 >;
 
 /**
- * Hook to get jetton balance
+ * 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.
+ *
+ * @param parameters - {@link UseJettonBalanceByAddressParameters} Jetton master, owner address, decimals, optional network override and TanStack Query overrides.
+ * @returns TanStack Query result for the jetton balance read.
+ *
+ * @sample docs/examples/src/appkit/hooks/jettons#USE_JETTON_BALANCE_BY_ADDRESS
+ *
+ * @public
+ * @category Hook
+ * @section Jettons
  */
 export const useJettonBalanceByAddress = <selectData = GetJettonBalanceByAddressData>(
     parameters: UseJettonBalanceByAddressParameters<selectData> = {},
diff --git a/packages/appkit-react/src/features/jettons/hooks/use-jetton-info.ts b/packages/appkit-react/src/features/jettons/hooks/use-jetton-info.ts
index a3fed815b..9657e9004 100644
--- a/packages/appkit-react/src/features/jettons/hooks/use-jetton-info.ts
+++ b/packages/appkit-react/src/features/jettons/hooks/use-jetton-info.ts
@@ -14,15 +14,38 @@ import { useQuery } from '../../../libs/query';
 import type { UseQueryReturnType } from '../../../libs/query';
 import { useNetwork } from '../../network';
 
+/**
+ * Parameters accepted by {@link useJettonInfo} — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the jetton master address and optional network override.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type UseJettonInfoParameters<selectData = GetJettonInfoData> = GetJettonInfoQueryConfig<selectData>;
 
+/**
+ * Return type of {@link useJettonInfo} — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions; `data` is `null` when the indexer has no record for that master address.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type UseJettonInfoReturnType<selectData = GetJettonInfoData> = UseQueryReturnType<
     selectData,
     GetJettonInfoErrorType
 >;
 
 /**
- * Hook to get jetton info by address
+ * React hook reading jetton-master metadata (name, symbol, decimals, image, description) through TanStack Query.
+ *
+ * @param parameters - {@link UseJettonInfoParameters} Jetton master address, optional network override and TanStack Query overrides.
+ * @returns TanStack Query result for the jetton info read.
+ *
+ * @sample docs/examples/src/appkit/hooks/jettons#USE_JETTON_INFO
+ *
+ * @public
+ * @category Hook
+ * @section Jettons
  */
 export const useJettonInfo = <selectData = GetJettonInfoData>(
     parameters: UseJettonInfoParameters<selectData> = {},
diff --git a/packages/appkit-react/src/features/jettons/hooks/use-jetton-wallet-address.ts b/packages/appkit-react/src/features/jettons/hooks/use-jetton-wallet-address.ts
index 7734f4fb7..706a05c6e 100644
--- a/packages/appkit-react/src/features/jettons/hooks/use-jetton-wallet-address.ts
+++ b/packages/appkit-react/src/features/jettons/hooks/use-jetton-wallet-address.ts
@@ -18,16 +18,39 @@ import { useQuery } from '../../../libs/query';
 import type { UseQueryReturnType } from '../../../libs/query';
 import { useNetwork } from '../../network';
 
+/**
+ * Parameters accepted by {@link useJettonWalletAddress} — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the jetton master, owner address and optional network override.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type UseJettonWalletAddressParameters<selectData = GetJettonWalletAddressData> =
     GetJettonWalletAddressQueryConfig<selectData>;
 
+/**
+ * Return type of {@link useJettonWalletAddress} — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type UseJettonWalletAddressReturnType<selectData = GetJettonWalletAddressData> = UseQueryReturnType<
     selectData,
     GetJettonWalletAddressErrorType
 >;
 
 /**
- * Hook to get jetton wallet address
+ * React hook deriving the owner's jetton-wallet address — the per-owner contract that actually holds the jetton balance for a given master — through TanStack Query.
+ *
+ * @param parameters - {@link UseJettonWalletAddressParameters} Jetton master, owner address, optional network override and TanStack Query overrides.
+ * @returns TanStack Query result for the jetton-wallet address read.
+ *
+ * @sample docs/examples/src/appkit/hooks/jettons#USE_JETTON_WALLET_ADDRESS
+ *
+ * @public
+ * @category Hook
+ * @section Jettons
  */
 export const useJettonWalletAddress = <selectData = GetJettonWalletAddressData>(
     parameters: UseJettonWalletAddressParameters<selectData> = {},
diff --git a/packages/appkit-react/src/features/jettons/hooks/use-jettons-by-address.ts b/packages/appkit-react/src/features/jettons/hooks/use-jettons-by-address.ts
index 8455e51e9..ed389a6a7 100644
--- a/packages/appkit-react/src/features/jettons/hooks/use-jettons-by-address.ts
+++ b/packages/appkit-react/src/features/jettons/hooks/use-jettons-by-address.ts
@@ -14,16 +14,39 @@ import { useQuery } from '../../../libs/query';
 import type { UseQueryReturnType } from '../../../libs/query';
 import { useNetwork } from '../../network';
 
+/**
+ * Parameters accepted by {@link useJettonsByAddress} — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the owner address, optional network override and pagination.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type UseJettonsByAddressParameters<selectData = GetJettonsByAddressData> =
     GetJettonsByAddressQueryConfig<selectData>;
 
+/**
+ * Return type of {@link useJettonsByAddress} — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type UseJettonsByAddressReturnType<selectData = GetJettonsByAddressData> = UseQueryReturnType<
     selectData,
     GetJettonsErrorType
 >;
 
 /**
- * Hook to get jettons
+ * React hook listing jettons held by an arbitrary address through TanStack Query — useful for wallets that aren't selected in AppKit (use {@link useJettons} for the selected wallet).
+ *
+ * @param parameters - {@link UseJettonsByAddressParameters} Owner address, optional network override, pagination and TanStack Query overrides.
+ * @returns TanStack Query result for the jettons list.
+ *
+ * @sample docs/examples/src/appkit/hooks/jettons#USE_JETTONS_BY_ADDRESS
+ *
+ * @public
+ * @category Hook
+ * @section Jettons
  */
 export const useJettonsByAddress = <selectData = GetJettonsByAddressData>(
     parameters: UseJettonsByAddressParameters<selectData> = {},
diff --git a/packages/appkit-react/src/features/jettons/hooks/use-jettons.ts b/packages/appkit-react/src/features/jettons/hooks/use-jettons.ts
index bb002e07e..bed09116f 100644
--- a/packages/appkit-react/src/features/jettons/hooks/use-jettons.ts
+++ b/packages/appkit-react/src/features/jettons/hooks/use-jettons.ts
@@ -12,12 +12,35 @@ import { useAddress } from '../../wallets/hooks/use-address';
 import { useJettonsByAddress } from './use-jettons-by-address';
 import type { UseJettonsByAddressParameters, UseJettonsByAddressReturnType } from './use-jettons-by-address';
 
+/**
+ * Parameters accepted by {@link useJettons} — same shape as {@link UseJettonsByAddressParameters}; the hook resolves `address` from the selected wallet and overrides any value supplied here.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type UseJettonsParameters<selectData = GetJettonsByAddressData> = UseJettonsByAddressParameters<selectData>;
 
+/**
+ * Return type of {@link useJettons} — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type UseJettonsReturnType<selectData = GetJettonsByAddressData> = UseJettonsByAddressReturnType<selectData>;
 
 /**
- * Hook to get jettons of the selected wallet
+ * React hook listing jettons held by the currently selected wallet through TanStack Query — auto-resolves the wallet address (use {@link useJettonsByAddress} for an arbitrary address).
+ *
+ * @param parameters - {@link UseJettonsParameters} TanStack Query overrides (`select`, `enabled`, `staleTime`, …), pagination and an optional network override.
+ * @returns TanStack Query result for the jettons list.
+ *
+ * @sample docs/examples/src/appkit/hooks/jettons#USE_JETTONS
+ *
+ * @public
+ * @category Hook
+ * @section Jettons
  */
 export const useJettons = <selectData = GetJettonsByAddressData>(
     parameters: UseJettonsParameters<selectData> = {},
diff --git a/packages/appkit-react/src/features/jettons/hooks/use-transfer-jetton.ts b/packages/appkit-react/src/features/jettons/hooks/use-transfer-jetton.ts
index fb797cb94..fb9ea4739 100644
--- a/packages/appkit-react/src/features/jettons/hooks/use-transfer-jetton.ts
+++ b/packages/appkit-react/src/features/jettons/hooks/use-transfer-jetton.ts
@@ -21,8 +21,22 @@ import { useMutation } from '../../../libs/query';
 import type { UseMutationReturnType } from '../../../libs/query';
 import { useAppKit } from '../../settings';
 
+/**
+ * Parameters accepted by {@link useTransferJetton} — TanStack Query mutation options.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type UseTransferJettonParameters<context = unknown> = TransferJettonOptions<context>;
 
+/**
+ * Return type of {@link useTransferJetton} — TanStack Query mutation result.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type UseTransferJettonReturnType<context = unknown> = UseMutationReturnType<
     TransferJettonData,
     TransferJettonErrorType,
@@ -35,6 +49,18 @@ export type UseTransferJettonReturnType<context = unknown> = UseMutationReturnTy
     MutateFunction<TransferJettonData, TransferJettonErrorType, TransferJettonVariables, context>
 >;
 
+/**
+ * React mutation hook that builds and sends a jetton transfer from the selected wallet in one step (wraps {@link appkit:transferJetton}); returns `mutate({ jettonAddress, recipientAddress, amount, jettonDecimals, comment? })`. Throws `Error('Wallet not connected')` if no wallet is currently selected.
+ *
+ * @param parameters - {@link UseTransferJettonParameters} TanStack Query mutation overrides.
+ * @returns Mutation result for the jetton transfer call.
+ *
+ * @sample docs/examples/src/appkit/hooks/jettons#USE_TRANSFER_JETTON
+ *
+ * @public
+ * @category Hook
+ * @section Jettons
+ */
 export const useTransferJetton = <context = unknown>(
     parameters: UseTransferJettonParameters<context> = {},
 ): UseTransferJettonReturnType<context> => {
diff --git a/packages/appkit-react/src/features/jettons/hooks/use-watch-jettons-by-address.ts b/packages/appkit-react/src/features/jettons/hooks/use-watch-jettons-by-address.ts
index 333f9bdc0..04045fba9 100644
--- a/packages/appkit-react/src/features/jettons/hooks/use-watch-jettons-by-address.ts
+++ b/packages/appkit-react/src/features/jettons/hooks/use-watch-jettons-by-address.ts
@@ -14,11 +14,25 @@ import { handleJettonBalanceUpdate, handleJettonsUpdate } from '@ton/appkit/quer
 
 import { useAppKit } from '../../settings';
 
+/**
+ * Parameters accepted by {@link useWatchJettonsByAddress} — same fields as {@link appkit:WatchJettonsByAddressOptions}, all optional so callers can render the hook before the address is known.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type UseWatchJettonsByAddressParameters = Partial<WatchJettonsByAddressOptions>;
 
 /**
- * Hook to watch jetton updates for a specific address in real-time.
- * Automatically updates TanStack Query caches for jetton balances.
+ * Subscribe to jetton-balance updates for an arbitrary owner address; updates flow into the TanStack Query cache so {@link useJettonsByAddress} and {@link useJettonBalanceByAddress} re-render automatically. Logs a warning and exits when no streaming provider is configured for the resolved network.
+ *
+ * @param parameters - {@link UseWatchJettonsByAddressParameters} Owner address, update callback and optional network override.
+ *
+ * @sample docs/examples/src/appkit/hooks/jettons#USE_WATCH_JETTONS_BY_ADDRESS
+ *
+ * @public
+ * @category Hook
+ * @section Jettons
  */
 export const useWatchJettonsByAddress = (parameters: UseWatchJettonsByAddressParameters): void => {
     const { address, network } = parameters;
diff --git a/packages/appkit-react/src/features/jettons/hooks/use-watch-jettons.ts b/packages/appkit-react/src/features/jettons/hooks/use-watch-jettons.ts
index 79ece05a3..9e87ede2f 100644
--- a/packages/appkit-react/src/features/jettons/hooks/use-watch-jettons.ts
+++ b/packages/appkit-react/src/features/jettons/hooks/use-watch-jettons.ts
@@ -12,11 +12,25 @@ import { useAddress } from '../../wallets/hooks/use-address';
 import { useNetwork } from '../../network/hooks/use-network';
 import { useWatchJettonsByAddress } from './use-watch-jettons-by-address';
 
+/**
+ * Parameters accepted by {@link useWatchJettons} — update callback and optional network override; the hook resolves the address from the selected wallet.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type UseWatchJettonsParameters = Partial<WatchJettonsOptions>;
 
 /**
- * Hook to watch jetton updates of the currently selected wallet in real-time.
- * Automatically updates TanStack Query caches for jetton balances.
+ * Subscribe to jetton-balance updates for the currently selected wallet; updates flow into the TanStack Query cache so {@link useJettons} re-renders automatically (use {@link useWatchJettonsByAddress} for a fixed address).
+ *
+ * @param parameters - {@link UseWatchJettonsParameters} Update callback and optional network override.
+ *
+ * @sample docs/examples/src/appkit/hooks/jettons#USE_WATCH_JETTONS
+ *
+ * @public
+ * @category Hook
+ * @section Jettons
  */
 export const useWatchJettons = (parameters: UseWatchJettonsParameters = {}): void => {
     const address = useAddress();
diff --git a/packages/appkit-react/src/features/network/hooks/use-block-number.ts b/packages/appkit-react/src/features/network/hooks/use-block-number.ts
index 247edc451..e8b87a8c5 100644
--- a/packages/appkit-react/src/features/network/hooks/use-block-number.ts
+++ b/packages/appkit-react/src/features/network/hooks/use-block-number.ts
@@ -14,15 +14,36 @@ import { useQuery } from '../../../libs/query';
 import type { UseQueryReturnType } from '../../../libs/query';
 import { useNetwork } from '../hooks/use-network';
 
+/**
+ * Parameters accepted by {@link useBlockNumber} — TanStack Query options plus an optional network override. Defaults to the selected wallet's network; if no wallet is selected, falls back to mainnet.
+ *
+ * @public
+ * @category Type
+ * @section Networks
+ */
 export type UseBlockNumberParameters<selectData = GetBlockNumberData> = GetBlockNumberQueryConfig<selectData>;
 
+/**
+ * Return type of {@link useBlockNumber} — TanStack Query result.
+ *
+ * @public
+ * @category Type
+ * @section Networks
+ */
 export type UseBlockNumberReturnType<selectData = GetBlockNumberData> = UseQueryReturnType<
     selectData,
     GetBlockNumberErrorType
 >;
 
 /**
- * Hook to get the current masterchain block number
+ * React hook reading the latest masterchain seqno through TanStack Query — useful for freshness checks and pagination cursors.
+ *
+ * @param parameters - {@link UseBlockNumberParameters} TanStack Query overrides and optional network.
+ * @returns TanStack Query result for the seqno read.
+ *
+ * @public
+ * @category Hook
+ * @section Networks
  */
 export const useBlockNumber = <selectData = GetBlockNumberData>(
     parameters: UseBlockNumberParameters<selectData> = {},
diff --git a/packages/appkit-react/src/features/network/hooks/use-default-network.ts b/packages/appkit-react/src/features/network/hooks/use-default-network.ts
index 694b99aed..45532050a 100644
--- a/packages/appkit-react/src/features/network/hooks/use-default-network.ts
+++ b/packages/appkit-react/src/features/network/hooks/use-default-network.ts
@@ -12,13 +12,26 @@ import type { GetDefaultNetworkReturnType, Network } from '@ton/appkit';
 
 import { useAppKit } from '../../settings';
 
+/**
+ * Return type of {@link useDefaultNetwork} — `[network, setNetwork]` tuple. `network` is the current default (or `undefined`); `setNetwork` calls {@link appkit:setDefaultNetwork} and emits `networks:default-changed`.
+ *
+ * @public
+ * @category Type
+ * @section Networks
+ */
 export type UseDefaultNetworkReturnType = [
     network: GetDefaultNetworkReturnType,
     setNetwork: (network: Network | undefined) => void,
 ];
 
 /**
- * Hook to get and set the default network for wallet connections.
+ * Read and write AppKit's default network — the network connectors use for new wallet connections. Returns a `useState`-style tuple; the read side re-renders when the default changes through any source (this hook, {@link appkit:setDefaultNetwork}, manager events).
+ *
+ * @returns Tuple `[network, setNetwork]`.
+ *
+ * @public
+ * @category Hook
+ * @section Networks
  */
 export const useDefaultNetwork = (): UseDefaultNetworkReturnType => {
     const appKit = useAppKit();
diff --git a/packages/appkit-react/src/features/network/hooks/use-network.ts b/packages/appkit-react/src/features/network/hooks/use-network.ts
index 6128c44f7..5ee97531f 100644
--- a/packages/appkit-react/src/features/network/hooks/use-network.ts
+++ b/packages/appkit-react/src/features/network/hooks/use-network.ts
@@ -11,10 +11,23 @@ import { useMemo } from 'react';
 
 import { useSelectedWallet } from '../../wallets';
 
+/**
+ * Return type of {@link useNetwork} — `undefined` when no wallet is currently selected.
+ *
+ * @public
+ * @category Type
+ * @section Networks
+ */
 export type UseNetworkReturnType = Network | undefined;
 
 /**
- * Hook to get network of the selected wallet
+ * Read the {@link appkit:Network} the selected wallet is connected to; re-renders when the wallet's network changes (e.g. user switches mainnet/testnet inside the wallet).
+ *
+ * @returns Selected wallet's network, or `undefined` when no wallet is selected.
+ *
+ * @public
+ * @category Hook
+ * @section Networks
  */
 export const useNetwork = (): UseNetworkReturnType => {
     const [wallet] = useSelectedWallet();
diff --git a/packages/appkit-react/src/features/network/hooks/use-networks.ts b/packages/appkit-react/src/features/network/hooks/use-networks.ts
index 775da117e..389b151d0 100644
--- a/packages/appkit-react/src/features/network/hooks/use-networks.ts
+++ b/packages/appkit-react/src/features/network/hooks/use-networks.ts
@@ -12,10 +12,23 @@ import type { GetNetworksReturnType } from '@ton/appkit';
 
 import { useAppKit } from '../../settings';
 
+/**
+ * Return type of {@link useNetworks} — same shape as {@link appkit:GetNetworksReturnType}.
+ *
+ * @public
+ * @category Type
+ * @section Networks
+ */
 export type UseNetworksReturnType = GetNetworksReturnType;
 
 /**
- * Hook to get all configured networks
+ * Read the list of networks configured on AppKit; re-renders when {@link appkit:AppKitNetworkManager} adds, replaces or drops a network.
+ *
+ * @returns Array of configured {@link appkit:Network}s.
+ *
+ * @public
+ * @category Hook
+ * @section Networks
  */
 export const useNetworks = (): UseNetworksReturnType => {
     const appKit = useAppKit();
diff --git a/packages/appkit-react/src/features/nft/components/nft-item/nft-item.tsx b/packages/appkit-react/src/features/nft/components/nft-item/nft-item.tsx
index 7c26830b1..170ce8b56 100644
--- a/packages/appkit-react/src/features/nft/components/nft-item/nft-item.tsx
+++ b/packages/appkit-react/src/features/nft/components/nft-item/nft-item.tsx
@@ -16,10 +16,25 @@ import { ImageIcon } from '../../../../components/ui/icons';
 import { useI18n } from '../../../settings/hooks/use-i18n';
 import styles from './nft-item.module.css';
 
+/**
+ * Props accepted by {@link NftItem} — extends the native `<button>` props (`onClick`, `disabled`, `className`, …) with the NFT to render.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export interface NftItemProps extends ComponentProps<'button'> {
+    /** NFT to render — name, collection name, image and on-sale state are derived via `getFormattedNftInfo`. */
     nft: NFT;
 }
 
+/**
+ * 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.
+ *
+ * @public
+ * @category Component
+ * @section NFTs
+ */
 export const NftItem: FC<NftItemProps> = ({ nft, className, ...props }) => {
     const { t } = useI18n();
     const { name, collectionName, image, isOnSale } = useMemo(() => getFormattedNftInfo(nft), [nft]);
diff --git a/packages/appkit-react/src/features/nft/hooks/use-nft.ts b/packages/appkit-react/src/features/nft/hooks/use-nft.ts
index 8a0d4d33e..b0cb36d47 100644
--- a/packages/appkit-react/src/features/nft/hooks/use-nft.ts
+++ b/packages/appkit-react/src/features/nft/hooks/use-nft.ts
@@ -14,12 +14,37 @@ import { useQuery } from '../../../libs/query';
 import type { UseQueryReturnType } from '../../../libs/query';
 import { useNetwork } from '../../network';
 
+/**
+ * Parameters accepted by {@link useNft} — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the NFT contract address and optional network override.
+ *
+ * The `network` field defaults to the selected wallet's network; if no wallet is selected, falls back to AppKit's default network, or mainnet when none is set.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export type UseNftParameters<selectData = GetNftData> = GetNftQueryConfig<selectData>;
 
+/**
+ * Return type of {@link useNft} — TanStack Query result carrying `data` (the NFT or `null` when the indexer has no record), `isLoading`, `error` and the standard companions.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export type UseNftReturnType<selectData = GetNftData> = UseQueryReturnType<selectData, GetNftErrorType>;
 
 /**
- * Hook to get a single NFT
+ * React hook reading metadata and ownership for a single NFT through TanStack Query, keyed by its contract address; `data` is `null` when the indexer has no record.
+ *
+ * @param parameters - {@link UseNftParameters} NFT address, optional network override, and TanStack Query overrides.
+ * @returns TanStack Query result for the NFT read.
+ *
+ * @sample docs/examples/src/appkit/hooks/nft#USE_NFT
+ *
+ * @public
+ * @category Hook
+ * @section NFTs
  */
 export const useNft = <selectData = GetNftData>(
     parameters: UseNftParameters<selectData> = {},
diff --git a/packages/appkit-react/src/features/nft/hooks/use-nfts-by-address.ts b/packages/appkit-react/src/features/nft/hooks/use-nfts-by-address.ts
index a0250940e..48965a36a 100644
--- a/packages/appkit-react/src/features/nft/hooks/use-nfts-by-address.ts
+++ b/packages/appkit-react/src/features/nft/hooks/use-nfts-by-address.ts
@@ -14,12 +14,37 @@ import { useQuery } from '../../../libs/query';
 import type { UseQueryReturnType } from '../../../libs/query';
 import { useNetwork } from '../../network';
 
+/**
+ * Parameters accepted by {@link useNftsByAddress} — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the owner address, optional pagination (`limit`, `offset`) and network override.
+ *
+ * The `network` field defaults to the selected wallet's network; if no wallet is selected, falls back to AppKit's default network, or mainnet when none is set.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export type UseNFTsByAddressParameters<selectData = GetNFTsData> = GetNFTsQueryConfig<selectData>;
 
+/**
+ * Return type of {@link useNftsByAddress} — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export type UseNFTsByAddressReturnType<selectData = GetNFTsData> = UseQueryReturnType<selectData, GetNFTsErrorType>;
 
 /**
- * Hook to get NFTs
+ * React hook that reads NFTs held by an arbitrary address through TanStack Query — useful for wallets that aren't selected in AppKit (use {@link useNfts} for the selected wallet).
+ *
+ * @param parameters - {@link UseNFTsByAddressParameters} Owner address, optional pagination and network override, plus TanStack Query overrides.
+ * @returns TanStack Query result for the NFTs read.
+ *
+ * @sample docs/examples/src/appkit/hooks/nft#USE_NFTS_BY_ADDRESS
+ *
+ * @public
+ * @category Hook
+ * @section NFTs
  */
 export const useNftsByAddress = <selectData = GetNFTsData>(
     parameters: UseNFTsByAddressParameters<selectData> = {},
diff --git a/packages/appkit-react/src/features/nft/hooks/use-nfts.ts b/packages/appkit-react/src/features/nft/hooks/use-nfts.ts
index 8af8c1e07..21ab66a96 100644
--- a/packages/appkit-react/src/features/nft/hooks/use-nfts.ts
+++ b/packages/appkit-react/src/features/nft/hooks/use-nfts.ts
@@ -12,12 +12,35 @@ import { useAddress } from '../../wallets/hooks/use-address';
 import { useNftsByAddress } from './use-nfts-by-address';
 import type { UseNFTsByAddressParameters, UseNFTsByAddressReturnType } from './use-nfts-by-address';
 
+/**
+ * Parameters accepted by {@link useNfts} — same shape as {@link UseNFTsByAddressParameters}; the hook resolves `address` from the selected wallet and overrides any value supplied here.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export type UseNFTsParameters<selectData = GetNFTsData> = UseNFTsByAddressParameters<selectData>;
 
+/**
+ * Return type of {@link useNfts} — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export type UseNFTsReturnType<selectData = GetNFTsData> = UseNFTsByAddressReturnType<selectData>;
 
 /**
- * Hook to get NFTs of the selected wallet
+ * React hook that reads NFTs held by the currently selected wallet through TanStack Query — auto-resolves the wallet address (use {@link useNftsByAddress} for an arbitrary address).
+ *
+ * @param parameters - {@link UseNFTsParameters} Optional pagination, network override, and TanStack Query overrides.
+ * @returns TanStack Query result for the NFTs read.
+ *
+ * @sample docs/examples/src/appkit/hooks/nft#USE_NFTS
+ *
+ * @public
+ * @category Hook
+ * @section NFTs
  */
 export const useNfts = <selectData = GetNFTsData>(
     parameters: UseNFTsParameters<selectData> = {},
diff --git a/packages/appkit-react/src/features/nft/hooks/use-transfer-nft.ts b/packages/appkit-react/src/features/nft/hooks/use-transfer-nft.ts
index 4ebe67a98..f5b934725 100644
--- a/packages/appkit-react/src/features/nft/hooks/use-transfer-nft.ts
+++ b/packages/appkit-react/src/features/nft/hooks/use-transfer-nft.ts
@@ -21,8 +21,22 @@ import { useMutation } from '../../../libs/query';
 import type { UseMutationReturnType } from '../../../libs/query';
 import { useAppKit } from '../../settings';
 
+/**
+ * Parameters accepted by {@link useTransferNft} — TanStack Query mutation options.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export type UseTransferNftParameters<context = unknown> = TransferNftOptions<context>;
 
+/**
+ * Return type of {@link useTransferNft} — TanStack Query mutation result.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export type UseTransferNftReturnType<context = unknown> = UseMutationReturnType<
     TransferNftData,
     TransferNftErrorType,
@@ -35,6 +49,18 @@ export type UseTransferNftReturnType<context = unknown> = UseMutationReturnType<
     MutateFunction<TransferNftData, TransferNftErrorType, TransferNftVariables, context>
 >;
 
+/**
+ * React mutation hook that builds and sends an NFT transfer from the selected wallet in one step (wraps {@link appkit:transferNft}); returns `mutate({ nftAddress, recipientAddress, amount?, comment? })` and throws `Error('Wallet not connected')` if no wallet is currently selected.
+ *
+ * @param parameters - {@link UseTransferNftParameters} TanStack Query mutation overrides.
+ * @returns Mutation result for the transfer call.
+ *
+ * @sample docs/examples/src/appkit/hooks/nft#USE_TRANSFER_NFT
+ *
+ * @public
+ * @category Hook
+ * @section NFTs
+ */
 export const useTransferNft = <context = unknown>(
     parameters: UseTransferNftParameters<context> = {},
 ): UseTransferNftReturnType<context> => {
diff --git a/packages/appkit-react/src/features/onramp/components/onramp-amount-reversed/onramp-amount-reversed.tsx b/packages/appkit-react/src/features/onramp/components/onramp-amount-reversed/onramp-amount-reversed.tsx
index 67a0a7c52..c75d83046 100644
--- a/packages/appkit-react/src/features/onramp/components/onramp-amount-reversed/onramp-amount-reversed.tsx
+++ b/packages/appkit-react/src/features/onramp/components/onramp-amount-reversed/onramp-amount-reversed.tsx
@@ -11,10 +11,17 @@ import type { FC } from 'react';
 import { AmountReversed } from '../../../../components/ui/amount-reversed';
 import type { AmountReversedProps } from '../../../../components/ui/amount-reversed';
 
+/**
+ * Props for `OnrampAmountReversed` — same as `AmountReversed` but with a required `onChangeDirection`. Internal: fiat onramp is not part of the public API yet.
+ */
 export interface OnrampAmountReversedProps extends Omit<AmountReversedProps, 'onChangeDirection'> {
+    /** Callback fired when the user toggles between token-amount and fiat-amount input. */
     onChangeDirection: () => void;
 }
 
+/**
+ * Thin wrapper around `AmountReversed` that fixes `decimals` to `2` — used to render the fiat-side companion value in fiat onramp widgets. Internal: fiat onramp is not part of the public API yet.
+ */
 export const OnrampAmountReversed: FC<OnrampAmountReversedProps> = (props) => (
     <AmountReversed {...props} decimals={2} />
 );
diff --git a/packages/appkit-react/src/features/onramp/components/onramp-currency-item/onramp-currency-item.tsx b/packages/appkit-react/src/features/onramp/components/onramp-currency-item/onramp-currency-item.tsx
index be0e40347..8d9ac76f3 100644
--- a/packages/appkit-react/src/features/onramp/components/onramp-currency-item/onramp-currency-item.tsx
+++ b/packages/appkit-react/src/features/onramp/components/onramp-currency-item/onramp-currency-item.tsx
@@ -11,10 +11,17 @@ import type { ComponentProps, FC } from 'react';
 import { CurrencyItem } from '../../../../components/shared/currency-item';
 import type { OnrampCurrency } from '../../types';
 
+/**
+ * Props for `OnrampCurrencyItem` — extends the `CurrencyItem.Container` props (e.g. `onClick`, `className`) with the currency to render. Internal: TonPay / fiat onramp are not part of the public API yet.
+ */
 export interface OnrampCurrencyItemProps extends ComponentProps<typeof CurrencyItem.Container> {
+    /** Fiat currency to render — logo, name and ticker code are taken from `OnrampCurrency`. */
     currency: OnrampCurrency;
 }
 
+/**
+ * Row component rendering a single `OnrampCurrency` (logo, name, ticker code) as a clickable item — used inside `OnrampCurrencySelectModal`. Internal: TonPay / fiat onramp are not part of the public API yet.
+ */
 export const OnrampCurrencyItem: FC<OnrampCurrencyItemProps> = ({ currency, ...props }) => {
     return (
         <CurrencyItem.Container {...props}>
diff --git a/packages/appkit-react/src/features/onramp/components/onramp-currency-select-modal/onramp-currency-select-modal.tsx b/packages/appkit-react/src/features/onramp/components/onramp-currency-select-modal/onramp-currency-select-modal.tsx
index 4d9d69913..5b22dd132 100644
--- a/packages/appkit-react/src/features/onramp/components/onramp-currency-select-modal/onramp-currency-select-modal.tsx
+++ b/packages/appkit-react/src/features/onramp/components/onramp-currency-select-modal/onramp-currency-select-modal.tsx
@@ -16,14 +16,25 @@ import { useI18n } from '../../../settings/hooks/use-i18n';
 import { filterCurrencies, groupCurrencySections } from './utils';
 import type { CurrencySection } from './utils';
 
+/**
+ * Props for `OnrampCurrencySelectModal`. Internal: TonPay / fiat onramp are not part of the public API yet.
+ */
 export interface OnrampCurrencySelectModalProps {
+    /** Whether the modal is open. */
     open: boolean;
+    /** Called when the modal requests to close (selection made or dismissed). */
     onClose: () => void;
+    /** Full list of fiat currencies the user can pick from. */
     currencies: OnrampCurrency[];
+    /** Optional section configs grouping `currencies` by id; ungrouped currencies fall under an "Other" section. */
     currencySections?: CurrencySectionConfig[];
+    /** Called with the picked currency before the modal closes. */
     onSelect: (currency: OnrampCurrency) => void;
 }
 
+/**
+ * Searchable modal listing fiat `OnrampCurrency` entries (optionally grouped into sections) — used by fiat onramp widgets to let users pick the fiat side of the trade. Internal: TonPay / fiat onramp are not part of the public API yet.
+ */
 export const OnrampCurrencySelectModal: FC<OnrampCurrencySelectModalProps> = ({
     open,
     onClose,
diff --git a/packages/appkit-react/src/features/onramp/components/onramp-provider-item/onramp-provider-item.tsx b/packages/appkit-react/src/features/onramp/components/onramp-provider-item/onramp-provider-item.tsx
index 6de9a4f49..6a72ced15 100644
--- a/packages/appkit-react/src/features/onramp/components/onramp-provider-item/onramp-provider-item.tsx
+++ b/packages/appkit-react/src/features/onramp/components/onramp-provider-item/onramp-provider-item.tsx
@@ -13,10 +13,17 @@ import type { OnrampProvider } from '../../types';
 import { Logo } from '../../../../components/ui/logo';
 import styles from './onramp-provider-item.module.css';
 
+/**
+ * Props for `OnrampProviderItem` — extends native `<button>` props with the provider to render. Internal: fiat onramp is not part of the public API yet.
+ */
 export interface OnrampProviderItemProps extends ComponentProps<'button'> {
+    /** Onramp provider to render — logo, name and description are taken from `OnrampProvider`. */
     provider: OnrampProvider;
 }
 
+/**
+ * Button-row component rendering a single `OnrampProvider` (logo, name, description) — used inside `OnrampProviderSelect`. Internal: fiat onramp is not part of the public API yet.
+ */
 export const OnrampProviderItem: FC<OnrampProviderItemProps> = ({ provider, className, ...props }) => {
     return (
         <button type="button" className={clsx(styles.container, className)} {...props}>
diff --git a/packages/appkit-react/src/features/onramp/components/onramp-provider-select/onramp-provider-select.tsx b/packages/appkit-react/src/features/onramp/components/onramp-provider-select/onramp-provider-select.tsx
index 7af5d8f72..65c36fde5 100644
--- a/packages/appkit-react/src/features/onramp/components/onramp-provider-select/onramp-provider-select.tsx
+++ b/packages/appkit-react/src/features/onramp/components/onramp-provider-select/onramp-provider-select.tsx
@@ -14,13 +14,23 @@ import styles from './onramp-provider-select.module.css';
 import { OnrampProviderItem } from '../onramp-provider-item';
 import { useI18n } from '../../../settings/hooks/use-i18n';
 
+/**
+ * Props for `OnrampProviderSelect`. Internal: fiat onramp is not part of the public API yet.
+ */
 export interface OnrampProviderSelectProps {
+    /** Whether the modal is open. */
     open: boolean;
+    /** Called when the modal requests to close (selection made or dismissed). */
     onClose: () => void;
+    /** Onramp providers the user can pick from. */
     providers: OnrampProvider[];
+    /** Called with the picked provider before the modal closes. */
     onSelect: (provider: OnrampProvider) => void;
 }
 
+/**
+ * Modal listing available onramp providers as `OnrampProviderItem` rows — used to let users pick a checkout provider. Internal: fiat onramp is not part of the public API yet.
+ */
 export const OnrampProviderSelect: FC<OnrampProviderSelectProps> = ({ open, onClose, providers, onSelect }) => {
     const { t } = useI18n();
 
diff --git a/packages/appkit-react/src/features/onramp/components/onramp-token-selectors/onramp-token-selectors.tsx b/packages/appkit-react/src/features/onramp/components/onramp-token-selectors/onramp-token-selectors.tsx
index 052845cc6..a4f0bd52d 100644
--- a/packages/appkit-react/src/features/onramp/components/onramp-token-selectors/onramp-token-selectors.tsx
+++ b/packages/appkit-react/src/features/onramp/components/onramp-token-selectors/onramp-token-selectors.tsx
@@ -13,13 +13,31 @@ import styles from './onramp-token-selectors.module.css';
 import { TokenSelector } from '../../../../components/shared/token-selector';
 import { useI18n } from '../../../settings/hooks/use-i18n';
 
+/**
+ * Props for {@link OnrampTokenSelectors} — extends native `<div>` props with the from/to display state and click handlers.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export interface OnrampTokenSelectorsProps extends ComponentProps<'div'> {
+    /** Source side — the token being bought; rendered with the "buy {symbol}" label. (`network`/`networkLogoSrc` fields are accepted for symmetry with `to` but are not surfaced on the `from` selector.) */
     from: { title: string; logoSrc?: string; network?: string; networkLogoSrc?: string };
+    /** Target side — the payment method/currency; rendered with the "for {symbol}" label and an optional `networkLogoSrc` badge. */
     to: { title: string; logoSrc?: string; network?: string; networkLogoSrc?: string };
+    /** Called when the user clicks the source selector — typically opens the token picker. */
     onFromClick: () => void;
+    /** Called when the user clicks the target selector — typically opens the method/currency picker. */
     onToClick: () => void;
 }
 
+/**
+ * Side-by-side from/to token selectors used at the top of onramp widgets — pairs a "buy {token}" selector with a "for {method}" selector, each clickable to open the matching picker.
+ *
+ * @public
+ * @category Component
+ * @section Crypto Onramp
+ */
 export const OnrampTokenSelectors: FC<OnrampTokenSelectorsProps> = ({
     from,
     to,
diff --git a/packages/appkit-react/src/features/onramp/hooks/use-build-onramp-url.ts b/packages/appkit-react/src/features/onramp/hooks/use-build-onramp-url.ts
index 9d45f6ec3..b74bacc8b 100644
--- a/packages/appkit-react/src/features/onramp/hooks/use-build-onramp-url.ts
+++ b/packages/appkit-react/src/features/onramp/hooks/use-build-onramp-url.ts
@@ -30,7 +30,7 @@ export type UseBuildOnrampUrlReturnType<context = unknown> = UseMutationResult<
 >;
 
 /**
- * Hook to build onramp URL
+ * React mutation hook that wraps `buildOnrampUrl` — builds a URL that redirects the user to an onramp provider's flow. Returns `mutate(params)`. Internal: not part of the public API yet (fiat onramp is WIP).
  */
 export const useBuildOnrampUrl = <context = unknown>(
     parameters: UseBuildOnrampUrlParameters<context> = {},
diff --git a/packages/appkit-react/src/features/onramp/hooks/use-create-crypto-onramp-deposit.ts b/packages/appkit-react/src/features/onramp/hooks/use-create-crypto-onramp-deposit.ts
index 510536933..45e4bbac2 100644
--- a/packages/appkit-react/src/features/onramp/hooks/use-create-crypto-onramp-deposit.ts
+++ b/packages/appkit-react/src/features/onramp/hooks/use-create-crypto-onramp-deposit.ts
@@ -20,9 +20,23 @@ import type {
 import { useAppKit } from '../../settings';
 import { useMutation } from '../../../libs/query';
 
+/**
+ * Parameters accepted by {@link useCreateCryptoOnrampDeposit} — TanStack Query mutation options forwarded via `parameters.mutation`.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type UseCreateCryptoOnrampDepositParameters<context = unknown> =
     CreateCryptoOnrampDepositMutationOptions<context>;
 
+/**
+ * Return type of {@link useCreateCryptoOnrampDeposit} — TanStack Query mutation result.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type UseCreateCryptoOnrampDepositReturnType<context = unknown> = UseMutationResult<
     CreateCryptoOnrampDepositData,
     CreateCryptoOnrampDepositErrorType,
@@ -31,7 +45,14 @@ export type UseCreateCryptoOnrampDepositReturnType<context = unknown> = UseMutat
 >;
 
 /**
- * Hook to create a crypto onramp deposit from a previously obtained quote
+ * React mutation hook that creates a crypto-onramp deposit from a quote previously obtained via {@link useCryptoOnrampQuote} (wraps {@link appkit:createCryptoOnrampDeposit}) — the resolved {@link appkit:CryptoOnrampDeposit} carries the address and amount the user must send on the source chain.
+ *
+ * @param parameters - {@link UseCreateCryptoOnrampDepositParameters} TanStack Query mutation overrides (`parameters.mutation`).
+ * @returns Mutation result for the deposit call.
+ *
+ * @public
+ * @category Hook
+ * @section Crypto Onramp
  */
 export const useCreateCryptoOnrampDeposit = <context = unknown>(
     parameters: UseCreateCryptoOnrampDepositParameters<context> = {},
diff --git a/packages/appkit-react/src/features/onramp/hooks/use-crypto-onramp-provider.ts b/packages/appkit-react/src/features/onramp/hooks/use-crypto-onramp-provider.ts
index d924c7648..9fe27f2d0 100644
--- a/packages/appkit-react/src/features/onramp/hooks/use-crypto-onramp-provider.ts
+++ b/packages/appkit-react/src/features/onramp/hooks/use-crypto-onramp-provider.ts
@@ -12,14 +12,28 @@ import type { GetCryptoOnrampProviderOptions, GetCryptoOnrampProviderReturnType
 
 import { useAppKit } from '../../settings/hooks/use-app-kit';
 
-export type UseCryptoOnrampProviderReturnType = GetCryptoOnrampProviderReturnType;
+/**
+ * Return type of {@link useCryptoOnrampProvider} — the matching {@link appkit:CryptoOnrampProviderInterface}, or `undefined` when none is registered (the hook swallows the throw from {@link appkit:getCryptoOnrampProvider}).
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
+export type UseCryptoOnrampProviderReturnType = GetCryptoOnrampProviderReturnType | undefined;
 
 /**
- * Hook to get a registered crypto-onramp provider by id, or the default one when no id is given.
+ * Read a registered crypto-onramp provider by id, or the default provider when no id is given — subscribes to {@link appkit:watchCryptoOnrampProviders} and re-reads via {@link appkit:getCryptoOnrampProvider} so the result stays in sync. The read swallows the throw from {@link appkit:getCryptoOnrampProvider} (which throws when no provider matches — or when no id is passed and no default has been registered) and yields `undefined` instead.
+ *
+ * @param options - {@link appkit:GetCryptoOnrampProviderOptions} Optional provider id.
+ * @returns The matching provider, or `undefined` when none is registered.
+ *
+ * @public
+ * @category Hook
+ * @section Crypto Onramp
  */
 export const useCryptoOnrampProvider = (
     options: GetCryptoOnrampProviderOptions = {},
-): UseCryptoOnrampProviderReturnType | undefined => {
+): UseCryptoOnrampProviderReturnType => {
     const appKit = useAppKit();
     const { id } = options;
 
diff --git a/packages/appkit-react/src/features/onramp/hooks/use-crypto-onramp-providers.ts b/packages/appkit-react/src/features/onramp/hooks/use-crypto-onramp-providers.ts
index 6b2457531..4bef69998 100644
--- a/packages/appkit-react/src/features/onramp/hooks/use-crypto-onramp-providers.ts
+++ b/packages/appkit-react/src/features/onramp/hooks/use-crypto-onramp-providers.ts
@@ -12,10 +12,23 @@ import type { GetCryptoOnrampProvidersReturnType } from '@ton/appkit';
 
 import { useAppKit } from '../../settings/hooks/use-app-kit';
 
+/**
+ * Return type of {@link useCryptoOnrampProviders} — array of every {@link appkit:CryptoOnrampProviderInterface} currently registered on the AppKit instance.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type UseCryptoOnrampProvidersReturnType = GetCryptoOnrampProvidersReturnType;
 
 /**
- * Hook to get all registered crypto-onramp providers.
+ * List every crypto-onramp provider registered on the AppKit instance (both those passed via {@link appkit:AppKitConfig}'s `providers` and those added later through {@link appkit:registerProvider}); subscribes to {@link appkit:watchCryptoOnrampProviders} and re-reads via {@link appkit:getCryptoOnrampProviders} so the array stays in sync.
+ *
+ * @returns Array of registered crypto-onramp providers.
+ *
+ * @public
+ * @category Hook
+ * @section Crypto Onramp
  */
 export const useCryptoOnrampProviders = (): UseCryptoOnrampProvidersReturnType => {
     const appKit = useAppKit();
diff --git a/packages/appkit-react/src/features/onramp/hooks/use-crypto-onramp-quote.ts b/packages/appkit-react/src/features/onramp/hooks/use-crypto-onramp-quote.ts
index e77851ee7..95d2cf18c 100644
--- a/packages/appkit-react/src/features/onramp/hooks/use-crypto-onramp-quote.ts
+++ b/packages/appkit-react/src/features/onramp/hooks/use-crypto-onramp-quote.ts
@@ -19,16 +19,37 @@ import { useAppKit } from '../../settings';
 import { useQuery } from '../../../libs/query';
 import type { UseQueryReturnType } from '../../../libs/query';
 
+/**
+ * Parameters accepted by {@link useCryptoOnrampQuote} — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the source/target assets, amount and optional provider override forwarded to {@link appkit:getCryptoOnrampQuote}.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type UseCryptoOnrampQuoteParameters<selectData = GetCryptoOnrampQuoteData> =
     GetCryptoOnrampQuoteQueryConfig<selectData>;
 
+/**
+ * Return type of {@link useCryptoOnrampQuote} — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type UseCryptoOnrampQuoteReturnType<selectData = GetCryptoOnrampQuoteData> = UseQueryReturnType<
     selectData,
     GetCryptoOnrampQuoteErrorType
 >;
 
 /**
- * Hook to get a crypto onramp quote
+ * React hook quoting a crypto-to-TON onramp through TanStack Query (wraps {@link appkit:getCryptoOnrampQuote}) — returns the rate, expected amount and provider metadata needed to call {@link useCreateCryptoOnrampDeposit}.
+ *
+ * @param parameters - {@link UseCryptoOnrampQuoteParameters} Quote inputs and TanStack Query overrides.
+ * @returns TanStack Query result for the quote read.
+ *
+ * @public
+ * @category Hook
+ * @section Crypto Onramp
  */
 export const useCryptoOnrampQuote = <selectData = GetCryptoOnrampQuoteData>(
     parameters: UseCryptoOnrampQuoteParameters<selectData> = {},
diff --git a/packages/appkit-react/src/features/onramp/hooks/use-crypto-onramp-status.ts b/packages/appkit-react/src/features/onramp/hooks/use-crypto-onramp-status.ts
index ef5671fa3..c96a2ca6f 100644
--- a/packages/appkit-react/src/features/onramp/hooks/use-crypto-onramp-status.ts
+++ b/packages/appkit-react/src/features/onramp/hooks/use-crypto-onramp-status.ts
@@ -19,16 +19,37 @@ import { useAppKit } from '../../settings';
 import { useQuery } from '../../../libs/query';
 import type { UseQueryReturnType } from '../../../libs/query';
 
+/**
+ * Parameters accepted by {@link useCryptoOnrampStatus} — TanStack Query options (`select`, `enabled`, `refetchInterval`, …) plus the deposit id, originating provider id and optional provider override forwarded to {@link appkit:getCryptoOnrampStatus}.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type UseCryptoOnrampStatusParameters<selectData = GetCryptoOnrampStatusData> =
     GetCryptoOnrampStatusQueryConfig<selectData>;
 
+/**
+ * Return type of {@link useCryptoOnrampStatus} — TanStack Query result carrying `data`, `isLoading`, `error` and the standard companions.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type UseCryptoOnrampStatusReturnType<selectData = GetCryptoOnrampStatusData> = UseQueryReturnType<
     selectData,
     GetCryptoOnrampStatusErrorType
 >;
 
 /**
- * Hook to get a crypto onramp quote
+ * React hook reading the current status of a crypto-onramp deposit previously created via {@link useCreateCryptoOnrampDeposit} through TanStack Query (wraps {@link appkit:getCryptoOnrampStatus}) — typically polled via `refetchInterval` until the status is `'success'` or `'failed'`.
+ *
+ * @param parameters - {@link UseCryptoOnrampStatusParameters} Deposit id, originating provider id and TanStack Query overrides.
+ * @returns TanStack Query result for the status read.
+ *
+ * @public
+ * @category Hook
+ * @section Crypto Onramp
  */
 export const useCryptoOnrampStatus = <selectData = GetCryptoOnrampStatusData>(
     parameters: UseCryptoOnrampStatusParameters<selectData> = {},
diff --git a/packages/appkit-react/src/features/onramp/hooks/use-onramp-provider.ts b/packages/appkit-react/src/features/onramp/hooks/use-onramp-provider.ts
index 4cd81af39..ef07d6708 100644
--- a/packages/appkit-react/src/features/onramp/hooks/use-onramp-provider.ts
+++ b/packages/appkit-react/src/features/onramp/hooks/use-onramp-provider.ts
@@ -12,12 +12,12 @@ import type { GetOnrampProviderOptions, GetOnrampProviderReturnType } from '@ton
 
 import { useAppKit } from '../../settings/hooks/use-app-kit';
 
-export type UseOnrampProviderReturnType = GetOnrampProviderReturnType;
+export type UseOnrampProviderReturnType = GetOnrampProviderReturnType | undefined;
 
 /**
- * Hook to get onramp provider
+ * React hook that reads a registered onramp provider by id, or the default provider when no id is given. Subscribes via `watchOnrampProviders`; returns `undefined` instead of throwing when no provider matches. Internal: not part of the public API yet (fiat onramp is WIP).
  */
-export const useOnrampProvider = (options: GetOnrampProviderOptions = {}): UseOnrampProviderReturnType | undefined => {
+export const useOnrampProvider = (options: GetOnrampProviderOptions = {}): UseOnrampProviderReturnType => {
     const appKit = useAppKit();
     const { id } = options;
 
diff --git a/packages/appkit-react/src/features/onramp/hooks/use-onramp-providers.ts b/packages/appkit-react/src/features/onramp/hooks/use-onramp-providers.ts
index 712ccd308..30b983edd 100644
--- a/packages/appkit-react/src/features/onramp/hooks/use-onramp-providers.ts
+++ b/packages/appkit-react/src/features/onramp/hooks/use-onramp-providers.ts
@@ -15,7 +15,7 @@ import { useAppKit } from '../../settings/hooks/use-app-kit';
 export type UseOnrampProvidersReturnType = GetOnrampProvidersReturnType;
 
 /**
- * Hook to get all registered onramp providers
+ * React hook that lists every onramp provider registered on the AppKit instance; subscribes via `watchOnrampProviders` so the array stays in sync. Internal: not part of the public API yet (fiat onramp is WIP).
  */
 export const useOnrampProviders = (): UseOnrampProvidersReturnType => {
     const appKit = useAppKit();
diff --git a/packages/appkit-react/src/features/onramp/hooks/use-onramp-quote.ts b/packages/appkit-react/src/features/onramp/hooks/use-onramp-quote.ts
index 5d8a5922d..26ccfbd9a 100644
--- a/packages/appkit-react/src/features/onramp/hooks/use-onramp-quote.ts
+++ b/packages/appkit-react/src/features/onramp/hooks/use-onramp-quote.ts
@@ -23,7 +23,7 @@ export type UseOnrampQuoteReturnType<selectData = GetOnrampQuoteData> = UseQuery
 >;
 
 /**
- * Hook to get onramp quote
+ * React hook that fetches an onramp quote through TanStack Query (wraps `getOnrampQuote`). Internal: not part of the public API yet (fiat onramp is WIP).
  */
 export const useOnrampQuote = <selectData = GetOnrampQuoteData>(
     parameters: UseOnrampQuoteParameters<selectData> = {},
diff --git a/packages/appkit-react/src/features/onramp/types.ts b/packages/appkit-react/src/features/onramp/types.ts
index e86f30651..db93000d2 100644
--- a/packages/appkit-react/src/features/onramp/types.ts
+++ b/packages/appkit-react/src/features/onramp/types.ts
@@ -6,33 +6,72 @@
  *
  */
 
+/**
+ * Fiat currency displayed in onramp pickers (e.g. `OnrampCurrencySelectModal`). Internal: TonPay / fiat onramp are not part of the public API yet.
+ */
 export interface OnrampCurrency {
+    /** Stable identifier used by section configs and pre-selection props. */
     id: string;
+    /** Ticker code (e.g. `"USD"`, `"EUR"`). */
     code: string;
+    /** Human-readable name (e.g. `"US Dollar"`). */
     name: string;
+    /** Optional currency symbol (e.g. `"$"`). */
     symbol?: string;
+    /** Optional logo URL. */
     logo?: string;
 }
 
+/**
+ * Onramp provider displayed in `OnrampProviderSelect`. Internal: fiat onramp is not part of the public API yet.
+ */
 export interface OnrampProvider {
+    /** Stable provider identifier. */
     id: string;
+    /** Display name. */
     name: string;
+    /** Short description shown under the name (e.g. supported methods). */
     description?: string;
+    /** Optional logo URL. */
     logo?: string;
 }
 
+/**
+ * Section configuration grouping `OnrampCurrency` entries by id in a picker. Internal: TonPay / fiat onramp are not part of the public API yet.
+ */
 export interface CurrencySectionConfig {
+    /** Section header (typically already localized by the caller). */
     title: string;
+    /** Ids of {@link OnrampCurrency} entries to include in this section, in order. */
     ids: string[];
 }
 
+/**
+ * Which side the amount input is denominated in — `token` (crypto) vs `currency` (fiat). Internal: fiat onramp is not part of the public API yet; the crypto onramp widget uses `CryptoAmountInputMode` instead.
+ */
 export type AmountInputMode = 'token' | 'currency';
 
+/**
+ * Quick-pick amount button shown above the crypto-onramp input (carried on {@link CryptoOnrampContextType}'s `presetAmounts`).
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export interface OnrampAmountPreset {
+    /** Amount value the preset sets on click (decimal string). */
     amount: string;
+    /** Button label shown to the user. */
     label: string;
 }
 
+/**
+ * Source crypto payment method (what the user pays with on another chain) in the crypto onramp widget.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export interface CryptoPaymentMethod {
     /** Stable identifier for the method — used for selection state and `methodSections.ids` */
     id: string;
@@ -54,31 +93,52 @@ export interface CryptoPaymentMethod {
     logo?: string;
 }
 
+/**
+ * Section configuration grouping {@link CryptoPaymentMethod} entries by id in a picker.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export interface PaymentMethodSectionConfig {
+    /** Section header (typically already localized by the caller). */
     title: string;
+    /** Ids of {@link CryptoPaymentMethod} entries to include in this section, in order. */
     ids: string[];
 }
 
 /**
- * Target token (what the user is buying on TON) in the crypto onramp widget.
- * Kept separate from AppkitUIToken because `address` is the raw form expected
- * by the onramp provider (e.g. "0x0000000000000000000000000000000000000000"
- * for native TON, "EQCx..." for USDT jetton master).
+ * Target token (what the user is buying on TON) in the crypto onramp widget. Kept separate from `AppkitUIToken` because `address` is the raw form expected by the onramp provider (e.g. `"0x0000000000000000000000000000000000000000"` for native TON, `"EQCx..."` for USDT jetton master).
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
  */
 export interface CryptoOnrampToken {
+    /** Stable identifier used by section configs and pre-selection props. */
     id: string;
-    /** Token symbol, e.g. "TON", "USDT" */
+    /** Token symbol, e.g. `"TON"`, `"USDT"`. */
     symbol: string;
-    /** Full token name, e.g. "Toncoin", "Tether" */
+    /** Full token name, e.g. `"Toncoin"`, `"Tether"`. */
     name: string;
-    /** Number of decimals for the token */
+    /** Number of decimals for the token. */
     decimals: number;
-    /** Address as the onramp provider expects it */
+    /** Address as the onramp provider expects it. */
     address: string;
+    /** Optional logo URL. */
     logo?: string;
 }
 
+/**
+ * Section configuration grouping {@link CryptoOnrampToken} entries by id in a picker.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export interface CryptoOnrampTokenSectionConfig {
+    /** Section header (typically already localized by the caller). */
     title: string;
+    /** Ids of {@link CryptoOnrampToken} entries to include in this section, in order. */
     ids: string[];
 }
diff --git a/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/crypto-onramp-widget-provider/crypto-onramp-context.ts b/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/crypto-onramp-widget-provider/crypto-onramp-context.ts
index 98db37869..3e9e2d3ec 100644
--- a/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/crypto-onramp-widget-provider/crypto-onramp-context.ts
+++ b/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/crypto-onramp-widget-provider/crypto-onramp-context.ts
@@ -22,78 +22,98 @@ import type {
     PaymentMethodSectionConfig,
 } from '../../../types';
 
+/**
+ * Which side the amount input is currently denominated in — `token` means the user is entering the target-token amount, `method` means they are entering the source payment-method amount.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type CryptoAmountInputMode = 'token' | 'method';
 
+/**
+ * Shape of the `CryptoOnrampContext` value — selection state, quote/deposit data and actions exposed by {@link CryptoOnrampWidgetProvider} to the widget UI (and to custom render callbacks passed to {@link CryptoOnrampWidget}).
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export interface CryptoOnrampContextType {
-    /** Full list of tokens to buy */
+    /** Full list of target tokens the user can buy. */
     tokens: CryptoOnrampToken[];
-    /** Optional section configs for grouping tokens */
+    /** Optional section configs grouping `tokens` in the picker. */
     tokenSections?: CryptoOnrampTokenSectionConfig[];
-    /** Currently selected token to buy */
+    /** Currently selected target token to buy. `null` until tokens load. */
     selectedToken: CryptoOnrampToken | null;
+    /** Updates `selectedToken`. */
     setSelectedToken: (token: CryptoOnrampToken) => void;
 
-    /** Available crypto payment methods */
+    /** Available source crypto payment methods. */
     paymentMethods: CryptoPaymentMethod[];
-    /** Optional section configs for grouping payment methods */
+    /** Optional section configs grouping `paymentMethods` in the picker. */
     methodSections?: PaymentMethodSectionConfig[];
-    /** Currently selected payment method */
+    /** Currently selected source payment method. */
     selectedMethod: CryptoPaymentMethod;
+    /** Updates `selectedMethod`. */
     setSelectedMethod: (method: CryptoPaymentMethod) => void;
-    /** CAIP-2 → chain display info map (defaults merged with consumer overrides) */
+    /** CAIP-2 → chain display info map (built-in defaults merged with consumer overrides). */
     chains: Record<string, ChainInfo>;
 
-    /** Current amount input value */
+    /** Current amount input value as a decimal string. */
     amount: string;
+    /** Updates `amount`. */
     setAmount: (value: string) => void;
-    /** Whether user is entering token amount or payment-method amount */
+    /** Which side `amount` is denominated in — see {@link CryptoAmountInputMode}. */
     amountInputMode: CryptoAmountInputMode;
+    /** Updates `amountInputMode`. */
     setAmountInputMode: (mode: CryptoAmountInputMode) => void;
-    /** Converted amount from quote */
+    /** Other side of `amount` after applying the current quote's rate. */
     convertedAmount: string;
+    /** Quick-pick amount buttons rendered in the widget. */
     presetAmounts: OnrampAmountPreset[];
 
-    /** Current quote from provider */
+    /** Current quote, or `null` if not yet fetched / invalidated. */
     quote: CryptoOnrampQuote | null;
-    /** Whether quote is being fetched */
+    /** Whether a quote is in flight (includes the input-debounce window). */
     isLoadingQuote: boolean;
-    /** Error from quote fetch (i18n key) */
+    /** Quote-side validation/fetch error as an i18n key, or `null`. */
     quoteError: string | null;
-    /** Display name of the provider behind the current quote, when one is available. */
+    /** Display name of the provider behind the current quote, when available. */
     quoteProviderName: string | null;
 
-    /** Current deposit offer from provider */
+    /** Current deposit returned by the provider once `createDeposit` succeeded. */
     deposit: CryptoOnrampDeposit | null;
-    /** Whether deposit is being created */
+    /** Whether `createDeposit` is in flight. */
     isCreatingDeposit: boolean;
-    /** Error from deposit creation (i18n key) */
+    /** Deposit-side error as an i18n key, or `null`. */
     depositError: string | null;
-    /** Formatted deposit amount */
+    /** Formatted deposit amount the user must send on the source chain. */
     depositAmount: string;
-    /** Function to trigger deposit creation */
+    /** Triggers deposit creation from the current quote. */
     createDeposit: () => void;
-    /** Deposit status */
+    /** Latest deposit status polled via {@link useCryptoOnrampStatus}, or `null`. */
     depositStatus: CryptoOnrampStatus | null;
 
-    /** Whether the current quote provider requires a refund address */
+    /** Whether the current quote provider requires a refund address before deposit. */
     isRefundAddressRequired: boolean;
-    /** Whether the current quote provider supports reversed (target-amount) input */
+    /** Whether the current quote provider supports reversed (target-amount) input. */
     isReversedAmountSupported: boolean;
-    /** Refund address */
+    /** Refund address the user typed, if `isRefundAddressRequired`. */
     refundAddress: string;
+    /** Updates `refundAddress`. */
     setRefundAddress: (address: string) => void;
 
-    /** User's balance of the selected target token (formatted, token units) */
+    /** Connected wallet's balance of the selected target token (formatted, token units). */
     targetBalance: string;
-    /** Whether the target token balance is being fetched */
+    /** Whether the target token balance is being fetched. */
     isLoadingTargetBalance: boolean;
 
-    /** Whether a TON wallet is currently connected */
+    /** Whether a TON wallet is currently connected. */
     isWalletConnected: boolean;
 
-    /** Whether the user can proceed (valid amount + quote available + wallet connected) */
+    /** Whether the user can proceed — valid amount, quote available, and wallet connected. */
     canContinue: boolean;
-    /** Reset state (invalidate quote and clear deposit) */
+    /** Invalidates the active quote and clears the deposit, returning the widget to its initial state. */
     onReset: () => void;
 }
 
@@ -140,8 +160,18 @@ const defaultContext: CryptoOnrampContextType = {
     onReset: () => {},
 };
 
+/**
+ * React context carrying the {@link CryptoOnrampContextType} value populated by {@link CryptoOnrampWidgetProvider}. Prefer reading it via {@link useCryptoOnrampContext}; direct access is an escape hatch (e.g. `Context.Consumer`).
+ */
 export const CryptoOnrampContext = createContext<CryptoOnrampContextType>(defaultContext);
 
+/**
+ * Reads the `CryptoOnrampContext` populated by {@link CryptoOnrampWidgetProvider} — returns the widget's selection state, quote/deposit data and actions ({@link CryptoOnrampContextType}).
+ *
+ * @public
+ * @category Hook
+ * @section Crypto Onramp
+ */
 export const useCryptoOnrampContext = (): CryptoOnrampContextType => {
     return useContext(CryptoOnrampContext);
 };
diff --git a/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/crypto-onramp-widget-provider/crypto-onramp-widget-provider.tsx b/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/crypto-onramp-widget-provider/crypto-onramp-widget-provider.tsx
index 31a3d1d3b..039d8abac 100644
--- a/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/crypto-onramp-widget-provider/crypto-onramp-widget-provider.tsx
+++ b/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/crypto-onramp-widget-provider/crypto-onramp-widget-provider.tsx
@@ -27,10 +27,21 @@ import { useCryptoOnrampQuoteAndDeposit } from './use-crypto-onramp-quote-and-de
 import { useCryptoOnrampTokenState } from './use-crypto-onramp-token-state';
 import { useCryptoOnrampValidation } from './use-crypto-onramp-validation';
 
+/**
+ * Props for {@link CryptoOnrampWidgetProvider} — configures the target tokens and payment methods exposed to the widget, plus optional chain display overrides.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export interface CryptoOnrampProviderProps extends PropsWithChildren {
+    /** Target tokens (what the user buys on TON). Defaults to a built-in list. */
     tokens?: CryptoOnrampToken[];
+    /** Optional section configs grouping `tokens` in the picker. */
     tokenSections?: CryptoOnrampTokenSectionConfig[];
+    /** Source crypto payment methods (what the user pays with on another chain). Defaults to a built-in list. */
     paymentMethods?: CryptoPaymentMethod[];
+    /** Optional section configs grouping `paymentMethods` in the picker. */
     methodSections?: PaymentMethodSectionConfig[];
     /**
      * Custom CAIP-2 → chain display info overrides. Merged on top of the
@@ -38,10 +49,19 @@ export interface CryptoOnrampProviderProps extends PropsWithChildren {
      * override or add (e.g. `{ 'eip155:42161': { name: 'Arbitrum', logo: '...' } }`).
      */
     chains?: Record<string, ChainInfo>;
+    /** ID of the target token pre-selected on mount. */
     defaultTokenId?: string;
+    /** ID of the source payment method pre-selected on mount. */
     defaultMethodId?: string;
 }
 
+/**
+ * Context provider that powers the crypto-to-TON onramp widget — wires together token/method selection state, quote fetching ({@link useCryptoOnrampQuote}), deposit creation ({@link useCreateCryptoOnrampDeposit}), deposit status polling ({@link useCryptoOnrampStatus}), the target-token balance and validation. Consumers read the state via {@link useCryptoOnrampContext}.
+ *
+ * @public
+ * @category Component
+ * @section Crypto Onramp
+ */
 export const CryptoOnrampWidgetProvider: FC<CryptoOnrampProviderProps> = ({
     children,
     tokens = CRYPTO_ONRAMP_TARGET_TOKENS,
diff --git a/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/crypto-onramp-widget-ui/crypto-onramp-widget-ui.tsx b/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/crypto-onramp-widget-ui/crypto-onramp-widget-ui.tsx
index e119d6301..8fb6c2bca 100644
--- a/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/crypto-onramp-widget-ui/crypto-onramp-widget-ui.tsx
+++ b/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/crypto-onramp-widget-ui/crypto-onramp-widget-ui.tsx
@@ -26,9 +26,23 @@ import { formatOnrampAmount } from '../utils/format-onramp-amount';
 import { useI18n } from '../../../../settings/hooks/use-i18n';
 import styles from './crypto-onramp-widget-ui.module.css';
 
+/**
+ * Props for {@link CryptoOnrampWidgetUI} (and for the custom render callback on {@link CryptoOnrampWidget}) — the full {@link CryptoOnrampContextType} state and actions, plus the native `<div>` props the widget root forwards (`className`, `style`, etc.).
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type CryptoOnrampWidgetRenderProps = CryptoOnrampContextType &
     Omit<ComponentProps<'div'>, keyof CryptoOnrampContextType>;
 
+/**
+ * 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 ({@link CryptoOnrampWidgetRenderProps}); typically rendered inside {@link CryptoOnrampWidgetProvider} via {@link CryptoOnrampWidget}.
+ *
+ * @public
+ * @category Component
+ * @section Crypto Onramp
+ */
 export const CryptoOnrampWidgetUI: FC<CryptoOnrampWidgetRenderProps> = ({
     tokens,
     tokenSections,
diff --git a/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/crypto-onramp-widget/crypto-onramp-widget.tsx b/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/crypto-onramp-widget/crypto-onramp-widget.tsx
index 521489779..8a9d4f338 100644
--- a/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/crypto-onramp-widget/crypto-onramp-widget.tsx
+++ b/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/crypto-onramp-widget/crypto-onramp-widget.tsx
@@ -16,14 +16,15 @@ import type { CryptoOnrampProviderProps, CryptoOnrampContextType } from '../cryp
 type DivExtras = Omit<ComponentProps<'div'>, 'children' | keyof CryptoOnrampContextType>;
 
 /**
- * Props for the CryptoOnrampWidget component.
- * Inherits all configuration from CryptoOnrampProviderProps.
+ * Props for {@link CryptoOnrampWidget} — extends {@link CryptoOnrampProviderProps} (tokens, payment methods, defaults, chain overrides) plus the native `<div>` props the widget root forwards.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
  */
 export interface CryptoOnrampWidgetProps extends Omit<CryptoOnrampProviderProps, 'children'>, DivExtras {
     /**
-     * Custom render function.
-     * When provided, it replaces the default widget UI and gives full control over the rendering.
-     * Accesses all state and actions from the crypto onramp context.
+     * Custom render function. When provided, replaces the default {@link CryptoOnrampWidgetUI} and is called with the full {@link CryptoOnrampWidgetRenderProps} (context state, actions and forwarded `<div>` props), so callers can build a fully custom UI on top of the same provider.
      */
     children?: (props: CryptoOnrampWidgetRenderProps) => ReactNode;
 }
@@ -42,11 +43,11 @@ const CryptoOnrampWidgetContent: FC<{ children?: (props: CryptoOnrampWidgetRende
 };
 
 /**
- * A high-level component that provides a complete crypto-to-crypto onramp interface.
+ * Drop-in widget for buying TON-side tokens with a crypto payment from another chain — wraps {@link CryptoOnrampWidgetProvider} (which drives token/method selection, quote fetching, deposit creation and status polling) around {@link CryptoOnrampWidgetUI}. Pass a `children` render function to swap in a fully custom UI while keeping the same provider state.
  *
- * It manages payment method selection, quote fetching, deposit creation, and
- * deposit status tracking. It can be used as a standalone widget with default UI
- * or customized using a render function.
+ * @public
+ * @category Component
+ * @section Crypto Onramp
  */
 export const CryptoOnrampWidget: FC<CryptoOnrampWidgetProps> = ({
     children,
diff --git a/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/utils/chains.ts b/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/utils/chains.ts
index 4558e04f4..e21b028c3 100644
--- a/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/utils/chains.ts
+++ b/packages/appkit-react/src/features/onramp/widgets/crypto-onramp/utils/chains.ts
@@ -7,20 +7,27 @@
  */
 
 /**
- * Display info for a CAIP-2 chain — used by the crypto onramp widget to
- * render chain names and logos.
+ * Display info for a CAIP-2 chain — used by the crypto onramp widget to render chain names and logos.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
  */
 export interface ChainInfo {
+    /** Human-readable chain name (e.g. `"Ethereum"`, `"Arbitrum One"`). */
     name: string;
+    /** Optional logo URL for the chain. */
     logo?: string;
 }
 
 /**
- * Default mapping of CAIP-2 chain identifiers to display info used in the
- * crypto onramp widget. Consumers can override or extend this map via the
- * `chains` prop on `CryptoOnrampWidgetProvider`.
+ * Default mapping of CAIP-2 chain identifiers to {@link ChainInfo} used by the crypto onramp widget. Consumers can override or extend this map via the `chains` prop on {@link CryptoOnrampWidgetProvider}.
  *
  * @see https://chainagnostic.org/CAIPs/caip-2
+ *
+ * @public
+ * @category Constants
+ * @section Crypto Onramp
  */
 export const DEFAULT_CHAINS: Record<string, ChainInfo> = {
     'eip155:1': { name: 'Ethereum' },
@@ -38,10 +45,10 @@ export const DEFAULT_CHAINS: Record<string, ChainInfo> = {
 };
 
 /**
- * Resolve display info for a CAIP-2 chain. Falls back to a synthetic info
- * object whose `name` is the reference portion of the CAIP-2 string
- * (e.g. `eip155:9999` → `9999`), or the raw value if it does not look like
- * a CAIP-2 identifier.
+ * Resolves display info for a CAIP-2 chain. Falls back to a synthetic info object whose `name` is the reference portion of the CAIP-2 string (e.g. `eip155:9999` → `9999`), or the raw value if it does not look like a CAIP-2 identifier.
+ *
+ * @param chain - CAIP-2 chain identifier to look up (e.g. `'eip155:1'`).
+ * @param chains - Map of CAIP-2 ids to {@link ChainInfo} to consult first; pass {@link DEFAULT_CHAINS} unless you need overrides.
  */
 export const getChainInfo = (chain: string, chains: Record<string, ChainInfo>): ChainInfo => {
     const direct = chains[chain];
diff --git a/packages/appkit-react/src/features/onramp/widgets/fiat-onramp/onramp-widget-provider/onramp-widget-provider.tsx b/packages/appkit-react/src/features/onramp/widgets/fiat-onramp/onramp-widget-provider/onramp-widget-provider.tsx
index 662a7b139..9bbd6683a 100644
--- a/packages/appkit-react/src/features/onramp/widgets/fiat-onramp/onramp-widget-provider/onramp-widget-provider.tsx
+++ b/packages/appkit-react/src/features/onramp/widgets/fiat-onramp/onramp-widget-provider/onramp-widget-provider.tsx
@@ -119,9 +119,9 @@ export interface OnrampProviderProps extends PropsWithChildren {
     tokenSections?: TokenSectionConfig[];
     /** Optional section configs for grouping currencies in the selector */
     currencySections?: CurrencySectionConfig[];
-    /** Id of the token pre-selected for purchase */
+    /** ID of the token pre-selected for purchase */
     defaultTokenId?: string;
-    /** Id of the fiat currency pre-selected */
+    /** ID of the fiat currency pre-selected */
     defaultCurrencyId?: string;
 }
 
diff --git a/packages/appkit-react/src/features/onramp/widgets/ton-pay-widget/ton-pay-widget.tsx b/packages/appkit-react/src/features/onramp/widgets/ton-pay-widget/ton-pay-widget.tsx
index 39845c390..9dbd8e045 100644
--- a/packages/appkit-react/src/features/onramp/widgets/ton-pay-widget/ton-pay-widget.tsx
+++ b/packages/appkit-react/src/features/onramp/widgets/ton-pay-widget/ton-pay-widget.tsx
@@ -30,25 +30,31 @@ const DEFAULT_CURRENCIES: OnrampCurrency[] = ONRAMP_CURRENCIES.filter((c) => c.i
 
 const DEFAULT_PRESET_AMOUNTS = ['50', '100', '250', '500'];
 
+/**
+ * Props for `TonPayWidget`. Internal: TonPay widget is not part of the public API yet.
+ */
 export interface TonPayWidgetProps {
-    /** Tokens available to buy — only TON and USDT are supported by TonPay */
+    /** Tokens available to buy — filtered down to TON and USDT (the only assets TonPay supports). */
     tokens: AppkitUIToken[];
-    /** Optional section configs for grouping tokens in the selector */
+    /** Optional section configs for grouping tokens in the picker. */
     tokenSections?: TokenSectionConfig[];
-    /** Id of the token pre-selected for purchase */
+    /** ID of the token pre-selected for purchase. */
     defaultTokenId?: string;
-    /** Fiat currencies to show in the selector. Defaults to USD only. */
+    /** Fiat currencies offered in the picker. Defaults to USD only. */
     currencies?: OnrampCurrency[];
-    /** Optional section configs for grouping currencies in the selector */
+    /** Optional section configs for grouping currencies in the picker. */
     currencySections?: CurrencySectionConfig[];
-    /** Id of the fiat currency pre-selected */
+    /** ID of the fiat currency pre-selected. */
     defaultCurrencyId?: string;
-    /** Pre-filled amount */
+    /** Pre-filled crypto amount as a decimal string. */
     defaultAmount?: string;
-    /** Preset amount buttons (crypto amounts). Defaults to 50/100/250/500 with the token ticker. */
+    /** Preset amount buttons. Defaults to `50` / `100` / `250` / `500`. */
     presetAmounts?: OnrampAmountPreset[];
 }
 
+/**
+ * Widget that funnels users into the TonPay (MoonPay) checkout — collects a target asset (TON or USDT), fiat currency and amount, requests a transfer link from `pay.ton.org` for the active wallet's address, and opens the hosted checkout in a new tab. Internal: TonPay widget is not part of the public API yet.
+ */
 export const TonPayWidget: FC<TonPayWidgetProps> = ({
     tokens,
     tokenSections,
diff --git a/packages/appkit-react/src/features/settings/hooks/use-app-kit-theme.ts b/packages/appkit-react/src/features/settings/hooks/use-app-kit-theme.ts
index 917c37684..915390e0a 100644
--- a/packages/appkit-react/src/features/settings/hooks/use-app-kit-theme.ts
+++ b/packages/appkit-react/src/features/settings/hooks/use-app-kit-theme.ts
@@ -8,8 +8,24 @@
 
 import { useEffect, useState } from 'react';
 
+/**
+ * Theme value accepted by {@link useAppKitTheme} — `'light'`, `'dark'`, or any custom string mapped to a `data-ta-theme` token in the host's CSS.
+ *
+ * @public
+ * @category Type
+ * @section Settings
+ */
 export type AppKitTheme = 'light' | 'dark' | string;
 
+/**
+ * State hook that mirrors the active appkit-react theme to `document.body[data-ta-theme]` — returns a `[theme, setTheme]` tuple just like `useState`.
+ *
+ * @returns Tuple `[theme, setTheme]` for reading and switching the active theme.
+ *
+ * @public
+ * @category Hook
+ * @section Settings
+ */
 export const useAppKitTheme = () => {
     const [theme, setTheme] = useState<AppKitTheme>('light');
 
diff --git a/packages/appkit-react/src/features/settings/hooks/use-app-kit.ts b/packages/appkit-react/src/features/settings/hooks/use-app-kit.ts
index c08260593..3da05b3bd 100644
--- a/packages/appkit-react/src/features/settings/hooks/use-app-kit.ts
+++ b/packages/appkit-react/src/features/settings/hooks/use-app-kit.ts
@@ -10,6 +10,15 @@ import { useContext } from 'react';
 
 import { AppKitContext } from '../../../providers/app-kit-provider';
 
+/**
+ * Read the {@link appkit:AppKit} instance hosted by {@link AppKitProvider}; throws when the hook is rendered outside the provider tree.
+ *
+ * @returns The AppKit instance shared with descendant hooks/components.
+ *
+ * @public
+ * @category Hook
+ * @section Settings
+ */
 export const useAppKit = () => {
     const context = useContext(AppKitContext);
 
diff --git a/packages/appkit-react/src/features/settings/hooks/use-i18n.ts b/packages/appkit-react/src/features/settings/hooks/use-i18n.ts
index f808e3bb1..81c46e6e4 100644
--- a/packages/appkit-react/src/features/settings/hooks/use-i18n.ts
+++ b/packages/appkit-react/src/features/settings/hooks/use-i18n.ts
@@ -10,6 +10,15 @@ import { useContext } from 'react';
 
 import { I18nContext } from '../../../providers/i18n-provider';
 
+/**
+ * Read the i18n context published by {@link I18nProvider} (or the wrapping {@link AppKitProvider}); returns the active locale, translation function and helpers to switch locales or merge dictionaries. Throws when rendered outside the provider tree.
+ *
+ * @returns The i18n context ({@link I18nContextType}) with `activeLocale`, `t`, `locale` and `addDict`.
+ *
+ * @public
+ * @category Hook
+ * @section Settings
+ */
 export const useI18n = () => {
     const i18n = useContext(I18nContext);
 
diff --git a/packages/appkit-react/src/features/signing/hooks/use-sign-binary.ts b/packages/appkit-react/src/features/signing/hooks/use-sign-binary.ts
index b13a6d30c..54ca7fd20 100644
--- a/packages/appkit-react/src/features/signing/hooks/use-sign-binary.ts
+++ b/packages/appkit-react/src/features/signing/hooks/use-sign-binary.ts
@@ -13,8 +13,22 @@ import type { SignBinaryData, SignBinaryErrorType, SignBinaryOptions, SignBinary
 import { useAppKit } from '../../settings';
 import { useMutation } from '../../../libs/query';
 
+/**
+ * Parameters accepted by {@link useSignBinary} — TanStack Query mutation options.
+ *
+ * @public
+ * @category Type
+ * @section Signing
+ */
 export type UseSignBinaryParameters<context = unknown> = SignBinaryOptions<context>;
 
+/**
+ * Return type of {@link useSignBinary} — TanStack Query mutation result.
+ *
+ * @public
+ * @category Type
+ * @section Signing
+ */
 export type UseSignBinaryReturnType<context = unknown> = UseMutationResult<
     SignBinaryData,
     SignBinaryErrorType,
@@ -23,16 +37,14 @@ export type UseSignBinaryReturnType<context = unknown> = UseMutationResult<
 >;
 
 /**
- * Hook to sign binary data with the connected wallet.
+ * React mutation hook that asks the selected wallet to sign a binary blob (wraps {@link appkit:signBinary}); returns `mutate({ bytes })` you call from event handlers. The underlying action throws `Error('Wallet not connected')` if no wallet is currently selected — TanStack Query surfaces it via the mutation's `error`.
  *
- * @example
- * ```tsx
- * const { mutate: signBinary, isPending } = useSignBinary();
+ * @param parameters - {@link UseSignBinaryParameters} TanStack Query mutation overrides.
+ * @returns Mutation result for the signing call.
  *
- * const handleSign = () => {
- *   signBinary({ bytes: btoa("binary data") });
- * };
- * ```
+ * @public
+ * @category Hook
+ * @section Signing
  */
 export const useSignBinary = <context = unknown>(
     parameters?: UseSignBinaryParameters<context>,
diff --git a/packages/appkit-react/src/features/signing/hooks/use-sign-cell.ts b/packages/appkit-react/src/features/signing/hooks/use-sign-cell.ts
index 265985a27..096a3eb41 100644
--- a/packages/appkit-react/src/features/signing/hooks/use-sign-cell.ts
+++ b/packages/appkit-react/src/features/signing/hooks/use-sign-cell.ts
@@ -13,8 +13,22 @@ import type { SignCellData, SignCellErrorType, SignCellOptions, SignCellVariable
 import { useAppKit } from '../../settings';
 import { useMutation } from '../../../libs/query';
 
+/**
+ * Parameters accepted by {@link useSignCell} — TanStack Query mutation options.
+ *
+ * @public
+ * @category Type
+ * @section Signing
+ */
 export type UseSignCellParameters<context = unknown> = SignCellOptions<context>;
 
+/**
+ * Return type of {@link useSignCell} — TanStack Query mutation result.
+ *
+ * @public
+ * @category Type
+ * @section Signing
+ */
 export type UseSignCellReturnType<context = unknown> = UseMutationResult<
     SignCellData,
     SignCellErrorType,
@@ -23,17 +37,14 @@ export type UseSignCellReturnType<context = unknown> = UseMutationResult<
 >;
 
 /**
- * Hook to sign TON Cell data with the connected wallet.
- * Used for on-chain signature verification.
+ * React mutation hook that asks the selected wallet to sign a TON cell (wraps {@link appkit:signCell}); typically used so the signature can later be verified on-chain. Returns `mutate({ cell, schema })` you call from event handlers. The underlying action throws `Error('Wallet not connected')` if no wallet is currently selected — TanStack Query surfaces it via the mutation's `error`.
  *
- * @example
- * ```tsx
- * const { mutate: signCell, isPending } = useSignCell();
+ * @param parameters - {@link UseSignCellParameters} TanStack Query mutation overrides.
+ * @returns Mutation result for the signing call.
  *
- * const handleSign = () => {
- *   signCell({ cell: bocBase64, schema: "transfer#abc amount:uint64 = Transfer" });
- * };
- * ```
+ * @public
+ * @category Hook
+ * @section Signing
  */
 export const useSignCell = <context = unknown>(
     parameters?: UseSignCellParameters<context>,
diff --git a/packages/appkit-react/src/features/signing/hooks/use-sign-text.ts b/packages/appkit-react/src/features/signing/hooks/use-sign-text.ts
index 0845e8f59..5a2460cfe 100644
--- a/packages/appkit-react/src/features/signing/hooks/use-sign-text.ts
+++ b/packages/appkit-react/src/features/signing/hooks/use-sign-text.ts
@@ -13,8 +13,22 @@ import type { SignTextData, SignTextErrorType, SignTextOptions, SignTextVariable
 import { useAppKit } from '../../settings';
 import { useMutation } from '../../../libs/query';
 
+/**
+ * Parameters accepted by {@link useSignText} — TanStack Query mutation options.
+ *
+ * @public
+ * @category Type
+ * @section Signing
+ */
 export type UseSignTextParameters<context = unknown> = SignTextOptions<context>;
 
+/**
+ * Return type of {@link useSignText} — TanStack Query mutation result.
+ *
+ * @public
+ * @category Type
+ * @section Signing
+ */
 export type UseSignTextReturnType<context = unknown> = UseMutationResult<
     SignTextData,
     SignTextErrorType,
@@ -23,16 +37,14 @@ export type UseSignTextReturnType<context = unknown> = UseMutationResult<
 >;
 
 /**
- * Hook to sign text messages with the connected wallet.
+ * React mutation hook that asks the selected wallet to sign a plain-text message (wraps {@link appkit:signText}); returns `mutate({ text })` you call from event handlers. The underlying action throws `Error('Wallet not connected')` if no wallet is currently selected — TanStack Query surfaces it via the mutation's `error`.
  *
- * @example
- * ```tsx
- * const { mutate: signText, isPending } = useSignText();
+ * @param parameters - {@link UseSignTextParameters} TanStack Query mutation overrides.
+ * @returns Mutation result for the signing call.
  *
- * const handleSign = () => {
- *   signText({ text: "Hello World" });
- * };
- * ```
+ * @public
+ * @category Hook
+ * @section Signing
  */
 export const useSignText = <context = unknown>(
     parameters: UseSignTextParameters<context> = {},
diff --git a/packages/appkit-react/src/features/staking/components/select-unstake-mode/select-unstake-mode.tsx b/packages/appkit-react/src/features/staking/components/select-unstake-mode/select-unstake-mode.tsx
index 64804068b..e612d1657 100644
--- a/packages/appkit-react/src/features/staking/components/select-unstake-mode/select-unstake-mode.tsx
+++ b/packages/appkit-react/src/features/staking/components/select-unstake-mode/select-unstake-mode.tsx
@@ -18,10 +18,21 @@ import { useI18n } from '../../../settings/hooks/use-i18n';
 import { formatAmount } from '../staking-info/utils';
 import styles from './select-unstake-mode.module.css';
 
+/**
+ * Props accepted by {@link SelectUnstakeMode}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export interface SelectUnstakeModeProps extends ComponentProps<'div'> {
+    /** Currently selected unstake mode (see {@link appkit:UnstakeMode}). */
     value: UnstakeModes;
+    /** Called when the user picks a different mode. */
     onValueChange: (mode: UnstakeModes) => void;
+    /** Dynamic provider info — used to show the instant-unstake limit when available. */
     providerInfo: StakingProviderInfo | undefined;
+    /** Static provider metadata — supplies `supportedUnstakeModes` and stake-token formatting. */
     providerMetadata: StakingProviderMetadata | undefined;
 }
 
@@ -31,6 +42,13 @@ interface ModeOption {
     tags: string[];
 }
 
+/**
+ * Collapsible selector for the unstake mode (instant / round-end / when-available). Filters options by `providerMetadata.supportedUnstakeModes` and renders nothing when only one mode is supported. Annotates the instant option with the provider's current instant-unstake limit.
+ *
+ * @public
+ * @category Component
+ * @section Staking
+ */
 export const SelectUnstakeMode: FC<SelectUnstakeModeProps> = ({
     value,
     onValueChange,
diff --git a/packages/appkit-react/src/features/staking/components/staking-balance-block/staking-balance-block.tsx b/packages/appkit-react/src/features/staking/components/staking-balance-block/staking-balance-block.tsx
index 43641c1a5..fa8829f45 100644
--- a/packages/appkit-react/src/features/staking/components/staking-balance-block/staking-balance-block.tsx
+++ b/packages/appkit-react/src/features/staking/components/staking-balance-block/staking-balance-block.tsx
@@ -20,16 +20,37 @@ import styles from './staking-balance-block.module.css';
 import { Logo } from '../../../../components/ui/logo';
 import { useJettonInfo } from '../../../jettons';
 
+/**
+ * Props accepted by {@link StakingBalanceBlock}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export interface StakingBalanceBlockProps extends ComponentProps<'div'> {
+    /** Provider metadata — supplies the stake/receive tokens (address, ticker, decimals). */
     providerMetadata: StakingProviderMetadata | undefined;
+    /** Operation direction; selects which token and balance to render. */
     direction: StakingQuoteDirection;
+    /** User's currently staked amount, used when `direction === 'unstake'`. */
     stakedBalance?: string;
+    /** True while the staked balance is being fetched. */
     isStakedBalanceLoading?: boolean;
+    /** User's wallet balance of the stake token, used when `direction === 'stake'`. */
     balance?: string;
+    /** True while the wallet balance is being fetched. */
     isBalanceLoading?: boolean;
+    /** When provided, renders a `MAX` button that invokes this callback. */
     onMaxClick?: () => void;
 }
 
+/**
+ * Row showing the user's relevant balance for the current direction: wallet balance of the stake token when staking, staked balance when unstaking. Renders a token icon (native TON when the token address is `'ton'`, otherwise a jetton icon resolved via {@link useJettonInfo}), a label, the formatted amount with ticker, and an optional `MAX` button.
+ *
+ * @public
+ * @category Component
+ * @section Staking
+ */
 export const StakingBalanceBlock: FC<StakingBalanceBlockProps> = ({
     providerMetadata,
     direction,
diff --git a/packages/appkit-react/src/features/staking/components/staking-info/staking-info.tsx b/packages/appkit-react/src/features/staking/components/staking-info/staking-info.tsx
index 042a65b87..f299bff86 100644
--- a/packages/appkit-react/src/features/staking/components/staking-info/staking-info.tsx
+++ b/packages/appkit-react/src/features/staking/components/staking-info/staking-info.tsx
@@ -14,15 +14,35 @@ import { InfoBlock } from '../../../../components/ui/info-block';
 import { useI18n } from '../../../settings/hooks/use-i18n';
 import { formatAmount } from './utils';
 
+/**
+ * Props accepted by {@link StakingInfo}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export interface StakingInfoProps extends ComponentProps<typeof InfoBlock.Container> {
+    /** Current staking quote — its `amountOut` is rendered in the "You get" row. */
     quote: StakingQuote | undefined;
+    /** True while the quote is being fetched; swaps the "You get" value for a skeleton. */
     isQuoteLoading: boolean;
+    /** Dynamic provider info — supplies APY and exchange rate. */
     providerInfo: StakingProviderInfo | undefined;
+    /** Static provider metadata — supplies token tickers/decimals and the provider name. */
     providerMetadata: StakingProviderMetadata | undefined;
+    /** True while provider info is being fetched. */
     isProviderInfoLoading: boolean;
+    /** Operation direction — controls which token's decimals/ticker label the "You get" amount. Defaults to `'stake'`. */
     direction?: StakingQuoteDirection;
 }
 
+/**
+ * Summary block rendered below the staking input. Shows the amount the user will receive, the provider's current APY, the stake-token to receive-token exchange rate (only when the provider has a receive token), and the provider name. The exchange-rate row always reads as `1 stakeToken = X receiveToken`, regardless of `direction`.
+ *
+ * @public
+ * @category Component
+ * @section Staking
+ */
 export const StakingInfo: FC<StakingInfoProps> = ({
     quote,
     isQuoteLoading,
diff --git a/packages/appkit-react/src/features/staking/components/staking-settings-modal/staking-settings-modal.tsx b/packages/appkit-react/src/features/staking/components/staking-settings-modal/staking-settings-modal.tsx
index a881b5017..48d194984 100644
--- a/packages/appkit-react/src/features/staking/components/staking-settings-modal/staking-settings-modal.tsx
+++ b/packages/appkit-react/src/features/staking/components/staking-settings-modal/staking-settings-modal.tsx
@@ -16,12 +16,25 @@ import { OptionSwitcher } from '../../../../components/shared/option-switcher';
 import { useI18n } from '../../../settings/hooks/use-i18n';
 import styles from './staking-settings-modal.module.css';
 
+/**
+ * Props accepted by {@link StakingSettingsModal}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export interface StakingSettingsModalProps {
+    /** Controls modal visibility. */
     open: boolean;
+    /** Called when the user dismisses the modal or after a successful save. */
     onClose: () => void;
+    /** Currently active staking provider — used to preselect the option when the modal opens. */
     provider: StakingProvider | undefined;
+    /** All registered staking providers to choose from. */
     providers: StakingProvider[];
+    /** Invoked with the chosen `providerId` when the user saves a different selection. */
     onProviderChange: (providerId: string) => void;
+    /** Network used to resolve each provider's display name via its metadata. */
     network?: Network;
 }
 
@@ -33,6 +46,13 @@ const getProviderName = (provider: StakingProvider, network?: Network): string =
     }
 };
 
+/**
+ * Modal that lets the user pick the active staking provider. The selection is staged locally and only committed via `onProviderChange` when the user presses `Save`; closing the modal otherwise discards the change. Each option is labeled with the provider's metadata `name`, falling back to its `providerId` if metadata is unavailable on the given network.
+ *
+ * @public
+ * @category Component
+ * @section Staking
+ */
 export const StakingSettingsModal: FC<StakingSettingsModalProps> = ({
     open,
     onClose,
diff --git a/packages/appkit-react/src/features/staking/components/staking-widget-provider/staking-widget-provider.tsx b/packages/appkit-react/src/features/staking/components/staking-widget-provider/staking-widget-provider.tsx
index 3bef2a947..5e1ff1312 100644
--- a/packages/appkit-react/src/features/staking/components/staking-widget-provider/staking-widget-provider.tsx
+++ b/packages/appkit-react/src/features/staking/components/staking-widget-provider/staking-widget-provider.tsx
@@ -43,8 +43,11 @@ import { useDebounceValue } from '../../../../hooks/use-debounce-value';
 import { useStakingValidation } from './use-staking-validation';
 
 /**
- * Context type for the StakingWidget.
- * Provides all necessary state and actions for building custom staking UIs.
+ * Shape of the staking context exposed by {@link StakingWidgetProvider} and read via {@link useStakingContext}. Aggregates inputs (amount, direction, unstake mode), fetched data (balances, quote, provider info/metadata), derived flags (`canSubmit`, `error`, loading states), and the actions used by {@link StakingWidgetUI} (send transaction, switch provider, max, low-balance handling).
+ *
+ * @public
+ * @category Type
+ * @section Staking
  */
 export interface StakingContextType {
     /** Amount the user wants to stake (string to preserve input UX) */
@@ -149,24 +152,35 @@ export const StakingContext = createContext<StakingContextType>({
 });
 
 /**
- * Hook to access the staking context.
- * Must be used within a StakingWidgetProvider (or StakingWidget).
+ * Reads the {@link StakingContextType} from the nearest {@link StakingWidgetProvider} (or {@link StakingWidget}). Outside a provider, returns the default context (empty inputs, no-op actions) so a custom UI can still mount without crashing.
+ *
+ * @public
+ * @category Hook
+ * @section Staking
  */
 export const useStakingContext = () => {
     return useContext(StakingContext);
 };
 
 /**
- * Props for the StakingWidgetProvider.
+ * Props accepted by {@link StakingWidgetProvider}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
  */
 export interface StakingProviderProps extends PropsWithChildren {
-    /**
-     * Network to use for quote fetching and transactions.
-     * When omitted, uses the selected wallet's network.
-     */
+    /** Network used for quote fetching, balance reads, and transactions. Falls back to the connected wallet's network when omitted. */
     network?: Network;
 }
 
+/**
+ * Headless provider that owns all staking-widget state. Tracks the input amount, direction (stake/unstake), unstake mode, and reverse-input toggle; resolves the selected provider via {@link useStakingProvider} and its info/metadata via {@link useStakingProviderInfo} and {@link useStakingProviderMetadata}; reads the user's wallet balance (native TON or jetton) and staked balance; debounces inputs into {@link useStakingQuote}; and submits via {@link useBuildStakeTransaction} + `useSendTransaction`, gating on a TON-shortfall check to surface a low-balance warning. Validation flags (`error`, `canSubmit`) come from `useStakingValidation`. Exposes everything through `StakingContext` for {@link useStakingContext} consumers.
+ *
+ * @public
+ * @category Component
+ * @section Staking
+ */
 export const StakingWidgetProvider: FC<StakingProviderProps> = ({ children, network: networkProp }) => {
     const [amount, setAmountRaw] = useState('');
     const [unstakeMode, setUnstakeMode] = useState<UnstakeModes>(UnstakeMode.INSTANT);
diff --git a/packages/appkit-react/src/features/staking/components/staking-widget-ui/staking-widget-ui.tsx b/packages/appkit-react/src/features/staking/components/staking-widget-ui/staking-widget-ui.tsx
index 35c6b0e7e..1cc174e8e 100644
--- a/packages/appkit-react/src/features/staking/components/staking-widget-ui/staking-widget-ui.tsx
+++ b/packages/appkit-react/src/features/staking/components/staking-widget-ui/staking-widget-ui.tsx
@@ -25,8 +25,22 @@ import { AmountReversed } from '../../../../components/ui/amount-reversed';
 import { LowBalanceModal } from '../../../../components/shared/low-balance-modal';
 import { SettingsButton } from '../../../../components/shared/settings-button';
 
+/**
+ * Props accepted by {@link StakingWidgetUI} (also the argument type for the `StakingWidget` render-prop). Combines the full {@link StakingContextType} with standard `<div>` props forwarded to the outer wrapper.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type StakingWidgetRenderProps = StakingContextType & ComponentProps<'div'>;
 
+/**
+ * Default staking-widget UI. Renders a stake/unstake tabbed layout: a centered amount input with optional reversed input, a {@link StakingBalanceBlock} for the relevant balance, the submit button (wired through `ButtonWithConnect` so a disconnected user is prompted to connect first), a settings button that opens {@link StakingSettingsModal}, the unstake-mode picker ({@link SelectUnstakeMode}, unstake tab only), and a {@link StakingInfo} summary. A {@link LowBalanceModal} surfaces when the built transaction would exceed the user's TON balance. All state is consumed from props (typically supplied by {@link StakingWidgetProvider}); this component owns only the local `settings modal open` flag.
+ *
+ * @public
+ * @category Component
+ * @section Staking
+ */
 export const StakingWidgetUI: FC<StakingWidgetRenderProps> = ({
     amount,
     canSubmit,
diff --git a/packages/appkit-react/src/features/staking/components/staking-widget/staking-widget.tsx b/packages/appkit-react/src/features/staking/components/staking-widget/staking-widget.tsx
index e0ef2d3c0..207b357c6 100644
--- a/packages/appkit-react/src/features/staking/components/staking-widget/staking-widget.tsx
+++ b/packages/appkit-react/src/features/staking/components/staking-widget/staking-widget.tsx
@@ -14,14 +14,16 @@ import { StakingWidgetProvider, useStakingContext } from '../staking-widget-prov
 import type { StakingProviderProps } from '../staking-widget-provider';
 
 /**
- * Props for the StakingWidget component.
+ * Props accepted by {@link StakingWidget}. Extends {@link StakingProviderProps} (e.g. `network`) and standard `<div>` props forwarded to the default UI.
+ *
+ * @public
+ * @category Type
+ * @section Staking
  */
 export interface StakingWidgetProps
     extends Omit<StakingProviderProps, 'children'>, Omit<ComponentProps<'div'>, 'children'> {
     /**
-     * Custom render function.
-     * When provided, it replaces the default widget UI and gives full control over the rendering.
-     * Useful for building unique staking interfaces while leveraging the widget's internal logic.
+     * Optional render-prop. When provided, the default {@link StakingWidgetUI} is bypassed and this function is called with the full {@link StakingWidgetRenderProps} (context state + forwarded `<div>` props), letting consumers build a custom UI on top of the widget's internal logic.
      */
     children?: (props: StakingWidgetRenderProps) => ReactNode;
 }
@@ -39,11 +41,11 @@ const StakingWidgetContent: FC<
 };
 
 /**
- * A high-level component that provides a complete staking interface.
+ * High-level staking widget that wires the full stake/unstake flow: pick a provider, enter an amount (with optional reverse input on supported providers), review the quote (APY, exchange rate, "you get"), then submit the transaction. Internally wraps {@link StakingWidgetProvider} around {@link StakingWidgetUI}; consumers can replace the UI by passing a render-prop `children` while keeping the widget's state, quoting, balance checks, and submission logic.
  *
- * It manages the staking lifecycle, including fetching quotes, building transactions,
- * and handling user input. It can be used as a standalone widget with default UI
- * or customized using a render function.
+ * @public
+ * @category Component
+ * @section Staking
  */
 export const StakingWidget: FC<StakingWidgetProps> = ({ children, network, ...rest }) => {
     return (
diff --git a/packages/appkit-react/src/features/staking/hooks/use-build-stake-transaction.ts b/packages/appkit-react/src/features/staking/hooks/use-build-stake-transaction.ts
index c0b5e7250..49b56c945 100644
--- a/packages/appkit-react/src/features/staking/hooks/use-build-stake-transaction.ts
+++ b/packages/appkit-react/src/features/staking/hooks/use-build-stake-transaction.ts
@@ -17,6 +17,13 @@ import type {
 import { useAppKit } from '../../settings';
 import { useMutation } from '../../../libs/query';
 
+/**
+ * Return type of {@link useBuildStakeTransaction} — TanStack Query mutation result that resolves to a {@link appkit:TransactionRequest}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type UseBuildStakeTransactionReturnType<context = unknown> = UseMutationResult<
     BuildStakeTransactionData,
     BuildStakeTransactionErrorType,
@@ -25,7 +32,13 @@ export type UseBuildStakeTransactionReturnType<context = unknown> = UseMutationR
 >;
 
 /**
- * Hook to build stake transaction
+ * React mutation hook that wraps {@link appkit:buildStakeTransaction} — turns a {@link appkit:StakingQuote} obtained via {@link useStakingQuote} into a {@link appkit:TransactionRequest} without sending it, so the UI can inspect or batch before signing. Returns `mutate(params)` where `params` matches {@link appkit:BuildStakeTransactionOptions}.
+ *
+ * @returns Mutation result for the build call.
+ *
+ * @public
+ * @category Hook
+ * @section Staking
  */
 export const useBuildStakeTransaction = <context = unknown>(): UseBuildStakeTransactionReturnType<context> => {
     const appKit = useAppKit();
diff --git a/packages/appkit-react/src/features/staking/hooks/use-staked-balance.ts b/packages/appkit-react/src/features/staking/hooks/use-staked-balance.ts
index da7899378..5acb06a4d 100644
--- a/packages/appkit-react/src/features/staking/hooks/use-staked-balance.ts
+++ b/packages/appkit-react/src/features/staking/hooks/use-staked-balance.ts
@@ -14,14 +14,36 @@ import { useQuery } from '../../../libs/query';
 import type { UseQueryReturnType } from '../../../libs/query';
 import { useNetwork } from '../../network';
 
+/**
+ * Parameters accepted by {@link useStakedBalance} — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the owner address, optional network override and optional `providerId`.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type UseStakedBalanceParameters<selectData = GetStakedBalanceData> = GetStakedBalanceQueryConfig<selectData>;
+
+/**
+ * Return type of {@link useStakedBalance} — TanStack Query result carrying the user's staked balance.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type UseStakedBalanceReturnType<selectData = GetStakedBalanceData> = UseQueryReturnType<
     selectData,
     GetStakedBalanceErrorType
 >;
 
 /**
- * Hook to get user's staked balance
+ * 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.
+ *
+ * @param parameters - {@link UseStakedBalanceParameters} Owner address, optional `providerId`, optional network override, and TanStack Query overrides.
+ * @returns TanStack Query result for the staked-balance read.
+ *
+ * @public
+ * @category Hook
+ * @section Staking
  */
 export const useStakedBalance = <selectData = GetStakedBalanceData>(
     parameters: UseStakedBalanceParameters<selectData> = {},
diff --git a/packages/appkit-react/src/features/staking/hooks/use-staking-provider-info.ts b/packages/appkit-react/src/features/staking/hooks/use-staking-provider-info.ts
index 39a7f5c96..30b9e6f0f 100644
--- a/packages/appkit-react/src/features/staking/hooks/use-staking-provider-info.ts
+++ b/packages/appkit-react/src/features/staking/hooks/use-staking-provider-info.ts
@@ -19,15 +19,37 @@ import type { UseQueryReturnType } from '../../../libs/query';
 import { useNetwork } from '../../network';
 import { useStakingProvider } from './use-staking-provider';
 
+/**
+ * Parameters accepted by {@link useStakingProviderInfo} — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus an optional `providerId` and network override.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type UseStakingProviderInfoParameters<selectData = GetStakingProviderInfoData> =
     GetStakingProviderInfoQueryConfig<selectData>;
+
+/**
+ * Return type of {@link useStakingProviderInfo} — TanStack Query result carrying live {@link appkit:StakingProviderInfo}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type UseStakingProviderInfoReturnType<selectData = GetStakingProviderInfoData> = UseQueryReturnType<
     selectData,
     GetStakingProviderInfoErrorType
 >;
 
 /**
- * Hook to get staking provider information
+ * 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 {@link 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.
+ *
+ * @param parameters - {@link UseStakingProviderInfoParameters} Optional `providerId`, network override, and TanStack Query overrides.
+ * @returns TanStack Query result for the live provider info.
+ *
+ * @public
+ * @category Hook
+ * @section Staking
  */
 export const useStakingProviderInfo = <selectData = GetStakingProviderInfoData>(
     parameters: UseStakingProviderInfoParameters<selectData> = {},
@@ -38,8 +60,8 @@ export const useStakingProviderInfo = <selectData = GetStakingProviderInfoData>(
 
     return useQuery(
         getStakingProviderInfoQueryOptions(appKit, {
-            providerId: provider?.providerId,
             ...parameters,
+            providerId: parameters.providerId ?? provider?.providerId,
             network: parameters.network ?? walletNetwork,
         }),
     );
diff --git a/packages/appkit-react/src/features/staking/hooks/use-staking-provider-metadata.ts b/packages/appkit-react/src/features/staking/hooks/use-staking-provider-metadata.ts
index 3563ecfad..9a3a60fd7 100644
--- a/packages/appkit-react/src/features/staking/hooks/use-staking-provider-metadata.ts
+++ b/packages/appkit-react/src/features/staking/hooks/use-staking-provider-metadata.ts
@@ -13,11 +13,33 @@ import { useMemo } from 'react';
 import { useAppKit } from '../../settings';
 import { useStakingProvider } from './use-staking-provider';
 
+/**
+ * Parameters accepted by {@link useStakingProviderMetadata} — optional `providerId` and network override.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type UseStakingProviderMetadataParameters = GetStakingProviderMetadataOptions;
-export type UseStakingProviderMetadataReturnType = GetStakingProviderMetadataReturnType;
 
 /**
- * Hook to get static staking provider metadata
+ * Return type of {@link useStakingProviderMetadata} — static {@link appkit:StakingProviderMetadata} for the resolved provider, or `undefined` when no provider matches and no default is registered (the hook swallows the throw from {@link appkit:getStakingProviderMetadata}).
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
+export type UseStakingProviderMetadataReturnType = GetStakingProviderMetadataReturnType | undefined;
+
+/**
+ * React hook reading static metadata for a staking provider (wraps {@link appkit:getStakingProviderMetadata}) — display name, stake/receive tokens, supported unstake modes and contract address. Returns `undefined` when no provider matches and no default is registered. Use {@link 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.
+ *
+ * @param parameters - {@link UseStakingProviderMetadataParameters} Optional `providerId` and network override.
+ * @returns Static {@link appkit:StakingProviderMetadata}, or `undefined` when the provider can't be resolved.
+ *
+ * @public
+ * @category Hook
+ * @section Staking
  */
 export const useStakingProviderMetadata = (parameters: UseStakingProviderMetadataParameters = {}) => {
     const appKit = useAppKit();
diff --git a/packages/appkit-react/src/features/staking/hooks/use-staking-provider.ts b/packages/appkit-react/src/features/staking/hooks/use-staking-provider.ts
index f9204a376..83e33b40a 100644
--- a/packages/appkit-react/src/features/staking/hooks/use-staking-provider.ts
+++ b/packages/appkit-react/src/features/staking/hooks/use-staking-provider.ts
@@ -12,14 +12,26 @@ import type { GetStakingProviderOptions, GetStakingProviderReturnType } from '@t
 
 import { useAppKit } from '../../settings/hooks/use-app-kit';
 
-export type UseStakingProviderReturnType = GetStakingProviderReturnType;
+/**
+ * Return type of {@link useStakingProvider} — the matching staking provider, or `undefined` when none resolves (the hook swallows the throw from {@link appkit:getStakingProvider}).
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
+export type UseStakingProviderReturnType = GetStakingProviderReturnType | undefined;
 
 /**
- * Hook to get staking provider
+ * React hook returning a registered staking provider; subscribes to provider-registry changes via {@link appkit:watchStakingProviders} 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 {@link appkit:getStakingProvider} action would throw).
+ *
+ * @param options - Optional provider `id`.
+ * @returns Matching staking provider instance, or `undefined` when none resolves.
+ *
+ * @public
+ * @category Hook
+ * @section Staking
  */
-export const useStakingProvider = (
-    options: GetStakingProviderOptions = {},
-): UseStakingProviderReturnType | undefined => {
+export const useStakingProvider = (options: GetStakingProviderOptions = {}): UseStakingProviderReturnType => {
     const appKit = useAppKit();
     const { id } = options;
 
diff --git a/packages/appkit-react/src/features/staking/hooks/use-staking-providers.ts b/packages/appkit-react/src/features/staking/hooks/use-staking-providers.ts
index 171964eb9..57cfe918f 100644
--- a/packages/appkit-react/src/features/staking/hooks/use-staking-providers.ts
+++ b/packages/appkit-react/src/features/staking/hooks/use-staking-providers.ts
@@ -12,10 +12,23 @@ import type { GetStakingProvidersReturnType } from '@ton/appkit';
 
 import { useAppKit } from '../../settings';
 
+/**
+ * Return type of {@link useStakingProviders} — array of registered staking providers.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type UseStakingProvidersReturnType = GetStakingProvidersReturnType;
 
 /**
- * Hook to get all registered staking providers.
+ * 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 {@link appkit:watchStakingProviders}.
+ *
+ * @returns Array of registered staking providers.
+ *
+ * @public
+ * @category Hook
+ * @section Staking
  */
 export const useStakingProviders = (): UseStakingProvidersReturnType => {
     const appKit = useAppKit();
diff --git a/packages/appkit-react/src/features/staking/hooks/use-staking-quote.ts b/packages/appkit-react/src/features/staking/hooks/use-staking-quote.ts
index 63b6cf409..2c04fdd68 100644
--- a/packages/appkit-react/src/features/staking/hooks/use-staking-quote.ts
+++ b/packages/appkit-react/src/features/staking/hooks/use-staking-quote.ts
@@ -14,14 +14,36 @@ import { useQuery } from '../../../libs/query';
 import type { UseQueryReturnType } from '../../../libs/query';
 import { useNetwork } from '../../network';
 
+/**
+ * Parameters accepted by {@link useStakingQuote} — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus stake/unstake amount, direction, target asset and optional `providerId`/network override.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type UseStakingQuoteParameters<selectData = GetStakingQuoteData> = GetStakingQuoteQueryConfig<selectData>;
+
+/**
+ * Return type of {@link useStakingQuote} — TanStack Query result carrying a {@link appkit:StakingQuote}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type UseStakingQuoteReturnType<selectData = GetStakingQuoteData> = UseQueryReturnType<
     selectData,
     GetStakingQuoteErrorType
 >;
 
 /**
- * Hook to get staking/unstaking quote
+ * React hook quoting a stake or unstake through TanStack Query (wraps {@link appkit:getStakingQuote}) — returns the rate, expected output and provider metadata needed to feed into {@link useBuildStakeTransaction}. 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.
+ *
+ * @param parameters - {@link UseStakingQuoteParameters} Quote parameters, optional `providerId`, optional network override, and TanStack Query overrides.
+ * @returns TanStack Query result for the quote read.
+ *
+ * @public
+ * @category Hook
+ * @section Staking
  */
 export const useStakingQuote = <selectData = GetStakingQuoteData>(
     parameters: UseStakingQuoteParameters<selectData> = {},
diff --git a/packages/appkit-react/src/features/swap/components/swap-field/swap-field.tsx b/packages/appkit-react/src/features/swap/components/swap-field/swap-field.tsx
index 5c579deb9..f7763e42c 100644
--- a/packages/appkit-react/src/features/swap/components/swap-field/swap-field.tsx
+++ b/packages/appkit-react/src/features/swap/components/swap-field/swap-field.tsx
@@ -18,20 +18,45 @@ import type { AppkitUIToken } from '../../../../types/appkit-ui-token';
 import { getDisplayAmount } from '../../utils/get-display-amount';
 import styles from './swap-field.module.css';
 
+/**
+ * Props accepted by {@link SwapField} — a single source/target row inside the swap widget that hosts the amount input, token picker trigger, fiat conversion and balance line.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export interface SwapFieldProps extends Omit<ComponentProps<typeof Input.Container>, 'children'> {
+    /** `pay` renders the editable source row with a "max" shortcut; `receive` renders the read-only target row. */
     type: 'pay' | 'receive';
+    /** Current amount shown in the input as a human-readable decimal string. */
     amount: string;
+    /** Fiat currency symbol displayed in front of the converted value. Defaults to `"$"`. */
     fiatSymbol?: string;
+    /** Currently selected token; controls the token selector label, balance formatting and fiat conversion. */
     token?: AppkitUIToken;
+    /** Called with the raw input value when the user edits the amount. Only fired for `type: "pay"`. */
     onAmountChange?: (value: string) => void;
+    /** Formatted balance of `token` for the active wallet, as a human-readable decimal string; rendered in the balance line beneath the input. */
     balance?: string;
+    /** When true, the balance area renders a skeleton placeholder instead of the value. */
     isBalanceLoading?: boolean;
+    /** When true, the underlying input renders its loading state — used while a fresh quote is in flight. */
     loading?: boolean;
+    /** Called when the user clicks the "max" shortcut to fill the maximum spendable amount. */
     onMaxClick?: () => void;
+    /** Called when the user clicks the token selector chip — typically opens a `SwapTokenSelectModal`. */
     onTokenSelectorClick?: () => void;
+    /** Reserved flag indicating whether a wallet is connected — currently accepted for API symmetry. */
     isWalletConnected?: boolean;
 }
 
+/**
+ * One row of the swap form. Renders the amount input, fiat conversion, balance line, and a token-selector chip. The `pay` variant is editable and exposes a "max" shortcut; the `receive` variant is read-only and shows the quote result.
+ *
+ * @public
+ * @category Component
+ * @section Swap
+ */
 export const SwapField: FC<SwapFieldProps> = ({
     type,
     token,
diff --git a/packages/appkit-react/src/features/swap/components/swap-flip-button/swap-flip-button.tsx b/packages/appkit-react/src/features/swap/components/swap-flip-button/swap-flip-button.tsx
index 3ddf3f305..84e980e24 100644
--- a/packages/appkit-react/src/features/swap/components/swap-flip-button/swap-flip-button.tsx
+++ b/packages/appkit-react/src/features/swap/components/swap-flip-button/swap-flip-button.tsx
@@ -13,11 +13,27 @@ import styles from './swap-flip-button.module.css';
 import { Button } from '../../../../components/ui/button';
 import { FlipIcon } from '../../../../components/ui/icons';
 
+/**
+ * Props accepted by {@link SwapFlipButton} — the round button placed between the two {@link SwapField} rows that swaps the source and target tokens.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export interface SwapFlipButtonProps extends ComponentProps<'div'> {
+    /** Called when the user clicks the button. Wire this to a handler that swaps the source/target tokens (e.g. `onFlip` from the swap context). */
     onClick?: () => void;
+    /** When true, the icon is drawn in its rotated state — used to animate between flips. */
     rotated?: boolean;
 }
 
+/**
+ * Round button rendered between the source and target {@link SwapField} rows. Clicking it flips the selected tokens; visual rotation is driven by `rotated`.
+ *
+ * @public
+ * @category Component
+ * @section Swap
+ */
 export const SwapFlipButton: FC<SwapFlipButtonProps> = ({ onClick, rotated, className, ...props }) => {
     return (
         <div className={clsx(styles.container, className)} {...props}>
diff --git a/packages/appkit-react/src/features/swap/components/swap-info/swap-info.tsx b/packages/appkit-react/src/features/swap/components/swap-info/swap-info.tsx
index 463385540..e3c3ccf27 100644
--- a/packages/appkit-react/src/features/swap/components/swap-info/swap-info.tsx
+++ b/packages/appkit-react/src/features/swap/components/swap-info/swap-info.tsx
@@ -14,14 +14,33 @@ import { useI18n } from '../../../settings/hooks/use-i18n';
 import type { AppkitUIToken } from '../../../../types/appkit-ui-token';
 import { getDisplayAmount } from '../../utils/get-display-amount';
 
+/**
+ * Props accepted by {@link SwapInfo} — the summary block under the swap form that surfaces minimum received, slippage and the chosen provider.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export interface SwapInfoProps extends ComponentProps<typeof InfoBlock.Container> {
+    /** Target token the user is receiving; used to format `minReceived` with the right decimals and symbol. */
     toToken: AppkitUIToken | null;
+    /** Slippage tolerance in basis points (`100` = 1%). Rendered as a percentage. */
     slippage: number;
+    /** Current {@link appkit:SwapProvider}; its display name is shown in the provider row. */
     provider?: SwapProvider;
+    /** Quote whose `minReceived` value is displayed; when undefined the value falls back to `0` (still suffixed with the token symbol). */
     quote?: SwapQuote;
+    /** When true, the minimum-received value renders a skeleton placeholder instead of the formatted number. */
     isQuoteLoading?: boolean;
 }
 
+/**
+ * Summary block rendered under the swap form. Shows the minimum amount the user is guaranteed to receive after slippage, the configured slippage tolerance, and the active {@link appkit:SwapProvider}.
+ *
+ * @public
+ * @category Component
+ * @section Swap
+ */
 export const SwapInfo: FC<SwapInfoProps> = ({ quote, provider, toToken, slippage, isQuoteLoading, ...props }) => {
     const { t } = useI18n();
 
diff --git a/packages/appkit-react/src/features/swap/components/swap-settings-modal/swap-settings-modal.tsx b/packages/appkit-react/src/features/swap/components/swap-settings-modal/swap-settings-modal.tsx
index 277ff8db8..cdbc561ce 100644
--- a/packages/appkit-react/src/features/swap/components/swap-settings-modal/swap-settings-modal.tsx
+++ b/packages/appkit-react/src/features/swap/components/swap-settings-modal/swap-settings-modal.tsx
@@ -23,16 +23,37 @@ const formatSlippage = (bps: number): string => `${(bps / 100).toFixed(2)}%`;
 
 const SLIPPAGE_OPTIONS = SLIPPAGE_PRESETS.map((bps) => ({ value: String(bps), label: formatSlippage(bps) }));
 
+/**
+ * Props accepted by `SwapSettingsModal` — the modal that lets the user pick a {@link appkit:SwapProvider} and a slippage preset before confirming a swap.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export interface SwapSettingsModalProps {
+    /** Controls modal visibility. */
     open: boolean;
+    /** Called when the user dismisses the modal (close icon, overlay click, or after pressing "save"). */
     onClose: () => void;
+    /** Current slippage tolerance in basis points (`100` = 1%); seeds the staged value when the modal opens. */
     slippage: number;
+    /** Called with the newly selected slippage in basis points when the user presses "save". */
     onSlippageChange: (bps: number) => void;
+    /** Currently active swap provider; its `providerId` seeds the staged selection. */
     provider: SwapProvider | undefined;
+    /** All swap providers available for selection — each gets a switcher option. */
     providers: SwapProvider[];
+    /** Called with the newly selected `providerId` when the user presses "save". */
     onProviderChange: (providerId: string) => void;
 }
 
+/**
+ * Modal that exposes per-swap settings: the {@link appkit:SwapProvider} and a slippage preset. Selections are staged locally and committed via `onSlippageChange` / `onProviderChange` only when the user presses "save"; closing without saving discards them.
+ *
+ * @public
+ * @category Component
+ * @section Swap
+ */
 export const SwapSettingsModal: FC<SwapSettingsModalProps> = ({
     open,
     onClose,
diff --git a/packages/appkit-react/src/features/swap/components/swap-token-select-modal/swap-token-select-modal.tsx b/packages/appkit-react/src/features/swap/components/swap-token-select-modal/swap-token-select-modal.tsx
index 05a849ada..74f61175c 100644
--- a/packages/appkit-react/src/features/swap/components/swap-token-select-modal/swap-token-select-modal.tsx
+++ b/packages/appkit-react/src/features/swap/components/swap-token-select-modal/swap-token-select-modal.tsx
@@ -12,8 +12,22 @@ import { TokenSelectModal } from '../../../../components/shared/token-select-mod
 import type { TokenSelectModalProps } from '../../../../components/shared/token-select-modal';
 import { useI18n } from '../../../settings/hooks/use-i18n';
 
+/**
+ * Props accepted by `SwapTokenSelectModal` — same shape as the underlying {@link TokenSelectModalProps} but with the title and search placeholder fixed to the swap-flow strings.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export type SwapTokenSelectModalProps = Omit<TokenSelectModalProps, 'title' | 'searchPlaceholder'>;
 
+/**
+ * Token picker used by the swap widget — thin wrapper around the shared `TokenSelectModal` that hard-codes the swap-specific title and search placeholder.
+ *
+ * @public
+ * @category Component
+ * @section Swap
+ */
 export const SwapTokenSelectModal: FC<SwapTokenSelectModalProps> = (props) => {
     const { t } = useI18n();
 
diff --git a/packages/appkit-react/src/features/swap/components/swap-widget-provider/swap-widget-provider.tsx b/packages/appkit-react/src/features/swap/components/swap-widget-provider/swap-widget-provider.tsx
index b4179f591..c68008225 100644
--- a/packages/appkit-react/src/features/swap/components/swap-widget-provider/swap-widget-provider.tsx
+++ b/packages/appkit-react/src/features/swap/components/swap-widget-provider/swap-widget-provider.tsx
@@ -35,8 +35,11 @@ import { useSwapValidation } from './use-swap-validation';
 export type { AppkitUIToken };
 
 /**
- * Context type for the SwapWidget.
- * Provides all necessary state and actions for building custom swap UIs.
+ * Shape of the value exposed by {@link useSwapContext}. Holds the selected source/target tokens, the entered amount and the latest quote, balance readouts, validation state, slippage / provider settings, and the callbacks needed to mutate them or to submit the swap transaction.
+ *
+ * @public
+ * @category Type
+ * @section Swap
  */
 export interface SwapContextType {
     /** Full list of available tokens for swapping */
@@ -141,34 +144,47 @@ export const SwapContext = createContext<SwapContextType>({
 });
 
 /**
- * Hook to access the swap context.
- * Must be used within a SwapWidgetProvider (or SwapWidget).
+ * Reads the {@link SwapContextType} populated by the nearest {@link SwapWidgetProvider} (or the {@link SwapWidget} that mounts one). Outside a provider it returns the no-op default value.
+ *
+ * @public
+ * @category Hook
+ * @section Swap
  */
 export const useSwapContext = () => {
     return useContext(SwapContext);
 };
 
 /**
- * Props for the SwapWidgetProvider.
+ * Props accepted by {@link SwapWidgetProvider} — the inputs that configure the swap flow (token universe, network override, defaults).
+ *
+ * @public
+ * @category Type
+ * @section Swap
  */
 export interface SwapProviderProps extends PropsWithChildren {
-    /** Full list of tokens available for swapping in the UI */
+    /** Full list of tokens available for swapping in the UI. Filtered to the active network internally. */
     tokens: AppkitUIToken[];
-    /** Optional section configs for grouping tokens in the selector */
+    /** Optional section configs for grouping tokens inside the `SwapTokenSelectModal`. */
     tokenSections?: TokenSectionConfig[];
-    /** Ticker of the token pre-selected for the source */
+    /** Symbol of the token pre-selected as the source on first mount (e.g. `"TON"`). */
     defaultFromSymbol?: string;
-    /** Ticker of the token pre-selected for the target */
+    /** Symbol of the token pre-selected as the target on first mount. */
     defaultToSymbol?: string;
-    /** Initial slippage in basis points (100 = 1%), defaults to 50 (0.5%) */
-    /** Network to use for quote fetching. When omitted, uses the selected wallet's network. */
+    /** Network used for quote fetching and balance reads. When omitted, falls back to the selected wallet's network via {@link useNetwork}. */
     network?: Network;
-    /** Fiat currency symbol for price display, defaults to "$" */
+    /** Fiat currency symbol displayed next to converted amounts. Defaults to `"$"`. */
     fiatSymbol?: string;
-    /** Initial slippage in basis points (100 = 1%), defaults to 100 (1%) */
+    /** Initial slippage tolerance in basis points (`100` = 1%). Defaults to `100`. */
     defaultSlippage?: number;
 }
 
+/**
+ * Provider that wires up the full swap state machine — debounces the entered amount, fetches the quote via {@link useSwapQuote}, reads source/target balances, validates the input, exposes the active {@link appkit:SwapProvider}, and offers `sendSwapTransaction` which builds the transaction with {@link useBuildSwapTransaction} and sends it (raising the low-balance warning when the outflow exceeds the user's TON balance). Children read everything through {@link useSwapContext}.
+ *
+ * @public
+ * @category Component
+ * @section Swap
+ */
 export const SwapWidgetProvider: FC<SwapProviderProps> = ({
     children,
     tokens,
diff --git a/packages/appkit-react/src/features/swap/components/swap-widget-ui/swap-widget-ui.tsx b/packages/appkit-react/src/features/swap/components/swap-widget-ui/swap-widget-ui.tsx
index 4a5ec13b2..f44568856 100644
--- a/packages/appkit-react/src/features/swap/components/swap-widget-ui/swap-widget-ui.tsx
+++ b/packages/appkit-react/src/features/swap/components/swap-widget-ui/swap-widget-ui.tsx
@@ -23,8 +23,22 @@ import type { SwapContextType } from '../swap-widget-provider';
 import { ButtonWithConnect } from '../../../../components/shared/button-with-connect';
 import { SettingsButton } from '../../../../components/shared/settings-button';
 
+/**
+ * Props accepted by {@link SwapWidgetUI} (and the `children` render-prop on {@link SwapWidget}). Combines the full {@link SwapContextType} with the standard `<div>` attributes forwarded to the wrapper element.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export type SwapWidgetRenderProps = SwapContextType & ComponentProps<'div'>;
 
+/**
+ * Default visual implementation of the swap widget — composes {@link SwapField} (source, then target), a {@link SwapFlipButton} between them, the submit button (auto-prompts wallet connect when no wallet is selected), the settings trigger that opens `SwapSettingsModal`, a `SwapTokenSelectModal` for picking source/target tokens, the {@link SwapInfo} summary, and a low-balance warning. Drives all state from the swap context props it receives — pair with {@link SwapWidgetProvider}, or use {@link SwapWidget} which mounts both.
+ *
+ * @public
+ * @category Component
+ * @section Swap
+ */
 export const SwapWidgetUI: FC<SwapWidgetRenderProps> = ({
     fromToken,
     toToken,
diff --git a/packages/appkit-react/src/features/swap/components/swap-widget/swap-widget.tsx b/packages/appkit-react/src/features/swap/components/swap-widget/swap-widget.tsx
index b9a2da12d..72974b94e 100644
--- a/packages/appkit-react/src/features/swap/components/swap-widget/swap-widget.tsx
+++ b/packages/appkit-react/src/features/swap/components/swap-widget/swap-widget.tsx
@@ -14,15 +14,14 @@ import { SwapWidgetProvider, useSwapContext } from '../swap-widget-provider';
 import type { SwapProviderProps } from '../swap-widget-provider';
 
 /**
- * Props for the SwapWidget component.
- * Inherits all configuration from SwapProviderProps.
+ * Props accepted by {@link SwapWidget} — extend {@link SwapProviderProps} (swap configuration: tokens, network, defaults) with the standard `<div>` attributes and an optional render-prop override.
+ *
+ * @public
+ * @category Type
+ * @section Swap
  */
 export interface SwapWidgetProps extends Omit<SwapProviderProps, 'children'>, Omit<ComponentProps<'div'>, 'children'> {
-    /**
-     * Custom render function.
-     * When provided, it replaces the default widget UI and gives full control over the rendering.
-     * Accesses all state and actions from the swap context.
-     */
+    /** Optional render-prop receiving the full swap context plus the forwarded `<div>` props; when supplied it replaces the default {@link SwapWidgetUI}. */
     children?: (props: SwapWidgetRenderProps) => ReactNode;
 }
 
@@ -39,11 +38,11 @@ const SwapWidgetContent: FC<
 };
 
 /**
- * A high-level component that provides a complete swap interface.
+ * Drop-in swap UI that walks the user through picking the source/target tokens, entering an amount, reviewing the quote (rate, min-received, slippage, provider), and confirming the swap — which builds the transaction via {@link useBuildSwapTransaction} and dispatches it through the standard send flow. Internally mounts a {@link SwapWidgetProvider} so the rendered UI (default {@link SwapWidgetUI} or a custom `children` render-prop) can read state through {@link useSwapContext}.
  *
- * It manages the token selection, quote fetching, and transaction building
- * for swaps between TON and Jettons. It can be used as a standalone widget
- * with default UI or customized using a render function.
+ * @public
+ * @category Component
+ * @section Swap
  */
 export const SwapWidget: FC<SwapWidgetProps> = ({
     children,
diff --git a/packages/appkit-react/src/features/swap/hooks/use-build-swap-transaction.ts b/packages/appkit-react/src/features/swap/hooks/use-build-swap-transaction.ts
index 9b2138f4d..01482c65e 100644
--- a/packages/appkit-react/src/features/swap/hooks/use-build-swap-transaction.ts
+++ b/packages/appkit-react/src/features/swap/hooks/use-build-swap-transaction.ts
@@ -20,8 +20,22 @@ import type {
 import { useAppKit } from '../../settings';
 import { useMutation } from '../../../libs/query';
 
+/**
+ * Parameters accepted by {@link useBuildSwapTransaction} — TanStack Query mutation options.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export type UseBuildSwapTransactionParameters<context = unknown> = BuildSwapTransactionMutationOptions<context>;
 
+/**
+ * Return type of {@link useBuildSwapTransaction} — TanStack Query mutation result.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export type UseBuildSwapTransactionReturnType<context = unknown> = UseMutationResult<
     BuildSwapTransactionData,
     BuildSwapTransactionErrorType,
@@ -30,7 +44,14 @@ export type UseBuildSwapTransactionReturnType<context = unknown> = UseMutationRe
 >;
 
 /**
- * Hook to build a swap transaction from a previously fetched quote.
+ * React mutation hook that wraps {@link appkit:buildSwapTransaction} — turns a {@link appkit:SwapQuote} obtained via {@link useSwapQuote} into a {@link appkit:TransactionRequest} without sending it, so the UI can inspect or batch before signing. Returns `mutate(params)` where `params` matches {@link appkit:BuildSwapTransactionOptions}.
+ *
+ * @param parameters - {@link UseBuildSwapTransactionParameters} TanStack Query mutation overrides.
+ * @returns Mutation result for the build call.
+ *
+ * @public
+ * @category Hook
+ * @section Swap
  */
 export const useBuildSwapTransaction = <context = unknown>(
     parameters?: UseBuildSwapTransactionParameters<context>,
diff --git a/packages/appkit-react/src/features/swap/hooks/use-swap-provider.ts b/packages/appkit-react/src/features/swap/hooks/use-swap-provider.ts
index f409bce2d..9016a16cb 100644
--- a/packages/appkit-react/src/features/swap/hooks/use-swap-provider.ts
+++ b/packages/appkit-react/src/features/swap/hooks/use-swap-provider.ts
@@ -12,11 +12,23 @@ import type { GetSwapProviderReturnType } from '@ton/appkit';
 
 import { useAppKit } from '../../settings/hooks/use-app-kit';
 
+/**
+ * Return type of {@link useSwapProvider} — `[provider, setProviderId]` tuple. `provider` is the default `SwapProviderInterface` (or `undefined` when none is registered); `setProviderId` calls {@link appkit:setDefaultSwapProvider} and emits `provider:default-changed`, which {@link appkit:watchSwapProviders} picks up.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export type UseSwapProviderReturnType = readonly [GetSwapProviderReturnType | undefined, (providerId: string) => void];
 
 /**
- * Hook to get and set the currently selected swap provider.
- * Mirrors the tuple shape of `useSelectedWallet`.
+ * Read and switch the default swap provider — subscribes to {@link appkit:watchSwapProviders} and re-reads via {@link appkit:getSwapProvider}. Returns a `useState`-style tuple; the read swallows the throw from {@link appkit:getSwapProvider} (which throws when no provider matches — or when no id is passed and no default has been registered) and yields `undefined` instead.
+ *
+ * @returns Tuple `[provider, setProviderId]`.
+ *
+ * @public
+ * @category Hook
+ * @section Swap
  */
 export const useSwapProvider = (): UseSwapProviderReturnType => {
     const appKit = useAppKit();
diff --git a/packages/appkit-react/src/features/swap/hooks/use-swap-providers.ts b/packages/appkit-react/src/features/swap/hooks/use-swap-providers.ts
index 97d9a8ec9..25429a195 100644
--- a/packages/appkit-react/src/features/swap/hooks/use-swap-providers.ts
+++ b/packages/appkit-react/src/features/swap/hooks/use-swap-providers.ts
@@ -12,10 +12,23 @@ import type { GetSwapProvidersReturnType } from '@ton/appkit';
 
 import { useAppKit } from '../../settings/hooks/use-app-kit';
 
+/**
+ * Return type of {@link useSwapProviders} — array of every `SwapProviderInterface` currently registered on the AppKit instance.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export type UseSwapProvidersReturnType = GetSwapProvidersReturnType;
 
 /**
- * Hook to get all registered swap providers.
+ * List every swap provider registered on the AppKit instance (both those passed via {@link appkit:AppKitConfig}'s `providers` and those added later through {@link appkit:registerProvider}); subscribes to {@link appkit:watchSwapProviders} and re-reads via {@link appkit:getSwapProviders} so the array stays in sync.
+ *
+ * @returns Array of registered swap providers.
+ *
+ * @public
+ * @category Hook
+ * @section Swap
  */
 export const useSwapProviders = (): UseSwapProvidersReturnType => {
     const appKit = useAppKit();
diff --git a/packages/appkit-react/src/features/swap/hooks/use-swap-quote.ts b/packages/appkit-react/src/features/swap/hooks/use-swap-quote.ts
index 54cdb5971..ea90206e2 100644
--- a/packages/appkit-react/src/features/swap/hooks/use-swap-quote.ts
+++ b/packages/appkit-react/src/features/swap/hooks/use-swap-quote.ts
@@ -16,15 +16,36 @@ import { useQuery } from '../../../libs/query';
 import type { UseQueryReturnType } from '../../../libs/query';
 import { useNetwork } from '../../network';
 
+/**
+ * Parameters accepted by {@link useSwapQuote} — TanStack Query options (`select`, `enabled`, `staleTime`, …) plus the {@link appkit:SwapQuoteParams} fields (source/target tokens, amount, `isReverseSwap` flag) and an optional `providerId` / network override.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export type UseSwapQuoteParameters<selectData = GetSwapQuoteData> = GetSwapQuoteQueryConfig<selectData>;
 
+/**
+ * Return type of {@link useSwapQuote} — TanStack Query result carrying `data` ({@link appkit:SwapQuote}), `isLoading`, `error` and the standard companions.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export type UseSwapQuoteReturnType<selectData = GetSwapQuoteData> = UseQueryReturnType<
     selectData,
     GetSwapQuoteErrorType
 >;
 
 /**
- * Hook to get a swap quote for the given token pair and amount.
+ * React hook fetching a swap quote through TanStack Query — wraps {@link appkit:getSwapQuote}. The resulting `data` is the {@link appkit:SwapQuote} payload required to call {@link appkit:buildSwapTransaction} (see {@link useBuildSwapTransaction}). 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.
+ *
+ * @param parameters - {@link UseSwapQuoteParameters} Source and target tokens, amount, optional network/provider override, and TanStack Query overrides.
+ * @returns TanStack Query result for the swap quote.
+ *
+ * @public
+ * @category Hook
+ * @section Swap
  */
 export const useSwapQuote = <selectData = GetSwapQuoteData>(
     parameters: UseSwapQuoteParameters<selectData> = {},
diff --git a/packages/appkit-react/src/features/transaction/components/transaction-progress/transaction-progress.tsx b/packages/appkit-react/src/features/transaction/components/transaction-progress/transaction-progress.tsx
index 8cc866cf1..51b284727 100644
--- a/packages/appkit-react/src/features/transaction/components/transaction-progress/transaction-progress.tsx
+++ b/packages/appkit-react/src/features/transaction/components/transaction-progress/transaction-progress.tsx
@@ -27,7 +27,7 @@ export interface TransactionProgressRenderProps extends TransactionProgressConte
 }
 
 export interface TransactionProgressProps extends Omit<ComponentProps<'div'>, 'children'> {
-    /** BOC of the transaction to strictly track status */
+    /** BoC of the transaction to strictly track status */
     boc: string;
     /** Render props function for full control over rendering */
     children?: (props: TransactionProgressRenderProps) => ReactNode;
diff --git a/packages/appkit-react/src/features/transaction/hooks/use-send-transaction.ts b/packages/appkit-react/src/features/transaction/hooks/use-send-transaction.ts
index b8aca2b68..cfd337f1d 100644
--- a/packages/appkit-react/src/features/transaction/hooks/use-send-transaction.ts
+++ b/packages/appkit-react/src/features/transaction/hooks/use-send-transaction.ts
@@ -21,8 +21,22 @@ import { useMutation } from '../../../libs/query';
 import type { UseMutationReturnType } from '../../../libs/query';
 import { useAppKit } from '../../settings';
 
+/**
+ * Parameters accepted by {@link useSendTransaction} — TanStack Query mutation options.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export type UseSendTransactionParameters<context = unknown> = SendTransactionOptions<context>;
 
+/**
+ * Return type of {@link useSendTransaction} — TanStack Query mutation result.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export type UseSendTransactionReturnType<context = unknown> = UseMutationReturnType<
     SendTransactionData,
     SendTransactionErrorType,
@@ -35,6 +49,16 @@ export type UseSendTransactionReturnType<context = unknown> = UseMutationReturnT
     MutateFunction<SendTransactionData, SendTransactionErrorType, SendTransactionVariables, context>
 >;
 
+/**
+ * React mutation hook that hands a pre-built {@link appkit:TransactionRequest} to the selected wallet for signing and broadcast (wraps {@link appkit:sendTransaction}); returns `mutate(request)`. The underlying action throws `Error('Wallet not connected')` if no wallet is currently selected — TanStack Query surfaces it via the mutation's `error`.
+ *
+ * @param parameters - {@link UseSendTransactionParameters} TanStack Query mutation overrides.
+ * @returns Mutation result for the send call.
+ *
+ * @public
+ * @category Hook
+ * @section Transactions
+ */
 export const useSendTransaction = <context = unknown>(
     parameters: UseSendTransactionParameters<context> = {},
 ): UseSendTransactionReturnType<context> => {
diff --git a/packages/appkit-react/src/features/transaction/hooks/use-transaction-status.ts b/packages/appkit-react/src/features/transaction/hooks/use-transaction-status.ts
index a1b4d5d65..49df6571a 100644
--- a/packages/appkit-react/src/features/transaction/hooks/use-transaction-status.ts
+++ b/packages/appkit-react/src/features/transaction/hooks/use-transaction-status.ts
@@ -19,33 +19,37 @@ import type { UseQueryReturnType } from '../../../libs/query';
 import { useAppKit } from '../../settings';
 import { useNetwork } from '../../network';
 
+/**
+ * Parameters accepted by {@link useTransactionStatus} — `boc` xor `normalizedHash` plus optional network and TanStack Query overrides; pair with `query.refetchInterval` to poll until the transaction completes.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export type UseTransactionStatusParameters<selectData = GetTransactionStatusData> = GetTransactionStatusParameters &
     GetTransactionStatusQueryConfig<selectData>;
 
+/**
+ * Return type of {@link useTransactionStatus} — TanStack Query result for the status read.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export type UseTransactionStatusReturnType<selectData = GetTransactionStatusData> = UseQueryReturnType<
     selectData,
     GetTransactionStatusErrorType
 >;
 
 /**
- * Hook to get the status of a transaction trace by BOC.
- *
- * This hook polls the toncenter API to track the progress of a transaction trace.
- * It is useful for tracking complex operations like swaps or multi-step flows.
+ * React hook that reads the trace status of a sent transaction (wraps {@link appkit:getTransactionStatus}); typically paired with `refetchInterval` to poll until the trace completes. The underlying action throws `Error('Either boc or normalizedHash must be provided')` when neither field is supplied — TanStack Query surfaces it via the query's `error`.
  *
- * @example
- * ```ts
- * const { data: status } = useTransactionStatus({
- *   boc: 'te6cc...',
- *   query: {
- *     refetchInterval: 2000, // Poll every 2 seconds
- *   }
- * });
+ * @param parameters - {@link UseTransactionStatusParameters} `boc` xor `normalizedHash`, optional network and TanStack Query overrides.
+ * @returns TanStack Query result for the status read.
  *
- * if (status?.status === 'pending') {
- *   console.log(`Progress: ${status.completedMessages}/${status.totalMessages}`);
- * }
- * ```
+ * @public
+ * @category Hook
+ * @section Transactions
  */
 export const useTransactionStatus = <selectData = GetTransactionStatusData>(
     parameters: UseTransactionStatusParameters<selectData>,
diff --git a/packages/appkit-react/src/features/transaction/hooks/use-transfer-ton.ts b/packages/appkit-react/src/features/transaction/hooks/use-transfer-ton.ts
index d1d65f1ec..21de6cc6b 100644
--- a/packages/appkit-react/src/features/transaction/hooks/use-transfer-ton.ts
+++ b/packages/appkit-react/src/features/transaction/hooks/use-transfer-ton.ts
@@ -21,8 +21,22 @@ import { useMutation } from '../../../libs/query';
 import type { UseMutationReturnType } from '../../../libs/query';
 import { useAppKit } from '../../settings';
 
+/**
+ * Parameters accepted by {@link useTransferTon} — TanStack Query mutation options.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export type UseTransferTonParameters<context = unknown> = TransferTonOptions<context>;
 
+/**
+ * Return type of {@link useTransferTon} — TanStack Query mutation result.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export type UseTransferTonReturnType<context = unknown> = UseMutationReturnType<
     TransferTonData,
     TransferTonErrorType,
@@ -35,6 +49,16 @@ export type UseTransferTonReturnType<context = unknown> = UseMutationReturnType<
     MutateFunction<TransferTonData, TransferTonErrorType, TransferTonVariables, context>
 >;
 
+/**
+ * React mutation hook that builds and sends a TON transfer from the selected wallet in one step (wraps {@link appkit:transferTon}); returns `mutate({ recipientAddress, amount, comment?, payload?, stateInit? })`. The underlying action throws `Error('Wallet not connected')` if no wallet is currently selected — TanStack Query surfaces it via the mutation's `error`.
+ *
+ * @param parameters - {@link UseTransferTonParameters} TanStack Query mutation overrides.
+ * @returns Mutation result for the transfer call.
+ *
+ * @public
+ * @category Hook
+ * @section Transactions
+ */
 export const useTransferTon = <context = unknown>(
     parameters: UseTransferTonParameters<context> = {},
 ): UseTransferTonReturnType<context> => {
diff --git a/packages/appkit-react/src/features/transaction/hooks/use-watch-transactions-by-address.ts b/packages/appkit-react/src/features/transaction/hooks/use-watch-transactions-by-address.ts
index 06886c82d..6e0f7a366 100644
--- a/packages/appkit-react/src/features/transaction/hooks/use-watch-transactions-by-address.ts
+++ b/packages/appkit-react/src/features/transaction/hooks/use-watch-transactions-by-address.ts
@@ -12,10 +12,25 @@ import type { WatchTransactionsByAddressOptions, TransactionsUpdate } from '@ton
 
 import { useAppKit } from '../../settings';
 
+/**
+ * Parameters accepted by {@link useWatchTransactionsByAddress} — same fields as {@link appkit:WatchTransactionsByAddressOptions}, all optional so callers can render the hook before the address is known.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export type UseWatchTransactionsByAddressParameters = Partial<WatchTransactionsByAddressOptions>;
 
 /**
- * Hook to watch transactions for a specific address in real-time.
+ * Subscribe to incoming-transaction events for an arbitrary address (use {@link useWatchTransactions} for the selected wallet); logs a warning and exits when no streaming provider is configured for the resolved network or no `onChange` callback was provided.
+ *
+ * @param parameters - {@link UseWatchTransactionsByAddressParameters} Address, update callback and optional network override.
+ *
+ * @sample docs/examples/src/appkit/hooks/transaction#USE_WATCH_TRANSACTIONS_BY_ADDRESS
+ *
+ * @public
+ * @category Hook
+ * @section Transactions
  */
 export const useWatchTransactionsByAddress = (parameters: UseWatchTransactionsByAddressParameters): void => {
     const { address, network } = parameters;
diff --git a/packages/appkit-react/src/features/transaction/hooks/use-watch-transactions.ts b/packages/appkit-react/src/features/transaction/hooks/use-watch-transactions.ts
index 4e1fa5a63..748efc79c 100644
--- a/packages/appkit-react/src/features/transaction/hooks/use-watch-transactions.ts
+++ b/packages/appkit-react/src/features/transaction/hooks/use-watch-transactions.ts
@@ -12,12 +12,28 @@ import { useAddress } from '../../wallets/hooks/use-address';
 import { useNetwork } from '../../network/hooks/use-network';
 import { useWatchTransactionsByAddress } from './use-watch-transactions-by-address';
 
+/**
+ * Parameters accepted by {@link useWatchTransactions}.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export interface UseWatchTransactionsParameters {
+    /** Callback fired on every transactions update from the streaming provider. */
     onChange?: (update: TransactionsUpdate) => void;
 }
 
 /**
- * Hook to watch transaction updates of the currently selected wallet in real-time.
+ * Subscribe to incoming-transaction events for the currently selected wallet (use {@link useWatchTransactionsByAddress} for a fixed address); auto-rebinds when the user connects, switches or disconnects.
+ *
+ * @param parameters - {@link UseWatchTransactionsParameters} Update callback.
+ *
+ * @sample docs/examples/src/appkit/hooks/transaction#USE_WATCH_TRANSACTIONS
+ *
+ * @public
+ * @category Hook
+ * @section Transactions
  */
 export const useWatchTransactions = (parameters: UseWatchTransactionsParameters = {}): void => {
     const address = useAddress();
diff --git a/packages/appkit-react/src/features/wallets/hooks/use-address.ts b/packages/appkit-react/src/features/wallets/hooks/use-address.ts
index f643f5239..8f98392f2 100644
--- a/packages/appkit-react/src/features/wallets/hooks/use-address.ts
+++ b/packages/appkit-react/src/features/wallets/hooks/use-address.ts
@@ -10,10 +10,23 @@ import { useMemo } from 'react';
 
 import { useSelectedWallet } from './use-selected-wallet';
 
+/**
+ * Return type of {@link useAddress} — `undefined` when no wallet is selected.
+ *
+ * @public
+ * @category Type
+ * @section Wallets
+ */
 export type UseAddressReturnType = string | undefined;
 
 /**
- * Hook to get current wallet address
+ * Read the user-friendly address of the currently selected wallet; re-renders when the selection changes.
+ *
+ * @returns Selected wallet's address, or `undefined` when none is selected.
+ *
+ * @public
+ * @category Hook
+ * @section Wallets
  */
 export const useAddress = (): UseAddressReturnType => {
     const [wallet] = useSelectedWallet();
diff --git a/packages/appkit-react/src/features/wallets/hooks/use-connect.ts b/packages/appkit-react/src/features/wallets/hooks/use-connect.ts
index 014bba94e..aaa5a3487 100644
--- a/packages/appkit-react/src/features/wallets/hooks/use-connect.ts
+++ b/packages/appkit-react/src/features/wallets/hooks/use-connect.ts
@@ -14,8 +14,22 @@ import { useMutation } from '../../../libs/query';
 import type { UseMutationReturnType } from '../../../libs/query';
 import { useAppKit } from '../../settings';
 
+/**
+ * Parameters accepted by {@link useConnect} — TanStack Query mutation options (`onSuccess`, `onError`, `onMutate`, `retry`, …).
+ *
+ * @public
+ * @category Type
+ * @section Wallets
+ */
 export type UseConnectParameters<context = unknown> = ConnectOptions<context>;
 
+/**
+ * Return type of {@link useConnect} — TanStack Query mutation result with `mutate`/`mutateAsync` and the standard companions.
+ *
+ * @public
+ * @category Type
+ * @section Wallets
+ */
 export type UseConnectReturnType<context = unknown> = UseMutationReturnType<
     ConnectData,
     ConnectErrorType,
@@ -28,6 +42,16 @@ export type UseConnectReturnType<context = unknown> = UseMutationReturnType<
     MutateFunction<ConnectData, ConnectErrorType, ConnectVariables, context>
 >;
 
+/**
+ * React mutation hook that triggers the connection flow on a registered connector by id (wraps {@link appkit:connect}); returns `mutate({ connectorId })` you call from event handlers. The underlying action throws `Error('Connector with id "<id>" not found')` when no connector with that id is registered — TanStack Query surfaces it via the mutation's `error`.
+ *
+ * @param parameters - {@link UseConnectParameters} TanStack Query mutation overrides.
+ * @returns Mutation result for the connect call.
+ *
+ * @public
+ * @category Hook
+ * @section Wallets
+ */
 export const useConnect = <context = unknown>(
     parameters: UseConnectParameters<context> = {},
 ): UseConnectReturnType<context> => {
diff --git a/packages/appkit-react/src/features/wallets/hooks/use-connected-wallets.ts b/packages/appkit-react/src/features/wallets/hooks/use-connected-wallets.ts
index b473d3093..e7c0ab917 100644
--- a/packages/appkit-react/src/features/wallets/hooks/use-connected-wallets.ts
+++ b/packages/appkit-react/src/features/wallets/hooks/use-connected-wallets.ts
@@ -12,8 +12,24 @@ import type { GetConnectedWalletsReturnType } from '@ton/appkit';
 
 import { useAppKit } from '../../settings';
 
+/**
+ * Return type of {@link useConnectedWallets} — same shape as {@link appkit:GetConnectedWalletsReturnType}.
+ *
+ * @public
+ * @category Type
+ * @section Wallets
+ */
 export type UseConnectedWalletsReturnType = GetConnectedWalletsReturnType;
 
+/**
+ * Read the list of currently connected wallets across all registered connectors; re-renders when a wallet connects or disconnects.
+ *
+ * @returns Read-only array of {@link appkit:WalletInterface}s.
+ *
+ * @public
+ * @category Hook
+ * @section Wallets
+ */
 export const useConnectedWallets = (): UseConnectedWalletsReturnType => {
     const appKit = useAppKit();
 
diff --git a/packages/appkit-react/src/features/wallets/hooks/use-connector-by-id.ts b/packages/appkit-react/src/features/wallets/hooks/use-connector-by-id.ts
index 3ebed506a..8fce85498 100644
--- a/packages/appkit-react/src/features/wallets/hooks/use-connector-by-id.ts
+++ b/packages/appkit-react/src/features/wallets/hooks/use-connector-by-id.ts
@@ -12,6 +12,16 @@ import type { Connector } from '@ton/appkit';
 
 import { useAppKit } from '../../settings';
 
+/**
+ * Read a connector by id (wraps {@link appkit:getConnectorById} + {@link appkit:watchConnectorById}); re-renders when the connector with that id is registered or unregistered (use {@link useConnectedWallets} to react to wallet connect/disconnect events).
+ *
+ * @param id - ID of the connector to look up.
+ * @returns The matching {@link appkit:Connector}, or `undefined` if none with that id is registered.
+ *
+ * @public
+ * @category Hook
+ * @section Connectors
+ */
 export const useConnectorById = (id: string): Connector | undefined => {
     const appKit = useAppKit();
 
diff --git a/packages/appkit-react/src/features/wallets/hooks/use-connectors.ts b/packages/appkit-react/src/features/wallets/hooks/use-connectors.ts
index 803600732..e9328b94a 100644
--- a/packages/appkit-react/src/features/wallets/hooks/use-connectors.ts
+++ b/packages/appkit-react/src/features/wallets/hooks/use-connectors.ts
@@ -12,8 +12,24 @@ import type { GetConnectorsReturnType } from '@ton/appkit';
 
 import { useAppKit } from '../../settings';
 
+/**
+ * Return type of {@link useConnectors} — same shape as {@link appkit:GetConnectorsReturnType}.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export type UseConnectorsReturnType = GetConnectorsReturnType;
 
+/**
+ * Read the list of connectors registered on this AppKit instance; re-renders when a connector is registered or unregistered (use {@link useConnectedWallets} to react to wallet connect/disconnect events).
+ *
+ * @returns Read-only array of registered {@link appkit:Connector}s.
+ *
+ * @public
+ * @category Hook
+ * @section Connectors
+ */
 export const useConnectors = (): UseConnectorsReturnType => {
     const appKit = useAppKit();
 
diff --git a/packages/appkit-react/src/features/wallets/hooks/use-disconnect.ts b/packages/appkit-react/src/features/wallets/hooks/use-disconnect.ts
index 9bf022804..9a9645d64 100644
--- a/packages/appkit-react/src/features/wallets/hooks/use-disconnect.ts
+++ b/packages/appkit-react/src/features/wallets/hooks/use-disconnect.ts
@@ -16,8 +16,22 @@ import { useMutation } from '../../../libs/query';
 import type { UseMutationReturnType } from '../../../libs/query';
 import { useAppKit } from '../../settings';
 
+/**
+ * Parameters accepted by {@link useDisconnect} — TanStack Query mutation options.
+ *
+ * @public
+ * @category Type
+ * @section Wallets
+ */
 export type UseDisconnectParameters<context = unknown> = DisconnectOptions<context>;
 
+/**
+ * Return type of {@link useDisconnect} — TanStack Query mutation result.
+ *
+ * @public
+ * @category Type
+ * @section Wallets
+ */
 export type UseDisconnectReturnType<context = unknown> = UseMutationReturnType<
     DisconnectData,
     DisconnectErrorType,
@@ -30,6 +44,16 @@ export type UseDisconnectReturnType<context = unknown> = UseMutationReturnType<
     MutateFunction<DisconnectData, DisconnectErrorType, DisconnectVariables, context>
 >;
 
+/**
+ * React mutation hook that disconnects the wallet currently connected through a registered connector (wraps {@link appkit:disconnect}); returns `mutate({ connectorId })` you call from event handlers. The underlying action throws `Error('Connector with id "<id>" not found')` when no connector with that id is registered — TanStack Query surfaces it via the mutation's `error`.
+ *
+ * @param parameters - {@link UseDisconnectParameters} TanStack Query mutation overrides.
+ * @returns Mutation result for the disconnect call.
+ *
+ * @public
+ * @category Hook
+ * @section Wallets
+ */
 export const useDisconnect = <context = unknown>(
     parameters: UseDisconnectParameters<context> = {},
 ): UseDisconnectReturnType<context> => {
diff --git a/packages/appkit-react/src/features/wallets/hooks/use-selected-wallet.ts b/packages/appkit-react/src/features/wallets/hooks/use-selected-wallet.ts
index 8e8c129c2..52efd0e6c 100644
--- a/packages/appkit-react/src/features/wallets/hooks/use-selected-wallet.ts
+++ b/packages/appkit-react/src/features/wallets/hooks/use-selected-wallet.ts
@@ -12,10 +12,23 @@ import type { GetSelectedWalletReturnType } from '@ton/appkit';
 
 import { useAppKit } from '../../settings';
 
+/**
+ * Return type of {@link useSelectedWallet} — `[wallet, setWalletId]` tuple. `wallet` is the active {@link appkit:WalletInterface} (or `null`); `setWalletId` calls {@link appkit:setSelectedWalletId} and emits `wallets:selection-changed`.
+ *
+ * @public
+ * @category Type
+ * @section Wallets
+ */
 export type UseSelectedWalletReturnType = readonly [GetSelectedWalletReturnType, (walletId: string | null) => void];
 
 /**
- * Hook to get the currently selected wallet
+ * Read and switch the wallet that AppKit treats as active — most action hooks ({@link useBalance}, {@link useSignText}, {@link useTransferTon}) target this wallet implicitly. Returns a `useState`-style tuple.
+ *
+ * @returns Tuple `[wallet, setWalletId]`.
+ *
+ * @public
+ * @category Hook
+ * @section Wallets
  */
 export const useSelectedWallet = (): UseSelectedWalletReturnType => {
     const appKit = useAppKit();
diff --git a/packages/appkit-react/src/providers/app-kit-provider.tsx b/packages/appkit-react/src/providers/app-kit-provider.tsx
index 82d859195..c1f966700 100644
--- a/packages/appkit-react/src/providers/app-kit-provider.tsx
+++ b/packages/appkit-react/src/providers/app-kit-provider.tsx
@@ -15,10 +15,25 @@ import { TonConnectBridge } from '../tonconnect/tonconnect-bridge';
 
 export const AppKitContext = createContext<AppKit | undefined>(undefined);
 
+/**
+ * Props accepted by {@link AppKitProvider}.
+ *
+ * @public
+ * @category Type
+ * @section Providers
+ */
 export interface AppKitProviderProps extends PropsWithChildren {
+    /** Runtime instance constructed at app startup; shared across every appkit-react hook and component. */
     appKit: AppKit;
 }
 
+/**
+ * Top-level React provider that wires AppKit, the TonConnect bridge and i18n into the component tree — wrap your app once near the root so descendant hooks ({@link useAppKit}, {@link useBalance}, …) and components can resolve their context.
+ *
+ * @public
+ * @category Component
+ * @section Providers
+ */
 export const AppKitProvider: FC<AppKitProviderProps> = ({ appKit, children }) => {
     return (
         <AppKitContext.Provider value={appKit}>
diff --git a/packages/appkit-react/src/providers/i18n-provider.tsx b/packages/appkit-react/src/providers/i18n-provider.tsx
index 3b8c6fdb6..75b024a28 100644
--- a/packages/appkit-react/src/providers/i18n-provider.tsx
+++ b/packages/appkit-react/src/providers/i18n-provider.tsx
@@ -12,20 +12,47 @@ import { createContext, useState, useRef, useEffect } from 'react';
 import type { Dict, I18n } from '../libs/i18n';
 import { i18n, defaultLanguage } from '../libs/i18n';
 
+/**
+ * Shape returned by {@link useI18n} — current locale, translation function and helpers to switch locales or merge new dictionaries at runtime.
+ *
+ * @public
+ * @category Type
+ * @section Providers
+ */
 export interface I18nContextType {
+    /** Currently active locale code (e.g., `"en"`, `"ru"`). */
     activeLocale: string;
+    /** Translation function — accepts a key plus interpolation values and returns the localized string. */
     t: I18n['t'];
+    /** Switch to a new locale; pass an optional `dict` to install translations alongside the switch. */
     locale: (lang: string, dict?: Dict) => void;
+    /** Merge a translation dictionary for `lang` without changing the active locale. */
     addDict: (lang: string, dict: Dict) => void;
 }
 
 export const I18nContext = createContext<I18nContextType | null>(null);
 
+/**
+ * Props accepted by {@link I18nProvider}.
+ *
+ * @public
+ * @category Type
+ * @section Providers
+ */
 export interface I18nProviderProps extends PropsWithChildren {
+    /** Initial locale code; defaults to the i18n library's default when omitted. */
     locale?: string;
+    /** Translation dictionaries keyed by locale; loaded into the underlying i18n instance on mount. */
     lngDicts?: Record<string, Dict>;
 }
 
+/**
+ * React provider that mounts the i18n context for {@link useI18n} and child components — already wrapped by {@link AppKitProvider}, so apps usually only render it directly when they need to override the locale or dictionaries.
+ *
+ * @public
+ * @category Component
+ * @section Providers
+ */
 export const I18nProvider = ({ children, locale, lngDicts }: I18nProviderProps) => {
     const activeLocaleRef = useRef(locale || defaultLanguage);
     const [, setTick] = useState(0);
diff --git a/packages/appkit-react/src/utils/map-defi-error.ts b/packages/appkit-react/src/utils/map-defi-error.ts
index 0a3b5ce7a..274c0fb25 100644
--- a/packages/appkit-react/src/utils/map-defi-error.ts
+++ b/packages/appkit-react/src/utils/map-defi-error.ts
@@ -10,7 +10,7 @@ import { DefiError } from '@ton/appkit';
 
 /**
  * Map a thrown error to an i18n key from the `defi.*` namespace.
- * Returns `null` when the error isn't a {@link DefiError} or the code isn't recognised —
+ * Returns `null` when the error isn't a {@link appkit:DefiError} or the code isn't recognised —
  * callers should decide on their own fallback (usually a domain-specific key).
  */
 export const mapDefiError = (error: unknown): string | null => {
diff --git a/packages/appkit/README.md b/packages/appkit/README.md
index a309e5553..cb67bcd35 100644
--- a/packages/appkit/README.md
+++ b/packages/appkit/README.md
@@ -1,7 +1,7 @@
 <!--
 This file is auto-generated. Do not edit manually.
 Changes will be overwritten when running the docs update script.
-Source template: template/packages/appkit/README.md
+Source template: docs/templates/packages/appkit/README.md
 -->
 
 # TonAppKit
@@ -72,7 +72,7 @@ const appKit = new AppKit({
 ```ts
 const balance = await getBalance(appKit);
 if (balance) {
-    console.log('Balance:', balance.toString());
+    console.log('Balance:', balance);
 }
 ```
  
diff --git a/packages/appkit/docs/actions.md b/packages/appkit/docs/actions.md
index 5c2280b02..d404e178b 100644
--- a/packages/appkit/docs/actions.md
+++ b/packages/appkit/docs/actions.md
@@ -1,7 +1,7 @@
 <!--
 This file is auto-generated. Do not edit manually.
 Changes will be overwritten when running the docs update script.
-Source template: template/packages/appkit/docs/actions.md
+Source template: docs/templates/packages/appkit/docs/actions.md
 -->
 
 # Actions
@@ -17,7 +17,7 @@ Get the TON balance of the currently selected wallet.
 ```ts
 const balance = await getBalance(appKit);
 if (balance) {
-    console.log('Balance:', balance.toString());
+    console.log('Balance:', balance);
 }
 ```
 
@@ -27,9 +27,9 @@ Fetch the TON balance of a specific address.
 
 ```ts
 const balanceByAddress = await getBalanceByAddress(appKit, {
-    address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c', // Zero Address
+    address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
 });
-console.log('Balance by address:', balanceByAddress.toString());
+console.log('Balance by address:', balanceByAddress);
 ```
 
 ### `watchBalance`
@@ -78,7 +78,7 @@ await connect(appKit, {
 Add a wallet connector to AppKit (e.g., TonConnect).
 
 ```ts
-const stopWatching = addConnector(
+const unregister = addConnector(
     appKit,
     createTonConnectConnector({
         tonConnectOptions: {
@@ -87,7 +87,7 @@ const stopWatching = addConnector(
     }),
 );
 
-// Later: stopWatching();
+// Later: unregister();
 ```
 
 ### `disconnect`
@@ -167,7 +167,7 @@ if (!response) {
     return;
 }
 console.log('Jettons:', response.jettons.length);
-response.jettons.forEach((j) => console.log(`- ${j.info.name}: ${j.balance.toString()}`));
+response.jettons.forEach((j) => console.log(`- ${j.info.name}: ${j.balance}`));
 ```
 
 ### `getJettonsByAddress`
@@ -185,7 +185,7 @@ 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.toString()}`));
+response.jettons.forEach((j) => console.log(`- ${j.info.name}: ${j.balance}`));
 ```
 
 ### `getJettonBalance`
@@ -204,7 +204,7 @@ const balance = await getJettonBalance(appKit, {
     ownerAddress: selectedWallet.getAddress(),
     jettonDecimals: 6,
 });
-console.log('Jetton Balance:', balance.toString());
+console.log('Jetton Balance:', balance);
 ```
 
 ### `getJettonInfo`
@@ -390,7 +390,7 @@ Get all NFTs owned by a specific address.
 
 ```ts
 const response = await getNftsByAddress(appKit, {
-    address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c', // Zero Address
+    address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
 });
 
 console.log('NFTs by address:', response.nfts.length);
@@ -563,7 +563,7 @@ Sign a TON Cell with the connected wallet. Used for on-chain signature verificat
 
 ```ts
 const result = await signCell(appKit, {
-    cell: 'te6ccgEBAQEAAgAAGA==' as Base64String, // Example BOC
+    cell: 'te6ccgEBAQEAAgAAGA==' as Base64String, // Example BoC
     schema: 'transfer#abc123 amount:uint64 = Transfer',
 });
 
@@ -657,7 +657,7 @@ console.log('Swap Transaction:', transactionResponse);
 Get all available staking provider IDs.
 
 ```ts
-const providers = await getStakingProviders(appKit);
+const providers = getStakingProviders(appKit);
 console.log('Available Staking Providers:', providers);
 ```
 
@@ -725,7 +725,7 @@ console.log('Staked Balance:', balance);
 Create a TON transfer transaction request without sending it.
  
 ```ts
-const tx = await createTransferTonTransaction(appKit, {
+const tx = createTransferTonTransaction(appKit, {
     recipientAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
     amount: '0.1', // 0.1 TON (human-readable format)
     comment: 'Draft transaction',
diff --git a/packages/appkit/docs/connectors.md b/packages/appkit/docs/connectors.md
index 0586da547..9c7fe9b93 100644
--- a/packages/appkit/docs/connectors.md
+++ b/packages/appkit/docs/connectors.md
@@ -1,7 +1,7 @@
 <!--
 This file is auto-generated. Do not edit manually.
 Changes will be overwritten when running the docs update script.
-Source template: template/packages/appkit/docs/connectors.md
+Source template: docs/templates/packages/appkit/docs/connectors.md
 -->
 
 # Connectors
diff --git a/packages/appkit/docs/reference.md b/packages/appkit/docs/reference.md
new file mode 100644
index 000000000..7a04f9bf6
--- /dev/null
+++ b/packages/appkit/docs/reference.md
@@ -0,0 +1,4400 @@
+<!--
+This file is auto-generated. Do not edit manually.
+Changes will be overwritten when running the docs update script.
+Source template: docs/templates/packages/appkit/docs/reference.md
+-->
+
+## Class
+
+### Client
+
+#### ApiClientTonApi
+
+[`ApiClient`](#apiclient) implementation backed by the TonAPI indexer.
+
+Constructor: `new ApiClientTonApi(config)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config` | `BaseApiClientConfig` | TonAPI client config — endpoint URL and API key; defaults to TonAPI mainnet/testnet URLs based on `config.network`. |
+
+#### ApiClientToncenter
+
+[`ApiClient`](#apiclient) implementation backed by the Toncenter API.
+
+Constructor: `new ApiClientToncenter(config)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config` | <code><a href="#apiclientconfig">ApiClientConfig</a></code> | Toncenter client config — endpoint URL, API key and optional DNS resolver override; defaults to mainnet/testnet Toncenter URLs based on `config.network`. |
+
+### 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)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config`\* | [`AppKitConfig`](#appkitconfig) | Networks, connectors, providers and runtime flags. |
+| `config.networks` | <code><a href="#networkadapters">NetworkAdapters</a></code> | Map of chain ID to [`NetworkConfig`](#networkconfig) (which holds the api-client setup); if omitted, AppKit defaults to mainnet only. |
+| `config.connectors` | <code><a href="#connectorinput">ConnectorInput</a>[]</code> | Wallet connectors registered at startup. |
+| `config.defaultNetwork` | <code><a href="#network">Network</a></code> | Default network. |
+| `config.providers` | <code><a href="#providerinput">ProviderInput</a>[]</code> | Providers registered at startup. |
+| `config.ssr` | `boolean` | Set to `true` to enable server-side rendering support. |
+
+**Example**
+
+```ts
+// 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; backs [`AppKit`](#appkit)'s `emitter` and any custom emitters apps create. `appKit.emitter.on(name, handler)` returns an unsubscribe function.
+
+Constructor: `new EventEmitter()`
+
+### Crypto Onramp
+
+#### CryptoOnrampError
+
+Error thrown by [`CryptoOnrampManager`](#cryptoonrampmanager) and crypto-onramp providers — extends [`DefiError`](#defierror) with `name: 'CryptoOnrampError'` and a stable `code` from the static `CryptoOnrampError.*` / `DefiError.*` constants.
+
+Constructor: `new CryptoOnrampError(message, code, details)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `message`\* | `string` | Human-readable description, forwarded to `Error`. |
+| `code`\* | `string` | Stable error code from the static `CryptoOnrampError.*` / `DefiError.*` constants. |
+| `details` | `unknown` | Optional provider-specific context for diagnostics. |
+
+#### CryptoOnrampManager
+
+Runtime that owns registered [`CryptoOnrampProvider`](#cryptoonrampprovider)s and dispatches quote/deposit/status calls. Exposed as [`AppKit`](#appkit)'s `cryptoOnrampManager`; usually accessed through the higher-level actions ([`getCryptoOnrampQuote`](#getcryptoonrampquote), [`createCryptoOnrampDeposit`](#createcryptoonrampdeposit), [`getCryptoOnrampStatus`](#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`](#cryptoonrampmanager) and the `getCryptoOnramp*` / [`createCryptoOnrampDeposit`](#createcryptoonrampdeposit) actions.
+
+Constructor: `new CryptoOnrampProvider()`
+
+**Example**
+
+```typescript
+class MyCryptoOnrampProvider extends CryptoOnrampProvider {
+  async getQuote(params: CryptoOnrampQuoteParams): Promise<CryptoOnrampQuote> {
+    // Implementation
+  }
+
+  async createDeposit(params: CryptoOnrampDepositParams): Promise<CryptoOnrampDeposit> {
+    // Implementation
+  }
+}
+```
+
+#### LayerswapCryptoOnrampProvider
+
+[`CryptoOnrampProvider`](#cryptoonrampprovider) implementation backed by Layerswap. Use [`createLayerswapProvider`](#createlayerswapprovider) to register it on AppKit; quote, deposit and status calls go through [`getCryptoOnrampQuote`](#getcryptoonrampquote) / [`createCryptoOnrampDeposit`](#createcryptoonrampdeposit) / [`getCryptoOnrampStatus`](#getcryptoonrampstatus) like any other crypto-onramp provider.
+
+Constructor: `new LayerswapCryptoOnrampProvider(config)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config` | <code><a href="#layerswapproviderconfig">LayerswapProviderConfig</a></code> | Optional [`LayerswapProviderConfig`](#layerswapproviderconfig); defaults are filled in for any field left undefined. |
+
+#### SwapsXyzCryptoOnrampProvider
+
+[`CryptoOnrampProvider`](#cryptoonrampprovider) implementation backed by swaps.xyz. Use [`createSwapsXyzProvider`](#createswapsxyzprovider) to register it on AppKit; quote, deposit and status calls go through [`getCryptoOnrampQuote`](#getcryptoonrampquote) / [`createCryptoOnrampDeposit`](#createcryptoonrampdeposit) / [`getCryptoOnrampStatus`](#getcryptoonrampstatus) like any other crypto-onramp provider.
+
+Constructor: `new SwapsXyzCryptoOnrampProvider(config)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config`\* | [`SwapsXyzProviderConfig`](#swapsxyzproviderconfig) | Configuration carrying the required `apiKey` plus optional URL/sender overrides. |
+
+### DeFi
+
+#### DefiError
+
+Base error thrown across all DeFi domains (swap, staking, onramp, crypto-onramp). Subclassed by [`SwapError`](#swaperror), [`StakingError`](#stakingerror), [`CryptoOnrampError`](#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)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `message`\* | `string` | Human-readable description, forwarded to `Error`. |
+| `code`\* | `string` | Stable error code from the `DefiError.*` constants. |
+| `details` | `unknown` | Optional provider-specific context for diagnostics. |
+
+### Networks
+
+#### AppKitNetworkManager
+
+Network manager exposed as [`AppKit`](#appkit)'s `networkManager` — extends walletkit's `KitNetworkManager` with a default-network setter and AppKit event emission.
+
+Constructor: `new AppKitNetworkManager(options, emitter)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options`\* | [`TonWalletKitOptions`](#tonwalletkitoptions) | Forwarded to the [`KitNetworkManager`](#kitnetworkmanager) base — chiefly the `networks` map keyed by chain ID. |
+| `emitter`\* | [`AppKitEmitter`](#appkitemitter) | Emitter the manager publishes `networks:default-changed` / `networks:updated` events through. |
+
+#### KitNetworkManager
+
+Walletkit-side network manager that [`AppKitNetworkManager`](#appkitnetworkmanager) extends, adding default-network state and AppKit event emission. Apps usually interact with the [`AppKitNetworkManager`](#appkitnetworkmanager) subclass via [`AppKit`](#appkit)'s `networkManager`.
+
+Constructor: `new KitNetworkManager(options)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options`\* | [`TonWalletKitOptions`](#tonwalletkitoptions) | Configuration carrying the `networks` map keyed by chain ID; at least one network must be configured. |
+
+### Staking
+
+#### StakingError
+
+Error thrown by [`StakingManager`](#stakingmanager) and staking providers — extends [`DefiError`](#defierror) with `name: 'StakingError'` and a typed [`StakingErrorCode`](#stakingerrorcode) on `code`.
+
+Constructor: `new StakingError(message, code, details)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `message`\* | `string` | Human-readable description, forwarded to `Error`. |
+| `code`\* | <code><a href="#stakingerrorcode">StakingErrorCode</a></code> | Stable [`StakingErrorCode`](#stakingerrorcode) for branching logic. |
+| `details` | `unknown` | Optional provider-specific context for diagnostics. |
+
+#### StakingManager
+
+Runtime that owns registered [`StakingProvider`](#stakingprovider)s and dispatches quote/stake/balance calls. Exposed as [`AppKit`](#appkit)'s `stakingManager`; usually accessed through the higher-level actions ([`getStakingQuote`](#getstakingquote), [`buildStakeTransaction`](#buildstaketransaction), [`getStakedBalance`](#getstakedbalance)).
+
+Constructor: `new StakingManager(createFactoryContext)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `createFactoryContext`\* | <code>() =&gt; <a href="#providerfactorycontext">ProviderFactoryContext</a></code> | Lazy provider of the [`ProviderFactoryContext`](#providerfactorycontext) the manager passes into provider factories at registration time. |
+
+#### StakingProvider
+
+Abstract base class implemented by staking providers (Tonstakers, custom integrations, …); apps don't use it directly — they consume providers through [`StakingManager`](#stakingmanager) and the `getStaking*` / `buildStakeTransaction` actions.
+
+Constructor: `new StakingProvider(providerId)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `providerId`\* | `string` | Stable id the provider registers with — must be unique within [`StakingManager`](#stakingmanager). |
+
+#### TonStakersStakingProvider
+
+[`StakingProvider`](#stakingprovider) implementation backed by Tonstakers. The constructor is private — use [`createTonstakersProvider`](#createtonstakersprovider) to register it on AppKit; quote and stake calls then go through [`getStakingQuote`](#getstakingquote) / [`buildStakeTransaction`](#buildstaketransaction) like any other staking provider.
+
+Constructor: `new TonStakersStakingProvider()`
+
+### Swap
+
+#### DeDustSwapProvider
+
+[`SwapProvider`](#swapprovider) implementation backed by DeDust. Use [`createDeDustProvider`](#creatededustprovider) to register it on AppKit; quote and swap calls go through [`getSwapQuote`](#getswapquote) / [`buildSwapTransaction`](#buildswaptransaction) like any other swap provider.
+
+Constructor: `new DeDustSwapProvider(config)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config` | <code><a href="#dedustswapproviderconfig">DeDustSwapProviderConfig</a></code> | Optional [`DeDustSwapProviderConfig`](#dedustswapproviderconfig); defaults are filled in for any field left undefined. |
+
+**Example**
+
+```typescript
+import { createDeDustProvider } from '@ton/walletkit/swap/dedust';
+
+kit.swap.registerProvider(
+    createDeDustProvider({
+        defaultSlippageBps: 100, // 1%
+        referralAddress: 'EQ...',
+        referralFeeBps: 50, // 0.5%
+    }),
+);
+```
+
+#### OmnistonSwapProvider
+
+[`SwapProvider`](#swapprovider) implementation backed by Omniston. Use [`createOmnistonProvider`](#createomnistonprovider) to register it on AppKit; quote and swap calls go through [`getSwapQuote`](#getswapquote) / [`buildSwapTransaction`](#buildswaptransaction) like any other swap provider.
+
+Constructor: `new OmnistonSwapProvider(config)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config` | <code><a href="#omnistonswapproviderconfig">OmnistonSwapProviderConfig</a></code> | Optional [`OmnistonSwapProviderConfig`](#omnistonswapproviderconfig); defaults are filled in for any field left undefined. |
+
+**Example**
+
+```typescript
+// Import from a separate entry point to avoid bundling the Omniston SDK
+import { createOmnistonProvider } from '@ton/walletkit/swap/omniston';
+
+kit.swap.registerProvider(
+    createOmnistonProvider({
+        apiUrl: 'wss://omni-ws.ston.fi',
+        defaultSlippageBps: 100, // 1%
+        referrerAddress: 'EQ...',
+        referrerFeeBps: 10, // 0.1%
+    }),
+);
+```
+
+#### SwapError
+
+Error thrown by [`SwapManager`](#swapmanager) and swap providers — extends [`DefiError`](#defierror) with `name: 'SwapError'` and a stable `code` from the static `SwapError.*` / `DefiError.*` constants.
+
+Constructor: `new SwapError(message, code, details)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `message`\* | `string` | Human-readable description, forwarded to `Error`. |
+| `code`\* | `string` | Stable error code from the static `SwapError.*` / `DefiError.*` constants. |
+| `details` | `unknown` | Optional provider-specific context for diagnostics. |
+
+#### SwapManager
+
+Runtime that owns registered [`SwapProvider`](#swapprovider)s and dispatches quote/swap calls. Exposed as [`AppKit`](#appkit)'s `swapManager`; usually accessed through the higher-level actions ([`getSwapQuote`](#getswapquote), [`buildSwapTransaction`](#buildswaptransaction)).
+
+Constructor: `new SwapManager(createFactoryContext)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `createFactoryContext`\* | <code>() =&gt; <a href="#providerfactorycontext">ProviderFactoryContext</a></code> | Lazy provider of the [`ProviderFactoryContext`](#providerfactorycontext) the manager passes into provider factories at registration time. |
+
+#### SwapProvider
+
+Abstract base class implemented by swap providers (DeDust, Omniston, custom integrations); apps don't use it directly — they consume providers through [`SwapManager`](#swapmanager) and the `getSwap*` / `buildSwapTransaction` actions.
+
+Constructor: `new SwapProvider()`
+
+**Example**
+
+```typescript
+class MySwapProvider extends SwapProvider {
+  async getQuote(params: SwapQuoteParams): Promise<SwapQuote> {
+    // Implementation
+  }
+
+  async buildSwapTransaction(params: SwapParams): Promise<TransactionRequest> {
+    // Implementation
+  }
+}
+```
+
+### Wallets
+
+#### TonConnectWalletAdapter
+
+[`WalletInterface`](#walletinterface) implementation backed by a TonConnect wallet. Built for you by [`createTonConnectConnector`](#createtonconnectconnector) — apps interact with it through standard AppKit actions ([`sendTransaction`](#sendtransaction), [`signText`](#signtext)/[`signBinary`](#signbinary)/[`signCell`](#signcell)); reads (balance, jettons, NFTs) go through AppKit actions using `appKit.networkManager`, not this adapter.
+
+Constructor: `new TonConnectWalletAdapter(config)`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config`\* | [`TonConnectWalletAdapterConfig`](#tonconnectwalletadapterconfig) | TonConnect wallet + UI instance and the id of the connector that produced them. |
+
+## Action
+
+### Balances
+
+#### getBalance
+
+Read the Toncoin balance of the currently selected wallet, returning `null` when no wallet is selected (use [`getBalanceByAddress`](#getbalancebyaddress) for an arbitrary address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options` | [`GetBalanceOptions`](#getbalanceoptions) | Optional network override. |
+| `options.network` | <code><a href="#network">Network</a></code> | Network to read the balance from. Defaults to the selected wallet's network. |
+
+Returns: <code>Promise&lt;<a href="#getbalancereturntype">GetBalanceReturnType</a>&gt;</code> — Balance in TON as a human-readable decimal string, or `null` when no wallet is selected.
+
+**Example**
+
+```ts
+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`](#getbalance) for the selected wallet).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetBalanceByAddressOptions`](#getbalancebyaddressoptions) | Target address and optional network. |
+| `options.address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Wallet address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+
+Returns: <code>Promise&lt;<a href="#getbalancebyaddressreturntype">GetBalanceByAddressReturnType</a>&gt;</code> — Balance in TON as a human-readable decimal string.
+
+**Example**
+
+```ts
+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`](#watchbalancebyaddress) for a fixed address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`WatchBalanceOptions`](#watchbalanceoptions) | Update callback and optional network override. |
+| `options.network` | <code><a href="#network">Network</a></code> | Network to watch on. Defaults to the selected wallet's network. |
+| `options.onChange`\* | <code>(update: <a href="#balanceupdate">BalanceUpdate</a>) =&gt; void</code> | Callback fired on every balance update from the streaming provider. |
+
+Returns: <code><a href="#watchbalancereturntype">WatchBalanceReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+**Example**
+
+```ts
+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`](#watchbalance) for the selected wallet).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`WatchBalanceByAddressOptions`](#watchbalancebyaddressoptions) | Target address, update callback and optional network override. |
+| `options.address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Wallet address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+| `options.onChange`\* | <code>(update: <a href="#balanceupdate">BalanceUpdate</a>) =&gt; void</code> | Callback fired on every balance update from the streaming provider. |
+
+Returns: <code><a href="#watchbalancebyaddressreturntype">WatchBalanceByAddressReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+**Example**
+
+```ts
+const unsubscribe = watchBalanceByAddress(appKit, {
+    address: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
+    onChange: (update) => {
+        console.log('Balance by address updated:', update.balance);
+    },
+});
+
+// Later: unsubscribe();
+```
+
+### Client
+
+#### getApiClient
+
+Read the [`ApiClient`](#apiclient) configured for a specific [`Network`](#network) — throws when the network has no client registered.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetApiClientOptions`](#getapiclientoptions) | Network to look up. |
+| `options.network`\* | <code><a href="#network">Network</a></code> | Network whose configured [`ApiClient`](#apiclient) should be returned. |
+
+Returns: <code><a href="#getapiclientreturntype">GetApiClientReturnType</a></code> — The configured [`ApiClient`](#apiclient) for the requested network.
+
+**Example**
+
+```ts
+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`](#appkitconfig)'s `connectors` at construction, but available after AppKit is up.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `connectorFn`\* | [`AddConnectorParameters`](#addconnectorparameters) | Connector instance or factory to register. |
+
+Returns: <code><a href="#addconnectorreturntype">AddConnectorReturnType</a></code> — Function that unregisters the connector when called.
+
+**Example**
+
+```ts
+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`](#setdefaultnetwork)); throws when no connector with that id exists.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`ConnectParameters`](#connectparameters) | Connector to connect through. |
+| `parameters.connectorId`\* | `string` | ID of the registered connector to drive the connection through (e.g., `'tonconnect'`). |
+
+Returns: <code>Promise&lt;<a href="#connectreturntype">ConnectReturnType</a>&gt;</code> — Resolves once the connector's connect flow completes; if a wallet was successfully connected, it becomes available via [`getSelectedWallet`](#getselectedwallet).
+
+**Example**
+
+```ts
+await connect(appKit, {
+    connectorId: 'tonconnect',
+});
+```
+
+#### createConnector
+
+Identity helper for typing a [`ConnectorFactory`](#connectorfactory) inline — returns the factory unchanged so authors get parameter inference without spelling the type out.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `factory`\* | [`ConnectorFactory`](#connectorfactory) | Factory to wrap. |
+
+Returns: <code><a href="#connectorfactory">ConnectorFactory</a></code> — The same factory, typed as [`ConnectorFactory`](#connectorfactory).
+
+#### createTonConnectConnector
+
+Build a TonConnect-backed [`Connector`](#connector) for AppKit; pass the result to [`AppKitConfig`](#appkitconfig)'s `connectors` or [`addConnector`](#addconnector).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config`\* | [`TonConnectConnectorConfig`](#tonconnectconnectorconfig) | Connector ID, metadata override and TonConnect options or pre-built UI instance. |
+
+Returns: <code><a href="#connectorfactory">ConnectorFactory</a></code> — Factory function consumed by AppKit at registration time.
+
+**Example**
+
+```ts
+// 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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`DisconnectParameters`](#disconnectparameters) | Connector to disconnect. |
+| `parameters.connectorId`\* | `string` | ID of the registered connector whose wallet should be disconnected. |
+
+Returns: <code>Promise&lt;<a href="#disconnectreturntype">DisconnectReturnType</a>&gt;</code> — Resolves once the connector tears down its session.
+
+**Example**
+
+```ts
+await disconnect(appKit, {
+    connectorId: 'tonconnect',
+});
+```
+
+#### getConnectorById
+
+Look up a registered connector by its id.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetConnectorByIdOptions`](#getconnectorbyidoptions) | ID of the connector to find. |
+| `options.id`\* | `string` | ID of the connector to look up. |
+
+Returns: <code><a href="#getconnectorbyidreturntype">GetConnectorByIdReturnType</a></code> — The matching [`Connector`](#connector), or `undefined` if none with that id is registered.
+
+**Example**
+
+```ts
+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`](#appkitconfig)'s `connectors` and those added later through [`addConnector`](#addconnector).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getconnectorsreturntype">GetConnectorsReturnType</a></code> — Read-only array of registered [`Connector`](#connector)s.
+
+**Example**
+
+```ts
+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`](#watchconnectedwallets) if you want to react to wallet connect/disconnect events instead.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`WatchConnectorByIdParameters`](#watchconnectorbyidparameters) | Connector ID and update callback. |
+| `parameters.id`\* | `string` | ID of the connector to watch. |
+| `parameters.onChange`\* | <code>(connector: <a href="#connector">Connector</a> \| undefined) =&gt; void</code> | Callback invoked when the connector with the watched id is registered or unregistered — receives the connector itself, or `undefined` when none is registered under that id. |
+
+Returns: <code><a href="#watchconnectorbyidreturntype">WatchConnectorByIdReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+**Example**
+
+```ts
+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`](#addconnector) or AppKit's constructor) or removed, and receives the current list. Use [`watchConnectedWallets`](#watchconnectedwallets) if you want to react to wallet connect/disconnect events instead.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`WatchConnectorsParameters`](#watchconnectorsparameters) | Update callback. |
+| `parameters.onChange`\* | <code>(connectors: readonly <a href="#connector">Connector</a>[]) =&gt; void</code> | Callback invoked when the list of registered connectors changes — receives the current list. |
+
+Returns: <code><a href="#watchconnectorsreturntype">WatchConnectorsReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+**Example**
+
+```ts
+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`](#getcryptoonrampquote) — the returned [`CryptoOnrampDeposit`](#cryptoonrampdeposit) carries the address and amount the user must send on the source chain.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`CreateCryptoOnrampDepositOptions`](#createcryptoonrampdepositoptions) | Quote, refund address, and optional provider override. |
+| `options.quote`\* | <code><a href="#cryptoonrampquote">CryptoOnrampQuote</a>&lt;TQuoteMetadata = unknown&gt;</code> | Quote to execute the deposit against (contains recipientAddress and provider metadata) |
+| `options.refundAddress`\* | `string` | Address to refund the crypto to in case of failure |
+| `options.providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `options.providerId` | `string` | Provider to create the deposit through; defaults to `quote.providerId`, then to the default provider. |
+
+Returns: <code><a href="#createcryptoonrampdepositreturntype">CreateCryptoOnrampDepositReturnType</a></code> — Deposit details the UI should show to the user (address, amount, optional `memo`/`expiresAt`).
+
+#### createLayerswapProvider
+
+Build a Layerswap-backed [`CryptoOnrampProvider`](#cryptoonrampprovider) for AppKit; pass the result to [`AppKitConfig`](#appkitconfig)'s `providers` or [`registerProvider`](#registerprovider).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config` | <code><a href="#layerswapproviderconfig">LayerswapProviderConfig</a></code> | Optional [`LayerswapProviderConfig`](#layerswapproviderconfig); defaults are filled in for any field left undefined. |
+
+Returns: <code>ProviderFactory&lt;<a href="#layerswapcryptoonrampprovider">LayerswapCryptoOnrampProvider</a>&gt;</code>.
+
+#### createSwapsXyzProvider
+
+Build a swaps.xyz-backed [`CryptoOnrampProvider`](#cryptoonrampprovider) for AppKit; pass the result to [`AppKitConfig`](#appkitconfig)'s `providers` or [`registerProvider`](#registerprovider).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config`\* | [`SwapsXyzProviderConfig`](#swapsxyzproviderconfig) | Configuration carrying the required `apiKey` plus optional URL/sender overrides. |
+
+Returns: <code>ProviderFactory&lt;<a href="#swapsxyzcryptoonrampprovider">SwapsXyzCryptoOnrampProvider</a>&gt;</code>.
+
+#### 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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options` | [`GetCryptoOnrampProviderOptions`](#getcryptoonrampprovideroptions) | Optional provider id. |
+| `options.id` | `string` | Provider ID to look up; when omitted, returns the registered default provider. |
+
+Returns: <code><a href="#getcryptoonrampproviderreturntype">GetCryptoOnrampProviderReturnType</a></code> — The matching [`CryptoOnrampProviderInterface`](#cryptoonrampproviderinterface).
+
+**Example**
+
+```ts
+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`](#appkitconfig)'s `providers` and those added later through [`registerProvider`](#registerprovider).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getcryptoonrampprovidersreturntype">GetCryptoOnrampProvidersReturnType</a></code> — Array of registered [`CryptoOnrampProviderInterface`](#cryptoonrampproviderinterface)s.
+
+**Example**
+
+```ts
+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`](#createcryptoonrampdeposit).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetCryptoOnrampQuoteOptions`](#getcryptoonrampquoteoptions) | Source asset, target asset, amount and optional provider override. |
+| `options.amount`\* | `string` | Amount to onramp (either source or target crypto, depending on isSourceAmount) |
+| `options.sourceCurrencyAddress`\* | `string` | Source crypto currency address (contract address or 0x0... for native) |
+| `options.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. |
+| `options.targetCurrencyAddress`\* | `string` | Target crypto currency address on TON (contract address or 0x0... for native) |
+| `options.recipientAddress`\* | `string` | TON address that will receive the target crypto |
+| `options.refundAddress` | `string` | Refund address for the source crypto |
+| `options.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. |
+| `options.providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `options.providerId` | `string` | Provider to quote against; defaults to the registered default provider. |
+
+Returns: <code><a href="#getcryptoonrampquotereturntype">GetCryptoOnrampQuoteReturnType</a></code> — 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'`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetCryptoOnrampStatusOptions`](#getcryptoonrampstatusoptions) | Deposit id, originating provider id and optional provider override. |
+| `options.depositId`\* | `string` | Deposit id |
+| `options.providerId`\* | `string` | Identifier of the provider that issued this deposit |
+
+Returns: <code><a href="#getcryptoonrampstatusreturntype">GetCryptoOnrampStatusReturnType</a></code> — Current [`CryptoOnrampStatus`](#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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`WatchCryptoOnrampProvidersParameters`](#watchcryptoonrampprovidersparameters) | Update callback. |
+| `parameters.onChange`\* | `() => void` | Callback fired whenever a crypto-onramp provider is registered or the default crypto-onramp provider changes. |
+
+Returns: <code><a href="#watchcryptoonrampprovidersreturntype">WatchCryptoOnrampProvidersReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+### DeFi
+
+#### registerProvider
+
+Register a DeFi / onramp provider at runtime — equivalent to passing it via [`AppKitConfig`](#appkitconfig)'s `providers` at construction, but available after AppKit is up. AppKit emits `provider:registered`, picked up by domain-specific subscribers like [`watchSwapProviders`](#watchswapproviders) and [`watchCryptoOnrampProviders`](#watchcryptoonrampproviders).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `provider`\* | [`RegisterProviderOptions`](#registerprovideroptions) | Provider instance or factory to register. |
+
+Returns: `void`.
+
+**Example**
+
+```ts
+registerProvider(
+    appKit,
+    createOmnistonProvider({
+        defaultSlippageBps: 100, // 1%
+    }),
+);
+```
+
+### Jettons
+
+#### createTransferJettonTransaction
+
+Build a jetton transfer [`TransactionRequest`](#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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`CreateTransferJettonTransactionParameters`](#createtransferjettontransactionparameters) | Jetton, recipient, amount, decimals and optional comment. |
+| `parameters.jettonAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address being transferred. |
+| `parameters.recipientAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Recipient who should receive the jettons. |
+| `parameters.amount`\* | `string` | Amount in jetton units as a human-readable decimal string (e.g., `"1.5"`). |
+| `parameters.jettonDecimals`\* | `number` | Decimals declared by the jetton master; used to convert `amount` into raw smallest units. |
+| `parameters.comment` | `string` | Optional human-readable comment attached to the transfer. |
+
+Returns: <code>Promise&lt;<a href="#createtransferjettontransactionreturntype">CreateTransferJettonTransactionReturnType</a>&gt;</code> — Transaction request ready to pass to `sendTransaction`.
+
+**Example**
+
+```ts
+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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetJettonBalanceOptions`](#getjettonbalanceoptions) | Jetton master, owner address, decimals and optional network override. |
+| `options.jettonAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address (the token, not the user's wallet for it). |
+| `options.ownerAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Owner of the jetton wallet — typically the connected user's address. |
+| `options.jettonDecimals`\* | `number` | Decimals declared by the jetton master; used to format the raw balance into a human-readable string. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+
+Returns: <code>Promise&lt;<a href="#getjettonbalancereturntype">GetJettonBalanceReturnType</a>&gt;</code> — Balance as a human-readable decimal string in the jetton's units.
+
+**Example**
+
+```ts
+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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetJettonInfoOptions`](#getjettoninfooptions) | Jetton master address and optional network override. |
+| `options.address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address whose metadata is being fetched. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+
+Returns: <code>Promise&lt;<a href="#getjettoninforeturntype">GetJettonInfoReturnType</a>&gt;</code> — Jetton metadata, or `null` if the indexer has no record.
+
+**Example**
+
+```ts
+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`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetJettonWalletAddressOptions`](#getjettonwalletaddressoptions) | Jetton master, owner address and optional network override. |
+| `options.jettonAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address. |
+| `options.ownerAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Owner whose jetton wallet should be derived. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+
+Returns: <code>Promise&lt;<a href="#getjettonwalletaddressreturntype">GetJettonWalletAddressReturnType</a>&gt;</code> — User-friendly address of the owner's jetton wallet.
+
+**Example**
+
+```ts
+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`](#getjettonsbyaddress) for an arbitrary address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options` | [`GetJettonsOptions`](#getjettonsoptions) | Optional network override and pagination. |
+| `options.network` | <code><a href="#network">Network</a></code> | Network to read jettons from. Defaults to the selected wallet's network. |
+| `options.limit` | `number` | Maximum number of jettons to return. |
+| `options.offset` | `number` | Number of jettons to skip before returning results — used for pagination. |
+
+Returns: <code>Promise&lt;<a href="#getjettonsreturntype">GetJettonsReturnType</a>&gt;</code> — Jettons response for the selected wallet, or `null` when none is selected.
+
+**Example**
+
+```ts
+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`](#getjettons) for the selected wallet); raw balances are formatted with each jetton's declared decimals, and entries without decimals are dropped.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetJettonsByAddressOptions`](#getjettonsbyaddressoptions) | Owner address, optional network override and pagination. |
+| `options.address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+| `options.limit` | `number` | Maximum number of jettons to return. |
+| `options.offset` | `number` | Number of jettons to skip before returning results — used for pagination. |
+
+Returns: <code>Promise&lt;<a href="#getjettonsbyaddressreturntype">GetJettonsByAddressReturnType</a>&gt;</code> — Jettons response with formatted balances.
+
+**Example**
+
+```ts
+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`](#createtransferjettontransaction) + [`sendTransaction`](#sendtransaction) if you need to inspect the transaction first); throws `Error('Wallet not connected')` if no wallet is currently selected.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`TransferJettonParameters`](#transferjettonparameters) | Jetton, recipient, amount, decimals and optional comment. |
+| `parameters.jettonAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address being transferred. |
+| `parameters.recipientAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Recipient who should receive the jettons. |
+| `parameters.amount`\* | `string` | Amount in jetton units as a human-readable decimal string (e.g., `"1.5"`). |
+| `parameters.jettonDecimals`\* | `number` | Decimals declared by the jetton master; used to convert `amount` into raw smallest units. |
+| `parameters.comment` | `string` | Optional human-readable comment attached to the transfer. |
+
+Returns: <code>Promise&lt;<a href="#transferjettonreturntype">TransferJettonReturnType</a>&gt;</code> — Wallet response carrying the BoC of the sent transaction.
+
+**Example**
+
+```ts
+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`](#watchjettonsbyaddress) for a fixed address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`WatchJettonsOptions`](#watchjettonsoptions) | Update callback and optional network override. |
+| `options.onChange`\* | <code>(update: <a href="#jettonupdate">JettonUpdate</a>) =&gt; void</code> | Callback fired on every jetton-balance update from the streaming provider. |
+| `options.network` | <code><a href="#network">Network</a></code> | Network to watch on. Defaults to the selected wallet's network. |
+
+Returns: <code><a href="#watchjettonsreturntype">WatchJettonsReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+#### watchJettonsByAddress
+
+Subscribe to jetton-balance updates for an arbitrary owner address (use [`watchJettons`](#watchjettons) for the selected wallet).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`WatchJettonsByAddressOptions`](#watchjettonsbyaddressoptions) | Owner address, update callback and optional network override. |
+| `options.address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `options.onChange`\* | <code>(update: <a href="#jettonupdate">JettonUpdate</a>) =&gt; void</code> | Callback fired on every jetton-balance update from the streaming provider. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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: <code><a href="#watchjettonsbyaddressreturntype">WatchJettonsByAddressReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+### NFTs
+
+#### createTransferNftTransaction
+
+Build an NFT transfer [`TransactionRequest`](#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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`CreateTransferNftTransactionParameters`](#createtransfernfttransactionparameters) | NFT, recipient, optional gas amount and comment. |
+| `parameters.nftAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | NFT contract address to transfer. |
+| `parameters.recipientAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | New owner address. |
+| `parameters.amount` | `string` | Amount of TON to attach to the transfer for gas; defaults to AppKit's NFT gas-fee constant when omitted. |
+| `parameters.comment` | `string` | Optional human-readable comment attached to the transfer. |
+
+Returns: <code>Promise&lt;<a href="#createtransfernfttransactionreturntype">CreateTransferNftTransactionReturnType</a>&gt;</code> — Transaction request ready to pass to `sendTransaction`.
+
+**Example**
+
+```ts
+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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetNftOptions`](#getnftoptions) | NFT address and optional network override. |
+| `options.address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | NFT contract address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+
+Returns: <code>Promise&lt;<a href="#getnftreturntype">GetNftReturnType</a>&gt;</code> — NFT data, or `null` if the indexer has no record.
+
+**Example**
+
+```ts
+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`](#getnftsbyaddress) for an arbitrary address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options` | [`GetNftsOptions`](#getnftsoptions) | Optional network override and pagination. |
+| `options.network` | <code><a href="#network">Network</a></code> | Network to read NFTs from. Defaults to the selected wallet's network. |
+| `options.limit` | `number` | Maximum number of NFTs to return. |
+| `options.offset` | `number` | Number of NFTs to skip before returning results — used for pagination. |
+
+Returns: <code>Promise&lt;<a href="#getnftsreturntype">GetNftsReturnType</a>&gt;</code> — NFTs response for the selected wallet, or `null` when none is selected.
+
+**Example**
+
+```ts
+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`](#getnfts) for the selected wallet).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetNftsByAddressOptions`](#getnftsbyaddressoptions) | Owner address, optional network override and pagination. |
+| `options.address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+| `options.limit` | `number` | Maximum number of NFTs to return. |
+| `options.offset` | `number` | Number of NFTs to skip before returning results — used for pagination. |
+
+Returns: <code>Promise&lt;<a href="#getnftsbyaddressreturntype">GetNftsByAddressReturnType</a>&gt;</code> — NFTs response with the owner's items.
+
+**Example**
+
+```ts
+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`](#createtransfernfttransaction) + [`sendTransaction`](#sendtransaction) if you need to inspect the transaction first); throws `Error('Wallet not connected')` if no wallet is currently selected.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`TransferNftParameters`](#transfernftparameters) | NFT, recipient, optional gas amount and comment. |
+| `parameters.nftAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | NFT contract address to transfer. |
+| `parameters.recipientAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | New owner address. |
+| `parameters.amount` | `string` | Amount of TON to attach to the transfer for gas; defaults to AppKit's NFT gas-fee constant when omitted. |
+| `parameters.comment` | `string` | Optional human-readable comment attached to the transfer. |
+
+Returns: <code>Promise&lt;<a href="#transfernftreturntype">TransferNftReturnType</a>&gt;</code> — Wallet response carrying the BoC of the sent transaction.
+
+**Example**
+
+```ts
+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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options` | [`GetBlockNumberOptions`](#getblocknumberoptions) | Optional network override. |
+| `options.network` | <code><a href="#network">Network</a></code> | Network to query. Defaults to mainnet when omitted. |
+
+Returns: <code>Promise&lt;<a href="#getblocknumberreturntype">GetBlockNumberReturnType</a>&gt;</code> — Current masterchain seqno as a number.
+
+**Example**
+
+```ts
+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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getdefaultnetworkreturntype">GetDefaultNetworkReturnType</a></code> — The default [`Network`](#network), or `undefined` if none is set.
+
+**Example**
+
+```ts
+const defaultNetwork = getDefaultNetwork(appKit);
+console.log('Default network:', defaultNetwork);
+```
+
+#### getNetwork
+
+Read the [`Network`](#network) the selected wallet is connected to, or `null` when no wallet is selected (use [`getDefaultNetwork`](#getdefaultnetwork) for AppKit's configured default).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getnetworkreturntype">GetNetworkReturnType</a></code> — Network of the selected wallet, or `null` when none is selected.
+
+**Example**
+
+```ts
+const network = getNetwork(appKit);
+
+if (network) {
+    console.log('Current network:', network);
+}
+```
+
+#### getNetworks
+
+List every network configured on this AppKit instance via [`AppKitConfig`](#appkitconfig)'s `networks`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getnetworksreturntype">GetNetworksReturnType</a></code> — Array of configured [`Network`](#network)s.
+
+**Example**
+
+```ts
+const networks = getNetworks(appKit);
+
+console.log('Configured networks:', networks);
+```
+
+#### hasStreamingProvider
+
+Check whether a streaming provider is registered for a network — required by [`watchBalance`](#watchbalance), [`watchJettons`](#watchjettons) and other live-update actions.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `network`\* | [`Network`](#network) | Network to check. |
+
+Returns: <code><a href="#hasstreamingproviderreturntype">HasStreamingProviderReturnType</a></code> — `true` when a streaming provider is registered for that network.
+
+**Example**
+
+```ts
+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`](#watchdefaultnetwork) subscribers fire. Pass `undefined` to remove the constraint and allow any registered network.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`SetDefaultNetworkParameters`](#setdefaultnetworkparameters) | Network to enforce, or `undefined` to clear. |
+| `parameters.network`\* | <code><a href="#network">Network</a> \| undefined</code> | Network to enforce on new wallet connections; pass `undefined` to allow any registered network. |
+
+Returns: <code><a href="#setdefaultnetworkreturntype">SetDefaultNetworkReturnType</a></code>.
+
+**Example**
+
+```ts
+// 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`](#setdefaultnetwork) is called.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`WatchDefaultNetworkParameters`](#watchdefaultnetworkparameters) | Update callback. |
+| `parameters.onChange`\* | <code>(network: <a href="#network">Network</a> \| undefined) =&gt; void</code> | Callback fired whenever [`setDefaultNetwork`](#setdefaultnetwork) updates the default — receives the new value (or `undefined` when cleared). |
+
+Returns: <code><a href="#watchdefaultnetworkreturntype">WatchDefaultNetworkReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+**Example**
+
+```ts
+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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`WatchNetworksParameters`](#watchnetworksparameters) | Update callback. |
+| `parameters.onChange`\* | <code>(networks: <a href="#network">Network</a>[]) =&gt; void</code> | Callback fired whenever the configured-networks list changes — receives the latest snapshot. |
+
+Returns: <code><a href="#watchnetworksreturntype">WatchNetworksReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+**Example**
+
+```ts
+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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`SignBinaryParameters`](#signbinaryparameters) | Binary content and optional network override. |
+| `parameters.bytes`\* | <code><a href="#base64string">Base64String</a></code> | Binary blob the user is asked to sign, encoded as Base64. |
+| `parameters.network` | <code><a href="#network">Network</a></code> | Network to issue the sign request against. Defaults to AppKit's configured default network; when none is set, the wallet falls back to its current network. |
+
+Returns: <code>Promise&lt;<a href="#signbinaryreturntype">SignBinaryReturnType</a>&gt;</code> — Signature and signed payload, as returned by the wallet.
+
+**Example**
+
+```ts
+// 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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`SignCellParameters`](#signcellparameters) | Cell content, TL-B schema and optional network override. |
+| `parameters.cell`\* | <code><a href="#base64string">Base64String</a></code> | TON cell content encoded as Base64 (BoC). |
+| `parameters.schema`\* | `string` | TL-B-style schema describing the cell layout so the wallet can render the payload to the user. |
+| `parameters.network` | <code><a href="#network">Network</a></code> | Network to issue the sign request against. Defaults to AppKit's configured default network; when none is set, the wallet falls back to its current network. |
+
+Returns: <code>Promise&lt;<a href="#signcellreturntype">SignCellReturnType</a>&gt;</code> — Signature and signed payload, as returned by the wallet.
+
+**Example**
+
+```ts
+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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`SignTextParameters`](#signtextparameters) | Text to sign and optional network override. |
+| `parameters.text`\* | `string` | UTF-8 text the user is asked to sign. |
+| `parameters.network` | <code><a href="#network">Network</a></code> | Network to issue the sign request against. Defaults to AppKit's configured default network; when none is set, the wallet falls back to its current network. |
+
+Returns: <code>Promise&lt;<a href="#signtextreturntype">SignTextReturnType</a>&gt;</code> — Signature and signed payload, as returned by the wallet.
+
+**Example**
+
+```ts
+const result = await signText(appKit, {
+    text: 'Hello, TON!',
+});
+
+console.log('Signature:', result.signature);
+```
+
+### Staking
+
+#### buildStakeTransaction
+
+Build a [`TransactionRequest`](#transactionrequest) that executes a stake or unstake previously quoted by [`getStakingQuote`](#getstakingquote) — returns it without sending so the UI can inspect or batch before signing.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`BuildStakeTransactionOptions`](#buildstaketransactionoptions) | Quote and optional provider override. |
+| `options.quote`\* | <code><a href="#stakingquote">StakingQuote</a></code> | The staking quote based on which the transaction is built |
+| `options.userAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the user performing the staking |
+| `options.providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `options.providerId` | `string` | Provider to stake/unstake through; defaults to the registered default staking provider. |
+
+Returns: <code><a href="#buildstaketransactionreturntype">BuildStakeTransactionReturnType</a></code> — Transaction request ready to pass to `sendTransaction`.
+
+**Example**
+
+```ts
+const txRequest = await buildStakeTransaction(appKit, {
+    quote,
+    userAddress,
+});
+console.log('Stake Transaction:', txRequest);
+```
+
+#### createTonstakersProvider
+
+Build a Tonstakers-backed [`StakingProvider`](#stakingprovider) for AppKit; pass the result to [`AppKitConfig`](#appkitconfig)'s `providers` or [`registerProvider`](#registerprovider).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config` | <code><a href="#tonstakersproviderconfig">TonStakersProviderConfig</a></code> | Optional [`TonStakersProviderConfig`](#tonstakersproviderconfig); defaults are filled in for any field left undefined. |
+
+Returns: <code>(ctx: <a href="#providerfactorycontext">ProviderFactoryContext</a>) =&gt; <a href="#tonstakersstakingprovider">TonStakersStakingProvider</a></code>.
+
+#### 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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetStakedBalanceOptions`](#getstakedbalanceoptions) | Owner address and optional network/provider override. |
+| `options.userAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Owner whose staked balance should be read. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+| `options.providerId` | `string` | Provider to query; defaults to the registered default staking provider. |
+
+Returns: <code><a href="#getstakedbalancereturntype">GetStakedBalanceReturnType</a></code> — Staked-balance breakdown ([`StakingBalance`](#stakingbalance)) for the user on the resolved network/provider.
+
+**Example**
+
+```ts
+const balance = await getStakedBalance(appKit, {
+    userAddress,
+});
+console.log('Staked Balance:', balance);
+```
+
+#### getStakingManager
+
+Read AppKit's [`StakingManager`](#stakingmanager) — the runtime that owns registered staking providers and dispatches quote/stake/balance calls. Apps usually use the higher-level actions ([`getStakingQuote`](#getstakingquote), [`buildStakeTransaction`](#buildstaketransaction), [`getStakedBalance`](#getstakedbalance)) instead of touching the manager directly.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getstakingmanagerreturntype">GetStakingManagerReturnType</a></code> — The [`StakingManager`](#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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options` | [`GetStakingProviderOptions`](#getstakingprovideroptions) | Optional provider id. |
+| `options.id` | `string` | Provider ID to look up; when omitted, returns the registered default staking provider. |
+
+Returns: <code><a href="#getstakingproviderreturntype">GetStakingProviderReturnType</a></code> — 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`](#getstakingprovidermetadata) for static metadata (display name, stake/receive tokens, supported unstake modes).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options` | [`GetStakingProviderInfoOptions`](#getstakingproviderinfooptions) | Optional network and provider override. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+| `options.providerId` | `string` | Provider to query; defaults to the registered default staking provider. |
+
+Returns: <code><a href="#getstakingproviderinforeturntype">GetStakingProviderInfoReturnType</a></code> — Live staking-provider info for the resolved network.
+
+**Example**
+
+```ts
+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`](#getstakingproviderinfo) for live values (APY, instant-unstake liquidity, exchange rate).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options` | [`GetStakingProviderMetadataOptions`](#getstakingprovidermetadataoptions) | Optional network and provider override. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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. |
+| `options.providerId` | `string` | Provider to query; defaults to the registered default staking provider. |
+
+Returns: <code><a href="#getstakingprovidermetadatareturntype">GetStakingProviderMetadataReturnType</a></code> — Static [`StakingProviderMetadata`](#stakingprovidermetadata) for the resolved provider.
+
+**Example**
+
+```ts
+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`](#appkitconfig)'s `providers` and those added later through [`registerProvider`](#registerprovider).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getstakingprovidersreturntype">GetStakingProvidersReturnType</a></code> — Array of registered staking providers.
+
+**Example**
+
+```ts
+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`](#buildstaketransaction).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetStakingQuoteOptions`](#getstakingquoteoptions) | Quote parameters and optional provider override. |
+| `options.direction`\* | <code><a href="#stakingquotedirection">StakingQuoteDirection</a></code> | Direction of the quote (stake or unstake) |
+| `options.amount`\* | `string` | Amount of tokens to stake or unstake |
+| `options.userAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the user |
+| `options.network` | <code><a href="#network">Network</a></code> | Network on which the staking will be executed |
+| `options.unstakeMode` | <code><a href="#unstakemodes">UnstakeModes</a></code> | Requested mode of unstaking |
+| `options.isReversed` | `boolean` | If true, for unstake requests the amount is specified in the staking coin (e.g. TON) instead of the Liquid Staking Token (e.g. tsTON). |
+| `options.providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `options.providerId` | `string` | Provider to quote against; defaults to the registered default staking provider. |
+
+Returns: <code><a href="#getstakingquotereturntype">GetStakingQuoteReturnType</a></code> — Quote with pricing details and provider metadata.
+
+**Example**
+
+```ts
+const quote = await getStakingQuote(appKit, {
+    amount: '1000000000',
+    direction: 'stake',
+});
+console.log('Staking Quote:', quote);
+```
+
+#### setDefaultStakingProvider
+
+Set the default staking provider — subsequent [`getStakingQuote`](#getstakingquote) and [`buildStakeTransaction`](#buildstaketransaction) calls without an explicit `providerId` route through it. Emits `provider:default-changed`, picked up by [`watchStakingProviders`](#watchstakingproviders).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`SetDefaultStakingProviderParameters`](#setdefaultstakingproviderparameters) | ID of the provider to make default. |
+| `parameters.providerId`\* | `string` | ID of the provider to make default — must already be registered. |
+
+Returns: <code><a href="#setdefaultstakingproviderreturntype">SetDefaultStakingProviderReturnType</a></code>.
+
+#### watchStakingProviders
+
+Subscribe to staking provider lifecycle — fires `onChange` whenever a new provider is registered or the default staking provider switches.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`WatchStakingProvidersParameters`](#watchstakingprovidersparameters) | Update callback. |
+| `parameters.onChange`\* | `() => void` | Callback fired whenever a staking provider is registered or the default staking provider changes. |
+
+Returns: <code><a href="#watchstakingprovidersreturntype">WatchStakingProvidersReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+### Swap
+
+#### buildSwapTransaction
+
+Build a [`TransactionRequest`](#transactionrequest) that executes a swap previously quoted by [`getSwapQuote`](#getswapquote) — returns it without sending so the UI can inspect or batch before signing.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`BuildSwapTransactionOptions`](#buildswaptransactionoptions) | Quote and provider-specific options. |
+| `options.quote`\* | <code><a href="#swapquote">SwapQuote</a></code> | The swap quote based on which the transaction is built |
+| `options.userAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the user performing the swap |
+| `options.destinationAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address to receive the swapped tokens (defaults to userAddress) |
+| `options.slippageBps` | `number` | Slippage tolerance in basis points (1 bp = 0.01%) |
+| `options.deadline` | `number` | Transaction deadline in unix timestamp |
+| `options.providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+
+Returns: <code><a href="#buildswaptransactionreturntype">BuildSwapTransactionReturnType</a></code> — Transaction request ready to pass to `sendTransaction`.
+
+**Example**
+
+```ts
+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`](#swapprovider) for AppKit; pass the result to [`AppKitConfig`](#appkitconfig)'s `providers` or [`registerProvider`](#registerprovider).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config` | <code><a href="#dedustswapproviderconfig">DeDustSwapProviderConfig</a></code> | Optional [`DeDustSwapProviderConfig`](#dedustswapproviderconfig); defaults are filled in for any field left undefined. |
+
+Returns: <code>(ctx: <a href="#providerfactorycontext">ProviderFactoryContext</a>) =&gt; <a href="#dedustswapprovider">DeDustSwapProvider</a></code>.
+
+#### createOmnistonProvider
+
+Build an Omniston-backed [`SwapProvider`](#swapprovider) for AppKit; pass the result to [`AppKitConfig`](#appkitconfig)'s `providers` or [`registerProvider`](#registerprovider).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config` | <code><a href="#omnistonswapproviderconfig">OmnistonSwapProviderConfig</a></code> | Optional [`OmnistonSwapProviderConfig`](#omnistonswapproviderconfig); defaults are filled in for any field left undefined. |
+
+Returns: <code>(ctx: <a href="#providerfactorycontext">ProviderFactoryContext</a>) =&gt; <a href="#omnistonswapprovider">OmnistonSwapProvider</a></code>.
+
+#### getSwapManager
+
+Read AppKit's [`SwapManager`](#swapmanager) — the runtime that owns registered swap providers and dispatches quote/build calls. Apps usually use the higher-level actions ([`getSwapQuote`](#getswapquote), [`buildSwapTransaction`](#buildswaptransaction)) instead of touching the manager directly.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getswapmanagerreturntype">GetSwapManagerReturnType</a></code> — The [`SwapManager`](#swapmanager) bound to this AppKit instance.
+
+**Example**
+
+```ts
+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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options` | [`GetSwapProviderOptions`](#getswapprovideroptions) | Optional provider id. |
+| `options.id` | `string` | Provider ID to look up; when omitted, returns the registered default swap provider. |
+
+Returns: <code><a href="#getswapproviderreturntype">GetSwapProviderReturnType</a></code> — The matching swap provider instance.
+
+**Example**
+
+```ts
+const swapProvider = getSwapProvider(appKit, { id: 'stonfi' });
+```
+
+#### getSwapProviders
+
+List every swap provider registered on this AppKit instance — both those passed via [`AppKitConfig`](#appkitconfig)'s `providers` and those added later through [`registerProvider`](#registerprovider).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getswapprovidersreturntype">GetSwapProvidersReturnType</a></code> — Array of registered swap providers.
+
+**Example**
+
+```ts
+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`](#buildswaptransaction).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`GetSwapQuoteOptions`](#getswapquoteoptions) | Source and target tokens, amount, optional network and provider override. |
+| `options.amount`\* | `string` | Amount of tokens to swap (incoming or outgoing depending on isReverseSwap) |
+| `options.from`\* | <code><a href="#swaptoken">SwapToken</a></code> | Token to swap from |
+| `options.to`\* | <code><a href="#swaptoken">SwapToken</a></code> | Token to swap to |
+| `options.network`\* | <code><a href="#network">Network</a></code> | Network on which the swap will be executed |
+| `options.slippageBps` | `number` | Slippage tolerance in basis points (1 bp = 0.01%) |
+| `options.maxOutgoingMessages` | `number` | Maximum number of outgoing messages |
+| `options.providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `options.isReverseSwap` | `boolean` | If true, amount is the amount to receive (buy). If false, amount is the amount to spend (sell). |
+| `options.providerId` | `string` | Provider to quote against; defaults to the registered default swap provider. |
+
+Returns: <code><a href="#getswapquotereturntype">GetSwapQuoteReturnType</a></code> — Quote with pricing details and the provider metadata required to build a transaction.
+
+**Example**
+
+```ts
+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`](#getswapquote) and [`buildSwapTransaction`](#buildswaptransaction) calls without an explicit `providerId` route through it. Emits `provider:default-changed`, picked up by [`watchSwapProviders`](#watchswapproviders).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`SetDefaultSwapProviderParameters`](#setdefaultswapproviderparameters) | ID of the provider to make default. |
+| `parameters.providerId`\* | `string` | ID of the provider to make default — must already be registered. |
+
+Returns: <code><a href="#setdefaultswapproviderreturntype">SetDefaultSwapProviderReturnType</a></code>.
+
+**Example**
+
+```ts
+setDefaultSwapProvider(appKit, { providerId: 'stonfi' });
+```
+
+#### watchSwapProviders
+
+Subscribe to swap provider lifecycle — fires `onChange` whenever a new provider is registered or the default swap provider switches.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`WatchSwapProvidersParameters`](#watchswapprovidersparameters) | Update callback. |
+| `parameters.onChange`\* | `() => void` | Callback fired whenever a swap provider is registered or the default swap provider changes. |
+
+Returns: <code><a href="#watchswapprovidersreturntype">WatchSwapProvidersReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+**Example**
+
+```ts
+const unsubscribe = watchSwapProviders(appKit, {
+    onChange: () => console.log('Swap providers updated'),
+});
+unsubscribe();
+```
+
+### Transactions
+
+#### createTransferTonTransaction
+
+Build a TON transfer [`TransactionRequest`](#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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`CreateTransferTonTransactionParameters`](#createtransfertontransactionparameters) | Recipient, amount and optional payload/comment/stateInit. |
+| `parameters.recipientAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Recipient address. |
+| `parameters.amount`\* | `string` | Amount in TON as a human-readable decimal string (e.g., `"1.5"`); converted to nano-TON internally. |
+| `parameters.comment` | `string` | Human-readable text comment; converted to a Base64 payload when no `payload` is supplied. |
+| `parameters.payload` | <code><a href="#base64string">Base64String</a></code> | Raw Base64 message payload — wins over `comment` when both are set. |
+| `parameters.stateInit` | <code><a href="#base64string">Base64String</a></code> | Initial state for deploying a new contract, encoded as Base64. |
+
+Returns: <code><a href="#createtransfertontransactionreturntype">CreateTransferTonTransactionReturnType</a></code> — Transaction request ready to pass to `sendTransaction`.
+
+**Example**
+
+```ts
+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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`GetTransactionStatusParameters`](#gettransactionstatusparameters) | `boc` xor `normalizedHash` and optional network override. |
+
+Returns: <code>Promise&lt;<a href="#gettransactionstatusreturntype">GetTransactionStatusReturnType</a>&gt;</code> — Status response with current state, completed/total message counts and trace details.
+
+#### sendTransaction
+
+Hand a pre-built [`TransactionRequest`](#transactionrequest) to the selected wallet for signing and broadcast — usually the second step after [`createTransferTonTransaction`](#createtransfertontransaction), [`buildSwapTransaction`](#buildswaptransaction) or [`buildStakeTransaction`](#buildstaketransaction); throws `Error('Wallet not connected')` if no wallet is currently selected.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`SendTransactionParameters`](#sendtransactionparameters) | Transaction request to broadcast. |
+
+Returns: <code>Promise&lt;<a href="#sendtransactionreturntype">SendTransactionReturnType</a>&gt;</code> — Wallet response carrying the BoC of the sent transaction.
+
+**Example**
+
+```ts
+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`](#createtransfertontransaction) + [`sendTransaction`](#sendtransaction) if you need to inspect the transaction first); throws `Error('Wallet not connected')` if no wallet is currently selected.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`TransferTonParameters`](#transfertonparameters) | Recipient, amount and optional payload/comment/stateInit. |
+| `parameters.recipientAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Recipient address. |
+| `parameters.amount`\* | `string` | Amount in TON as a human-readable decimal string (e.g., `"1.5"`); converted to nano-TON internally. |
+| `parameters.comment` | `string` | Human-readable text comment; converted to a Base64 payload when no `payload` is supplied. |
+| `parameters.payload` | <code><a href="#base64string">Base64String</a></code> | Raw Base64 message payload — wins over `comment` when both are set. |
+| `parameters.stateInit` | <code><a href="#base64string">Base64String</a></code> | Initial state for deploying a new contract, encoded as Base64. |
+
+Returns: <code>Promise&lt;<a href="#transfertonreturntype">TransferTonReturnType</a>&gt;</code> — Wallet response carrying the BoC of the sent transaction.
+
+**Example**
+
+```ts
+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`](#watchtransactionsbyaddress) for a fixed address).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`WatchTransactionsOptions`](#watchtransactionsoptions) | Update callback and optional network override. |
+| `options.onChange`\* | <code>(update: <a href="#transactionsupdate">TransactionsUpdate</a>) =&gt; void</code> | Callback fired on every transactions update from the streaming provider. |
+| `options.network` | <code><a href="#network">Network</a></code> | Network to watch on. Defaults to the selected wallet's network. |
+
+Returns: <code><a href="#watchtransactionsreturntype">WatchTransactionsReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+#### watchTransactionsByAddress
+
+Subscribe to incoming-transaction events for an arbitrary address (use [`watchTransactions`](#watchtransactions) for the selected wallet).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `options`\* | [`WatchTransactionsByAddressOptions`](#watchtransactionsbyaddressoptions) | Address, update callback and optional network override. |
+| `options.address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Address to watch — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `options.onChange`\* | <code>(update: <a href="#transactionsupdate">TransactionsUpdate</a>) =&gt; void</code> | Callback fired on every transactions update from the streaming provider. |
+| `options.network` | <code><a href="#network">Network</a></code> | 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: <code><a href="#watchtransactionsbyaddressreturntype">WatchTransactionsByAddressReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+### Wallets
+
+#### getConnectedWallets
+
+List every wallet currently connected through any registered [`Connector`](#connector).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getconnectedwalletsreturntype">GetConnectedWalletsReturnType</a></code> — Read-only array of [`WalletInterface`](#walletinterface)s.
+
+**Example**
+
+```ts
+const wallets = getConnectedWallets(appKit);
+
+console.log('Connected wallets:', wallets);
+```
+
+#### getSelectedWallet
+
+Read the wallet AppKit treats as "active" — most actions ([`getBalance`](#getbalance), [`signText`](#signtext), [`transferTon`](#transferton)) target this wallet implicitly. Returns `null` when no wallet is connected or selected.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+
+Returns: <code><a href="#getselectedwalletreturntype">GetSelectedWalletReturnType</a></code> — Selected [`WalletInterface`](#walletinterface), or `null` when none is selected.
+
+**Example**
+
+```ts
+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`](#watchselectedwallet) subscribers fire. Pass `null` to clear the selection.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`SetSelectedWalletIdParameters`](#setselectedwalletidparameters) | Wallet ID to select, or `null` to clear. |
+| `parameters.walletId`\* | `string \| null` | Wallet ID (as returned by [`WalletInterface`](#walletinterface)'s `getWalletId()`) to select; pass `null` to clear the selection. |
+
+Returns: <code><a href="#setselectedwalletidreturntype">SetSelectedWalletIdReturnType</a></code>.
+
+**Example**
+
+```ts
+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`](#connector).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`WatchConnectedWalletsParameters`](#watchconnectedwalletsparameters) | Update callback. |
+| `parameters.onChange`\* | <code>(wallets: <a href="#walletinterface">WalletInterface</a>[]) =&gt; void</code> | Callback fired whenever the list of connected wallets changes — receives the latest snapshot. |
+
+Returns: <code><a href="#watchconnectedwalletsreturntype">WatchConnectedWalletsReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+**Example**
+
+```ts
+const unsubscribe = watchConnectedWallets(appKit, {
+    onChange: (wallets) => {
+        console.log('Connected wallets updated:', wallets.length);
+    },
+});
+
+// Later: unsubscribe();
+```
+
+#### watchSelectedWallet
+
+Subscribe to selected-wallet changes — fires when [`setSelectedWalletId`](#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.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKit`\* | [`AppKit`](#appkit) | Runtime instance. |
+| `parameters`\* | [`WatchSelectedWalletParameters`](#watchselectedwalletparameters) | Update callback. |
+| `parameters.onChange`\* | <code>(wallet: <a href="#walletinterface">WalletInterface</a> \| null) =&gt; void</code> | Callback fired whenever the selected wallet changes — receives the new wallet, or `null` when the selection was cleared. |
+
+Returns: <code><a href="#watchselectedwalletreturntype">WatchSelectedWalletReturnType</a></code> — Unsubscribe function — call it to stop receiving updates.
+
+**Example**
+
+```ts
+const unsubscribe = watchSelectedWallet(appKit, {
+    onChange: (wallet) => {
+        if (wallet) {
+            console.log('Selected wallet changed:', wallet.getWalletId());
+        } else {
+            console.log('Wallet deselected');
+        }
+    },
+});
+
+// Later: unsubscribe();
+```
+
+## Type
+
+### Balances
+
+#### BalanceUpdate
+
+Update payload delivered to [`watchBalance`](#watchbalance) / [`watchBalanceByAddress`](#watchbalancebyaddress) subscribers when the watched address's TON balance changes.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `type`\* | `'balance'` | The update type field |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The account address |
+| `rawBalance`\* | <code><a href="#tokenamount">TokenAmount</a></code> | The account balance in nano units |
+| `balance`\* | `string` | The formatted balance |
+| `status`\* | <code><a href="#streamingupdatestatus">StreamingUpdateStatus</a></code> | The finality of the update |
+
+#### GetBalanceByAddressOptions
+
+Options for [`getBalanceByAddress`](#getbalancebyaddress).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Wallet address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+
+#### GetBalanceByAddressReturnType
+
+Return type of [`getBalanceByAddress`](#getbalancebyaddress).
+
+```ts
+type GetBalanceByAddressReturnType = TokenAmount;
+```
+
+#### GetBalanceOptions
+
+Options for [`getBalance`](#getbalance).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="#network">Network</a></code> | Network to read the balance from. Defaults to the selected wallet's network. |
+
+#### GetBalanceReturnType
+
+Return type of [`getBalance`](#getbalance).
+
+```ts
+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).
+
+```ts
+type StreamingUpdateStatus = 'pending' | 'confirmed' | 'finalized' | 'invalidated';
+```
+
+#### WatchBalanceByAddressOptions
+
+Options for [`watchBalanceByAddress`](#watchbalancebyaddress).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Wallet address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+| `onChange`\* | <code>(update: <a href="#balanceupdate">BalanceUpdate</a>) =&gt; void</code> | Callback fired on every balance update from the streaming provider. |
+
+#### WatchBalanceByAddressReturnType
+
+Return type of [`watchBalanceByAddress`](#watchbalancebyaddress) — call to stop receiving updates.
+
+```ts
+type WatchBalanceByAddressReturnType = () => void;
+```
+
+#### WatchBalanceOptions
+
+Options for [`watchBalance`](#watchbalance).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="#network">Network</a></code> | Network to watch on. Defaults to the selected wallet's network. |
+| `onChange`\* | <code>(update: <a href="#balanceupdate">BalanceUpdate</a>) =&gt; void</code> | Callback fired on every balance update from the streaming provider. |
+
+#### WatchBalanceReturnType
+
+Return type of [`watchBalance`](#watchbalance) — call to stop receiving updates.
+
+```ts
+type WatchBalanceReturnType = () => void;
+```
+
+### Client
+
+#### AddressBook
+
+Map of raw addresses to their resolved metadata, returned alongside indexed lists (e.g. [`JettonsResponse`](#jettonsresponse), [`NFTsResponse`](#nftsresponse)) so consumers can render labels without extra lookups.
+
+```ts
+type AddressBook = {
+    [key: UserFriendlyAddress]: AddressBookEntry;
+};
+```
+
+#### AddressBookEntry
+
+Single entry inside an [`AddressBook`](#addressbook) — pairs the user-friendly address with optional domain name and the list of contract interfaces it implements.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The human-readable representation of the blockchain address |
+| `domain` | `string` | The domain name associated with the address if available |
+| `interfaces`\* | `string[]` | List of supported interfaces by the address |
+
+#### ApiClient
+
+Indexer/RPC client interface used by AppKit to read on-chain state — balance, jettons, NFTs, masterchain seqno, etc. Each [`Network`](#network) resolves to its own `ApiClient` via [`AppKitNetworkManager`](#appkitnetworkmanager); apps usually pull one through [`getApiClient`](#getapiclient) rather than constructing it directly.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `nftItemsByAddress`\* | <code>(request: NFTsRequest) =&gt; Promise&lt;<a href="#nftsresponse">NFTsResponse</a>&gt;</code> | Look up specific NFT items by address. |
+| `nftItemsByOwner`\* | <code>(request: UserNFTsRequest) =&gt; Promise&lt;<a href="#nftsresponse">NFTsResponse</a>&gt;</code> | List NFT items held by an owner; supports pagination. |
+| `fetchEmulation`\* | <code>(messageBoc: <a href="#base64string">Base64String</a>, ignoreSignature?: boolean) =&gt; Promise&lt;ToncenterEmulationResult&gt;</code> | Run an emulation pass on a Base64-encoded BoC; returns the predicted account-state changes and emitted events without sending the message. |
+| `sendBoc`\* | <code>(boc: <a href="#base64string">Base64String</a>) =&gt; Promise&lt;string&gt;</code> | Broadcast a signed BoC to the network and return the message hash. |
+| `runGetMethod`\* | <code>(address: <a href="#userfriendlyaddress">UserFriendlyAddress</a>, method: string, stack?: RawStackItem[], seqno?: number) =&gt; Promise&lt;GetMethodResult&gt;</code> | Run an on-chain `get` method against a contract and read its TVM stack output. |
+| `getAccountState`\* | <code>(address: <a href="#userfriendlyaddress">UserFriendlyAddress</a>, seqno?: number) =&gt; Promise&lt;FullAccountState&gt;</code> | Read the full on-chain account state (code, data, status, balance) for an address. |
+| `getBalance`\* | <code>(address: <a href="#userfriendlyaddress">UserFriendlyAddress</a>, seqno?: number) =&gt; Promise&lt;<a href="#tokenamount">TokenAmount</a>&gt;</code> | Read the TON balance of an address in raw nanotons. |
+| `getAccountTransactions`\* | `(request: TransactionsByAddressRequest) => Promise<TransactionsResponse>` | List transactions for an address; ordered newest-first, paginated via `LimitRequest`. |
+| `getTransactionsByHash`\* | `(request: GetTransactionByHashRequest) => Promise<TransactionsResponse>` | Fetch a transaction by its message or body hash. |
+| `getPendingTransactions`\* | `(request: GetPendingTransactionsRequest) => Promise<TransactionsResponse>` | List pending (unconfirmed) transactions by accounts or trace ids; useful for "in-flight" UIs. |
+| `getTrace`\* | `(request: GetTraceRequest) => Promise<ToncenterTracesResponse>` | Fetch a confirmed trace (the tree of internal messages spawned by an external one). |
+| `getPendingTrace`\* | `(request: GetPendingTraceRequest) => Promise<ToncenterTracesResponse>` | Fetch a pending trace by external-message hash, while it's still in flight. |
+| `resolveDnsWallet`\* | `(domain: string) => Promise<string \| null>` | Resolve a TON DNS domain to the wallet address it points at; `null` when unset. |
+| `backResolveDnsWallet`\* | <code>(address: <a href="#userfriendlyaddress">UserFriendlyAddress</a>) =&gt; Promise&lt;string \| null&gt;</code> | Reverse-resolve a wallet address to a TON DNS domain that points at it; `null` when none. |
+| `jettonsByAddress`\* | `(request: GetJettonsByAddressRequest) => Promise<ToncenterResponseJettonMasters>` | Look up jetton masters by address — returns indexer metadata for the requested jettons. |
+| `jettonsByOwnerAddress`\* | <code>(request: GetJettonsByOwnerRequest) =&gt; Promise&lt;<a href="#jettonsresponse">JettonsResponse</a>&gt;</code> | List jetton holdings owned by an address — returns balances + jetton-master metadata. |
+| `getEvents`\* | `(request: GetEventsRequest) => Promise<GetEventsResponse>` | List parsed account events (jetton transfers, NFT moves, swaps, …) for an address. |
+| `getMasterchainInfo`\* | `() => Promise<MasterchainInfo>` | Read the latest masterchain info — last seqno, shards, time. |
+
+#### ApiClientConfig
+
+Configuration accepted by [`NetworkConfig`](#networkconfig)'s `apiClient` — picks an [`ApiClient`](#apiclient) implementation (Toncenter / TonAPI) and supplies its endpoint URL plus optional API key.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `url` | `string` | Base URL of the indexer endpoint. Defaults to `'https://toncenter.com'` for mainnet, `'https://testnet.toncenter.com'` for testnet. |
+| `key` | `string` | API key forwarded to the indexer for higher rate limits. |
+
+#### GetApiClientOptions
+
+Options for [`getApiClient`](#getapiclient).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network`\* | <code><a href="#network">Network</a></code> | Network whose configured [`ApiClient`](#apiclient) should be returned. |
+
+#### GetApiClientReturnType
+
+Return type of [`getApiClient`](#getapiclient).
+
+```ts
+type GetApiClientReturnType = ApiClient;
+```
+
+#### TokenInfo
+
+Display metadata for a token (TON, jetton, or NFT) — name, symbol, image and animation as reported by the indexer; surfaced as [`Jetton`](#jetton)'s `info` and [`NFT`](#nft)'s `info`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Display name of the token |
+| `description` | `string` | Human-readable description of the token |
+| `image` | `TokenImage` | Token image in various sizes |
+| `animation` | `TokenAnimation` | Animated media associated with the token |
+| `symbol` | `string` | Ticker symbol of the token (e.g., "TON", "USDT") |
+
+### Connectors
+
+#### AddConnectorParameters
+
+Connector instance or factory accepted by [`addConnector`](#addconnector) — same shape used in [`AppKitConfig`](#appkitconfig)'s `connectors`.
+
+```ts
+type AddConnectorParameters = ConnectorInput;
+```
+
+#### AddConnectorReturnType
+
+Return type of [`addConnector`](#addconnector) — call to remove the connector from AppKit.
+
+```ts
+type AddConnectorReturnType = () => void;
+```
+
+#### ConnectParameters
+
+Parameters accepted by [`connect`](#connect).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `connectorId`\* | `string` | ID of the registered connector to drive the connection through (e.g., `'tonconnect'`). |
+
+#### ConnectReturnType
+
+Return type of [`connect`](#connect).
+
+```ts
+type ConnectReturnType = void;
+```
+
+#### Connector
+
+Wallet connector contract — the protocol-specific bridge (TonConnect, embedded wallet, …) AppKit drives once you register it via [`AppKitConfig`](#appkitconfig)'s `connectors`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id`\* | `string` | Stable connector identifier, unique within an AppKit instance. |
+| `type`\* | `string` | Protocol type (e.g. `'tonconnect'`). Multiple connectors can share the same type. |
+| `metadata`\* | <code><a href="#connectormetadata">ConnectorMetadata</a></code> | Display metadata (name, icon) shown in connect UIs. |
+| `destroy`\* | `() => void` | Release any resources held by the connector. Call on app teardown. |
+| `connectWallet`\* | <code>(network?: <a href="#network">Network</a>) =&gt; Promise&lt;void&gt;</code> | Initiate a wallet connection flow on the given network. |
+| `disconnectWallet`\* | `() => Promise<void>` | Disconnect the currently connected wallet, if any. |
+| `getConnectedWallets`\* | <code>() =&gt; <a href="#walletinterface">WalletInterface</a>[]</code> | Wallets currently connected through this connector. |
+
+#### ConnectorFactory
+
+Factory that builds a [`Connector`](#connector) from [`ConnectorFactoryContext`](#connectorfactorycontext); AppKit calls it at registration time.
+
+```ts
+type ConnectorFactory = (ctx: ConnectorFactoryContext) => Connector;
+```
+
+#### ConnectorFactoryContext
+
+Context that AppKit injects into a [`ConnectorFactory`](#connectorfactory) when building the connector at registration time.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `networkManager`\* | <code><a href="#appkitnetworkmanager">AppKitNetworkManager</a></code> | Network manager the connector should use for client lookups and default-network reads. |
+| `eventEmitter`\* | <code><a href="#appkitemitter">AppKitEmitter</a></code> | Event emitter the connector should publish wallet/connection events to. |
+| `ssr` | `boolean` | `true` when the connector is constructed during server-side rendering — connectors may skip browser-only setup. |
+
+#### ConnectorInput
+
+Either a ready-made [`Connector`](#connector) or a [`ConnectorFactory`](#connectorfactory) that produces one — the value accepted by [`addConnector`](#addconnector) and [`AppKitConfig`](#appkitconfig)'s `connectors`.
+
+```ts
+type ConnectorInput = Connector | ConnectorFactory;
+```
+
+#### ConnectorMetadata
+
+Display metadata for a [`Connector`](#connector), surfaced in connect UIs to help users pick the right wallet.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name`\* | `string` | Human-readable connector name (e.g., `'TonConnect'`). |
+| `iconUrl` | `string` | Optional URL of an icon shown next to the name. |
+
+#### DisconnectParameters
+
+Parameters accepted by [`disconnect`](#disconnect).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `connectorId`\* | `string` | ID of the registered connector whose wallet should be disconnected. |
+
+#### DisconnectReturnType
+
+Return type of [`disconnect`](#disconnect).
+
+```ts
+type DisconnectReturnType = void;
+```
+
+#### GetConnectorByIdOptions
+
+Options for [`getConnectorById`](#getconnectorbyid).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id`\* | `string` | ID of the connector to look up. |
+
+#### GetConnectorByIdReturnType
+
+Return type of [`getConnectorById`](#getconnectorbyid) — `undefined` when no connector with that id is registered.
+
+```ts
+type GetConnectorByIdReturnType = Connector | undefined;
+```
+
+#### GetConnectorsReturnType
+
+Return type of [`getConnectors`](#getconnectors) — read-only view of the registered-connectors array.
+
+```ts
+type GetConnectorsReturnType = readonly Connector[];
+```
+
+#### TonConnectConnector
+
+[`Connector`](#connector) produced by [`createTonConnectConnector`](#createtonconnectconnector) — extends the base interface with the underlying `TonConnectUI` instance for advanced flows that need direct access (e.g., custom modals).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id`\* | `string` | Stable connector identifier, unique within an AppKit instance. |
+| `type`\* | `string` | Protocol type (e.g. `'tonconnect'`). Multiple connectors can share the same type. |
+| `metadata`\* | <code><a href="#connectormetadata">ConnectorMetadata</a></code> | Display metadata (name, icon) shown in connect UIs. |
+| `destroy`\* | `() => void` | Release any resources held by the connector. Call on app teardown. |
+| `connectWallet`\* | <code>(network?: <a href="#network">Network</a>) =&gt; Promise&lt;void&gt;</code> | Initiate a wallet connection flow on the given network. |
+| `disconnectWallet`\* | `() => Promise<void>` | Disconnect the currently connected wallet, if any. |
+| `getConnectedWallets`\* | <code>() =&gt; <a href="#walletinterface">WalletInterface</a>[]</code> | Wallets currently connected through this connector. |
+| `tonConnectUI`\* | `TonConnectUI \| null` | Underlying `TonConnectUI` instance — `null` during SSR or before the connector has been initialised. Apps that need to drive the modal directly (e.g. custom UI flows) can read this and call its methods. |
+
+#### TonConnectConnectorConfig
+
+Configuration accepted by [`createTonConnectConnector`](#createtonconnectconnector).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Connector ID. Defaults to [`TONCONNECT_DEFAULT_CONNECTOR_ID`](#tonconnect_default_connector_id) (`'tonconnect'`); set this when you need to register multiple TonConnect-flavoured connectors side by side. |
+| `metadata` | <code><a href="#connectormetadata">ConnectorMetadata</a></code> | Display metadata override; merged on top of TonConnect's default name and icon. |
+| `tonConnectOptions` | `TonConnectUiCreateOptions` | Options forwarded to the underlying `TonConnectUI` constructor (manifest URL, etc.). Ignored when `tonConnectUI` is supplied. |
+| `tonConnectUI` | `TonConnectUI` | Pre-built `TonConnectUI` instance to reuse; when set, the connector skips its own instantiation and `tonConnectOptions` is ignored. |
+
+#### WatchConnectorByIdParameters
+
+Parameters accepted by [`watchConnectorById`](#watchconnectorbyid).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id`\* | `string` | ID of the connector to watch. |
+| `onChange`\* | <code>(connector: <a href="#connector">Connector</a> \| undefined) =&gt; void</code> | Callback invoked when the connector with the watched id is registered or unregistered — receives the connector itself, or `undefined` when none is registered under that id. |
+
+#### WatchConnectorByIdReturnType
+
+Return type of [`watchConnectorById`](#watchconnectorbyid) — call to stop receiving updates.
+
+```ts
+type WatchConnectorByIdReturnType = () => void;
+```
+
+#### WatchConnectorsParameters
+
+Parameters accepted by [`watchConnectors`](#watchconnectors).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | <code>(connectors: readonly <a href="#connector">Connector</a>[]) =&gt; void</code> | Callback invoked when the list of registered connectors changes — receives the current list. |
+
+#### WatchConnectorsReturnType
+
+Return type of [`watchConnectors`](#watchconnectors) — call to stop receiving updates.
+
+```ts
+type WatchConnectorsReturnType = () => void;
+```
+
+### Core
+
+#### AppKitConfig
+
+Constructor options for [`AppKit`](#appkit) — networks, connectors, providers and runtime flags.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `networks` | <code><a href="#networkadapters">NetworkAdapters</a></code> | Map of chain ID to [`NetworkConfig`](#networkconfig) (which holds the api-client setup); if omitted, AppKit defaults to mainnet only. |
+| `connectors` | <code><a href="#connectorinput">ConnectorInput</a>[]</code> | Wallet connectors registered at startup. |
+| `defaultNetwork` | <code><a href="#network">Network</a></code> | Default network. |
+| `providers` | <code><a href="#providerinput">ProviderInput</a>[]</code> | Providers registered at startup. |
+| `ssr` | `boolean` | Set to `true` to enable server-side rendering support. |
+
+#### AppKitEmitter
+
+Strongly-typed event emitter exposed as [`AppKit`](#appkit)'s `emitter`; `appKit.emitter.on(name, handler)` returns an unsubscribe function.
+
+```ts
+type AppKitEmitter = EventEmitter<AppKitEvents>;
+```
+
+#### AppKitEvents
+
+Map of every event name AppKit can emit to its payload type, used to type listeners on [`AppKitEmitter`](#appkitemitter).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `connector:added`\* | <code><a href="#connectoraddedpayload">ConnectorAddedPayload</a></code> | Fired by [`addConnector`](#addconnector) when a connector is registered with AppKit. |
+| `connector:removed`\* | <code><a href="#connectorremovedpayload">ConnectorRemovedPayload</a></code> | Fired by `removeConnector` when a connector is unregistered from AppKit. |
+| `connector:wallets-updated`\* | <code><a href="#connectorwalletsupdatedpayload">ConnectorWalletsUpdatedPayload</a></code> | Fired by a connector whenever its connected-wallets list changes (connect, disconnect, or account switch inside the wallet). |
+| `wallets:updated`\* | <code>&lbrace; wallets: <a href="#walletinterface">WalletInterface</a>[] &rbrace;</code> | Fired by AppKit's wallet manager after re-aggregating connectors — `wallets` is the full current set. |
+| `wallets:selection-changed`\* | `{ walletId: string \| null }` | Fired when the selected wallet changes — `walletId` is the new selection, or `null` when cleared. |
+| `networks:updated`\* | `Record<string, never>` | Fired by the network manager when a network's API client is registered or replaced via `setClient`. |
+| `networks:default-changed`\* | <code><a href="#defaultnetworkchangedpayload">DefaultNetworkChangedPayload</a></code> | Fired by [`setDefaultNetwork`](#setdefaultnetwork) — carries the new default network, or `undefined` when the constraint was cleared. |
+| `streaming:balance-update`\* | <code><a href="#balanceupdate">BalanceUpdate</a></code> | Fired by a streaming provider when a watched address's TON balance changes. |
+| `streaming:transactions`\* | <code><a href="#transactionsupdate">TransactionsUpdate</a></code> | Fired by a streaming provider when new transactions land for a watched address. |
+| `streaming:jettons-update`\* | <code><a href="#jettonupdate">JettonUpdate</a></code> | Fired by a streaming provider when a watched address's jetton holdings change. |
+| `provider:registered`\* | `BaseProviderUpdate` | Fired by a DeFi manager when a provider is registered through it (carries the provider's id and kind). |
+| `provider:default-changed`\* | `BaseProviderUpdate` | Fired by a DeFi manager when its default provider is set or cleared (carries the new default's id and kind). |
+
+#### ConnectorAddedPayload
+
+Payload of `connector:added` events — the connector that was just registered.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `connector`\* | <code><a href="#connector">Connector</a></code> | [`Connector`](#connector) just registered with AppKit. |
+
+#### ConnectorRemovedPayload
+
+Payload of `connector:removed` events — the connector that was just unregistered.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `connector`\* | <code><a href="#connector">Connector</a></code> | [`Connector`](#connector) just unregistered from AppKit (already torn down via `destroy()`). |
+
+#### ConnectorWalletsUpdatedPayload
+
+Payload of `connector:wallets-updated` events — fired by a connector when its connected-wallets list changes (connect, disconnect, or account switch inside the wallet).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `connectorId`\* | `string` | ID of the [`Connector`](#connector) whose wallets just changed. |
+| `wallets`\* | <code><a href="#walletinterface">WalletInterface</a>[]</code> | Wallets currently exposed by the connector — empty when the wallet was just disconnected. |
+
+#### DefaultNetworkChangedPayload
+
+Payload of `networks:default-changed` events — the new default network, or `undefined` when cleared.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network`\* | <code><a href="#network">Network</a> \| undefined</code> | New default network, or `undefined` when the constraint is cleared. |
+
+#### EventListener
+
+Listener callback signature accepted by [`EventEmitter`](#eventemitter)'s `on` — receives a [`KitEvent`](#kitevent) for the given event type and may return a Promise the emitter awaits.
+
+```ts
+type EventListener = (event: KitEvent<T>) => void | Promise<void>;
+```
+
+#### EventPayload
+
+Generic event-payload constraint — an `object` that the typed event-name → payload map maps to.
+
+```ts
+type EventPayload = object;
+```
+
+#### KitEvent
+
+Envelope every [`EventEmitter`](#eventemitter) listener receives — `type` is the event name, `payload` is the event-specific data, `source` identifies who emitted it, and `timestamp` is the wall-clock millisecond mark.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `type`\* | `string` | Event name (e.g., `'connector:wallets-updated'`). |
+| `payload`\* | `T = any` | Event-specific payload — typed via the emitter's event-name → payload map. |
+| `source` | `string` | Identifier of the component that emitted the event (connector id, manager name, etc.); useful for filtering listeners. |
+| `timestamp`\* | `number` | Wall-clock timestamp in milliseconds when the event was emitted. |
+
+#### SharedKitEvents
+
+Event-name → payload map shared between AppKit and walletkit; AppKit extends it with its own connector, wallet and network events to type [`AppKitEmitter`](#appkitemitter).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `streaming:balance-update`\* | <code><a href="#balanceupdate">BalanceUpdate</a></code> | Fired by a streaming provider when a watched address's TON balance changes. |
+| `streaming:transactions`\* | <code><a href="#transactionsupdate">TransactionsUpdate</a></code> | Fired by a streaming provider when new transactions land for a watched address. |
+| `streaming:jettons-update`\* | <code><a href="#jettonupdate">JettonUpdate</a></code> | Fired by a streaming provider when a watched address's jetton holdings change. |
+| `provider:registered`\* | `BaseProviderUpdate` | Fired by a DeFi manager when a provider is registered through it (carries the provider's id and kind). |
+| `provider:default-changed`\* | `BaseProviderUpdate` | Fired by a DeFi manager when its default provider is set or cleared (carries the new default's id and kind). |
+
+### Crypto Onramp
+
+#### CreateCryptoOnrampDepositOptions
+
+Options for [`createCryptoOnrampDeposit`](#createcryptoonrampdeposit) — extends [`CryptoOnrampDepositParams`](#cryptoonrampdepositparams) with an optional provider override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `quote`\* | <code><a href="#cryptoonrampquote">CryptoOnrampQuote</a>&lt;TQuoteMetadata = unknown&gt;</code> | Quote to execute the deposit against (contains recipientAddress and provider metadata) |
+| `refundAddress`\* | `string` | Address to refund the crypto to in case of failure |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `providerId` | `string` | Provider to create the deposit through; defaults to `quote.providerId`, then to the default provider. |
+
+#### CreateCryptoOnrampDepositReturnType
+
+Return type of [`createCryptoOnrampDeposit`](#createcryptoonrampdeposit).
+
+```ts
+type CreateCryptoOnrampDepositReturnType = Promise<CryptoOnrampDeposit>;
+```
+
+#### CryptoOnrampDeposit
+
+Deposit details returned by a crypto onramp provider.
+
+The user must send `amount` of `sourceCurrencyAddress` to `address` on `sourceChain`
+to complete the onramp; the provider then delivers the target crypto to the
+user's TON address.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `depositId`\* | `string` | Deposit id |
+| `address`\* | `string` | Deposit address on the source chain |
+| `amount`\* | `string` | Exact amount of source crypto the user must send |
+| `sourceCurrencyAddress`\* | `string` | Source crypto currency address (contract address or 0x0... for native) |
+| `sourceChain`\* | `string` | Source chain identifier in CAIP-2 format (e.g. 'eip155:42161'). |
+| `memo` | `string` | Optional memo / tag required by some chains (e.g. XRP, TON comment) |
+| `expiresAt` | `number` | Unix timestamp (ms) after which the deposit offer is no longer valid |
+| `chainWarning` | `string` | Chain-specific warning to show the user (e.g. "send only on Solana") |
+| `providerId`\* | `string` | Identifier of the provider that issued this deposit |
+
+#### CryptoOnrampDepositParams
+
+Parameters for creating a crypto onramp deposit.
+
+The recipient is taken from `quote.recipientAddress` set at quote time.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `quote`\* | <code><a href="#cryptoonrampquote">CryptoOnrampQuote</a>&lt;TQuoteMetadata = unknown&gt;</code> | Quote to execute the deposit against (contains recipientAddress and provider metadata) |
+| `refundAddress`\* | `string` | Address to refund the crypto to in case of failure |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+
+#### CryptoOnrampProviderInterface
+
+Interface that all crypto onramp providers must implement
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `type`\* | `'crypto-onramp'` | Provider kind discriminator pinned to `'crypto-onramp'` so [`registerProvider`](#registerprovider) routes it to the crypto-onramp manager. |
+| `providerId`\* | `string` | Unique identifier for the provider |
+| `getMetadata`\* | <code>() =&gt; <a href="#cryptoonrampprovidermetadata">CryptoOnrampProviderMetadata</a></code> | Get static metadata for the provider (display name, logo, url). |
+| `getQuote`\* | <code>(params: <a href="#cryptoonrampquoteparams">CryptoOnrampQuoteParams</a>&lt;TQuoteOptions&gt;) =&gt; Promise&lt;<a href="#cryptoonrampquote">CryptoOnrampQuote</a>&gt;</code> | Get a quote for onramping from another crypto asset into a TON asset |
+| `createDeposit`\* | <code>(params: <a href="#cryptoonrampdepositparams">CryptoOnrampDepositParams</a>&lt;TDepositOptions&gt;) =&gt; Promise&lt;<a href="#cryptoonrampdeposit">CryptoOnrampDeposit</a>&gt;</code> | Create a deposit for a previously obtained quote |
+| `getStatus`\* | <code>(params: <a href="#cryptoonrampstatusparams">CryptoOnrampStatusParams</a>) =&gt; Promise&lt;<a href="#cryptoonrampstatus">CryptoOnrampStatus</a>&gt;</code> | Get the status of a deposit |
+| `getSupportedNetworks`\* | <code>() =&gt; <a href="#network">Network</a>[]</code> | Networks this provider can operate on. Consumers should check before calling provider methods. Implementations may return a static list or compute it dynamically (e.g. from runtime config). |
+
+#### CryptoOnrampProviderMetadata
+
+Static metadata for a crypto-onramp provider.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name`\* | `string` | Human-readable provider name (e.g. 'Swaps.xyz') |
+| `logo` | `string` | URL to the provider's logo image |
+| `url` | `string` | URL to the provider's website |
+| `isRefundAddressRequired` | `boolean` | Whether this provider requires a refund address on the source chain. When true, the UI must collect a refund address before creating a deposit. |
+| `isReversedAmountSupported` | `boolean` | Whether this provider supports reversed (target-amount) quotes. When false, the UI should hide the direction toggle and only allow source-amount input. |
+
+#### CryptoOnrampProviderMetadataOverride
+
+Used in provider configuration to override fields of the provider's metadata.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Override the provider's display name |
+| `logo` | `string` | Override the provider's logo URL |
+| `url` | `string` | Override the provider's website URL |
+
+#### CryptoOnrampQuote
+
+Crypto onramp quote response with pricing information
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `sourceCurrencyAddress`\* | `string` | Source crypto currency address (contract address or 0x0... for native) |
+| `sourceChain`\* | `string` | Source chain identifier in CAIP-2 format (e.g. 'eip155:42161'). |
+| `targetCurrencyAddress`\* | `string` | Target crypto currency address on TON (contract address or 0x0... for native) |
+| `sourceAmount`\* | `string` | Amount of source crypto to send |
+| `targetAmount`\* | `string` | Amount of target crypto to receive |
+| `rate`\* | `string` | Exchange rate (amount of target per 1 unit of source) |
+| `recipientAddress`\* | `string` | TON address that will receive the target crypto |
+| `providerId`\* | `string` | Identifier of the crypto onramp provider |
+| `metadata` | `TMetadata = unknown` | Provider-specific metadata for the quote (e.g. raw response needed to execute) |
+
+#### CryptoOnrampQuoteParams
+
+Parameters for requesting a crypto-to-crypto onramp quote.
+
+The target network is always TON, so only the source side is parameterised.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `amount`\* | `string` | Amount to onramp (either source or target crypto, depending on isSourceAmount) |
+| `sourceCurrencyAddress`\* | `string` | Source crypto currency address (contract address or 0x0... for native) |
+| `sourceChain`\* | `string` | Source chain identifier in CAIP-2 format (e.g. 'eip155:1' for Ethereum mainnet, 'eip155:42161' for Arbitrum One). Providers map this to their own chain identifiers internally. |
+| `targetCurrencyAddress`\* | `string` | Target crypto currency address on TON (contract address or 0x0... for native) |
+| `recipientAddress`\* | `string` | TON address that will receive the target crypto |
+| `refundAddress` | `string` | Refund address for the source crypto |
+| `isSourceAmount` | `boolean` | If true, `amount` is the source amount to spend. If false, `amount` is the target amount to receive. Defaults to true when omitted. |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+
+#### CryptoOnrampStatus
+
+Final state of a crypto-onramp deposit returned by [`getCryptoOnrampStatus`](#getcryptoonrampstatus) — `'success'` (delivered to the recipient), `'pending'` (still in flight), or `'failed'` (provider could not complete the deposit).
+
+```ts
+type CryptoOnrampStatus = 'success' | 'pending' | 'failed';
+```
+
+#### CryptoOnrampStatusParams
+
+Parameters accepted by [`getCryptoOnrampStatus`](#getcryptoonrampstatus) — identifies a previously created deposit and the provider that issued it.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `depositId`\* | `string` | Deposit id |
+| `providerId`\* | `string` | Identifier of the provider that issued this deposit |
+
+#### GetCryptoOnrampProviderOptions
+
+Options for [`getCryptoOnrampProvider`](#getcryptoonrampprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Provider ID to look up; when omitted, returns the registered default provider. |
+
+#### GetCryptoOnrampProviderReturnType
+
+Return type of [`getCryptoOnrampProvider`](#getcryptoonrampprovider).
+
+```ts
+type GetCryptoOnrampProviderReturnType = CryptoOnrampProviderInterface;
+```
+
+#### GetCryptoOnrampProvidersReturnType
+
+Return type of [`getCryptoOnrampProviders`](#getcryptoonrampproviders).
+
+```ts
+type GetCryptoOnrampProvidersReturnType = CryptoOnrampProviderInterface[];
+```
+
+#### GetCryptoOnrampQuoteOptions
+
+Options for [`getCryptoOnrampQuote`](#getcryptoonrampquote) — extends [`CryptoOnrampQuoteParams`](#cryptoonrampquoteparams) with an optional provider override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `amount`\* | `string` | Amount to onramp (either source or target crypto, depending on isSourceAmount) |
+| `sourceCurrencyAddress`\* | `string` | Source crypto currency address (contract address or 0x0... for native) |
+| `sourceChain`\* | `string` | Source chain identifier in CAIP-2 format (e.g. 'eip155:1' for Ethereum mainnet, 'eip155:42161' for Arbitrum One). Providers map this to their own chain identifiers internally. |
+| `targetCurrencyAddress`\* | `string` | Target crypto currency address on TON (contract address or 0x0... for native) |
+| `recipientAddress`\* | `string` | TON address that will receive the target crypto |
+| `refundAddress` | `string` | Refund address for the source crypto |
+| `isSourceAmount` | `boolean` | If true, `amount` is the source amount to spend. If false, `amount` is the target amount to receive. Defaults to true when omitted. |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `providerId` | `string` | Provider to quote against; defaults to the registered default provider. |
+
+#### GetCryptoOnrampQuoteReturnType
+
+Return type of [`getCryptoOnrampQuote`](#getcryptoonrampquote).
+
+```ts
+type GetCryptoOnrampQuoteReturnType = Promise<CryptoOnrampQuote>;
+```
+
+#### GetCryptoOnrampStatusOptions
+
+Options for [`getCryptoOnrampStatus`](#getcryptoonrampstatus) — extends [`CryptoOnrampStatusParams`](#cryptoonrampstatusparams) with an optional provider override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `depositId`\* | `string` | Deposit id |
+| `providerId`\* | `string` | Identifier of the provider that issued this deposit |
+
+#### GetCryptoOnrampStatusReturnType
+
+Return type of [`getCryptoOnrampStatus`](#getcryptoonrampstatus).
+
+```ts
+type GetCryptoOnrampStatusReturnType = Promise<CryptoOnrampStatus>;
+```
+
+#### LayerswapProviderConfig
+
+Configuration accepted by [`createLayerswapProvider`](#createlayerswapprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `apiKey` | `string` | Optional API key. Forwarded as `X-LS-APIKEY` when provided. |
+| `apiUrl` | `string` | Override the base API URL. Defaults to https://api.layerswap.io/api/v2 |
+
+#### LayerswapQuoteMetadata
+
+Provider-specific metadata returned on a [`CryptoOnrampQuote`](#cryptoonrampquote)'s `metadata` from Layerswap — carries the swap id and deposit action that [`createCryptoOnrampDeposit`](#createcryptoonrampdeposit) reads to build the deposit.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `swapId`\* | `string` | Layerswap swap id created at quote time and reused by `createDeposit` / `getStatus`. |
+| `depositAddress`\* | `string` | Pre-computed deposit address on the source chain that the user must send funds to. |
+| `sourceAmountBaseUnits`\* | `string` | Source-chain amount the user must send, in raw base units (e.g., wei). |
+| `targetAmountBaseUnits`\* | `string` | Target-chain amount the user receives, in raw base units (e.g., nanotons). |
+
+#### SwapsXyzProviderConfig
+
+Configuration accepted by [`createSwapsXyzProvider`](#createswapsxyzprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `apiKey`\* | `string` | API key issued by swaps.xyz (passed as `x-api-key`) |
+| `apiUrl` | `string` | Override the base API URL. Defaults to https://api-v2.swaps.xyz/api |
+| `defaultSender` | `string` | EVM address used as `sender` on getAction requests. Required by the API even for deposit flows where the actual payer is unknown. Defaults to a null address when omitted. |
+
+#### SwapsXyzQuoteMetadata
+
+Provider-specific metadata returned on a [`CryptoOnrampQuote`](#cryptoonrampquote)'s `metadata` from swaps.xyz — carries the resolved action and bridge route that [`createCryptoOnrampDeposit`](#createcryptoonrampdeposit) needs.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `sender`\* | `string` | EVM sender address swaps.xyz was quoted for; required when later calling `createDeposit`. |
+| `response`\* | `SwapsXyzGetActionResponse` | Raw `getAction` response cached at quote time so `createDeposit` doesn't need an extra round-trip. |
+
+#### SwapsXyzQuoteOptions
+
+swaps.xyz-specific options forwarded through `providerOptions` on [`CryptoOnrampQuoteParams`](#cryptoonrampquoteparams).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `slippageBps` | `number` | Slippage tolerance in basis points (0-10000). Defaults to 100 (1%). |
+
+#### WatchCryptoOnrampProvidersParameters
+
+Parameters accepted by [`watchCryptoOnrampProviders`](#watchcryptoonrampproviders).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | `() => void` | Callback fired whenever a crypto-onramp provider is registered or the default crypto-onramp provider changes. |
+
+#### WatchCryptoOnrampProvidersReturnType
+
+Return type of [`watchCryptoOnrampProviders`](#watchcryptoonrampproviders) — call to stop receiving updates.
+
+```ts
+type WatchCryptoOnrampProvidersReturnType = () => void;
+```
+
+### DeFi
+
+#### DefiManagerAPI
+
+Shape every DeFi domain manager (swap, staking, onramp, crypto-onramp) satisfies — provider registration, default-provider selection and lookups; mostly relevant when authoring a new domain manager.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `createFactoryContext`\* | <code>() =&gt; <a href="#providerfactorycontext">ProviderFactoryContext</a></code> | Build a fresh [`ProviderFactoryContext`](#providerfactorycontext) the manager hands to provider factories at registration time. |
+| `registerProvider`\* | <code>(provider: <a href="#providerinput">ProviderInput</a>&lt;T&gt;) =&gt; void</code> | Register a new provider. If a provider with the same id is already registered, it is replaced. |
+| `removeProvider`\* | `(provider: T) => void` | Remove a previously registered provider. No-op if the provider was not registered. |
+| `setDefaultProvider`\* | `(providerId: string) => void` | Set the default provider |
+| `getProvider`\* | `(providerId?: string) => T` | Get a registered provider |
+| `getProviders`\* | `() => T[]` | Get all registered providers. The returned array keeps a stable reference until the provider list changes. |
+| `hasProvider`\* | `(providerId: string) => boolean` | Check if a provider is registered |
+
+#### DefiProvider
+
+Base interface implemented by every DeFi provider (swap, staking, onramp, crypto-onramp) — exposes `providerId`, `type` and `getSupportedNetworks`. Domain-specific provider interfaces extend this with quote/build/status methods.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `type`\* | <code><a href="#defiprovidertype">DefiProviderType</a></code> | Provider kind discriminator narrowed to the DeFi-domain literals so the right manager picks it up at registration time. |
+| `getSupportedNetworks`\* | <code>() =&gt; <a href="#network">Network</a>[]</code> | Networks this provider can operate on. Consumers should check before calling provider methods. Implementations may return a static list or compute it dynamically (e.g. from runtime config). |
+| `providerId`\* | `string` | Stable provider identifier, unique within the manager that registered it. |
+
+#### DefiProviderType
+
+Discriminator that tags every [`DefiProvider`](#defiprovider) with its kind — `'swap'`, `'staking'`, `'onramp'`, or `'crypto-onramp'`; used by [`registerProvider`](#registerprovider) to dispatch to the right manager.
+
+```ts
+type DefiProviderType = 'swap' | 'staking' | 'onramp' | 'crypto-onramp';
+```
+
+#### ProviderFactoryContext
+
+Context that AppKit's DeFi managers inject into a [`ProviderInput`](#providerinput) factory at registration time — gives the provider access to AppKit's network manager and event emitter, plus an `ssr` flag for server-side initialisation.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `networkManager`\* | `NetworkManager` | Network manager the provider should use for client lookups and default-network reads. |
+| `eventEmitter`\* | <code><a href="#eventemitter">EventEmitter</a>&lt;Events = <a href="#sharedkitevents">SharedKitEvents</a>&gt;</code> | Event emitter the provider should publish its events to. |
+| `ssr` | `boolean` | `true` when the provider is constructed during server-side rendering — factories may skip browser-only setup. |
+
+#### ProviderInput
+
+Either a ready-made DeFi/onramp provider instance or a factory that produces one — the value accepted by [`AppKitConfig`](#appkitconfig)'s `providers` and [`registerProvider`](#registerprovider).
+
+```ts
+type ProviderInput = T | ProviderFactory<T>;
+```
+
+#### RegisterProviderOptions
+
+Provider instance or factory accepted by [`registerProvider`](#registerprovider) — same shape used in [`AppKitConfig`](#appkitconfig)'s `providers`. AppKit dispatches it to the right manager based on `provider.type` (`'swap'`, `'staking'`, `'onramp'`, `'crypto-onramp'`).
+
+```ts
+type RegisterProviderOptions = ProviderInput;
+```
+
+### Jettons
+
+#### CreateTransferJettonTransactionParameters
+
+Parameters accepted by [`createTransferJettonTransaction`](#createtransferjettontransaction) and [`transferJetton`](#transferjetton).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `jettonAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address being transferred. |
+| `recipientAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Recipient who should receive the jettons. |
+| `amount`\* | `string` | Amount in jetton units as a human-readable decimal string (e.g., `"1.5"`). |
+| `jettonDecimals`\* | `number` | Decimals declared by the jetton master; used to convert `amount` into raw smallest units. |
+| `comment` | `string` | Optional human-readable comment attached to the transfer. |
+
+#### CreateTransferJettonTransactionReturnType
+
+Return type of [`createTransferJettonTransaction`](#createtransferjettontransaction).
+
+```ts
+type CreateTransferJettonTransactionReturnType = TransactionRequest;
+```
+
+#### GetJettonBalanceOptions
+
+Options for [`getJettonBalance`](#getjettonbalance).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `jettonAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address (the token, not the user's wallet for it). |
+| `ownerAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Owner of the jetton wallet — typically the connected user's address. |
+| `jettonDecimals`\* | `number` | Decimals declared by the jetton master; used to format the raw balance into a human-readable string. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+
+#### GetJettonBalanceReturnType
+
+Return type of [`getJettonBalance`](#getjettonbalance).
+
+```ts
+type GetJettonBalanceReturnType = TokenAmount;
+```
+
+#### GetJettonInfoOptions
+
+Options for [`getJettonInfo`](#getjettoninfo).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address whose metadata is being fetched. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+
+#### GetJettonInfoReturnType
+
+Return type of [`getJettonInfo`](#getjettoninfo) — `null` when the indexer has no record for that master address.
+
+```ts
+type GetJettonInfoReturnType = JettonInfo | null;
+```
+
+#### GetJettonWalletAddressOptions
+
+Options for [`getJettonWalletAddress`](#getjettonwalletaddress).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `jettonAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Jetton master contract address. |
+| `ownerAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Owner whose jetton wallet should be derived. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+
+#### GetJettonWalletAddressReturnType
+
+Return type of [`getJettonWalletAddress`](#getjettonwalletaddress).
+
+```ts
+type GetJettonWalletAddressReturnType = UserFriendlyAddress;
+```
+
+#### GetJettonsByAddressOptions
+
+Options for [`getJettonsByAddress`](#getjettonsbyaddress).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+| `limit` | `number` | Maximum number of jettons to return. |
+| `offset` | `number` | Number of jettons to skip before returning results — used for pagination. |
+
+#### GetJettonsByAddressReturnType
+
+Return type of [`getJettonsByAddress`](#getjettonsbyaddress).
+
+```ts
+type GetJettonsByAddressReturnType = JettonsResponse;
+```
+
+#### GetJettonsOptions
+
+Options for [`getJettons`](#getjettons).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="#network">Network</a></code> | Network to read jettons from. Defaults to the selected wallet's network. |
+| `limit` | `number` | Maximum number of jettons to return. |
+| `offset` | `number` | Number of jettons to skip before returning results — used for pagination. |
+
+#### GetJettonsReturnType
+
+Return type of [`getJettons`](#getjettons) — `null` when no wallet is currently selected.
+
+```ts
+type GetJettonsReturnType = JettonsResponse | null;
+```
+
+#### Jetton
+
+Fungible TEP-74 token held in the user's TON wallet — carries the master contract address, the user's jetton-wallet address, current balance, and token metadata.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The jetton master contract address (the token itself). |
+| `walletAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The owner's jetton-wallet contract address — the per-owner contract that actually holds this balance. |
+| `balance`\* | <code><a href="#tokenamount">TokenAmount</a></code> | The current jetton balance |
+| `info`\* | <code><a href="#tokeninfo">TokenInfo</a></code> | Information about the token |
+| `decimalsNumber` | `number` | The number of decimal places used by the token |
+| `isVerified`\* | `boolean` | Indicates if the jetton is verified |
+| `prices`\* | `JettonPrice[]` | Current prices of the jetton in various currencies |
+| `extra` | `{         [key: string]: unknown;     }` | Additional arbitrary data related to the jetton |
+
+#### JettonInfo
+
+Token metadata for a jetton master — name, symbol, decimals, image, and verification status as reported by the indexer.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | `string` | Jetton master contract address. |
+| `name`\* | `string` | Display name of the jetton (e.g., `"Tether USD"`). |
+| `symbol`\* | `string` | Ticker symbol (e.g., `"USDT"`). |
+| `description`\* | `string` | Free-form description set by the issuer. |
+| `decimals` | `number` | Number of decimal places used to format raw amounts (e.g., `6` for USDT). |
+| `totalSupply` | `string` | Total supply in raw smallest units. |
+| `image` | `string` | URL of the jetton's image. |
+| `image_data` | `string` | Inline image data (Base64) when no `image` URL is published. |
+| `uri` | `string` | Off-chain metadata URI (TEP-64). |
+| `verification` | <code><a href="#jettonverification">JettonVerification</a></code> | Verification status reported by the indexer. |
+| `metadata` | `Record<string, unknown>` | Additional indexer-supplied metadata that doesn't fit the canonical fields. |
+
+#### JettonUpdate
+
+Update payload delivered to [`watchJettons`](#watchjettons) / [`watchJettonsByAddress`](#watchjettonsbyaddress) subscribers when the watched owner's jetton balance changes.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `type`\* | `'jettons'` | The update type field |
+| `masterAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The master jetton contract address |
+| `walletAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The jetton wallet contract address |
+| `ownerAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The owner of the jetton wallet |
+| `rawBalance`\* | <code><a href="#tokenamount">TokenAmount</a></code> | Balance in raw smallest units (e.g. nano) |
+| `decimals` | `number` | Decimals mapped from metadata if available |
+| `balance` | `string` | Human readable formatted balance if decimals are known |
+| `status`\* | <code><a href="#streamingupdatestatus">StreamingUpdateStatus</a></code> | The finality of the update |
+
+#### JettonVerification
+
+Verification metadata reported by the indexer for a [`JettonInfo`](#jettoninfo) — `verified` flag plus optional verifier source.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `verified`\* | `boolean` | `true` when the indexer has verified this jetton against an allow-list. |
+| `source` | `'toncenter' \| 'community' \| 'manual'` | Origin of the verification claim. |
+| `warnings` | `string[]` | Free-form warnings the UI should surface (e.g., scam indicators). |
+
+#### JettonsResponse
+
+Response payload of [`getJettons`](#getjettons) / [`getJettonsByAddress`](#getjettonsbyaddress) — the list of [`Jetton`](#jetton)s plus the address book that resolves raw addresses inside it.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `addressBook`\* | <code><a href="#addressbook">AddressBook</a></code> | Address book mapping |
+| `jettons`\* | <code><a href="#jetton">Jetton</a>[]</code> | List of Jettons |
+
+#### TransferJettonParameters
+
+Parameters accepted by [`transferJetton`](#transferjetton) — same shape as [`CreateTransferJettonTransactionParameters`](#createtransferjettontransactionparameters).
+
+```ts
+type TransferJettonParameters = CreateTransferJettonTransactionParameters;
+```
+
+#### TransferJettonReturnType
+
+Return type of [`transferJetton`](#transferjetton).
+
+```ts
+type TransferJettonReturnType = SendTransactionResponse;
+```
+
+#### WatchJettonsByAddressOptions
+
+Options for [`watchJettonsByAddress`](#watchjettonsbyaddress).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `onChange`\* | <code>(update: <a href="#jettonupdate">JettonUpdate</a>) =&gt; void</code> | Callback fired on every jetton-balance update from the streaming provider. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+
+#### WatchJettonsByAddressReturnType
+
+Return type of [`watchJettonsByAddress`](#watchjettonsbyaddress) — call to stop receiving updates.
+
+```ts
+type WatchJettonsByAddressReturnType = () => void;
+```
+
+#### WatchJettonsOptions
+
+Options for [`watchJettons`](#watchjettons).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | <code>(update: <a href="#jettonupdate">JettonUpdate</a>) =&gt; void</code> | Callback fired on every jetton-balance update from the streaming provider. |
+| `network` | <code><a href="#network">Network</a></code> | Network to watch on. Defaults to the selected wallet's network. |
+
+#### WatchJettonsReturnType
+
+Return type of [`watchJettons`](#watchjettons) — call to stop receiving updates.
+
+```ts
+type WatchJettonsReturnType = () => void;
+```
+
+### NFTs
+
+#### CreateTransferNftTransactionParameters
+
+Parameters accepted by [`createTransferNftTransaction`](#createtransfernfttransaction) and [`transferNft`](#transfernft).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `nftAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | NFT contract address to transfer. |
+| `recipientAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | New owner address. |
+| `amount` | `string` | Amount of TON to attach to the transfer for gas; defaults to AppKit's NFT gas-fee constant when omitted. |
+| `comment` | `string` | Optional human-readable comment attached to the transfer. |
+
+#### CreateTransferNftTransactionReturnType
+
+Return type of [`createTransferNftTransaction`](#createtransfernfttransaction).
+
+```ts
+type CreateTransferNftTransactionReturnType = TransactionRequest;
+```
+
+#### GetNftOptions
+
+Options for [`getNft`](#getnft).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | NFT contract address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+
+#### GetNftReturnType
+
+Return type of [`getNft`](#getnft) — `null` when the indexer has no record for that address.
+
+```ts
+type GetNftReturnType = NFT | null;
+```
+
+#### GetNftsByAddressOptions
+
+Options for [`getNftsByAddress`](#getnftsbyaddress).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Owner address — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+| `limit` | `number` | Maximum number of NFTs to return. |
+| `offset` | `number` | Number of NFTs to skip before returning results — used for pagination. |
+
+#### GetNftsByAddressReturnType
+
+Return type of [`getNftsByAddress`](#getnftsbyaddress).
+
+```ts
+type GetNftsByAddressReturnType = NFTsResponse;
+```
+
+#### GetNftsOptions
+
+Options for [`getNfts`](#getnfts).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="#network">Network</a></code> | Network to read NFTs from. Defaults to the selected wallet's network. |
+| `limit` | `number` | Maximum number of NFTs to return. |
+| `offset` | `number` | Number of NFTs to skip before returning results — used for pagination. |
+
+#### GetNftsReturnType
+
+Return type of [`getNfts`](#getnfts) — `null` when no wallet is currently selected.
+
+```ts
+type GetNftsReturnType = NFTsResponse | null;
+```
+
+#### NFT
+
+Non-fungible TEP-62 token held in the user's TON wallet — carries the contract address, optional collection link, owner, sale state, and on-chain metadata.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Contract address of the NFT item |
+| `index` | `string` | Index of the item within its collection |
+| `info` | <code><a href="#tokeninfo">TokenInfo</a></code> | Display information about the NFT (name, description, images) |
+| `attributes` | <code><a href="#nftattribute">NFTAttribute</a>[]</code> | Custom attributes/traits of the NFT (e.g., rarity, properties) |
+| `collection` | <code><a href="#nftcollection">NFTCollection</a></code> | Information about the collection this item belongs to |
+| `auctionContractAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the auction contract, if the NFT is being auctioned |
+| `codeHash` | <code><a href="#hex">Hex</a></code> | Hash of the NFT smart contract code |
+| `dataHash` | <code><a href="#hex">Hex</a></code> | Hash of the NFT's on-chain data |
+| `isInited` | `boolean` | Whether the NFT contract has been initialized |
+| `isSoulbound` | `boolean` | Whether the NFT is soulbound (non-transferable) |
+| `isOnSale` | `boolean` | Whether the NFT is currently listed for sale |
+| `ownerAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Current owner address of the NFT |
+| `realOwnerAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Real owner address when NFT is on sale (sale contract becomes temporary owner) |
+| `saleContractAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the sale contract, if the NFT is listed for sale |
+| `extra` | `{         [key: string]: unknown;     }` | Additional arbitrary data related to the NFT. |
+
+#### NFTAttribute
+
+Single trait of an [`NFT`](#nft) — `traitType` names the category (e.g., `"Background"`), `value` carries the trait's value (e.g., `"Blue"`).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `traitType` | `string` | Category or type of the trait (e.g., "Background", "Eyes") |
+| `displayType` | `string` | Indexer-supplied hint for how the attribute should be rendered. Optional and indexer-specific. |
+| `value` | `string` | Value of the attribute (e.g., "Blue", "Rare") |
+
+#### NFTCollection
+
+NFT collection (TEP-62) — surfaced as [`NFT`](#nft)'s `collection` and carries the collection's name, image, owner and minting cursor.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The blockchain address of the NFT collection contract |
+| `name` | `string` | The name of the NFT collection |
+| `image` | `TokenImage` | The image representing the NFT collection |
+| `description` | `string` | A brief description of the NFT collection |
+| `nextItemIndex` | `string` | The index value for the next item to be minted in the collection |
+| `codeHash` | <code><a href="#hex">Hex</a></code> | The hash of the collection's smart contract code |
+| `dataHash` | <code><a href="#hex">Hex</a></code> | The hash of the collection's data in the blockchain |
+| `ownerAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The blockchain address of the collection owner |
+| `extra` | `{         [key: string]: unknown;     }` | Additional arbitrary data related to the NFT collection |
+
+#### NFTsResponse
+
+Response payload of [`getNfts`](#getnfts) / [`getNftsByAddress`](#getnftsbyaddress) — the list of [`NFT`](#nft)s plus an address book that resolves raw addresses inside it.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `addressBook` | <code><a href="#addressbook">AddressBook</a></code> | Address book entries related to the NFTs |
+| `nfts`\* | <code><a href="#nft">NFT</a>[]</code> | List of NFTs |
+
+#### TransferNftParameters
+
+Parameters accepted by [`transferNft`](#transfernft) — same shape as [`CreateTransferNftTransactionParameters`](#createtransfernfttransactionparameters).
+
+```ts
+type TransferNftParameters = CreateTransferNftTransactionParameters;
+```
+
+#### TransferNftReturnType
+
+Return type of [`transferNft`](#transfernft).
+
+```ts
+type TransferNftReturnType = SendTransactionResponse;
+```
+
+### Networks
+
+#### GetBlockNumberOptions
+
+Options for [`getBlockNumber`](#getblocknumber).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="#network">Network</a></code> | Network to query. Defaults to mainnet when omitted. |
+
+#### GetBlockNumberReturnType
+
+Return type of [`getBlockNumber`](#getblocknumber).
+
+```ts
+type GetBlockNumberReturnType = number;
+```
+
+#### GetDefaultNetworkReturnType
+
+Return type of [`getDefaultNetwork`](#getdefaultnetwork) — `undefined` when no default has been set (apps may operate on any registered network).
+
+```ts
+type GetDefaultNetworkReturnType = Network | undefined;
+```
+
+#### GetNetworkReturnType
+
+Return type of [`getNetwork`](#getnetwork) — `null` when no wallet is currently selected.
+
+```ts
+type GetNetworkReturnType = Network | null;
+```
+
+#### GetNetworksReturnType
+
+Return type of [`getNetworks`](#getnetworks).
+
+```ts
+type GetNetworksReturnType = Network[];
+```
+
+#### HasStreamingProviderReturnType
+
+Return type of [`hasStreamingProvider`](#hasstreamingprovider).
+
+```ts
+type HasStreamingProviderReturnType = boolean;
+```
+
+#### Network
+
+TON blockchain network identifier.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `chainId`\* | `string` | Chain ID of the network (e.g., "-239" for mainnet, "-3" for testnet) |
+
+#### NetworkAdapters
+
+Multi-network configuration keyed by chain ID
+Example: \{ [Network.mainnet().chainId]: \{ apiClient: \{...\} \}, [Network.testnet().chainId]: \{ apiClient: \{...\} \} \}
+
+```ts
+type NetworkAdapters = {
+    [key: string]: NetworkConfig | undefined;
+};
+```
+
+#### NetworkConfig
+
+Network configuration for a specific chain
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `apiClient` | <code><a href="#apiclientconfig">ApiClientConfig</a> \| <a href="#apiclient">ApiClient</a></code> | API client configuration or instance |
+
+#### SetDefaultNetworkParameters
+
+Parameters accepted by [`setDefaultNetwork`](#setdefaultnetwork).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network`\* | <code><a href="#network">Network</a> \| undefined</code> | Network to enforce on new wallet connections; pass `undefined` to allow any registered network. |
+
+#### SetDefaultNetworkReturnType
+
+Return type of [`setDefaultNetwork`](#setdefaultnetwork).
+
+```ts
+type SetDefaultNetworkReturnType = void;
+```
+
+#### TonWalletKitOptions
+
+Walletkit-side options shape consumed by [`KitNetworkManager`](#kitnetworkmanager)'s constructor — chiefly the `networks` map keyed by chain ID. [`AppKit`](#appkit) constructs the manager for you, so apps rarely instantiate this directly.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `walletManifest` | `WalletInfo` | TonConnect wallet manifest published by the dApp; required for the wallet to recognize the integration. |
+| `deviceInfo` | `DeviceInfo` | Device fingerprint forwarded with TonConnect requests so wallets can recognize the host. |
+| `sessionManager` | `TONConnectSessionManager` | Custom session manager implementation. If not provided, TONConnectStoredSessionManager will be used. |
+| `networks` | <code><a href="#networkadapters">NetworkAdapters</a></code> | Network configuration |
+| `bridge` | `BridgeConfig` | Bridge settings |
+| `storage` | `StorageConfig \| StorageAdapter` | Storage settings |
+| `validation` | `{         strictMode?: boolean;         allowUnknownWalletVersions?: boolean;     }` | Validation settings |
+| `eventProcessor` | `EventProcessorConfig` | Event processor settings |
+| `analytics` | `AnalyticsManagerOptions & {         enabled?: boolean;     }` | Analytics manager options merged with an `enabled` toggle; off by default. |
+| `dev` | `{         disableNetworkSend?: boolean;         disableManifestDomainCheck?: boolean;     }` | Diagnostic toggles useful during local development; should not be set in production builds. |
+
+#### WatchDefaultNetworkParameters
+
+Parameters accepted by [`watchDefaultNetwork`](#watchdefaultnetwork).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | <code>(network: <a href="#network">Network</a> \| undefined) =&gt; void</code> | Callback fired whenever [`setDefaultNetwork`](#setdefaultnetwork) updates the default — receives the new value (or `undefined` when cleared). |
+
+#### WatchDefaultNetworkReturnType
+
+Return type of [`watchDefaultNetwork`](#watchdefaultnetwork) — call to stop receiving updates.
+
+```ts
+type WatchDefaultNetworkReturnType = () => void;
+```
+
+#### WatchNetworksParameters
+
+Parameters accepted by [`watchNetworks`](#watchnetworks).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | <code>(networks: <a href="#network">Network</a>[]) =&gt; void</code> | Callback fired whenever the configured-networks list changes — receives the latest snapshot. |
+
+#### WatchNetworksReturnType
+
+Return type of [`watchNetworks`](#watchnetworks) — call to stop receiving updates.
+
+```ts
+type WatchNetworksReturnType = () => void;
+```
+
+### Primitives
+
+#### Base64String
+
+Base64-encoded byte string — used for transaction payloads, BoCs, signatures, and other opaque binary blobs that travel through TonConnect and the indexer APIs.
+
+```ts
+type Base64String = string & {
+    readonly [base64StringBrand]: never;
+};
+```
+
+#### ExtraCurrencies
+
+Map of extra-currency ids to raw amounts attached to a transaction message — TON's mechanism for transferring non-jetton native tokens (e.g., wrapped or testnet currencies). Keys are the extra-currency ids defined by the masterchain configuration.
+
+```ts
+type ExtraCurrencies = {
+    [key: string]: string;
+};
+```
+
+#### Hex
+
+`0x`-prefixed hexadecimal string used for public keys and other hashes.
+
+```ts
+type Hex = `0x${string}` & {
+    readonly [hashBrand]: never;
+};
+```
+
+#### TokenAmount
+
+Decimal string carrying a token amount; preserves precision and avoids floating-point rounding (e.g., `"1.5"` TON, or raw nano units depending on the API).
+
+```ts
+type TokenAmount = string;
+```
+
+#### UserFriendlyAddress
+
+User-friendly TON wallet address as a base64url string (e.g., `"EQDtFp...4q2"`).
+
+```ts
+type UserFriendlyAddress = string;
+```
+
+### Signing
+
+#### SignBinaryParameters
+
+Parameters accepted by [`signBinary`](#signbinary).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `bytes`\* | <code><a href="#base64string">Base64String</a></code> | Binary blob the user is asked to sign, encoded as Base64. |
+| `network` | <code><a href="#network">Network</a></code> | Network to issue the sign request against. Defaults to AppKit's configured default network; when none is set, the wallet falls back to its current network. |
+
+#### SignBinaryReturnType
+
+Return type of [`signBinary`](#signbinary).
+
+```ts
+type SignBinaryReturnType = SignDataResponse;
+```
+
+#### SignCellParameters
+
+Parameters accepted by [`signCell`](#signcell).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `cell`\* | <code><a href="#base64string">Base64String</a></code> | TON cell content encoded as Base64 (BoC). |
+| `schema`\* | `string` | TL-B-style schema describing the cell layout so the wallet can render the payload to the user. |
+| `network` | <code><a href="#network">Network</a></code> | Network to issue the sign request against. Defaults to AppKit's configured default network; when none is set, the wallet falls back to its current network. |
+
+#### SignCellReturnType
+
+Return type of [`signCell`](#signcell).
+
+```ts
+type SignCellReturnType = SignDataResponse;
+```
+
+#### SignData
+
+Payload the user is asked to sign — discriminated union over `'text'`, `'binary'`, and `'cell'`; nested under [`SignDataRequest`](#signdatarequest)'s `data`.
+
+```ts
+type SignData = | { type: 'text'; value: SignDataText }
+    | { type: 'binary'; value: SignDataBinary }
+    | { type: 'cell'; value: SignDataCell };
+```
+
+#### SignDataBinary
+
+Binary variant of [`SignData`](#signdata) — opaque byte content the user is asked to sign.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `content`\* | <code><a href="#base64string">Base64String</a></code> | Raw binary content encoded as Base64. |
+
+#### SignDataCell
+
+TON cell variant of [`SignData`](#signdata) — Base64-encoded cell payload paired with the schema needed to parse it.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `schema`\* | `string` | TL-B-style schema describing the cell layout so the wallet can render the payload to the user. |
+| `content`\* | <code><a href="#base64string">Base64String</a></code> | Cell content encoded as Base64. |
+
+#### SignDataRequest
+
+Sign-data payload sent to [`WalletInterface`](#walletinterface)'s `signData` — discriminated by `data.type` (`'text'`, `'binary'`, or `'cell'`).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="#network">Network</a></code> | Network to issue the sign request against; defaults to the wallet's current network. |
+| `from` | `string` | Sender address in raw format; usually omitted, the wallet fills it in. |
+| `data`\* | <code><a href="#signdata">SignData</a></code> | Payload the user is asked to sign. |
+
+#### SignDataResponse
+
+Wallet response to a [`SignDataRequest`](#signdatarequest) — carries the signature plus the canonicalized address, timestamp, and domain the wallet committed to.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `signature`\* | `string` | Base64-encoded signature. |
+| `address`\* | `string` | Wallet address that signed, in user-friendly format. |
+| `timestamp`\* | `number` | Unix timestamp the wallet stamped onto the signature. |
+| `domain`\* | `string` | dApp domain the wallet bound the signature to. |
+| `payload`\* | <code><a href="#signdatarequest">SignDataRequest</a></code> | Original payload that was signed, echoed back for binding. |
+
+#### SignDataText
+
+Plain-text variant of [`SignData`](#signdata) — UTF-8 string the user is asked to sign.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `content`\* | `string` | UTF-8 text the user signs. |
+
+#### SignTextParameters
+
+Parameters accepted by [`signText`](#signtext).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `text`\* | `string` | UTF-8 text the user is asked to sign. |
+| `network` | <code><a href="#network">Network</a></code> | Network to issue the sign request against. Defaults to AppKit's configured default network; when none is set, the wallet falls back to its current network. |
+
+#### SignTextReturnType
+
+Return type of [`signText`](#signtext).
+
+```ts
+type SignTextReturnType = SignDataResponse;
+```
+
+### Staking
+
+#### BuildStakeTransactionOptions
+
+Options for [`buildStakeTransaction`](#buildstaketransaction) — extends [`StakeParams`](#stakeparams) with an optional provider override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `quote`\* | <code><a href="#stakingquote">StakingQuote</a></code> | The staking quote based on which the transaction is built |
+| `userAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the user performing the staking |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `providerId` | `string` | Provider to stake/unstake through; defaults to the registered default staking provider. |
+
+#### BuildStakeTransactionReturnType
+
+Return type of [`buildStakeTransaction`](#buildstaketransaction).
+
+```ts
+type BuildStakeTransactionReturnType = Promise<TransactionRequest>;
+```
+
+#### GetStakedBalanceOptions
+
+Options for [`getStakedBalance`](#getstakedbalance).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `userAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Owner whose staked balance should be read. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+| `providerId` | `string` | Provider to query; defaults to the registered default staking provider. |
+
+#### GetStakedBalanceReturnType
+
+Return type of [`getStakedBalance`](#getstakedbalance).
+
+```ts
+type GetStakedBalanceReturnType = Promise<StakingBalance>;
+```
+
+#### GetStakingManagerReturnType
+
+Return type of [`getStakingManager`](#getstakingmanager).
+
+```ts
+type GetStakingManagerReturnType = StakingManager;
+```
+
+#### GetStakingProviderInfoOptions
+
+Options for [`getStakingProviderInfo`](#getstakingproviderinfo).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+| `providerId` | `string` | Provider to query; defaults to the registered default staking provider. |
+
+#### GetStakingProviderInfoReturnType
+
+Return type of [`getStakingProviderInfo`](#getstakingproviderinfo).
+
+```ts
+type GetStakingProviderInfoReturnType = Promise<StakingProviderInfo>;
+```
+
+#### GetStakingProviderMetadataOptions
+
+Options for [`getStakingProviderMetadata`](#getstakingprovidermetadata).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+| `providerId` | `string` | Provider to query; defaults to the registered default staking provider. |
+
+#### GetStakingProviderMetadataReturnType
+
+Return type of [`getStakingProviderMetadata`](#getstakingprovidermetadata).
+
+```ts
+type GetStakingProviderMetadataReturnType = StakingProviderMetadata;
+```
+
+#### GetStakingProviderOptions
+
+Options for [`getStakingProvider`](#getstakingprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Provider ID to look up; when omitted, returns the registered default staking provider. |
+
+#### GetStakingProviderReturnType
+
+Return type of [`getStakingProvider`](#getstakingprovider).
+
+```ts
+type GetStakingProviderReturnType = StakingProviderInterface;
+```
+
+#### GetStakingProvidersReturnType
+
+Return type of [`getStakingProviders`](#getstakingproviders).
+
+```ts
+type GetStakingProvidersReturnType = StakingProviderInterface[];
+```
+
+#### GetStakingQuoteOptions
+
+Options for [`getStakingQuote`](#getstakingquote) — extends [`StakingQuoteParams`](#stakingquoteparams) with an optional provider override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `direction`\* | <code><a href="#stakingquotedirection">StakingQuoteDirection</a></code> | Direction of the quote (stake or unstake) |
+| `amount`\* | `string` | Amount of tokens to stake or unstake |
+| `userAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the user |
+| `network` | <code><a href="#network">Network</a></code> | Network on which the staking will be executed |
+| `unstakeMode` | <code><a href="#unstakemodes">UnstakeModes</a></code> | Requested mode of unstaking |
+| `isReversed` | `boolean` | If true, for unstake requests the amount is specified in the staking coin (e.g. TON) instead of the Liquid Staking Token (e.g. tsTON). |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `providerId` | `string` | Provider to quote against; defaults to the registered default staking provider. |
+
+#### GetStakingQuoteReturnType
+
+Return type of [`getStakingQuote`](#getstakingquote).
+
+```ts
+type GetStakingQuoteReturnType = Promise<StakingQuote>;
+```
+
+#### SetDefaultStakingProviderParameters
+
+Parameters accepted by [`setDefaultStakingProvider`](#setdefaultstakingprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `providerId`\* | `string` | ID of the provider to make default — must already be registered. |
+
+#### SetDefaultStakingProviderReturnType
+
+Return type of [`setDefaultStakingProvider`](#setdefaultstakingprovider).
+
+```ts
+type SetDefaultStakingProviderReturnType = void;
+```
+
+#### StakeParams
+
+Parameters for staking TON
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `quote`\* | <code><a href="#stakingquote">StakingQuote</a></code> | The staking quote based on which the transaction is built |
+| `userAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the user performing the staking |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+
+#### StakingAPI
+
+Staking API interface exposed by StakingManager
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `getQuote`\* | <code>(params: <a href="#stakingquoteparams">StakingQuoteParams</a>, providerId?: string) =&gt; Promise&lt;<a href="#stakingquote">StakingQuote</a>&gt;</code> | Get a quote for staking or unstaking |
+| `buildStakeTransaction`\* | <code>(params: <a href="#stakeparams">StakeParams</a>, providerId?: string) =&gt; Promise&lt;<a href="#transactionrequest">TransactionRequest</a>&gt;</code> | Build a transaction for staking |
+| `getStakedBalance`\* | <code>(userAddress: <a href="#userfriendlyaddress">UserFriendlyAddress</a>, network?: <a href="#network">Network</a>, providerId?: string) =&gt; Promise&lt;<a href="#stakingbalance">StakingBalance</a>&gt;</code> | Get user's staked balance |
+| `getStakingProviderInfo`\* | <code>(network?: <a href="#network">Network</a>, providerId?: string) =&gt; Promise&lt;<a href="#stakingproviderinfo">StakingProviderInfo</a>&gt;</code> | Get staking provider information |
+| `getStakingProviderMetadata`\* | <code>(network?: <a href="#network">Network</a>, providerId?: string) =&gt; <a href="#stakingprovidermetadata">StakingProviderMetadata</a></code> | Get static metadata for a staking provider |
+| `createFactoryContext`\* | <code>() =&gt; <a href="#providerfactorycontext">ProviderFactoryContext</a></code> | Build a fresh [`ProviderFactoryContext`](#providerfactorycontext) the manager hands to provider factories at registration time. |
+| `registerProvider`\* | <code>(provider: <a href="#providerinput">ProviderInput</a>&lt;StakingProviderInterface&gt;) =&gt; void</code> | Register a new provider. If a provider with the same id is already registered, it is replaced. |
+| `removeProvider`\* | `(provider: StakingProviderInterface) => void` | Remove a previously registered provider. No-op if the provider was not registered. |
+| `setDefaultProvider`\* | `(providerId: string) => void` | Set the default provider |
+| `getProvider`\* | `(providerId?: string) => StakingProviderInterface` | Get a registered provider |
+| `getProviders`\* | `() => Array<StakingProviderInterface>` | Get all registered providers. The returned array keeps a stable reference until the provider list changes. |
+| `hasProvider`\* | `(providerId: string) => boolean` | Check if a provider is registered |
+
+#### StakingBalance
+
+Staking balance information for a user
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `rawStakedBalance`\* | <code><a href="#tokenamount">TokenAmount</a></code> | Amount currently staked |
+| `stakedBalance`\* | `string` | Amount currently staked |
+| `rawInstantUnstakeAvailable`\* | <code><a href="#tokenamount">TokenAmount</a></code> | Amount available for instant unstake |
+| `instantUnstakeAvailable`\* | `string` | Amount available for instant unstake |
+| `providerId`\* | `string` | Identifier of the staking provider |
+
+#### StakingProviderInfo
+
+Dynamic staking information for a provider
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `apy`\* | `number` | Annual Percentage Yield in basis points (100 = 1%) |
+| `rawInstantUnstakeAvailable` | <code><a href="#tokenamount">TokenAmount</a></code> | Amount available for instant unstake |
+| `instantUnstakeAvailable` | `string` | Amount available for instant unstake |
+| `exchangeRate` | `string` | Exchange rate between stakeToken and receiveToken (e.g. 1 TON = 0.95 tsTON). Undefined when there is no receiveToken (direct/custodial staking). |
+
+#### StakingProviderMetadata
+
+Static metadata for a staking provider
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name`\* | `string` | Human-readable provider name (e.g. "Tonstakers") |
+| `supportedUnstakeModes`\* | <code><a href="#unstakemodes">UnstakeModes</a>[]</code> | Supported unstake modes for this provider |
+| `supportsReversedQuote`\* | `boolean` | Whether provider supports reversed quote format (e.g., passing TON instead of tsTON for unstake) |
+| `stakeToken`\* | <code><a href="#stakingtokeninfo">StakingTokenInfo</a></code> | Token that the user sends when staking (e.g. TON) |
+| `receiveToken` | <code><a href="#stakingtokeninfo">StakingTokenInfo</a></code> | Token that the user receives when staking (e.g. tsTON for liquid staking). Absent for direct/custodial staking. |
+| `contractAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Provider contract address (optional — custodial providers may not have one) |
+
+#### StakingQuote
+
+Staking quote response with pricing information
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `direction`\* | <code><a href="#stakingquotedirection">StakingQuoteDirection</a></code> | Direction of the quote (stake or unstake) |
+| `rawAmountIn`\* | <code><a href="#tokenamount">TokenAmount</a></code> | Amount of tokens being provided |
+| `rawAmountOut`\* | <code><a href="#tokenamount">TokenAmount</a></code> | Estimated amount of tokens to be received |
+| `amountIn`\* | `string` | Formatted amount of tokens being provided |
+| `amountOut`\* | `string` | Formatted estimated amount of tokens to be received |
+| `network`\* | <code><a href="#network">Network</a></code> | Network on which the staking will be executed |
+| `providerId`\* | `string` | Identifier of the staking provider |
+| `unstakeMode` | <code><a href="#unstakemodes">UnstakeModes</a></code> | Mode of unstaking (if applicable) |
+| `metadata` | `unknown` | Provider-specific metadata for the quote |
+
+#### StakingQuoteDirection
+
+Direction of the staking quote
+
+```ts
+type StakingQuoteDirection = 'stake' | 'unstake';
+```
+
+#### StakingQuoteParams
+
+Parameters for getting a staking quote
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `direction`\* | <code><a href="#stakingquotedirection">StakingQuoteDirection</a></code> | Direction of the quote (stake or unstake) |
+| `amount`\* | `string` | Amount of tokens to stake or unstake |
+| `userAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the user |
+| `network` | <code><a href="#network">Network</a></code> | Network on which the staking will be executed |
+| `unstakeMode` | <code><a href="#unstakemodes">UnstakeModes</a></code> | Requested mode of unstaking |
+| `isReversed` | `boolean` | If true, for unstake requests the amount is specified in the staking coin (e.g. TON) instead of the Liquid Staking Token (e.g. tsTON). |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+
+#### StakingTokenInfo
+
+Display metadata for a staking-pool token — `ticker`, `decimals` and `address` (or `'ton'` for native TON); carried on [`StakingProviderMetadata`](#stakingprovidermetadata)'s `stakeToken` and `receiveToken` so the UI can render the pool's input/output assets.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `ticker`\* | `string` | Ticker symbol (e.g., `"TON"`, `"tsTON"`). |
+| `decimals`\* | `number` | Number of decimal places used to format raw amounts. |
+| `address`\* | `string` | `'ton'` for native TON, otherwise the token contract address in user-friendly format. |
+
+#### TonStakersProviderConfig
+
+Configuration accepted by [`createTonstakersProvider`](#createtonstakersprovider).
+
+_Empty type._
+
+#### UnstakeModes
+
+Mode of unstaking
+
+```ts
+type UnstakeModes = (typeof UnstakeMode)[keyof typeof UnstakeMode];
+```
+
+#### WatchStakingProvidersParameters
+
+Parameters accepted by [`watchStakingProviders`](#watchstakingproviders).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | `() => void` | Callback fired whenever a staking provider is registered or the default staking provider changes. |
+
+#### WatchStakingProvidersReturnType
+
+Return type of [`watchStakingProviders`](#watchstakingproviders) — call to stop receiving updates.
+
+```ts
+type WatchStakingProvidersReturnType = () => void;
+```
+
+### Swap
+
+#### BuildSwapTransactionOptions
+
+Options for [`buildSwapTransaction`](#buildswaptransaction) — same shape as [`SwapParams`](#swapparams).
+
+```ts
+type BuildSwapTransactionOptions = SwapParams<T>;
+```
+
+#### BuildSwapTransactionReturnType
+
+Return type of [`buildSwapTransaction`](#buildswaptransaction).
+
+```ts
+type BuildSwapTransactionReturnType = Promise<TransactionRequest>;
+```
+
+#### DeDustProviderOptions
+
+DeDust-specific options forwarded through `providerOptions` on [`SwapQuoteParams`](#swapquoteparams) / [`SwapParams`](#swapparams).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `protocols` | `string[]` | Protocols to use for routing Available: 'dedust', 'dedust_v3', 'dedust_v3_memepad', 'stonfi_v1', 'stonfi_v2', 'tonco', 'memeslab', 'tonfun' |
+| `excludeProtocols` | `string[]` | Protocols to exclude from routing |
+| `onlyVerifiedPools` | `boolean` | Only use verified pools |
+| `maxSplits` | `number` | Maximum number of route splits |
+| `maxLength` | `number` | Maximum route length (hops) |
+| `excludeVolatilePools` | `boolean` | Exclude volatile pools |
+| `referralAddress` | `string` | The address of the referrer |
+| `referralFeeBps` | `number` | Referral fee in basis points (max 100 = 1%) |
+
+#### DeDustQuoteMetadata
+
+Provider-specific metadata returned on a [`SwapQuote`](#swapquote)'s `metadata` from DeDust — carries the resolved route, fees and `swapData` payload that [`buildSwapTransaction`](#buildswaptransaction) needs.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `quoteResponse`\* | `DeDustQuoteResponse` | Raw quote response from API |
+| `slippageBps`\* | `number` | Slippage used for the quote in basis points |
+
+#### DeDustReferralOptions
+
+Optional referral metadata attached to DeDust swaps so the provider can attribute them.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `referralAddress` | `string` | The address of the referrer |
+| `referralFeeBps` | `number` | Referral fee in basis points (max 100 = 1%) |
+
+#### DeDustSwapProviderConfig
+
+Configuration accepted by [`createDeDustProvider`](#creatededustprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `providerId` | `string` | Custom provider ID (defaults to 'dedust') |
+| `defaultSlippageBps` | `number` | Default slippage tolerance in basis points (1 bp = 0.01%) |
+| `apiUrl` | `string` | API base URL |
+| `onlyVerifiedPools` | `boolean` | Only use verified pools |
+| `maxSplits` | `number` | Maximum number of route splits |
+| `maxLength` | `number` | Maximum route length (hops) |
+| `minPoolUsdTvl` | `string` | Minimum pool TVL in USD |
+| `metadata` | `SwapProviderMetadataOverride` | Custom metadata for the provider |
+| `referralAddress` | `string` | The address of the referrer |
+| `referralFeeBps` | `number` | Referral fee in basis points (max 100 = 1%) |
+
+#### GetSwapManagerReturnType
+
+Return type of [`getSwapManager`](#getswapmanager).
+
+```ts
+type GetSwapManagerReturnType = SwapManager;
+```
+
+#### GetSwapProviderOptions
+
+Options for [`getSwapProvider`](#getswapprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Provider ID to look up; when omitted, returns the registered default swap provider. |
+
+#### GetSwapProviderReturnType
+
+Return type of [`getSwapProvider`](#getswapprovider).
+
+```ts
+type GetSwapProviderReturnType = SwapProviderInterface;
+```
+
+#### GetSwapProvidersReturnType
+
+Return type of [`getSwapProviders`](#getswapproviders).
+
+```ts
+type GetSwapProvidersReturnType = SwapProviderInterface[];
+```
+
+#### GetSwapQuoteOptions
+
+Options for [`getSwapQuote`](#getswapquote) — extends [`SwapQuoteParams`](#swapquoteparams) with an optional provider override.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `amount`\* | `string` | Amount of tokens to swap (incoming or outgoing depending on isReverseSwap) |
+| `from`\* | <code><a href="#swaptoken">SwapToken</a></code> | Token to swap from |
+| `to`\* | <code><a href="#swaptoken">SwapToken</a></code> | Token to swap to |
+| `network`\* | <code><a href="#network">Network</a></code> | Network on which the swap will be executed |
+| `slippageBps` | `number` | Slippage tolerance in basis points (1 bp = 0.01%) |
+| `maxOutgoingMessages` | `number` | Maximum number of outgoing messages |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `isReverseSwap` | `boolean` | If true, amount is the amount to receive (buy). If false, amount is the amount to spend (sell). |
+| `providerId` | `string` | Provider to quote against; defaults to the registered default swap provider. |
+
+#### GetSwapQuoteReturnType
+
+Return type of [`getSwapQuote`](#getswapquote).
+
+```ts
+type GetSwapQuoteReturnType = Promise<SwapQuote>;
+```
+
+#### OmnistonProviderOptions
+
+Omniston-specific options forwarded through `providerOptions` on [`SwapQuoteParams`](#swapquoteparams) / [`SwapParams`](#swapparams).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `settlementMethods` | `SettlementMethodValue[]` | Settlement methods to use for the swap |
+| `referrerAddress` | `string` | The address of the referrer |
+| `referrerFeeBps` | `number` | Referrer fee in basis points (1 bp = 0.01%) |
+| `flexibleReferrerFee` | `boolean` | Whether a flexible referrer fee is allowed |
+
+#### OmnistonQuoteMetadata
+
+Provider-specific metadata returned on a [`SwapQuote`](#swapquote)'s `metadata` from Omniston — carries the resolved route and signed quote payload that [`buildSwapTransaction`](#buildswaptransaction) needs.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `omnistonQuote`\* | `Quote` | The actual Omniston quote object |
+
+#### OmnistonReferrerOptions
+
+Optional referrer metadata attached to Omniston swaps so the provider can attribute them.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `referrerAddress` | `string` | The address of the referrer |
+| `referrerFeeBps` | `number` | Referrer fee in basis points (1 bp = 0.01%) |
+| `flexibleReferrerFee` | `boolean` | Whether a flexible referrer fee is allowed |
+
+#### OmnistonSwapProviderConfig
+
+Configuration accepted by [`createOmnistonProvider`](#createomnistonprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `apiUrl` | `string` | Optional URL for the Omniston API |
+| `defaultSlippageBps` | `number` | Default slippage tolerance in basis points (1 bp = 0.01%) |
+| `quoteTimeoutMs` | `number` | Timeout for quote requests in milliseconds |
+| `providerId` | `string` | Identifier for the provider |
+| `metadata` | `SwapProviderMetadataOverride` | Custom metadata for the provider |
+| `referrerAddress` | `string` | The address of the referrer |
+| `referrerFeeBps` | `number` | Referrer fee in basis points (1 bp = 0.01%) |
+| `flexibleReferrerFee` | `boolean` | Whether a flexible referrer fee is allowed |
+
+#### SetDefaultSwapProviderParameters
+
+Parameters accepted by [`setDefaultSwapProvider`](#setdefaultswapprovider).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `providerId`\* | `string` | ID of the provider to make default — must already be registered. |
+
+#### SetDefaultSwapProviderReturnType
+
+Return type of [`setDefaultSwapProvider`](#setdefaultswapprovider).
+
+```ts
+type SetDefaultSwapProviderReturnType = void;
+```
+
+#### SwapAPI
+
+API surface exposed by [`SwapManager`](#swapmanager) — quote and build-transaction calls (plus the provider-management methods inherited from [`DefiManagerAPI`](#defimanagerapi)). Mostly relevant when authoring a swap manager replacement.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `getQuote`\* | <code>(params: <a href="#swapquoteparams">SwapQuoteParams</a>, providerId?: string) =&gt; Promise&lt;<a href="#swapquote">SwapQuote</a>&gt;</code> | Get a quote for swapping tokens |
+| `buildSwapTransaction`\* | <code>(params: <a href="#swapparams">SwapParams</a>) =&gt; Promise&lt;<a href="#transactionrequest">TransactionRequest</a>&gt;</code> | Build a transaction for a swap. Provider is taken from `params.quote.providerId`, or the manager default. |
+| `createFactoryContext`\* | <code>() =&gt; <a href="#providerfactorycontext">ProviderFactoryContext</a></code> | Build a fresh [`ProviderFactoryContext`](#providerfactorycontext) the manager hands to provider factories at registration time. |
+| `registerProvider`\* | <code>(provider: <a href="#providerinput">ProviderInput</a>&lt;SwapProviderInterface&lt;unknown, unknown&gt;&gt;) =&gt; void</code> | Register a new provider. If a provider with the same id is already registered, it is replaced. |
+| `removeProvider`\* | `(provider: SwapProviderInterface<unknown, unknown>) => void` | Remove a previously registered provider. No-op if the provider was not registered. |
+| `setDefaultProvider`\* | `(providerId: string) => void` | Set the default provider |
+| `getProvider`\* | `(providerId?: string) => SwapProviderInterface<unknown, unknown>` | Get a registered provider |
+| `getProviders`\* | `() => Array<SwapProviderInterface<unknown, unknown>>` | Get all registered providers. The returned array keeps a stable reference until the provider list changes. |
+| `hasProvider`\* | `(providerId: string) => boolean` | Check if a provider is registered |
+
+#### SwapParams
+
+Parameters consumed by [`buildSwapTransaction`](#buildswaptransaction) — the previously obtained [`SwapQuote`](#swapquote) plus optional provider-specific options (`TProviderOptions`).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `quote`\* | <code><a href="#swapquote">SwapQuote</a></code> | The swap quote based on which the transaction is built |
+| `userAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address of the user performing the swap |
+| `destinationAddress` | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Address to receive the swapped tokens (defaults to userAddress) |
+| `slippageBps` | `number` | Slippage tolerance in basis points (1 bp = 0.01%) |
+| `deadline` | `number` | Transaction deadline in unix timestamp |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+
+#### SwapQuote
+
+Quote returned by [`getSwapQuote`](#getswapquote) — source/target tokens, expected amounts, rate, slippage, fees and the provider-specific `metadata` that [`buildSwapTransaction`](#buildswaptransaction) needs to construct the transaction.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `fromToken`\* | <code><a href="#swaptoken">SwapToken</a></code> | Token being sold |
+| `toToken`\* | <code><a href="#swaptoken">SwapToken</a></code> | Token being bought |
+| `rawFromAmount`\* | <code><a href="#tokenamount">TokenAmount</a></code> | Amount of tokens to sell |
+| `rawToAmount`\* | <code><a href="#tokenamount">TokenAmount</a></code> | Amount of tokens to buy |
+| `fromAmount`\* | `string` | Amount of tokens to sell |
+| `toAmount`\* | `string` | Amount of tokens to buy |
+| `rawMinReceived`\* | <code><a href="#tokenamount">TokenAmount</a></code> | Minimum amount of tokens to receive (after slippage) |
+| `minReceived`\* | `string` | Minimum amount of tokens to receive (after slippage) |
+| `network`\* | <code><a href="#network">Network</a></code> | Network on which the swap will be executed |
+| `priceImpact` | `number` | Price impact of the swap in basis points (100 = 1%) |
+| `providerId`\* | `string` | Identifier of the swap provider |
+| `expiresAt` | `number` | Unix timestamp in seconds when the quote expires |
+| `metadata` | `unknown` | Provider-specific metadata for the quote |
+
+#### SwapQuoteParams
+
+Parameters consumed by [`getSwapQuote`](#getswapquote) — source/target tokens and an amount that is interpreted as either the spend side or the receive side (`isReverseSwap` flag), plus optional slippage and provider-specific options.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `amount`\* | `string` | Amount of tokens to swap (incoming or outgoing depending on isReverseSwap) |
+| `from`\* | <code><a href="#swaptoken">SwapToken</a></code> | Token to swap from |
+| `to`\* | <code><a href="#swaptoken">SwapToken</a></code> | Token to swap to |
+| `network`\* | <code><a href="#network">Network</a></code> | Network on which the swap will be executed |
+| `slippageBps` | `number` | Slippage tolerance in basis points (1 bp = 0.01%) |
+| `maxOutgoingMessages` | `number` | Maximum number of outgoing messages |
+| `providerOptions` | `TProviderOptions = unknown` | Provider-specific options |
+| `isReverseSwap` | `boolean` | If true, amount is the amount to receive (buy). If false, amount is the amount to spend (sell). |
+
+#### SwapToken
+
+Token descriptor passed to [`getSwapQuote`](#getswapquote) via [`SwapQuoteParams`](#swapquoteparams)'s `from` and `to` fields (and surfaced on the resulting [`SwapQuote`](#swapquote)) — address, decimals plus optional symbol/name/image used by swap-input UIs.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | `string` | Token contract address; `'ton'` is used for native TON on the TON chain. |
+| `decimals`\* | `number` | Number of decimal places used to format raw amounts. |
+| `name` | `string` | Display name (e.g., `"Tether USD"`). |
+| `symbol` | `string` | Ticker symbol (e.g., `"USDT"`). |
+| `image` | `string` | URL of the token's image. |
+| `chainId` | `string` | Chain id in CAIP-2 format when the token lives outside TON. |
+
+#### WatchSwapProvidersParameters
+
+Parameters accepted by [`watchSwapProviders`](#watchswapproviders).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | `() => void` | Callback fired whenever a swap provider is registered or the default swap provider changes. |
+
+#### WatchSwapProvidersReturnType
+
+Return type of [`watchSwapProviders`](#watchswapproviders) — call to stop receiving updates.
+
+```ts
+type WatchSwapProvidersReturnType = () => void;
+```
+
+### Transactions
+
+#### CreateTransferTonTransactionParameters
+
+Parameters accepted by [`createTransferTonTransaction`](#createtransfertontransaction) and [`transferTon`](#transferton).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `recipientAddress`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Recipient address. |
+| `amount`\* | `string` | Amount in TON as a human-readable decimal string (e.g., `"1.5"`); converted to nano-TON internally. |
+| `comment` | `string` | Human-readable text comment; converted to a Base64 payload when no `payload` is supplied. |
+| `payload` | <code><a href="#base64string">Base64String</a></code> | Raw Base64 message payload — wins over `comment` when both are set. |
+| `stateInit` | <code><a href="#base64string">Base64String</a></code> | Initial state for deploying a new contract, encoded as Base64. |
+
+#### CreateTransferTonTransactionReturnType
+
+Return type of [`createTransferTonTransaction`](#createtransfertontransaction).
+
+```ts
+type CreateTransferTonTransactionReturnType = TransactionRequest;
+```
+
+#### GetTransactionStatusParameters
+
+Parameters accepted by [`getTransactionStatus`](#gettransactionstatus) — must carry exactly one of `boc` or `normalizedHash`, plus an optional network override.
+
+```ts
+type GetTransactionStatusParameters = {
+    /** Network to check the transaction 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. */
+    network?: Network;
+} & (
+    | {
+          /** Base64-encoded BoC of the sent transaction (returned by {@link sendTransaction}). */
+          boc: string;
+          normalizedHash?: never;
+      }
+    | {
+          boc?: never;
+          /** Hex-encoded normalized hash of the external-in message (returned by {@link sendTransaction} as `normalizedHash`). */
+          normalizedHash: string;
+      }
+);
+```
+
+#### GetTransactionStatusReturnType
+
+Return type of [`getTransactionStatus`](#gettransactionstatus).
+
+```ts
+type GetTransactionStatusReturnType = TransactionStatusResponse;
+```
+
+#### SendTransactionParameters
+
+Parameters accepted by [`sendTransaction`](#sendtransaction) — same shape as [`TransactionRequest`](#transactionrequest).
+
+```ts
+type SendTransactionParameters = TransactionRequest;
+```
+
+#### SendTransactionResponse
+
+Wallet response carrying the BoC (bag of cells) of the external message that was signed and broadcast — used to track or hash the resulting transaction.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `boc`\* | <code><a href="#base64string">Base64String</a></code> | BoC of the sent transaction |
+| `normalizedBoc`\* | <code><a href="#base64string">Base64String</a></code> | Normalized BoC of the external-in message |
+| `normalizedHash`\* | <code><a href="#hex">Hex</a></code> | Hash of the normalized external-in message |
+
+#### SendTransactionReturnType
+
+Return type of [`sendTransaction`](#sendtransaction).
+
+```ts
+type SendTransactionReturnType = SendTransactionResponse;
+```
+
+#### Transaction
+
+Single transaction record carried inside [`TransactionsUpdate`](#transactionsupdate)'s `transactions` — account, lt/hash, in/out messages and emulation result.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `account`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Account of the transaction |
+| `accountStateBefore` | `AccountState` | The state of the account before the transaction was executed |
+| `accountStateAfter` | `AccountState` | The state of the account after the transaction has been applied |
+| `description` | `TransactionDescription` | The detailed breakdown of the transaction execution |
+| `hash`\* | <code><a href="#hex">Hex</a></code> | Hash of the transaction |
+| `logicalTime`\* | `LogicalTime` | The logical time of the transaction |
+| `now`\* | `number` | Unix timestamp of the transaction |
+| `mcBlockSeqno`\* | `number` | Masterchain block sequence number |
+| `traceExternalHash`\* | <code><a href="#hex">Hex</a></code> | External hash of the trace |
+| `traceId` | `string` | ID of the trace |
+| `previousTransactionHash` | `string` | The hash of the previous transaction |
+| `previousTransactionLogicalTime` | `LogicalTime` | The logical time of the previous transaction |
+| `origStatus` | `AccountStatus` | Original status of the transaction |
+| `endStatus` | `AccountStatus` | End status of the transaction |
+| `totalFees` | <code><a href="#tokenamount">TokenAmount</a></code> | Total fees of the transaction |
+| `totalFeesExtraCurrencies` | <code><a href="#extracurrencies">ExtraCurrencies</a></code> | Extra currencies in the total fees |
+| `blockRef` | `TransactionBlockRef` | The reference to the block in which the transaction was included |
+| `inMessage` | `TransactionMessage` | The incoming message associated with the transaction |
+| `outMessages`\* | `TransactionMessage[]` | The list of outgoing messages produced by the transaction |
+| `isEmulated`\* | `boolean` | Emulated state of the transaction |
+
+#### TransactionRequest
+
+Transaction payload passed to [`WalletInterface`](#walletinterface)'s `sendTransaction` — one or more messages, optional network override and `validUntil` deadline.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `messages`\* | <code><a href="#transactionrequestmessage">TransactionRequestMessage</a>[]</code> | Messages to include in the transaction. |
+| `network` | <code><a href="#network">Network</a></code> | Network to execute the transaction on. |
+| `validUntil` | `number` | Unix timestamp (seconds) after which the transaction becomes invalid. |
+| `fromAddress` | `string` | Sender wallet address — accepts either raw or user-friendly format. |
+
+#### TransactionRequestMessage
+
+Individual message inside a [`TransactionRequest`](#transactionrequest) — recipient, amount, optional payload and contract `stateInit`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | `string` | Recipient wallet address — accepts either raw or user-friendly format. |
+| `amount`\* | <code><a href="#tokenamount">TokenAmount</a></code> | Amount to transfer, in nano-TON (1 TON = 10⁹ nano-TON). |
+| `extraCurrency` | <code><a href="#extracurrencies">ExtraCurrencies</a></code> | Additional currencies to include in the transfer. |
+| `stateInit` | `string` | Initial state for deploying a new contract, encoded as Base64. |
+| `payload` | `string` | Message payload, encoded as Base64. |
+
+#### TransactionsUpdate
+
+Update payload delivered to [`watchTransactions`](#watchtransactions) / [`watchTransactionsByAddress`](#watchtransactionsbyaddress) subscribers when transactions land for the watched address.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `type`\* | `'transactions'` | The update type field |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | The account address |
+| `transactions`\* | <code><a href="#transaction">Transaction</a>[]</code> | The array of transactions |
+| `traceHash`\* | <code><a href="#hex">Hex</a></code> | The hash of the trace |
+| `addressBook` | <code><a href="#addressbook">AddressBook</a></code> | Address book from streaming v2 notification |
+| `metadata` | `TransactionAddressMetadata` | Metadata from streaming v2 notification |
+| `status`\* | <code><a href="#streamingupdatestatus">StreamingUpdateStatus</a></code> | The finality of the update |
+
+#### TransferTonParameters
+
+Parameters accepted by [`transferTon`](#transferton) — same shape as [`CreateTransferTonTransactionParameters`](#createtransfertontransactionparameters).
+
+```ts
+type TransferTonParameters = CreateTransferTonTransactionParameters;
+```
+
+#### TransferTonReturnType
+
+Return type of [`transferTon`](#transferton).
+
+```ts
+type TransferTonReturnType = SendTransactionResponse;
+```
+
+#### WatchTransactionsByAddressOptions
+
+Options for [`watchTransactionsByAddress`](#watchtransactionsbyaddress).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `address`\* | <code><a href="#userfriendlyaddress">UserFriendlyAddress</a> \| Address</code> | Address to watch — pass a [`UserFriendlyAddress`](#userfriendlyaddress) string or an `Address` instance from `@ton/core`. |
+| `onChange`\* | <code>(update: <a href="#transactionsupdate">TransactionsUpdate</a>) =&gt; void</code> | Callback fired on every transactions update from the streaming provider. |
+| `network` | <code><a href="#network">Network</a></code> | 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. |
+
+#### WatchTransactionsByAddressReturnType
+
+Return type of [`watchTransactionsByAddress`](#watchtransactionsbyaddress) — call to stop receiving updates.
+
+```ts
+type WatchTransactionsByAddressReturnType = () => void;
+```
+
+#### WatchTransactionsOptions
+
+Options for [`watchTransactions`](#watchtransactions).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | <code>(update: <a href="#transactionsupdate">TransactionsUpdate</a>) =&gt; void</code> | Callback fired on every transactions update from the streaming provider. |
+| `network` | <code><a href="#network">Network</a></code> | Network to watch on. Defaults to the selected wallet's network. |
+
+#### WatchTransactionsReturnType
+
+Return type of [`watchTransactions`](#watchtransactions) — call to stop receiving updates.
+
+```ts
+type WatchTransactionsReturnType = () => void;
+```
+
+### Wallets
+
+#### GetConnectedWalletsReturnType
+
+Return type of [`getConnectedWallets`](#getconnectedwallets) — read-only view of the connected-wallets array.
+
+```ts
+type GetConnectedWalletsReturnType = readonly WalletInterface[];
+```
+
+#### GetSelectedWalletReturnType
+
+Return type of [`getSelectedWallet`](#getselectedwallet) — `null` when no wallet is currently selected.
+
+```ts
+type GetSelectedWalletReturnType = WalletInterface | null;
+```
+
+#### SetSelectedWalletIdParameters
+
+Parameters accepted by [`setSelectedWalletId`](#setselectedwalletid).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `walletId`\* | `string \| null` | Wallet ID (as returned by [`WalletInterface`](#walletinterface)'s `getWalletId()`) to select; pass `null` to clear the selection. |
+
+#### SetSelectedWalletIdReturnType
+
+Return type of [`setSelectedWalletId`](#setselectedwalletid).
+
+```ts
+type SetSelectedWalletIdReturnType = void;
+```
+
+#### TonConnectWalletAdapterConfig
+
+Configuration accepted by [`TonConnectWalletAdapter`](#tonconnectwalletadapter) when wrapping a TonConnect wallet for AppKit.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `connectorId`\* | `string` | ID of the connector that produced this wallet — surfaced as `WalletInterface.connectorId`. |
+| `tonConnectWallet`\* | `TonConnectWallet` | Underlying TonConnect wallet object. |
+| `tonConnectUI`\* | `TonConnectUI` | TonConnect UI instance used to drive `sendTransaction` and `signData` calls. |
+
+#### WalletInterface
+
+Wallet contract surfaced by every [`Connector`](#connector) — covers identity (address, public key, network) and signing operations; reads (balance, jettons, NFTs) go through AppKit actions instead.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `connectorId`\* | `string` | ID of the [`Connector`](#connector) that produced this wallet. |
+| `getAddress`\* | <code>() =&gt; <a href="#userfriendlyaddress">UserFriendlyAddress</a></code> | Wallet address as a user-friendly base64url string. |
+| `getPublicKey`\* | <code>() =&gt; <a href="#hex">Hex</a></code> | Wallet public key as a `0x`-prefixed hex string. |
+| `getNetwork`\* | <code>() =&gt; <a href="#network">Network</a></code> | Network the wallet is currently connected to. |
+| `getWalletId`\* | `() => string` | Stable identifier combining address and network — unique across AppKit's connected wallets. |
+| `sendTransaction`\* | <code>(request: <a href="#transactionrequest">TransactionRequest</a>) =&gt; Promise&lt;<a href="#sendtransactionresponse">SendTransactionResponse</a>&gt;</code> | Send a transaction — the wallet signs and broadcasts it. |
+| `signData`\* | <code>(payload: <a href="#signdatarequest">SignDataRequest</a>) =&gt; Promise&lt;<a href="#signdataresponse">SignDataResponse</a>&gt;</code> | Sign arbitrary data — text, binary or TON cell — through the wallet's sign-data flow. |
+
+#### WatchConnectedWalletsParameters
+
+Parameters accepted by [`watchConnectedWallets`](#watchconnectedwallets).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | <code>(wallets: <a href="#walletinterface">WalletInterface</a>[]) =&gt; void</code> | Callback fired whenever the list of connected wallets changes — receives the latest snapshot. |
+
+#### WatchConnectedWalletsReturnType
+
+Return type of [`watchConnectedWallets`](#watchconnectedwallets) — call to stop receiving updates.
+
+```ts
+type WatchConnectedWalletsReturnType = () => void;
+```
+
+#### WatchSelectedWalletParameters
+
+Parameters accepted by [`watchSelectedWallet`](#watchselectedwallet).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `onChange`\* | <code>(wallet: <a href="#walletinterface">WalletInterface</a> \| null) =&gt; void</code> | Callback fired whenever the selected wallet changes — receives the new wallet, or `null` when the selection was cleared. |
+
+#### WatchSelectedWalletReturnType
+
+Return type of [`watchSelectedWallet`](#watchselectedwallet) — call to stop receiving updates.
+
+```ts
+type WatchSelectedWalletReturnType = () => void;
+```
+
+## Constants
+
+### Connectors
+
+#### CONNECTOR_EVENTS
+
+Event names AppKit emits for connector-list and connector-wallet changes; payloads are [`ConnectorAddedPayload`](#connectoraddedpayload), [`ConnectorRemovedPayload`](#connectorremovedpayload) and [`ConnectorWalletsUpdatedPayload`](#connectorwalletsupdatedpayload).
+
+```ts
+const CONNECTOR_EVENTS = {
+    /** A connector was registered via {@link addConnector} (or AppKit's constructor). */
+    ADDED: 'connector:added',
+    /** A connector was unregistered via `removeConnector` or its own teardown. */
+    REMOVED: 'connector:removed',
+    /** A connector's connected-wallets list changed (connect, disconnect, or account switch inside the wallet). */
+    WALLETS_UPDATED: 'connector:wallets-updated',
+} as const;
+```
+
+#### TONCONNECT_DEFAULT_CONNECTOR_ID
+
+Default id assigned to the TonConnect connector when none is supplied to [`createTonConnectConnector`](#createtonconnectconnector); pass this to [`connect`](#connect) / [`disconnect`](#disconnect) to drive the TonConnect flow without hard-coding the literal.
+
+```ts
+const TONCONNECT_DEFAULT_CONNECTOR_ID = 'tonconnect';
+```
+
+### Networks
+
+#### NETWORKS_EVENTS
+
+Event names AppKit emits on network changes; `DEFAULT_CHANGED` carries a [`DefaultNetworkChangedPayload`](#defaultnetworkchangedpayload).
+
+```ts
+const NETWORKS_EVENTS = {
+    UPDATED: 'networks:updated',
+    DEFAULT_CHANGED: 'networks:default-changed',
+} as const;
+```
+
+### Staking
+
+#### StakingErrorCode
+
+Discriminator carried on every [`StakingError`](#stakingerror)'s `code` — `'INVALID_PARAMS'` (the request was malformed) or `'UNSUPPORTED_OPERATION'` (the provider doesn't support this call).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `InvalidParams`\* | `"INVALID_PARAMS"` | Caller passed parameters that fail provider-level validation. |
+| `UnsupportedOperation`\* | `"UNSUPPORTED_OPERATION"` | Provider doesn't support the requested operation (e.g., reversed quote on a unidirectional pool). |
+
+#### UnstakeMode
+
+Allowed unstake-timing flavours referenced by [`UnstakeModes`](#unstakemodes) and [`StakingProviderMetadata`](#stakingprovidermetadata)'s `supportedUnstakeModes` — `'INSTANT'` (immediate withdrawal when the pool has liquidity, otherwise the funds are returned), `'WHEN_AVAILABLE'` (paid out as soon as liquidity is available — instantly or at round end), `'ROUND_END'` (paid out at the end of the staking round, typically for the best rate).
+
+```ts
+const UnstakeMode = { readonly INSTANT: "INSTANT"; readonly WHEN_AVAILABLE: "WHEN_AVAILABLE"; readonly ROUND_END: "ROUND_END"; };
+```
+
+### Wallets
+
+#### WALLETS_EVENTS
+
+Event names AppKit emits when the available wallet list (`UPDATED`) or the active wallet (`SELECTION_CHANGED`) changes.
+
+```ts
+const WALLETS_EVENTS = {
+    UPDATED: 'wallets:updated',
+    SELECTION_CHANGED: 'wallets:selection-changed',
+} as const;
+```
diff --git a/packages/appkit/docs/staking.md b/packages/appkit/docs/staking.md
index eff1434fa..e8d1d1bdf 100644
--- a/packages/appkit/docs/staking.md
+++ b/packages/appkit/docs/staking.md
@@ -1,7 +1,7 @@
 <!--
 This file is auto-generated. Do not edit manually.
 Changes will be overwritten when running the docs update script.
-Source template: template/packages/appkit/docs/staking.md
+Source template: docs/templates/packages/appkit/docs/staking.md
 -->
 
 # Staking
diff --git a/packages/appkit/docs/swap.md b/packages/appkit/docs/swap.md
index 1847973b2..697b2189c 100644
--- a/packages/appkit/docs/swap.md
+++ b/packages/appkit/docs/swap.md
@@ -1,7 +1,7 @@
 <!--
 This file is auto-generated. Do not edit manually.
 Changes will be overwritten when running the docs update script.
-Source template: template/packages/appkit/docs/swap.md
+Source template: docs/templates/packages/appkit/docs/swap.md
 -->
 
 # Swap
diff --git a/packages/appkit/src/actions/balances/get-balance-by-address.ts b/packages/appkit/src/actions/balances/get-balance-by-address.ts
index d4833395c..f4c372822 100644
--- a/packages/appkit/src/actions/balances/get-balance-by-address.ts
+++ b/packages/appkit/src/actions/balances/get-balance-by-address.ts
@@ -7,19 +7,50 @@
  */
 
 import { Address } from '@ton/core';
-import type { TokenAmount, Network } from '@ton/walletkit';
-import { formatUnits } from '@ton/walletkit';
 
 import type { AppKit } from '../../core/app-kit';
+import type { TokenAmount, UserFriendlyAddress } from '../../types/primitives';
+import type { Network } from '../../types/network';
+import { formatUnits } from '../../utils';
 import { resolveNetwork } from '../../utils/network/resolve-network';
 
+/**
+ * Options for {@link getBalanceByAddress}.
+ *
+ * @public
+ * @category Type
+ * @section Balances
+ */
 export interface GetBalanceByAddressOptions {
-    address: string | Address;
+    /** Wallet address — pass a {@link UserFriendlyAddress} string or an `Address` instance from `@ton/core`. */
+    address: UserFriendlyAddress | Address;
+    /** 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. */
     network?: Network;
 }
 
+/**
+ * Return type of {@link getBalanceByAddress}.
+ *
+ * @public
+ * @category Type
+ * @section Balances
+ */
 export type GetBalanceByAddressReturnType = TokenAmount;
 
+/**
+ * Read the Toncoin balance of an arbitrary address — useful for wallets that aren't selected in AppKit (use {@link getBalance} for the selected wallet).
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetBalanceByAddressOptions} Target address and optional network.
+ * @returns Balance in TON as a human-readable decimal string.
+ *
+ * @sample docs/examples/src/appkit/actions/balances#GET_BALANCE_BY_ADDRESS
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Balances
+ */
 export const getBalanceByAddress = async (
     appKit: AppKit,
     options: GetBalanceByAddressOptions,
diff --git a/packages/appkit/src/actions/balances/get-balance.ts b/packages/appkit/src/actions/balances/get-balance.ts
index 3fd874984..d684e6937 100644
--- a/packages/appkit/src/actions/balances/get-balance.ts
+++ b/packages/appkit/src/actions/balances/get-balance.ts
@@ -6,19 +6,47 @@
  *
  */
 
-import type { TokenAmount } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { TokenAmount } from '../../types/primitives';
+import type { Network } from '../../types/network';
 import { getSelectedWallet } from '../wallets/get-selected-wallet';
 import { getBalanceByAddress } from './get-balance-by-address';
-import type { Network } from '../../types/network';
 
+/**
+ * Options for {@link getBalance}.
+ *
+ * @public
+ * @category Type
+ * @section Balances
+ */
 export interface GetBalanceOptions {
+    /** Network to read the balance from. Defaults to the selected wallet's network. */
     network?: Network;
 }
 
+/**
+ * Return type of {@link getBalance}.
+ *
+ * @public
+ * @category Type
+ * @section Balances
+ */
 export type GetBalanceReturnType = TokenAmount | null;
 
+/**
+ * Read the Toncoin balance of the currently selected wallet, returning `null` when no wallet is selected (use {@link getBalanceByAddress} for an arbitrary address).
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetBalanceOptions} Optional network override.
+ * @returns Balance in TON as a human-readable decimal string, or `null` when no wallet is selected.
+ *
+ * @sample docs/examples/src/appkit/actions/balances#GET_BALANCE
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Balances
+ */
 export const getBalance = async (appKit: AppKit, options: GetBalanceOptions = {}): Promise<GetBalanceReturnType> => {
     const selectedWallet = getSelectedWallet(appKit);
 
diff --git a/packages/appkit/src/actions/balances/watch-balance-by-address.ts b/packages/appkit/src/actions/balances/watch-balance-by-address.ts
index 6116e7fc9..de0d9f564 100644
--- a/packages/appkit/src/actions/balances/watch-balance-by-address.ts
+++ b/packages/appkit/src/actions/balances/watch-balance-by-address.ts
@@ -7,21 +7,51 @@
  */
 
 import { Address } from '@ton/core';
-import type { BalanceUpdate, Network } from '@ton/walletkit';
 
 import type { AppKit } from '../../core/app-kit';
+import type { BalanceUpdate } from '../../core/streaming';
+import type { UserFriendlyAddress } from '../../types/primitives';
+import type { Network } from '../../types/network';
 import { resolveNetwork } from '../../utils/network/resolve-network';
 
+/**
+ * Options for {@link watchBalanceByAddress}.
+ *
+ * @public
+ * @category Type
+ * @section Balances
+ */
 export interface WatchBalanceByAddressOptions {
-    address: string | Address;
+    /** Wallet address — pass a {@link UserFriendlyAddress} string or an `Address` instance from `@ton/core`. */
+    address: UserFriendlyAddress | Address;
+    /** 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. */
     network?: Network;
+    /** Callback fired on every balance update from the streaming provider. */
     onChange: (update: BalanceUpdate) => void;
 }
 
+/**
+ * Return type of {@link watchBalanceByAddress} — call to stop receiving updates.
+ *
+ * @public
+ * @category Type
+ * @section Balances
+ */
 export type WatchBalanceByAddressReturnType = () => void;
 
 /**
- * Watch account balance changes by address.
+ * Subscribe to Toncoin balance updates for an arbitrary address — useful for monitoring wallets that aren't selected in AppKit (use {@link watchBalance} for the selected wallet).
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link WatchBalanceByAddressOptions} Target address, update callback and optional network override.
+ * @returns Unsubscribe function — call it to stop receiving updates.
+ *
+ * @sample docs/examples/src/appkit/actions/balances#WATCH_BALANCE_BY_ADDRESS
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Balances
  */
 export const watchBalanceByAddress = (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/balances/watch-balance.ts b/packages/appkit/src/actions/balances/watch-balance.ts
index e8ff00a60..50ed1d147 100644
--- a/packages/appkit/src/actions/balances/watch-balance.ts
+++ b/packages/appkit/src/actions/balances/watch-balance.ts
@@ -6,22 +6,49 @@
  *
  */
 
-import type { BalanceUpdate, Network } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
 import { WALLETS_EVENTS } from '../../core/app-kit';
+import type { BalanceUpdate } from '../../core/streaming';
+import type { Network } from '../../types/network';
 import { getSelectedWallet } from '../wallets/get-selected-wallet';
 import { watchBalanceByAddress } from './watch-balance-by-address';
 
+/**
+ * Options for {@link watchBalance}.
+ *
+ * @public
+ * @category Type
+ * @section Balances
+ */
 export interface WatchBalanceOptions {
+    /** Network to watch on. Defaults to the selected wallet's network. */
     network?: Network;
+    /** Callback fired on every balance update from the streaming provider. */
     onChange: (update: BalanceUpdate) => void;
 }
 
+/**
+ * Return type of {@link watchBalance} — call to stop receiving updates.
+ *
+ * @public
+ * @category Type
+ * @section Balances
+ */
 export type WatchBalanceReturnType = () => void;
 
 /**
- * Watch account balance changes for the selected wallet.
+ * Subscribe to Toncoin balance updates for the currently selected wallet, automatically rebinding whenever the selected wallet changes or the connected-wallets list updates (use {@link watchBalanceByAddress} for a fixed address).
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link WatchBalanceOptions} Update callback and optional network override.
+ * @returns Unsubscribe function — call it to stop receiving updates.
+ *
+ * @sample docs/examples/src/appkit/actions/balances#WATCH_BALANCE
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Balances
  */
 export const watchBalance = (appKit: AppKit, options: WatchBalanceOptions): WatchBalanceReturnType => {
     const { network, onChange } = options;
diff --git a/packages/appkit/src/actions/connectors/add-connector.ts b/packages/appkit/src/actions/connectors/add-connector.ts
index 36121b536..7114f0984 100644
--- a/packages/appkit/src/actions/connectors/add-connector.ts
+++ b/packages/appkit/src/actions/connectors/add-connector.ts
@@ -9,12 +9,36 @@
 import type { AppKit } from '../../core/app-kit';
 import type { ConnectorInput } from '../../types/connector';
 
+/**
+ * Connector instance or factory accepted by {@link addConnector} — same shape used in {@link AppKitConfig}'s `connectors`.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export type AddConnectorParameters = ConnectorInput;
 
+/**
+ * Return type of {@link addConnector} — call to remove the connector from AppKit.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export type AddConnectorReturnType = () => void;
 
 /**
- * Add a wallet connector
+ * Register a wallet connector at runtime — equivalent to passing it via {@link AppKitConfig}'s `connectors` at construction, but available after AppKit is up.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param connectorFn - {@link AddConnectorParameters} Connector instance or factory to register.
+ * @returns Function that unregisters the connector when called.
+ *
+ * @sample docs/examples/src/appkit/actions/connectors#ADD_CONNECTOR
+ *
+ * @public
+ * @category Action
+ * @section Connectors
  */
 export const addConnector = (appKit: AppKit, connectorFn: AddConnectorParameters): AddConnectorReturnType => {
     return appKit.addConnector(connectorFn);
diff --git a/packages/appkit/src/actions/connectors/connect.ts b/packages/appkit/src/actions/connectors/connect.ts
index 199d6bb7c..860efbd8f 100644
--- a/packages/appkit/src/actions/connectors/connect.ts
+++ b/packages/appkit/src/actions/connectors/connect.ts
@@ -9,14 +9,40 @@
 import type { AppKit } from '../../core/app-kit';
 import { getDefaultNetwork } from '../network/get-default-network';
 
+/**
+ * Parameters accepted by {@link connect}.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export type ConnectParameters = {
+    /** ID of the registered connector to drive the connection through (e.g., `'tonconnect'`). */
     connectorId: string;
 };
 
+/**
+ * Return type of {@link connect}.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export type ConnectReturnType = void;
 
 /**
- * Connect wallet using specific connector
+ * Trigger the connection flow on a registered connector by id — drives it against AppKit's default network (set via {@link setDefaultNetwork}); throws when no connector with that id exists.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link ConnectParameters} Connector to connect through.
+ * @returns Resolves once the connector's connect flow completes; if a wallet was successfully connected, it becomes available via {@link getSelectedWallet}.
+ *
+ * @sample docs/examples/src/appkit/actions/connectors#CONNECT
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Connectors
  */
 export const connect = async (appKit: AppKit, parameters: ConnectParameters): Promise<ConnectReturnType> => {
     const { connectorId } = parameters;
diff --git a/packages/appkit/src/actions/connectors/disconnect.ts b/packages/appkit/src/actions/connectors/disconnect.ts
index 4fdd0db2d..51dded32f 100644
--- a/packages/appkit/src/actions/connectors/disconnect.ts
+++ b/packages/appkit/src/actions/connectors/disconnect.ts
@@ -8,14 +8,40 @@
 
 import type { AppKit } from '../../core/app-kit';
 
+/**
+ * Parameters accepted by {@link disconnect}.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export type DisconnectParameters = {
+    /** ID of the registered connector whose wallet should be disconnected. */
     connectorId: string;
 };
 
+/**
+ * Return type of {@link disconnect}.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export type DisconnectReturnType = void;
 
 /**
- * Disconnect wallet using specific connector
+ * 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.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link DisconnectParameters} Connector to disconnect.
+ * @returns Resolves once the connector tears down its session.
+ *
+ * @sample docs/examples/src/appkit/actions/connectors#DISCONNECT
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Connectors
  */
 export const disconnect = async (appKit: AppKit, parameters: DisconnectParameters): Promise<DisconnectReturnType> => {
     const { connectorId } = parameters;
diff --git a/packages/appkit/src/actions/connectors/get-connector-by-id.ts b/packages/appkit/src/actions/connectors/get-connector-by-id.ts
index 9bd3263f2..15bccafda 100644
--- a/packages/appkit/src/actions/connectors/get-connector-by-id.ts
+++ b/packages/appkit/src/actions/connectors/get-connector-by-id.ts
@@ -9,14 +9,40 @@
 import type { Connector } from '../../types/connector';
 import type { AppKit } from '../../core/app-kit';
 
+/**
+ * Options for {@link getConnectorById}.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export interface GetConnectorByIdOptions {
+    /** ID of the connector to look up. */
     id: string;
 }
 
+/**
+ * Return type of {@link getConnectorById} — `undefined` when no connector with that id is registered.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export type GetConnectorByIdReturnType = Connector | undefined;
 
 /**
- * Get connector by id
+ * Look up a registered connector by its id.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetConnectorByIdOptions} ID of the connector to find.
+ * @returns The matching {@link Connector}, or `undefined` if none with that id is registered.
+ *
+ * @sample docs/examples/src/appkit/actions/connectors#GET_CONNECTOR_BY_ID
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Connectors
  */
 export const getConnectorById = (appKit: AppKit, options: GetConnectorByIdOptions): GetConnectorByIdReturnType => {
     return appKit.connectors.find((connector) => connector.id === options.id);
diff --git a/packages/appkit/src/actions/connectors/get-connectors.ts b/packages/appkit/src/actions/connectors/get-connectors.ts
index 5f9adae9a..a82fad9aa 100644
--- a/packages/appkit/src/actions/connectors/get-connectors.ts
+++ b/packages/appkit/src/actions/connectors/get-connectors.ts
@@ -9,10 +9,26 @@
 import type { Connector } from '../../types/connector';
 import type { AppKit } from '../../core/app-kit';
 
+/**
+ * Return type of {@link getConnectors} — read-only view of the registered-connectors array.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export type GetConnectorsReturnType = readonly Connector[];
 
 /**
- * Get connected wallets
+ * List every connector registered on this AppKit instance — both those passed via {@link AppKitConfig}'s `connectors` and those added later through {@link addConnector}.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @returns Read-only array of registered {@link Connector}s.
+ *
+ * @sample docs/examples/src/appkit/actions/connectors#GET_CONNECTORS
+ *
+ * @public
+ * @category Action
+ * @section Connectors
  */
 export const getConnectors = (appKit: AppKit): GetConnectorsReturnType => {
     return appKit.connectors;
diff --git a/packages/appkit/src/actions/connectors/watch-connector-by-id.ts b/packages/appkit/src/actions/connectors/watch-connector-by-id.ts
index 067d86397..accff17bb 100644
--- a/packages/appkit/src/actions/connectors/watch-connector-by-id.ts
+++ b/packages/appkit/src/actions/connectors/watch-connector-by-id.ts
@@ -11,15 +11,42 @@ import { CONNECTOR_EVENTS } from '../../core/app-kit';
 import type { Connector } from '../../types/connector';
 import { getConnectorById } from './get-connector-by-id';
 
+/**
+ * Parameters accepted by {@link watchConnectorById}.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export interface WatchConnectorByIdParameters {
+    /** ID of the connector to watch. */
     id: string;
+    /** Callback invoked when the connector with the watched id is registered or unregistered — receives the connector itself, or `undefined` when none is registered under that id. */
     onChange: (connector: Connector | undefined) => void;
 }
 
+/**
+ * Return type of {@link watchConnectorById} — call to stop receiving updates.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export type WatchConnectorByIdReturnType = () => void;
 
 /**
- * Watch connector by id
+ * 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 {@link watchConnectedWallets} if you want to react to wallet connect/disconnect events instead.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link WatchConnectorByIdParameters} Connector ID and update callback.
+ * @returns Unsubscribe function — call it to stop receiving updates.
+ *
+ * @sample docs/examples/src/appkit/actions/connectors#WATCH_CONNECTOR_BY_ID
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Connectors
  */
 export const watchConnectorById = (
     appKit: AppKit,
@@ -27,9 +54,15 @@ export const watchConnectorById = (
 ): WatchConnectorByIdReturnType => {
     const { id, onChange } = parameters;
 
-    const unsubscribe = appKit.emitter.on(CONNECTOR_EVENTS.CONNECTED, () => {
+    const handler = (): void => {
         onChange(getConnectorById(appKit, { id }));
-    });
+    };
+
+    const unsubscribeAdded = appKit.emitter.on(CONNECTOR_EVENTS.ADDED, handler);
+    const unsubscribeRemoved = appKit.emitter.on(CONNECTOR_EVENTS.REMOVED, handler);
 
-    return unsubscribe;
+    return () => {
+        unsubscribeAdded();
+        unsubscribeRemoved();
+    };
 };
diff --git a/packages/appkit/src/actions/connectors/watch-connectors.ts b/packages/appkit/src/actions/connectors/watch-connectors.ts
index a4d3b76e2..31a135d92 100644
--- a/packages/appkit/src/actions/connectors/watch-connectors.ts
+++ b/packages/appkit/src/actions/connectors/watch-connectors.ts
@@ -11,21 +11,53 @@ import { CONNECTOR_EVENTS } from '../../core/app-kit';
 import type { Connector } from '../../types/connector';
 import { getConnectors } from './get-connectors';
 
+/**
+ * Parameters accepted by {@link watchConnectors}.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export type WatchConnectorsParameters = {
+    /** Callback invoked when the list of registered connectors changes — receives the current list. */
     onChange: (connectors: readonly Connector[]) => void;
 };
 
+/**
+ * Return type of {@link watchConnectors} — call to stop receiving updates.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export type WatchConnectorsReturnType = () => void;
 
 /**
- * Watch connectors
+ * Subscribe to changes in the registered-connectors list — the callback fires when a connector is added (via {@link addConnector} or AppKit's constructor) or removed, and receives the current list. Use {@link watchConnectedWallets} if you want to react to wallet connect/disconnect events instead.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link WatchConnectorsParameters} Update callback.
+ * @returns Unsubscribe function — call it to stop receiving updates.
+ *
+ * @sample docs/examples/src/appkit/actions/connectors#WATCH_CONNECTORS
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Connectors
  */
 export const watchConnectors = (appKit: AppKit, parameters: WatchConnectorsParameters): WatchConnectorsReturnType => {
     const { onChange } = parameters;
 
-    const unsubscribe = appKit.emitter.on(CONNECTOR_EVENTS.CONNECTED, () => {
+    const handler = (): void => {
         onChange(getConnectors(appKit));
-    });
+    };
+
+    const unsubscribeAdded = appKit.emitter.on(CONNECTOR_EVENTS.ADDED, handler);
+    const unsubscribeRemoved = appKit.emitter.on(CONNECTOR_EVENTS.REMOVED, handler);
 
-    return unsubscribe;
+    return () => {
+        unsubscribeAdded();
+        unsubscribeRemoved();
+    };
 };
diff --git a/packages/appkit/src/actions/crypto-onramp/create-crypto-onramp-deposit.ts b/packages/appkit/src/actions/crypto-onramp/create-crypto-onramp-deposit.ts
index 8796a42b4..94217c19e 100644
--- a/packages/appkit/src/actions/crypto-onramp/create-crypto-onramp-deposit.ts
+++ b/packages/appkit/src/actions/crypto-onramp/create-crypto-onramp-deposit.ts
@@ -9,14 +9,39 @@
 import type { CryptoOnrampDeposit, CryptoOnrampDepositParams } from '../../crypto-onramp';
 import type { AppKit } from '../../core/app-kit';
 
+/**
+ * Options for {@link createCryptoOnrampDeposit} — extends {@link CryptoOnrampDepositParams} with an optional provider override.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type CreateCryptoOnrampDepositOptions<T = unknown> = CryptoOnrampDepositParams<T> & {
+    /** Provider to create the deposit through; defaults to `quote.providerId`, then to the default provider. */
     providerId?: string;
 };
 
+/**
+ * Return type of {@link createCryptoOnrampDeposit}.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type CreateCryptoOnrampDepositReturnType = Promise<CryptoOnrampDeposit>;
 
 /**
- * Create a crypto onramp deposit from a previously obtained quote
+ * Create a crypto-onramp deposit from a quote previously obtained via {@link getCryptoOnrampQuote} — the returned {@link CryptoOnrampDeposit} carries the address and amount the user must send on the source chain.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link CreateCryptoOnrampDepositOptions} Quote, refund address, and optional provider override.
+ * @returns Deposit details the UI should show to the user (address, amount, optional `memo`/`expiresAt`).
+ *
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Crypto Onramp
  */
 export const createCryptoOnrampDeposit = async <T = unknown>(
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/crypto-onramp/get-crypto-onramp-provider.ts b/packages/appkit/src/actions/crypto-onramp/get-crypto-onramp-provider.ts
index 47cf0a91f..ef90df627 100644
--- a/packages/appkit/src/actions/crypto-onramp/get-crypto-onramp-provider.ts
+++ b/packages/appkit/src/actions/crypto-onramp/get-crypto-onramp-provider.ts
@@ -6,18 +6,43 @@
  *
  */
 
-import type { CryptoOnrampProviderInterface } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { CryptoOnrampProviderInterface } from '../../crypto-onramp';
 
+/**
+ * Options for {@link getCryptoOnrampProvider}.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export interface GetCryptoOnrampProviderOptions {
+    /** Provider ID to look up; when omitted, returns the registered default provider. */
     id?: string;
 }
 
+/**
+ * Return type of {@link getCryptoOnrampProvider}.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type GetCryptoOnrampProviderReturnType = CryptoOnrampProviderInterface;
 
 /**
- * Get a registered crypto-onramp provider by id, or the default one when no id is given.
+ * 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.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetCryptoOnrampProviderOptions} Optional provider id.
+ * @returns The matching {@link CryptoOnrampProviderInterface}.
+ *
+ * @sample docs/examples/src/appkit/actions/onramp#GET_CRYPTO_ONRAMP_PROVIDER
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Crypto Onramp
  */
 export const getCryptoOnrampProvider = (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/crypto-onramp/get-crypto-onramp-providers.ts b/packages/appkit/src/actions/crypto-onramp/get-crypto-onramp-providers.ts
index ea4add53b..b14de4f8b 100644
--- a/packages/appkit/src/actions/crypto-onramp/get-crypto-onramp-providers.ts
+++ b/packages/appkit/src/actions/crypto-onramp/get-crypto-onramp-providers.ts
@@ -6,14 +6,29 @@
  *
  */
 
-import type { CryptoOnrampProviderInterface } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { CryptoOnrampProviderInterface } from '../../crypto-onramp';
 
+/**
+ * Return type of {@link getCryptoOnrampProviders}.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type GetCryptoOnrampProvidersReturnType = CryptoOnrampProviderInterface[];
 
 /**
- * Get all registered crypto-onramp providers.
+ * List every crypto-onramp provider registered on this AppKit instance — both those passed via {@link AppKitConfig}'s `providers` and those added later through {@link registerProvider}.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @returns Array of registered {@link CryptoOnrampProviderInterface}s.
+ *
+ * @sample docs/examples/src/appkit/actions/onramp#GET_CRYPTO_ONRAMP_PROVIDERS
+ *
+ * @public
+ * @category Action
+ * @section Crypto Onramp
  */
 export const getCryptoOnrampProviders = (appKit: AppKit): GetCryptoOnrampProvidersReturnType => {
     return appKit.cryptoOnrampManager.getProviders();
diff --git a/packages/appkit/src/actions/crypto-onramp/get-crypto-onramp-quote.ts b/packages/appkit/src/actions/crypto-onramp/get-crypto-onramp-quote.ts
index 32fee07da..0ff71f9a1 100644
--- a/packages/appkit/src/actions/crypto-onramp/get-crypto-onramp-quote.ts
+++ b/packages/appkit/src/actions/crypto-onramp/get-crypto-onramp-quote.ts
@@ -9,14 +9,39 @@
 import type { CryptoOnrampQuote, CryptoOnrampQuoteParams } from '../../crypto-onramp';
 import type { AppKit } from '../../core/app-kit';
 
+/**
+ * Options for {@link getCryptoOnrampQuote} — extends {@link CryptoOnrampQuoteParams} with an optional provider override.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type GetCryptoOnrampQuoteOptions<T = unknown> = CryptoOnrampQuoteParams<T> & {
+    /** Provider to quote against; defaults to the registered default provider. */
     providerId?: string;
 };
 
+/**
+ * Return type of {@link getCryptoOnrampQuote}.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type GetCryptoOnrampQuoteReturnType = Promise<CryptoOnrampQuote>;
 
 /**
- * Get a crypto onramp quote
+ * 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 {@link createCryptoOnrampDeposit}.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetCryptoOnrampQuoteOptions} Source asset, target asset, amount and optional provider override.
+ * @returns Quote with pricing details and the provider metadata required to create a deposit.
+ *
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Crypto Onramp
  */
 export const getCryptoOnrampQuote = async <T = unknown>(
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/crypto-onramp/get-crypto-onramp-status.ts b/packages/appkit/src/actions/crypto-onramp/get-crypto-onramp-status.ts
index 7be56078d..81299c5b2 100644
--- a/packages/appkit/src/actions/crypto-onramp/get-crypto-onramp-status.ts
+++ b/packages/appkit/src/actions/crypto-onramp/get-crypto-onramp-status.ts
@@ -9,14 +9,39 @@
 import type { CryptoOnrampStatus, CryptoOnrampStatusParams } from '../../crypto-onramp';
 import type { AppKit } from '../../core/app-kit';
 
+/**
+ * Options for {@link getCryptoOnrampStatus} — extends {@link CryptoOnrampStatusParams} with an optional provider override.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type GetCryptoOnrampStatusOptions = CryptoOnrampStatusParams & {
+    /** Provider that issued the deposit; defaults to the registered default provider. */
     providerId?: string;
 };
 
+/**
+ * Return type of {@link getCryptoOnrampStatus}.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type GetCryptoOnrampStatusReturnType = Promise<CryptoOnrampStatus>;
 
 /**
- * Get a crypto onramp quote
+ * Read the current status of a crypto-onramp deposit by id — typically polled until the result is `'success'` or `'failed'`.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetCryptoOnrampStatusOptions} Deposit id, originating provider id and optional provider override.
+ * @returns Current {@link CryptoOnrampStatus} of the deposit.
+ *
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Crypto Onramp
  */
 export const getCryptoOnrampStatus = async (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/crypto-onramp/watch-crypto-onramp-providers.ts b/packages/appkit/src/actions/crypto-onramp/watch-crypto-onramp-providers.ts
index dea15b8eb..6f40dfb8a 100644
--- a/packages/appkit/src/actions/crypto-onramp/watch-crypto-onramp-providers.ts
+++ b/packages/appkit/src/actions/crypto-onramp/watch-crypto-onramp-providers.ts
@@ -8,14 +8,39 @@
 
 import type { AppKit } from '../../core/app-kit';
 
+/**
+ * Parameters accepted by {@link watchCryptoOnrampProviders}.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export interface WatchCryptoOnrampProvidersParameters {
+    /** Callback fired whenever a crypto-onramp provider is registered or the default crypto-onramp provider changes. */
     onChange: () => void;
 }
 
+/**
+ * Return type of {@link watchCryptoOnrampProviders} — call to stop receiving updates.
+ *
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type WatchCryptoOnrampProvidersReturnType = () => void;
 
 /**
- * Watch for new crypto-onramp providers registration and default-provider changes.
+ * Subscribe to crypto-onramp provider lifecycle — fires `onChange` whenever a new provider is registered or the default crypto-onramp provider switches.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link WatchCryptoOnrampProvidersParameters} Update callback.
+ * @returns Unsubscribe function — call it to stop receiving updates.
+ *
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Crypto Onramp
  */
 export const watchCryptoOnrampProviders = (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/index.ts b/packages/appkit/src/actions/index.ts
index b9d31916d..dc7b8025d 100644
--- a/packages/appkit/src/actions/index.ts
+++ b/packages/appkit/src/actions/index.ts
@@ -41,7 +41,7 @@ export {
     type WatchConnectorByIdReturnType,
 } from './connectors/watch-connector-by-id';
 
-// Crypto onramp
+// Crypto Onramp
 export {
     getCryptoOnrampProvider,
     type GetCryptoOnrampProviderOptions,
diff --git a/packages/appkit/src/actions/jettons/create-transfer-jetton-transaction.ts b/packages/appkit/src/actions/jettons/create-transfer-jetton-transaction.ts
index bd4b818f9..e05363e35 100644
--- a/packages/appkit/src/actions/jettons/create-transfer-jetton-transaction.ts
+++ b/packages/appkit/src/actions/jettons/create-transfer-jetton-transaction.ts
@@ -6,30 +6,60 @@
  *
  */
 
+import type { AppKit } from '../../core/app-kit';
+import type { TransactionRequest } from '../../types/transaction';
+import type { UserFriendlyAddress } from '../../types/primitives';
 import {
     createJettonTransferPayload,
     createTransferTransaction,
     getJettonWalletAddressFromClient,
     DEFAULT_JETTON_GAS_FEE,
     parseUnits,
-} from '@ton/walletkit';
-
-import type { TransactionRequest } from '../../types/transaction';
-import type { AppKit } from '../../core/app-kit';
+} from '../../utils';
 import { getSelectedWallet } from '../wallets/get-selected-wallet';
 
+/**
+ * Parameters accepted by {@link createTransferJettonTransaction} and {@link transferJetton}.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export interface CreateTransferJettonTransactionParameters {
-    jettonAddress: string;
-    recipientAddress: string;
+    /** Jetton master contract address being transferred. */
+    jettonAddress: UserFriendlyAddress;
+    /** Recipient who should receive the jettons. */
+    recipientAddress: UserFriendlyAddress;
+    /** Amount in jetton units as a human-readable decimal string (e.g., `"1.5"`). */
     amount: string;
+    /** Decimals declared by the jetton master; used to convert `amount` into raw smallest units. */
     jettonDecimals: number;
+    /** Optional human-readable comment attached to the transfer. */
     comment?: string;
 }
 
+/**
+ * Return type of {@link createTransferJettonTransaction}.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type CreateTransferJettonTransactionReturnType = TransactionRequest;
 
 /**
- * Create a Jetton transfer transaction request
+ * Build a jetton transfer {@link 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.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link CreateTransferJettonTransactionParameters} Jetton, recipient, amount, decimals and optional comment.
+ * @returns Transaction request ready to pass to `sendTransaction`.
+ *
+ * @sample docs/examples/src/appkit/actions/jettons#CREATE_TRANSFER_JETTON_TRANSACTION
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Jettons
  */
 export const createTransferJettonTransaction = async (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/jettons/get-jetton-balance.ts b/packages/appkit/src/actions/jettons/get-jetton-balance.ts
index c59531add..506715530 100644
--- a/packages/appkit/src/actions/jettons/get-jetton-balance.ts
+++ b/packages/appkit/src/actions/jettons/get-jetton-balance.ts
@@ -6,23 +6,54 @@
  *
  */
 
-import { getJettonBalanceFromClient, formatUnits } from '@ton/walletkit';
-import type { TokenAmount, UserFriendlyAddress } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
-import { getJettonWalletAddress } from './get-jetton-wallet-address';
-import { resolveNetwork } from '../../utils/network/resolve-network';
+import type { TokenAmount, UserFriendlyAddress } from '../../types/primitives';
 import type { Network } from '../../types/network';
+import { getJettonBalanceFromClient, formatUnits } from '../../utils';
+import { resolveNetwork } from '../../utils/network/resolve-network';
+import { getJettonWalletAddress } from './get-jetton-wallet-address';
 
+/**
+ * Options for {@link getJettonBalance}.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export interface GetJettonBalanceOptions {
+    /** Jetton master contract address (the token, not the user's wallet for it). */
     jettonAddress: UserFriendlyAddress;
+    /** Owner of the jetton wallet — typically the connected user's address. */
     ownerAddress: UserFriendlyAddress;
+    /** Decimals declared by the jetton master; used to format the raw balance into a human-readable string. */
     jettonDecimals: number;
+    /** 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. */
     network?: Network;
 }
 
+/**
+ * Return type of {@link getJettonBalance}.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type GetJettonBalanceReturnType = TokenAmount;
 
+/**
+ * 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.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetJettonBalanceOptions} Jetton master, owner address, decimals and optional network override.
+ * @returns Balance as a human-readable decimal string in the jetton's units.
+ *
+ * @sample docs/examples/src/appkit/actions/jettons#GET_JETTON_BALANCE
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Jettons
+ */
 export const getJettonBalance = async (
     appKit: AppKit,
     options: GetJettonBalanceOptions,
diff --git a/packages/appkit/src/actions/jettons/get-jetton-info.ts b/packages/appkit/src/actions/jettons/get-jetton-info.ts
index a2681f5a0..36de81370 100644
--- a/packages/appkit/src/actions/jettons/get-jetton-info.ts
+++ b/packages/appkit/src/actions/jettons/get-jetton-info.ts
@@ -6,19 +6,49 @@
  *
  */
 
-import type { JettonInfo } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
-import { resolveNetwork } from '../../utils/network/resolve-network';
+import type { JettonInfo } from '../../types/jetton';
 import type { Network } from '../../types/network';
+import type { UserFriendlyAddress } from '../../types/primitives';
+import { resolveNetwork } from '../../utils/network/resolve-network';
 
+/**
+ * Options for {@link getJettonInfo}.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export interface GetJettonInfoOptions {
-    address: string;
+    /** Jetton master contract address whose metadata is being fetched. */
+    address: UserFriendlyAddress;
+    /** 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. */
     network?: Network;
 }
 
+/**
+ * Return type of {@link getJettonInfo} — `null` when the indexer has no record for that master address.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type GetJettonInfoReturnType = JettonInfo | null;
 
+/**
+ * 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.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetJettonInfoOptions} Jetton master address and optional network override.
+ * @returns Jetton metadata, or `null` if the indexer has no record.
+ *
+ * @sample docs/examples/src/appkit/actions/jettons#GET_JETTON_INFO
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Jettons
+ */
 export const getJettonInfo = async (
     appKit: AppKit,
     options: GetJettonInfoOptions,
diff --git a/packages/appkit/src/actions/jettons/get-jetton-wallet-address.ts b/packages/appkit/src/actions/jettons/get-jetton-wallet-address.ts
index 5fbd9d294..38c169a7e 100644
--- a/packages/appkit/src/actions/jettons/get-jetton-wallet-address.ts
+++ b/packages/appkit/src/actions/jettons/get-jetton-wallet-address.ts
@@ -6,21 +6,51 @@
  *
  */
 
-import { getJettonWalletAddressFromClient } from '@ton/walletkit';
-import type { UserFriendlyAddress } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
-import { resolveNetwork } from '../../utils/network/resolve-network';
+import type { UserFriendlyAddress } from '../../types/primitives';
 import type { Network } from '../../types/network';
+import { getJettonWalletAddressFromClient } from '../../utils';
+import { resolveNetwork } from '../../utils/network/resolve-network';
 
+/**
+ * Options for {@link getJettonWalletAddress}.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export interface GetJettonWalletAddressOptions {
+    /** Jetton master contract address. */
     jettonAddress: UserFriendlyAddress;
+    /** Owner whose jetton wallet should be derived. */
     ownerAddress: UserFriendlyAddress;
+    /** 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. */
     network?: Network;
 }
 
+/**
+ * Return type of {@link getJettonWalletAddress}.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type GetJettonWalletAddressReturnType = UserFriendlyAddress;
 
+/**
+ * Derive the jetton-wallet address for a given owner — the per-owner contract that actually holds the jetton balance for `jettonAddress`.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetJettonWalletAddressOptions} Jetton master, owner address and optional network override.
+ * @returns User-friendly address of the owner's jetton wallet.
+ *
+ * @sample docs/examples/src/appkit/actions/jettons#GET_JETTON_WALLET_ADDRESS
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Jettons
+ */
 export const getJettonWalletAddress = async (
     appKit: AppKit,
     options: GetJettonWalletAddressOptions,
diff --git a/packages/appkit/src/actions/jettons/get-jettons-by-address.ts b/packages/appkit/src/actions/jettons/get-jettons-by-address.ts
index 808cae0e4..8e8128af6 100644
--- a/packages/appkit/src/actions/jettons/get-jettons-by-address.ts
+++ b/packages/appkit/src/actions/jettons/get-jettons-by-address.ts
@@ -7,22 +7,55 @@
  */
 
 import { Address } from '@ton/core';
-import type { Jetton, JettonsResponse } from '@ton/walletkit';
-import { getJettonsFromClient, formatUnits } from '@ton/walletkit';
 
 import type { AppKit } from '../../core/app-kit';
-import { resolveNetwork } from '../../utils/network/resolve-network';
+import type { Jetton, JettonsResponse } from '../../types/jetton';
 import type { Network } from '../../types/network';
+import type { UserFriendlyAddress } from '../../types/primitives';
+import { getJettonsFromClient, formatUnits } from '../../utils';
+import { resolveNetwork } from '../../utils/network/resolve-network';
 
+/**
+ * Options for {@link getJettonsByAddress}.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export interface GetJettonsByAddressOptions {
-    address: string | Address;
+    /** Owner address — pass a {@link UserFriendlyAddress} string or an `Address` instance from `@ton/core`. */
+    address: UserFriendlyAddress | Address;
+    /** 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. */
     network?: Network;
+    /** Maximum number of jettons to return. */
     limit?: number;
+    /** Number of jettons to skip before returning results — used for pagination. */
     offset?: number;
 }
 
+/**
+ * Return type of {@link getJettonsByAddress}.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type GetJettonsByAddressReturnType = JettonsResponse;
 
+/**
+ * List jettons held by an arbitrary address — useful for inspecting wallets that aren't selected in AppKit (use {@link getJettons} for the selected wallet); raw balances are formatted with each jetton's declared decimals, and entries without decimals are dropped.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetJettonsByAddressOptions} Owner address, optional network override and pagination.
+ * @returns Jettons response with formatted balances.
+ *
+ * @sample docs/examples/src/appkit/actions/jettons#GET_JETTONS_BY_ADDRESS
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Jettons
+ */
 export const getJettonsByAddress = async (
     appKit: AppKit,
     options: GetJettonsByAddressOptions,
diff --git a/packages/appkit/src/actions/jettons/get-jettons.ts b/packages/appkit/src/actions/jettons/get-jettons.ts
index 5f662a894..1cac6fbec 100644
--- a/packages/appkit/src/actions/jettons/get-jettons.ts
+++ b/packages/appkit/src/actions/jettons/get-jettons.ts
@@ -6,21 +6,51 @@
  *
  */
 
-import type { JettonsResponse } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
-import { getJettonsByAddress } from './get-jettons-by-address';
-import { getSelectedWallet } from '../wallets/get-selected-wallet';
+import type { JettonsResponse } from '../../types/jetton';
 import type { Network } from '../../types/network';
+import { getSelectedWallet } from '../wallets/get-selected-wallet';
+import { getJettonsByAddress } from './get-jettons-by-address';
 
+/**
+ * Options for {@link getJettons}.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export interface GetJettonsOptions {
+    /** Network to read jettons from. Defaults to the selected wallet's network. */
     network?: Network;
+    /** Maximum number of jettons to return. */
     limit?: number;
+    /** Number of jettons to skip before returning results — used for pagination. */
     offset?: number;
 }
 
+/**
+ * Return type of {@link getJettons} — `null` when no wallet is currently selected.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type GetJettonsReturnType = JettonsResponse | null;
 
+/**
+ * List jettons held by the currently selected wallet, returning `null` when no wallet is selected (use {@link getJettonsByAddress} for an arbitrary address).
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetJettonsOptions} Optional network override and pagination.
+ * @returns Jettons response for the selected wallet, or `null` when none is selected.
+ *
+ * @sample docs/examples/src/appkit/actions/jettons#GET_JETTONS
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Jettons
+ */
 export const getJettons = async (appKit: AppKit, options: GetJettonsOptions = {}): Promise<GetJettonsReturnType> => {
     const selectedWallet = getSelectedWallet(appKit);
 
diff --git a/packages/appkit/src/actions/jettons/transfer-jetton.ts b/packages/appkit/src/actions/jettons/transfer-jetton.ts
index 01f17501d..de55d791a 100644
--- a/packages/appkit/src/actions/jettons/transfer-jetton.ts
+++ b/packages/appkit/src/actions/jettons/transfer-jetton.ts
@@ -6,21 +6,45 @@
  *
  */
 
-import type { SendTransactionResponse } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { SendTransactionResponse } from '../../types/transaction';
+import { sendTransaction } from '../transaction/send-transaction';
 import { createTransferJettonTransaction } from './create-transfer-jetton-transaction';
 import type { CreateTransferJettonTransactionParameters } from './create-transfer-jetton-transaction';
-import { sendTransaction } from '../transaction/send-transaction';
 
+/**
+ * Parameters accepted by {@link transferJetton} — same shape as {@link CreateTransferJettonTransactionParameters}.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type TransferJettonParameters = CreateTransferJettonTransactionParameters;
 
+/**
+ * Return type of {@link transferJetton}.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type TransferJettonReturnType = SendTransactionResponse;
 
 export type TransferJettonErrorType = Error;
 
 /**
- * Transfer Jetton - creates and sends a Jetton transfer transaction
+ * Build and send a jetton transfer from the selected wallet in one step (use {@link createTransferJettonTransaction} + {@link sendTransaction} if you need to inspect the transaction first); throws `Error('Wallet not connected')` if no wallet is currently selected.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link TransferJettonParameters} Jetton, recipient, amount, decimals and optional comment.
+ * @returns Wallet response carrying the BoC of the sent transaction.
+ *
+ * @sample docs/examples/src/appkit/actions/jettons#TRANSFER_JETTON
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Jettons
  */
 export const transferJetton = async (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/jettons/watch-jettons-by-address.ts b/packages/appkit/src/actions/jettons/watch-jettons-by-address.ts
index 0cd80d9c9..834542792 100644
--- a/packages/appkit/src/actions/jettons/watch-jettons-by-address.ts
+++ b/packages/appkit/src/actions/jettons/watch-jettons-by-address.ts
@@ -7,21 +7,50 @@
  */
 
 import { Address } from '@ton/core';
-import type { JettonUpdate, Network } from '@ton/walletkit';
 
 import type { AppKit } from '../../core/app-kit';
+import type { JettonUpdate } from '../../core/streaming';
+import type { Network } from '../../types/network';
+import type { UserFriendlyAddress } from '../../types/primitives';
 import { resolveNetwork } from '../../utils/network/resolve-network';
 
+/**
+ * Options for {@link watchJettonsByAddress}.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export interface WatchJettonsByAddressOptions {
-    address: string | Address;
+    /** Owner address — pass a {@link UserFriendlyAddress} string or an `Address` instance from `@ton/core`. */
+    address: UserFriendlyAddress | Address;
+    /** Callback fired on every jetton-balance update from the streaming provider. */
     onChange: (update: JettonUpdate) => void;
+    /** 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. */
     network?: Network;
 }
 
+/**
+ * Return type of {@link watchJettonsByAddress} — call to stop receiving updates.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type WatchJettonsByAddressReturnType = () => void;
 
 /**
- * Watch jetton updates by owner address.
+ * Subscribe to jetton-balance updates for an arbitrary owner address (use {@link watchJettons} for the selected wallet).
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link WatchJettonsByAddressOptions} Owner address, update callback and optional network override.
+ * @returns Unsubscribe function — call it to stop receiving updates.
+ *
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Jettons
  */
 export const watchJettonsByAddress = (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/jettons/watch-jettons.ts b/packages/appkit/src/actions/jettons/watch-jettons.ts
index db8eb3fd3..25b5f35ca 100644
--- a/packages/appkit/src/actions/jettons/watch-jettons.ts
+++ b/packages/appkit/src/actions/jettons/watch-jettons.ts
@@ -6,22 +6,48 @@
  *
  */
 
-import type { JettonUpdate, Network } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
 import { WALLETS_EVENTS } from '../../core/app-kit';
+import type { JettonUpdate } from '../../core/streaming';
+import type { Network } from '../../types/network';
 import { getSelectedWallet } from '../wallets/get-selected-wallet';
 import { watchJettonsByAddress } from './watch-jettons-by-address';
 
+/**
+ * Options for {@link watchJettons}.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export interface WatchJettonsOptions {
+    /** Callback fired on every jetton-balance update from the streaming provider. */
     onChange: (update: JettonUpdate) => void;
+    /** Network to watch on. Defaults to the selected wallet's network. */
     network?: Network;
 }
 
+/**
+ * Return type of {@link watchJettons} — call to stop receiving updates.
+ *
+ * @public
+ * @category Type
+ * @section Jettons
+ */
 export type WatchJettonsReturnType = () => void;
 
 /**
- * Watch jetton updates for the selected wallet.
+ * Subscribe to jetton-balance updates for the currently selected wallet, automatically rebinding when the user connects, switches, or disconnects (use {@link watchJettonsByAddress} for a fixed address).
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link WatchJettonsOptions} Update callback and optional network override.
+ * @returns Unsubscribe function — call it to stop receiving updates.
+ *
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Jettons
  */
 export const watchJettons = (appKit: AppKit, options: WatchJettonsOptions): WatchJettonsReturnType => {
     const { network, onChange } = options;
diff --git a/packages/appkit/src/actions/network/get-api-client.ts b/packages/appkit/src/actions/network/get-api-client.ts
index ff19b546e..1efde5465 100644
--- a/packages/appkit/src/actions/network/get-api-client.ts
+++ b/packages/appkit/src/actions/network/get-api-client.ts
@@ -10,12 +10,40 @@ import type { Network } from '../../types/network';
 import type { AppKit } from '../../core/app-kit';
 import type { ApiClient } from '../../core/network';
 
+/**
+ * Return type of {@link getApiClient}.
+ *
+ * @public
+ * @category Type
+ * @section Client
+ */
 export type GetApiClientReturnType = ApiClient;
 
-export type GetApiClientOptions = { network: Network };
+/**
+ * Options for {@link getApiClient}.
+ *
+ * @public
+ * @category Type
+ * @section Client
+ */
+export type GetApiClientOptions = {
+    /** Network whose configured {@link ApiClient} should be returned. */
+    network: Network;
+};
 
 /**
- * Get API client for a network
+ * Read the {@link ApiClient} configured for a specific {@link Network} — throws when the network has no client registered.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetApiClientOptions} Network to look up.
+ * @returns The configured {@link ApiClient} for the requested network.
+ *
+ * @sample docs/examples/src/appkit/actions/network#GET_API_CLIENT
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Client
  */
 export const getApiClient = (appKit: AppKit, options: GetApiClientOptions): GetApiClientReturnType => {
     return appKit.networkManager.getClient(options.network);
diff --git a/packages/appkit/src/actions/network/get-block-number.ts b/packages/appkit/src/actions/network/get-block-number.ts
index 3cad4201c..780f26d69 100644
--- a/packages/appkit/src/actions/network/get-block-number.ts
+++ b/packages/appkit/src/actions/network/get-block-number.ts
@@ -6,18 +6,43 @@
  *
  */
 
-import { Network } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import { Network } from '../../types/network';
 
+/**
+ * Options for {@link getBlockNumber}.
+ *
+ * @public
+ * @category Type
+ * @section Networks
+ */
 export interface GetBlockNumberOptions {
+    /** Network to query. Defaults to mainnet when omitted. */
     network?: Network;
 }
 
+/**
+ * Return type of {@link getBlockNumber}.
+ *
+ * @public
+ * @category Type
+ * @section Networks
+ */
 export type GetBlockNumberReturnType = number;
 
 /**
- * Get the latest block number (seqno) of the masterchain for the specified network (or mainnet by default).
+ * 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.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetBlockNumberOptions} Optional network override.
+ * @returns Current masterchain seqno as a number.
+ *
+ * @sample docs/examples/src/appkit/actions/network#GET_BLOCK_NUMBER
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Networks
  */
 export const getBlockNumber = async (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/network/get-default-network.ts b/packages/appkit/src/actions/network/get-default-network.ts
index 527e97659..eff9b2478 100644
--- a/packages/appkit/src/actions/network/get-default-network.ts
+++ b/packages/appkit/src/actions/network/get-default-network.ts
@@ -9,10 +9,26 @@
 import type { Network } from '../../types/network';
 import type { AppKit } from '../../core/app-kit';
 
+/**
+ * Return type of {@link getDefaultNetwork} — `undefined` when no default has been set (apps may operate on any registered network).
+ *
+ * @public
+ * @category Type
+ * @section Networks
+ */
 export type GetDefaultNetworkReturnType = Network | undefined;
 
 /**
- * Get the current default network
+ * Read AppKit's currently configured default network — the one connectors enforce on new wallet connections; `undefined` means any registered network is allowed.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @returns The default {@link Network}, or `undefined` if none is set.
+ *
+ * @sample docs/examples/src/appkit/actions/network#GET_DEFAULT_NETWORK
+ *
+ * @public
+ * @category Action
+ * @section Networks
  */
 export const getDefaultNetwork = (appKit: AppKit): GetDefaultNetworkReturnType => {
     return appKit.networkManager.getDefaultNetwork();
diff --git a/packages/appkit/src/actions/network/get-network.ts b/packages/appkit/src/actions/network/get-network.ts
index 3a47c4501..f965f24bf 100644
--- a/packages/appkit/src/actions/network/get-network.ts
+++ b/packages/appkit/src/actions/network/get-network.ts
@@ -10,10 +10,26 @@ import type { Network } from '../../types/network';
 import type { AppKit } from '../../core/app-kit';
 import { getSelectedWallet } from '../wallets/get-selected-wallet';
 
+/**
+ * Return type of {@link getNetwork} — `null` when no wallet is currently selected.
+ *
+ * @public
+ * @category Type
+ * @section Networks
+ */
 export type GetNetworkReturnType = Network | null;
 
 /**
- * Get the network of the currently selected wallet
+ * Read the {@link Network} the selected wallet is connected to, or `null` when no wallet is selected (use {@link getDefaultNetwork} for AppKit's configured default).
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @returns Network of the selected wallet, or `null` when none is selected.
+ *
+ * @sample docs/examples/src/appkit/actions/network#GET_NETWORK
+ *
+ * @public
+ * @category Action
+ * @section Networks
  */
 export const getNetwork = (appKit: AppKit): GetNetworkReturnType => {
     const wallet = getSelectedWallet(appKit);
diff --git a/packages/appkit/src/actions/network/get-networks.ts b/packages/appkit/src/actions/network/get-networks.ts
index 646e0f7df..e9251bb1b 100644
--- a/packages/appkit/src/actions/network/get-networks.ts
+++ b/packages/appkit/src/actions/network/get-networks.ts
@@ -9,10 +9,26 @@
 import type { Network } from '../../types/network';
 import type { AppKit } from '../../core/app-kit';
 
+/**
+ * Return type of {@link getNetworks}.
+ *
+ * @public
+ * @category Type
+ * @section Networks
+ */
 export type GetNetworksReturnType = Network[];
 
 /**
- * Get all configured networks
+ * List every network configured on this AppKit instance via {@link AppKitConfig}'s `networks`.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @returns Array of configured {@link Network}s.
+ *
+ * @sample docs/examples/src/appkit/actions/network#GET_NETWORKS
+ *
+ * @public
+ * @category Action
+ * @section Networks
  */
 export const getNetworks = (appKit: AppKit): GetNetworksReturnType => {
     return appKit.networkManager.getConfiguredNetworks();
diff --git a/packages/appkit/src/actions/network/has-streaming-provider.ts b/packages/appkit/src/actions/network/has-streaming-provider.ts
index 2144996cf..18e90831a 100644
--- a/packages/appkit/src/actions/network/has-streaming-provider.ts
+++ b/packages/appkit/src/actions/network/has-streaming-provider.ts
@@ -9,10 +9,27 @@
 import type { AppKit } from '../../core/app-kit/services/app-kit';
 import type { Network } from '../../types/network';
 
+/**
+ * Return type of {@link hasStreamingProvider}.
+ *
+ * @public
+ * @category Type
+ * @section Networks
+ */
 export type HasStreamingProviderReturnType = boolean;
 
 /**
- * Check if a streaming provider is registered for a specific network.
+ * Check whether a streaming provider is registered for a network — required by {@link watchBalance}, {@link watchJettons} and other live-update actions.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param network - {@link Network} Network to check.
+ * @returns `true` when a streaming provider is registered for that network.
+ *
+ * @sample docs/examples/src/appkit/actions/network#HAS_STREAMING_PROVIDER
+ *
+ * @public
+ * @category Action
+ * @section Networks
  */
 export const hasStreamingProvider = (appKit: AppKit, network: Network): HasStreamingProviderReturnType => {
     return appKit.streamingManager.hasProvider(network);
diff --git a/packages/appkit/src/actions/network/set-default-network.ts b/packages/appkit/src/actions/network/set-default-network.ts
index d46a4be63..3d255bf9f 100644
--- a/packages/appkit/src/actions/network/set-default-network.ts
+++ b/packages/appkit/src/actions/network/set-default-network.ts
@@ -9,16 +9,39 @@
 import type { Network } from '../../types/network';
 import type { AppKit } from '../../core/app-kit';
 
+/**
+ * Parameters accepted by {@link setDefaultNetwork}.
+ *
+ * @public
+ * @category Type
+ * @section Networks
+ */
 export type SetDefaultNetworkParameters = {
+    /** Network to enforce on new wallet connections; pass `undefined` to allow any registered network. */
     network: Network | undefined;
 };
 
+/**
+ * Return type of {@link setDefaultNetwork}.
+ *
+ * @public
+ * @category Type
+ * @section Networks
+ */
 export type SetDefaultNetworkReturnType = void;
 
 /**
- * Set the default network for wallet connections.
- * If set, connectors will enforce this network when connecting.
- * Set to `undefined` to allow any network.
+ * Set or clear the default network — connectors enforce it on new wallet connections; emits `NETWORKS_EVENTS.DEFAULT_CHANGED` so {@link watchDefaultNetwork} subscribers fire. Pass `undefined` to remove the constraint and allow any registered network.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link SetDefaultNetworkParameters} Network to enforce, or `undefined` to clear.
+ *
+ * @sample docs/examples/src/appkit/actions/network#SET_DEFAULT_NETWORK
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Networks
  */
 export const setDefaultNetwork = (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/network/watch-default-network.ts b/packages/appkit/src/actions/network/watch-default-network.ts
index 1365f3dd6..f7c66d77c 100644
--- a/packages/appkit/src/actions/network/watch-default-network.ts
+++ b/packages/appkit/src/actions/network/watch-default-network.ts
@@ -11,14 +11,40 @@ import type { AppKit } from '../../core/app-kit';
 import { getDefaultNetwork } from './get-default-network';
 import { NETWORKS_EVENTS } from '../../core/app-kit';
 
+/**
+ * Parameters accepted by {@link watchDefaultNetwork}.
+ *
+ * @public
+ * @category Type
+ * @section Networks
+ */
 export type WatchDefaultNetworkParameters = {
+    /** Callback fired whenever {@link setDefaultNetwork} updates the default — receives the new value (or `undefined` when cleared). */
     onChange: (network: Network | undefined) => void;
 };
 
+/**
+ * Return type of {@link watchDefaultNetwork} — call to stop receiving updates.
+ *
+ * @public
+ * @category Type
+ * @section Networks
+ */
 export type WatchDefaultNetworkReturnType = () => void;
 
 /**
- * Watch default network changes
+ * Subscribe to default-network changes — fires when {@link setDefaultNetwork} is called.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link WatchDefaultNetworkParameters} Update callback.
+ * @returns Unsubscribe function — call it to stop receiving updates.
+ *
+ * @sample docs/examples/src/appkit/actions/network#WATCH_DEFAULT_NETWORK
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Networks
  */
 export const watchDefaultNetwork = (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/network/watch-networks.ts b/packages/appkit/src/actions/network/watch-networks.ts
index 0c3562d50..19d2c2158 100644
--- a/packages/appkit/src/actions/network/watch-networks.ts
+++ b/packages/appkit/src/actions/network/watch-networks.ts
@@ -11,14 +11,40 @@ import { getNetworks } from './get-networks';
 import type { AppKit } from '../../core/app-kit';
 import { NETWORKS_EVENTS } from '../../core/app-kit';
 
+/**
+ * Parameters accepted by {@link watchNetworks}.
+ *
+ * @public
+ * @category Type
+ * @section Networks
+ */
 export type WatchNetworksParameters = {
+    /** Callback fired whenever the configured-networks list changes — receives the latest snapshot. */
     onChange: (networks: Network[]) => void;
 };
 
+/**
+ * Return type of {@link watchNetworks} — call to stop receiving updates.
+ *
+ * @public
+ * @category Type
+ * @section Networks
+ */
 export type WatchNetworksReturnType = () => void;
 
 /**
- * Watch configured networks
+ * Subscribe to changes of the configured-networks list — fires when AppKit's network manager registers or replaces a network's API client.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link WatchNetworksParameters} Update callback.
+ * @returns Unsubscribe function — call it to stop receiving updates.
+ *
+ * @sample docs/examples/src/appkit/actions/network#WATCH_NETWORKS
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Networks
  */
 export const watchNetworks = (appKit: AppKit, parameters: WatchNetworksParameters): WatchNetworksReturnType => {
     const { onChange } = parameters;
diff --git a/packages/appkit/src/actions/nft/create-transfer-nft-transaction.ts b/packages/appkit/src/actions/nft/create-transfer-nft-transaction.ts
index 15f5c4a68..4391d7c7f 100644
--- a/packages/appkit/src/actions/nft/create-transfer-nft-transaction.ts
+++ b/packages/appkit/src/actions/nft/create-transfer-nft-transaction.ts
@@ -6,23 +6,52 @@
  *
  */
 
-import { createNftTransferPayload, createTransferTransaction, DEFAULT_NFT_GAS_FEE } from '@ton/walletkit';
-
-import type { TransactionRequest } from '../../types/transaction';
 import type { AppKit } from '../../core/app-kit';
+import type { TransactionRequest } from '../../types/transaction';
+import type { UserFriendlyAddress } from '../../types/primitives';
+import { createNftTransferPayload, createTransferTransaction, DEFAULT_NFT_GAS_FEE } from '../../utils';
 import { getSelectedWallet } from '../wallets/get-selected-wallet';
 
+/**
+ * Parameters accepted by {@link createTransferNftTransaction} and {@link transferNft}.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export interface CreateTransferNftTransactionParameters {
-    nftAddress: string;
-    recipientAddress: string;
+    /** NFT contract address to transfer. */
+    nftAddress: UserFriendlyAddress;
+    /** New owner address. */
+    recipientAddress: UserFriendlyAddress;
+    /** Amount of TON to attach to the transfer for gas; defaults to AppKit's NFT gas-fee constant when omitted. */
     amount?: string;
+    /** Optional human-readable comment attached to the transfer. */
     comment?: string;
 }
 
+/**
+ * Return type of {@link createTransferNftTransaction}.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export type CreateTransferNftTransactionReturnType = TransactionRequest;
 
 /**
- * Create a NFT transfer transaction request
+ * Build an NFT transfer {@link 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.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link CreateTransferNftTransactionParameters} NFT, recipient, optional gas amount and comment.
+ * @returns Transaction request ready to pass to `sendTransaction`.
+ *
+ * @sample docs/examples/src/appkit/actions/nft#CREATE_TRANSFER_NFT_TRANSACTION
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section NFTs
  */
 export const createTransferNftTransaction = async (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/nft/get-nft.ts b/packages/appkit/src/actions/nft/get-nft.ts
index 62b588a2c..4c6c15f7a 100644
--- a/packages/appkit/src/actions/nft/get-nft.ts
+++ b/packages/appkit/src/actions/nft/get-nft.ts
@@ -7,20 +7,51 @@
  */
 
 import { Address } from '@ton/core';
-import { getNftFromClient } from '@ton/walletkit';
 
 import type { AppKit } from '../../core/app-kit';
-import { resolveNetwork } from '../../utils/network/resolve-network';
 import type { Network } from '../../types/network';
 import type { NFT } from '../../types/nft';
+import type { UserFriendlyAddress } from '../../types/primitives';
+import { getNftFromClient } from '../../utils';
+import { resolveNetwork } from '../../utils/network/resolve-network';
 
+/**
+ * Options for {@link getNft}.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export interface GetNftOptions {
-    address: string | Address;
+    /** NFT contract address — pass a {@link UserFriendlyAddress} string or an `Address` instance from `@ton/core`. */
+    address: UserFriendlyAddress | Address;
+    /** 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. */
     network?: Network;
 }
 
+/**
+ * Return type of {@link getNft} — `null` when the indexer has no record for that address.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export type GetNftReturnType = NFT | null;
 
+/**
+ * Fetch metadata and ownership for a single NFT by its contract address; returns `null` when the indexer has no record.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetNftOptions} NFT address and optional network override.
+ * @returns NFT data, or `null` if the indexer has no record.
+ *
+ * @sample docs/examples/src/appkit/actions/nft#GET_NFT
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section NFTs
+ */
 export const getNft = async (appKit: AppKit, options: GetNftOptions): Promise<GetNftReturnType> => {
     const { address, network } = options;
     const addressString = Address.isAddress(address) ? address.toString() : Address.parse(address).toString();
diff --git a/packages/appkit/src/actions/nft/get-nfts-by-address.ts b/packages/appkit/src/actions/nft/get-nfts-by-address.ts
index 278f3b472..6e284219c 100644
--- a/packages/appkit/src/actions/nft/get-nfts-by-address.ts
+++ b/packages/appkit/src/actions/nft/get-nfts-by-address.ts
@@ -7,22 +7,55 @@
  */
 
 import { Address } from '@ton/core';
-import type { NFTsResponse } from '@ton/walletkit';
-import { getNftsFromClient } from '@ton/walletkit';
 
 import type { AppKit } from '../../core/app-kit';
-import { resolveNetwork } from '../../utils/network/resolve-network';
 import type { Network } from '../../types/network';
+import type { NFTsResponse } from '../../types/nft';
+import type { UserFriendlyAddress } from '../../types/primitives';
+import { getNftsFromClient } from '../../utils';
+import { resolveNetwork } from '../../utils/network/resolve-network';
 
+/**
+ * Options for {@link getNftsByAddress}.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export interface GetNftsByAddressOptions {
-    address: string | Address;
+    /** Owner address — pass a {@link UserFriendlyAddress} string or an `Address` instance from `@ton/core`. */
+    address: UserFriendlyAddress | Address;
+    /** 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. */
     network?: Network;
+    /** Maximum number of NFTs to return. */
     limit?: number;
+    /** Number of NFTs to skip before returning results — used for pagination. */
     offset?: number;
 }
 
+/**
+ * Return type of {@link getNftsByAddress}.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export type GetNftsByAddressReturnType = NFTsResponse;
 
+/**
+ * List NFTs held by an arbitrary address — useful for inspecting wallets that aren't selected in AppKit (use {@link getNfts} for the selected wallet).
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetNftsByAddressOptions} Owner address, optional network override and pagination.
+ * @returns NFTs response with the owner's items.
+ *
+ * @sample docs/examples/src/appkit/actions/nft#GET_NFTS_BY_ADDRESS
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section NFTs
+ */
 export const getNftsByAddress = async (
     appKit: AppKit,
     options: GetNftsByAddressOptions,
diff --git a/packages/appkit/src/actions/nft/get-nfts.ts b/packages/appkit/src/actions/nft/get-nfts.ts
index f3e689864..369aaca84 100644
--- a/packages/appkit/src/actions/nft/get-nfts.ts
+++ b/packages/appkit/src/actions/nft/get-nfts.ts
@@ -6,21 +6,51 @@
  *
  */
 
-import type { NFTsResponse } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
-import { getNftsByAddress } from './get-nfts-by-address';
-import { getSelectedWallet } from '../wallets/get-selected-wallet';
 import type { Network } from '../../types/network';
+import type { NFTsResponse } from '../../types/nft';
+import { getSelectedWallet } from '../wallets/get-selected-wallet';
+import { getNftsByAddress } from './get-nfts-by-address';
 
+/**
+ * Options for {@link getNfts}.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export interface GetNftsOptions {
+    /** Network to read NFTs from. Defaults to the selected wallet's network. */
     network?: Network;
+    /** Maximum number of NFTs to return. */
     limit?: number;
+    /** Number of NFTs to skip before returning results — used for pagination. */
     offset?: number;
 }
 
+/**
+ * Return type of {@link getNfts} — `null` when no wallet is currently selected.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export type GetNftsReturnType = NFTsResponse | null;
 
+/**
+ * List NFTs held by the currently selected wallet, returning `null` when no wallet is selected (use {@link getNftsByAddress} for an arbitrary address).
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetNftsOptions} Optional network override and pagination.
+ * @returns NFTs response for the selected wallet, or `null` when none is selected.
+ *
+ * @sample docs/examples/src/appkit/actions/nft#GET_NFTS
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section NFTs
+ */
 export const getNfts = async (appKit: AppKit, options: GetNftsOptions = {}): Promise<GetNftsReturnType> => {
     const selectedWallet = getSelectedWallet(appKit);
 
diff --git a/packages/appkit/src/actions/nft/transfer-nft.ts b/packages/appkit/src/actions/nft/transfer-nft.ts
index 5fc71e5f4..17ea0d447 100644
--- a/packages/appkit/src/actions/nft/transfer-nft.ts
+++ b/packages/appkit/src/actions/nft/transfer-nft.ts
@@ -6,19 +6,43 @@
  *
  */
 
-import type { SendTransactionResponse } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { SendTransactionResponse } from '../../types/transaction';
+import { sendTransaction } from '../transaction/send-transaction';
 import { createTransferNftTransaction } from './create-transfer-nft-transaction';
 import type { CreateTransferNftTransactionParameters } from './create-transfer-nft-transaction';
-import { sendTransaction } from '../transaction/send-transaction';
 
+/**
+ * Parameters accepted by {@link transferNft} — same shape as {@link CreateTransferNftTransactionParameters}.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export type TransferNftParameters = CreateTransferNftTransactionParameters;
 
+/**
+ * Return type of {@link transferNft}.
+ *
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export type TransferNftReturnType = SendTransactionResponse;
 
 /**
- * Transfer NFT to another wallet
+ * Build and send an NFT transfer from the selected wallet in one step (use {@link createTransferNftTransaction} + {@link sendTransaction} if you need to inspect the transaction first); throws `Error('Wallet not connected')` if no wallet is currently selected.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link TransferNftParameters} NFT, recipient, optional gas amount and comment.
+ * @returns Wallet response carrying the BoC of the sent transaction.
+ *
+ * @sample docs/examples/src/appkit/actions/nft#TRANSFER_NFT
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section NFTs
  */
 export const transferNft = async (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/onramp/build-onramp-url.ts b/packages/appkit/src/actions/onramp/build-onramp-url.ts
index ec4afbd4d..88d3143e8 100644
--- a/packages/appkit/src/actions/onramp/build-onramp-url.ts
+++ b/packages/appkit/src/actions/onramp/build-onramp-url.ts
@@ -6,9 +6,8 @@
  *
  */
 
-import type { OnrampParams } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { OnrampParams } from '../../onramp';
 
 export type BuildOnrampUrlOptions<T = unknown> = OnrampParams<T> & {
     providerId?: string;
diff --git a/packages/appkit/src/actions/onramp/get-onramp-manager.ts b/packages/appkit/src/actions/onramp/get-onramp-manager.ts
index 2fafad61b..b0d6d6504 100644
--- a/packages/appkit/src/actions/onramp/get-onramp-manager.ts
+++ b/packages/appkit/src/actions/onramp/get-onramp-manager.ts
@@ -6,9 +6,8 @@
  *
  */
 
-import type { OnrampManager } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { OnrampManager } from '../../onramp';
 
 export type GetOnrampManagerReturnType = OnrampManager;
 
diff --git a/packages/appkit/src/actions/onramp/get-onramp-provider.ts b/packages/appkit/src/actions/onramp/get-onramp-provider.ts
index 948386573..c306d1608 100644
--- a/packages/appkit/src/actions/onramp/get-onramp-provider.ts
+++ b/packages/appkit/src/actions/onramp/get-onramp-provider.ts
@@ -6,9 +6,8 @@
  *
  */
 
-import type { OnrampProviderInterface } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { OnrampProviderInterface } from '../../onramp';
 
 export interface GetOnrampProviderOptions {
     id?: string;
diff --git a/packages/appkit/src/actions/onramp/get-onramp-providers.ts b/packages/appkit/src/actions/onramp/get-onramp-providers.ts
index 97440fc28..fc121f3ce 100644
--- a/packages/appkit/src/actions/onramp/get-onramp-providers.ts
+++ b/packages/appkit/src/actions/onramp/get-onramp-providers.ts
@@ -6,9 +6,8 @@
  *
  */
 
-import type { OnrampProviderInterface } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { OnrampProviderInterface } from '../../onramp';
 
 export type GetOnrampProvidersReturnType = OnrampProviderInterface[];
 
diff --git a/packages/appkit/src/actions/onramp/get-onramp-quote.ts b/packages/appkit/src/actions/onramp/get-onramp-quote.ts
index 7a6b46908..28d7274ca 100644
--- a/packages/appkit/src/actions/onramp/get-onramp-quote.ts
+++ b/packages/appkit/src/actions/onramp/get-onramp-quote.ts
@@ -6,10 +6,9 @@
  *
  */
 
-import type { OnrampQuote, OnrampQuoteParams } from '@ton/walletkit';
-
-import { resolveNetwork } from '../../utils';
 import type { AppKit } from '../../core/app-kit';
+import type { OnrampQuote, OnrampQuoteParams } from '../../onramp';
+import { resolveNetwork } from '../../utils';
 
 export type GetOnrampQuoteOptions<T = unknown> = OnrampQuoteParams<T> & {
     providerId?: string;
diff --git a/packages/appkit/src/actions/onramp/watch-onramp-providers.ts b/packages/appkit/src/actions/onramp/watch-onramp-providers.ts
index a14d12682..ac0fef00b 100644
--- a/packages/appkit/src/actions/onramp/watch-onramp-providers.ts
+++ b/packages/appkit/src/actions/onramp/watch-onramp-providers.ts
@@ -15,7 +15,7 @@ export interface WatchOnrampProvidersParameters {
 export type WatchOnrampProvidersReturnType = () => void;
 
 /**
- * Watch for new onramp providers registration
+ * Subscribe to onramp provider lifecycle — fires `onChange` whenever a new provider is registered or the default onramp provider switches.
  */
 export const watchOnrampProviders = (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/providers/register-provider.ts b/packages/appkit/src/actions/providers/register-provider.ts
index 341c9d333..b4328a477 100644
--- a/packages/appkit/src/actions/providers/register-provider.ts
+++ b/packages/appkit/src/actions/providers/register-provider.ts
@@ -6,14 +6,29 @@
  *
  */
 
-import type { ProviderInput } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { ProviderInput } from '../../types/provider';
 
+/**
+ * Provider instance or factory accepted by {@link registerProvider} — same shape used in {@link AppKitConfig}'s `providers`. AppKit dispatches it to the right manager based on `provider.type` (`'swap'`, `'staking'`, `'onramp'`, `'crypto-onramp'`).
+ *
+ * @public
+ * @category Type
+ * @section DeFi
+ */
 export type RegisterProviderOptions = ProviderInput;
 
 /**
- * Register provider
+ * Register a DeFi / onramp provider at runtime — equivalent to passing it via {@link AppKitConfig}'s `providers` at construction, but available after AppKit is up. AppKit emits `provider:registered`, picked up by domain-specific subscribers like {@link watchSwapProviders} and {@link watchCryptoOnrampProviders}.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param provider - {@link RegisterProviderOptions} Provider instance or factory to register.
+ *
+ * @sample docs/examples/src/appkit/actions/providers#REGISTER_PROVIDER
+ *
+ * @public
+ * @category Action
+ * @section DeFi
  */
 export const registerProvider = (appKit: AppKit, provider: RegisterProviderOptions): void => {
     appKit.registerProvider(provider);
diff --git a/packages/appkit/src/actions/signing/sign-binary.ts b/packages/appkit/src/actions/signing/sign-binary.ts
index 8618e84bc..fa859c83e 100644
--- a/packages/appkit/src/actions/signing/sign-binary.ts
+++ b/packages/appkit/src/actions/signing/sign-binary.ts
@@ -13,23 +13,42 @@ import { getSelectedWallet } from '../wallets/get-selected-wallet';
 import type { Base64String } from '../../types/primitives';
 import { getDefaultNetwork } from '../network/get-default-network';
 
+/**
+ * Parameters accepted by {@link signBinary}.
+ *
+ * @public
+ * @category Type
+ * @section Signing
+ */
 export interface SignBinaryParameters {
-    /** Binary data to sign (base64 encoded) */
+    /** Binary blob the user is asked to sign, encoded as Base64. */
     bytes: Base64String;
-    /** Optional network (mainnet/testnet) */
+    /** Network to issue the sign request against. Defaults to AppKit's configured default network; when none is set, the wallet falls back to its current network. */
     network?: Network;
 }
 
+/**
+ * Return type of {@link signBinary}.
+ *
+ * @public
+ * @category Type
+ * @section Signing
+ */
 export type SignBinaryReturnType = SignDataResponse;
 
 /**
- * Sign binary data with the connected wallet.
+ * Ask the selected wallet to sign a binary blob; throws `Error('Wallet not connected')` if no wallet is currently selected.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link SignBinaryParameters} Binary content and optional network override.
+ * @returns Signature and signed payload, as returned by the wallet.
+ *
+ * @sample docs/examples/src/appkit/actions/signing#SIGN_BINARY
+ * @expand parameters
  *
- * @example
- * ```ts
- * const result = await signBinary(appKit, { bytes: btoa("binary data") });
- * console.log(result.signature);
- * ```
+ * @public
+ * @category Action
+ * @section Signing
  */
 export const signBinary = async (appKit: AppKit, parameters: SignBinaryParameters): Promise<SignBinaryReturnType> => {
     const wallet = getSelectedWallet(appKit);
diff --git a/packages/appkit/src/actions/signing/sign-cell.ts b/packages/appkit/src/actions/signing/sign-cell.ts
index ac3d833cc..a7e80f79f 100644
--- a/packages/appkit/src/actions/signing/sign-cell.ts
+++ b/packages/appkit/src/actions/signing/sign-cell.ts
@@ -13,29 +13,44 @@ import { getSelectedWallet } from '../wallets/get-selected-wallet';
 import type { Base64String } from '../../types/primitives';
 import { getDefaultNetwork } from '../network/get-default-network';
 
+/**
+ * Parameters accepted by {@link signCell}.
+ *
+ * @public
+ * @category Type
+ * @section Signing
+ */
 export interface SignCellParameters {
-    /** Base64 encoded Bag of Cells */
+    /** TON cell content encoded as Base64 (BoC). */
     cell: Base64String;
-    /** TL-B schema for the cell structure */
+    /** TL-B-style schema describing the cell layout so the wallet can render the payload to the user. */
     schema: string;
-    /** Optional network (mainnet/testnet) */
+    /** Network to issue the sign request against. Defaults to AppKit's configured default network; when none is set, the wallet falls back to its current network. */
     network?: Network;
 }
 
+/**
+ * Return type of {@link signCell}.
+ *
+ * @public
+ * @category Type
+ * @section Signing
+ */
 export type SignCellReturnType = SignDataResponse;
 
 /**
- * Sign a TON Cell with the connected wallet.
- * Used for on-chain signature verification.
+ * 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.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link SignCellParameters} Cell content, TL-B schema and optional network override.
+ * @returns Signature and signed payload, as returned by the wallet.
+ *
+ * @sample docs/examples/src/appkit/actions/signing#SIGN_CELL
+ * @expand parameters
  *
- * @example
- * ```ts
- * const result = await signCell(appKit, {
- *   cell: bocBase64,
- *   schema: "transfer#abc123 amount:uint64 = Transfer"
- * });
- * console.log(result.signature);
- * ```
+ * @public
+ * @category Action
+ * @section Signing
  */
 export const signCell = async (appKit: AppKit, parameters: SignCellParameters): Promise<SignCellReturnType> => {
     const wallet = getSelectedWallet(appKit);
diff --git a/packages/appkit/src/actions/signing/sign-text.ts b/packages/appkit/src/actions/signing/sign-text.ts
index d9fbb621b..c229a6b0d 100644
--- a/packages/appkit/src/actions/signing/sign-text.ts
+++ b/packages/appkit/src/actions/signing/sign-text.ts
@@ -12,23 +12,42 @@ import type { SignDataResponse } from '../../types/signing';
 import { getSelectedWallet } from '../wallets/get-selected-wallet';
 import { getDefaultNetwork } from '../network/get-default-network';
 
+/**
+ * Parameters accepted by {@link signText}.
+ *
+ * @public
+ * @category Type
+ * @section Signing
+ */
 export interface SignTextParameters {
-    /** Text message to sign */
+    /** UTF-8 text the user is asked to sign. */
     text: string;
-    /** Optional network (mainnet/testnet) */
+    /** Network to issue the sign request against. Defaults to AppKit's configured default network; when none is set, the wallet falls back to its current network. */
     network?: Network;
 }
 
+/**
+ * Return type of {@link signText}.
+ *
+ * @public
+ * @category Type
+ * @section Signing
+ */
 export type SignTextReturnType = SignDataResponse;
 
 /**
- * Sign a text message with the connected wallet.
+ * Ask the selected wallet to sign a plain text message; throws `Error('Wallet not connected')` if no wallet is currently selected.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link SignTextParameters} Text to sign and optional network override.
+ * @returns Signature and signed payload, as returned by the wallet.
+ *
+ * @sample docs/examples/src/appkit/actions/signing#SIGN_TEXT
+ * @expand parameters
  *
- * @example
- * ```ts
- * const result = await signText(appKit, { text: "Hello World" });
- * console.log(result.signature);
- * ```
+ * @public
+ * @category Action
+ * @section Signing
  */
 export const signText = async (appKit: AppKit, parameters: SignTextParameters): Promise<SignTextReturnType> => {
     const wallet = getSelectedWallet(appKit);
diff --git a/packages/appkit/src/actions/staking/build-stake-transaction.ts b/packages/appkit/src/actions/staking/build-stake-transaction.ts
index 6cadb0f48..652d5a1c6 100644
--- a/packages/appkit/src/actions/staking/build-stake-transaction.ts
+++ b/packages/appkit/src/actions/staking/build-stake-transaction.ts
@@ -6,19 +6,44 @@
  *
  */
 
-import type { StakeParams } from '@ton/walletkit';
-
-import type { TransactionRequest } from '../../types/transaction';
 import type { AppKit } from '../../core/app-kit';
+import type { StakeParams } from '../../staking';
+import type { TransactionRequest } from '../../types/transaction';
 
+/**
+ * Options for {@link buildStakeTransaction} — extends {@link StakeParams} with an optional provider override.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type BuildStakeTransactionOptions = StakeParams & {
+    /** Provider to stake/unstake through; defaults to the registered default staking provider. */
     providerId?: string;
 };
 
+/**
+ * Return type of {@link buildStakeTransaction}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type BuildStakeTransactionReturnType = Promise<TransactionRequest>;
 
 /**
- * Build stake transaction
+ * Build a {@link TransactionRequest} that executes a stake or unstake previously quoted by {@link getStakingQuote} — returns it without sending so the UI can inspect or batch before signing.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link BuildStakeTransactionOptions} Quote and optional provider override.
+ * @returns Transaction request ready to pass to `sendTransaction`.
+ *
+ * @sample docs/examples/src/appkit/actions/staking#BUILD_STAKE_TRANSACTION
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Staking
  */
 export const buildStakeTransaction = async (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/staking/get-staked-balance.ts b/packages/appkit/src/actions/staking/get-staked-balance.ts
index f975dc764..ce6273919 100644
--- a/packages/appkit/src/actions/staking/get-staked-balance.ts
+++ b/packages/appkit/src/actions/staking/get-staked-balance.ts
@@ -6,21 +6,50 @@
  *
  */
 
-import type { StakingBalance, UserFriendlyAddress, Network } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { StakingBalance } from '../../staking';
+import type { Network } from '../../types/network';
+import type { UserFriendlyAddress } from '../../types/primitives';
 import { resolveNetwork } from '../../utils';
 
+/**
+ * Options for {@link getStakedBalance}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type GetStakedBalanceOptions = {
+    /** Owner whose staked balance should be read. */
     userAddress: UserFriendlyAddress;
+    /** 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. */
     network?: Network;
+    /** Provider to query; defaults to the registered default staking provider. */
     providerId?: string;
 };
 
+/**
+ * Return type of {@link getStakedBalance}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type GetStakedBalanceReturnType = Promise<StakingBalance>;
 
 /**
- * Get staked balance
+ * Read a user's staked balance from a staking provider — total staked plus, depending on the provider, any instant-unstake balance available right now.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetStakedBalanceOptions} Owner address and optional network/provider override.
+ * @returns Staked-balance breakdown ({@link StakingBalance}) for the user on the resolved network/provider.
+ *
+ * @sample docs/examples/src/appkit/actions/staking#GET_STAKED_BALANCE
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Staking
  */
 export const getStakedBalance = async (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/staking/get-staking-manager.ts b/packages/appkit/src/actions/staking/get-staking-manager.ts
index d5243498f..e23c0ca96 100644
--- a/packages/appkit/src/actions/staking/get-staking-manager.ts
+++ b/packages/appkit/src/actions/staking/get-staking-manager.ts
@@ -6,14 +6,27 @@
  *
  */
 
-import type { StakingManager } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { StakingManager } from '../../staking';
 
+/**
+ * Return type of {@link getStakingManager}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type GetStakingManagerReturnType = StakingManager;
 
 /**
- * Get staking manager instance
+ * Read AppKit's {@link StakingManager} — the runtime that owns registered staking providers and dispatches quote/stake/balance calls. Apps usually use the higher-level actions ({@link getStakingQuote}, {@link buildStakeTransaction}, {@link getStakedBalance}) instead of touching the manager directly.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @returns The {@link StakingManager} bound to this AppKit instance.
+ *
+ * @public
+ * @category Action
+ * @section Staking
  */
 export const getStakingManager = (appKit: AppKit): GetStakingManagerReturnType => {
     return appKit.stakingManager;
diff --git a/packages/appkit/src/actions/staking/get-staking-provider-info.ts b/packages/appkit/src/actions/staking/get-staking-provider-info.ts
index eab2a1b7b..70a6167d1 100644
--- a/packages/appkit/src/actions/staking/get-staking-provider-info.ts
+++ b/packages/appkit/src/actions/staking/get-staking-provider-info.ts
@@ -6,20 +6,47 @@
  *
  */
 
-import type { StakingProviderInfo, Network } from '@ton/walletkit';
-
-import { resolveNetwork } from '../../utils';
 import type { AppKit } from '../../core/app-kit';
+import type { StakingProviderInfo } from '../../staking';
+import type { Network } from '../../types/network';
+import { resolveNetwork } from '../../utils';
 
+/**
+ * Options for {@link getStakingProviderInfo}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type GetStakingProviderInfoOptions = {
+    /** 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. */
     network?: Network;
+    /** Provider to query; defaults to the registered default staking provider. */
     providerId?: string;
 };
 
+/**
+ * Return type of {@link getStakingProviderInfo}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type GetStakingProviderInfoReturnType = Promise<StakingProviderInfo>;
 
 /**
- * Get staking provider info
+ * 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 {@link getStakingProviderMetadata} for static metadata (display name, stake/receive tokens, supported unstake modes).
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetStakingProviderInfoOptions} Optional network and provider override.
+ * @returns Live staking-provider info for the resolved network.
+ *
+ * @sample docs/examples/src/appkit/actions/staking#GET_STAKING_PROVIDER_INFO
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Staking
  */
 export const getStakingProviderInfo = async (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/staking/get-staking-provider-metadata.ts b/packages/appkit/src/actions/staking/get-staking-provider-metadata.ts
index 6c709ead1..4aecc6ec6 100644
--- a/packages/appkit/src/actions/staking/get-staking-provider-metadata.ts
+++ b/packages/appkit/src/actions/staking/get-staking-provider-metadata.ts
@@ -6,20 +6,47 @@
  *
  */
 
-import type { StakingProviderMetadata, Network } from '@ton/walletkit';
-
-import { resolveNetwork } from '../../utils';
 import type { AppKit } from '../../core/app-kit';
+import type { StakingProviderMetadata } from '../../staking';
+import type { Network } from '../../types/network';
+import { resolveNetwork } from '../../utils';
 
+/**
+ * Options for {@link getStakingProviderMetadata}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type GetStakingProviderMetadataOptions = {
+    /** 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. */
     network?: Network;
+    /** Provider to query; defaults to the registered default staking provider. */
     providerId?: string;
 };
 
+/**
+ * Return type of {@link getStakingProviderMetadata}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type GetStakingProviderMetadataReturnType = StakingProviderMetadata;
 
 /**
- * Get staking provider static metadata
+ * Read static metadata for a staking provider — display name, stake/receive tokens, supported unstake modes, contract address. Use {@link getStakingProviderInfo} for live values (APY, instant-unstake liquidity, exchange rate).
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetStakingProviderMetadataOptions} Optional network and provider override.
+ * @returns Static {@link StakingProviderMetadata} for the resolved provider.
+ *
+ * @sample docs/examples/src/appkit/actions/staking#GET_STAKING_PROVIDER_METADATA
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Staking
  */
 export const getStakingProviderMetadata = (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/staking/get-staking-provider.ts b/packages/appkit/src/actions/staking/get-staking-provider.ts
index 3b7c168b6..b4839b981 100644
--- a/packages/appkit/src/actions/staking/get-staking-provider.ts
+++ b/packages/appkit/src/actions/staking/get-staking-provider.ts
@@ -6,21 +6,42 @@
  *
  */
 
-import type { StakingProviderInterface } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { StakingProviderInterface } from '../../staking';
 
+/**
+ * Options for {@link getStakingProvider}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type GetStakingProviderOptions = {
-    /**
-     * Provider ID to get. If not provided, returns default provider.
-     */
+    /** Provider ID to look up; when omitted, returns the registered default staking provider. */
     id?: string;
 };
 
+/**
+ * Return type of {@link getStakingProvider}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type GetStakingProviderReturnType = StakingProviderInterface;
 
 /**
- * Get staking provider instance
+ * 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.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetStakingProviderOptions} Optional provider id.
+ * @returns The matching staking provider instance.
+ *
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Staking
  */
 export const getStakingProvider = (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/staking/get-staking-providers.ts b/packages/appkit/src/actions/staking/get-staking-providers.ts
index 2d0c4dbc4..33683a491 100644
--- a/packages/appkit/src/actions/staking/get-staking-providers.ts
+++ b/packages/appkit/src/actions/staking/get-staking-providers.ts
@@ -6,14 +6,29 @@
  *
  */
 
-import type { StakingProviderInterface } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { StakingProviderInterface } from '../../staking';
 
+/**
+ * Return type of {@link getStakingProviders}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type GetStakingProvidersReturnType = StakingProviderInterface[];
 
 /**
- * Get all registered staking providers.
+ * List every staking provider registered on this AppKit instance — both those passed via {@link AppKitConfig}'s `providers` and those added later through {@link registerProvider}.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @returns Array of registered staking providers.
+ *
+ * @sample docs/examples/src/appkit/actions/staking#GET_STAKING_PROVIDERS
+ *
+ * @public
+ * @category Action
+ * @section Staking
  */
 export const getStakingProviders = (appKit: AppKit): GetStakingProvidersReturnType => {
     return appKit.stakingManager.getProviders();
diff --git a/packages/appkit/src/actions/staking/get-staking-quote.ts b/packages/appkit/src/actions/staking/get-staking-quote.ts
index fa683764e..e9c638b39 100644
--- a/packages/appkit/src/actions/staking/get-staking-quote.ts
+++ b/packages/appkit/src/actions/staking/get-staking-quote.ts
@@ -6,19 +6,44 @@
  *
  */
 
-import type { StakingQuote, StakingQuoteParams } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { StakingQuote, StakingQuoteParams } from '../../staking';
 import { resolveNetwork } from '../../utils';
 
+/**
+ * Options for {@link getStakingQuote} — extends {@link StakingQuoteParams} with an optional provider override.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type GetStakingQuoteOptions = StakingQuoteParams & {
+    /** Provider to quote against; defaults to the registered default staking provider. */
     providerId?: string;
 };
 
+/**
+ * Return type of {@link getStakingQuote}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type GetStakingQuoteReturnType = Promise<StakingQuote>;
 
 /**
- * Get staking quote
+ * Quote a stake or unstake — given the amount, direction and target asset, returns the rate, expected output and provider metadata needed to call {@link buildStakeTransaction}.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetStakingQuoteOptions} Quote parameters and optional provider override.
+ * @returns Quote with pricing details and provider metadata.
+ *
+ * @sample docs/examples/src/appkit/actions/staking#GET_STAKING_QUOTE
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Staking
  */
 export const getStakingQuote = async (appKit: AppKit, options: GetStakingQuoteOptions): GetStakingQuoteReturnType => {
     const optionsWithNetwork = {
diff --git a/packages/appkit/src/actions/staking/set-default-staking-provider.ts b/packages/appkit/src/actions/staking/set-default-staking-provider.ts
index 58822fbb5..c02402c1e 100644
--- a/packages/appkit/src/actions/staking/set-default-staking-provider.ts
+++ b/packages/appkit/src/actions/staking/set-default-staking-provider.ts
@@ -8,15 +8,38 @@
 
 import type { AppKit } from '../../core/app-kit';
 
+/**
+ * Parameters accepted by {@link setDefaultStakingProvider}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export interface SetDefaultStakingProviderParameters {
+    /** ID of the provider to make default — must already be registered. */
     providerId: string;
 }
 
+/**
+ * Return type of {@link setDefaultStakingProvider}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type SetDefaultStakingProviderReturnType = void;
 
 /**
- * Set the default staking provider.
- * Subsequent quote and stake-transaction calls will use this provider when none is specified.
+ * Set the default staking provider — subsequent {@link getStakingQuote} and {@link buildStakeTransaction} calls without an explicit `providerId` route through it. Emits `provider:default-changed`, picked up by {@link watchStakingProviders}.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link SetDefaultStakingProviderParameters} ID of the provider to make default.
+ *
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Staking
  */
 export const setDefaultStakingProvider = (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/staking/watch-staking-providers.ts b/packages/appkit/src/actions/staking/watch-staking-providers.ts
index 5497bf86e..56d6720be 100644
--- a/packages/appkit/src/actions/staking/watch-staking-providers.ts
+++ b/packages/appkit/src/actions/staking/watch-staking-providers.ts
@@ -8,14 +8,39 @@
 
 import type { AppKit } from '../../core/app-kit';
 
+/**
+ * Parameters accepted by {@link watchStakingProviders}.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export interface WatchStakingProvidersParameters {
+    /** Callback fired whenever a staking provider is registered or the default staking provider changes. */
     onChange: () => void;
 }
 
+/**
+ * Return type of {@link watchStakingProviders} — call to stop receiving updates.
+ *
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type WatchStakingProvidersReturnType = () => void;
 
 /**
- * Watch for staking providers registration and default provider changes
+ * Subscribe to staking provider lifecycle — fires `onChange` whenever a new provider is registered or the default staking provider switches.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link WatchStakingProvidersParameters} Update callback.
+ * @returns Unsubscribe function — call it to stop receiving updates.
+ *
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Staking
  */
 export const watchStakingProviders = (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/swap/build-swap-transaction.ts b/packages/appkit/src/actions/swap/build-swap-transaction.ts
index 5408fb643..8a1c5cd7e 100644
--- a/packages/appkit/src/actions/swap/build-swap-transaction.ts
+++ b/packages/appkit/src/actions/swap/build-swap-transaction.ts
@@ -10,12 +10,37 @@ import type { SwapParams } from '../../swap';
 import type { TransactionRequest } from '../../types/transaction';
 import type { AppKit } from '../../core/app-kit';
 
+/**
+ * Options for {@link buildSwapTransaction} — same shape as {@link SwapParams}.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export type BuildSwapTransactionOptions<T = unknown> = SwapParams<T>;
 
+/**
+ * Return type of {@link buildSwapTransaction}.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export type BuildSwapTransactionReturnType = Promise<TransactionRequest>;
 
 /**
- * Build swap transaction
+ * Build a {@link TransactionRequest} that executes a swap previously quoted by {@link getSwapQuote} — returns it without sending so the UI can inspect or batch before signing.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link BuildSwapTransactionOptions} Quote and provider-specific options.
+ * @returns Transaction request ready to pass to `sendTransaction`.
+ *
+ * @sample docs/examples/src/appkit/actions/swap#BUILD_SWAP_TRANSACTION
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Swap
  */
 export const buildSwapTransaction = async <T = unknown>(
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/swap/get-swap-manager.ts b/packages/appkit/src/actions/swap/get-swap-manager.ts
index 191a0e563..a44e85285 100644
--- a/packages/appkit/src/actions/swap/get-swap-manager.ts
+++ b/packages/appkit/src/actions/swap/get-swap-manager.ts
@@ -6,14 +6,29 @@
  *
  */
 
-import type { SwapManager } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { SwapManager } from '../../swap';
 
+/**
+ * Return type of {@link getSwapManager}.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export type GetSwapManagerReturnType = SwapManager;
 
 /**
- * Get swap manager instance
+ * Read AppKit's {@link SwapManager} — the runtime that owns registered swap providers and dispatches quote/build calls. Apps usually use the higher-level actions ({@link getSwapQuote}, {@link buildSwapTransaction}) instead of touching the manager directly.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @returns The {@link SwapManager} bound to this AppKit instance.
+ *
+ * @sample docs/examples/src/appkit/actions/swap#GET_SWAP_MANAGER
+ *
+ * @public
+ * @category Action
+ * @section Swap
  */
 export const getSwapManager = (appKit: AppKit): GetSwapManagerReturnType => {
     return appKit.swapManager;
diff --git a/packages/appkit/src/actions/swap/get-swap-provider.ts b/packages/appkit/src/actions/swap/get-swap-provider.ts
index d302927c0..276cc8c91 100644
--- a/packages/appkit/src/actions/swap/get-swap-provider.ts
+++ b/packages/appkit/src/actions/swap/get-swap-provider.ts
@@ -6,16 +6,44 @@
  *
  */
 
-import type { SwapProviderInterface } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { SwapProviderInterface } from '../../swap';
 
+/**
+ * Options for {@link getSwapProvider}.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export interface GetSwapProviderOptions {
+    /** Provider ID to look up; when omitted, returns the registered default swap provider. */
     id?: string;
 }
 
+/**
+ * Return type of {@link getSwapProvider}.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export type GetSwapProviderReturnType = SwapProviderInterface;
 
+/**
+ * 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.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetSwapProviderOptions} Optional provider id.
+ * @returns The matching swap provider instance.
+ *
+ * @sample docs/examples/src/appkit/actions/swap#GET_SWAP_PROVIDER
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Swap
+ */
 export const getSwapProvider = (appKit: AppKit, options: GetSwapProviderOptions = {}): GetSwapProviderReturnType => {
     return appKit.swapManager.getProvider(options.id);
 };
diff --git a/packages/appkit/src/actions/swap/get-swap-providers.ts b/packages/appkit/src/actions/swap/get-swap-providers.ts
index 04bafa021..5b3e54e0c 100644
--- a/packages/appkit/src/actions/swap/get-swap-providers.ts
+++ b/packages/appkit/src/actions/swap/get-swap-providers.ts
@@ -6,14 +6,29 @@
  *
  */
 
-import type { SwapProviderInterface } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { SwapProviderInterface } from '../../swap';
 
+/**
+ * Return type of {@link getSwapProviders}.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export type GetSwapProvidersReturnType = SwapProviderInterface[];
 
 /**
- * Get all registered swap providers.
+ * List every swap provider registered on this AppKit instance — both those passed via {@link AppKitConfig}'s `providers` and those added later through {@link registerProvider}.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @returns Array of registered swap providers.
+ *
+ * @sample docs/examples/src/appkit/actions/swap#GET_SWAP_PROVIDERS
+ *
+ * @public
+ * @category Action
+ * @section Swap
  */
 export const getSwapProviders = (appKit: AppKit): GetSwapProvidersReturnType => {
     return appKit.swapManager.getProviders();
diff --git a/packages/appkit/src/actions/swap/get-swap-quote.ts b/packages/appkit/src/actions/swap/get-swap-quote.ts
index 1d716a88b..b5bae7807 100644
--- a/packages/appkit/src/actions/swap/get-swap-quote.ts
+++ b/packages/appkit/src/actions/swap/get-swap-quote.ts
@@ -6,19 +6,44 @@
  *
  */
 
-import type { SwapQuote, SwapQuoteParams } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { SwapQuote, SwapQuoteParams } from '../../swap';
 import { resolveNetwork } from '../../utils';
 
+/**
+ * Options for {@link getSwapQuote} — extends {@link SwapQuoteParams} with an optional provider override.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export type GetSwapQuoteOptions<T = unknown> = SwapQuoteParams<T> & {
+    /** Provider to quote against; defaults to the registered default swap provider. */
     providerId?: string;
 };
 
+/**
+ * Return type of {@link getSwapQuote}.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export type GetSwapQuoteReturnType = Promise<SwapQuote>;
 
 /**
- * Get swap quote
+ * Quote a swap — given source/target tokens and an amount, returns the rate, expected output and provider metadata needed to call {@link buildSwapTransaction}.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link GetSwapQuoteOptions} Source and target tokens, amount, optional network and provider override.
+ * @returns Quote with pricing details and the provider metadata required to build a transaction.
+ *
+ * @sample docs/examples/src/appkit/actions/swap#GET_SWAP_QUOTE
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Swap
  */
 export const getSwapQuote = async <T = unknown>(
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/swap/set-default-swap-provider.ts b/packages/appkit/src/actions/swap/set-default-swap-provider.ts
index 583f0078a..554a71abd 100644
--- a/packages/appkit/src/actions/swap/set-default-swap-provider.ts
+++ b/packages/appkit/src/actions/swap/set-default-swap-provider.ts
@@ -8,15 +8,39 @@
 
 import type { AppKit } from '../../core/app-kit';
 
+/**
+ * Parameters accepted by {@link setDefaultSwapProvider}.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export interface SetDefaultSwapProviderParameters {
+    /** ID of the provider to make default — must already be registered. */
     providerId: string;
 }
 
+/**
+ * Return type of {@link setDefaultSwapProvider}.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export type SetDefaultSwapProviderReturnType = void;
 
 /**
- * Set the default swap provider.
- * Subsequent quote and swap-transaction calls will use this provider when none is specified.
+ * Set the default swap provider — subsequent {@link getSwapQuote} and {@link buildSwapTransaction} calls without an explicit `providerId` route through it. Emits `provider:default-changed`, picked up by {@link watchSwapProviders}.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link SetDefaultSwapProviderParameters} ID of the provider to make default.
+ *
+ * @sample docs/examples/src/appkit/actions/swap#SET_DEFAULT_SWAP_PROVIDER
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Swap
  */
 export const setDefaultSwapProvider = (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/swap/watch-swap-providers.ts b/packages/appkit/src/actions/swap/watch-swap-providers.ts
index c29094be9..9d6237ea5 100644
--- a/packages/appkit/src/actions/swap/watch-swap-providers.ts
+++ b/packages/appkit/src/actions/swap/watch-swap-providers.ts
@@ -8,14 +8,40 @@
 
 import type { AppKit } from '../../core/app-kit';
 
+/**
+ * Parameters accepted by {@link watchSwapProviders}.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export interface WatchSwapProvidersParameters {
+    /** Callback fired whenever a swap provider is registered or the default swap provider changes. */
     onChange: () => void;
 }
 
+/**
+ * Return type of {@link watchSwapProviders} — call to stop receiving updates.
+ *
+ * @public
+ * @category Type
+ * @section Swap
+ */
 export type WatchSwapProvidersReturnType = () => void;
 
 /**
- * Watch for new swap providers registration
+ * Subscribe to swap provider lifecycle — fires `onChange` whenever a new provider is registered or the default swap provider switches.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link WatchSwapProvidersParameters} Update callback.
+ * @returns Unsubscribe function — call it to stop receiving updates.
+ *
+ * @sample docs/examples/src/appkit/actions/swap#WATCH_SWAP_PROVIDERS
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Swap
  */
 export const watchSwapProviders = (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/transaction/create-transfer-ton-transaction.ts b/packages/appkit/src/actions/transaction/create-transfer-ton-transaction.ts
index bf84ad836..584e3d52c 100644
--- a/packages/appkit/src/actions/transaction/create-transfer-ton-transaction.ts
+++ b/packages/appkit/src/actions/transaction/create-transfer-ton-transaction.ts
@@ -6,29 +6,54 @@
  *
  */
 
-import { createCommentPayloadBase64, parseUnits } from '@ton/walletkit';
-
-import type { TransactionRequest, TransactionRequestMessage } from '../../types/transaction';
 import type { AppKit } from '../../core/app-kit';
+import type { TransactionRequest, TransactionRequestMessage } from '../../types/transaction';
+import type { Base64String, UserFriendlyAddress } from '../../types/primitives';
+import { createCommentPayloadBase64, parseUnits } from '../../utils';
 import { getSelectedWallet } from '../wallets/get-selected-wallet';
 
+/**
+ * Parameters accepted by {@link createTransferTonTransaction} and {@link transferTon}.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export interface CreateTransferTonTransactionParameters {
-    /** Recipient address */
-    recipientAddress: string;
-    /** Amount in TONs */
+    /** Recipient address. */
+    recipientAddress: UserFriendlyAddress;
+    /** Amount in TON as a human-readable decimal string (e.g., `"1.5"`); converted to nano-TON internally. */
     amount: string;
-    /** Human-readable text comment (will be converted to payload) */
+    /** Human-readable text comment; converted to a Base64 payload when no `payload` is supplied. */
     comment?: string;
-    /** Message payload data encoded in Base64 (overrides comment if provided) */
-    payload?: string;
-    /** Initial state for deploying a new contract, encoded in Base64 */
-    stateInit?: string;
+    /** Raw Base64 message payload — wins over `comment` when both are set. */
+    payload?: Base64String;
+    /** Initial state for deploying a new contract, encoded as Base64. */
+    stateInit?: Base64String;
 }
 
+/**
+ * Return type of {@link createTransferTonTransaction}.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export type CreateTransferTonTransactionReturnType = TransactionRequest;
 
 /**
- * Create a TON transfer transaction request
+ * Build a TON transfer {@link 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.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link CreateTransferTonTransactionParameters} Recipient, amount and optional payload/comment/stateInit.
+ * @returns Transaction request ready to pass to `sendTransaction`.
+ *
+ * @sample docs/examples/src/appkit/actions/transaction#CREATE_TRANSFER_TON_TRANSACTION
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Transactions
  */
 export const createTransferTonTransaction = (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/transaction/get-transaction-status.ts b/packages/appkit/src/actions/transaction/get-transaction-status.ts
index dd250b7a4..fbfffb296 100644
--- a/packages/appkit/src/actions/transaction/get-transaction-status.ts
+++ b/packages/appkit/src/actions/transaction/get-transaction-status.ts
@@ -6,50 +6,56 @@
  *
  */
 
-import type { TransactionStatusResponse } from '@ton/walletkit';
-import { getTransactionStatus as walletKitGetTransactionStatus } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
 import type { Network } from '../../types/network';
+import type { TransactionStatusResponse } from '../../types/transaction';
+import { getTransactionStatusFromClient as walletKitGetTransactionStatus } from '../../utils';
 import { resolveNetwork } from '../../utils/network/resolve-network';
 
+/**
+ * Parameters accepted by {@link getTransactionStatus} — must carry exactly one of `boc` or `normalizedHash`, plus an optional network override.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export type GetTransactionStatusParameters = {
-    /** Network to check the transaction on */
+    /** Network to check the transaction 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. */
     network?: Network;
 } & (
     | {
-          /** BOC of the sent transaction (base64) */
+          /** Base64-encoded BoC of the sent transaction (returned by {@link sendTransaction}). */
           boc: string;
-          /** Hash of the sent transaction (hex) */
           normalizedHash?: never;
       }
     | {
-          /** BOC of the sent transaction (base64) */
           boc?: never;
-          /** Normalized Hash of the external-in transaction (hex) */
+          /** Hex-encoded normalized hash of the external-in message (returned by {@link sendTransaction} as `normalizedHash`). */
           normalizedHash: string;
       }
 );
 
+/**
+ * Return type of {@link getTransactionStatus}.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export type GetTransactionStatusReturnType = TransactionStatusResponse;
 
 export type GetTransactionStatusErrorType = Error;
 
 /**
- * Get the status of a transaction by its BOC.
+ * 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.
  *
- * In TON, a single external message triggers a tree of internal messages.
- * The transaction is "complete" only when the entire trace finishes.
- * This action checks toncenter's trace endpoints to determine the current status.
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link GetTransactionStatusParameters} `boc` xor `normalizedHash` and optional network override.
+ * @returns Status response with current state, completed/total message counts and trace details.
  *
- * @example
- * ```ts
- * const result = await sendTransaction(appKit, { messages: [...] });
- * const status = await getTransactionStatus(appKit, { boc: result.boc });
- * // status.status === 'pending' | 'completed' | 'failed'
- * // status.completedMessages === 3
- * // status.totalMessages === 5
- * ```
+ * @public
+ * @category Action
+ * @section Transactions
  */
 export const getTransactionStatus = async (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/transaction/send-transaction.ts b/packages/appkit/src/actions/transaction/send-transaction.ts
index 723d952d2..5fb5b7e67 100644
--- a/packages/appkit/src/actions/transaction/send-transaction.ts
+++ b/packages/appkit/src/actions/transaction/send-transaction.ts
@@ -6,20 +6,42 @@
  *
  */
 
-import type { SendTransactionResponse } from '@ton/walletkit';
-
-import type { TransactionRequest } from '../../types/transaction';
 import type { AppKit } from '../../core/app-kit';
+import type { TransactionRequest, SendTransactionResponse } from '../../types/transaction';
 import { getSelectedWallet } from '../wallets/get-selected-wallet';
 
+/**
+ * Parameters accepted by {@link sendTransaction} — same shape as {@link TransactionRequest}.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export type SendTransactionParameters = TransactionRequest;
 
+/**
+ * Return type of {@link sendTransaction}.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export type SendTransactionReturnType = SendTransactionResponse;
 
 export type SendTransactionErrorType = Error;
 
 /**
- * Send transaction
+ * Hand a pre-built {@link TransactionRequest} to the selected wallet for signing and broadcast — usually the second step after {@link createTransferTonTransaction}, {@link buildSwapTransaction} or {@link buildStakeTransaction}; throws `Error('Wallet not connected')` if no wallet is currently selected.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link SendTransactionParameters} Transaction request to broadcast.
+ * @returns Wallet response carrying the BoC of the sent transaction.
+ *
+ * @sample docs/examples/src/appkit/actions/transaction#SEND_TRANSACTION
+ *
+ * @public
+ * @category Action
+ * @section Transactions
  */
 export const sendTransaction = async (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/transaction/transfer-ton.ts b/packages/appkit/src/actions/transaction/transfer-ton.ts
index 530e75da9..933383ad2 100644
--- a/packages/appkit/src/actions/transaction/transfer-ton.ts
+++ b/packages/appkit/src/actions/transaction/transfer-ton.ts
@@ -6,21 +6,45 @@
  *
  */
 
-import type { SendTransactionResponse } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { SendTransactionResponse } from '../../types/transaction';
 import { createTransferTonTransaction } from './create-transfer-ton-transaction';
 import type { CreateTransferTonTransactionParameters } from './create-transfer-ton-transaction';
 import { sendTransaction } from './send-transaction';
 
+/**
+ * Parameters accepted by {@link transferTon} — same shape as {@link CreateTransferTonTransactionParameters}.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export type TransferTonParameters = CreateTransferTonTransactionParameters;
 
+/**
+ * Return type of {@link transferTon}.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export type TransferTonReturnType = SendTransactionResponse;
 
 export type TransferTonErrorType = Error;
 
 /**
- * Transfer TON - creates and sends a TON transfer transaction
+ * Build and send a TON transfer from the selected wallet in one step (use {@link createTransferTonTransaction} + {@link sendTransaction} if you need to inspect the transaction first); throws `Error('Wallet not connected')` if no wallet is currently selected.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link TransferTonParameters} Recipient, amount and optional payload/comment/stateInit.
+ * @returns Wallet response carrying the BoC of the sent transaction.
+ *
+ * @sample docs/examples/src/appkit/actions/transaction#TRANSFER_TON
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Transactions
  */
 export const transferTon = async (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/transaction/watch-transactions-by-address.ts b/packages/appkit/src/actions/transaction/watch-transactions-by-address.ts
index cf9e62724..f36fb2a12 100644
--- a/packages/appkit/src/actions/transaction/watch-transactions-by-address.ts
+++ b/packages/appkit/src/actions/transaction/watch-transactions-by-address.ts
@@ -7,21 +7,50 @@
  */
 
 import { Address } from '@ton/core';
-import type { TransactionsUpdate, Network } from '@ton/walletkit';
 
 import type { AppKit } from '../../core/app-kit';
+import type { TransactionsUpdate } from '../../core/streaming';
+import type { Network } from '../../types/network';
+import type { UserFriendlyAddress } from '../../types/primitives';
 import { resolveNetwork } from '../../utils/network/resolve-network';
 
+/**
+ * Options for {@link watchTransactionsByAddress}.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export interface WatchTransactionsByAddressOptions {
-    address: string | Address;
+    /** Address to watch — pass a {@link UserFriendlyAddress} string or an `Address` instance from `@ton/core`. */
+    address: UserFriendlyAddress | Address;
+    /** Callback fired on every transactions update from the streaming provider. */
     onChange: (update: TransactionsUpdate) => void;
+    /** 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. */
     network?: Network;
 }
 
+/**
+ * Return type of {@link watchTransactionsByAddress} — call to stop receiving updates.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export type WatchTransactionsByAddressReturnType = () => void;
 
 /**
- * Watch transactions by address.
+ * Subscribe to incoming-transaction events for an arbitrary address (use {@link watchTransactions} for the selected wallet).
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link WatchTransactionsByAddressOptions} Address, update callback and optional network override.
+ * @returns Unsubscribe function — call it to stop receiving updates.
+ *
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Transactions
  */
 export const watchTransactionsByAddress = (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/transaction/watch-transactions.ts b/packages/appkit/src/actions/transaction/watch-transactions.ts
index 4ad39c1aa..ea80aacfd 100644
--- a/packages/appkit/src/actions/transaction/watch-transactions.ts
+++ b/packages/appkit/src/actions/transaction/watch-transactions.ts
@@ -6,22 +6,48 @@
  *
  */
 
-import type { TransactionsUpdate, Network } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
 import { WALLETS_EVENTS } from '../../core/app-kit';
+import type { TransactionsUpdate } from '../../core/streaming';
+import type { Network } from '../../types/network';
 import { getSelectedWallet } from '../wallets/get-selected-wallet';
 import { watchTransactionsByAddress } from './watch-transactions-by-address';
 
+/**
+ * Options for {@link watchTransactions}.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export interface WatchTransactionsOptions {
+    /** Callback fired on every transactions update from the streaming provider. */
     onChange: (update: TransactionsUpdate) => void;
+    /** Network to watch on. Defaults to the selected wallet's network. */
     network?: Network;
 }
 
+/**
+ * Return type of {@link watchTransactions} — call to stop receiving updates.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export type WatchTransactionsReturnType = () => void;
 
 /**
- * Watch transactions for the selected wallet.
+ * Subscribe to incoming-transaction events for the currently selected wallet, automatically rebinding when the user connects, switches, or disconnects (use {@link watchTransactionsByAddress} for a fixed address).
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param options - {@link WatchTransactionsOptions} Update callback and optional network override.
+ * @returns Unsubscribe function — call it to stop receiving updates.
+ *
+ * @expand options
+ *
+ * @public
+ * @category Action
+ * @section Transactions
  */
 export const watchTransactions = (appKit: AppKit, options: WatchTransactionsOptions): WatchTransactionsReturnType => {
     const { network, onChange } = options;
diff --git a/packages/appkit/src/actions/wallets/get-connected-wallets.ts b/packages/appkit/src/actions/wallets/get-connected-wallets.ts
index dbc8ed25e..24746335e 100644
--- a/packages/appkit/src/actions/wallets/get-connected-wallets.ts
+++ b/packages/appkit/src/actions/wallets/get-connected-wallets.ts
@@ -9,10 +9,26 @@
 import type { AppKit } from '../../core/app-kit';
 import type { WalletInterface } from '../../types/wallet';
 
+/**
+ * Return type of {@link getConnectedWallets} — read-only view of the connected-wallets array.
+ *
+ * @public
+ * @category Type
+ * @section Wallets
+ */
 export type GetConnectedWalletsReturnType = readonly WalletInterface[];
 
 /**
- * Get connected wallets
+ * List every wallet currently connected through any registered {@link Connector}.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @returns Read-only array of {@link WalletInterface}s.
+ *
+ * @sample docs/examples/src/appkit/actions/wallets#GET_CONNECTED_WALLETS
+ *
+ * @public
+ * @category Action
+ * @section Wallets
  */
 export const getConnectedWallets = (appKit: AppKit): GetConnectedWalletsReturnType => {
     return appKit.walletsManager.wallets;
diff --git a/packages/appkit/src/actions/wallets/get-selected-wallet.ts b/packages/appkit/src/actions/wallets/get-selected-wallet.ts
index 0512e010b..4f90b299f 100644
--- a/packages/appkit/src/actions/wallets/get-selected-wallet.ts
+++ b/packages/appkit/src/actions/wallets/get-selected-wallet.ts
@@ -9,10 +9,26 @@
 import type { AppKit } from '../../core/app-kit';
 import type { WalletInterface } from '../../types/wallet';
 
+/**
+ * Return type of {@link getSelectedWallet} — `null` when no wallet is currently selected.
+ *
+ * @public
+ * @category Type
+ * @section Wallets
+ */
 export type GetSelectedWalletReturnType = WalletInterface | null;
 
 /**
- * Get currently selected wallet
+ * Read the wallet AppKit treats as "active" — most actions ({@link getBalance}, {@link signText}, {@link transferTon}) target this wallet implicitly. Returns `null` when no wallet is connected or selected.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @returns Selected {@link WalletInterface}, or `null` when none is selected.
+ *
+ * @sample docs/examples/src/appkit/actions/wallets#GET_SELECTED_WALLET
+ *
+ * @public
+ * @category Action
+ * @section Wallets
  */
 export const getSelectedWallet = (appKit: AppKit): GetSelectedWalletReturnType => {
     return appKit.walletsManager.selectedWallet;
diff --git a/packages/appkit/src/actions/wallets/set-selected-wallet-id.ts b/packages/appkit/src/actions/wallets/set-selected-wallet-id.ts
index 8ca697fc0..4813807e1 100644
--- a/packages/appkit/src/actions/wallets/set-selected-wallet-id.ts
+++ b/packages/appkit/src/actions/wallets/set-selected-wallet-id.ts
@@ -8,14 +8,39 @@
 
 import type { AppKit } from '../../core/app-kit';
 
+/**
+ * Parameters accepted by {@link setSelectedWalletId}.
+ *
+ * @public
+ * @category Type
+ * @section Wallets
+ */
 export interface SetSelectedWalletIdParameters {
+    /** Wallet ID (as returned by {@link WalletInterface}'s `getWalletId()`) to select; pass `null` to clear the selection. */
     walletId: string | null;
 }
 
+/**
+ * Return type of {@link setSelectedWalletId}.
+ *
+ * @public
+ * @category Type
+ * @section Wallets
+ */
 export type SetSelectedWalletIdReturnType = void;
 
 /**
- * Set selected wallet
+ * Switch which connected wallet AppKit treats as selected — emits `WALLETS_EVENTS.SELECTION_CHANGED` so {@link watchSelectedWallet} subscribers fire. Pass `null` to clear the selection.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link SetSelectedWalletIdParameters} Wallet ID to select, or `null` to clear.
+ *
+ * @sample docs/examples/src/appkit/actions/wallets#SET_SELECTED_WALLET_ID
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Wallets
  */
 export const setSelectedWalletId = (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/wallets/watch-connected-wallets.ts b/packages/appkit/src/actions/wallets/watch-connected-wallets.ts
index 3c0db1f60..c2d38f992 100644
--- a/packages/appkit/src/actions/wallets/watch-connected-wallets.ts
+++ b/packages/appkit/src/actions/wallets/watch-connected-wallets.ts
@@ -10,14 +10,40 @@ import type { AppKit } from '../../core/app-kit';
 import { WALLETS_EVENTS } from '../../core/app-kit';
 import type { WalletInterface } from '../../types/wallet';
 
+/**
+ * Parameters accepted by {@link watchConnectedWallets}.
+ *
+ * @public
+ * @category Type
+ * @section Wallets
+ */
 export type WatchConnectedWalletsParameters = {
+    /** Callback fired whenever the list of connected wallets changes — receives the latest snapshot. */
     onChange: (wallets: WalletInterface[]) => void;
 };
 
+/**
+ * Return type of {@link watchConnectedWallets} — call to stop receiving updates.
+ *
+ * @public
+ * @category Type
+ * @section Wallets
+ */
 export type WatchConnectedWalletsReturnType = () => void;
 
 /**
- * Watch connected wallets
+ * Subscribe to the list of connected wallets — fires whenever a wallet connects or disconnects through any registered {@link Connector}.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link WatchConnectedWalletsParameters} Update callback.
+ * @returns Unsubscribe function — call it to stop receiving updates.
+ *
+ * @sample docs/examples/src/appkit/actions/wallets#WATCH_CONNECTED_WALLETS
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Wallets
  */
 export const watchConnectedWallets = (
     appKit: AppKit,
diff --git a/packages/appkit/src/actions/wallets/watch-selected-wallet.ts b/packages/appkit/src/actions/wallets/watch-selected-wallet.ts
index 22bee3a7b..1a7fbdb1e 100644
--- a/packages/appkit/src/actions/wallets/watch-selected-wallet.ts
+++ b/packages/appkit/src/actions/wallets/watch-selected-wallet.ts
@@ -11,14 +11,40 @@ import { WALLETS_EVENTS } from '../../core/app-kit';
 import { getSelectedWallet } from '../../actions';
 import type { WalletInterface } from '../../types/wallet';
 
+/**
+ * Parameters accepted by {@link watchSelectedWallet}.
+ *
+ * @public
+ * @category Type
+ * @section Wallets
+ */
 export interface WatchSelectedWalletParameters {
+    /** Callback fired whenever the selected wallet changes — receives the new wallet, or `null` when the selection was cleared. */
     onChange: (wallet: WalletInterface | null) => void;
 }
 
+/**
+ * Return type of {@link watchSelectedWallet} — call to stop receiving updates.
+ *
+ * @public
+ * @category Type
+ * @section Wallets
+ */
 export type WatchSelectedWalletReturnType = () => void;
 
 /**
- * Watch selected wallet
+ * Subscribe to selected-wallet changes — fires when {@link 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.
+ *
+ * @param appKit - {@link AppKit} Runtime instance.
+ * @param parameters - {@link WatchSelectedWalletParameters} Update callback.
+ * @returns Unsubscribe function — call it to stop receiving updates.
+ *
+ * @sample docs/examples/src/appkit/actions/wallets#WATCH_SELECTED_WALLET
+ * @expand parameters
+ *
+ * @public
+ * @category Action
+ * @section Wallets
  */
 export const watchSelectedWallet = (
     appKit: AppKit,
diff --git a/packages/appkit/src/connectors/tonconnect/adapters/ton-connect-wallet-adapter.ts b/packages/appkit/src/connectors/tonconnect/adapters/ton-connect-wallet-adapter.ts
index d7db5c564..0d7acda1b 100644
--- a/packages/appkit/src/connectors/tonconnect/adapters/ton-connect-wallet-adapter.ts
+++ b/packages/appkit/src/connectors/tonconnect/adapters/ton-connect-wallet-adapter.ts
@@ -9,35 +9,45 @@
 import { Address } from '@ton/core';
 import type { Wallet as TonConnectWallet } from '@tonconnect/sdk';
 import type { SignDataPayload as TonConnectSignDataPayload } from '@tonconnect/sdk';
-import type { SendTransactionResponse, UserFriendlyAddress, Hex } from '@ton/walletkit';
-import { asHex, createWalletId, getNormalizedExtMessageHash } from '@ton/walletkit';
 import type { TonConnectUI } from '@tonconnect/ui';
 
-import type { TransactionRequest } from '../../../types/transaction';
-import type { Base64String } from '../../../types/primitives';
-import { getValidUntil } from '../utils/transaction';
-import type { WalletInterface } from '../../../types/wallet';
-import type { SignDataRequest, SignDataResponse } from '../../../types/signing';
 import { Network } from '../../../types/network';
+import type { Base64String, UserFriendlyAddress, Hex } from '../../../types/primitives';
+import type { SignDataRequest, SignDataResponse } from '../../../types/signing';
+import type { TransactionRequest, SendTransactionResponse } from '../../../types/transaction';
+import type { WalletInterface } from '../../../types/wallet';
+import { asHex, createWalletId, getNormalizedExtMessageHash } from '../../../utils';
+import { getValidUntil } from '../utils/transaction';
 
 /**
- * Configuration for TonConnectWalletAdapter
+ * Configuration accepted by {@link TonConnectWalletAdapter} when wrapping a TonConnect wallet for AppKit.
+ *
+ * @public
+ * @category Type
+ * @section Wallets
  */
 export interface TonConnectWalletAdapterConfig {
+    /** ID of the connector that produced this wallet — surfaced as `WalletInterface.connectorId`. */
     connectorId: string;
+    /** Underlying TonConnect wallet object. */
     tonConnectWallet: TonConnectWallet;
+    /** TonConnect UI instance used to drive `sendTransaction` and `signData` calls. */
     tonConnectUI: TonConnectUI;
 }
 
 /**
- * Minimal adapter that makes TonConnect wallet compatible with WalletInterface.
- * Only implements identity and signing methods - data fetching is done via actions.
+ * {@link WalletInterface} implementation backed by a TonConnect wallet. Built for you by {@link createTonConnectConnector} — apps interact with it through standard AppKit actions ({@link sendTransaction}, {@link signText}/{@link signBinary}/{@link signCell}); reads (balance, jettons, NFTs) go through AppKit actions using `appKit.networkManager`, not this adapter.
+ *
+ * @public
+ * @category Class
+ * @section Wallets
  */
 export class TonConnectWalletAdapter implements WalletInterface {
     public readonly tonConnectWallet: TonConnectWallet;
     public readonly tonConnectUI: TonConnectUI;
     public readonly connectorId: string;
 
+    /** @param config - {@link TonConnectWalletAdapterConfig} TonConnect wallet + UI instance and the id of the connector that produced them. */
     constructor(config: TonConnectWalletAdapterConfig) {
         this.tonConnectWallet = config.tonConnectWallet;
         this.tonConnectUI = config.tonConnectUI;
diff --git a/packages/appkit/src/connectors/tonconnect/connectors/ton-connect-connector.ts b/packages/appkit/src/connectors/tonconnect/connectors/ton-connect-connector.ts
index c53507fc1..b10a9340c 100644
--- a/packages/appkit/src/connectors/tonconnect/connectors/ton-connect-connector.ts
+++ b/packages/appkit/src/connectors/tonconnect/connectors/ton-connect-connector.ts
@@ -16,26 +16,63 @@ import type { WalletInterface } from '../../../types/wallet';
 import { TONCONNECT_DEFAULT_CONNECTOR_ID } from '../constants/id';
 import { createConnector } from '../../../types/connector';
 
+/**
+ * Configuration accepted by {@link createTonConnectConnector}.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export interface TonConnectConnectorConfig {
+    /** Connector ID. Defaults to {@link TONCONNECT_DEFAULT_CONNECTOR_ID} (`'tonconnect'`); set this when you need to register multiple TonConnect-flavoured connectors side by side. */
     id?: string;
+    /** Display metadata override; merged on top of TonConnect's default name and icon. */
     metadata?: ConnectorMetadata;
+    /** Options forwarded to the underlying `TonConnectUI` constructor (manifest URL, etc.). Ignored when `tonConnectUI` is supplied. */
     tonConnectOptions?: TonConnectUiCreateOptions;
+    /** Pre-built `TonConnectUI` instance to reuse; when set, the connector skips its own instantiation and `tonConnectOptions` is ignored. */
     tonConnectUI?: TonConnectUI;
 }
 
+/**
+ * {@link Connector} produced by {@link createTonConnectConnector} — extends the base interface with the underlying `TonConnectUI` instance for advanced flows that need direct access (e.g., custom modals).
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export type TonConnectConnector = Connector & {
     type: 'tonconnect';
+    /** Underlying `TonConnectUI` instance — `null` during SSR or before the connector has been initialised. Apps that need to drive the modal directly (e.g. custom UI flows) can read this and call its methods. */
     tonConnectUI: TonConnectUI | null;
 };
 
+/**
+ * Build a TonConnect-backed {@link Connector} for AppKit; pass the result to {@link AppKitConfig}'s `connectors` or {@link addConnector}.
+ *
+ * @param config - {@link TonConnectConnectorConfig} Connector ID, metadata override and TonConnect options or pre-built UI instance.
+ * @returns Factory function consumed by AppKit at registration time.
+ *
+ * @sample docs/examples/src/appkit/connectors/tonconnect#TON_CONNECT_CONNECTOR
+ *
+ * @public
+ * @category Action
+ * @section Connectors
+ */
 export const createTonConnectConnector = (config: TonConnectConnectorConfig) => {
     return createConnector(({ eventEmitter, networkManager, ssr }): TonConnectConnector => {
         let originalTonConnectUI: TonConnectUI | null = null;
         let unsubscribeTonConnect: (() => void) | null = null;
+        let unsubscribeDefaultNetwork: (() => void) | null = null;
+        let destroyed = false;
 
         const id = config.id ?? TONCONNECT_DEFAULT_CONNECTOR_ID;
 
         const getTonConnectUI = (): TonConnectUI | null => {
+            if (destroyed) {
+                return null;
+            }
+
             if (originalTonConnectUI) {
                 return originalTonConnectUI;
             }
@@ -84,19 +121,17 @@ export const createTonConnectConnector = (config: TonConnectConnectorConfig) =>
                 return;
             }
 
-            unsubscribeTonConnect = originalTonConnectUI.onStatusChange((wallet) => {
-                const wallets = getConnectedWallets();
-
-                if (wallet) {
-                    eventEmitter.emit(CONNECTOR_EVENTS.CONNECTED, { wallets, connectorId: id }, id);
-                } else {
-                    eventEmitter.emit(CONNECTOR_EVENTS.DISCONNECTED, { connectorId: id }, id);
-                }
+            unsubscribeTonConnect = originalTonConnectUI.onStatusChange(() => {
+                eventEmitter.emit(
+                    CONNECTOR_EVENTS.WALLETS_UPDATED,
+                    { connectorId: id, wallets: getConnectedWallets() },
+                    id,
+                );
             });
 
             // Set default network and subscribe to changes
             originalTonConnectUI.setConnectionNetwork(networkManager.getDefaultNetwork()?.chainId);
-            eventEmitter.on(NETWORKS_EVENTS.DEFAULT_CHANGED, ({ payload }) => {
+            unsubscribeDefaultNetwork = eventEmitter.on(NETWORKS_EVENTS.DEFAULT_CHANGED, ({ payload }) => {
                 if (originalTonConnectUI) {
                     originalTonConnectUI.setConnectionNetwork(payload.network?.chainId);
                 }
@@ -135,7 +170,11 @@ export const createTonConnectConnector = (config: TonConnectConnectorConfig) =>
             },
 
             destroy() {
+                destroyed = true;
                 unsubscribeTonConnect?.();
+                unsubscribeDefaultNetwork?.();
+                unsubscribeTonConnect = null;
+                unsubscribeDefaultNetwork = null;
                 originalTonConnectUI = null;
             },
         };
diff --git a/packages/appkit/src/connectors/tonconnect/constants/id.ts b/packages/appkit/src/connectors/tonconnect/constants/id.ts
index 17b334637..47b838434 100644
--- a/packages/appkit/src/connectors/tonconnect/constants/id.ts
+++ b/packages/appkit/src/connectors/tonconnect/constants/id.ts
@@ -6,4 +6,11 @@
  *
  */
 
+/**
+ * Default id assigned to the TonConnect connector when none is supplied to {@link createTonConnectConnector}; pass this to {@link connect} / {@link disconnect} to drive the TonConnect flow without hard-coding the literal.
+ *
+ * @public
+ * @category Constants
+ * @section Connectors
+ */
 export const TONCONNECT_DEFAULT_CONNECTOR_ID = 'tonconnect';
diff --git a/packages/appkit/src/connectors/tonconnect/index.ts b/packages/appkit/src/connectors/tonconnect/index.ts
index 993c740b8..0b9e7fd44 100644
--- a/packages/appkit/src/connectors/tonconnect/index.ts
+++ b/packages/appkit/src/connectors/tonconnect/index.ts
@@ -7,17 +7,12 @@
  */
 
 /**
- * TonConnect Feature Entry Point
- *
- * This module contains all TonConnect-related functionality.
- * Import from '@ton/appkit/tonconnect' to use TonConnect features.
- *
- * This is a separate entry point to allow tree-shaking for users
- * who don't need TonConnect functionality.
+ * TonConnect entry point. Import from `@ton/appkit/tonconnect`; it's kept as a separate
+ * entry so apps that don't use TonConnect can tree-shake it out.
  *
  * @example
  * ```ts
- * import { TonConnectConnector, TonConnectWalletWrapper } from '@ton/appkit/tonconnect';
+ * import { createTonConnectConnector, TonConnectWalletAdapter } from '@ton/appkit/tonconnect';
  * ```
  */
 
diff --git a/packages/appkit/src/connectors/tonconnect/utils/transaction.ts b/packages/appkit/src/connectors/tonconnect/utils/transaction.ts
index 2d6d10069..f7f84023e 100644
--- a/packages/appkit/src/connectors/tonconnect/utils/transaction.ts
+++ b/packages/appkit/src/connectors/tonconnect/utils/transaction.ts
@@ -16,7 +16,7 @@ import type { TransactionRequest, TransactionRequestMessage } from '../../../typ
 export const DEFAULT_TRANSACTION_VALIDITY_SECONDS = 300;
 
 /**
- * Convert TonWalletKit TransactionRequest to TonConnect SendTransactionRequest format
+ * Convert a walletkit `TransactionRequest` to a TonConnect `SendTransactionRequest`.
  */
 export const toTonConnectTransaction = (request: TransactionRequest): SendTransactionRequest => {
     return {
diff --git a/packages/appkit/src/core/app-kit/constants/events.ts b/packages/appkit/src/core/app-kit/constants/events.ts
index d8c012c55..f35bf646c 100644
--- a/packages/appkit/src/core/app-kit/constants/events.ts
+++ b/packages/appkit/src/core/app-kit/constants/events.ts
@@ -7,15 +7,27 @@
  */
 
 /**
- * Connector events
+ * Event names AppKit emits for connector-list and connector-wallet changes; payloads are {@link ConnectorAddedPayload}, {@link ConnectorRemovedPayload} and {@link ConnectorWalletsUpdatedPayload}.
+ *
+ * @public
+ * @category Constants
+ * @section Connectors
  */
 export const CONNECTOR_EVENTS = {
-    CONNECTED: 'connector:connected',
-    DISCONNECTED: 'connector:disconnected',
+    /** A connector was registered via {@link addConnector} (or AppKit's constructor). */
+    ADDED: 'connector:added',
+    /** A connector was unregistered via `removeConnector` or its own teardown. */
+    REMOVED: 'connector:removed',
+    /** A connector's connected-wallets list changed (connect, disconnect, or account switch inside the wallet). */
+    WALLETS_UPDATED: 'connector:wallets-updated',
 } as const;
 
 /**
- * Wallet events
+ * Event names AppKit emits when the available wallet list (`UPDATED`) or the active wallet (`SELECTION_CHANGED`) changes.
+ *
+ * @public
+ * @category Constants
+ * @section Wallets
  */
 export const WALLETS_EVENTS = {
     UPDATED: 'wallets:updated',
@@ -23,7 +35,11 @@ export const WALLETS_EVENTS = {
 } as const;
 
 /**
- * Networks events
+ * Event names AppKit emits on network changes; `DEFAULT_CHANGED` carries a {@link DefaultNetworkChangedPayload}.
+ *
+ * @public
+ * @category Constants
+ * @section Networks
  */
 export const NETWORKS_EVENTS = {
     UPDATED: 'networks:updated',
diff --git a/packages/appkit/src/core/app-kit/index.ts b/packages/appkit/src/core/app-kit/index.ts
index 89ee67bcf..92e06e688 100644
--- a/packages/appkit/src/core/app-kit/index.ts
+++ b/packages/appkit/src/core/app-kit/index.ts
@@ -13,7 +13,8 @@ export type { AppKitConfig } from './types/config';
 export type {
     AppKitEmitter,
     AppKitEvents,
-    WalletConnectedPayload,
-    WalletDisconnectedPayload,
+    ConnectorAddedPayload,
+    ConnectorRemovedPayload,
+    ConnectorWalletsUpdatedPayload,
     DefaultNetworkChangedPayload,
 } from './types/events';
diff --git a/packages/appkit/src/core/app-kit/services/app-kit.ts b/packages/appkit/src/core/app-kit/services/app-kit.ts
index e99423010..65e279e5e 100644
--- a/packages/appkit/src/core/app-kit/services/app-kit.ts
+++ b/packages/appkit/src/core/app-kit/services/app-kit.ts
@@ -6,29 +6,34 @@
  *
  */
 
-import { SwapManager, StreamingManager, OnrampManager, CryptoOnrampManager } from '@ton/walletkit';
-import type {
-    ProviderInput,
-    SwapProviderInterface,
-    StakingProviderInterface,
-    OnrampProviderInterface,
-    CryptoOnrampProviderInterface,
-} from '@ton/walletkit';
-
-import type { AppKitConfig } from '../types/config';
-import { CONNECTOR_EVENTS, WALLETS_EVENTS } from '../constants/events';
+import { CryptoOnrampManager } from '../../../crypto-onramp';
+import type { CryptoOnrampProviderInterface } from '../../../crypto-onramp';
+import { OnrampManager } from '../../../onramp';
+import type { OnrampProviderInterface } from '../../../onramp';
 import { StakingManager } from '../../../staking';
+import type { StakingProviderInterface } from '../../../staking';
+import { SwapManager } from '../../../swap';
+import type { SwapProviderInterface } from '../../../swap';
 import type { Connector, ConnectorFactoryContext, ConnectorInput } from '../../../types/connector';
-import { EventEmitter } from '../../emitter';
-import type { AppKitEmitter, AppKitEvents } from '../types/events';
+import { Network } from '../../../types/network';
+import type { ProviderInput } from '../../../types/provider';
 import type { WalletInterface } from '../../../types/wallet';
-import { WalletsManager } from '../../wallets-manager';
+import { EventEmitter } from '../../emitter';
 import { AppKitNetworkManager } from '../../network';
-import { Network } from '../../../types/network';
+import { StreamingManager } from '../../streaming';
+import { WalletsManager } from '../../wallets-manager';
+import { CONNECTOR_EVENTS, WALLETS_EVENTS } from '../constants/events';
+import type { AppKitEmitter, AppKitEvents } from '../types/events';
+import type { AppKitConfig } from '../types/config';
 
 /**
- * Central hub for wallet management.
- * Stores emitter, providers, and manages wallet connections.
+ * 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.
+ *
+ * @sample docs/examples/src/appkit#APPKIT_INIT
+ *
+ * @public
+ * @category Class
+ * @section Core
  */
 export class AppKit {
     readonly emitter: AppKitEmitter;
@@ -43,12 +48,15 @@ export class AppKit {
     readonly streamingManager: StreamingManager;
     readonly config: AppKitConfig;
 
+    /**
+     * @param config - {@link AppKitConfig} Networks, connectors, providers and runtime flags.
+     * @expand config
+     */
     constructor(config: AppKitConfig) {
         this.config = config;
 
         this.emitter = new EventEmitter<AppKitEvents>();
-        this.emitter.on(CONNECTOR_EVENTS.CONNECTED, this.updateWalletsFromConnectors.bind(this));
-        this.emitter.on(CONNECTOR_EVENTS.DISCONNECTED, this.updateWalletsFromConnectors.bind(this));
+        this.emitter.on(CONNECTOR_EVENTS.WALLETS_UPDATED, this.updateWalletsFromConnectors.bind(this));
 
         // Use provided networks config or default to mainnet
         const networks = config.networks ?? {
@@ -56,6 +64,9 @@ export class AppKit {
         };
 
         this.networkManager = new AppKitNetworkManager({ networks }, this.emitter);
+        if (config.defaultNetwork) {
+            this.networkManager.setDefaultNetwork(config.defaultNetwork);
+        }
         this.walletsManager = new WalletsManager(this.emitter);
 
         this.swapManager = new SwapManager(() => this.createFactoryContext());
@@ -94,6 +105,8 @@ export class AppKit {
         }
 
         this.connectors.push(connector);
+        this.updateWalletsFromConnectors();
+        this.emitter.emit(CONNECTOR_EVENTS.ADDED, { connector }, 'appkit');
 
         return () => {
             this.removeConnector(connector);
@@ -110,6 +123,8 @@ export class AppKit {
         if (oldConnector) {
             oldConnector.destroy();
             this.connectors.splice(this.connectors.indexOf(oldConnector), 1);
+            this.updateWalletsFromConnectors();
+            this.emitter.emit(CONNECTOR_EVENTS.REMOVED, { connector: oldConnector }, 'appkit');
         }
     }
 
diff --git a/packages/appkit/src/core/app-kit/types/config.ts b/packages/appkit/src/core/app-kit/types/config.ts
index d2cc0b2e0..38814a6ac 100644
--- a/packages/appkit/src/core/app-kit/types/config.ts
+++ b/packages/appkit/src/core/app-kit/types/config.ts
@@ -6,40 +6,30 @@
  *
  */
 
-import type { NetworkAdapters, ProviderInput } from '@ton/walletkit';
-
 import type { ConnectorInput } from '../../../types/connector';
-import type { Network } from '../../../types/network';
+import type { Network, NetworkAdapters } from '../../../types/network';
+import type { ProviderInput } from '../../../types/provider';
 
 /**
- * Configuration for AppKit
+ * Constructor options for {@link AppKit} — networks, connectors, providers and runtime flags.
+ *
+ * @public
+ * @category Type
+ * @section Core
  */
 export interface AppKitConfig {
-    /**
-     * Network configuration
-     * At least one network must be configured.
-     *
-     * Keys are chain IDs (use `Network.mainnet().chainId` or `Network.testnet().chainId`)
-     * Values contain apiClient configuration (url and optional API key)
-     */
+    /** Map of chain ID to {@link NetworkConfig} (which holds the api-client setup); if omitted, AppKit defaults to mainnet only. */
     networks?: NetworkAdapters;
 
-    /**
-     * Wallet connectors
-     */
+    /** Wallet connectors registered at startup. */
     connectors?: ConnectorInput[];
 
-    /**
-     * Default network for wallet connections.
-     * If set, connectors (e.g. TonConnect) will enforce this network when connecting.
-     * Set to `undefined` to allow any network.
-     */
+    /** Default network. */
     defaultNetwork?: Network;
 
+    /** Providers registered at startup. */
     providers?: ProviderInput[];
 
-    /**
-     * Enable server-side rendering support
-     */
+    /** Set to `true` to enable server-side rendering support. */
     ssr?: boolean;
 }
diff --git a/packages/appkit/src/core/app-kit/types/events.ts b/packages/appkit/src/core/app-kit/types/events.ts
index b0b602589..970860a84 100644
--- a/packages/appkit/src/core/app-kit/types/events.ts
+++ b/packages/appkit/src/core/app-kit/types/events.ts
@@ -6,37 +6,97 @@
  *
  */
 
+import type { Connector } from '../../../types/connector';
 import type { Network } from '../../../types/network';
 import type { CONNECTOR_EVENTS, WALLETS_EVENTS, NETWORKS_EVENTS } from '../constants/events';
 import type { SharedKitEvents } from '../../emitter';
 import type { EventEmitter } from '../../emitter';
 import type { WalletInterface } from '../../../types/wallet';
 
-export interface WalletConnectedPayload {
-    wallets: WalletInterface[];
-    connectorId: string;
+/**
+ * Payload of `connector:added` events — the connector that was just registered.
+ *
+ * @public
+ * @category Type
+ * @section Core
+ */
+export interface ConnectorAddedPayload {
+    /** {@link Connector} just registered with AppKit. */
+    connector: Connector;
+}
+
+/**
+ * Payload of `connector:removed` events — the connector that was just unregistered.
+ *
+ * @public
+ * @category Type
+ * @section Core
+ */
+export interface ConnectorRemovedPayload {
+    /** {@link Connector} just unregistered from AppKit (already torn down via `destroy()`). */
+    connector: Connector;
 }
 
-export interface WalletDisconnectedPayload {
+/**
+ * Payload of `connector:wallets-updated` events — fired by a connector when its connected-wallets list changes (connect, disconnect, or account switch inside the wallet).
+ *
+ * @public
+ * @category Type
+ * @section Core
+ */
+export interface ConnectorWalletsUpdatedPayload {
+    /** ID of the {@link Connector} whose wallets just changed. */
     connectorId: string;
+    /** Wallets currently exposed by the connector — empty when the wallet was just disconnected. */
+    wallets: WalletInterface[];
 }
 
+/**
+ * Payload of `networks:default-changed` events — the new default network, or `undefined` when cleared.
+ *
+ * @public
+ * @category Type
+ * @section Core
+ */
 export interface DefaultNetworkChangedPayload {
+    /** New default network, or `undefined` when the constraint is cleared. */
     network: Network | undefined;
 }
 
+/**
+ * Map of every event name AppKit can emit to its payload type, used to type listeners on {@link AppKitEmitter}.
+ *
+ * @public
+ * @category Type
+ * @section Core
+ */
 export type AppKitEvents = {
     // Connector events
-    [CONNECTOR_EVENTS.CONNECTED]: WalletConnectedPayload;
-    [CONNECTOR_EVENTS.DISCONNECTED]: WalletDisconnectedPayload;
+    /** Fired by {@link addConnector} when a connector is registered with AppKit. */
+    [CONNECTOR_EVENTS.ADDED]: ConnectorAddedPayload;
+    /** Fired by `removeConnector` when a connector is unregistered from AppKit. */
+    [CONNECTOR_EVENTS.REMOVED]: ConnectorRemovedPayload;
+    /** Fired by a connector whenever its connected-wallets list changes (connect, disconnect, or account switch inside the wallet). */
+    [CONNECTOR_EVENTS.WALLETS_UPDATED]: ConnectorWalletsUpdatedPayload;
 
     // Wallets events
+    /** Fired by AppKit's wallet manager after re-aggregating connectors — `wallets` is the full current set. */
     [WALLETS_EVENTS.UPDATED]: { wallets: WalletInterface[] };
+    /** Fired when the selected wallet changes — `walletId` is the new selection, or `null` when cleared. */
     [WALLETS_EVENTS.SELECTION_CHANGED]: { walletId: string | null };
 
     // Networks events
+    /** Fired by the network manager when a network's API client is registered or replaced via `setClient`. */
     [NETWORKS_EVENTS.UPDATED]: Record<string, never>;
+    /** Fired by {@link setDefaultNetwork} — carries the new default network, or `undefined` when the constraint was cleared. */
     [NETWORKS_EVENTS.DEFAULT_CHANGED]: DefaultNetworkChangedPayload;
 } & SharedKitEvents;
 
+/**
+ * Strongly-typed event emitter exposed as {@link AppKit}'s `emitter`; `appKit.emitter.on(name, handler)` returns an unsubscribe function.
+ *
+ * @public
+ * @category Type
+ * @section Core
+ */
 export type AppKitEmitter = EventEmitter<AppKitEvents>;
diff --git a/packages/appkit/src/core/emitter/index.ts b/packages/appkit/src/core/emitter/index.ts
index 415f6bb99..efebbfdb7 100644
--- a/packages/appkit/src/core/emitter/index.ts
+++ b/packages/appkit/src/core/emitter/index.ts
@@ -7,9 +7,51 @@
  */
 
 /**
- * Events Feature
- * Provides Emitter implementation
+ * Strongly-typed event emitter built on a string event name → payload type map; backs {@link AppKit}'s `emitter` and any custom emitters apps create. `appKit.emitter.on(name, handler)` returns an unsubscribe function.
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section Core
  */
 export { EventEmitter } from '@ton/walletkit';
 
-export type { EventPayload, KitEvent, EventListener, SharedKitEvents } from '@ton/walletkit';
+/**
+ * Generic event-payload constraint — an `object` that the typed event-name → payload map maps to.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Core
+ */
+export type { EventPayload } from '@ton/walletkit';
+
+/**
+ * Envelope every {@link EventEmitter} listener receives — `type` is the event name, `payload` is the event-specific data, `source` identifies who emitted it, and `timestamp` is the wall-clock millisecond mark.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Core
+ */
+export type { KitEvent } from '@ton/walletkit';
+
+/**
+ * Listener callback signature accepted by {@link EventEmitter}'s `on` — receives a {@link KitEvent} for the given event type and may return a Promise the emitter awaits.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Core
+ */
+export type { EventListener } from '@ton/walletkit';
+
+/**
+ * Event-name → payload map shared between AppKit and walletkit; AppKit extends it with its own connector, wallet and network events to type {@link AppKitEmitter}.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Core
+ */
+export type { SharedKitEvents } from '@ton/walletkit';
diff --git a/packages/appkit/src/core/network/index.ts b/packages/appkit/src/core/network/index.ts
index 7434fc17d..62d55fa7c 100644
--- a/packages/appkit/src/core/network/index.ts
+++ b/packages/appkit/src/core/network/index.ts
@@ -7,4 +7,4 @@
  */
 
 export { AppKitNetworkManager } from './services/app-kit-network-manager';
-export { ApiClient, ApiClientToncenter, ApiClientTonApi } from '@ton/walletkit';
+export { ApiClient, ApiClientToncenter, ApiClientTonApi, KitNetworkManager } from './walletkit';
diff --git a/packages/appkit/src/core/network/services/app-kit-network-manager.ts b/packages/appkit/src/core/network/services/app-kit-network-manager.ts
index d49e94a83..6a6f74919 100644
--- a/packages/appkit/src/core/network/services/app-kit-network-manager.ts
+++ b/packages/appkit/src/core/network/services/app-kit-network-manager.ts
@@ -6,17 +6,27 @@
  *
  */
 
-import type { ApiClient } from '@ton/walletkit';
-import { KitNetworkManager } from '@ton/walletkit';
-
+import type { ApiClient } from '../../../types/api-client';
+import type { Network } from '../../../types/network';
 import { NETWORKS_EVENTS } from '../../app-kit/constants/events';
 import type { AppKitEmitter } from '../../app-kit/types/events';
-import type { Network } from '../../../types/network';
+import { KitNetworkManager } from '../walletkit';
 
+/**
+ * Network manager exposed as {@link AppKit}'s `networkManager` — extends walletkit's `KitNetworkManager` with a default-network setter and AppKit event emission.
+ *
+ * @public
+ * @category Class
+ * @section Networks
+ */
 export class AppKitNetworkManager extends KitNetworkManager {
     private emitter: AppKitEmitter;
     private defaultNetwork: Network | undefined = undefined;
 
+    /**
+     * @param options - {@link TonWalletKitOptions} Forwarded to the {@link KitNetworkManager} base — chiefly the `networks` map keyed by chain ID.
+     * @param emitter - {@link AppKitEmitter} Emitter the manager publishes `networks:default-changed` / `networks:updated` events through.
+     */
     constructor(options: ConstructorParameters<typeof KitNetworkManager>[0], emitter: AppKitEmitter) {
         super(options);
         this.emitter = emitter;
@@ -30,8 +40,8 @@ export class AppKitNetworkManager extends KitNetworkManager {
     }
 
     /**
-     * Set the default network for wallet connections.
-     * Emits a change event and propagates to all connectors.
+     * Set the default network for wallet connections. Emits `networks:default-changed`;
+     * connectors that listen for it (e.g., TonConnect) can re-bind their connection network.
      */
     setDefaultNetwork(network: Network | undefined): void {
         this.defaultNetwork = network;
diff --git a/packages/appkit/src/core/network/walletkit.ts b/packages/appkit/src/core/network/walletkit.ts
new file mode 100644
index 000000000..705ae1449
--- /dev/null
+++ b/packages/appkit/src/core/network/walletkit.ts
@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+// Re-export of walletkit network primitives. Kept in a leaf file so internal
+// modules (`./services/...`) can import without forming a cycle through `./index.ts`.
+
+/**
+ * Walletkit-side network manager that {@link AppKitNetworkManager} extends, adding default-network state and AppKit event emission. Apps usually interact with the {@link AppKitNetworkManager} subclass via {@link AppKit}'s `networkManager`.
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section Networks
+ */
+export { KitNetworkManager } from '@ton/walletkit';
+
+/**
+ * Indexer/RPC client interface used by AppKit to read on-chain state — balance, jettons, NFTs, masterchain seqno, etc. Each {@link Network} resolves to its own `ApiClient` via {@link AppKitNetworkManager}; apps usually pull one through {@link getApiClient} rather than constructing it directly.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Client
+ */
+export { ApiClient } from '@ton/walletkit';
+
+/**
+ * {@link ApiClient} implementation backed by the Toncenter API.
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section Client
+ */
+export { ApiClientToncenter } from '@ton/walletkit';
+
+/**
+ * {@link ApiClient} implementation backed by the TonAPI indexer.
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section Client
+ */
+export { ApiClientTonApi } from '@ton/walletkit';
diff --git a/packages/appkit/src/core/streaming/index.ts b/packages/appkit/src/core/streaming/index.ts
index 3829c9b3f..bd6de1700 100644
--- a/packages/appkit/src/core/streaming/index.ts
+++ b/packages/appkit/src/core/streaming/index.ts
@@ -20,11 +20,57 @@ export type {
     StreamingAPI,
     TonCenterStreamingProviderConfig,
     TonApiStreamingProviderConfig,
-    BalanceUpdate,
-    TransactionsUpdate,
-    Transaction,
-    JettonUpdate,
     StreamingUpdate,
     StreamingWatchType,
     StreamingEvents,
 } from '@ton/walletkit';
+
+/**
+ * Update payload delivered to {@link watchTransactions} / {@link watchTransactionsByAddress} subscribers when transactions land for the watched address.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Transactions
+ */
+export type { TransactionsUpdate } from '@ton/walletkit';
+
+/**
+ * Single transaction record carried inside {@link TransactionsUpdate}'s `transactions` — account, lt/hash, in/out messages and emulation result.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Transactions
+ */
+export type { Transaction } from '@ton/walletkit';
+
+/**
+ * Update payload delivered to {@link watchJettons} / {@link watchJettonsByAddress} subscribers when the watched owner's jetton balance changes.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Jettons
+ */
+export type { JettonUpdate } from '@ton/walletkit';
+
+/**
+ * Finality stage carried by every streaming update — `'pending'` (in mempool), `'confirmed'` (included in a block), `'finalized'` (irreversible), or `'invalidated'` (rolled back).
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Balances
+ */
+export type { StreamingUpdateStatus } from '@ton/walletkit';
+
+/**
+ * Update payload delivered to {@link watchBalance} / {@link watchBalanceByAddress} subscribers when the watched address's TON balance changes.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Balances
+ */
+export type { BalanceUpdate } from '@ton/walletkit';
diff --git a/packages/appkit/src/core/wallets-manager/services/wallets-manager.ts b/packages/appkit/src/core/wallets-manager/services/wallets-manager.ts
index 7d4765073..e22716cf6 100644
--- a/packages/appkit/src/core/wallets-manager/services/wallets-manager.ts
+++ b/packages/appkit/src/core/wallets-manager/services/wallets-manager.ts
@@ -54,6 +54,7 @@ export class WalletsManager {
      */
     setSelectedWalletId(id: string | null): void {
         this._selectedWalletId = id;
+        this.emitter.emit(WALLETS_EVENTS.SELECTION_CHANGED, { walletId: this._selectedWalletId }, 'wallets-manager');
     }
 
     /**
@@ -70,18 +71,12 @@ export class WalletsManager {
 
         // If list is not empty, auto-select the first one
         if (wallets.length > 0) {
-            this._selectedWalletId = wallets[0].getWalletId();
-            this.emitter.emit(
-                WALLETS_EVENTS.SELECTION_CHANGED,
-                { walletId: this._selectedWalletId },
-                'wallets-manager',
-            );
+            this.setSelectedWalletId(wallets[0].getWalletId());
 
             return;
         }
 
         // Otherwise clear selection
-        this._selectedWalletId = null;
-        this.emitter.emit(WALLETS_EVENTS.SELECTION_CHANGED, { walletId: null }, 'wallets-manager');
+        this.setSelectedWalletId(null);
     }
 }
diff --git a/packages/appkit/src/crypto-onramp/index.ts b/packages/appkit/src/crypto-onramp/index.ts
index e51f9a065..8cdc60246 100644
--- a/packages/appkit/src/crypto-onramp/index.ts
+++ b/packages/appkit/src/crypto-onramp/index.ts
@@ -6,17 +6,71 @@
  *
  */
 
-export { CryptoOnrampProvider, CryptoOnrampManager, CryptoOnrampError } from '@ton/walletkit';
+/**
+ * Error thrown by {@link CryptoOnrampManager} and crypto-onramp providers — extends {@link DefiError} with `name: 'CryptoOnrampError'` and a stable `code` from the static `CryptoOnrampError.*` / `DefiError.*` constants.
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section Crypto Onramp
+ */
+export { CryptoOnrampError } from '@ton/walletkit';
+
+/**
+ * Abstract base class implemented by crypto-onramp providers (Layerswap, swaps.xyz, custom integrations); apps don't use it directly — they consume providers through {@link CryptoOnrampManager} and the `getCryptoOnramp*` / {@link createCryptoOnrampDeposit} actions.
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section Crypto Onramp
+ */
+export { CryptoOnrampProvider } from '@ton/walletkit';
 
+/**
+ * Runtime that owns registered {@link CryptoOnrampProvider}s and dispatches quote/deposit/status calls. Exposed as {@link AppKit}'s `cryptoOnrampManager`; usually accessed through the higher-level actions ({@link getCryptoOnrampQuote}, {@link createCryptoOnrampDeposit}, {@link getCryptoOnrampStatus}).
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section Crypto Onramp
+ */
+export { CryptoOnrampManager } from '@ton/walletkit';
+
+/**
+ * @extract
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
 export type {
-    CryptoOnrampAPI,
-    CryptoOnrampProviderInterface,
-    CryptoOnrampProviderMetadata,
-    CryptoOnrampProviderMetadataOverride,
     CryptoOnrampQuote,
     CryptoOnrampQuoteParams,
     CryptoOnrampDeposit,
     CryptoOnrampDepositParams,
-    CryptoOnrampStatus,
-    CryptoOnrampStatusParams,
+    CryptoOnrampProviderMetadata,
+    CryptoOnrampProviderMetadataOverride,
+    CryptoOnrampProviderInterface,
 } from '@ton/walletkit';
+
+/**
+ * Final state of a crypto-onramp deposit returned by {@link getCryptoOnrampStatus} — `'success'` (delivered to the recipient), `'pending'` (still in flight), or `'failed'` (provider could not complete the deposit).
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
+export type { CryptoOnrampStatus } from '@ton/walletkit';
+
+/**
+ * Parameters accepted by {@link getCryptoOnrampStatus} — identifies a previously created deposit and the provider that issued it.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
+export type { CryptoOnrampStatusParams } from '@ton/walletkit';
+
+// Internal-only — `CryptoOnrampAPI` is the contract `CryptoOnrampManager` satisfies, not consumed directly from `@ton/appkit`.
+export type { CryptoOnrampAPI } from '@ton/walletkit';
diff --git a/packages/appkit/src/crypto-onramp/layerswap/index.ts b/packages/appkit/src/crypto-onramp/layerswap/index.ts
index 8894baf33..0d40f901a 100644
--- a/packages/appkit/src/crypto-onramp/layerswap/index.ts
+++ b/packages/appkit/src/crypto-onramp/layerswap/index.ts
@@ -6,4 +6,56 @@
  *
  */
 
-export * from '@ton/walletkit/crypto-onramp/layerswap';
+/**
+ * {@link CryptoOnrampProvider} implementation backed by Layerswap. Use {@link createLayerswapProvider} to register it on AppKit; quote, deposit and status calls go through {@link getCryptoOnrampQuote} / {@link createCryptoOnrampDeposit} / {@link getCryptoOnrampStatus} like any other crypto-onramp provider.
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section Crypto Onramp
+ */
+export { LayerswapCryptoOnrampProvider } from '@ton/walletkit/crypto-onramp/layerswap';
+
+/**
+ * Build a Layerswap-backed {@link CryptoOnrampProvider} for AppKit; pass the result to {@link AppKitConfig}'s `providers` or {@link registerProvider}.
+ *
+ * @extract
+ * @public
+ * @category Action
+ * @section Crypto Onramp
+ */
+export { createLayerswapProvider } from '@ton/walletkit/crypto-onramp/layerswap';
+
+/**
+ * Configuration accepted by {@link createLayerswapProvider}.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
+export type { LayerswapProviderConfig } from '@ton/walletkit/crypto-onramp/layerswap';
+
+/**
+ * Provider-specific metadata returned on a {@link CryptoOnrampQuote}'s `metadata` from Layerswap — carries the swap id and deposit action that {@link createCryptoOnrampDeposit} reads to build the deposit.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
+export type { LayerswapQuoteMetadata } from '@ton/walletkit/crypto-onramp/layerswap';
+
+// Internal Layerswap response shapes — re-exported for compatibility but not surfaced in the documented reference.
+export type {
+    LayerswapToken,
+    LayerswapNetwork,
+    LayerswapDepositAction,
+    LayerswapSwap,
+    LayerswapSwapStatus,
+    LayerswapQuote,
+    LayerswapSwapData,
+    LayerswapCreateSwapResponse,
+    LayerswapGetSwapResponse,
+    LayerswapErrorResponse,
+} from '@ton/walletkit/crypto-onramp/layerswap';
diff --git a/packages/appkit/src/crypto-onramp/swaps-xyz/index.ts b/packages/appkit/src/crypto-onramp/swaps-xyz/index.ts
index 85909caad..b9e37a49d 100644
--- a/packages/appkit/src/crypto-onramp/swaps-xyz/index.ts
+++ b/packages/appkit/src/crypto-onramp/swaps-xyz/index.ts
@@ -6,4 +6,63 @@
  *
  */
 
-export * from '@ton/walletkit/crypto-onramp/swaps-xyz';
+/**
+ * {@link CryptoOnrampProvider} implementation backed by swaps.xyz. Use {@link createSwapsXyzProvider} to register it on AppKit; quote, deposit and status calls go through {@link getCryptoOnrampQuote} / {@link createCryptoOnrampDeposit} / {@link getCryptoOnrampStatus} like any other crypto-onramp provider.
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section Crypto Onramp
+ */
+export { SwapsXyzCryptoOnrampProvider } from '@ton/walletkit/crypto-onramp/swaps-xyz';
+
+/**
+ * Build a swaps.xyz-backed {@link CryptoOnrampProvider} for AppKit; pass the result to {@link AppKitConfig}'s `providers` or {@link registerProvider}.
+ *
+ * @extract
+ * @public
+ * @category Action
+ * @section Crypto Onramp
+ */
+export { createSwapsXyzProvider } from '@ton/walletkit/crypto-onramp/swaps-xyz';
+
+/**
+ * Configuration accepted by {@link createSwapsXyzProvider}.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
+export type { SwapsXyzProviderConfig } from '@ton/walletkit/crypto-onramp/swaps-xyz';
+
+/**
+ * swaps.xyz-specific options forwarded through `providerOptions` on {@link CryptoOnrampQuoteParams}.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
+export type { SwapsXyzQuoteOptions } from '@ton/walletkit/crypto-onramp/swaps-xyz';
+
+/**
+ * Provider-specific metadata returned on a {@link CryptoOnrampQuote}'s `metadata` from swaps.xyz — carries the resolved action and bridge route that {@link createCryptoOnrampDeposit} needs.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Crypto Onramp
+ */
+export type { SwapsXyzQuoteMetadata } from '@ton/walletkit/crypto-onramp/swaps-xyz';
+
+// Internal swaps.xyz response shapes — re-exported for compatibility but not surfaced in the documented reference.
+export type {
+    SwapsXyzVmId,
+    SwapsXyzSwapDirection,
+    SwapsXyzPayment,
+    SwapsXyzEvmTx,
+    SwapsXyzBridgeRouteStep,
+    SwapsXyzGetActionResponse,
+    SwapsXyzErrorResponse,
+} from '@ton/walletkit/crypto-onramp/swaps-xyz';
diff --git a/packages/appkit/src/index.ts b/packages/appkit/src/index.ts
index 5026c5cff..06c1a439c 100644
--- a/packages/appkit/src/index.ts
+++ b/packages/appkit/src/index.ts
@@ -41,7 +41,6 @@ export * from './actions';
 
 // Types
 export * from './types/connector';
-export * from './types/balance';
 export * from './types/wallet';
 export * from './types/query';
 export * from './types/utils';
@@ -51,6 +50,8 @@ export * from './types/nft';
 export * from './types/transaction';
 export * from './types/primitives';
 export * from './types/signing';
+export * from './types/provider';
+export * from './types/client';
 
 // Utils
 export * from './utils';
diff --git a/packages/appkit/src/onramp/index.ts b/packages/appkit/src/onramp/index.ts
index bed681716..b5654e95e 100644
--- a/packages/appkit/src/onramp/index.ts
+++ b/packages/appkit/src/onramp/index.ts
@@ -6,6 +6,10 @@
  *
  */
 
+// Internal-only re-exports (used by appkit code; not yet part of the public API).
+export { OnrampManager } from '@ton/walletkit';
+export type { OnrampProviderInterface, OnrampParams, OnrampQuote, OnrampQuoteParams } from '@ton/walletkit';
+
 // fiat-onramp: not ready — exported via sub-path to keep off main @ton/appkit API
 export {
     getOnrampProvider,
diff --git a/packages/appkit/src/queries/index.ts b/packages/appkit/src/queries/index.ts
index f3a487a3f..acad46aac 100644
--- a/packages/appkit/src/queries/index.ts
+++ b/packages/appkit/src/queries/index.ts
@@ -37,7 +37,7 @@ export {
     type DisconnectVariables,
 } from './connectors/disconnect';
 
-// Crypto onramp
+// Crypto Onramp
 export {
     getCryptoOnrampQuoteQueryOptions,
     type GetCryptoOnrampQuoteQueryConfig,
diff --git a/packages/appkit/src/queries/jettons/get-jetton-balance-by-address.ts b/packages/appkit/src/queries/jettons/get-jetton-balance-by-address.ts
index a42ce0555..f173386da 100644
--- a/packages/appkit/src/queries/jettons/get-jetton-balance-by-address.ts
+++ b/packages/appkit/src/queries/jettons/get-jetton-balance-by-address.ts
@@ -7,9 +7,9 @@
  */
 
 import type { QueryClient } from '@tanstack/query-core';
-import type { TokenAmount } from '@ton/walletkit';
 
 import type { AppKit } from '../../core/app-kit';
+import type { TokenAmount } from '../../types/primitives';
 import { getJettonBalance } from '../../actions/jettons/get-jetton-balance';
 import type { GetJettonBalanceOptions as GetJettonBalanceParameters } from '../../actions/jettons/get-jetton-balance';
 import type { QueryOptions, QueryParameter } from '../../types/query';
diff --git a/packages/appkit/src/queries/jettons/get-jetton-wallet-address.ts b/packages/appkit/src/queries/jettons/get-jetton-wallet-address.ts
index 1881825e1..01cc191f6 100644
--- a/packages/appkit/src/queries/jettons/get-jetton-wallet-address.ts
+++ b/packages/appkit/src/queries/jettons/get-jetton-wallet-address.ts
@@ -6,9 +6,8 @@
  *
  */
 
-import type { UserFriendlyAddress } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { UserFriendlyAddress } from '../../types/primitives';
 import { getJettonWalletAddress } from '../../actions/jettons/get-jetton-wallet-address';
 import type { GetJettonWalletAddressOptions as GetJettonWalletAddressParameters } from '../../actions/jettons/get-jetton-wallet-address';
 import type { QueryOptions, QueryParameter } from '../../types/query';
diff --git a/packages/appkit/src/queries/nft/get-nft.ts b/packages/appkit/src/queries/nft/get-nft.ts
index 4d6175b90..53a7e7d3b 100644
--- a/packages/appkit/src/queries/nft/get-nft.ts
+++ b/packages/appkit/src/queries/nft/get-nft.ts
@@ -6,9 +6,8 @@
  *
  */
 
-import type { NFT } from '@ton/walletkit';
-
 import type { AppKit } from '../../core/app-kit';
+import type { NFT } from '../../types/nft';
 import { getNft } from '../../actions/nft/get-nft';
 import type { GetNftOptions as GetNftParameters } from '../../actions/nft/get-nft';
 import type { QueryOptions, QueryParameter } from '../../types/query';
diff --git a/packages/appkit/src/staking/index.ts b/packages/appkit/src/staking/index.ts
index 4008f03cf..138df02e5 100644
--- a/packages/appkit/src/staking/index.ts
+++ b/packages/appkit/src/staking/index.ts
@@ -6,15 +6,64 @@
  *
  */
 
-export {
-    DefiError,
-    StakingProvider,
-    UnstakeMode,
-    StakingError,
-    StakingErrorCode,
-    StakingManager,
-} from '@ton/walletkit';
+// `DefiError` is shared by swap and staking; it is exported via `./swap` to keep a single declaration.
+
+/**
+ * Abstract base class implemented by staking providers (Tonstakers, custom integrations, …); apps don't use it directly — they consume providers through {@link StakingManager} and the `getStaking*` / `buildStakeTransaction` actions.
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section Staking
+ */
+export { StakingProvider } from '@ton/walletkit';
+
+/**
+ * Error thrown by {@link StakingManager} and staking providers — extends {@link DefiError} with `name: 'StakingError'` and a typed {@link StakingErrorCode} on `code`.
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section Staking
+ */
+export { StakingError } from '@ton/walletkit';
+
+/**
+ * Runtime that owns registered {@link StakingProvider}s and dispatches quote/stake/balance calls. Exposed as {@link AppKit}'s `stakingManager`; usually accessed through the higher-level actions ({@link getStakingQuote}, {@link buildStakeTransaction}, {@link getStakedBalance}).
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section Staking
+ */
+export { StakingManager } from '@ton/walletkit';
+
+/**
+ * Discriminator carried on every {@link StakingError}'s `code` — `'INVALID_PARAMS'` (the request was malformed) or `'UNSUPPORTED_OPERATION'` (the provider doesn't support this call).
+ *
+ * @extract
+ * @public
+ * @category Constants
+ * @section Staking
+ */
+export { StakingErrorCode } from '@ton/walletkit';
+
+/**
+ * Allowed unstake-timing flavours referenced by {@link UnstakeModes} and {@link StakingProviderMetadata}'s `supportedUnstakeModes` — `'INSTANT'` (immediate withdrawal when the pool has liquidity, otherwise the funds are returned), `'WHEN_AVAILABLE'` (paid out as soon as liquidity is available — instantly or at round end), `'ROUND_END'` (paid out at the end of the staking round, typically for the best rate).
+ *
+ * @extract
+ * @public
+ * @category Constants
+ * @section Staking
+ */
+export { UnstakeMode } from '@ton/walletkit';
 
+/**
+ * @extract
+ * @public
+ * @category Type
+ * @section Staking
+ */
 export type {
     UnstakeModes,
     StakeParams,
@@ -23,8 +72,19 @@ export type {
     StakingQuoteParams,
     StakingBalance,
     StakingProviderInfo,
-    StakingProviderInterface,
     StakingQuoteDirection,
     StakingProviderMetadata,
-    StakingTokenInfo,
 } from '@ton/walletkit';
+
+/**
+ * Display metadata for a staking-pool token — `ticker`, `decimals` and `address` (or `'ton'` for native TON); carried on {@link StakingProviderMetadata}'s `stakeToken` and `receiveToken` so the UI can render the pool's input/output assets.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Staking
+ */
+export type { StakingTokenInfo } from '@ton/walletkit';
+
+// Internal-only — `StakingProviderInterface` is the contract authors implement, not consumed from `@ton/appkit`.
+export type { StakingProviderInterface } from '@ton/walletkit';
diff --git a/packages/appkit/src/staking/tonstakers/index.ts b/packages/appkit/src/staking/tonstakers/index.ts
index 9b56f3973..d7529dc36 100644
--- a/packages/appkit/src/staking/tonstakers/index.ts
+++ b/packages/appkit/src/staking/tonstakers/index.ts
@@ -6,4 +6,32 @@
  *
  */
 
-export * from '@ton/walletkit/staking/tonstakers';
+/**
+ * {@link StakingProvider} implementation backed by Tonstakers. The constructor is private — use {@link createTonstakersProvider} to register it on AppKit; quote and stake calls then go through {@link getStakingQuote} / {@link buildStakeTransaction} like any other staking provider.
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section Staking
+ */
+export { TonStakersStakingProvider } from '@ton/walletkit/staking/tonstakers';
+
+/**
+ * Build a Tonstakers-backed {@link StakingProvider} for AppKit; pass the result to {@link AppKitConfig}'s `providers` or {@link registerProvider}.
+ *
+ * @extract
+ * @public
+ * @category Action
+ * @section Staking
+ */
+export { createTonstakersProvider } from '@ton/walletkit/staking/tonstakers';
+
+/**
+ * Configuration accepted by {@link createTonstakersProvider}.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Staking
+ */
+export type { TonStakersProviderConfig } from '@ton/walletkit/staking/tonstakers';
diff --git a/packages/appkit/src/swap/dedust/index.ts b/packages/appkit/src/swap/dedust/index.ts
index 46f0da4f8..30cc91b4f 100644
--- a/packages/appkit/src/swap/dedust/index.ts
+++ b/packages/appkit/src/swap/dedust/index.ts
@@ -6,4 +6,71 @@
  *
  */
 
-export * from '@ton/walletkit/swap/dedust';
+/**
+ * {@link SwapProvider} implementation backed by DeDust. Use {@link createDeDustProvider} to register it on AppKit; quote and swap calls go through {@link getSwapQuote} / {@link buildSwapTransaction} like any other swap provider.
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section Swap
+ */
+export { DeDustSwapProvider } from '@ton/walletkit/swap/dedust';
+
+/**
+ * Build a DeDust-backed {@link SwapProvider} for AppKit; pass the result to {@link AppKitConfig}'s `providers` or {@link registerProvider}.
+ *
+ * @extract
+ * @public
+ * @category Action
+ * @section Swap
+ */
+export { createDeDustProvider } from '@ton/walletkit/swap/dedust';
+
+/**
+ * Configuration accepted by {@link createDeDustProvider}.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Swap
+ */
+export type { DeDustSwapProviderConfig } from '@ton/walletkit/swap/dedust';
+
+/**
+ * DeDust-specific options forwarded through `providerOptions` on {@link SwapQuoteParams} / {@link SwapParams}.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Swap
+ */
+export type { DeDustProviderOptions } from '@ton/walletkit/swap/dedust';
+
+/**
+ * Optional referral metadata attached to DeDust swaps so the provider can attribute them.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Swap
+ */
+export type { DeDustReferralOptions } from '@ton/walletkit/swap/dedust';
+
+/**
+ * Provider-specific metadata returned on a {@link SwapQuote}'s `metadata` from DeDust — carries the resolved route, fees and `swapData` payload that {@link buildSwapTransaction} needs.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Swap
+ */
+export type { DeDustQuoteMetadata } from '@ton/walletkit/swap/dedust';
+
+// Internal — type guard for DeDust quote metadata + walletkit response shapes; re-exported for compatibility but not surfaced in the documented reference.
+export { isDeDustQuoteMetadata } from '@ton/walletkit/swap/dedust';
+export type {
+    DeDustQuoteResponse,
+    DeDustRouteStep,
+    DeDustSwapData,
+    DeDustSwapResponse,
+} from '@ton/walletkit/swap/dedust';
diff --git a/packages/appkit/src/swap/index.ts b/packages/appkit/src/swap/index.ts
index 4209e845c..5a2faa82e 100644
--- a/packages/appkit/src/swap/index.ts
+++ b/packages/appkit/src/swap/index.ts
@@ -6,15 +6,125 @@
  *
  */
 
-export { DefiError, SwapError, SwapProvider, SwapManager } from '@ton/walletkit';
-
-export type {
-    SwapToken,
-    TokenAmount,
-    SwapParams,
-    SwapAPI,
-    SwapQuote,
-    SwapQuoteParams,
-    DefiManagerAPI,
-    DefiProvider,
-} from '@ton/walletkit';
+/**
+ * Base error thrown across all DeFi domains (swap, staking, onramp, crypto-onramp). Subclassed by {@link SwapError}, {@link StakingError}, {@link CryptoOnrampError} and the internal onramp error — catch the base when you don't care which domain produced the failure.
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section DeFi
+ */
+export { DefiError } from '@ton/walletkit';
+
+/**
+ * Error thrown by {@link SwapManager} and swap providers — extends {@link DefiError} with `name: 'SwapError'` and a stable `code` from the static `SwapError.*` / `DefiError.*` constants.
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section Swap
+ */
+export { SwapError } from '@ton/walletkit';
+
+/**
+ * Abstract base class implemented by swap providers (DeDust, Omniston, custom integrations); apps don't use it directly — they consume providers through {@link SwapManager} and the `getSwap*` / `buildSwapTransaction` actions.
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section Swap
+ */
+export { SwapProvider } from '@ton/walletkit';
+
+/**
+ * Runtime that owns registered {@link SwapProvider}s and dispatches quote/swap calls. Exposed as {@link AppKit}'s `swapManager`; usually accessed through the higher-level actions ({@link getSwapQuote}, {@link buildSwapTransaction}).
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section Swap
+ */
+export { SwapManager } from '@ton/walletkit';
+
+/**
+ * Shape every DeFi domain manager (swap, staking, onramp, crypto-onramp) satisfies — provider registration, default-provider selection and lookups; mostly relevant when authoring a new domain manager.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section DeFi
+ */
+export type { DefiManagerAPI } from '@ton/walletkit';
+
+/**
+ * Base interface implemented by every DeFi provider (swap, staking, onramp, crypto-onramp) — exposes `providerId`, `type` and `getSupportedNetworks`. Domain-specific provider interfaces extend this with quote/build/status methods.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section DeFi
+ */
+export type { DefiProvider } from '@ton/walletkit';
+
+/**
+ * Discriminator that tags every {@link DefiProvider} with its kind — `'swap'`, `'staking'`, `'onramp'`, or `'crypto-onramp'`; used by {@link registerProvider} to dispatch to the right manager.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section DeFi
+ */
+export type { DefiProviderType } from '@ton/walletkit';
+
+/**
+ * Token descriptor passed to {@link getSwapQuote} via {@link SwapQuoteParams}'s `from` and `to` fields (and surfaced on the resulting {@link SwapQuote}) — address, decimals plus optional symbol/name/image used by swap-input UIs.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Swap
+ */
+export type { SwapToken } from '@ton/walletkit';
+
+/**
+ * Parameters consumed by {@link buildSwapTransaction} — the previously obtained {@link SwapQuote} plus optional provider-specific options (`TProviderOptions`).
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Swap
+ */
+export type { SwapParams } from '@ton/walletkit';
+
+/**
+ * API surface exposed by {@link SwapManager} — quote and build-transaction calls (plus the provider-management methods inherited from {@link DefiManagerAPI}). Mostly relevant when authoring a swap manager replacement.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Swap
+ */
+export type { SwapAPI } from '@ton/walletkit';
+
+/**
+ * Quote returned by {@link getSwapQuote} — source/target tokens, expected amounts, rate, slippage, fees and the provider-specific `metadata` that {@link buildSwapTransaction} needs to construct the transaction.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Swap
+ */
+export type { SwapQuote } from '@ton/walletkit';
+
+/**
+ * Parameters consumed by {@link getSwapQuote} — source/target tokens and an amount that is interpreted as either the spend side or the receive side (`isReverseSwap` flag), plus optional slippage and provider-specific options.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Swap
+ */
+export type { SwapQuoteParams } from '@ton/walletkit';
+
+// Internal-only — `SwapProviderInterface` is the contract authors implement, not consumed from `@ton/appkit`.
+export type { SwapProviderInterface } from '@ton/walletkit';
diff --git a/packages/appkit/src/swap/omniston/index.ts b/packages/appkit/src/swap/omniston/index.ts
index c623c0c9c..b7cc8d014 100644
--- a/packages/appkit/src/swap/omniston/index.ts
+++ b/packages/appkit/src/swap/omniston/index.ts
@@ -6,4 +6,62 @@
  *
  */
 
-export * from '@ton/walletkit/swap/omniston';
+/**
+ * {@link SwapProvider} implementation backed by Omniston. Use {@link createOmnistonProvider} to register it on AppKit; quote and swap calls go through {@link getSwapQuote} / {@link buildSwapTransaction} like any other swap provider.
+ *
+ * @extract
+ * @public
+ * @category Class
+ * @section Swap
+ */
+export { OmnistonSwapProvider } from '@ton/walletkit/swap/omniston';
+
+/**
+ * Build an Omniston-backed {@link SwapProvider} for AppKit; pass the result to {@link AppKitConfig}'s `providers` or {@link registerProvider}.
+ *
+ * @extract
+ * @public
+ * @category Action
+ * @section Swap
+ */
+export { createOmnistonProvider } from '@ton/walletkit/swap/omniston';
+
+/**
+ * Configuration accepted by {@link createOmnistonProvider}.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Swap
+ */
+export type { OmnistonSwapProviderConfig } from '@ton/walletkit/swap/omniston';
+
+/**
+ * Omniston-specific options forwarded through `providerOptions` on {@link SwapQuoteParams} / {@link SwapParams}.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Swap
+ */
+export type { OmnistonProviderOptions } from '@ton/walletkit/swap/omniston';
+
+/**
+ * Optional referrer metadata attached to Omniston swaps so the provider can attribute them.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Swap
+ */
+export type { OmnistonReferrerOptions } from '@ton/walletkit/swap/omniston';
+
+/**
+ * Provider-specific metadata returned on a {@link SwapQuote}'s `metadata` from Omniston — carries the resolved route and signed quote payload that {@link buildSwapTransaction} needs.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Swap
+ */
+export type { OmnistonQuoteMetadata } from '@ton/walletkit/swap/omniston';
diff --git a/packages/appkit/src/types/balance.ts b/packages/appkit/src/types/api-client.ts
similarity index 65%
rename from packages/appkit/src/types/balance.ts
rename to packages/appkit/src/types/api-client.ts
index 27f18d1ab..a14dab9d0 100644
--- a/packages/appkit/src/types/balance.ts
+++ b/packages/appkit/src/types/api-client.ts
@@ -6,6 +6,4 @@
  *
  */
 
-import type { TokenAmount } from '@ton/walletkit';
-
-export type Balance = TokenAmount;
+export { ApiClient } from '@ton/walletkit';
diff --git a/packages/appkit/src/types/client.ts b/packages/appkit/src/types/client.ts
new file mode 100644
index 000000000..1edf6dfe3
--- /dev/null
+++ b/packages/appkit/src/types/client.ts
@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+/**
+ * Display metadata for a token (TON, jetton, or NFT) — name, symbol, image and animation as reported by the indexer; surfaced as {@link Jetton}'s `info` and {@link NFT}'s `info`.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Client
+ */
+export type { TokenInfo } from '@ton/walletkit';
+
+/**
+ * Map of raw addresses to their resolved metadata, returned alongside indexed lists (e.g. {@link JettonsResponse}, {@link NFTsResponse}) so consumers can render labels without extra lookups.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Client
+ */
+export type { AddressBook } from '@ton/walletkit';
+
+/**
+ * Single entry inside an {@link AddressBook} — pairs the user-friendly address with optional domain name and the list of contract interfaces it implements.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Client
+ */
+export type { AddressBookEntry } from '@ton/walletkit';
diff --git a/packages/appkit/src/types/connector.ts b/packages/appkit/src/types/connector.ts
index 834cf92a0..fc16f9f0f 100644
--- a/packages/appkit/src/types/connector.ts
+++ b/packages/appkit/src/types/connector.ts
@@ -12,51 +12,93 @@ import type { AppKitNetworkManager } from '../core/network';
 import type { Network } from './network';
 
 /**
- * Interface for wallet connectors
+ * Wallet connector contract — the protocol-specific bridge (TonConnect, embedded wallet, …) AppKit drives once you register it via {@link AppKitConfig}'s `connectors`.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
  */
 export interface Connector {
-    /** Provider unique identifier */
+    /** Stable connector identifier, unique within an AppKit instance. */
     readonly id: string;
 
-    /** Protocol type (e.g. 'tonconnect') */
+    /** Protocol type (e.g. `'tonconnect'`). Multiple connectors can share the same type. */
     readonly type: string;
 
+    /** Display metadata (name, icon) shown in connect UIs. */
     readonly metadata: ConnectorMetadata;
 
-    /** Cleanup connector resources */
+    /** Release any resources held by the connector. Call on app teardown. */
     destroy(): void;
 
-    /** Connect a wallet */
+    /** Initiate a wallet connection flow on the given network. */
     connectWallet(network?: Network): Promise<void>;
 
-    /** Disconnect a wallet */
+    /** Disconnect the currently connected wallet, if any. */
     disconnectWallet(): Promise<void>;
 
-    /** Get connected wallets */
+    /** Wallets currently connected through this connector. */
     getConnectedWallets(): WalletInterface[];
 }
 
+/**
+ * Display metadata for a {@link Connector}, surfaced in connect UIs to help users pick the right wallet.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export interface ConnectorMetadata {
+    /** Human-readable connector name (e.g., `'TonConnect'`). */
     name: string;
+    /** Optional URL of an icon shown next to the name. */
     iconUrl?: string;
 }
 
 /**
- * Context passed to connector factory functions.
+ * Context that AppKit injects into a {@link ConnectorFactory} when building the connector at registration time.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
  */
 export interface ConnectorFactoryContext {
+    /** Network manager the connector should use for client lookups and default-network reads. */
     networkManager: AppKitNetworkManager;
+    /** Event emitter the connector should publish wallet/connection events to. */
     eventEmitter: AppKitEmitter;
+    /** `true` when the connector is constructed during server-side rendering — connectors may skip browser-only setup. */
     ssr?: boolean;
 }
 
-/** Factory function that creates a connector from context */
+/**
+ * Factory that builds a {@link Connector} from {@link ConnectorFactoryContext}; AppKit calls it at registration time.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export type ConnectorFactory = (ctx: ConnectorFactoryContext) => Connector;
 
-/** A connector instance or a factory that creates one */
+/**
+ * Either a ready-made {@link Connector} or a {@link ConnectorFactory} that produces one — the value accepted by {@link addConnector} and {@link AppKitConfig}'s `connectors`.
+ *
+ * @public
+ * @category Type
+ * @section Connectors
+ */
 export type ConnectorInput = Connector | ConnectorFactory;
 
-/** Helper for creating typed connector factories */
+/**
+ * Identity helper for typing a {@link ConnectorFactory} inline — returns the factory unchanged so authors get parameter inference without spelling the type out.
+ *
+ * @param factory - {@link ConnectorFactory} Factory to wrap.
+ * @returns The same factory, typed as {@link ConnectorFactory}.
+ *
+ * @public
+ * @category Action
+ * @section Connectors
+ */
 export const createConnector = (factory: ConnectorFactory): ConnectorFactory => {
     return factory;
 };
diff --git a/packages/appkit/src/types/jetton.ts b/packages/appkit/src/types/jetton.ts
index ed0191fa1..bb28a5984 100644
--- a/packages/appkit/src/types/jetton.ts
+++ b/packages/appkit/src/types/jetton.ts
@@ -6,4 +6,42 @@
  *
  */
 
-export type { Jetton, JettonInfo } from '@ton/walletkit';
+/**
+ * Fungible TEP-74 token held in the user's TON wallet — carries the master contract address, the user's jetton-wallet address, current balance, and token metadata.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Jettons
+ */
+export type { Jetton } from '@ton/walletkit';
+
+/**
+ * Token metadata for a jetton master — name, symbol, decimals, image, and verification status as reported by the indexer.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Jettons
+ */
+export type { JettonInfo } from '@ton/walletkit';
+
+/**
+ * Response payload of {@link getJettons} / {@link getJettonsByAddress} — the list of {@link Jetton}s plus the address book that resolves raw addresses inside it.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Jettons
+ */
+export type { JettonsResponse } from '@ton/walletkit';
+
+/**
+ * Verification metadata reported by the indexer for a {@link JettonInfo} — `verified` flag plus optional verifier source.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Jettons
+ */
+export type { JettonVerification } from '@ton/walletkit';
diff --git a/packages/appkit/src/types/network.ts b/packages/appkit/src/types/network.ts
index 006b43054..1e190460c 100644
--- a/packages/appkit/src/types/network.ts
+++ b/packages/appkit/src/types/network.ts
@@ -6,4 +6,30 @@
  *
  */
 
-export { Network } from '@ton/walletkit';
+/**
+ * @extract
+ * @public
+ * @category Type
+ * @section Networks
+ */
+export { Network, NetworkAdapters, NetworkConfig } from '@ton/walletkit';
+
+/**
+ * Configuration accepted by {@link NetworkConfig}'s `apiClient` — picks an {@link ApiClient} implementation (Toncenter / TonAPI) and supplies its endpoint URL plus optional API key.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Client
+ */
+export { ApiClientConfig } from '@ton/walletkit';
+
+/**
+ * Walletkit-side options shape consumed by {@link KitNetworkManager}'s constructor — chiefly the `networks` map keyed by chain ID. {@link AppKit} constructs the manager for you, so apps rarely instantiate this directly.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Networks
+ */
+export type { TonWalletKitOptions } from '@ton/walletkit';
diff --git a/packages/appkit/src/types/nft.ts b/packages/appkit/src/types/nft.ts
index dd057ba05..a147728a3 100644
--- a/packages/appkit/src/types/nft.ts
+++ b/packages/appkit/src/types/nft.ts
@@ -6,4 +6,42 @@
  *
  */
 
+/**
+ * Non-fungible TEP-62 token held in the user's TON wallet — carries the contract address, optional collection link, owner, sale state, and on-chain metadata.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section NFTs
+ */
 export type { NFT } from '@ton/walletkit';
+
+/**
+ * Response payload of {@link getNfts} / {@link getNftsByAddress} — the list of {@link NFT}s plus an address book that resolves raw addresses inside it.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section NFTs
+ */
+export type { NFTsResponse } from '@ton/walletkit';
+
+/**
+ * Single trait of an {@link NFT} — `traitType` names the category (e.g., `"Background"`), `value` carries the trait's value (e.g., `"Blue"`).
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section NFTs
+ */
+export type { NFTAttribute } from '@ton/walletkit';
+
+/**
+ * NFT collection (TEP-62) — surfaced as {@link NFT}'s `collection` and carries the collection's name, image, owner and minting cursor.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section NFTs
+ */
+export type { NFTCollection } from '@ton/walletkit';
diff --git a/packages/appkit/src/types/primitives.ts b/packages/appkit/src/types/primitives.ts
index 62317acb4..f61c427b8 100644
--- a/packages/appkit/src/types/primitives.ts
+++ b/packages/appkit/src/types/primitives.ts
@@ -6,4 +6,52 @@
  *
  */
 
+/**
+ * Map of extra-currency ids to raw amounts attached to a transaction message — TON's mechanism for transferring non-jetton native tokens (e.g., wrapped or testnet currencies). Keys are the extra-currency ids defined by the masterchain configuration.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Primitives
+ */
+export type { ExtraCurrencies } from '@ton/walletkit';
+
+/**
+ * Base64-encoded byte string — used for transaction payloads, BoCs, signatures, and other opaque binary blobs that travel through TonConnect and the indexer APIs.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Primitives
+ */
 export type { Base64String } from '@ton/walletkit';
+
+/**
+ * `0x`-prefixed hexadecimal string used for public keys and other hashes.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Primitives
+ */
+export type { Hex } from '@ton/walletkit';
+
+/**
+ * Decimal string carrying a token amount; preserves precision and avoids floating-point rounding (e.g., `"1.5"` TON, or raw nano units depending on the API).
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Primitives
+ */
+export type { TokenAmount } from '@ton/walletkit';
+
+/**
+ * User-friendly TON wallet address as a base64url string (e.g., `"EQDtFp...4q2"`).
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Primitives
+ */
+export type { UserFriendlyAddress } from '@ton/walletkit';
diff --git a/packages/appkit/src/types/provider.ts b/packages/appkit/src/types/provider.ts
index 51d5748df..334de7436 100644
--- a/packages/appkit/src/types/provider.ts
+++ b/packages/appkit/src/types/provider.ts
@@ -6,9 +6,30 @@
  *
  */
 
-import type { SwapProviderInterface, StakingProviderInterface } from '@ton/walletkit';
+import type { SwapProviderInterface } from '../swap';
+import type { StakingProviderInterface } from '../staking';
 
 /**
- * Provider configuration
+ * Internal union of registerable DeFi provider instances (swap or staking) — used to type provider-related collections inside AppKit.
  */
 export type Provider = SwapProviderInterface | StakingProviderInterface;
+
+/**
+ * Either a ready-made DeFi/onramp provider instance or a factory that produces one — the value accepted by {@link AppKitConfig}'s `providers` and {@link registerProvider}.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section DeFi
+ */
+export type { ProviderInput } from '@ton/walletkit';
+
+/**
+ * Context that AppKit's DeFi managers inject into a {@link ProviderInput} factory at registration time — gives the provider access to AppKit's network manager and event emitter, plus an `ssr` flag for server-side initialisation.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section DeFi
+ */
+export type { ProviderFactoryContext } from '@ton/walletkit';
diff --git a/packages/appkit/src/types/query.ts b/packages/appkit/src/types/query.ts
index 1ce879206..6671ef600 100644
--- a/packages/appkit/src/types/query.ts
+++ b/packages/appkit/src/types/query.ts
@@ -11,6 +11,7 @@ import type * as Query from '@tanstack/query-core';
 import type { Compute, LooseOmit, RequiredBy, UnionLooseOmit } from './utils.js';
 
 export type MutationParameter<data = unknown, error = Error, variables = void, context = unknown> = {
+    /** TanStack Query mutation options forwarded to `useMutation` (`onSuccess`, `onError`, `onMutate`, `retry`, …); `mutationFn`, `mutationKey` and `throwOnError` are managed by the wrapper. */
     mutation?:
         | LooseOmit<
               Query.MutationOptions<data, error, Compute<variables>, context>,
@@ -25,6 +26,7 @@ export type QueryParameter<
     data = queryFnData,
     queryKey extends Query.QueryKey = Query.QueryKey,
 > = {
+    /** TanStack Query options forwarded to `useQuery` (`enabled`, `staleTime`, `refetchInterval`, `select`, …); `queryKey` and `queryFn` are managed by the wrapper. */
     query?: UnionLooseOmit<QueryOptions<queryFnData, error, data, queryKey>, 'queryKey' | 'queryFn'> | undefined;
 };
 
diff --git a/packages/appkit/src/types/signing.ts b/packages/appkit/src/types/signing.ts
index c97fc2403..153a1331e 100644
--- a/packages/appkit/src/types/signing.ts
+++ b/packages/appkit/src/types/signing.ts
@@ -12,7 +12,11 @@ import type { Base64String } from './primitives';
 // SignData types for wallet adapter
 
 /**
- * Data to be signed by the wallet, discriminated by type.
+ * Payload the user is asked to sign — discriminated union over `'text'`, `'binary'`, and `'cell'`; nested under {@link SignDataRequest}'s `data`.
+ *
+ * @public
+ * @category Type
+ * @section Signing
  */
 export type SignData =
     | { type: 'text'; value: SignDataText }
@@ -20,59 +24,75 @@ export type SignData =
     | { type: 'cell'; value: SignDataCell };
 
 /**
- * Binary data to be signed.
+ * Binary variant of {@link SignData} — opaque byte content the user is asked to sign.
+ *
+ * @public
+ * @category Type
+ * @section Signing
  */
 export interface SignDataBinary {
-    /**
-     * Raw binary content encoded as bytes in Base64
-     */
+    /** Raw binary content encoded as Base64. */
     content: Base64String;
 }
 
 /**
- * TON Cell data to be signed with a schema definition.
+ * TON cell variant of {@link SignData} — Base64-encoded cell payload paired with the schema needed to parse it.
+ *
+ * @public
+ * @category Type
+ * @section Signing
  */
 export interface SignDataCell {
-    /**
-     * Schema describing the cell structure for parsing
-     */
+    /** TL-B-style schema describing the cell layout so the wallet can render the payload to the user. */
     schema: string;
-    /**
-     * Cell content encoded in Base64
-     */
+    /** Cell content encoded as Base64. */
     content: Base64String;
 }
 
 /**
- * Plain text data to be signed.
+ * Plain-text variant of {@link SignData} — UTF-8 string the user is asked to sign.
+ *
+ * @public
+ * @category Type
+ * @section Signing
  */
 export interface SignDataText {
-    /**
-     * Text content to be signed
-     */
+    /** UTF-8 text the user signs. */
     content: string;
 }
 
-/** SignData Request Payload - sent to wallet */
+/**
+ * Sign-data payload sent to {@link WalletInterface}'s `signData` — discriminated by `data.type` (`'text'`, `'binary'`, or `'cell'`).
+ *
+ * @public
+ * @category Type
+ * @section Signing
+ */
 export interface SignDataRequest {
-    /** Network */
+    /** Network to issue the sign request against; defaults to the wallet's current network. */
     network?: Network;
-    /** Sender address in raw format */
+    /** Sender address in raw format; usually omitted, the wallet fills it in. */
     from?: string;
-    /** Data to sign */
+    /** Payload the user is asked to sign. */
     data: SignData;
 }
 
-/** SignData Response - returned from wallet */
+/**
+ * Wallet response to a {@link SignDataRequest} — carries the signature plus the canonicalized address, timestamp, and domain the wallet committed to.
+ *
+ * @public
+ * @category Type
+ * @section Signing
+ */
 export interface SignDataResponse {
-    /** Base64 encoded signature */
+    /** Base64-encoded signature. */
     signature: string;
-    /** Wallet address that signed */
+    /** Wallet address that signed, in user-friendly format. */
     address: string;
-    /** Unix timestamp when signed */
+    /** Unix timestamp the wallet stamped onto the signature. */
     timestamp: number;
-    /** Domain of the dApp */
+    /** dApp domain the wallet bound the signature to. */
     domain: string;
-    /** Original payload that was signed */
+    /** Original payload that was signed, echoed back for binding. */
     payload: SignDataRequest;
 }
diff --git a/packages/appkit/src/types/transaction.ts b/packages/appkit/src/types/transaction.ts
index 0255b717b..783389679 100644
--- a/packages/appkit/src/types/transaction.ts
+++ b/packages/appkit/src/types/transaction.ts
@@ -6,60 +6,62 @@
  *
  */
 
-import type { ExtraCurrencies, TokenAmount } from '@ton/walletkit';
-
+import type { ExtraCurrencies, TokenAmount } from './primitives';
 import type { Network } from './network';
 
-export type { TransactionStatus } from '@ton/walletkit';
+export type { TransactionStatus, TransactionStatusResponse } from '@ton/walletkit';
+
+/**
+ * Wallet response carrying the BoC (bag of cells) of the external message that was signed and broadcast — used to track or hash the resulting transaction.
+ *
+ * @extract
+ * @public
+ * @category Type
+ * @section Transactions
+ */
+export type { SendTransactionResponse } from '@ton/walletkit';
 
+/**
+ * Transaction payload passed to {@link WalletInterface}'s `sendTransaction` — one or more messages, optional network override and `validUntil` deadline.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
+ */
 export interface TransactionRequest {
-    /**
-     * List of messages to include in the transaction
-     */
+    /** Messages to include in the transaction. */
     messages: TransactionRequestMessage[];
 
-    /**
-     * Network to execute the transaction on
-     */
+    /** Network to execute the transaction on. */
     network?: Network;
 
-    /**
-     * Unix timestamp after which the transaction becomes invalid
-     */
+    /** Unix timestamp (seconds) after which the transaction becomes invalid. */
     validUntil?: number;
 
-    /**
-     * Sender wallet address in received format(raw, user friendly)
-     */
+    /** Sender wallet address — accepts either raw or user-friendly format. */
     fromAddress?: string;
 }
 
 /**
- * Individual message within a transaction request.
+ * Individual message inside a {@link TransactionRequest} — recipient, amount, optional payload and contract `stateInit`.
+ *
+ * @public
+ * @category Type
+ * @section Transactions
  */
 export interface TransactionRequestMessage {
-    /**
-     * Recipient wallet address in format received from caller (raw, user friendly)
-     */
+    /** Recipient wallet address — accepts either raw or user-friendly format. */
     address: string;
 
-    /**
-     * Amount to transfer in nanos
-     */
+    /** Amount to transfer, in nano-TON (1 TON = 10⁹ nano-TON). */
     amount: TokenAmount;
 
-    /**
-     * Additional currencies to include in the transfer
-     */
+    /** Additional currencies to include in the transfer. */
     extraCurrency?: ExtraCurrencies;
 
-    /**
-     * Initial state for deploying a new contract, encoded in Base64
-     */
+    /** Initial state for deploying a new contract, encoded as Base64. */
     stateInit?: string;
 
-    /**
-     * Message payload data encoded in Base64
-     */
+    /** Message payload, encoded as Base64. */
     payload?: string;
 }
diff --git a/packages/appkit/src/types/wallet.ts b/packages/appkit/src/types/wallet.ts
index 81f42030f..12a787b78 100644
--- a/packages/appkit/src/types/wallet.ts
+++ b/packages/appkit/src/types/wallet.ts
@@ -6,44 +6,37 @@
  *
  */
 
-import type { SendTransactionResponse, Hex, UserFriendlyAddress } from '@ton/walletkit';
-
-import type { TransactionRequest } from './transaction';
+import type { Hex, UserFriendlyAddress } from './primitives';
+import type { TransactionRequest, SendTransactionResponse } from './transaction';
 import type { SignDataRequest, SignDataResponse } from './signing';
 import type { Network } from './network';
 
 /**
- * Minimal wallet interface for appkit.
- * Only includes methods that require wallet-specific logic (signing, identity).
- * Data fetching (balance, jettons, nfts) is done via actions using networkManager.
+ * Wallet contract surfaced by every {@link Connector} — covers identity (address, public key, network) and signing operations; reads (balance, jettons, NFTs) go through AppKit actions instead.
+ *
+ * @public
+ * @category Type
+ * @section Wallets
  */
 export interface WalletInterface {
-    /** Connector that created this wallet */
+    /** ID of the {@link Connector} that produced this wallet. */
     readonly connectorId: string;
 
-    // ==========================================
-    // Identity
-    // ==========================================
-
-    /** Get the wallet address */
+    /** Wallet address as a user-friendly base64url string. */
     getAddress(): UserFriendlyAddress;
 
-    /** Get the wallet public key */
+    /** Wallet public key as a `0x`-prefixed hex string. */
     getPublicKey(): Hex;
 
-    /** Get the network the wallet is connected to */
+    /** Network the wallet is currently connected to. */
     getNetwork(): Network;
 
-    /** Get unique wallet identifier */
+    /** Stable identifier combining address and network — unique across AppKit's connected wallets. */
     getWalletId(): string;
 
-    // ==========================================
-    // Actions requiring wallet signature
-    // ==========================================
-
-    /** Send a transaction (wallet signs and submits) */
+    /** Send a transaction — the wallet signs and broadcasts it. */
     sendTransaction(request: TransactionRequest): Promise<SendTransactionResponse>;
 
-    /** Sign arbitrary data using TonConnect signData */
+    /** Sign arbitrary data — text, binary or TON cell — through the wallet's sign-data flow. */
     signData(payload: SignDataRequest): Promise<SignDataResponse>;
 }
diff --git a/packages/appkit/src/utils/amount/calc-fiat-value.ts b/packages/appkit/src/utils/amount/calc-fiat-value.ts
index 8fc9de483..0fcbc2f65 100644
--- a/packages/appkit/src/utils/amount/calc-fiat-value.ts
+++ b/packages/appkit/src/utils/amount/calc-fiat-value.ts
@@ -7,8 +7,7 @@
  */
 
 /**
- * Calculates the fiat value of a token amount.
- * Returns null when rate is unavailable or amount is zero/invalid.
+ * Calculates the fiat value of a token amount. Returns `'0'` when the rate is unavailable or the amount is zero/invalid.
  */
 export const calcFiatValue = (amount: string, rate: string | undefined): string => {
     if (!rate) return '0';
diff --git a/packages/appkit/src/utils/balance/calc-max-spendable.ts b/packages/appkit/src/utils/balance/calc-max-spendable.ts
index 6b1a2533b..066cbe027 100644
--- a/packages/appkit/src/utils/balance/calc-max-spendable.ts
+++ b/packages/appkit/src/utils/balance/calc-max-spendable.ts
@@ -6,7 +6,7 @@
  *
  */
 
-import { formatUnits, parseUnits } from '@ton/walletkit';
+import { formatUnits, parseUnits } from '..';
 
 /**
  * Default TON reserve subtracted from balance when computing the max spendable amount
@@ -27,9 +27,9 @@ export interface CalcMaxSpendableParams {
 }
 
 /**
- * Compute the max spendable amount a user can place into an input when they click MAX.
- * For native TON — subtracts a fixed reserve so the user still has room for network fees.
- * For jettons — returns the full balance (gas is paid from TON separately).
+ * Compute the max amount a user can spend — used to populate the input when the user clicks MAX.
+ * For native TON: subtracts a fixed reserve so the user still has room for network fees.
+ * For jettons: returns the full balance (gas is paid from TON separately).
  */
 export const calcMaxSpendable = ({
     balance,
diff --git a/packages/appkit/src/utils/balance/get-ton-shortfall.ts b/packages/appkit/src/utils/balance/get-ton-shortfall.ts
index 732bd6336..5c2d66be9 100644
--- a/packages/appkit/src/utils/balance/get-ton-shortfall.ts
+++ b/packages/appkit/src/utils/balance/get-ton-shortfall.ts
@@ -6,7 +6,7 @@
  *
  */
 
-import { formatUnits, parseUnits } from '@ton/walletkit';
+import { formatUnits, parseUnits } from '..';
 
 /** Default extra TON buffer added on top of built transaction outflow when checking balance before sending. */
 export const DEFAULT_GAS_BUFFER_NANOS = 100_000_000n;
@@ -45,7 +45,7 @@ export interface GetTonShortfallParams {
 
 /**
  * Check whether the user's TON balance covers the built transaction.
- * - Returns `null` if the balance is sufficient.
+ * - Returns `undefined` if the balance is sufficient.
  * - Returns `{ mode: 'reduce', ... }` with a smaller suggested `fromAmount` when `fromToken` is TON
  *   and the balance is enough to cover at least gas (user can fix it by reducing the amount).
  * - Returns `{ mode: 'topup', ... }` when `fromToken` is a jetton (reducing jetton amount won't free up TON gas),
diff --git a/packages/appkit/src/utils/functions/debounce.ts b/packages/appkit/src/utils/functions/debounce.ts
index 29e3166b5..aa9f9e46a 100644
--- a/packages/appkit/src/utils/functions/debounce.ts
+++ b/packages/appkit/src/utils/functions/debounce.ts
@@ -49,9 +49,8 @@ export interface DebouncedFunction<F extends (...args: unknown[]) => void> {
 }
 
 /**
- * Creates a debounced function that delays invoking the provided function until after `debounceMs` milliseconds
- * have elapsed since the last time the debounced function was invoked. The debounced function also has a `cancel`
- * method to cancel any pending execution.
+ * Creates a debounced function that delays invoking `func` until `debounceMs` milliseconds have elapsed since the
+ * last call. The returned function exposes `cancel`, `schedule`, and `flush` for manual control.
  *
  * @template F - The type of function.
  * @param {F} func - The function to debounce.
diff --git a/packages/appkit/src/utils/index.ts b/packages/appkit/src/utils/index.ts
index 20ade7b66..bb81f623f 100644
--- a/packages/appkit/src/utils/index.ts
+++ b/packages/appkit/src/utils/index.ts
@@ -6,7 +6,26 @@
  *
  */
 
-export { formatUnits, parseUnits, compareAddress } from '@ton/walletkit';
+export {
+    formatUnits,
+    parseUnits,
+    compareAddress,
+    asHex,
+    createWalletId,
+    getNormalizedExtMessageHash,
+    createCommentPayloadBase64,
+    createJettonTransferPayload,
+    createNftTransferPayload,
+    createTransferTransaction,
+    DEFAULT_JETTON_GAS_FEE,
+    DEFAULT_NFT_GAS_FEE,
+    getJettonBalanceFromClient,
+    getJettonWalletAddressFromClient,
+    getJettonsFromClient,
+    getNftFromClient,
+    getNftsFromClient,
+    getTransactionStatus as getTransactionStatusFromClient,
+} from '@ton/walletkit';
 
 export * from './address/format';
 export * from './amount/calc-fiat-value';
diff --git a/packages/appkit/src/utils/jetton/jetton-info.ts b/packages/appkit/src/utils/jetton/jetton-info.ts
index 02972ba34..3ce921407 100644
--- a/packages/appkit/src/utils/jetton/jetton-info.ts
+++ b/packages/appkit/src/utils/jetton/jetton-info.ts
@@ -6,7 +6,7 @@
  *
  */
 
-import type { Jetton } from '@ton/walletkit';
+import type { Jetton } from '../../types/jetton';
 
 export const getJettonsSymbol = (jetton: Jetton): string | undefined => {
     if (!jetton?.info?.symbol) {
diff --git a/packages/appkit/src/utils/network/resolve-network.ts b/packages/appkit/src/utils/network/resolve-network.ts
index 91ddf1111..76e68ded1 100644
--- a/packages/appkit/src/utils/network/resolve-network.ts
+++ b/packages/appkit/src/utils/network/resolve-network.ts
@@ -18,7 +18,7 @@ import { getDefaultNetwork } from '../../actions/network/get-default-network';
  * 1. Explicitly passed `network` parameter
  * 2. Selected wallet's network
  * 3. Configured default network
- * 4. Mainnet (last resort)
+ * 4. Mainnet, when nothing else is configured.
  */
 export const resolveNetwork = (appKit: AppKit, network?: Network): Network => {
     if (network) return network;
diff --git a/packages/appkit/src/utils/nft/nft-info.ts b/packages/appkit/src/utils/nft/nft-info.ts
index 7added6e9..5ef95d89c 100644
--- a/packages/appkit/src/utils/nft/nft-info.ts
+++ b/packages/appkit/src/utils/nft/nft-info.ts
@@ -6,8 +6,7 @@
  *
  */
 
-import type { NFT } from '@ton/walletkit';
-
+import type { NFT } from '../../types/nft';
 import { middleEllipsis } from '../string/middle-ellipsis';
 
 export const getNftImage = (nft: NFT): string | null => {
diff --git a/packages/mcp/src/tools/wallet-management-tools.ts b/packages/mcp/src/tools/wallet-management-tools.ts
index 82b291548..97ffefb79 100644
--- a/packages/mcp/src/tools/wallet-management-tools.ts
+++ b/packages/mcp/src/tools/wallet-management-tools.ts
@@ -60,11 +60,11 @@ const setNetworkConfigSchema = z.object({
 });
 
 const setActiveWalletSchema = z.object({
-    walletSelector: z.string().min(1).describe('Wallet id, name, or address'),
+    walletSelector: z.string().min(1).describe('Wallet ID, name, or address'),
 });
 
 const removeWalletSchema = z.object({
-    walletSelector: z.string().min(1).describe('Wallet id, name, or address to remove'),
+    walletSelector: z.string().min(1).describe('Wallet ID, name, or address to remove'),
 });
 
 const validateAgenticWalletSchema = z.object({
diff --git a/packages/walletkit/README.md b/packages/walletkit/README.md
index 6b461544d..492b7bcdc 100644
--- a/packages/walletkit/README.md
+++ b/packages/walletkit/README.md
@@ -1,7 +1,7 @@
 <!--
 This file is auto-generated. Do not edit manually.
 Changes will be overwritten when running the docs update script.
-Source template: template/packages/walletkit/README.md
+Source template: docs/templates/packages/walletkit/README.md
 -->
 
 # TonWalletKit
@@ -213,7 +213,7 @@ if (!wallet) {
 }
 // Query balance
 const balance = await wallet.getBalance();
-console.log('WalletBalance', wallet.getAddress(), balance.toString());
+console.log('WalletBalance', wallet.getAddress(), balance);
 ```
 
 ### Rendering previews (reference)
diff --git a/packages/walletkit/src/api/interfaces/CryptoOnrampAPI.ts b/packages/walletkit/src/api/interfaces/CryptoOnrampAPI.ts
index 80b3f086c..acd81d490 100644
--- a/packages/walletkit/src/api/interfaces/CryptoOnrampAPI.ts
+++ b/packages/walletkit/src/api/interfaces/CryptoOnrampAPI.ts
@@ -53,6 +53,7 @@ export interface CryptoOnrampProviderInterface<
     TQuoteOptions = unknown,
     TDepositOptions = unknown,
 > extends DefiProvider {
+    /** Provider kind discriminator pinned to `'crypto-onramp'` so {@link registerProvider} routes it to the crypto-onramp manager. */
     readonly type: 'crypto-onramp';
 
     /**
diff --git a/packages/walletkit/src/api/interfaces/DefiManagerAPI.ts b/packages/walletkit/src/api/interfaces/DefiManagerAPI.ts
index c4ceabe8d..a3480633e 100644
--- a/packages/walletkit/src/api/interfaces/DefiManagerAPI.ts
+++ b/packages/walletkit/src/api/interfaces/DefiManagerAPI.ts
@@ -14,6 +14,7 @@ import type { DefiProvider } from './DefiProvider';
  * Swap API interface exposed by SwapManager
  */
 export interface DefiManagerAPI<T extends DefiProvider> {
+    /** Build a fresh {@link ProviderFactoryContext} the manager hands to provider factories at registration time. */
     createFactoryContext(): ProviderFactoryContext;
     /**
      * Register a new provider. If a provider with the same id is already registered, it is replaced.
diff --git a/packages/walletkit/src/api/interfaces/DefiProvider.ts b/packages/walletkit/src/api/interfaces/DefiProvider.ts
index 2d8c9a24a..c59b10691 100644
--- a/packages/walletkit/src/api/interfaces/DefiProvider.ts
+++ b/packages/walletkit/src/api/interfaces/DefiProvider.ts
@@ -17,6 +17,7 @@ export type DefiProviderType = 'swap' | 'staking' | 'onramp' | 'crypto-onramp';
  * Base interface for all DeFi providers
  */
 export interface DefiProvider extends BaseProvider {
+    /** Provider kind discriminator narrowed to the DeFi-domain literals so the right manager picks it up at registration time. */
     readonly type: DefiProviderType;
 
     /**
diff --git a/packages/walletkit/src/api/interfaces/index.ts b/packages/walletkit/src/api/interfaces/index.ts
index dda0eb1c7..c96be575a 100644
--- a/packages/walletkit/src/api/interfaces/index.ts
+++ b/packages/walletkit/src/api/interfaces/index.ts
@@ -15,7 +15,7 @@ export type { DefiManagerAPI } from './DefiManagerAPI';
 export type { SwapAPI, SwapProviderInterface } from './SwapAPI';
 export type { OnrampAPI, OnrampProviderInterface } from './OnrampAPI';
 export type { CryptoOnrampAPI, CryptoOnrampProviderInterface } from './CryptoOnrampAPI';
-export type { DefiProvider } from './DefiProvider';
+export type { DefiProvider, DefiProviderType } from './DefiProvider';
 export type { StakingAPI, StakingProviderInterface } from './StakingAPI';
 
 export type { TONConnectSessionManager } from './TONConnectSessionManager';
diff --git a/packages/walletkit/src/api/models/bridge/SendTransactionApprovalResponse.ts b/packages/walletkit/src/api/models/bridge/SendTransactionApprovalResponse.ts
index 22bb4ca1a..d230f7d72 100644
--- a/packages/walletkit/src/api/models/bridge/SendTransactionApprovalResponse.ts
+++ b/packages/walletkit/src/api/models/bridge/SendTransactionApprovalResponse.ts
@@ -13,7 +13,7 @@ import type { Base64String } from '../core/Primitives';
  */
 export interface SendTransactionApprovalResponse {
     /**
-     * Signed transaction in BOC (Bag of Cells) format, encoded in Base64
+     * Signed transaction in BoC (Bag of Cells) format, encoded in Base64
      */
     signedBoc: Base64String;
 }
diff --git a/packages/walletkit/src/api/models/core/BaseProvider.ts b/packages/walletkit/src/api/models/core/BaseProvider.ts
index 4caed3acf..4fa15362f 100644
--- a/packages/walletkit/src/api/models/core/BaseProvider.ts
+++ b/packages/walletkit/src/api/models/core/BaseProvider.ts
@@ -10,7 +10,9 @@
  * Base interface shared by all provider types.
  */
 export interface BaseProvider {
+    /** Stable provider identifier, unique within the manager that registered it. */
     readonly providerId: string;
+    /** Provider kind discriminator (e.g., `'swap'`, `'staking'`, `'onramp'`, `'crypto-onramp'`); used to route registrations to the right manager. */
     readonly type: string;
 }
 
@@ -20,6 +22,8 @@ export interface BaseProviderUpdate {
 }
 
 export interface BaseProviderEvents {
+    /** Fired by a DeFi manager when a provider is registered through it (carries the provider's id and kind). */
     'provider:registered': BaseProviderUpdate;
+    /** Fired by a DeFi manager when its default provider is set or cleared (carries the new default's id and kind). */
     'provider:default-changed': BaseProviderUpdate;
 }
diff --git a/packages/walletkit/src/api/models/index.ts b/packages/walletkit/src/api/models/index.ts
index d24b66eee..1fb1be83e 100644
--- a/packages/walletkit/src/api/models/index.ts
+++ b/packages/walletkit/src/api/models/index.ts
@@ -102,7 +102,7 @@ export type { OnrampQuoteParams } from './onramp/OnrampQuoteParams';
 export type { OnrampLimits } from './onramp/OnrampLimits';
 export type { OnrampLimitParams } from './onramp/OnrampLimitParams';
 
-// Crypto onramp models
+// Crypto Onramp models
 export type { CryptoOnrampQuote } from './crypto-onramp/CryptoOnrampQuote';
 export type { CryptoOnrampQuoteParams } from './crypto-onramp/CryptoOnrampQuoteParams';
 export type { CryptoOnrampDepositParams } from './crypto-onramp/CryptoOnrampDepositParams';
diff --git a/packages/walletkit/src/api/models/jettons/Jetton.ts b/packages/walletkit/src/api/models/jettons/Jetton.ts
index 9493408f4..04325cc9f 100644
--- a/packages/walletkit/src/api/models/jettons/Jetton.ts
+++ b/packages/walletkit/src/api/models/jettons/Jetton.ts
@@ -15,12 +15,12 @@ import type { TokenInfo } from '../core/TokenInfo';
  */
 export interface Jetton {
     /**
-     * The Jetton contract address
+     * The jetton master contract address (the token itself).
      */
     address: UserFriendlyAddress;
 
     /**
-     * The Jetton wallet address
+     * The owner's jetton-wallet contract address — the per-owner contract that actually holds this balance.
      */
     walletAddress: UserFriendlyAddress;
 
diff --git a/packages/walletkit/src/api/models/nfts/NFT.ts b/packages/walletkit/src/api/models/nfts/NFT.ts
index 20dd6cc71..b516988d4 100644
--- a/packages/walletkit/src/api/models/nfts/NFT.ts
+++ b/packages/walletkit/src/api/models/nfts/NFT.ts
@@ -86,7 +86,7 @@ export interface NFT {
     saleContractAddress?: UserFriendlyAddress;
 
     /**
-     * Off-chain metadata of the NFT (key-value pairs)
+     * Additional arbitrary data related to the NFT.
      */
     extra?: { [key: string]: unknown };
 }
diff --git a/packages/walletkit/src/api/models/nfts/NFTAttribute.ts b/packages/walletkit/src/api/models/nfts/NFTAttribute.ts
index fa45ffb15..5f34a333c 100644
--- a/packages/walletkit/src/api/models/nfts/NFTAttribute.ts
+++ b/packages/walletkit/src/api/models/nfts/NFTAttribute.ts
@@ -16,7 +16,7 @@ export interface NFTAttribute {
     traitType?: string;
 
     /**
-     * How the attribute should be displayed (e.g., "string", "number", "date")
+     * Indexer-supplied hint for how the attribute should be rendered. Optional and indexer-specific.
      */
     displayType?: string;
 
diff --git a/packages/walletkit/src/api/models/staking/StakingProviderMetadata.ts b/packages/walletkit/src/api/models/staking/StakingProviderMetadata.ts
index 33d08c996..a40c26312 100644
--- a/packages/walletkit/src/api/models/staking/StakingProviderMetadata.ts
+++ b/packages/walletkit/src/api/models/staking/StakingProviderMetadata.ts
@@ -10,10 +10,14 @@ import type { UserFriendlyAddress } from '../core/Primitives';
 import type { UnstakeModes } from './UnstakeMode';
 
 export interface StakingTokenInfo {
+    /** Ticker symbol (e.g., `"TON"`, `"tsTON"`). */
     ticker: string;
-    /** @format int */
+    /**
+     * Number of decimal places used to format raw amounts.
+     * @format int
+     */
     decimals: number;
-    /** 'ton' for native TON, otherwise contract address in friendly format */
+    /** `'ton'` for native TON, otherwise the token contract address in user-friendly format. */
     address: string;
 }
 
diff --git a/packages/walletkit/src/api/models/streaming/StreamingEvents.ts b/packages/walletkit/src/api/models/streaming/StreamingEvents.ts
index 8d65827aa..ee532f756 100644
--- a/packages/walletkit/src/api/models/streaming/StreamingEvents.ts
+++ b/packages/walletkit/src/api/models/streaming/StreamingEvents.ts
@@ -11,7 +11,10 @@ import type { TransactionsUpdate } from './TransactionsUpdate';
 import type { JettonUpdate } from './JettonUpdate';
 
 export interface StreamingEvents {
+    /** Fired by a streaming provider when a watched address's TON balance changes. */
     'streaming:balance-update': BalanceUpdate;
+    /** Fired by a streaming provider when new transactions land for a watched address. */
     'streaming:transactions': TransactionsUpdate;
+    /** Fired by a streaming provider when a watched address's jetton holdings change. */
     'streaming:jettons-update': JettonUpdate;
 }
diff --git a/packages/walletkit/src/api/models/swaps/SwapToken.ts b/packages/walletkit/src/api/models/swaps/SwapToken.ts
index 7bdd2c1c7..9b7d2e286 100644
--- a/packages/walletkit/src/api/models/swaps/SwapToken.ts
+++ b/packages/walletkit/src/api/models/swaps/SwapToken.ts
@@ -10,15 +10,21 @@
  * Token type for swap
  */
 export type SwapToken = {
+    /** Token contract address; `'ton'` is used for native TON on the TON chain. */
     address: string;
 
     /**
+     * Number of decimal places used to format raw amounts.
      * @format: int
      */
     decimals: number;
 
+    /** Display name (e.g., `"Tether USD"`). */
     name?: string;
+    /** Ticker symbol (e.g., `"USDT"`). */
     symbol?: string;
+    /** URL of the token's image. */
     image?: string;
+    /** Chain id in CAIP-2 format when the token lives outside TON. */
     chainId?: string;
 };
diff --git a/packages/walletkit/src/api/models/transactions/SendTransactionResponse.ts b/packages/walletkit/src/api/models/transactions/SendTransactionResponse.ts
index 0f242103e..c160fc29e 100644
--- a/packages/walletkit/src/api/models/transactions/SendTransactionResponse.ts
+++ b/packages/walletkit/src/api/models/transactions/SendTransactionResponse.ts
@@ -10,11 +10,11 @@ import type { Base64String, Hex } from '../core/Primitives';
 
 export interface SendTransactionResponse {
     /**
-     * BOC of the sent transaction
+     * BoC of the sent transaction
      */
     boc: Base64String;
     /**
-     * Normalized BOC of the external-in message
+     * Normalized BoC of the external-in message
      */
     normalizedBoc: Base64String;
     /**
diff --git a/packages/walletkit/src/api/models/transactions/Transaction.ts b/packages/walletkit/src/api/models/transactions/Transaction.ts
index 9634bc1e9..ee7b4246c 100644
--- a/packages/walletkit/src/api/models/transactions/Transaction.ts
+++ b/packages/walletkit/src/api/models/transactions/Transaction.ts
@@ -25,7 +25,7 @@ export interface Transaction {
     accountStateBefore?: AccountState;
 
     /**
-     * * The state of the account after the transaction has been applied
+     * The state of the account after the transaction has been applied
      */
     accountStateAfter?: AccountState;
 
@@ -283,7 +283,7 @@ export interface TransactionMessageContent {
     hash?: string;
 
     /**
-     * The body in BOC format
+     * The body in BoC format
      */
     body?: Base64String;
 
diff --git a/packages/walletkit/src/bridge/core/BridgeConfig.ts b/packages/walletkit/src/bridge/core/BridgeConfig.ts
index e06ff57ab..62679a267 100644
--- a/packages/walletkit/src/bridge/core/BridgeConfig.ts
+++ b/packages/walletkit/src/bridge/core/BridgeConfig.ts
@@ -39,7 +39,7 @@ export interface BridgeConfig {
     protocolVersion: number;
 
     /**
-     * Id of wallet assosiated with dApp connection in bridge
+     * ID of wallet assosiated with dApp connection in bridge
      */
     walletId?: WalletId;
 }
diff --git a/packages/walletkit/src/clients/tonapi/ApiClientTonApi.ts b/packages/walletkit/src/clients/tonapi/ApiClientTonApi.ts
index d930a212c..1f1940494 100644
--- a/packages/walletkit/src/clients/tonapi/ApiClientTonApi.ts
+++ b/packages/walletkit/src/clients/tonapi/ApiClientTonApi.ts
@@ -67,6 +67,7 @@ import { mapMasterchainInfo } from './mappers/map-masterchain-info';
  * with the default Toncenter client. Some methods are not yet fully implemented.
  */
 export class ApiClientTonApi extends BaseApiClient implements ApiClient {
+    /** @param config - TonAPI client config — endpoint URL and API key; defaults to TonAPI mainnet/testnet URLs based on `config.network`. */
     constructor(config: BaseApiClientConfig = {}) {
         let defaultEndpoint: string;
 
diff --git a/packages/walletkit/src/clients/toncenter/ApiClientToncenter.ts b/packages/walletkit/src/clients/toncenter/ApiClientToncenter.ts
index cf6dd38b9..cefec3e89 100644
--- a/packages/walletkit/src/clients/toncenter/ApiClientToncenter.ts
+++ b/packages/walletkit/src/clients/toncenter/ApiClientToncenter.ts
@@ -70,6 +70,7 @@ export interface ApiClientConfig extends BaseApiClientConfig {
 }
 
 export class ApiClientToncenter extends BaseApiClient implements ApiClient {
+    /** @param config - Toncenter client config — endpoint URL, API key and optional DNS resolver override; defaults to mainnet/testnet Toncenter URLs based on `config.network`. */
     constructor(config: ApiClientConfig = {}) {
         const defaultEndpoint =
             config.network?.chainId === Network.mainnet().chainId
diff --git a/packages/walletkit/src/core/EventEmitter.ts b/packages/walletkit/src/core/EventEmitter.ts
index d884784bd..8ed330081 100644
--- a/packages/walletkit/src/core/EventEmitter.ts
+++ b/packages/walletkit/src/core/EventEmitter.ts
@@ -15,9 +15,13 @@ const log = globalLogger.createChild('EventEmitter');
 export type EventPayload = object;
 
 export interface KitEvent<T> {
+    /** Event name (e.g., `'connector:wallets-updated'`). */
     type: string;
+    /** Event-specific payload — typed via the emitter's event-name → payload map. */
     payload: T;
+    /** Identifier of the component that emitted the event (connector id, manager name, etc.); useful for filtering listeners. */
     source?: string;
+    /** Wall-clock timestamp in milliseconds when the event was emitted. */
     timestamp: number;
 }
 
diff --git a/packages/walletkit/src/core/NetworkManager.ts b/packages/walletkit/src/core/NetworkManager.ts
index 021739425..fc6632e70 100644
--- a/packages/walletkit/src/core/NetworkManager.ts
+++ b/packages/walletkit/src/core/NetworkManager.ts
@@ -32,6 +32,7 @@ export interface NetworkManager {
 export class KitNetworkManager implements NetworkManager {
     private clients: Map<string, ApiClient> = new Map();
 
+    /** @param options - {@link TonWalletKitOptions} Configuration carrying the `networks` map keyed by chain ID; at least one network must be configured. */
     constructor(options: TonWalletKitOptions) {
         this.initializeClients(options);
 
diff --git a/packages/walletkit/src/defi/crypto-onramp/README.md b/packages/walletkit/src/defi/crypto-onramp/README.md
index b280ce500..868d7f53b 100644
--- a/packages/walletkit/src/defi/crypto-onramp/README.md
+++ b/packages/walletkit/src/defi/crypto-onramp/README.md
@@ -1,7 +1,7 @@
 <!--
 This file is auto-generated. Do not edit manually.
 Changes will be overwritten when running the docs update script.
-Source template: template/packages/walletkit/src/defi/crypto-onramp/README.md
+Source template: docs/templates/packages/walletkit/src/defi/crypto-onramp/README.md
 -->
 
 # Crypto Onramp Manager
@@ -36,7 +36,7 @@ All providers accept the same base parameters for `getQuote`:
 interface CryptoOnrampQuoteParams<TProviderOptions = unknown> {
     amount: string;                     // Amount in base units (source or target, see isSourceAmount)
     sourceCurrencyAddress: string;      // Source token contract address (or native zero address)
-    sourceChain: string;              // Source chain identifier in CAIP-2 format (e.g. 'eip155:1', 'eip155:42161')
+    sourceNetwork: string;              // Source chain identifier
     targetCurrencyAddress: string;      // Target TON token address
     recipientAddress: string;           // TON address that will receive the target crypto
     refundAddress?: string;             // Refund address on the source chain (required by some providers)
@@ -50,7 +50,7 @@ interface CryptoOnrampQuoteParams<TProviderOptions = unknown> {
 ```typescript
 const quote = await kit.cryptoOnramp.getQuote({
     sourceCurrencyAddress: '0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9', // USDT on Arbitrum
-    sourceChain: 'eip155:42161', // Arbitrum One in CAIP-2 format
+    sourceNetwork: '42161', // Arbitrum One chain ID
     targetCurrencyAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs', // USDT on TON
     amount: '1000000', // 1 USDT (6 decimals)
     recipientAddress: 'UQ...', // TON address to receive the bridged tokens
@@ -120,7 +120,7 @@ export class MyCryptoOnrampProvider extends CryptoOnrampProvider<MyQuoteOptions>
         // Fetch quote from your bridge API...
         return {
             sourceCurrencyAddress,
-            sourceChain: params.sourceChain,
+            sourceNetwork: params.sourceNetwork,
             targetCurrencyAddress,
             sourceAmount: '...',
             targetAmount: '...',
@@ -132,7 +132,7 @@ export class MyCryptoOnrampProvider extends CryptoOnrampProvider<MyQuoteOptions>
 
     async createDeposit(params: CryptoOnrampDepositParams): Promise<CryptoOnrampDeposit> {
         // params.quote.recipientAddress holds the TON recipient set at quote time
-        return { depositId: '...', address: '0x...', amount: '...', sourceCurrencyAddress: '...', sourceChain: '...', providerId: this.providerId };
+        return { depositId: '...', address: '0x...', amount: '...', sourceCurrencyAddress: '...', sourceNetwork: '...', providerId: this.providerId };
     }
 
     async getStatus(params: CryptoOnrampStatusParams): Promise<CryptoOnrampStatus> {
@@ -154,7 +154,7 @@ export class MyCryptoOnrampProvider extends CryptoOnrampProvider<MyQuoteOptions>
 Get a quote for a crypto-to-TON bridge operation.
 
 **Parameters:**
-- `params: CryptoOnrampQuoteParams<TProviderOptions>` – `sourceCurrencyAddress`, `sourceChain`, `targetCurrencyAddress`, `amount`, `recipientAddress`, `isSourceAmount?`, `refundAddress?`, `providerOptions?`
+- `params: CryptoOnrampQuoteParams<TProviderOptions>` – `sourceCurrencyAddress`, `sourceNetwork`, `targetCurrencyAddress`, `amount`, `recipientAddress`, `isSourceAmount?`, `refundAddress?`, `providerOptions?`
 - `providerId?: string` – Provider to use (uses default if omitted)
 
 **Returns:** `Promise<CryptoOnrampQuote>`
diff --git a/packages/walletkit/src/defi/crypto-onramp/errors.ts b/packages/walletkit/src/defi/crypto-onramp/errors.ts
index 5c15eadc2..a7f9c5d0e 100644
--- a/packages/walletkit/src/defi/crypto-onramp/errors.ts
+++ b/packages/walletkit/src/defi/crypto-onramp/errors.ts
@@ -16,6 +16,11 @@ export class CryptoOnrampError extends DefiError {
     static readonly INVALID_REFUND_ADDRESS = 'INVALID_REFUND_ADDRESS';
     static readonly REVERSED_AMOUNT_NOT_SUPPORTED = 'REVERSED_AMOUNT_NOT_SUPPORTED';
 
+    /**
+     * @param message - Human-readable description, forwarded to `Error`.
+     * @param code - Stable error code from the static `CryptoOnrampError.*` / `DefiError.*` constants.
+     * @param details - Optional provider-specific context for diagnostics.
+     */
     constructor(message: string, code: string, details?: unknown) {
         super(message, code, details);
         this.name = 'CryptoOnrampError';
diff --git a/packages/walletkit/src/defi/crypto-onramp/layerswap/LayerswapCryptoOnrampProvider.ts b/packages/walletkit/src/defi/crypto-onramp/layerswap/LayerswapCryptoOnrampProvider.ts
index 04c4b0d10..b8f396849 100644
--- a/packages/walletkit/src/defi/crypto-onramp/layerswap/LayerswapCryptoOnrampProvider.ts
+++ b/packages/walletkit/src/defi/crypto-onramp/layerswap/LayerswapCryptoOnrampProvider.ts
@@ -56,9 +56,13 @@ export interface LayerswapProviderConfig {
  * action here; `createDeposit` just reads them out.
  */
 export interface LayerswapQuoteMetadata {
+    /** Layerswap swap id created at quote time and reused by `createDeposit` / `getStatus`. */
     swapId: string;
+    /** Pre-computed deposit address on the source chain that the user must send funds to. */
     depositAddress: string;
+    /** Source-chain amount the user must send, in raw base units (e.g., wei). */
     sourceAmountBaseUnits: string;
+    /** Target-chain amount the user receives, in raw base units (e.g., nanotons). */
     targetAmountBaseUnits: string;
 }
 
@@ -82,6 +86,7 @@ export class LayerswapCryptoOnrampProvider extends CryptoOnrampProvider<undefine
     private readonly apiKey: string | undefined;
     private readonly apiUrl: string;
 
+    /** @param config - Optional {@link LayerswapProviderConfig}; defaults are filled in for any field left undefined. */
     constructor(config: LayerswapProviderConfig = {}) {
         super();
         this.apiKey = config.apiKey;
@@ -256,6 +261,8 @@ export class LayerswapCryptoOnrampProvider extends CryptoOnrampProvider<undefine
 /**
  * Returns a `ProviderFactory` for `LayerswapCryptoOnrampProvider`.
  * Pass to `providers: [createLayerswapProvider(config)]`.
+ *
+ * @param config - Optional {@link LayerswapProviderConfig}; defaults are filled in for any field left undefined.
  */
 export const createLayerswapProvider = (config: LayerswapProviderConfig = {}) =>
     createProvider(() => new LayerswapCryptoOnrampProvider(config));
diff --git a/packages/walletkit/src/defi/crypto-onramp/layerswap/README.md b/packages/walletkit/src/defi/crypto-onramp/layerswap/README.md
index d05443a2f..d373c09aa 100644
--- a/packages/walletkit/src/defi/crypto-onramp/layerswap/README.md
+++ b/packages/walletkit/src/defi/crypto-onramp/layerswap/README.md
@@ -1,7 +1,7 @@
 <!--
 This file is auto-generated. Do not edit manually.
 Changes will be overwritten when running the docs update script.
-Source template: template/packages/walletkit/src/defi/crypto-onramp/layerswap/README.md
+Source template: docs/templates/packages/walletkit/src/defi/crypto-onramp/layerswap/README.md
 -->
 
 # Layerswap Crypto Onramp Provider
@@ -37,7 +37,7 @@ See [Crypto Onramp README](../README.md) for base `CryptoOnrampQuoteParams`. Lay
 ```typescript
 const quote = await kit.cryptoOnramp.getQuote({
     sourceCurrencyAddress: '0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9', // USDT on Arbitrum
-    sourceChain: 'eip155:42161',
+    sourceNetwork: '42161',
     targetCurrencyAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs', // USDT on TON
     amount: '1000000', // 1 USDT (6 decimals)
     recipientAddress: 'UQ...', // TON address to receive tokens
diff --git a/packages/walletkit/src/defi/crypto-onramp/swaps-xyz/README.md b/packages/walletkit/src/defi/crypto-onramp/swaps-xyz/README.md
index 1adf4c6d5..8df8dde7f 100644
--- a/packages/walletkit/src/defi/crypto-onramp/swaps-xyz/README.md
+++ b/packages/walletkit/src/defi/crypto-onramp/swaps-xyz/README.md
@@ -1,7 +1,7 @@
 <!--
 This file is auto-generated. Do not edit manually.
 Changes will be overwritten when running the docs update script.
-Source template: template/packages/walletkit/src/defi/crypto-onramp/swaps-xyz/README.md
+Source template: docs/templates/packages/walletkit/src/defi/crypto-onramp/swaps-xyz/README.md
 -->
 
 # Swaps.xyz Crypto Onramp Provider
@@ -48,7 +48,7 @@ import type { SwapsXyzQuoteOptions } from '@ton/walletkit/crypto-onramp/swaps-xy
 
 const quote = await kit.cryptoOnramp.getQuote<SwapsXyzQuoteOptions>({
     sourceCurrencyAddress: '0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9', // USDT on Arbitrum
-    sourceChain: 'eip155:42161',
+    sourceNetwork: '42161',
     targetCurrencyAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs', // USDT on TON
     amount: '1000000', // 1 USDT (6 decimals)
     recipientAddress: 'UQ...', // TON address to receive tokens
diff --git a/packages/walletkit/src/defi/crypto-onramp/swaps-xyz/SwapsXyzCryptoOnrampProvider.ts b/packages/walletkit/src/defi/crypto-onramp/swaps-xyz/SwapsXyzCryptoOnrampProvider.ts
index c8b474d1b..c8e203d78 100644
--- a/packages/walletkit/src/defi/crypto-onramp/swaps-xyz/SwapsXyzCryptoOnrampProvider.ts
+++ b/packages/walletkit/src/defi/crypto-onramp/swaps-xyz/SwapsXyzCryptoOnrampProvider.ts
@@ -59,7 +59,9 @@ export interface SwapsXyzQuoteOptions {
  * CryptoOnrampDeposit without an extra network round-trip.
  */
 export interface SwapsXyzQuoteMetadata {
+    /** EVM sender address swaps.xyz was quoted for; required when later calling `createDeposit`. */
     sender: string;
+    /** Raw `getAction` response cached at quote time so `createDeposit` doesn't need an extra round-trip. */
     response: SwapsXyzGetActionResponse;
 }
 
@@ -85,6 +87,7 @@ export class SwapsXyzCryptoOnrampProvider extends CryptoOnrampProvider<SwapsXyzQ
     private readonly apiUrl: string;
     private readonly defaultSender: string;
 
+    /** @param config - {@link SwapsXyzProviderConfig} Configuration carrying the required `apiKey` plus optional URL/sender overrides. */
     constructor(config: SwapsXyzProviderConfig) {
         super();
         this.apiKey = config.apiKey;
@@ -286,6 +289,8 @@ export class SwapsXyzCryptoOnrampProvider extends CryptoOnrampProvider<SwapsXyzQ
 /**
  * Returns a `ProviderFactory` for `SwapsXyzCryptoOnrampProvider`.
  * Pass to `providers: [createSwapsXyzProvider(config)]`.
+ *
+ * @param config - {@link SwapsXyzProviderConfig} Configuration carrying the required `apiKey` plus optional URL/sender overrides.
  */
 export const createSwapsXyzProvider = (config: SwapsXyzProviderConfig) =>
     createProvider(() => new SwapsXyzCryptoOnrampProvider(config));
diff --git a/packages/walletkit/src/defi/crypto-onramp/swaps-xyz/utils.ts b/packages/walletkit/src/defi/crypto-onramp/swaps-xyz/utils.ts
index 9c555dad4..8a7138397 100644
--- a/packages/walletkit/src/defi/crypto-onramp/swaps-xyz/utils.ts
+++ b/packages/walletkit/src/defi/crypto-onramp/swaps-xyz/utils.ts
@@ -13,7 +13,7 @@ import type { SwapsXyzErrorResponse } from './types';
 const EVM_ADDRESS_REGEX = /^(0x)?[0-9a-fA-F]{40}$/;
 
 /**
- * Extract a numeric EVM chain id from a CAIP-2 string. Returns `undefined`
+ * Extract a numeric EVM chain ID from a CAIP-2 string. Returns `undefined`
  * for non-EVM (`namespace !== 'eip155'`) or malformed values.
  */
 export const parseEvmChainIdFromCaip2 = (value: string): number | undefined => {
@@ -24,7 +24,7 @@ export const parseEvmChainIdFromCaip2 = (value: string): number | undefined => {
 };
 
 /**
- * Build the CAIP-2 representation for an EVM chain id.
+ * Build the CAIP-2 representation for an EVM chain ID.
  */
 export const evmChainIdToCaip2 = (chainId: number | string): string => `eip155:${chainId}`;
 
diff --git a/packages/walletkit/src/defi/errors.ts b/packages/walletkit/src/defi/errors.ts
index 30e5512b2..b07b9867f 100644
--- a/packages/walletkit/src/defi/errors.ts
+++ b/packages/walletkit/src/defi/errors.ts
@@ -6,17 +6,33 @@
  *
  */
 
+/**
+ * Base error thrown by DeFi managers (swap, staking, onramp) when a provider call fails; subclassed by {@link SwapError} / {@link StakingError} and discriminated at runtime via the `code` field.
+ */
 export class DefiError extends Error {
+    /** Provider with the requested id is not registered with the manager. */
     static readonly PROVIDER_NOT_FOUND = 'PROVIDER_NOT_FOUND';
+    /** No default provider is configured and the caller did not specify one. */
     static readonly NO_DEFAULT_PROVIDER = 'NO_DEFAULT_PROVIDER';
+    /** Provider rejected the request because of an upstream/network failure. */
     static readonly NETWORK_ERROR = 'NETWORK_ERROR';
+    /** Provider does not support the network selected for the operation. */
     static readonly UNSUPPORTED_NETWORK = 'UNSUPPORTED_NETWORK';
+    /** Caller passed parameters that fail provider-level validation. */
     static readonly INVALID_PARAMS = 'INVALID_PARAMS';
+    /** Provider failed its own internal validation and cannot be used. */
     static readonly INVALID_PROVIDER = 'INVALID_PROVIDER';
 
+    /** Stable error code for branching logic; one of the static `DefiError.*` constants. */
     public readonly code: string;
+    /** Provider-specific extra context (request payload, upstream error, etc.); shape is not stable. */
     public readonly details?: unknown;
 
+    /**
+     * @param message - Human-readable description, forwarded to `Error`.
+     * @param code - Stable error code from the `DefiError.*` constants.
+     * @param details - Optional provider-specific context for diagnostics.
+     */
     constructor(message: string, code: string, details?: unknown) {
         super(message);
         this.name = 'DefiError';
diff --git a/packages/walletkit/src/defi/staking/README.md b/packages/walletkit/src/defi/staking/README.md
index 52c8fba89..ca46f1100 100644
--- a/packages/walletkit/src/defi/staking/README.md
+++ b/packages/walletkit/src/defi/staking/README.md
@@ -1,7 +1,7 @@
 <!--
 This file is auto-generated. Do not edit manually.
 Changes will be overwritten when running the docs update script.
-Source template: template/packages/walletkit/src/defi/staking/README.md
+Source template: docs/templates/packages/walletkit/src/defi/staking/README.md
 -->
 
 # Staking
diff --git a/packages/walletkit/src/defi/staking/StakingManager.ts b/packages/walletkit/src/defi/staking/StakingManager.ts
index d8dd51b9a..cb8a6bf50 100644
--- a/packages/walletkit/src/defi/staking/StakingManager.ts
+++ b/packages/walletkit/src/defi/staking/StakingManager.ts
@@ -30,6 +30,7 @@ const log = globalLogger.createChild('StakingManager');
  * for staking operations. Providers can be switched dynamically.
  */
 export class StakingManager extends DefiManager<StakingProviderInterface> implements StakingAPI {
+    /** @param createFactoryContext - Lazy provider of the {@link ProviderFactoryContext} the manager passes into provider factories at registration time. */
     constructor(createFactoryContext: () => ProviderFactoryContext) {
         super(createFactoryContext);
     }
diff --git a/packages/walletkit/src/defi/staking/StakingProvider.ts b/packages/walletkit/src/defi/staking/StakingProvider.ts
index f001868eb..e7899c5d4 100644
--- a/packages/walletkit/src/defi/staking/StakingProvider.ts
+++ b/packages/walletkit/src/defi/staking/StakingProvider.ts
@@ -26,6 +26,7 @@ export abstract class StakingProvider implements StakingProviderInterface {
     readonly type = 'staking';
     readonly providerId: string;
 
+    /** @param providerId - Stable id the provider registers with — must be unique within {@link StakingManager}. */
     constructor(providerId: string) {
         this.providerId = providerId;
     }
diff --git a/packages/walletkit/src/defi/staking/errors.ts b/packages/walletkit/src/defi/staking/errors.ts
index 2aa5754b1..332668513 100644
--- a/packages/walletkit/src/defi/staking/errors.ts
+++ b/packages/walletkit/src/defi/staking/errors.ts
@@ -9,13 +9,20 @@
 import { DefiError } from '../errors';
 
 export enum StakingErrorCode {
+    /** Caller passed parameters that fail provider-level validation. */
     InvalidParams = 'INVALID_PARAMS',
+    /** Provider doesn't support the requested operation (e.g., reversed quote on a unidirectional pool). */
     UnsupportedOperation = 'UNSUPPORTED_OPERATION',
 }
 
 export class StakingError extends DefiError {
     public readonly code: StakingErrorCode;
 
+    /**
+     * @param message - Human-readable description, forwarded to `Error`.
+     * @param code - Stable {@link StakingErrorCode} for branching logic.
+     * @param details - Optional provider-specific context for diagnostics.
+     */
     constructor(message: string, code: StakingErrorCode, details?: unknown) {
         super(message, code, details);
         this.name = 'StakingError';
diff --git a/packages/walletkit/src/defi/staking/tonstakers/README.md b/packages/walletkit/src/defi/staking/tonstakers/README.md
index 2c9f41e03..f9035f2a9 100644
--- a/packages/walletkit/src/defi/staking/tonstakers/README.md
+++ b/packages/walletkit/src/defi/staking/tonstakers/README.md
@@ -1,7 +1,7 @@
 <!--
 This file is auto-generated. Do not edit manually.
 Changes will be overwritten when running the docs update script.
-Source template: template/packages/walletkit/src/defi/staking/tonstakers/README.md
+Source template: docs/templates/packages/walletkit/src/defi/staking/tonstakers/README.md
 -->
 
 # Tonstakers staking provider
diff --git a/packages/walletkit/src/defi/staking/tonstakers/TonStakersStakingProvider.ts b/packages/walletkit/src/defi/staking/tonstakers/TonStakersStakingProvider.ts
index eff9e5c29..7d46abf48 100644
--- a/packages/walletkit/src/defi/staking/tonstakers/TonStakersStakingProvider.ts
+++ b/packages/walletkit/src/defi/staking/tonstakers/TonStakersStakingProvider.ts
@@ -510,6 +510,8 @@ export class TonStakersStakingProvider extends StakingProvider {
 /**
  * Returns an AppKit / `ProviderInput` factory: pass to `providers: [createTonstakersProvider(config)]`.
  * At kit init, the factory receives context and builds the provider using `ctx.networkManager` for RPC.
+ *
+ * @param config - Optional {@link TonStakersProviderConfig}; defaults are filled in for any field left undefined.
  */
 export const createTonstakersProvider = (
     config: TonStakersProviderConfig = {},
diff --git a/packages/walletkit/src/defi/swap/README.md b/packages/walletkit/src/defi/swap/README.md
index c56e2bd36..85994d376 100644
--- a/packages/walletkit/src/defi/swap/README.md
+++ b/packages/walletkit/src/defi/swap/README.md
@@ -1,7 +1,7 @@
 <!--
 This file is auto-generated. Do not edit manually.
 Changes will be overwritten when running the docs update script.
-Source template: template/packages/walletkit/src/defi/swap/README.md
+Source template: docs/templates/packages/walletkit/src/defi/swap/README.md
 -->
 
 # Swap Manager
diff --git a/packages/walletkit/src/defi/swap/SwapManager.ts b/packages/walletkit/src/defi/swap/SwapManager.ts
index 173fe9da6..044ef9814 100644
--- a/packages/walletkit/src/defi/swap/SwapManager.ts
+++ b/packages/walletkit/src/defi/swap/SwapManager.ts
@@ -23,6 +23,7 @@ const log = globalLogger.createChild('SwapManager');
  * for swap operations. Providers can be switched dynamically.
  */
 export class SwapManager extends DefiManager<SwapProviderInterface> implements SwapAPI {
+    /** @param createFactoryContext - Lazy provider of the {@link ProviderFactoryContext} the manager passes into provider factories at registration time. */
     constructor(createFactoryContext: () => ProviderFactoryContext) {
         super(createFactoryContext);
     }
diff --git a/packages/walletkit/src/defi/swap/dedust/DeDustSwapProvider.ts b/packages/walletkit/src/defi/swap/dedust/DeDustSwapProvider.ts
index 7a5b96e1e..15fcfb2a4 100644
--- a/packages/walletkit/src/defi/swap/dedust/DeDustSwapProvider.ts
+++ b/packages/walletkit/src/defi/swap/dedust/DeDustSwapProvider.ts
@@ -83,6 +83,7 @@ export class DeDustSwapProvider extends SwapProvider<DeDustProviderOptions, DeDu
         url: 'https://dedust.io',
     };
 
+    /** @param config - Optional {@link DeDustSwapProviderConfig}; defaults are filled in for any field left undefined. */
     constructor(config?: DeDustSwapProviderConfig) {
         super();
         this.providerId = config?.providerId ?? 'dedust';
@@ -313,6 +314,8 @@ export class DeDustSwapProvider extends SwapProvider<DeDustProviderOptions, DeDu
 /**
  * Returns an AppKit / `ProviderInput` factory for {@link DeDustSwapProvider}:
  * pass to `providers: [createDeDustProvider(config)]`.
+ *
+ * @param config - Optional {@link DeDustSwapProviderConfig}; defaults are filled in for any field left undefined.
  */
 export const createDeDustProvider = (
     config: DeDustSwapProviderConfig = {},
diff --git a/packages/walletkit/src/defi/swap/dedust/README.md b/packages/walletkit/src/defi/swap/dedust/README.md
index f3bbb59bf..5148367f9 100644
--- a/packages/walletkit/src/defi/swap/dedust/README.md
+++ b/packages/walletkit/src/defi/swap/dedust/README.md
@@ -1,7 +1,7 @@
 <!--
 This file is auto-generated. Do not edit manually.
 Changes will be overwritten when running the docs update script.
-Source template: template/packages/walletkit/src/defi/swap/dedust/README.md
+Source template: docs/templates/packages/walletkit/src/defi/swap/dedust/README.md
 -->
 
 # DeDust Swap Provider
diff --git a/packages/walletkit/src/defi/swap/errors.ts b/packages/walletkit/src/defi/swap/errors.ts
index 481ac390e..23d49b416 100644
--- a/packages/walletkit/src/defi/swap/errors.ts
+++ b/packages/walletkit/src/defi/swap/errors.ts
@@ -14,6 +14,11 @@ export class SwapError extends DefiError {
     static readonly QUOTE_EXPIRED = 'QUOTE_EXPIRED';
     static readonly BUILD_TX_FAILED = 'BUILD_TX_FAILED';
 
+    /**
+     * @param message - Human-readable description, forwarded to `Error`.
+     * @param code - Stable error code from the static `SwapError.*` / `DefiError.*` constants.
+     * @param details - Optional provider-specific context for diagnostics.
+     */
     constructor(message: string, code: string, details?: unknown) {
         super(message, code, details);
         this.name = 'SwapError';
diff --git a/packages/walletkit/src/defi/swap/omniston/OmnistonSwapProvider.ts b/packages/walletkit/src/defi/swap/omniston/OmnistonSwapProvider.ts
index 667c2bd1e..c9da54d0a 100644
--- a/packages/walletkit/src/defi/swap/omniston/OmnistonSwapProvider.ts
+++ b/packages/walletkit/src/defi/swap/omniston/OmnistonSwapProvider.ts
@@ -60,6 +60,7 @@ export class OmnistonSwapProvider extends SwapProvider<OmnistonProviderOptions>
 
     readonly providerId: string;
 
+    /** @param config - Optional {@link OmnistonSwapProviderConfig}; defaults are filled in for any field left undefined. */
     constructor(config?: OmnistonSwapProviderConfig) {
         super();
         this.providerId = config?.providerId ?? 'omniston';
@@ -337,6 +338,8 @@ export class OmnistonSwapProvider extends SwapProvider<OmnistonProviderOptions>
 /**
  * Returns an AppKit / `ProviderInput` factory for {@link OmnistonSwapProvider}:
  * pass to `providers: [createOmnistonProvider(config)]`.
+ *
+ * @param config - Optional {@link OmnistonSwapProviderConfig}; defaults are filled in for any field left undefined.
  */
 export const createOmnistonProvider = (
     config: OmnistonSwapProviderConfig = {},
diff --git a/packages/walletkit/src/defi/swap/omniston/README.md b/packages/walletkit/src/defi/swap/omniston/README.md
index 460dfd939..cceb44f88 100644
--- a/packages/walletkit/src/defi/swap/omniston/README.md
+++ b/packages/walletkit/src/defi/swap/omniston/README.md
@@ -1,7 +1,7 @@
 <!--
 This file is auto-generated. Do not edit manually.
 Changes will be overwritten when running the docs update script.
-Source template: template/packages/walletkit/src/defi/swap/omniston/README.md
+Source template: docs/templates/packages/walletkit/src/defi/swap/omniston/README.md
 -->
 
 # Omniston Swap Provider
diff --git a/packages/walletkit/src/defi/swap/omniston/models/OmnistonQuoteMetadata.ts b/packages/walletkit/src/defi/swap/omniston/models/OmnistonQuoteMetadata.ts
index 5e26e5fda..2f9f03f52 100644
--- a/packages/walletkit/src/defi/swap/omniston/models/OmnistonQuoteMetadata.ts
+++ b/packages/walletkit/src/defi/swap/omniston/models/OmnistonQuoteMetadata.ts
@@ -13,7 +13,7 @@ import type { Quote } from '@ston-fi/omniston-sdk';
  */
 export interface OmnistonQuoteMetadata {
     /**
-     * The actual omniston quote object
+     * The actual Omniston quote object
      * @format frozen
      */
     omnistonQuote: Quote;
diff --git a/packages/walletkit/src/types/config.ts b/packages/walletkit/src/types/config.ts
index 3acad1afe..9f05ac80a 100644
--- a/packages/walletkit/src/types/config.ts
+++ b/packages/walletkit/src/types/config.ts
@@ -20,8 +20,10 @@ import type { TONConnectSessionManager } from '../api/interfaces';
  * API client configuration options
  */
 export interface ApiClientConfig {
-    url?: string; // default 'https://toncenter.com' for mainnet, 'https://testnet.toncenter.com' for testnet
-    key?: string; // key for better RPS limits
+    /** Base URL of the indexer endpoint. Defaults to `'https://toncenter.com'` for mainnet, `'https://testnet.toncenter.com'` for testnet. */
+    url?: string;
+    /** API key forwarded to the indexer for higher rate limits. */
+    key?: string;
 }
 
 /**
@@ -34,7 +36,7 @@ export interface NetworkConfig {
 
 /**
  * Multi-network configuration keyed by chain ID
- * Example: { [Networl.mainnet().chainId]: { apiClient: {...} }, [Networl.testnet().chainId]: { apiClient: {...} } }
+ * Example: { [Network.mainnet().chainId]: { apiClient: {...} }, [Network.testnet().chainId]: { apiClient: {...} } }
  */
 export type NetworkAdapters = {
     [key: string]: NetworkConfig | undefined;
@@ -44,7 +46,9 @@ export type NetworkAdapters = {
  * Main configuration options for TonWalletKit
  */
 export interface TonWalletKitOptions {
+    /** TonConnect wallet manifest published by the dApp; required for the wallet to recognize the integration. */
     walletManifest?: WalletInfo;
+    /** Device fingerprint forwarded with TonConnect requests so wallets can recognize the host. */
     deviceInfo?: DeviceInfo;
 
     /**
@@ -70,10 +74,12 @@ export interface TonWalletKitOptions {
     /** Event processor settings */
     eventProcessor?: EventProcessorConfig;
 
+    /** Analytics manager options merged with an `enabled` toggle; off by default. */
     analytics?: AnalyticsManagerOptions & {
         enabled?: boolean;
     };
 
+    /** Diagnostic toggles useful during local development; should not be set in production builds. */
     dev?: {
         disableNetworkSend?: boolean;
         disableManifestDomainCheck?: boolean;
diff --git a/packages/walletkit/src/types/factory.ts b/packages/walletkit/src/types/factory.ts
index af0446664..44cff8425 100644
--- a/packages/walletkit/src/types/factory.ts
+++ b/packages/walletkit/src/types/factory.ts
@@ -15,8 +15,11 @@ import type { SharedKitEvents } from './emitter';
  * Context passed to provider factory functions.
  */
 export interface ProviderFactoryContext<Events extends SharedKitEvents = SharedKitEvents> {
+    /** Network manager the provider should use for client lookups and default-network reads. */
     networkManager: NetworkManager;
+    /** Event emitter the provider should publish its events to. */
     eventEmitter: EventEmitter<Events>;
+    /** `true` when the provider is constructed during server-side rendering — factories may skip browser-only setup. */
     ssr?: boolean;
 }
 
diff --git a/packages/walletkit/src/types/jettons.ts b/packages/walletkit/src/types/jettons.ts
index c5a3b4f06..6359b89cf 100644
--- a/packages/walletkit/src/types/jettons.ts
+++ b/packages/walletkit/src/types/jettons.ts
@@ -12,22 +12,36 @@ import type { Jetton, Network } from '../api/models';
 
 // === Core Jetton Information ===
 export interface JettonInfo {
+    /** Jetton master contract address. */
     address: string;
+    /** Display name of the jetton (e.g., `"Tether USD"`). */
     name: string;
+    /** Ticker symbol (e.g., `"USDT"`). */
     symbol: string;
+    /** Free-form description set by the issuer. */
     description: string;
+    /** Number of decimal places used to format raw amounts (e.g., `6` for USDT). */
     decimals?: number;
+    /** Total supply in raw smallest units. */
     totalSupply?: string;
+    /** URL of the jetton's image. */
     image?: string;
+    /** Inline image data (Base64) when no `image` URL is published. */
     image_data?: string;
+    /** Off-chain metadata URI (TEP-64). */
     uri?: string;
+    /** Verification status reported by the indexer. */
     verification?: JettonVerification;
+    /** Additional indexer-supplied metadata that doesn't fit the canonical fields. */
     metadata?: Record<string, unknown>;
 }
 
 export interface JettonVerification {
+    /** `true` when the indexer has verified this jetton against an allow-list. */
     verified: boolean;
+    /** Origin of the verification claim. */
     source?: 'toncenter' | 'community' | 'manual';
+    /** Free-form warnings the UI should surface (e.g., scam indicators). */
     warnings?: string[];
 }
 
diff --git a/packages/walletkit/src/types/toncenter/ApiClient.ts b/packages/walletkit/src/types/toncenter/ApiClient.ts
index e0ad6d43a..1978103e9 100644
--- a/packages/walletkit/src/types/toncenter/ApiClient.ts
+++ b/packages/walletkit/src/types/toncenter/ApiClient.ts
@@ -95,34 +95,52 @@ export interface GetEventsResponse {
 }
 
 export interface ApiClient {
+    /** Look up specific NFT items by address. */
     nftItemsByAddress(request: NFTsRequest): Promise<NFTsResponse>;
+    /** List NFT items held by an owner; supports pagination. */
     nftItemsByOwner(request: UserNFTsRequest): Promise<NFTsResponse>;
+    /** Run an emulation pass on a Base64-encoded BoC; returns the predicted account-state changes and emitted events without sending the message. */
     fetchEmulation(messageBoc: Base64String, ignoreSignature?: boolean): Promise<ToncenterEmulationResult>;
+    /** Broadcast a signed BoC to the network and return the message hash. */
     sendBoc(boc: Base64String): Promise<string>;
+    /** Run an on-chain `get` method against a contract and read its TVM stack output. */
     runGetMethod(
         address: UserFriendlyAddress,
         method: string,
         stack?: RawStackItem[],
         seqno?: number,
     ): Promise<GetMethodResult>; // TODO - Make serializable
+    /** Read the full on-chain account state (code, data, status, balance) for an address. */
     getAccountState(address: UserFriendlyAddress, seqno?: number): Promise<FullAccountState>;
+    /** Read the TON balance of an address in raw nanotons. */
     getBalance(address: UserFriendlyAddress, seqno?: number): Promise<TokenAmount>;
 
+    /** List transactions for an address; ordered newest-first, paginated via `LimitRequest`. */
     getAccountTransactions(request: TransactionsByAddressRequest): Promise<TransactionsResponse>;
+    /** Fetch a transaction by its message or body hash. */
     getTransactionsByHash(request: GetTransactionByHashRequest): Promise<TransactionsResponse>;
 
+    /** List pending (unconfirmed) transactions by accounts or trace ids; useful for "in-flight" UIs. */
     getPendingTransactions(request: GetPendingTransactionsRequest): Promise<TransactionsResponse>;
 
+    /** Fetch a confirmed trace (the tree of internal messages spawned by an external one). */
     getTrace(request: GetTraceRequest): Promise<ToncenterTracesResponse>;
+    /** Fetch a pending trace by external-message hash, while it's still in flight. */
     getPendingTrace(request: GetPendingTraceRequest): Promise<ToncenterTracesResponse>;
 
+    /** Resolve a TON DNS domain to the wallet address it points at; `null` when unset. */
     resolveDnsWallet(domain: string): Promise<string | null>;
+    /** Reverse-resolve a wallet address to a TON DNS domain that points at it; `null` when none. */
     backResolveDnsWallet(address: UserFriendlyAddress): Promise<string | null>;
 
+    /** Look up jetton masters by address — returns indexer metadata for the requested jettons. */
     jettonsByAddress(request: GetJettonsByAddressRequest): Promise<ToncenterResponseJettonMasters>;
+    /** List jetton holdings owned by an address — returns balances + jetton-master metadata. */
     jettonsByOwnerAddress(request: GetJettonsByOwnerRequest): Promise<JettonsResponse>;
 
+    /** List parsed account events (jetton transfers, NFT moves, swaps, …) for an address. */
     getEvents(request: GetEventsRequest): Promise<GetEventsResponse>;
 
+    /** Read the latest masterchain info — last seqno, shards, time. */
     getMasterchainInfo(): Promise<MasterchainInfo>;
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 17e9def08..e82ebbd46 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -517,7 +517,72 @@ importers:
         specifier: 5.9.3
         version: 5.9.3
 
-  demo/examples:
+  demo/v4ledger-adapter:
+    dependencies:
+      '@ledgerhq/hw-transport':
+        specifier: 6.32.0
+        version: 6.32.0
+      '@ton-community/ton-ledger':
+        specifier: ^7.3.0
+        version: 7.3.0(@ton/core@0.63.1(@ton/crypto@3.3.0))
+      '@ton/core':
+        specifier: 'catalog:'
+        version: 0.63.1(@ton/crypto@3.3.0)
+      '@ton/walletkit':
+        specifier: workspace:*
+        version: link:../../packages/walletkit
+      '@tonconnect/protocol':
+        specifier: 'catalog:'
+        version: 2.4.0
+    devDependencies:
+      '@ledgerhq/hw-transport-node-hid':
+        specifier: 6.30.0
+        version: 6.30.0
+      dotenv:
+        specifier: ^17.4.2
+        version: 17.4.2
+      rimraf:
+        specifier: ^6.1.2
+        version: 6.1.3
+      typescript:
+        specifier: ~5.9.3
+        version: 5.9.3
+
+  demo/wallet-core:
+    dependencies:
+      '@demo/v4ledger-adapter':
+        specifier: workspace:*
+        version: link:../v4ledger-adapter
+      '@ton/core':
+        specifier: 'catalog:'
+        version: 0.63.1(@ton/crypto@3.3.0)
+      '@ton/crypto':
+        specifier: 'catalog:'
+        version: 3.3.0
+      '@ton/walletkit':
+        specifier: workspace:*
+        version: link:../../packages/walletkit
+      immer:
+        specifier: ^10.2.0
+        version: 10.2.0
+      react:
+        specifier: 'catalog:'
+        version: 19.2.3
+      zustand:
+        specifier: ^5.0.8
+        version: 5.0.10(@types/react@19.2.14)(immer@10.2.0)(react@19.2.3)(use-sync-external-store@1.6.0(react@19.2.3))
+    devDependencies:
+      '@types/react':
+        specifier: 'catalog:'
+        version: 19.2.14
+      rimraf:
+        specifier: ^6.1.2
+        version: 6.1.3
+      typescript:
+        specifier: ~5.9.3
+        version: 5.9.3
+
+  docs/examples:
     dependencies:
       '@tanstack/react-query':
         specifier: 'catalog:'
@@ -572,67 +637,31 @@ importers:
         specifier: ^4.1.4
         version: 4.1.4(@types/node@25.6.0)(@vitest/coverage-v8@4.1.4)(@vitest/ui@4.1.4)(happy-dom@20.8.9)(vite@8.0.8(@types/node@25.6.0)(esbuild@0.27.7)(jiti@2.6.1)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.3))
 
-  demo/v4ledger-adapter:
+  docs/reference-generator:
     dependencies:
-      '@ledgerhq/hw-transport':
-        specifier: 6.32.0
-        version: 6.32.0
-      '@ton-community/ton-ledger':
-        specifier: ^7.3.0
-        version: 7.3.0(@ton/core@0.63.1(@ton/crypto@3.3.0))
-      '@ton/core':
-        specifier: 'catalog:'
-        version: 0.63.1(@ton/crypto@3.3.0)
-      '@ton/walletkit':
-        specifier: workspace:*
-        version: link:../../packages/walletkit
-      '@tonconnect/protocol':
-        specifier: 'catalog:'
-        version: 2.4.0
+      ts-morph:
+        specifier: ^28.0.0
+        version: 28.0.0
     devDependencies:
-      '@ledgerhq/hw-transport-node-hid':
-        specifier: 6.30.0
-        version: 6.30.0
-      dotenv:
-        specifier: ^17.4.2
-        version: 17.4.2
-      rimraf:
-        specifier: ^6.1.2
-        version: 6.1.3
+      tsx:
+        specifier: ^4.21.0
+        version: 4.21.0
       typescript:
         specifier: ~5.9.3
         version: 5.9.3
 
-  demo/wallet-core:
+  docs/template-resolver:
     dependencies:
-      '@demo/v4ledger-adapter':
-        specifier: workspace:*
-        version: link:../v4ledger-adapter
-      '@ton/core':
-        specifier: 'catalog:'
-        version: 0.63.1(@ton/crypto@3.3.0)
-      '@ton/crypto':
-        specifier: 'catalog:'
-        version: 3.3.0
-      '@ton/walletkit':
-        specifier: workspace:*
-        version: link:../../packages/walletkit
-      immer:
-        specifier: ^10.2.0
-        version: 10.2.0
-      react:
-        specifier: 'catalog:'
-        version: 19.2.3
-      zustand:
-        specifier: ^5.0.8
-        version: 5.0.10(@types/react@19.2.14)(immer@10.2.0)(react@19.2.3)(use-sync-external-store@1.6.0(react@19.2.3))
+      eslint:
+        specifier: ^9.39.4
+        version: 9.39.4(jiti@2.6.1)
+      prettier:
+        specifier: ^3.6.2
+        version: 3.8.1
     devDependencies:
-      '@types/react':
-        specifier: 'catalog:'
-        version: 19.2.14
-      rimraf:
-        specifier: ^6.1.2
-        version: 6.1.3
+      tsx:
+        specifier: ^4.21.0
+        version: 4.21.0
       typescript:
         specifier: ~5.9.3
         version: 5.9.3
@@ -4072,6 +4101,9 @@ packages:
   '@truecarry/webext-bridge@6.0.2':
     resolution: {integrity: sha512-Q2gmBkfbForHKxvDKI2Ep5LGih7+wEsjluXqNxUHNXW2b8ztNmuI77nZBqNLb83B3AeKGxe0txPnCycPVgYzXA==}
 
+  '@ts-morph/common@0.29.0':
+    resolution: {integrity: sha512-35oUmphHbJvQ/+UTwFNme/t2p3FoKiGJ5auTjjpNTop2dyREspirjMy82PLSC1pnDJ8ah1GU98hwpVt64YXQsg==}
+
   '@tsconfig/node10@1.0.12':
     resolution: {integrity: sha512-UCYBaeFvM11aU2y3YPZ//O5Rhj+xKyzy7mvcIoAjASbigy8mHMryP5cK7dgjlz2hWxh1g5pLw084E0a/wlUSFQ==}
 
@@ -5196,6 +5228,9 @@ packages:
     resolution: {integrity: sha512-QVb0dM5HvG+uaxitm8wONl7jltx8dqhfU33DcqtOZcLSVIKSDDLDi7+0LbAKiyI8hD9u42m2YxXSkMGWThaecQ==}
     engines: {iojs: '>= 1.0.0', node: '>= 0.12.0'}
 
+  code-block-writer@13.0.3:
+    resolution: {integrity: sha512-Oofo0pq3IKnsFtuHqSF7TqBfr71aeyZDVJ0HpmqB7FBM2qEigL0iPONSCZSO9pE9dZTAxANe5XHG9Uy0YMv8cg==}
+
   collect-v8-coverage@1.0.3:
     resolution: {integrity: sha512-1L5aqIkwPfiodaMgQunkF1zRhNqifHBmtbbbxcr6yVxxBnliw4TDOW6NxpO8DJLgJ16OT+Y4ztZqP6p/FtXnAw==}
 
@@ -9394,6 +9429,9 @@ packages:
     engines: {node: '>=22.0.0'}
     hasBin: true
 
+  ts-morph@28.0.0:
+    resolution: {integrity: sha512-Wp3tnZ2bzwxyTZMtgWVzXDfm7lB1Drz+y9DmmYH/L702PQhPyVrp3pkou3yIz4qjS14GY9kcpmLiOOMvl8oG1g==}
+
   ts-node@10.9.2:
     resolution: {integrity: sha512-f0FFpIdcHgn8zcPSbf1dRevwt047YMnaiJM3u2w2RewrB+fob/zePZcrOyQoLMMO7aBIddLcQIEK5dYjkLnGrQ==}
     hasBin: true
@@ -9673,14 +9711,17 @@ packages:
 
   uuid@7.0.3:
     resolution: {integrity: sha512-DPSke0pXhTZgoF/d+WSt2QaKMCFSfx7QegxEWT+JOuHF5aWrKEn0G+ztjuJg/gG8/ItK+rbPCD/yNv8yyih6Cg==}
+    deprecated: uuid@10 and below is no longer supported.  For ESM codebases, update to uuid@latest.  For CommonJS codebases, use uuid@11 (but be aware this version will likely be deprecated in 2028).
     hasBin: true
 
   uuid@8.3.2:
     resolution: {integrity: sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==}
+    deprecated: uuid@10 and below is no longer supported.  For ESM codebases, update to uuid@latest.  For CommonJS codebases, use uuid@11 (but be aware this version will likely be deprecated in 2028).
     hasBin: true
 
   uuid@9.0.1:
     resolution: {integrity: sha512-b+1eJOlsR9K8HJpow9Ok3fiWOWSIcIzXodvv0rQjVoOVNpWMpxf1wZNpt4y9h10odCNrqnYp1OBzRktckBe3sA==}
+    deprecated: uuid@10 and below is no longer supported.  For ESM codebases, update to uuid@latest.  For CommonJS codebases, use uuid@11 (but be aware this version will likely be deprecated in 2028).
     hasBin: true
 
   v8-compile-cache-lib@3.0.1:
@@ -13891,7 +13932,7 @@ snapshots:
   '@testing-library/dom@10.4.1':
     dependencies:
       '@babel/code-frame': 7.29.0
-      '@babel/runtime': 7.28.6
+      '@babel/runtime': 7.29.2
       '@types/aria-query': 5.0.4
       aria-query: 5.3.0
       dom-accessibility-api: 0.5.16
@@ -13920,7 +13961,7 @@ snapshots:
 
   '@testing-library/react@16.3.2(@testing-library/dom@10.4.1)(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
     dependencies:
-      '@babel/runtime': 7.28.6
+      '@babel/runtime': 7.29.2
       '@testing-library/dom': 10.4.1
       react: 19.2.3
       react-dom: 19.2.3(react@19.2.3)
@@ -14085,6 +14126,12 @@ snapshots:
       tiny-uid: 1.1.2
       webextension-polyfill: 0.9.0
 
+  '@ts-morph/common@0.29.0':
+    dependencies:
+      minimatch: 10.2.5
+      path-browserify: 1.0.1
+      tinyglobby: 0.2.16
+
   '@tsconfig/node10@1.0.12': {}
 
   '@tsconfig/node12@1.0.11': {}
@@ -15434,6 +15481,8 @@ snapshots:
 
   co@4.6.0: {}
 
+  code-block-writer@13.0.3: {}
+
   collect-v8-coverage@1.0.3: {}
 
   color-convert@1.9.3:
@@ -18084,7 +18133,7 @@ snapshots:
 
   metro-runtime@0.83.3:
     dependencies:
-      '@babel/runtime': 7.28.6
+      '@babel/runtime': 7.29.2
       flow-enums-runtime: 0.0.6
 
   metro-runtime@0.83.5:
@@ -20368,8 +20417,8 @@ snapshots:
 
   tinyglobby@0.2.15:
     dependencies:
-      fdir: 6.5.0(picomatch@4.0.3)
-      picomatch: 4.0.3
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
 
   tinyglobby@0.2.16:
     dependencies:
@@ -20460,6 +20509,11 @@ snapshots:
       tslib: 2.8.1
       typescript: 5.9.3
 
+  ts-morph@28.0.0:
+    dependencies:
+      '@ts-morph/common': 0.29.0
+      code-block-writer: 13.0.3
+
   ts-node@10.9.2(@types/node@25.6.0)(typescript@5.9.3):
     dependencies:
       '@cspotcode/source-map-support': 0.8.1
@@ -20495,7 +20549,7 @@ snapshots:
 
   tsx@4.21.0:
     dependencies:
-      esbuild: 0.27.3
+      esbuild: 0.27.7
       get-tsconfig: 4.13.6
     optionalDependencies:
       fsevents: 2.3.3
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 582e16182..dac148b37 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -2,6 +2,7 @@ packages:
   - packages/*
   - apps/*
   - demo/*
+  - docs/*
 
 catalog:
   '@tanstack/query-core': 5.99.0