diff --git a/README.md b/README.md index 2a43386..491b9e9 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,80 @@ -# WDK docs +# WDK Docs Official documentation for the Wallet Development Kit (WDK) by Tether. Live at: [docs.wdk.tether.io](https://docs.wdk.tether.io) -## Architecture +## Stack -WDK docs website is a static website generated via SSG functionality from a Next.js+[Fumadocs](https://fumadocs.dev) application. +The docs site is a static Next.js application built with [Fumadocs](https://fumadocs.dev). +- Docs content lives in `content/docs/**/*.mdx`. +- Sidebar navigation is defined in `src/lib/custom-tree.ts`. +- Generated Fumadocs artifacts live under `.source/` and should not be edited directly. +- Generated search output at `public/api/search.json` is created by dev/build scripts and should not be committed unless the project intentionally starts tracking it. -## Development +## Prerequisites -`@tetherto/docs-seo-*` is installed from GitHub Packages. Add a package-read -token to `.env.local`, then export it before installing dependencies: +- Node.js 22 or newer. +- npm. +- A GitHub token with `read:packages` access for installing `@tetherto/docs-seo-*` from GitHub Packages. + +## Setup + +Copy the local environment template and add your package-read token: ```bash cp .env.example .env.local -set -a && . ./.env.local && set +a ``` +Set `GITHUB_TOKEN` in `.env.local`, then export it before installing dependencies: + ```bash +set -a && . ./.env.local && set +a npm install +``` + +## Local Preview + +Start the local docs server: + +```bash npm run dev ``` +The dev server runs on [http://localhost:3001](http://localhost:3001). The command generates the local search index first, then starts Next.js with Fumadocs. + +Useful smoke-test routes: + +- [http://localhost:3001/](http://localhost:3001/) +- [http://localhost:3001/overview/changelog/](http://localhost:3001/overview/changelog/) +- [http://localhost:3001/sdk/all-modules/](http://localhost:3001/sdk/all-modules/) +- [http://localhost:3001/sdk/swidge-modules/](http://localhost:3001/sdk/swidge-modules/) +- [http://localhost:3001/sdk/core-module/guides/protocol-integration/](http://localhost:3001/sdk/core-module/guides/protocol-integration/) + +If port `3001` is already in use, stop the other process or run Next directly with another port: + +```bash +DOCS_SEO_QUIET_GENERATED=1 NODE_OPTIONS='--import tsx/esm' npx next dev --turbo -p 3002 +``` + +## Validation + +Run these checks before opening or updating a PR: + +```bash +git diff --check +npm run check:meta +LINK_CHECK_EXTERNAL=false npm run check:links +npm run build +``` + +Use the external link checker when network checks are required: + +```bash +npm run check:links +``` + ## Build ```bash @@ -56,10 +107,10 @@ Important environment variables: ```bash # Comprehensive markdown-level link checker (internal + external + anchors + assets) -node scripts/check-links.mjs +npm run check:links # Internal-only (fast, no network) -LINK_CHECK_EXTERNAL=false node scripts/check-links.mjs +LINK_CHECK_EXTERNAL=false npm run check:links ``` ## License diff --git a/content/docs/ai/agent-skills.mdx b/content/docs/ai/agent-skills.mdx index e5de0f5..8247bd7 100644 --- a/content/docs/ai/agent-skills.mdx +++ b/content/docs/ai/agent-skills.mdx @@ -16,7 +16,7 @@ WDK provides agent skills: structured instruction sets that teach AI agents how An agent skill is a structured set of instructions and reference documentation that teaches an AI agent to use a specific tool or SDK. Skills follow the [AgentSkills specification](https://agentskills.io/specification). Each skill is a `SKILL.md` file with frontmatter metadata and detailed instructions that any compatible agent can load and execute. -WDK publishes a skill that covers the full SDK surface: wallet modules, swap, bridge, lending, fiat on/off-ramps, and the indexer. When an agent loads the skill, it learns WDK's APIs so you don't need blockchain expertise to get started. You can view the full skill file on [GitHub](https://github.com/tetherto/wdk-docs/blob/main/skills/wdk/SKILL.md). +WDK publishes a skill that covers the full SDK surface: wallet modules, swidge, swap, bridge, lending, fiat on/off-ramps, and the indexer. When an agent loads the skill, it learns WDK's APIs so you don't need blockchain expertise to get started. You can view the full skill file on [GitHub](https://github.com/tetherto/wdk-docs/blob/main/skills/wdk/SKILL.md). ## Capabilities diff --git a/content/docs/overview/changelog.mdx b/content/docs/overview/changelog.mdx index 719d5a7..36d8ce6 100644 --- a/content/docs/overview/changelog.mdx +++ b/content/docs/overview/changelog.mdx @@ -10,6 +10,13 @@ Stay up to date with the latest improvements, new features, and bug fixes across --- +### May 19, 2026 + +**What's New** +- **[Swidge Protocol Interface](../sdk/swidge-modules)**: New page covering WDK's shared route interface for swap-only, bridge-only, and combined swap and bridge providers, including `quoteSwidge()`, `executeSwidge()`, `getSwidgeStatus()`, route options, result fields, status values, fee handling, and migration guidance for the existing standalone swap and bridge interfaces. + +--- + ### April 22, 2026 **Fixes** diff --git a/content/docs/sdk/all-modules.mdx b/content/docs/sdk/all-modules.mdx index 6146cb1..e94bb5a 100644 --- a/content/docs/sdk/all-modules.mdx +++ b/content/docs/sdk/all-modules.mdx @@ -1,6 +1,6 @@ --- title: All Modules -description: Complete list of all available WDK modules including wallet, swap, bridge, lending, and fiat modules. +description: Complete list of all available WDK modules including wallet, swidge, swap, bridge, lending, and fiat modules. docType: reference schemaType: TechArticle --- @@ -31,6 +31,12 @@ Wallet modules provide blockchain-specific wallet functionality for managing add | [`@tetherto/wdk-wallet-solana`](https://github.com/tetherto/wdk-wallet-solana) | Solana | Solana blockchain wallet | [Docs](./wallet-modules/wallet-solana/) | | [`@tetherto/wdk-wallet-spark`](https://github.com/tetherto/wdk-wallet-spark) | Spark | Spark/Lightning Bitcoin L2 wallet | [Docs](./wallet-modules/wallet-spark/) | +## Swidge Modules + +Swidge modules provide one interface for providers that can quote and execute swap-only, bridge-only, or combined swap and bridge routes. + +No released swidge provider module is listed yet. See the [swidge protocol interface](./swidge-modules/) for the shared API shape provider modules should implement. + ## Swap Modules DEX swap functionality for token exchanges. diff --git a/content/docs/sdk/bridge-modules/index.mdx b/content/docs/sdk/bridge-modules/index.mdx index e64e297..f0d257e 100644 --- a/content/docs/sdk/bridge-modules/index.mdx +++ b/content/docs/sdk/bridge-modules/index.mdx @@ -7,6 +7,10 @@ schemaType: TechArticle The Wallet Development Kit (WDK) provides a set of modules that support bridging between different blockchain networks. All modules share a common interface, ensuring consistent behavior across different blockchain implementations. + +WDK is introducing the [swidge interface](/sdk/swidge-modules) for providers that can support swap-only, bridge-only, or combined swap and bridge routes through one route interface. Existing bridge modules remain supported, but the standalone bridge interface is expected to be deprecated in a future release once swidge provider modules are available. + + ## Bridge Protocol Modules Cross-chain bridge functionality for token transfers between blockchains: @@ -27,4 +31,4 @@ To get started with WDK modules, follow these steps: You can also: - Learn about key concepts like [Account Abstraction](../../resources/concepts#account-abstraction) and other important definitions -- Use one of our ready-to-use examples to be production ready \ No newline at end of file +- Use one of our ready-to-use examples to be production ready diff --git a/content/docs/sdk/core-module/api-reference.mdx b/content/docs/sdk/core-module/api-reference.mdx index d4b1bf5..4ceab85 100644 --- a/content/docs/sdk/core-module/api-reference.mdx +++ b/content/docs/sdk/core-module/api-reference.mdx @@ -497,8 +497,23 @@ interface ILendingProtocol { borrow(options: LendingOptions): Promise; repay(options: LendingOptions): Promise; } + +// Swidge Protocol +interface ISwidgeProtocol { + quoteSwidge(options: SwidgeOptions): Promise; + executeSwidge( + quote: SwidgeQuote, + config?: SwidgeProtocolConfig + ): Promise; + getSwidgeStatus( + id: string, + options?: SwidgeStatusOptions + ): Promise; +} ``` +`ISwidgeProtocol` is the shared interface for providers that can execute swap-only, bridge-only, or combined swap and bridge routes. See [Swidge Protocol Interface](/sdk/swidge-modules) for the full option, quote, result, fee, and status shapes. + *** ## Next Steps diff --git a/content/docs/sdk/core-module/guides/protocol-integration.mdx b/content/docs/sdk/core-module/guides/protocol-integration.mdx index 5e89537..5612295 100644 --- a/content/docs/sdk/core-module/guides/protocol-integration.mdx +++ b/content/docs/sdk/core-module/guides/protocol-integration.mdx @@ -1,11 +1,11 @@ --- title: Integrate Protocols -description: Learn how to use Swaps, Bridges, and Lending protocols. +description: Learn how to use Swidge, Swap, Bridge, and Lending protocols. docType: how-to schemaType: TechArticle --- -The WDK Core module supports registering external protocols. This allows you to extend the basic wallet functionality with advanced features like [token swapping](#swapping-tokens), [cross-chain bridging](#bridging-assets), and lending, all through a unified interface. +The WDK Core module supports registering external protocols. This allows you to extend the basic wallet functionality with advanced features like [swidge routes](/sdk/swidge-modules), [token swapping](#swapping-tokens), [cross-chain bridging](#bridging-assets), and lending. ## Register Protocols @@ -54,7 +54,35 @@ const wdk = new WDK(seedPhrase) ## Use Protocols -Once [registered](#register-protocols), you can access the protocol instance using the specific getter methods: `getSwapProtocol`, `getBridgeProtocol`, or `getLendingProtocol`. +Once [registered](#register-protocols), you can access the protocol instance using the specific getter methods, such as `getSwapProtocol`, `getBridgeProtocol`, `getLendingProtocol`, or `getFiatProtocol`. + +### Swidge Routes + +Use a swidge provider module when one provider can quote and execute swap-only, bridge-only, or combined swap and bridge routes through the same interface. The shared swidge interface quotes with `quoteSwidge()`, executes with `executeSwidge()`, and tracks asynchronous settlement with `getSwidgeStatus()`. The example below assumes `swidge` is an instance of a concrete provider module that implements the shared interface. + +```typescript title="Swidge route flow" +const quote = await swidge.quoteSwidge({ + fromToken: '0xSourceToken...', + toToken: '0xDestinationToken...', + toChain: 'arbitrum', + recipient: '0xRecipient...', + fromTokenAmount: 1000000n, + slippage: 0.01 +}) + +const result = await swidge.executeSwidge(quote, { + swidgeMaxFee: 200000000000000n +}) + +const status = await swidge.getSwidgeStatus(result.id, { + toChain: 'arbitrum', + providerData: result.providerData +}) +``` + + +Existing swap and bridge modules keep their current accessors until swidge provider modules ship. See the [swidge protocol interface](/sdk/swidge-modules) for the shared API shape. + ### Swapping Tokens diff --git a/content/docs/sdk/core-module/usage.mdx b/content/docs/sdk/core-module/usage.mdx index 00e2eb3..f92eaf8 100644 --- a/content/docs/sdk/core-module/usage.mdx +++ b/content/docs/sdk/core-module/usage.mdx @@ -22,7 +22,7 @@ Retrieve accounts and check balances. Transfer native tokens. -Use Swap, Bridge, and Lending protocols. +Use Swidge, Swap, Bridge, and Lending protocols. Add logging and failover protection. diff --git a/content/docs/sdk/get-started.mdx b/content/docs/sdk/get-started.mdx index b9ffce2..41216df 100644 --- a/content/docs/sdk/get-started.mdx +++ b/content/docs/sdk/get-started.mdx @@ -14,7 +14,7 @@ It is built on some core principles: **self-custodial and stateless** (private k * **Multi-Chain Support**: Bitcoin, Ethereum, TON, TRON, Solana, Spark, and more * **Account Abstraction**: Gasless transactions on supported chains -* **DeFi Integration**: Plug-in support for swaps, bridges, and lending protocols +* **DeFi Integration**: Plug-in support for swidge routes, swaps, bridges, and lending protocols * **Extensible Design**: Add custom modules for new blockchains or protocols *** @@ -32,7 +32,7 @@ New functionality is added through modules rather than modifying core code. Also #### Module Types -WDK modules are organized into five main categories, each serving a specific purpose in the blockchain application stack: +WDK modules are organized into six main categories, each serving a specific purpose in the blockchain application stack: @@ -41,6 +41,9 @@ Main orchestrator and shared utilities Blockchain-specific wallet operations + +Swap-only, bridge-only, or combined asset routes + Token swapping across DEXs diff --git a/content/docs/sdk/swap-modules/index.mdx b/content/docs/sdk/swap-modules/index.mdx index 8a3c58a..0068794 100644 --- a/content/docs/sdk/swap-modules/index.mdx +++ b/content/docs/sdk/swap-modules/index.mdx @@ -7,6 +7,10 @@ schemaType: TechArticle The Swap Development Kit (WDK) provides a set of modules that support swap on top of multiple blockchain networks. All modules share a common interface, ensuring consistent behavior across different blockchain implementations. + +WDK is introducing the [swidge interface](/sdk/swidge-modules) for providers that can support swap-only, bridge-only, or combined swap and bridge routes through one route interface. Existing swap modules remain supported, but the standalone swap interface is expected to be deprecated in a future release once swidge provider modules are available. + + ## Swap Protocol Modules DeFi swap functionality for token exchanges across different DEXs: diff --git a/content/docs/sdk/swidge-modules/index.mdx b/content/docs/sdk/swidge-modules/index.mdx new file mode 100644 index 0000000..1654599 --- /dev/null +++ b/content/docs/sdk/swidge-modules/index.mdx @@ -0,0 +1,162 @@ +--- +title: Swidge Protocol Interface +description: Learn the WDK swidge interface for swap-only, bridge-only, and combined asset routes. +docType: reference +schemaType: TechArticle +--- + +The swidge interface is WDK's shared route interface for protocol providers that can quote and execute asset movement. A swidge route can be a swap-only route, a bridge-only route, or a combined swap and bridge route. It gives builders one quote, execution, and status shape for routes where the token changes, the chain changes, or both change. + + +Existing standalone swap and bridge interfaces remain supported for released modules. WDK plans to deprecate those standalone interfaces in a future release after swidge provider coverage is available. + + +## When to use swidge + +Use a swidge provider when a route matches any of these shapes: + +- Swap one token into another token on the same chain. +- Bridge the same token from one chain to another chain. +- Swap and bridge in one route. +- Route between different tokens, different chains, or both. + +Use the existing [swap modules](/sdk/swap-modules) and [bridge modules](/sdk/bridge-modules) for provider modules that have not shipped a swidge implementation yet. + +## Interface methods + +Concrete swidge provider modules extend `SwidgeProtocol` from `@tetherto/wdk-wallet/protocols`. The base interface exposes three methods: + +| Method | Description | +|--------|-------------| +| `quoteSwidge(options)` | Quotes the route before execution. | +| `executeSwidge(quote, config?)` | Executes a quote returned by `quoteSwidge()`. This is a write method and must be user-confirmed. | +| `getSwidgeStatus(id, options?)` | Looks up the status of an in-flight swidge execution. | + +```typescript title="Swidge protocol shape" +interface ISwidgeProtocol { + quoteSwidge(options: SwidgeOptions): Promise + executeSwidge( + quote: SwidgeQuote, + config?: SwidgeProtocolConfig + ): Promise + getSwidgeStatus( + id: string, + options?: SwidgeStatusOptions + ): Promise +} +``` + +## Quote a route + +Call `quoteSwidge()` before execution so the user can review source amount, expected destination amount, minimum output, fees, and quote expiry. + +```typescript title="Quote a swidge route" +const quote = await swidge.quoteSwidge({ + fromToken: '0xSourceToken...', + toToken: '0xDestinationToken...', + toChain: 'arbitrum', + recipient: '0xRecipient...', + fromTokenAmount: 1000000n, + slippage: 0.01 +}) + +console.log('Expected output:', quote.toTokenAmount) +console.log('Minimum output:', quote.toTokenAmountMin) +console.log('Fees:', quote.fees) +``` + +`SwidgeOptions` supports exact-in and exact-out routes: + +| Option | Type | Description | +|--------|------|-------------| +| `fromToken` | `string` | Source token address or provider-specific asset identifier. | +| `toToken` | `string` | Destination token address or provider-specific asset identifier. | +| `toChain` | `string \| number` | Destination chain identifier. For same-chain swaps, this is usually the source or account chain. | +| `recipient` | `string` | Optional recipient for the output tokens. | +| `slippage` | `number` | Optional decimal slippage tolerance, for example `0.01` for 1%. | +| `fromTokenAmount` | `number \| bigint` | Exact source amount to spend. Do not pass with `toTokenAmount`. | +| `toTokenAmount` | `number \| bigint` | Exact destination amount to receive. Do not pass with `fromTokenAmount`. | + +## Execute a quote + +Call `executeSwidge()` with the quote returned by `quoteSwidge()`. Apply fee caps with `SwidgeProtocolConfig` where supported by the provider. + +```typescript title="Execute a swidge quote" +const result = await swidge.executeSwidge(quote, { + swidgeMaxFee: 200000000000000n, + swidgeMaxProtocolFee: 100000000000000n +}) + +console.log('Swidge ID:', result.id) +console.log('Primary transaction:', result.hash) +console.log('Transactions:', result.transactions) +``` + + +`executeSwidge()` can submit one or more transactions. Ask for explicit user confirmation before calling it, and display the quote amounts, fee breakdown, route, and recipient first. + + +## Track status + +Use `getSwidgeStatus()` when the provider returns an execution ID and the final destination result may settle asynchronously. + +```typescript title="Check swidge status" +const status = await swidge.getSwidgeStatus(result.id, { + fromChain: 'ethereum', + toChain: 'arbitrum', + providerData: result.providerData +}) + +if (status.status === 'completed') { + console.log('Swidge complete') +} +``` + +Supported statuses are: + +| Status | Meaning | +|--------|---------| +| `pending` | The route has started and is waiting for progress. | +| `action-required` | The user or integrator must take another action. | +| `completed` | The route completed successfully. | +| `failed` | The route failed. | +| `refund-pending` | A refund has started but has not completed. | +| `refunded` | The route was refunded. | +| `cancelled` | The route was cancelled. | +| `expired` | The quote or route expired. | +| `partial` | The route partially completed. | + +## Result fields + +`SwidgeQuote` and `SwidgeResult` can include an itemized `fees` array. Prefer displaying the itemized fees when available because providers may charge gas, protocol, bridge, relayer, application, affiliate, liquidity, or other fee types. + +| Field | Type | Description | +|-------|------|-------------| +| `id` | `string` | Execution identifier returned by `executeSwidge()`. | +| `hash` | `string` | Primary transaction hash, if available immediately. | +| `transactions` | `SwidgeTransaction[]` | Source, destination, approval, refund, or other transaction hashes. | +| `fromTokenAmount` | `bigint` | Actual source amount spent. | +| `toTokenAmount` | `bigint` | Actual or expected destination amount. | +| `toTokenAmountMin` | `bigint` | Minimum destination amount after slippage. | +| `fee` | `bigint` | Total aggregated fee, if the provider exposes one. | +| `protocolFee` | `bigint` | Protocol-specific fee portion, if exposed. | +| `fees` | `SwidgeFee[]` | Itemized fee breakdown. | +| `providerData` | `object` | Opaque provider payload for execution or status tracking. | + +## Supported assets and chains + +Provider modules should document the route shapes, assets, and chains they support on their module pages. Dedicated discovery methods such as `getSupportedAssets()` and `getSupportedChains()` are not part of the current swidge interface surface documented here. + +## Next steps + + + +Register and use protocol modules with WDK accounts + + +Use existing standalone swap modules + + +Use existing standalone bridge modules + + diff --git a/package-lock.json b/package-lock.json index 0663cfd..a28dbc6 100644 --- a/package-lock.json +++ b/package-lock.json @@ -34,8 +34,8 @@ "mermaid": "^11.15.0", "next": "^16.2.6", "next-themes": "^0.4.6", - "react": "^19.2.3", - "react-dom": "^19.2.3", + "react": "19.2.3", + "react-dom": "19.2.3", "react-icons": "^5.5.0", "rehype-katex": "^7.0.1", "remark-gfm": "^4.0.1", @@ -2024,17 +2024,6 @@ "integrity": "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==", "license": "MIT" }, - "node_modules/@inkeep/cxkit-primitives/node_modules/zod": { - "version": "3.25.76", - "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", - "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", - "license": "MIT", - "optional": true, - "peer": true, - "funding": { - "url": "https://github.com/sponsors/colinhacks" - } - }, "node_modules/@inkeep/cxkit-react": { "version": "0.5.111", "resolved": "https://registry.npmjs.org/@inkeep/cxkit-react/-/cxkit-react-0.5.111.tgz", @@ -4852,7 +4841,7 @@ "node": ">= 12.22.0 < 13 || >= 14.17.0 < 15 || >= 15.12.0 < 16 || >= 16.0.0" } }, - "node_modules/@takumi-rs/helpers": { + "node_modules/@takumi-rs/core/node_modules/@takumi-rs/helpers": { "version": "1.1.2", "resolved": "https://registry.npmjs.org/@takumi-rs/helpers/-/helpers-1.1.2.tgz", "integrity": "sha512-Edvmk7UzPhlbUCYpIqeBBfq9h/lAeWAhtwIhJJ10vxv7qNWjgfIPakzNWeAYhFVj8KT5y47S3RLT3cKVniqI5g==", @@ -4888,6 +4877,24 @@ "@takumi-rs/helpers": "1.1.2" } }, + "node_modules/@takumi-rs/wasm/node_modules/@takumi-rs/helpers": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@takumi-rs/helpers/-/helpers-1.1.2.tgz", + "integrity": "sha512-Edvmk7UzPhlbUCYpIqeBBfq9h/lAeWAhtwIhJJ10vxv7qNWjgfIPakzNWeAYhFVj8KT5y47S3RLT3cKVniqI5g==", + "license": "(MIT OR Apache-2.0)", + "peerDependencies": { + "react": "^19.2.5", + "react-dom": "^18.0.0 || ^19.0.0" + }, + "peerDependenciesMeta": { + "react": { + "optional": true + }, + "react-dom": { + "optional": true + } + } + }, "node_modules/@tanem/svg-injector": { "version": "10.1.68", "resolved": "https://registry.npmjs.org/@tanem/svg-injector/-/svg-injector-10.1.68.tgz", @@ -11064,9 +11071,9 @@ "license": "ISC" }, "node_modules/react": { - "version": "19.2.5", - "resolved": "https://registry.npmjs.org/react/-/react-19.2.5.tgz", - "integrity": "sha512-llUJLzz1zTUBrskt2pwZgLq59AemifIftw4aB7JxOqf1HY2FDaGDxgwpAPVzHU1kdWabH7FauP4i1oEeer2WCA==", + "version": "19.2.3", + "resolved": "https://registry.npmjs.org/react/-/react-19.2.3.tgz", + "integrity": "sha512-Ku/hhYbVjOQnXDZFv2+RibmLFGwFdeeKHFcOTlrt7xplBnya5OGn/hIRDsqDiSUcfORsDC7MPxwork8jBwsIWA==", "license": "MIT", "engines": { "node": ">=0.10.0" @@ -12288,6 +12295,24 @@ "@takumi-rs/wasm": "1.1.2" } }, + "node_modules/takumi-js/node_modules/@takumi-rs/helpers": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@takumi-rs/helpers/-/helpers-1.1.2.tgz", + "integrity": "sha512-Edvmk7UzPhlbUCYpIqeBBfq9h/lAeWAhtwIhJJ10vxv7qNWjgfIPakzNWeAYhFVj8KT5y47S3RLT3cKVniqI5g==", + "license": "(MIT OR Apache-2.0)", + "peerDependencies": { + "react": "^19.2.5", + "react-dom": "^18.0.0 || ^19.0.0" + }, + "peerDependenciesMeta": { + "react": { + "optional": true + }, + "react-dom": { + "optional": true + } + } + }, "node_modules/tapable": { "version": "2.3.0", "resolved": "https://registry.npmjs.org/tapable/-/tapable-2.3.0.tgz", diff --git a/package.json b/package.json index c4d0910..a55520b 100644 --- a/package.json +++ b/package.json @@ -46,8 +46,8 @@ "mermaid": "^11.15.0", "next": "^16.2.6", "next-themes": "^0.4.6", - "react": "^19.2.3", - "react-dom": "^19.2.3", + "react": "19.2.3", + "react-dom": "19.2.3", "react-icons": "^5.5.0", "rehype-katex": "^7.0.1", "remark-gfm": "^4.0.1", diff --git a/public/llms-full.txt b/public/llms-full.txt index ff44f55..cb4390e 100644 --- a/public/llms-full.txt +++ b/public/llms-full.txt @@ -1,68 +1,93 @@ -# WDK Documentation +# Welcome to WDK (/) -Base URL: https://docs.wdk.tether.su -Raw markdown is available by appending `.md` to any documentation page URL. -## Welcome to WDK -URL: https://docs.wdk.tether.su/ -Description: >- -The **Wallet Development Kit _by Tether_ (WDK)** is Tether's open-source toolkit that empowers humans, machines and AI agents alike to build, deploy and use secure, multi-chain, self-custodial wallets that can be integrated anywhere from the smallest embedded device to any mobile, desktop and server operating system. WDK enables trillions of self-custodial wallets. + +The **Wallet Development Kit *by Tether* (WDK)** is Tether's open-source toolkit that empowers humans, machines and AI agents alike to build, deploy and use secure, multi-chain, self-custodial wallets that can be integrated anywhere from the smallest embedded device to any mobile, desktop and server operating system. WDK enables trillions of self-custodial wallets. WDK provides a set of core libraries that give you the highest level of control and a wide range of user-interface templates and widgets to maximize your development and deployment speed. + + *** ### Discover WDK -Understand WDK core features and design principles + + + Understand WDK core features and design principles + -Discover our philosophy and idea for the future wallets + + Discover our philosophy and idea for the future wallets + -Learn foundational concepts and terminology + + Learn foundational concepts and terminology + + *** ### Start Building -Get started with WDK in a Node.js environment + + + Get started with WDK in a Node.js environment + -Build mobile wallets with React Native Expo + + Build mobile wallets with React Native Expo + -Deploy WDK in lightweight environments + + Deploy WDK in lightweight environments + -Explore our React Native UI Kit with pre-built components + + Explore our React Native UI Kit with pre-built components + + *** ### Get Involved -## Agent Skills -URL: https://docs.wdk.tether.su/ai/agent-skills -Description: Give any AI agent self-custodial wallet capabilities with WDK agent skills + + + + +# Agent Skills (/ai/agent-skills) + + + WDK provides agent skills: structured instruction sets that teach AI agents how to create wallets, send transactions, swap tokens, bridge assets, and interact with DeFi protocols across 20+ blockchains. All operations are self-custodial. Keys stay on your machine, with no third-party custody dependency. -**Skill vs MCP Toolkit**: Use an **agent skill** when your agent platform works with file-based instructions (e.g., OpenClaw, Cursor). Use the [MCP Toolkit](mcp-toolkit/) when your agent supports the Model Context Protocol natively (e.g., Claude, Cursor). Use both for maximum coverage. + + **Skill vs MCP Toolkit**: Use an **agent skill** when your agent platform works with file-based instructions (e.g., OpenClaw, Cursor). Use the [MCP Toolkit](mcp-toolkit/) when your agent supports the Model Context Protocol natively (e.g., Claude, Cursor). Use both for maximum coverage. + ## What Are Agent Skills? An agent skill is a structured set of instructions and reference documentation that teaches an AI agent to use a specific tool or SDK. Skills follow the [AgentSkills specification](https://agentskills.io/specification). Each skill is a `SKILL.md` file with frontmatter metadata and detailed instructions that any compatible agent can load and execute. -WDK publishes a skill that covers the full SDK surface: wallet modules, swap, bridge, lending, fiat on/off-ramps, and the indexer. When an agent loads the skill, it learns WDK's APIs so you don't need blockchain expertise to get started. You can view the full skill file on [GitHub](https://github.com/tetherto/wdk-docs/blob/main/skills/wdk/SKILL.md). +WDK publishes a skill that covers the full SDK surface: wallet modules, swidge, swap, bridge, lending, fiat on/off-ramps, and the indexer. When an agent loads the skill, it learns WDK's APIs so you don't need blockchain expertise to get started. You can view the full skill file on [GitHub](https://github.com/tetherto/wdk-docs/blob/main/skills/wdk/SKILL.md). ## Capabilities Once an agent loads the WDK skill, it can: -| Category | Operations | -| --- | --- | -| **Wallets** | Create and recover wallets across EVM chains, Bitcoin, Solana, Spark, TON, and Tron | -| **Transactions** | Send native tokens and token transfers (ERC-20, SPL, Jetton, TRC-20) | -| **Swaps** | DEX swaps via Velora (EVM) and StonFi (TON) | -| **Bridges** | Cross-chain bridges with USDT0 via LayerZero | -| **Lending** | Supply, borrow, repay, and withdraw via Aave V3 | -| **Fiat** | Buy and sell crypto via MoonPay on/off-ramps | -| **Gasless** | Fee-free transfers on TON (via paymaster) and Tron (via gas-free service), and ERC-4337 account abstraction on EVM | +| Category | Operations | +| ---------------- | ------------------------------------------------------------------------------------------------------------------ | +| **Wallets** | Create and recover wallets across EVM chains, Bitcoin, Solana, Spark, TON, and Tron | +| **Transactions** | Send native tokens and token transfers (ERC-20, SPL, Jetton, TRC-20) | +| **Swaps** | DEX swaps via Velora (EVM) and StonFi (TON) | +| **Bridges** | Cross-chain bridges with USDT0 via LayerZero | +| **Lending** | Supply, borrow, repay, and withdraw via Aave V3 | +| **Fiat** | Buy and sell crypto via MoonPay on/off-ramps | +| **Gasless** | Fee-free transfers on TON (via paymaster) and Tron (via gas-free service), and ERC-4337 account abstraction on EVM | -All write operations require explicit human confirmation. The skill instructs agents to estimate fees before sending and includes prompt injection protection guidance. + + All write operations require explicit human confirmation. The skill instructs agents to estimate fees before sending and includes prompt injection protection guidance. + ## How It Works @@ -77,7438 +102,8100 @@ The skill includes security guidance: pre-transaction validation checklists, pro WDK's agent skills use a self-custodial model where your agent controls its own keys locally. This differs from hosted solutions where a third party manages your keys. -| Feature | WDK | Coinbase Agentic Wallet | Privy Server Wallets | -| --- | --- | --- | --- | -| Custody model | Self-custodial | Coinbase-hosted | Privy-hosted (server) | -| Multi-chain | Yes (EVM, Bitcoin, Solana, TON, Tron, Spark + more) | EVM + Solana | EVM + Solana + Bitcoin + more | -| Open source | Yes (SDK + skills) | CLI/skills open, infra closed | Skills open, API closed | -| MCP support | Yes ([MCP Toolkit](mcp-toolkit/)) | Via skills | Via skills | -| OpenClaw support | Yes ([ClawHub skill](https://clawhub.ai/HumanRupert/tether-wallet-development-kit)) | Yes (npx skills) | Yes (ClawHub skill) | -| x402 payments | Via [community extensions](#community-projects) | Yes (native) | No | -| Key management | Local / self-managed | Coinbase infrastructure | Privy infrastructure | +| Feature | WDK | Coinbase Agentic Wallet | Privy Server Wallets | +| ---------------- | ----------------------------------------------------------------------------------- | ----------------------------- | ----------------------------- | +| Custody model | Self-custodial | Coinbase-hosted | Privy-hosted (server) | +| Multi-chain | Yes (EVM, Bitcoin, Solana, TON, Tron, Spark + more) | EVM + Solana | EVM + Solana + Bitcoin + more | +| Open source | Yes (SDK + skills) | CLI/skills open, infra closed | Skills open, API closed | +| MCP support | Yes ([MCP Toolkit](mcp-toolkit/)) | Via skills | Via skills | +| OpenClaw support | Yes ([ClawHub skill](https://clawhub.ai/HumanRupert/tether-wallet-development-kit)) | Yes (npx skills) | Yes (ClawHub skill) | +| x402 payments | Via [community extensions](#community-projects) | Yes (native) | No | +| Key management | Local / self-managed | Coinbase infrastructure | Privy infrastructure | ## Use With Agent Platforms -| Platform | How to Use | -| --- | --- | -| **OpenClaw** | Install from [ClawHub](openclaw) or clone to workspace. See [OpenClaw Integration](openclaw) | -| **Claude** | Upload `SKILL.md` as project knowledge, or paste into conversation | -| **Cursor / Windsurf** | Clone to `.cursor/skills/wdk` or `.windsurf/skills/wdk` | -| **Any MCP-compatible agent** | Use the [MCP Toolkit](mcp-toolkit/) for structured tool calling | -| **Any other agent** | Copy `SKILL.md` into system prompt or conversation context | +| Platform | How to Use | +| ---------------------------- | -------------------------------------------------------------------------------------------- | +| **OpenClaw** | Install from [ClawHub](openclaw) or clone to workspace. See [OpenClaw Integration](openclaw) | +| **Claude** | Upload `SKILL.md` as project knowledge, or paste into conversation | +| **Cursor / Windsurf** | Clone to `.cursor/skills/wdk` or `.windsurf/skills/wdk` | +| **Any MCP-compatible agent** | Use the [MCP Toolkit](mcp-toolkit/) for structured tool calling | +| **Any other agent** | Copy `SKILL.md` into system prompt or conversation context | ## Community Projects Community-built projects using WDK's agentic capabilities: -| Project | Description | -| --- | --- | +| Project | Description | +| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | [wdk-wallet-evm-x402-facilitator](https://github.com/SemanticPay/wdk-wallet-evm-x402-facilitator) | Agent-to-agent payments using the x402 HTTP payment protocol | -| [x402-usdt0](https://github.com/baghdadgherras/x402-usdt0) | Reference implementation of x402 on Plasma with USDT0 | -| [Novanet zkML Guardrails](https://github.com/hshadab/tether) | Zero-knowledge ML safety checks for wallet operations | +| [x402-usdt0](https://github.com/baghdadgherras/x402-usdt0) | Reference implementation of x402 on Plasma with USDT0 | +| [Novanet zkML Guardrails](https://github.com/hshadab/tether) | Zero-knowledge ML safety checks for wallet operations | ## Resources -- [WDK SKILL.md on GitHub](https://github.com/tetherto/wdk-docs/blob/main/skills/wdk/SKILL.md) - The full skill file agents consume -- [WDK Skill on ClawHub](https://clawhub.ai/HumanRupert/tether-wallet-development-kit) - Install the skill -- [AgentSkills Specification](https://agentskills.io/specification) - The skill format standard -- [WDK MCP Toolkit](https://github.com/tetherto/wdk-mcp-toolkit) - MCP server for structured tool calling -- [WDK Core](https://github.com/tetherto/wdk-core) - The core SDK +* [WDK SKILL.md on GitHub](https://github.com/tetherto/wdk-docs/blob/main/skills/wdk/SKILL.md) - The full skill file agents consume +* [WDK Skill on ClawHub](https://clawhub.ai/HumanRupert/tether-wallet-development-kit) - Install the skill +* [AgentSkills Specification](https://agentskills.io/specification) - The skill format standard +* [WDK MCP Toolkit](https://github.com/tetherto/wdk-mcp-toolkit) - MCP server for structured tool calling +* [WDK Core](https://github.com/tetherto/wdk-core) - The core SDK *** ## Need Help? -## MCP Toolkit -URL: https://docs.wdk.tether.su/ai/mcp-toolkit -Description: Build MCP servers that give AI agents self-custodial WDK wallets -The MCP Toolkit lets AI agents interact with self-custodial WDK wallets. It creates an [MCP server](https://modelcontextprotocol.io/) that exposes wallet operations (checking balances, sending transactions, swapping tokens, bridging assets, and more) as structured tools that any MCP-compatible AI client can call. - -Powered by [`@tetherto/wdk-mcp-toolkit`](https://github.com/tetherto/wdk-mcp-toolkit). - -**Beta** - This package is in active development (`v1.0.0-beta.1`). APIs may change between releases. -## Features - -- **MCP Server Extension** - Extends the official `@modelcontextprotocol/sdk` McpServer with WDK-specific capabilities -- **Multi-Chain** - Support for 13 blockchains out of the box, including EVM chains, Bitcoin, Solana, Spark, TON, and Tron -- **35 Built-in Tools** - Ready-to-use tools for wallets, pricing, indexer queries, swaps, bridges, lending, and fiat on/off-ramps -- **Human Confirmation** - All write operations use MCP elicitations to require explicit user approval before broadcasting transactions -- **Extensible** - Register custom tools alongside built-in ones using standard MCP SDK patterns -- **Secure by Design** - Seed phrases stay local, `close()` wipes keys from memory, and read/write tool separation lets you control access + -## Supported Chains -| Chain | Identifier | -| --- | --- | -| Ethereum | `ethereum` | -| Polygon | `polygon` | -| Arbitrum | `arbitrum` | -| Optimism | `optimism` | -| Base | `base` | -| Avalanche | `avalanche` | -| BNB Chain | `bnb` | -| Plasma | `plasma` | -| Bitcoin | `bitcoin` | -| Solana | `solana` | -| Spark | `spark` | -| TON | `ton` | -| Tron | `tron` | +# OpenClaw (Community Skill) (/ai/openclaw) -You can register **any** blockchain name - the `CHAINS` constants are for convenience only. For custom chains, register tokens manually with `registerToken()`. -Install and run your first MCP server in minutes -Wallets, capabilities, tokens, protocols, and custom tools -All 35 built-in MCP tools and the WdkMcpServer class -Use WDK tools in LangChain agents via the serve CLI + + The WDK skill for OpenClaw is a community skill, developed and maintained independently by a third-party contributor. -**Already using an AI coding assistant?** See [Build with AI](../../start-building/build-with-ai) for how to connect WDK docs as context via MCP or Markdown. + Tether and the WDK Team do not endorse or assume responsibility for its code, security, or maintenance. Use your own judgment and proceed at your own risk. Artificial intelligence has inherent risks and limitations. You assume full responsibility for any reliance and use of artificial intelligence and agree that any such reliance and use is entirely at your own risk. + -*** +[OpenClaw](https://openclaw.ai) is an open-source AI agent platform. With the WDK community skill, your OpenClaw agent can create wallets, send transactions, swap tokens, bridge assets, and interact with DeFi protocols. Everything stays self-custodial. -## Need Help? -## API Reference -URL: https://docs.wdk.tether.su/ai/mcp-toolkit/api-reference -Description: WdkMcpServer class and all 35 built-in MCP tools -## WdkMcpServer + + The WDK community skill follows the [AgentSkills specification](https://agentskills.io/specification), so it works with any compatible agent platform. This page covers the OpenClaw-specific setup. + -The `WdkMcpServer` class extends `McpServer` from `@modelcontextprotocol/sdk` with WDK-specific wallet, pricing, indexer, and protocol capabilities. +## Install the WDK Community Skill -### Constructor +Install from [ClawHub](https://clawhub.ai/HumanRupert/tether-wallet-development-kit): -```javascript -const server = new WdkMcpServer(name: string, version: string) +```bash +npx clawhub install tether-wallet-development-kit ``` -| Parameter | Type | Description | -| --- | --- | --- | -| `name` | `string` | Server name (shown to AI clients) | -| `version` | `string` | Server version string | +This installs the skill into your workspace's `skills/` directory. OpenClaw picks it up automatically on the next session. -### Core Methods + + You might see a VirusTotal warning during installation. It flags the skill as suspicious because it handles crypto keys and calls external APIs. This is normal for any wallet SDK skill, nevertheless review the skill's source code on [ClawHub](https://clawhub.ai/HumanRupert/tether-wallet-development-kit) before proceeding. + -#### `useWdk(config)` + + We plan to publish the official WDK skill to its own GitHub repository. Once that's live, you'll also be able to install via `git clone`. + -Initializes the WDK wallet engine. Must be called before `registerWallet()` or `registerProtocol()`. +## Configuration -```typescript -server.useWdk(config: WdkConfig): WdkMcpServer -``` +The WDK community skill does not require environment variables. Your agent will ask for a seed phrase in conversation when it needs to create or recover a wallet. The skill passes the seed phrase as a constructor parameter in code rather than reading it from configuration. -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `config.seed` | `string` | Yes | BIP-39 mnemonic seed phrase | + + Your seed phrase controls real funds. Never share it, commit it to version control, or expose it in logs. The skill instructs agents to never log or expose seed phrases or private keys. + -**Returns:** `WdkMcpServer` (for chaining) +## Verify It Works ---- +Start a new OpenClaw session and try a simple prompt: -#### `registerWallet(blockchain, WalletManager, config)` +``` +Create a multi-chain wallet with Ethereum and Bitcoin support, then show me the addresses. +``` -Registers a wallet module for a specific blockchain. +The agent should use the WDK community skill to create wallet accounts and return the generated addresses. All write operations (transactions, swaps, bridges) require your explicit confirmation before executing. -```typescript -server.registerWallet( - blockchain: string, - WalletManager: W, - config: ConstructorParameters[1] -): WdkMcpServer -``` +OpenClaw creating a multi-chain wallet using the WDK skill -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `blockchain` | `string` | Yes | Chain name (e.g., `'ethereum'`, `'bitcoin'`) | -| `WalletManager` | `class` | Yes | Wallet module class (e.g., `WalletManagerEvm`) | -| `config` | `object` | Yes | Module-specific config (see each wallet module's docs) | +*Example output from the WDK skill creating a multi-chain wallet* -**Requires:** `useWdk()` called first +## What Your Agent Can Do ---- +Once the skill is loaded, your agent can: -#### `registerProtocol(chain, label, Protocol, config?)` +* **Create wallets** across 20+ blockchains (EVM, Bitcoin, Solana, TON, Tron, Spark) +* **Send transactions** and token transfers +* **Swap tokens** via DEX aggregators (Velora, StonFi) +* **Bridge assets** cross-chain with USDT0 +* **Lend and borrow** through Aave V3 +* **Buy and sell crypto** via MoonPay fiat on/off-ramps -Registers a DeFi protocol (swap, bridge, lending, or fiat) for a chain. +For the full list of capabilities and how skills work, see [Agent Skills](agent-skills). -```typescript -server.registerProtocol( - chain: string, - label: string, - Protocol: P, - config?: ConstructorParameters[1] -): WdkMcpServer -``` +## Security Risks and Safety Precautions -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `string` | Yes | Chain name (must have a wallet registered) | -| `label` | `string` | Yes | Protocol identifier (e.g., `'velora'`, `'aave'`) | -| `Protocol` | `class` | Yes | Protocol module class | -| `config` | `object` | No | Protocol-specific config | +OpenClaw is powerful because it runs on your system and can take real actions like creating files, fetching data from the web, and executing transactions. That same power can become a security risk if you're not careful about how and where you run it. -**Requires:** `useWdk()` called first +This isn't a flaw in OpenClaw. It's what happens when you give any AI agent direct system access. Knowing these risks lets you use OpenClaw safely. ---- +### Why running OpenClaw locally requires caution -#### `useIndexer(config)` +When you run OpenClaw on your own computer or a virtual server, you're allowing a chat interface to trigger actions on that system. This is a concern if your bot: -Enables the WDK Indexer client for querying token balances and transfer history. +* Has access to sensitive directories +* Runs with elevated privileges +* Is connected to a publicly accessible chat +* Receives poorly scoped instructions -```typescript -server.useIndexer(config: ): WdkMcpServer -``` +It can unintentionally modify files, overwrite data, or expose information you didn't intend to share. The risk isn't that OpenClaw is malicious. The risk is that it will do exactly what it's told, even when the instruction is vague or unsafe. -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `config.apiKey` | `string` | Yes | WDK Indexer API key | +### How to use OpenClaw safely ---- +To reduce risk, here are some practical safety measures: -#### `usePricing()` +* Run OpenClaw as a non-privileged user +* Keep its working files in a dedicated directory +* Avoid connecting it to public or shared chats initially +* Be explicit when asking it to read or write files +* Test new capabilities on a disposable system or VM -Enables the Bitfinex pricing client for current and historical prices. +Think of OpenClaw the same way you'd think about running scripts on your system: powerful and useful, but something you need to be careful with. -```typescript -server.usePricing(): WdkMcpServer -``` +### Inherent Limitations of Artificial Intelligence ---- +OpenClaw makes use of artificial intelligence and machine learning technologies. While the use of artificial intelligence and machine learning enables capabilities, it also involves inherent limitations and risks. These include: -#### `registerTools(tools)` +1. The potential for inaccurate, incomplete, unexpected or misleading outputs or actions (including so-called hallucinations) +2. The risk that outputs or actions may contain biases +3. The possibility of errors related to document quality or text recognition of inputs +4. The possibility that the outputs may suggest specific immediate or near term actions that should not be relied upon +5. The risk that OpenClaw may take unexpected actions (including the sending of assets) -Registers multiple MCP tools at once. +## Next Steps -```typescript -server.registerTools(tools: ToolFunction[]): WdkMcpServer -``` +* [Agent Skills](agent-skills) - Full capabilities, how skills work, and a comparison with other agentic wallet solutions +* [MCP Toolkit](mcp-toolkit/) - Programmatic wallet access for MCP-compatible agents +* [OpenClaw Skills Documentation](https://docs.openclaw.ai/tools/skills) - How OpenClaw discovers and loads skills ---- +*** -#### `registerToken(chain, symbol, token)` +## Need Help? -Registers a custom token for a chain. + -```typescript -server.registerToken(chain: string, symbol: string, token: TokenInfo): WdkMcpServer -``` -| Parameter | Type | Description | -| --- | --- | --- | -| `chain` | `string` | Chain name | -| `symbol` | `string` | Token symbol (e.g., `'USDC'`) | -| `token.address` | `string` | Token contract address | -| `token.decimals` | `number` | Token decimal places | +# x402 (/ai/x402) ---- -#### `close()` -Disposes the WDK instance and clears seed material from memory. Call this when shutting down the server. +## What Is x402? -```typescript -server.close(): void -``` +[x402](https://www.x402.org) is an open payment protocol, [originally developed by Coinbase](https://docs.x402.org/), that gives the long-reserved [HTTP 402 Payment Required](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/402) status code a concrete, blockchain-native meaning: if you want this resource, pay for it. No accounts, API keys, or checkout flows. Just plain HTTP. -### Query Methods +This matters for AI agents because they need to pay for resources programmatically. x402 makes payment a first-class part of the web stack, so an agent can discover a price, sign a payment, and receive a resource in a single request-response cycle. -| Method | Returns | Description | -| --- | --- | --- | -| `getChains()` | `string[]` | Registered blockchain names | -| `getTokenInfo(chain, symbol)` | `TokenInfo \| undefined` | Token address and decimals | -| `getRegisteredTokens(chain)` | `string[]` | Registered token symbols for a chain | -| `getSwapChains()` | `string[]` | Chains with swap protocols | -| `getSwapProtocols(chain)` | `string[]` | Swap protocol labels for a chain | -| `getBridgeChains()` | `string[]` | Chains with bridge protocols | -| `getBridgeProtocols(chain)` | `string[]` | Bridge protocol labels for a chain | -| `getLendingChains()` | `string[]` | Chains with lending protocols | -| `getLendingProtocols(chain)` | `string[]` | Lending protocol labels for a chain | -| `getFiatChains()` | `string[]` | Chains with fiat protocols | -| `getFiatProtocols(chain)` | `string[]` | Fiat protocol labels for a chain | +### The Three Roles -### Getters +| Role | Description | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| **Client (Buyer)** | The entity requesting a paid resource. Can be a human application, an AI agent, or any service with a wallet. | +| **Resource Server (Seller)** | The API or service providing the paid resource. Defines payment requirements and returns `402` for unpaid requests. | +| **Facilitator** | An intermediary that verifies payment signatures and submits transactions on-chain. Never holds funds, only executes signed authorizations. | -| Getter | Type | Description | -| --- | --- | --- | -| `server.wdk` | `WalletKit` | WDK instance (after `useWdk()`) | -| `server.indexerClient` | `WdkIndexerClient` | Indexer client (after `useIndexer()`) | -| `server.pricingClient` | `WdkPricingClient` | Pricing client (after `usePricing()`) | +### How the Protocol Works -*** + + + #### Client requests a resource -## Types + A standard HTTP request. `GET`, `POST`, whatever your API expects. + -```typescript -type WdkConfig = + + #### Server responds with 402 Payment Required -type TokenInfo = + The response body describes what to pay: amount, token, network, and recipient address. -type ToolFunction = (server: WdkMcpServer) => void -``` + ```json + { + "x402Version": 1, + "accepts": [{ + "scheme": "exact", + "network": "eip155:9745", + "maxAmountRequired": "1000000", + "asset": "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb", + "resource": "https://api.example.com/data", + "payTo": "0x1234...abcd" + }] + } + ``` + -*** + + #### Client signs a payment -## Built-in MCP Tools + The client constructs an [EIP-3009](https://eips.ethereum.org/EIPS/eip-3009) `transferWithAuthorization` and signs it with their wallet. No tokens leave the wallet yet. It's a signed intent, not a transfer. + -All tools use [Zod](https://zod.dev/) for input/output validation and include [MCP tool annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) that describe their behavior to AI clients. + + #### Client retries with payment header -### MCP Annotations + The signed payload goes in the `X-PAYMENT` header on the same request. + -Every tool declares these annotations: + + #### Facilitator verifies -| Annotation | Type | Meaning | -| --- | --- | --- | -| `readOnlyHint` | `boolean` | Tool does not modify state | -| `destructiveHint` | `boolean` | Tool may spend funds or make irreversible changes | -| `idempotentHint` | `boolean` | Calling multiple times produces the same result | -| `openWorldHint` | `boolean` | Tool interacts with external systems | + The server forwards the payload to the facilitator's `/verify` endpoint. The facilitator checks that the signature is valid, the amount is sufficient, and the payer has funds. No money moves yet. + -**Human Confirmation** - All tools where `destructiveHint: true` use MCP [elicitations](https://modelcontextprotocol.io/docs/concepts/elicitation) to show a confirmation dialog before broadcasting. The user must explicitly approve each transaction. + + #### Server performs the work -*** + Inference, database query, generation, whatever the resource requires. This only happens after verification succeeds. + -## Wallet Tools + + #### Facilitator settles on-chain -_Requires: `useWdk()` + `registerWallet()`_ + The server calls the facilitator's `/settle` endpoint. The facilitator submits the signed authorization on-chain, transferring tokens from buyer to seller. + -### `getAddress` + + #### Server returns the resource -Get the wallet address for a blockchain. **Read-only.** + `200 OK` with the result in the body and a settlement receipt in the `X-PAYMENT-RESPONSE` header. + + -**Input:** +For the full protocol specification, see [x402.org](https://www.x402.org) and the [x402 GitHub repository](https://github.com/coinbase/x402). -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | The blockchain to get the address for | +## How to Use x402 With WDK -**Output:** +WDK wallets work as drop-in signers for x402. `WalletAccountEvm` satisfies the client x402 signer interface directly. Self-custodial x402 payments on any EVM chain. -| Field | Type | Description | -| --- | --- | --- | -| `address` | `string` | The wallet address | +This guide walks through three things: ---- +1. **Client (Buyer)** - Pay for x402-protected resources using a WDK wallet +2. **Server with Hosted Facilitator** - Accept x402 payments by delegating verification and settlement to a third-party facilitator +3. **Server with Self-Hosted Facilitator** - Run verification and settlement in-process using a WDK wallet, with no external dependencies -### `getBalance` + + The x402 integration described on this page uses community-developed modules and third-party facilitator services. Tether does not endorse, operate, or assume legal or financial responsibility for any third-party facilitator. You are solely responsible for using any service. -Get the native token balance for a blockchain (ETH, BTC, SOL, etc.). **Read-only.** + Artificial intelligence and blockchain transactions carry inherent risks and limitations. + -**Input:** +### Recommended Chains -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | The blockchain to query | +x402 with WDK works on any EVM chain where USD₮0 is deployed (see full list at [docs.usdt0.to](https://docs.usdt0.to/technical-documentation/deployments)). However, we recommend **Plasma** and **Stable** for x402 payments. Both chains are purpose-built for USD₮ transfers with near-instant finality and near-zero fees. Agents only need to hold USD₮. -**Output:** +| Chain | CAIP-2 | RPC | USD₮0 Contract | Explorer | +| ---------- | ------------- | ------------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------------- | +| **Plasma** | `eip155:9745` | `https://rpc.plasma.to` | `0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb` | [plasmascan.to](https://plasmascan.to/address/0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb) | +| **Stable** | `eip155:988` | `https://rpc.stable.xyz` | `0x779Ded0c9e1022225f8E0630b35a9b54bE713736` | [stablescan.xyz](https://stablescan.xyz/address/0x779Ded0c9e1022225f8E0630b35a9b54bE713736) | -| Field | Type | Description | -| --- | --- | --- | -| `balance` | `string` | Balance in base units (wei, satoshis, etc.) | +*** ---- +## Client: Paying for Resources -### `getTokenBalance` + + See the full working client example at [`x402/client.js`](https://github.com/SemanticPay/x402-usdt0-demo/blob/main/x402/client.js). + -Get the balance of a registered token (USDT, USDC, etc.). **Read-only.** +```bash +npm install @tetherto/wdk-wallet-evm @x402/fetch @x402/evm +``` -**Input:** + + + #### Create a wallet -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | The blockchain to query | -| `token` | `string` | Yes | Token symbol (e.g., `"USDT"`) | + ```javascript + import WalletManagerEvm from "@tetherto/wdk-wallet-evm"; -**Output:** + const account = await new WalletManagerEvm(process.env.SEED_PHRASE, { + provider: "https://rpc.plasma.to", // or "https://rpc.stable.xyz" + }).getAccount(); + ``` + -| Field | Type | Description | -| --- | --- | --- | -| `balance` | `string` | Human-readable token balance | -| `balanceBaseUnits` | `string` | Balance in smallest unit | + + #### Register with x402 ---- + `WalletAccountEvm` satisfies the `ClientEvmSigner` interface directly. No adapter needed. -### `getFeeRates` + ```javascript + import { x402Client, wrapFetchWithPayment } from "@x402/fetch"; + import { registerExactEvmScheme } from "@x402/evm/exact/client"; -Get current network fee rates. **Read-only.** + const client = new x402Client(); + registerExactEvmScheme(client, { signer: account }); -**Input:** + const fetchWithPayment = wrapFetchWithPayment(fetch, client); + ``` + -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | The blockchain to query | + + #### Make a paid request -**Output:** + `fetchWithPayment` intercepts any `402` response, signs an EIP-3009 authorization with your WDK wallet, and retries automatically. -| Field | Type | Description | -| --- | --- | --- | -| `normal` | `string` | Normal fee rate (balanced speed) | -| `fast` | `string` | Fast fee rate (higher cost, faster confirmation) | + ```javascript + const response = await fetchWithPayment("https://api.example.com/weather", { + method: "GET", + }); -Fee units vary by chain: satoshis/byte (Bitcoin), wei (Ethereum), or chain-specific units. + const data = await response.json(); + console.log("Response:", data); + ``` + + ---- + + Your seed phrase controls your funds. Never commit it to version control. Use environment variables or a secrets manager. + -### `getMaxSpendableBtc` +### Getting USD₮0 on Plasma or Stable -Get the maximum spendable Bitcoin amount after fees. **Read-only.** Bitcoin-only. +Before you can make x402 payments, your wallet needs USD₮0 on the target chain. If you hold USD₮ on Ethereum (or any supported EVM chain), bridge it using `@tetherto/wdk-protocol-bridge-usdt0-evm`. -**Input:** None + + The bridge uses [LayerZero](https://layerzero.network) for secure cross-chain transfers. USD₮ on Ethereum is automatically converted to USD₮0 on the destination chain. + -**Output:** +```bash +npm install @tetherto/wdk-wallet-evm @tetherto/wdk-protocol-bridge-usdt0-evm +``` -| Field | Type | Description | -| --- | --- | --- | -| `amount` | `string` | Maximum spendable amount (satoshis) | -| `fee` | `string` | Estimated transaction fee (satoshis) | -| `changeValue` | `string` | Expected change output (satoshis) | +#### Bridge USD₮ from Ethereum to Plasma / Stable ---- + + + #### Create wallet and bridge protocol -### `quoteSendTransaction` + ```javascript + import WalletManagerEvm from "@tetherto/wdk-wallet-evm"; + import Usdt0ProtocolEvm from "@tetherto/wdk-protocol-bridge-usdt0-evm"; -Estimate the fee for sending native currency. **Read-only.** Does not broadcast. + const account = await new WalletManagerEvm(process.env.SEED_PHRASE, { + provider: "https://eth.drpc.org", + }).getAccount(); -**Input:** + const bridge = new Usdt0ProtocolEvm(account, { + bridgeMaxFee: 100000000000000n, // Max 0.0001 ETH in bridge fees + }); + ``` + -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | The blockchain | -| `to` | `string` | Yes | Recipient address | -| `value` | `string` | Yes | Amount in **base units** (wei, satoshis) | + + #### Get a quote (recommended) -**Output:** + ```javascript + const USDT_ETHEREUM = "0xdAC17F958D2ee523a2206206994597C13D831ec7"; -| Field | Type | Description | -| --- | --- | --- | -| `fee` | `string` | Estimated transaction fee in base units | + const quote = await bridge.quoteBridge({ + targetChain: "plasma", // or "stable" + recipient: await account.getAddress(), + token: USDT_ETHEREUM, + amount: 10000000n, // 10 USD₮ (6 decimals) + }); ---- + console.log("Total cost:", Number(quote.fee + quote.bridgeFee) / 1e18, "ETH"); + ``` + -### `quoteTransfer` + + #### Execute the bridge -Estimate the fee for transferring a token. **Read-only.** Does not broadcast. + ```javascript + const result = await bridge.bridge({ + targetChain: "plasma", // or "stable" + recipient: await account.getAddress(), + token: USDT_ETHEREUM, + amount: 10000000n, + }); -**Input:** + console.log("Bridge tx:", result.hash); + ``` -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | The blockchain | -| `token` | `string` | Yes | Token symbol (e.g., `"USDT"`) | -| `recipient` | `string` | Yes | Recipient address | -| `amount` | `string` | Yes | Amount in **human-readable** format (e.g., `"10"`) | + USD₮0 arrives on the destination chain within a few minutes. + + -**Output:** + + You can bridge from any of 25+ supported EVM chains, not just Ethereum. Point your wallet at the source chain's RPC and use the [USD₮ token address](https://tether.to/es/supported-protocols/) on that chain. See the full [bridge module documentation](../sdk/bridge-modules/bridge-usdt0-evm/). + -| Field | Type | Description | -| --- | --- | --- | -| `fee` | `string` | Estimated transaction fee in base units | +*** ---- +## Server: Accepting Payments (Hosted Facilitator) -### `sendTransaction` +Your server delegates verification and settlement to a hosted facilitator. You never interact with the chain directly. -Send native currency (ETH, BTC, etc.). **Destructive** - requires user confirmation. + + **About the Semantic facilitator:** [Semantic](https://docs.semanticpay.io) operates a public USD₮-enabled x402 facilitator at `https://x402.semanticpay.io`. This is a third-party service not operated, endorsed, or guaranteed by Tether. -**Input:** + The x402 protocol is an open standard. Anyone can build a facilitator or use one of their choice. + -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | The blockchain | -| `to` | `string` | Yes | Recipient address | -| `value` | `string` | Yes | Amount in **base units** (wei, satoshis) | + + See the full working server example at [`x402/server.js`](https://github.com/SemanticPay/x402-usdt0-demo/blob/main/x402/server.js). + -**Output:** +```bash +npm install @tetherto/wdk-wallet-evm @x402/express @x402/evm @x402/core express dotenv +``` -| Field | Type | Description | -| --- | --- | --- | -| `hash` | `string` | Transaction hash | -| `fee` | `string` | Actual fee paid | + + + #### Create the seller wallet -This tool shows a confirmation dialog with transaction details before broadcasting. The user must approve the transaction explicitly. + ```javascript + import WalletManagerEvm from "@tetherto/wdk-wallet-evm"; ---- + const sellerAccount = await new WalletManagerEvm(process.env.SEED_PHRASE, { + provider: "https://rpc.plasma.to", + }).getAccount(); -### `transfer` + const sellerAddress = await sellerAccount.getAddress(); + ``` + -Transfer a registered token. **Destructive** - requires user confirmation. + + #### Create the facilitator client -**Input:** + ```javascript + import { HTTPFacilitatorClient } from "@x402/core"; -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | The blockchain | -| `token` | `string` | Yes | Token symbol (e.g., `"USDT"`) | -| `to` | `string` | Yes | Recipient address | -| `amount` | `string` | Yes | Amount in **human-readable** format (e.g., `"100"`) | + const facilitatorClient = new HTTPFacilitatorClient({ + url: "https://x402.semanticpay.io/", + }); + ``` + -**Output:** + + #### Configure payment middleware -| Field | Type | Description | -| --- | --- | --- | -| `hash` | `string` | Transaction hash | -| `fee` | `string` | Actual fee paid | + ```javascript + import express from "express"; + import { paymentMiddleware, x402ResourceServer } from "@x402/express"; + import { ExactEvmScheme } from "@x402/evm/exact/server"; -This tool shows a confirmation dialog with transaction details before broadcasting. The user must approve the transaction explicitly. + const PLASMA_NETWORK = "eip155:9745"; + const USDT0_PLASMA = "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb"; ---- + const app = express(); -### `sign` + app.use( + paymentMiddleware( + { + "GET /weather": { + accepts: [ + { + scheme: "exact", + network: PLASMA_NETWORK, + price: { + amount: "1000", // $0.001 (6 decimals) + asset: USDT0_PLASMA, + extra: { name: "USDT0", version: "1", decimals: 6 }, + }, + payTo: sellerAddress, + }, + ], + description: "Weather data", + mimeType: "application/json", + }, + }, + new x402ResourceServer(facilitatorClient).register( + PLASMA_NETWORK, + new ExactEvmScheme(), + ), + ), + ); + ``` + + + The `extra` fields are passed to the buyer for EIP-712 signature construction. `name` and `version` must match what the on-chain USD₮0 contract expects. + + + + + #### Add your routes + + ```javascript + // Gated - requires payment + app.get("/weather", (req, res) => { + res.json({ weather: "sunny", temperature: 70 }); + }); -Sign an arbitrary message with the wallet's private key. **Does not reveal the private key.** + // Not gated - no payment config + app.get("/health", (req, res) => { + res.json({ status: "ok" }); + }); -**Input:** + app.listen(4021); + ``` -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | The blockchain | -| `message` | `string` | Yes | Message to sign | + Routes not listed in the middleware config behave like normal Express routes. + + -**Output:** +### Multi-Chain (Plasma + Stable) -| Field | Type | Description | -| --- | --- | --- | -| `signature` | `string` | Cryptographic signature | +To accept payments on both chains, add both networks to the `accepts` array and register both with the resource server. The buyer's client picks whichever network it has funds on. ---- +```javascript +const NETWORKS = { + plasma: { network: "eip155:9745", usdt0: "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb" }, + stable: { network: "eip155:988", usdt0: "0x779Ded0c9e1022225f8E0630b35a9b54bE713736" }, +}; -### `verify` +const resourceServer = new x402ResourceServer(facilitatorClient) + .register(NETWORKS.plasma.network, new ExactEvmScheme()) + .register(NETWORKS.stable.network, new ExactEvmScheme()); +``` -Verify that a signature is valid for a given message. **Read-only.** +### Lifecycle Events -**Input:** +The Semantic facilitator supports an optional `X-Event-Callback` header. When provided, the facilitator POSTs real-time events to your callback URL during verification and settlement. -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | The blockchain | -| `message` | `string` | Yes | Original message | -| `signature` | `string` | Yes | Signature to verify | +| Type | When | Key Fields | +| ------------------ | --------------------------------- | ----------------------------------- | +| `verify_started` | Facilitator begins verifying | `details.network`, `details.checks` | +| `verify_completed` | Verification finished | `details.isValid` | +| `verify_failed` | Verification error | `details.error` | +| `settle_started` | Broadcasting on-chain transaction | `details.network` | +| `settle_completed` | Transaction confirmed | `details.transactionHash` | +| `settle_failed` | Settlement error | `details.error` | -**Output:** +```javascript +const facilitatorClient = new HTTPFacilitatorClient({ + url: "https://x402.semanticpay.io/", + fetch: (url, init) => + fetch(url, { + ...init, + headers: { ...init?.headers, "X-Event-Callback": "http://localhost:4021/payment-events" }, + }), +}); +``` -| Field | Type | Description | -| --- | --- | --- | -| `valid` | `boolean` | Whether the signature is valid | + + Events are fire-and-forget. If the callback URL is unreachable, events are silently dropped. + *** -## Pricing Tools +## Server: Self-Hosted Facilitator (In-Process) -_Requires: `usePricing()`_ +Instead of relying on a hosted facilitator, you can run verification and settlement in-process using the `@semanticio/wdk-wallet-evm-x402-facilitator` community module. This wraps a WDK wallet as an x402 `FacilitatorEvmSigner`. Your server handles the entire payment lifecycle locally. -### `getCurrentPrice` + + Unlike the hosted Semantic facilitator (Plasma and Stable only), a self-hosted facilitator works with **any EVM chain where USD₮0 is deployed**. See the full deployment list at [docs.usdt0.to](https://docs.usdt0.to/technical-documentation/deployments). + -Get the current spot price from Bitfinex. **Read-only.** + + `@semanticio/wdk-wallet-evm-x402-facilitator` is a community module developed and maintained by [Semantic Pay](https://www.semanticpay.io). Tether does not endorse, audit, or assume responsibility for this module. It is currently in beta. Test thoroughly before using in production. + -**Input:** + + See the full working self-hosted server example at [`x402/server-inprocess.js`](https://github.com/SemanticPay/x402-usdt0-demo/blob/main/x402/server-inprocess.js). + -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `base` | `string` | Yes | Base currency (e.g., `"BTC"`, `"ETH"`) | -| `quote` | `string` | Yes | Quote currency (e.g., `"USD"`, `"USDT"`) | +```bash +npm install @semanticio/wdk-wallet-evm-x402-facilitator @tetherto/wdk-wallet-evm @x402/core @x402/evm @x402/express express dotenv +``` -**Output:** + + + #### Create the facilitator signer -| Field | Type | Description | -| --- | --- | --- | -| `base` | `string` | Base currency | -| `quote` | `string` | Quote currency | -| `price` | `number` | Current spot price | + The facilitator wallet submits settlement transactions on-chain. It needs gas tokens on the target chain. ---- + ```javascript + import WalletManagerEvm from "@tetherto/wdk-wallet-evm"; + import WalletAccountEvmX402Facilitator from "@semanticio/wdk-wallet-evm-x402-facilitator"; -### `getHistoricalPrice` + const walletAccount = await new WalletManagerEvm(process.env.FACILITATOR_MNEMONIC, { + provider: process.env.RPC_URL, // Any EVM chain with USD₮0 + }).getAccount(); -Get historical price data (OHLCV candles) from Bitfinex. **Read-only.** + const evmSigner = new WalletAccountEvmX402Facilitator(walletAccount); + ``` -**Input:** + + The facilitator wallet and the seller wallet can use different seed phrases. The facilitator pays gas; the seller receives USD₮. The facilitator wallet must have enough native token to pay gas. + + -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `from` | `string` | Yes | Base currency (e.g., `"BTC"`) | -| `to` | `string` | Yes | Quote currency (e.g., `"USD"`) | -| `start` | `number` | No | Start timestamp (ms, unix epoch) | -| `end` | `number` | No | End timestamp (ms, unix epoch) | + + #### Initialize the facilitator -**Output:** + ```javascript + import { x402Facilitator } from "@x402/core/facilitator"; + import { registerExactEvmScheme } from "@x402/evm/exact/facilitator"; -| Field | Type | Description | -| --- | --- | --- | -| `from` | `string` | Base currency | -| `to` | `string` | Quote currency | -| `start` | `number` | Start timestamp (if provided) | -| `end` | `number` | End timestamp (if provided) | -| `points` | `number[][]` | Array of `[timestamp, open, close, high, low, volume]` | + const facilitator = new x402Facilitator() + .onAfterVerify(async (ctx) => { + console.log("[verify]", ctx.result?.isValid ? "valid" : "invalid"); + }) + .onAfterSettle(async (ctx) => { + console.log("[settle] tx:", ctx.result?.transaction); + }); -Long time ranges are automatically downscaled to ≤100 data points. + registerExactEvmScheme(facilitator, { + signer: evmSigner, + networks: process.env.NETWORK_ID, // e.g. "eip155:9745" + }); + ``` -*** + Available hooks: `onBeforeVerify`, `onAfterVerify`, `onBeforeSettle`, `onAfterSettle`. All are `async` and receive a context object with the payment payload and result. + -## Indexer Tools + + #### Wire into Express -_Requires: `useIndexer()`_ + Same `paymentMiddleware` pattern, but pass the in-process `facilitator` directly instead of an `HTTPFacilitatorClient`. -### `getIndexerTokenBalance` + ```javascript + import { paymentMiddleware, x402ResourceServer } from "@x402/express"; + import { ExactEvmScheme } from "@x402/evm/exact/server"; -Get token balance for **any** address via the WDK Indexer API. **Read-only.** + const NETWORK = process.env.NETWORK_ID || "eip155:9745"; + const USDT0 = process.env.USDT0_ADDRESS || "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb"; -**Input:** + const resourceServer = new x402ResourceServer(facilitator).register( + NETWORK, + new ExactEvmScheme(), + ); -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `blockchain` | `enum` | Yes | Blockchain to query | -| `token` | `enum` | Yes | Token (e.g., `"usdt"`, `"xaut"`, `"btc"`) | -| `address` | `string` | Yes | Wallet address | + app.use( + paymentMiddleware( + { + "GET /weather": { + accepts: [{ + scheme: "exact", + network: NETWORK, + price: { amount: "1000", asset: USDT0, extra: { name: "USDT0", version: "1", decimals: 6 } }, + payTo: process.env.PAY_TO_ADDRESS, + }], + description: "Weather data", + mimeType: "application/json", + }, + }, + resourceServer, + ), + ); + ``` + + -**Output:** +*** -| Field | Type | Description | -| --- | --- | --- | -| `tokenBalance.blockchain` | `string` | Blockchain name | -| `tokenBalance.token` | `string` | Token name | -| `tokenBalance.amount` | `string` | Token balance | +## Summary -This queries the **indexed** balance, which may have slight delay compared to real-time blockchain state. For your own wallet's balance, use `getBalance` or `getTokenBalance` instead. +| Role | Packages | Notes | +| ------------------------ | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | +| **Buyer (Client)** | `@tetherto/wdk-wallet-evm`, `@x402/fetch`, `@x402/evm` | `WalletAccountEvm` satisfies `ClientEvmSigner` directly. | +| **Seller (Hosted)** | `@tetherto/wdk-wallet-evm`, `@x402/express`, `@x402/evm`, `@x402/core` | Delegates to a hosted facilitator. Semantic supports Plasma and Stable. | +| **Seller (Self-Hosted)** | `@tetherto/wdk-wallet-evm`, `@semanticio/wdk-wallet-evm-x402-facilitator`, `@x402/core`, `@x402/evm`, `@x402/express` | In-process facilitator. Any USD₮0 chain. | ---- +*** -### `getTokenTransfers` +## Resources -Get token transfer history for an address. **Read-only.** +* [x402 Protocol Spec](https://www.x402.org) - The open standard specification +* [x402 GitHub](https://github.com/coinbase/x402) - Reference implementations and examples +* [Semantic Facilitator Docs](https://docs.semanticpay.io) - API Reference for the hosted facilitator +* [Self-Hosted Facilitator Module](https://www.npmjs.com/package/@semanticio/wdk-wallet-evm-x402-facilitator) - Community in-process facilitator +* [x402-usdt0 Demo](https://github.com/SemanticPay/x402-usdt0-demo) - Full working buyer + seller demo +* [WDK EVM Wallet Module](../sdk/wallet-modules/wallet-evm/) - WDK EVM wallet documentation +* [USD₮0 Deployments](https://docs.usdt0.to/technical-documentation/deployments) - Contract addresses on all chains +* [EIP-3009 Specification](https://eips.ethereum.org/EIPS/eip-3009) - The authorization standard enabling gasless USD₮ transfers -**Input:** -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `blockchain` | `enum` | Yes | Blockchain to query | -| `token` | `enum` | Yes | Token (e.g., `"usdt"`, `"xaut"`, `"btc"`) | -| `address` | `string` | Yes | Wallet address | -| `limit` | `number` | No | Results per page (1–1000, default: 10) | -| `fromTs` | `number` | No | Start timestamp (unix seconds) | -| `toTs` | `number` | No | End timestamp (unix seconds) | -| `sort` | `enum` | No | `"asc"` or `"desc"` (default: `"desc"`) | +# React Native Starter (Alpha) (/examples-and-starters/react-native-starter) -**Output:** -| Field | Type | Description | -| --- | --- | --- | -| `transfers` | `object[]` | Array of transfer records | -| `transfers[].blockchain` | `string` | Blockchain | -| `transfers[].blockNumber` | `number` | Block number | -| `transfers[].transactionHash` | `string` | Transaction hash | -| `transfers[].token` | `string` | Token | -| `transfers[].amount` | `string` | Transfer amount | -| `transfers[].timestamp` | `number` | Unix timestamp | -| `transfers[].from` | `string` | Sender address | -| `transfers[].to` | `string` | Recipient address | -*** +The React Native Starter Alpha is an Expo + React Native app showing how to build a multi-chain wallet using WDK via BareKit worklets and secure secret management. This starter includes wallet creation/import flows, balances, transactions, and a modular service layer. -## Swap Tools + -_Requires: `registerProtocol()` with a swap protocol_ +*** -### `quoteSwap` + + **Prerequisites:** Node.js 22+, and either Xcode (iOS) or Android SDK API 29+ (Android). See the [React Native Quickstart](../start-building/react-native-quickstart#prerequisites) for details. + -Get a swap quote without executing. **Read-only.** +### Quickstart -**Input:** +Get your React Native wallet running in minutes with these simple steps: -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | Blockchain with swap protocol | -| `tokenIn` | `string` | Yes | Token to sell (e.g., `"USDT"`) | -| `tokenOut` | `string` | Yes | Token to buy (e.g., `"USDC"`) | -| `amount` | `string` | Yes | Amount in human-readable units | -| `side` | `enum` | Yes | `"sell"` or `"buy"` | + + + #### Clone and Install -**Output:** + ```bash + git clone https://github.com/tetherto/wdk-starter-react-native.git && cd wdk-starter-react-native && npm install + ``` + -| Field | Type | Description | -| --- | --- | --- | -| `protocol` | `string` | DEX protocol used | -| `tokenIn` | `string` | Input token symbol | -| `tokenOut` | `string` | Output token symbol | -| `tokenInAmount` | `string` | Input amount (human-readable) | -| `tokenOutAmount` | `string` | Output amount (human-readable) | -| `fee` | `string` | Estimated fee | + + #### Configure Environment ---- + ```bash + cp .env.example .env + ``` -### `swap` + Get your free WDK Indexer API key [here](../tools/indexer-api/get-started) and add it to your `.env` file: -Execute a token swap. **Destructive** - requires user confirmation. + ```bash + EXPO_PUBLIC_WDK_INDEXER_BASE_URL=https://wdk-api.tether.io + EXPO_PUBLIC_WDK_INDEXER_API_KEY=your_actual_api_key_here + # Optional: For Tron network support + EXPO_PUBLIC_TRON_API_KEY=your_tron_api_key + EXPO_PUBLIC_TRON_API_SECRET=your_tron_api_secret + ``` + -**Input:** + + #### Run Your App -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | Blockchain with swap protocol | -| `tokenIn` | `string` | Yes | Token to sell | -| `tokenOut` | `string` | Yes | Token to buy | -| `amount` | `string` | Yes | Amount in human-readable units | -| `side` | `enum` | Yes | `"sell"` or `"buy"` | -| `to` | `string` | No | Recipient address (defaults to wallet) | + For first-time setup, generate native project files: -**Output:** + ```bash + npx expo prebuild + ``` -| Field | Type | Description | -| --- | --- | --- | -| `success` | `boolean` | Whether the swap succeeded | -| `protocol` | `string` | DEX protocol used | -| `hash` | `string` | Transaction hash | -| `tokenIn` | `string` | Input token symbol | -| `tokenOut` | `string` | Output token symbol | -| `tokenInAmount` | `string` | Actual input amount | -| `tokenOutAmount` | `string` | Actual output amount | -| `fee` | `string` | Fee paid | + Then run the app: -This tool quotes the swap first, then shows a confirmation dialog before broadcasting. + ```bash + npm run ios # iOS Simulator + npm run android # Android Emulator + ``` + + *** -## Bridge Tools - -_Requires: `registerProtocol()` with a bridge protocol_ + + **Need detailed instructions?** Check out the complete [React Native Quickstart](../start-building/react-native-quickstart) guide for step-by-step setup, configuration, and troubleshooting. + -### `quoteBridge` +### Features -Get a bridge quote without executing. **Read-only.** +**Multi-Token & Chain Support** -**Input:** +* **BTC**: Native SegWit transfers on Bitcoin network +* **USD₮**: Gasless transactions on EVM (Ethereum, Polygon, Arbitrum), native transfers on TON and Tron +* **XAU₮**: Gasless transactions on Ethereum network -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | Source blockchain | -| `targetChain` | `string` | Yes | Destination blockchain | -| `token` | `string` | Yes | Token to bridge (e.g., `"USDT"`) | -| `amount` | `string` | Yes | Amount in human-readable units | -| `recipient` | `string` | No | Recipient on target chain (defaults to wallet) | +**Wallet Management** -**Output:** +* **Secure Seed Generation**: Cryptographically secure entropy generation +* **Seed Import**: Import existing 12-word mnemonic phrases +* **Encrypted Storage**: Secure key storage via [`@tetherto/wdk-secret-manager`](https://github.com/tetherto/wdk-secret-manager) +* **Multi-Account Support**: Derive multiple accounts from single seed -| Field | Type | Description | -| --- | --- | --- | -| `protocol` | `string` | Bridge protocol used | -| `sourceChain` | `string` | Source blockchain | -| `targetChain` | `string` | Destination blockchain | -| `token` | `string` | Token symbol | -| `amount` | `string` | Amount to bridge | -| `fee` | `string` | Estimated gas fee | -| `bridgeFee` | `string` | Bridge protocol fee | +**Asset Management** ---- +* **Real-Time Balances**: Live balance updates via [WDK Indexer](../tools/indexer-api/) +* **Transaction History**: Complete transaction tracking and history via [WDK Indexer](../tools/indexer-api/) +* **Price Conversion**: Real-time fiat pricing via [Pricing Provider](../tools/price-rates/) -### `bridge` +**User Experience** -Execute a cross-chain bridge. **Destructive** - requires user confirmation. +* **QR Code Scanner**: Scan addresses and payment requests via camera +* **Send/Receive Flows**: Intuitive transfer interfaces +* **Network Selection**: Choose optimal network for each transaction +* **Token Selection**: Multi-token transfer support +* **Activity Feed**: Real-time transaction monitoring -**Input:** +*** -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | Source blockchain | -| `targetChain` | `string` | Yes | Destination blockchain | -| `token` | `string` | Yes | Token to bridge | -| `amount` | `string` | Yes | Amount in human-readable units | -| `recipient` | `string` | No | Recipient on target chain (defaults to wallet) | +### Project Structure -**Output:** +The starter includes a modular architecture designed for scalability and maintainability: -| Field | Type | Description | -| --- | --- | --- | -| `success` | `boolean` | Whether the bridge succeeded | -| `protocol` | `string` | Bridge protocol used | -| `hash` | `string` | Transaction hash | -| `sourceChain` | `string` | Source blockchain | -| `targetChain` | `string` | Destination blockchain | -| `token` | `string` | Token symbol | -| `amount` | `string` | Amount bridged | -| `fee` | `string` | Gas fee paid | -| `bridgeFee` | `string` | Bridge protocol fee paid | +```text title="Project Structure" +src/ +├── app/ # Expo Router screens (file-based routing) +│ ├── onboarding/ # First-time user flows +│ ├── wallet-setup/ # Create/import wallet screens +│ ├── send/ & receive/ # Transaction flows +│ ├── settings.tsx # Configuration & preferences +│ └── token-details.tsx # Individual asset views +├── components/ # Reusable UI components +├── config/ # Network, asset, and chain settings +├── services/ # Business logic (pricing integration) +├── hooks/ # Custom React hooks +└── utils/ # Formatting & helper functions +``` -Bridge finality varies by target chain - tokens may take minutes to hours to arrive. +Detailed project structure can be found in the [Github Repository](https://github.com/tetherto/wdk-starter-react-native/tree/main?tab=readme-ov-file#-project-structure). *** -## Lending Tools +### Available Scripts -_Requires: `registerProtocol()` with a lending protocol_ +| Script | Description | +| ------------------------ | --------------------------------------------- | +| `npm start` | Start Expo development server with dev client | +| `npm run android` | Run on Android emulator/device | +| `npm run ios` | Run on iOS simulator | +| `npm run web` | Start web development server | +| `npm run prebuild` | Generate native project files | +| `npm run prebuild:clean` | Clean and regenerate native project files | +| `npm run lint` | Run ESLint | +| `npm run lint:fix` | Fix ESLint errors | +| `npm run format` | Format code with Prettier | +| `npm run format:check` | Check code formatting | +| `npm run typecheck` | Run TypeScript type checking | -### `quoteSupply` +*** -Get a fee estimate for supplying tokens to a lending pool. **Read-only.** +### Technology Stack -**Input:** +#### Core Technologies -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | Blockchain with lending protocol | -| `token` | `string` | Yes | Token to supply | -| `amount` | `string` | Yes | Amount in human-readable units | -| `onBehalfOf` | `string` | No | Address to receive aTokens (defaults to wallet) | +* **Expo**: \~54.0.8 with development client +* **React Native**: 0.81.4 +* **React**: 19.1.0 +* **TypeScript**: \~5.9.2 +* **Reanimated**: \~4.1.0 +* **New Architecture**: Enabled -**Output:** +#### Build Configuration -| Field | Type | Description | -| --- | --- | --- | -| `protocol` | `string` | Lending protocol used | -| `chain` | `string` | Blockchain | -| `token` | `string` | Token symbol | -| `amount` | `string` | Amount to supply | -| `fee` | `string` | Estimated gas fee | +* **Android**: minSdkVersion 29 +* **iOS**: Latest Xcode toolchain +* **Build Properties**: Configured via `expo-build-properties` ---- +*** -### `supply` +### Next Steps -Supply tokens to a lending pool. **Destructive** - requires user confirmation. +**Customizing the UI** -Same input as `quoteSupply`. Output includes `success`, `protocol`, `hash`, `token`, `amount`, and `fee`. +This starter uses components from the [WDK React Native UI Kit](../ui-kits/react-native-ui-kit/). To customize the look and feel: ---- +* [**Theming Guide**](../ui-kits/react-native-ui-kit/theming) - Deep dive into theming capabilities +* [**Component Reference**](../ui-kits/react-native-ui-kit/api-reference) - Complete component documentation -### `quoteWithdraw` +**Add new functionality** -Estimate fee for withdrawing from a lending pool. **Read-only.** +This starter provides a solid foundation that you can extend with additional functionality: -**Input:** +* **Add support for other tokens** using wallet modules in the [WDK SDK](../sdk/get-started) +* **Add DeFi protocols** like swaps, bridges, and lending using [protocol modules](../sdk/get-started) -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | Blockchain | -| `token` | `string` | Yes | Token to withdraw | -| `amount` | `string` | Yes | Amount in human-readable units | +**Or explore documentation** -**Output:** Same structure as `quoteSupply`. +* [**WDK SDK Documentation**](../sdk/get-started) - Learn about the underlying SDK +* [**UI Kit Documentation**](../ui-kits/react-native-ui-kit/get-started) - Customize the interface +* [**WDK Indexer**](../tools/indexer-api/) - Understand data fetching +* [**Secret Manager**](../tools/secret-manager/) - Learn about secure key management ---- +*** -### `withdraw` +## Need Help? -Withdraw tokens from a lending pool. **Destructive** - requires user confirmation. + -Same input as `quoteWithdraw`. Output includes `success`, `protocol`, `hash`, `token`, `amount`, and `fee`. ---- +# About WDK (/overview/about) -### `quoteBorrow` -Estimate fee for borrowing from a lending pool. **Read-only.** -**Input:** +The **Wallet Development Kit *by Tether* (WDK)** is Tether's open-source toolkit that empowers humans, machines and AI agents alike to build, deploy and use secure, multi-chain, self-custodial wallets that can be integrated anywhere from the smallest embedded device to any mobile, desktop and server operating system. -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | Blockchain | -| `token` | `string` | Yes | Token to borrow | -| `amount` | `string` | Yes | Amount in human-readable units | +A developer-first framework designed for maximum flexibility and scalability, powering anything from consumer wallets to wallet-enabled apps, DeFi integrations (lending, swaps, ...), IoT use cases, and AI agents. -**Output:** Same structure as `quoteSupply`. +Unlike closed solutions or SaaS-based wallet infrastructure providers, WDK offers zero lock-in and is designed for maximum flexibility and extensibility. It is modular, runs on Bare, Node.js and React-Native, thus can be embedded in a wide variety of environments. ---- +*** -### `borrow` +## What Problems Does WDK Solve? -Borrow tokens from a lending pool. **Destructive** - requires user confirmation. +The current blockchain ecosystem is highly fragmented, with each blockchain requiring different SDKs, APIs, and integration approaches. This fragmentation creates significant barriers for developers who want to build truly seamless user-experiences that span across any blockchain, environment and use-case. -Same input as `quoteBorrow`. Output includes `success`, `protocol`, `hash`, `token`, `amount`, and `fee`. +Traditional wallet development requires months of integration work. Developers must learn different standards, implement contrasting security practices, or rely on closed-source paid solutions which act as gatekeepers. ---- +### **The Missing AI Foundation** -### `quoteRepay` +As we move toward a world where humans, machines and AI Agents need to manage digital assets safely, existing solutions fall short. AI agents will require wallets to interact in the financial infrastructure, and WDK wants to lay secure foundation that works for human, AI and IoT use cases. WDK enables trillions of self-custodial wallets. -Estimate fee for repaying a loan. **Read-only.** +*** -**Input:** +## Why WDK is Different -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | Blockchain | -| `token` | `string` | Yes | Token to repay | -| `amount` | `string` | Yes | Amount in human-readable units | + + + Works with Node.js, Bare runtime, mobile (React Native), and future embedded environments + -**Output:** Same structure as `quoteSupply`. + + Pick only the modules you need; extend functionality with custom modules + ---- + + Clear SDK design, strong TypeScript typing, extensive docs, and ready-to-use starters + -### `repay` + + Stateless and self-custodial architecture ensures keys never leave user control + -Repay borrowed tokens. **Destructive** - requires user confirmation. + + Transparent, community-driven, and free to adopt with no vendor lock-in + -Same input as `quoteRepay`. Output includes `success`, `protocol`, `hash`, `token`, `amount`, and `fee`. + + Maintained and supported by Tether with strong community involvement + + *** -## Fiat Tools +## What WDK Provides -_Requires: `registerProtocol()` with a fiat protocol_ +WDK combines four core components to deliver a complete wallet development solution: -### `quoteBuy` + + + Unified APIs for wallet and protocol operations across multiple blockchains + -Get a quote for purchasing crypto with fiat. **Read-only.** + + Reliable blockchain data access for balances, transactions, and historical data + -**Input:** + + Reusable React Native components for building wallet interfaces + -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | Blockchain for the fiat protocol | -| `cryptoAsset` | `string` | Yes | Crypto asset code (e.g., `"eth"`, `"btc"`) | -| `fiatCurrency` | `string` | Yes | Fiat currency code (e.g., `"USD"`, `"EUR"`) | -| `amount` | `string` | Yes | Amount to quote | -| `amountType` | `enum` | Yes | `"crypto"` or `"fiat"` | + + Production-ready wallet templates and reference implementations + + -**Output:** +*** -| Field | Type | Description | -| --- | --- | --- | -| `protocol` | `string` | Fiat protocol used | -| `cryptoAsset` | `string` | Crypto asset code | -| `fiatCurrency` | `string` | Fiat currency code | -| `cryptoAmount` | `string` | Crypto amount (base units) | -| `fiatAmount` | `string` | Fiat amount (smallest units, e.g., cents) | -| `fee` | `string` | Total fee (fiat smallest units) | -| `rate` | `string` | Exchange rate | +## Supported Blockchains & Protocols ---- +WDK natively supports a broad set of blockchains and standards out of the box: -### `buy` + + + | Blockchain/Module | Support | + | --------------------------------------------------------------- | ------- | + | [Bitcoin](../sdk/wallet-modules/wallet-btc/) | ✅ | + | [Ethereum & EVM](../sdk/wallet-modules/wallet-evm/) | ✅ | + | [Ethereum ERC-4337](../sdk/wallet-modules/wallet-evm-erc-4337/) | ✅ | + | [TON](../sdk/wallet-modules/wallet-ton/) | ✅ | + | [TON Gasless](../sdk/wallet-modules/wallet-ton-gasless/) | ✅ | + | [TRON](../sdk/wallet-modules/wallet-tron/) | ✅ | + | [TRON Gasfree](../sdk/wallet-modules/wallet-tron-gasfree/) | ✅ | + | [Solana](../sdk/wallet-modules/wallet-solana/) | ✅ | + | [Spark/Lightning](../sdk/wallet-modules/wallet-spark/) | ✅ | + + + + | Protocol/Module | Support | + | -------------------------------------------------------------- | ----------- | + | [velora (EVM)](../sdk/swap-modules/swap-velora-evm/) | ✅ | + | StonFi (TON) | In progress | + | [USD₮0 Bridge (EVM)](../sdk/bridge-modules/bridge-usdt0-evm/) | ✅ | + | [Aave Lending (EVM)](../sdk/lending-modules/lending-aave-evm/) | ✅ | + + -Execute a fiat-to-crypto purchase. **Destructive** - requires user confirmation. +The modular architecture allows new chains, tokens, or protocols to be added by implementing dedicated modules. -Same input as `quoteBuy`. Output includes `success`, `protocol`, redirect URL or transaction details. +Ready to start building? Explore our [getting started guide](../start-building/nodejs-bare-quickstart) or dive into our [SDK documentation](../sdk/get-started). ---- -### `quoteSell` +# Changelog (/overview/changelog) -Get a quote for selling crypto to fiat. **Read-only.** -Same input structure as `quoteBuy`. Same output structure. ---- +Stay up to date with the latest improvements, new features, and bug fixes across all WDK modules. -### `sell` +*** -Execute a crypto-to-fiat sale. **Destructive** - requires user confirmation. +### May 19, 2026 -Same input as `quoteSell`. Output includes `success`, `protocol`, and transaction details. +**What's New** ---- +* **[Swidge Protocol Interface](../sdk/swidge-modules)**: New page covering WDK's shared route interface for swap-only, bridge-only, and combined swap and bridge providers, including `quoteSwidge()`, `executeSwidge()`, `getSwidgeStatus()`, route options, result fields, status values, fee handling, and migration guidance for the existing standalone swap and bridge interfaces. -### `getTransactionDetail` +*** -Get details of a fiat transaction by ID. **Read-only.** +### April 22, 2026 -**Input:** +**Fixes** -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | Blockchain | -| `transactionId` | `string` | Yes | Transaction ID from the fiat provider | +* **wdk-core** ([v1.0.0-beta.8](https://github.com/tetherto/wdk/releases/tag/v1.0.0-beta.8)): Fix `WDK.getRandomSeedPhrase(wordCount?)` so client code can generate 24-word BIP-39 seed phrases instead of always receiving the default 12-word mnemonic. ---- +*** -### `getSupportedCryptoAssets` +### April 19, 2026 -List crypto assets supported by the fiat provider. **Read-only.** +**Changes** -**Input:** +* **lending-aave-evm** ([v1.0.0-beta.4](https://www.npmjs.com/package/@tetherto/wdk-protocol-lending-aave-evm/v/1.0.0-beta.4)): Expand per-operation ERC‑4337 config overrides from `paymasterToken`-only to the wallet module's paymaster-token, sponsorship-policy, and native-coin gas modes. -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | Blockchain | +**Fixes** ---- +* **failover-provider** ([v1.0.0-beta.2](https://www.npmjs.com/package/@tetherto/wdk-failover-provider/v/1.0.0-beta.2)): Remove unnecessary published type definitions without changing the runtime failover behavior. +* **wallet-solana** ([v1.0.0-beta.7](https://www.npmjs.com/package/@tetherto/wdk-wallet-solana/v/1.0.0-beta.7)): Fix `SolanaWalletConfig.rpcUrl` typings to accept ordered `string[]` failover endpoints and align the published TypeScript definitions with the beta.6 runtime behavior. -### `getSupportedFiatCurrencies` +*** -List fiat currencies supported by the fiat provider. **Read-only.** +### April 15, 2026 -**Input:** +**Changes** -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | Blockchain | +* **wallet-solana** ([v1.0.0-beta.6](https://www.npmjs.com/package/@tetherto/wdk-wallet-solana/v/1.0.0-beta.6)): Add runtime RPC failover support for ordered `rpcUrl` lists plus `retries`, and tighten custom `TransactionMessage` and derivation-path validation for durable nonce lifetimes, fee payer matching, and hardened SLIP-0010 child paths. ---- +*** -### `getSupportedCountries` +### April 14, 2026 -List countries supported by the fiat provider. **Read-only.** +**What's New** -**Input:** +* **failover-provider** ([v1.0.0-beta.1](https://github.com/tetherto/wdk-failover-provider/releases/tag/v1.0.0-beta.1)): Initial release of a generic `FailoverProvider\` that chains provider candidates and retries sync or async failures with configurable `retries` and `shouldRetryOn(error)` logic. -| Parameter | Type | Required | Description | -| --- | --- | --- | --- | -| `chain` | `enum` | Yes | Blockchain | +**Changes** -*** +* **fiat-moonpay** ([v1.0.0-beta.2](https://github.com/tetherto/wdk-protocol-fiat-moonpay/releases/tag/v1.0.0-beta.2)): \[Breaking] Replace `secretKey` signing with optional backend `signUrl`, add `environment` selection for production or sandbox widget URLs, and return unsigned widget URLs when no signer is configured. -## Utility Exports +*** -Utility functions for converting between human-readable amounts and blockchain base units: +### April 13, 2026 -```javascript -import from '@tetherto/wdk-mcp-toolkit' -``` +**What's New** -### `parseAmountToBaseUnits(amount, decimals)` +* **wdk-utils** ([v1.0.0-beta.2](https://github.com/tetherto/wdk-utils/releases/tag/v1.0.0-beta.2)): Add EIP-681 request parsing utilities for transfer deeplinks, including request detection and structured parse results. +* **wdk-core** ([v1.0.0-beta.7](https://github.com/tetherto/wdk/releases/tag/v1.0.0-beta.7)): Added `dispose(blockchains?)`, so you can dispose one or more registered wallets without tearing down every wallet in the WDK instance. +* **pear-wrk-wdk** ([v1.0.0-beta.8](../tools/pear-wrk-wdk)): Adds `resetWdkWallets({ config })` so custom Bare hosts can selectively dispose and re-register wallet modules from a new `networks` config. -Converts a human-readable amount string to `BigInt` base units without floating-point errors. +**Changes** -```javascript -parseAmountToBaseUnits('2.01', 6) // → 2010000n -parseAmountToBaseUnits('100', 18) // → 100000000000000000000n -parseAmountToBaseUnits('1,000.50', 6) // → 1000500000n -``` +* **wallet-spark** ([v1.0.0-beta.13](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.13)): Refresh `@buildonspark/bare` and `@buildonspark/spark-sdk` dependencies. +* **wallet-spark** ([v1.0.0-beta.14](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.14)): Add SparkScan-backed balance polling for `getBalance()`. +* **wallet-spark** ([v1.0.0-beta.15](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.15)): Refresh `@buildonspark/bare`, `@buildonspark/spark-sdk`, and `bare-node-runtime` dependencies. +* **wallet-spark** ([v1.0.0-beta.16](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.16)): Add `syncAndRetry` and `syncWalletBalance()` for retrying failed `sendTransaction()` and `payLightningInvoice()` calls once after syncing wallet state. -### `formatBaseUnitsToAmount(baseUnits, decimals)` +**Fixes** -Converts `BigInt` base units to a human-readable string. +* **worklet-bundler** ([v1.0.0-beta.3](https://github.com/tetherto/wdk-worklet-bundler/releases/tag/v1.0.0-beta.3)): Generated worklet entrypoints now suspend and resume both HTTP and HTTPS global agents with Bare thread lifecycle events. +* **wallet-btc** ([v1.0.0-beta.8](https://github.com/tetherto/wdk-wallet-btc/releases/tag/v1.0.0-beta.8)): `getBalance()` now includes unconfirmed funds when present, and `sendTransaction()` accepts an optional `timeoutMs` to keep polling after broadcast until spent inputs disappear from unspent outputs. +* **wallet-evm** ([v1.0.0-beta.11](https://github.com/tetherto/wdk-wallet-evm/releases/tag/v1.0.0-beta.11)): Pin string-backed RPC providers to a static network during EVM account setup. +* **wallet-evm-erc-4337** ([v1.0.0-beta.6](https://github.com/tetherto/wdk-wallet-evm-erc-4337/releases/tag/v1.0.0-beta.6)): Reuse the internal EVM read-only helper during ERC-4337 method calls instead of recreating it on each call. -```javascript -formatBaseUnitsToAmount(2010000n, 6) // → '2.01' -formatBaseUnitsToAmount(100000000000000000000n, 18) // → '100' -``` +*** -### `AmountParseError` +### April 3, 2026 -Custom error class with a `code` property for programmatic handling: +**Changes** -| Error Code | Description | -| --- | --- | -| `EMPTY_STRING` | Empty amount string | -| `INVALID_FORMAT` | Not a valid number | -| `NEGATIVE_AMOUNT` | Negative amounts not allowed | -| `EXCESSIVE_PRECISION` | More decimal places than token supports | -| `INVALID_DECIMALS` | Decimals value out of range | -| `SCIENTIFIC_NOTATION_PRECISION` | Scientific notation exceeds precision | +* **wallet-spark** ([v1.0.0-beta.12](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.12)): [`WalletAccountReadOnlySpark`](../sdk/wallet-modules/wallet-spark/api-reference) gained [`getTransfers()`](../sdk/wallet-modules/wallet-spark/api-reference), [`getUnusedDepositAddresses()`](../sdk/wallet-modules/wallet-spark/api-reference) (paginated return type), [`getStaticDepositAddresses()`](../sdk/wallet-modules/wallet-spark/api-reference), [`getUtxosForDepositAddress()`](../sdk/wallet-modules/wallet-spark/api-reference), and [`getSparkInvoices()`](../sdk/wallet-modules/wallet-spark/api-reference) (new parameter type). Removed `sparkScanApiKey` config option and `SparkTransactionReceipt` type after dropping the `@sparkscan/api-node-sdk-client` dependency. [`getTransactionReceipt()`](../sdk/wallet-modules/wallet-spark/api-reference) now returns `SparkTransfer` instead. Added [`getAccountByPath()`](../sdk/wallet-modules/wallet-spark/api-reference) to [`WalletManagerSpark`](../sdk/wallet-modules/wallet-spark/api-reference). SIGNET network support documented. Dependency upgrades: `@buildonspark/spark-sdk` 0.7.3, `@buildonspark/bare` 0.0.53. *** -## Need Help? -## Configuration -URL: https://docs.wdk.tether.su/ai/mcp-toolkit/configuration -Description: Configure wallets, capabilities, tokens, protocols, and custom tools -## Server Setup +### April 2, 2026 -Create a server with a name and version: +**Changes** -```javascript -import from '@tetherto/wdk-mcp-toolkit' +* **react-native-core** ([v1.0.0-beta.7](https://www.npmjs.com/package/@tetherto/wdk-react-native-core/v/1.0.0-beta.7)): Added missing type exports: `WdkAppState`, `TransactionParams`, `TransactionResult`, `UseAccountResponse`, `AddressInfo`, `AddressInfoResult`, `BalanceQueryOptions`, `UseWdkAppResult`. Removed `indexer` as a top-level config prop. -const server = new WdkMcpServer('my-server', '1.0.0') -``` +*** -The `WdkMcpServer` extends `McpServer` from the official [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) with WDK-specific capabilities. All standard MCP server features are available. +### March 24, 2026 -*** +**What's New** -## Wallet Configuration +* **[React Native Core](../tools/react-native-core/)**: Added documentation for `@tetherto/wdk-react-native-core` ([v1.0.0-beta.6](https://github.com/tetherto/wdk-core-react-native/releases/tag/v1.0.0-beta.6)), the hooks-based React Native integration layer for WDK. Includes [API Reference](../tools/react-native-core/api-reference) covering `WdkAppProvider`, `useWdkApp`, `useWalletManager`, `useAccount`, `useBalance`, and more. Updated [React Native Quickstart](../start-building/react-native-quickstart) with step-by-step integration guide. -### Enable WDK +*** -```javascript -server.useWdk() -``` +### March 12, 2026 -The `seed` is a BIP-39 mnemonic phrase used for key derivation across all registered blockchains. +**Changes** -**Never hardcode seed phrases in source code.** Use environment variables or a secrets manager. The setup wizard generates a gitignored `.vscode/mcp.json` for local development. +* **wallet-btc** ([v1.0.0-beta.6](https://github.com/tetherto/wdk-wallet-btc/releases/tag/v1.0.0-beta.6)): Added `dispose()` method to [`WalletAccountReadOnlyBtc`](../sdk/wallet-modules/wallet-btc/api-reference) for closing internal Electrum connections. Security dependency updates. -### Register Wallets +*** -Register a wallet module for each blockchain you want to support: +### March 6, 2026 -```javascript -import WalletManagerEvm from '@tetherto/wdk-wallet-evm' -import WalletManagerBtc from '@tetherto/wdk-wallet-btc' -import WalletManagerSolana from '@tetherto/wdk-wallet-solana' +**Changes** -// EVM chains - one module handles all EVM networks -server.registerWallet('ethereum', WalletManagerEvm, ) -server.registerWallet('polygon', WalletManagerEvm, ) +* **wallet-tron**: Fixed case-sensitive address check in `verify`, upgraded TonWeb to v6.2.0 (`v1.0.0-beta.5`) +* **lending-aave-evm**: Security dependency updates ([v1.0.0-beta.4](https://github.com/tetherto/wdk-protocol-lending-aave-evm/releases/tag/v1.0.0-beta.4)) +* **wdk**: Security dependency updates ([v1.0.0-beta.6](https://github.com/tetherto/wdk/releases/tag/v1.0.0-beta.6)) -// Bitcoin -server.registerWallet('bitcoin', WalletManagerBtc, ) +*** -// Solana -server.registerWallet('solana', WalletManagerSolana, ) -``` +### March 5, 2026 -Each `registerWallet()` call registers the chain name and makes it available to all wallet tools. For configuration details of each wallet module, see the [Wallet Modules](../../sdk/wallet-modules/) documentation. +**What's New** + +* **create-wdk-module**: Added documentation for the [`create-wdk-module`](../tools/create-wdk-module) CLI scaffolding tool. Updated [Community Modules](../sdk/community-modules/) and [SDK Get Started](../sdk/get-started) pages with references to the new tool. *** -## Capabilities +### February 26, 2026 -Enable optional capabilities before registering their tools: +**Changes** -| Capability | Method | Requirement | Unlocks | -| --- | --- | --- | --- | -| **Pricing** | `server.usePricing()` | None | `PRICING_TOOLS` (2 tools) | -| **Indexer** | `server.useIndexer()` | [WDK API key](../../tools/indexer-api/get-started/#request-api-key) | `INDEXER_TOOLS` (2 tools) | -| **Swap** | `server.registerProtocol(chain, label, SwapProtocol)` | Swap module installed | `SWAP_TOOLS` (2 tools) | -| **Bridge** | `server.registerProtocol(chain, label, BridgeProtocol)` | Bridge module installed | `BRIDGE_TOOLS` (2 tools) | -| **Lending** | `server.registerProtocol(chain, label, LendingProtocol)` | Lending module installed | `LENDING_TOOLS` (8 tools) | -| **Fiat** | `server.registerProtocol(chain, label, FiatProtocol, config)` | Fiat module installed | `FIAT_TOOLS` (8 tools) | +* **wdk-protocol-bridge-usdt0-evm** ([v1.0.0-beta.3](https://github.com/tetherto/wdk-protocol-bridge-usdt0-evm/releases/tag/v1.0.0-beta.3)): Added per-call `BridgeOptions` overrides (`oftContractAddress`, `dstEid`) and expanded routing from EVM source chains to EVM plus non-EVM destinations (Solana, TON, TRON). -### Pricing +*** -Fetches live prices from Bitfinex. No API key needed. +### February 25, 2026 -```javascript -server.usePricing() -``` +**Changes** -### Indexer +* **wallet-evm** ([v1.0.0-beta.8](https://github.com/tetherto/wdk-wallet-evm/releases/tag/v1.0.0-beta.8)): Added [`getTokenBalances(tokenAddresses)`](../sdk/wallet-modules/wallet-evm/api-reference) to [`WalletAccountReadOnlyEvm`](../sdk/wallet-modules/wallet-evm/api-reference), also available on [`WalletAccountEvm`](../sdk/wallet-modules/wallet-evm/api-reference) through inheritance. +* **wallet-evm-erc-4337** ([v1.0.0-beta.5](https://github.com/tetherto/wdk-wallet-evm-erc-4337/releases/tag/v1.0.0-beta.5)): Added EIP-712 typed data methods [`signTypedData(typedData)`](../sdk/wallet-modules/wallet-evm-erc-4337/api-reference) and [`verifyTypedData(typedData, signature)`](../sdk/wallet-modules/wallet-evm-erc-4337/api-reference), plus multicall token balance method [`getTokenBalances(tokenAddresses)`](../sdk/wallet-modules/wallet-evm-erc-4337/api-reference). -Enables querying token balances and transfer history for **any** address. Requires an API key. +*** -```javascript -server.useIndexer() -``` +### February 24, 2026 -### Protocols +**Changes** -DeFi protocols are registered per-chain: +* **wallet-spark** ([v1.0.0-beta.11](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.11)): Added Pear runtime entrypoint support (`pear.js`), removed static import causing runtime issues, and bumped spark bare SDK (`@buildonspark/bare`) to `0.0.47`. -```javascript -import VeloraProtocolEvm from '@tetherto/wdk-protocol-swap-velora-evm' -import Usdt0ProtocolEvm from '@tetherto/wdk-protocol-bridge-usdt0-evm' -import AaveProtocolEvm from '@tetherto/wdk-protocol-lending-aave-evm' -import MoonPayProtocol from '@tetherto/wdk-protocol-fiat-moonpay' +*** -server.registerProtocol('ethereum', 'velora', VeloraProtocolEvm) -server.registerProtocol('ethereum', 'usdt0', Usdt0ProtocolEvm) -server.registerProtocol('ethereum', 'aave', AaveProtocolEvm) -server.registerProtocol('ethereum', 'moonpay', MoonPayProtocol, ) -``` +### February 20, 2026 -*** +**What's New** -## Token Management +* **[Showcase](../overview/showcase)**: More visibility for our showcase page, we value contributions! Added 4 featured community projects: [wdk-mcp](https://github.com/dieselftw/wdk-mcp), [wdk-starter-browser-extension](https://github.com/base58-io/wdk-starter-browser-extension), [wdk-wallet-evm-x402-facilitator](https://github.com/SemanticPay/wdk-wallet-evm-x402-facilitator), and [x402-usdt0](https://github.com/baghdadgherras/x402-usdt0). +* **[Community Modules](../sdk/community-modules)**: Added [`@base58-io/wdk-wallet-cosmos`](https://github.com/base58-io/wdk-wallet-cosmos) — wallet module for Cosmos-compatible blockchains by [Base58](https://base58.io/). -### Default Tokens +*** -USDT is auto-registered for supported chains via `DEFAULT_TOKENS`. You can query what's available: +### February 18, 2026 -```javascript -server.getRegisteredTokens('ethereum') // ['USDT'] -``` +**What's New** -### Custom Tokens +* **[x402 Payments](../ai/x402)**: New guide for accepting and making instant USD₮ payments over HTTP using WDK self-custodial wallets. Covers the x402 protocol, buyer integration with `@tetherto/wdk-wallet-evm`, seller setup with hosted and self-hosted facilitators, and bridging USD₮ to Plasma and Stable chains. -Register additional tokens with `registerToken()`: +*** -```javascript -server.registerToken('ethereum', 'DAI', ) -``` +### February 15, 2026 -Registered tokens are available to all tools that accept a `token` parameter (`getTokenBalance`, `transfer`, `quoteTransfer`, `swap`, etc.). +**Changes** + +* **wallet-spark**: Added [`getIdentityKey()`](../sdk/wallet-modules/wallet-spark/api-reference) method to [`WalletAccountReadOnlySpark`](../sdk/wallet-modules/wallet-spark/api-reference) for retrieving the account's identity public key ([v1.0.0-beta.10](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.10)) *** -## Tool Registration +### February 14, 2026 -### Built-in Tool Arrays +**Changes** -Each category exports three arrays for fine-grained control: +* **wallet-spark**: Upgrade spark-sdk from `0.6.1` to `0.6.4` and spark bare SDK to `0.0.43` ([v1.0.0-beta.9](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.9)) -| Export | Contents | -| --- | --- | -| `WALLET_TOOLS` | All 11 wallet tools | -| `WALLET_READ_TOOLS` | 7 read-only wallet tools | -| `WALLET_WRITE_TOOLS` | 4 wallet tools that modify state | -| `PRICING_TOOLS` | All 2 pricing tools | -| `INDEXER_TOOLS` | All 2 indexer tools | -| `SWAP_TOOLS` | All 2 swap tools | -| `SWAP_READ_TOOLS` | 1 read-only swap tool | -| `SWAP_WRITE_TOOLS` | 1 swap tool that modifies state | -| `BRIDGE_TOOLS` | All 2 bridge tools | -| `BRIDGE_READ_TOOLS` | 1 read-only bridge tool | -| `BRIDGE_WRITE_TOOLS` | 1 bridge tool that modifies state | -| `LENDING_TOOLS` | All 8 lending tools | -| `LENDING_READ_TOOLS` | 4 read-only lending tools | -| `LENDING_WRITE_TOOLS` | 4 lending tools that modify state | -| `FIAT_TOOLS` | All 8 fiat tools | -| `FIAT_READ_TOOLS` | 6 read-only fiat tools | -| `FIAT_WRITE_TOOLS` | 2 fiat tools that modify state | +*** -### Read-Only Mode +### February 12, 2026 -To allow an AI agent to query data without the ability to make transactions: +**What's New** -```javascript -import from '@tetherto/wdk-mcp-toolkit' +* **[Agent Skills](../ai/agent-skills)**: New page covering WDK's agent skill capabilities, self-custodial vs hosted comparison, and platform compatibility with OpenClaw, Claude, Cursor, and other agent platforms. +* **[OpenClaw Integration](../ai/openclaw)**: New page for installing and configuring the WDK skill in OpenClaw via ClawHub, including security precautions for running agents locally. -server.registerTools([ - ...WALLET_READ_TOOLS, - ...PRICING_TOOLS, - ...INDEXER_TOOLS, - ...SWAP_READ_TOOLS -]) -``` +**Changes** -### Individual Tool Registration +* **wallet-evm** ([v1.0.0-beta.7](https://github.com/tetherto/wdk-wallet-evm/releases/tag/v1.0.0-beta.7)): Added [EIP-712](https://eips.ethereum.org/EIPS/eip-712) typed data support: + * Added [`signTypedData(typedData)`](../sdk/wallet-modules/wallet-evm/api-reference) method to [`WalletAccountEvm`](../sdk/wallet-modules/wallet-evm/api-reference) for signing structured data + * Added [`verifyTypedData(typedData, signature)`](../sdk/wallet-modules/wallet-evm/api-reference) method to [`WalletAccountEvm`](../sdk/wallet-modules/wallet-evm/api-reference) and [`WalletAccountReadOnlyEvm`](../sdk/wallet-modules/wallet-evm/api-reference) for verifying typed data signatures +* **wallet-evm-erc-4337** ([v1.0.0-beta.4](https://github.com/tetherto/wdk-wallet-evm-erc-4337/releases/tag/v1.0.0-beta.4)): + * Added 2 new gas payment modes: [Sponsorship Policy](../sdk/wallet-modules/wallet-evm-erc-4337/configuration#gas-payment-mode-flags) and [Native Coins](../sdk/wallet-modules/wallet-evm-erc-4337/configuration#gas-payment-mode-flags), alongside the existing Paymaster Token mode + * Added per-call [config override](../sdk/wallet-modules/wallet-evm-erc-4337/api-reference) parameter to `sendTransaction`, `transfer`, `quoteSendTransaction`, and `quoteTransfer` + * Added [`getUserOperationReceipt(hash)`](../sdk/wallet-modules/wallet-evm-erc-4337/api-reference) method for retrieving ERC-4337 UserOperation receipts + * Added [`ConfigurationError`](../sdk/wallet-modules/wallet-evm-erc-4337/api-reference) error type for invalid configuration validation -You can also import and register tools individually: +*** -```javascript -import from '@tetherto/wdk-mcp-toolkit' +### February 10, 2026 -server.registerTools([getAddress, getBalance, getCurrentPrice]) -``` +**What's New** -### Custom Tools +* **[Build with AI](../start-building/build-with-ai)**: New guide for using AI coding assistants with WDK. Includes MCP server setup, Markdown context endpoints, project rules, and example prompts. Supports Cursor, Claude Code, GitHub Copilot, Windsurf, Cline, and Continue. +* **[MCP Toolkit](../ai/mcp-toolkit)**: New documentation for `@tetherto/wdk-mcp-toolkit` (`v1.0.0-beta.1`). Covers the `WdkMcpServer` class, 35 built-in MCP tools across 7 categories (wallet, pricing, indexer, swap, bridge, lending, fiat), setup wizard, multi-tool configuration, and full API Reference. -Add your own MCP tools alongside the built-in ones using the standard `registerTool()` method (inherited from `McpServer`). See the [MCP SDK tools documentation](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server.md#tools) for full details. +*** -```javascript -server.registerTool( - 'myCustomTool', - { - title: 'My Custom Tool', - description: 'Description of what this tool does', - inputSchema: z.object(), - outputSchema: z.object(), - annotations: - }, - async () => { - return { - content: [{ type: 'text', text: `Result: $` }], - structuredContent: - } - } -) -``` +### February 08, 2026 + +**Changes** + +* **wallet-spark**: Fixed import causing wallet init failure. Upgrade spark-sdk from `0.5.7` to `0.6.1` ([v1.0.0-beta.8](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.8)) *** -## Environment Variables +### February 02, 2026 + +**Changes** -| Variable | Required | Description | -| --- | --- | --- | -| `WDK_SEED` | Yes | BIP-39 mnemonic for wallet key derivation | -| `WDK_INDEXER_API_KEY` | No | API key for WDK Indexer | -| `MOONPAY_API_KEY` | No | API key for MoonPay fiat on/off-ramp | -| `MOONPAY_SECRET_KEY` | No | Secret key for MoonPay | +* **wallet-ton-gasless**: Added `verify` method to [`WalletAccountReadOnlyTonGasless`](../sdk/wallet-modules/wallet-ton-gasless/api-reference#walletaccountreadonlytongasless) ([v1.0.0-beta.4](https://github.com/tetherto/wdk-wallet-ton-gasless/releases/tag/v1.0.0-beta.4)) +* **wallet-tron-gasfree**: Added `verify` method to [`WalletAccountReadOnlyTronGasfree`](../sdk/wallet-modules/wallet-tron-gasfree/api-reference#walletaccountreadonlytrongasfree) ([v1.0.0-beta.4](https://github.com/tetherto/wdk-wallet-tron-gasfree/releases/tag/v1.0.0-beta.4)) -*** +### January 29, 2026 -## Security Checklist +**What's New** + +* **wdk-indexer** + * Updated Ethereum indexer supported tokens list to add USA₮. -**Self-custodial wallets require careful key management.** Follow these guidelines to protect user funds. +**Changes** -- [ ] **Use a dedicated development wallet** - Never use production wallets with real funds for testing -- [ ] **Never hardcode seed phrases** - Always use environment variables or `.vscode/mcp.json` (gitignored) -- [ ] **Use `WALLET_READ_TOOLS` for untrusted agents** - Only register write tools when user confirmation is available -- [ ] **Call `server.close()` on shutdown** - This disposes the WDK instance and wipes keys from memory -- [ ] **Use `stdio` transport** - The default transport communicates only with the local AI client process -- [ ] **Review MCP annotations** - Tools declare `readOnlyHint` and `destructiveHint` so clients can warn users appropriately -- [ ] **Keep `.vscode/mcp.json` gitignored** - The setup wizard handles this automatically +* **wdk-indexer docs** + * Fixed the USD₮, XAU₮ token names. *** -## Need Help? -## Get Started -URL: https://docs.wdk.tether.su/ai/mcp-toolkit/get-started -Description: Install the MCP Toolkit and run your first AI-powered wallet server -**Building a LangChain agent?** The `serve` command provides zero-config MCP server startup -- no server script needed. See [LangChain Integration](langchain). +### January 26, 2026 -## Setup Wizard +**Changes** -The fastest way to get running. Clone the repository and let the wizard configure everything: +* **wallet-btc** ([v1.0.0-beta.5](https://github.com/tetherto/wdk-wallet-btc/releases/tag/v1.0.0-beta.5)): + * Added `verify` method to [`WalletAccountReadOnlyBtc`](../sdk/wallet-modules/wallet-btc/api-reference) + * Added Pluggable Transport classes: [`ElectrumTcp`](../sdk/wallet-modules/wallet-btc/api-reference), [`ElectrumTls`](../sdk/wallet-modules/wallet-btc/api-reference), [`ElectrumSsl`](../sdk/wallet-modules/wallet-btc/api-reference), [`ElectrumWs`](../sdk/wallet-modules/wallet-btc/api-reference) +* **wallet-evm**: Added `verify` method to [`WalletAccountReadOnlyEvm`](../sdk/wallet-modules/wallet-evm/api-reference) ([v1.0.0-beta.5](https://github.com/tetherto/wdk-wallet-evm/releases/tag/v1.0.0-beta.5)) +* **wallet-solana**: Added `verify` method to [`WalletAccountReadOnlySolana`](../sdk/wallet-modules/wallet-solana/api-reference) ([v1.0.0-beta.5](https://github.com/tetherto/wdk-wallet-solana/releases/tag/v1.0.0-beta.5)) +* **wallet-ton**: Added `verify` method to [`WalletAccountReadOnlyTon`](../sdk/wallet-modules/wallet-ton/api-reference) ([v1.0.0-beta.7](https://github.com/tetherto/wdk-wallet-ton/releases/tag/v1.0.0-beta.7)) +* **wallet-tron**: Added `verify` method to [`WalletAccountReadOnlyTron`](../sdk/wallet-modules/wallet-tron/api-reference) ([v1.0.0-beta.4](https://github.com/tetherto/wdk-wallet-tron/releases/tag/v1.0.0-beta.4)) +* **wallet-spark**: Added `verify` method to [`WalletAccountReadOnlySpark`](../sdk/wallet-modules/wallet-spark/api-reference) ([v1.0.0-beta.7](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.7)) -```bash title="Terminal" -git clone https://github.com/tetherto/wdk-mcp-toolkit.git -cd wdk-mcp-toolkit -npm install -npm run setup -``` +*** -The wizard will: -1. Prompt for your seed phrase (required) -2. Ask for optional API keys (WDK Indexer, MoonPay) -3. Generate `.vscode/mcp.json` with your credentials -4. Install required dependencies automatically +### January 23, 2026 -Once complete, open the project in VS Code, start the MCP server from `.vscode/mcp.json`, and open the chatbot with **Cmd + Shift + I** (or run **Chat: Open Agent** from the Command Palette on non-Mac). +**What's New** -**Security** - Your seed phrase is stored locally in `.vscode/mcp.json`, which is gitignored. Always use a **dedicated development wallet** with limited funds. +* **wdk-core docs**: Added comprehensive [Core Module Guides](../sdk/core-module/guides/getting-started) covering: + * [Getting Started](../sdk/core-module/guides/getting-started) - Installation and instantiation + * [Wallet Registration](../sdk/core-module/guides/wallet-registration) - Registering wallet modules for different blockchains + * [Account Management](../sdk/core-module/guides/account-management) - Working with accounts and addresses + * [Transactions](../sdk/core-module/guides/transactions) - Sending native tokens + * [Protocol Integration](../sdk/core-module/guides/protocol-integration) - Using swaps, bridges, and lending protocols + * [Middleware](../sdk/core-module/guides/middleware) - Configuring logging and failover protection + * [Error Handling](../sdk/core-module/guides/error-handling) - Best practices and memory management +* **wdk-core**: Added support for 24-word seed phrases via `WDK.getRandomSeedPhrase(24)` +* **indexer-api**: + * Added new `/api/v1/chains` endpoint to list supported blockchains and tokens + * Added XAU₮ support for Plasma network -*** +**Changes** -## Manual Setup +* **wallet-btc docs**: + * Updated documentation with BIP-84 (Native SegWit) and BIP-44 (Legacy) support + * Improved API Reference and configuration documentation +* **wallet-spark docs**: + * Removed testnet support (now only mainnet and regtest) + * Added [Lightspark Regtest Faucet](https://app.lightspark.com/regtest-faucet) link for test funds +* **wallet-tron-gasfree docs**: + * Updated testnet from Shasta to Nile + * Updated GasFree service URLs and configuration examples +* **wallet-evm-erc-4337 docs**: Added paymaster token configuration documentation +* **docs**: + * Updated token symbols to USD₮ and XAU₮ throughout documentation + * Various documentation improvements with better cross-linking and examples -If you prefer to set things up yourself or want to integrate the toolkit into an existing project: +**Fixes** -#### Install the toolkit +* **wallet-tron-gasfree docs**: Fixed typo "Gras-Free" to "Gas-Free" +* Fixed GitBook callout syntax and formatting issues across documentation -Install the MCP Toolkit and the wallet modules you need: +*** -```bash title="Terminal" -npm install @tetherto/wdk-mcp-toolkit @modelcontextprotocol/sdk +### December 23, 2025 -# Wallet modules (add any combination) -npm install @tetherto/wdk-wallet-evm # Ethereum, Polygon, Arbitrum, etc. -npm install @tetherto/wdk-wallet-btc # Bitcoin -``` +**What's New** -#### Create your MCP server +* Added [MoonPay Fiat Module](../sdk/fiat-modules/fiat-moonpay/) for on-ramp and off-ramp functionality +* Added [Community Modules](../sdk/community-modules/) section to highlight community-built modules -Create `index.js` with a basic multi-chain server: +**Changes** -```javascript title="index.js" -import from '@tetherto/wdk-mcp-toolkit' -import WalletManagerEvm from '@tetherto/wdk-wallet-evm' -import WalletManagerBtc from '@tetherto/wdk-wallet-btc' +* Added this changelog page in the docs! +* **wallet-spark**: Updated Spark SDK to latest version ([v1.0.0-beta.6](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.6)) +* Introduced [All Modules](../sdk/all-modules) page in docs for comprehensive module listings +* Reorganized documentation structure for better navigation -const server = new WdkMcpServer('my-wallet-server', '1.0.0') +*** -// 1. Enable WDK with your seed phrase -server.useWdk() +### December 17, 2025 -// 2. Register wallet modules -server.registerWallet('ethereum', WalletManagerEvm, ) +**What's New** -server.registerWallet('bitcoin', WalletManagerBtc, ) +* **wdk-core**: Added fiat protocol support for on-ramp integrations ([v1.0.0-beta.5](https://github.com/tetherto/wdk-core/releases/tag/v1.0.0-beta.5)) +* **wdk-wallet**: Added fiat protocol integration ([v1.0.0-beta.6](https://github.com/tetherto/wdk-wallet/releases/tag/v1.0.0-beta.6)) -// 3. Enable pricing -server.usePricing() +*** -// 4. Register tools and start -server.registerTools([...WALLET_TOOLS, ...PRICING_TOOLS]) -``` +### December 3, 2025 + +**What's New** -#### Connect your AI client +* **wallet-ton**: Added integration tests ([v1.0.0-beta.6](https://github.com/tetherto/wdk-wallet-ton/releases/tag/v1.0.0-beta.6)) +* **wallet-btc**: Added support for custom `feeRate` and `confirmationTarget` parameters ([v1.0.0-beta.4](https://github.com/tetherto/wdk-wallet-btc/releases/tag/v1.0.0-beta.4)) -Add the MCP server to your AI tool's configuration: +**Changes** -**Config path:** `.vscode/mcp.json` (project-level) +* **wallet-ton**: Updated default derivation path, fixed transaction receipt LT and from address +* **wallet-solana**: Updated default derivation path for better compatibility ([v1.0.0-beta.4](https://github.com/tetherto/wdk-wallet-solana/releases/tag/v1.0.0-beta.4)) +* **wallet-btc**: Multiple improvements: + * Automatic dust limit inference based on wallet type + * Performance improvements with bounded concurrency and caching for `getTransfers` + * Switched to `bitcoinjs-message` for standard message signing + * Updated default BIP to 84 (Native SegWit) + * Fixed testnet derivation path (now uses `1'`) -```json title=".vscode/mcp.json" -{ - "servers": { - "wdk": { - "type": "stdio", - "command": "node", - "args": ["index.js"], - "env": - } - } -} -``` +*** -Then in VS Code: -1. Open `.vscode/mcp.json` and click **Start** above the server config -2. Open GitHub Copilot Chat and select **Agent mode** -3. Click **Tools** to verify the MCP tools are available +### November 14, 2025 -→ [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) +**Changes** -**Config path:** `.cursor/mcp.json` (project-level) +* **wdk-wallet**: Runtime updates and dependency synchronization ([v1.0.0-beta.5](https://github.com/tetherto/wdk-wallet/releases/tag/v1.0.0-beta.5)) -```json -{ - "mcpServers": { - "wdk": { - "command": "node", - "args": ["index.js"], - "env": - } - } -} -``` +*** -→ [Cursor MCP documentation](https://cursor.com/docs/context/mcp) +### November 12, 2025 -Run this command from your project directory: +**What's New** -```bash -claude mcp add wdk -- node index.js -``` +* **wallet-solana**: Added `sendTransaction` support with unit tests ([v1.0.0-beta.3](https://github.com/tetherto/wdk-wallet-solana/releases/tag/v1.0.0-beta.3)) -Set the environment variable separately: +**Changes** -```bash -export WDK_SEED="your twelve word seed phrase here" -``` +* **wallet-solana**: Fixed `punycode` module resolution issue +* **lending-aave-evm**: Runtime compatibility updates ([v1.0.0-beta.3](https://github.com/tetherto/wdk-protocol-lending-aave-evm/releases/tag/v1.0.0-beta.3)) -→ [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/tutorials#set-up-model-context-protocol-mcp) +*** -**Config path:** `~/.codeium/windsurf/mcp_config.json` +### November 11, 2025 -```json -{ - "mcpServers": { - "wdk": { - "command": "node", - "args": ["index.js"], - "env": - } - } -} -``` +**Changes** -→ [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp) +* **swap-velora-evm**: Runtime compatibility updates ([v1.0.0-beta.4](https://github.com/tetherto/wdk-protocol-swap-velora-evm/releases/tag/v1.0.0-beta.4)) -Add via Cline's MCP settings panel in VS Code, or create the config file directly: +*** -```json -{ - "mcpServers": { - "wdk": { - "command": "node", - "args": ["index.js"], - "env": - } - } -} -``` +### November 9-10, 2025 -→ [Cline MCP documentation](https://github.com/cline/cline#add-context) +**What's New** -**Config path:** `~/.continue/config.yaml` +* **wallet-ton-gasless**: Added unit tests ([v1.0.0-beta.3](https://github.com/tetherto/wdk-wallet-ton-gasless/releases/tag/v1.0.0-beta.3)) +* **pear-wrk-wdk**: Added seed buffer support in `workletStart` ([v1.0.0-beta.5](../tools/pear-wrk-wdk)) -Add to the `mcpServers` section with the command and arguments for your server: +**Changes** -``` -command: node -args: ["index.js"] -env: - WDK_SEED: "your twelve word seed phrase here" -``` +* **wallet-tron-gasfree**: Fixed bug interacting with Gasfree API ([v1.0.0-beta.3](https://github.com/tetherto/wdk-wallet-tron-gasfree/releases/tag/v1.0.0-beta.3)) +* **wallet-ton-gasless**: Updated TON query-id and transaction hash handling +* **wallet-evm**: Runtime updates ([v1.0.0-beta.4](https://github.com/tetherto/wdk-wallet-evm/releases/tag/v1.0.0-beta.4)) +* **wallet-tron**: Dependency and runtime updates ([v1.0.0-beta.3](https://github.com/tetherto/wdk-wallet-tron/releases/tag/v1.0.0-beta.3)) -→ [Continue MCP documentation](https://docs.continue.dev/customize/mcp-tools) +*** -#### Try it out +### November 8, 2025 -Ask your AI assistant: +**Changes** -``` -What's my ethereum address? -``` +* **wdk-core**: Updated `bare-node-runtime` for improved compatibility ([v1.0.0-beta.4](https://github.com/tetherto/wdk-core/releases/tag/v1.0.0-beta.4)) +* **wallet-spark**: Updated Spark dependencies and improved `dispose` method ([v1.0.0-beta.5](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.5)) -``` -Check my BTC balance -``` +*** -``` -What's the current price of ETH in USD? -``` +### November 7, 2025 -``` -Send 10 USDT to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7 on ethereum -``` +**Changes** -Write operations (sending, swapping, bridging) will show a **confirmation dialog** before executing. You must explicitly approve each transaction. +* **wallet-evm-erc-4337**: Fixed destructuring of user operation in `getTransactionReceipt()` ([v1.0.0-beta.3](https://github.com/tetherto/wdk-wallet-evm-erc-4337/releases/tag/v1.0.0-beta.3)) +* **wallet-ton**: Replaced UUID-based message body with seqno/queryId for TON transfers, downgraded `@ton/ton` to 15.1.0 for stability ([v1.0.0-beta.5](https://github.com/tetherto/wdk-wallet-ton/releases/tag/v1.0.0-beta.5)) *** -## Optional Capabilities +## How to Stay Updated -Add more capabilities by installing additional packages and enabling them on the server: +* Check this page for the latest updates +* Join our [Discord community](https://discord.gg/arYXDhHB2w) for real-time announcements +* Star and follow the [GitHub repositories](https://github.com/orgs/tetherto/repositories?q=wdk) for detailed release notes -```javascript title="Additional capabilities" -import from '@tetherto/wdk-mcp-toolkit' -import VeloraProtocolEvm from '@tetherto/wdk-protocol-swap-velora-evm' -import Usdt0ProtocolEvm from '@tetherto/wdk-protocol-bridge-usdt0-evm' -import AaveProtocolEvm from '@tetherto/wdk-protocol-lending-aave-evm' -import MoonPayProtocol from '@tetherto/wdk-protocol-fiat-moonpay' -// Indexer - transaction history -server.useIndexer() +# Partner with WDK (/overview/partner-program) -// DeFi protocols -server.registerProtocol('ethereum', 'velora', VeloraProtocolEvm) -server.registerProtocol('ethereum', 'usdt0', Usdt0ProtocolEvm) -server.registerProtocol('ethereum', 'aave', AaveProtocolEvm) -server.registerProtocol('ethereum', 'moonpay', MoonPayProtocol, ) -// Register the corresponding tools -server.registerTools([ - ...INDEXER_TOOLS, - ...SWAP_TOOLS, - ...BRIDGE_TOOLS, - ...LENDING_TOOLS, - ...FIAT_TOOLS -]) -``` -*** +Build with WDK alongside Tether. Whether you're integrating WDK into your product or extending the ecosystem with new capabilities, we have a partnership track designed for you. -## Environment Variables +WDK is built to be open and extensible, but we know that building great products often takes more than just great documentation. We offer a selected group of partners a direct connection with Tether's engineering and product teams so you can ship faster, with confidence. We offer 3 partnership tracks depending on how you plan to work with WDK. -| Variable | Required | Description | -| --- | --- | --- | -| `WDK_SEED` | Yes | BIP-39 seed phrase for wallet derivation | -| `WDK_INDEXER_API_KEY` | No | Enables `INDEXER_TOOLS` - [get a key](../../tools/indexer-api/get-started/#request-api-key) | -| `MOONPAY_API_KEY` | No | Enables `FIAT_TOOLS` - [MoonPay Dashboard](https://dashboard.moonpay.com/) | -| `MOONPAY_SECRET_KEY` | No | Required with `MOONPAY_API_KEY` | +* [Project Partners](#project-partners) +* [WDK Tech Contributors](#wdk-tech-contributors) +* [Consulting & Implementation Partners (Alpha)](#consulting--implementation-partners-alpha) *** -## Next Steps - -* [**Configuration**](configuration) - Wallets, tokens, protocols, custom tools, and security -* [**API Reference**](api-reference) - All 35 built-in MCP tools with parameters and schemas +## Project Partners -*** +Integrate WDK more confidently, with direct access to Tether's engineering team and WDK solutions architects. Project Partners approved for Tether-supported implementations will benefit from: -## Need Help? -## LangChain Integration -URL: https://docs.wdk.tether.su/ai/mcp-toolkit/langchain -Description: Use WDK MCP tools in LangChain agents with zero-config server startup -You can use the WDK MCP Toolkit as a tool provider for [LangChain](https://www.langchain.com/) agents in both Python and TypeScript. LangChain's `MultiServerMCPClient` spawns the MCP server as a subprocess and converts WDK tools into LangChain-compatible tools, giving your agent access to wallet operations, pricing, swaps, bridges, lending, and more. +* Access to a WDK Solutions Architect to discuss product-specific implementation strategies +* Custom integration assistance +* Privileged support channel +* WDK roadmap visibility +* Early access to APIs and SDKs +* Direct access to WDK product and engineering core team -This integration uses the `serve` CLI command, which starts a fully configured MCP server on stdio with no server script required. +### Is it for you? -This approach uses LangChain's MCP adapters to connect to the WDK MCP server. WDK does not ship a native LangChain integration, it leverages the standard MCP protocol that LangChain already supports. +Project Partners are companies and teams building end-user products powered by WDK. You're a good fit for this track if you are: -**Want more control?** The `serve` command is the fastest way to get running, but you can also [write your own MCP server](get-started#manual-setup) with the programmatic API for full control over wallets, tools, and protocols. Then point LangChain's `MultiServerMCPClient` at it using `node your-server.js` instead of the `serve` command. +* A **fintech or neobank** building a wallet, payments app, or asset management platform and looking to leverage WDK as your underlying wallet infrastructure. +* An **exchange or trading platform** adding self-custodial wallet features for your users. +* A **messaging or social platform** integrating peer-to-peer payments or tipping functionality. +* A **remittance or cross-border payments provider** looking to use stablecoins and multi-chain support to serve your customers. +* An **enterprise or institutional player** that needs WDK integrated into internal treasury, compliance, or operations tooling. +* Any team that plans to **ship a product to end users** where WDK handles key management, transaction signing, or blockchain interactions under the hood. -*** +As a Project Partner, you get hands-on integration support from the team that builds WDK. We'll help you navigate architecture decisions, troubleshoot implementation challenges, and make sure your product launches on solid foundations. -## The `serve` Command +[Become a Project Partner](https://forms.monday.com/forms/6d484c4b34949e3a238988c47bf0a1b6?r=euc1) -The `serve` command provides zero-config MCP server startup so you don't need to write a server script: +*** -```bash title="Terminal" -npx @tetherto/wdk-mcp-toolkit serve -``` +## WDK Tech Contributors -Pass `WDK_SEED` to enable wallet operations, or omit it to run with pricing tools only: +Tap into the network of WDK adopters by developing modules and extensions for the WDK ecosystem. Technology partners approved as WDK Tech Contributors will benefit from: -```bash title="Terminal" -# With wallet operations -WDK_SEED="your twelve word seed phrase here" npx @tetherto/wdk-mcp-toolkit serve +* Build and publish WDK modules +* Visibility across WDK community and in WDK documentation +* Co-marketing opportunities +* Early access to APIs and SDKs +* Technical documentation collaboration -# Pricing-only mode (no seed required) -npx @tetherto/wdk-mcp-toolkit serve -``` +### Is it for you? -### Default Chains +Tech Contributors are protocol teams, service providers, and developer organizations building modules, plugins, or integrations that extend what WDK can do. You're a good fit for this track if you are: -By default, `serve` enables **three chains**: Ethereum, Arbitrum, and Bitcoin. For each enabled chain it dynamically imports the required wallet package and skips any that aren't installed. You can change the enabled set with the `WDK_CHAINS` environment variable. +* A **swap or DEX protocol** looking to provide liquidity and trading capabilities to WDK-powered wallets. +* A **bridge protocol** enabling cross-chain asset transfers that WDK wallets can access natively. +* An **on/off-ramp provider** connecting fiat currencies to the WDK ecosystem. +* A **lending or DeFi protocol** looking to make your services available directly within WDK wallets. +* A **hardware wallet or signing solution provider** building signer integrations for WDK. +* A **blockchain or L2 network** that wants first-class WDK wallet support for your chain. +* An **open-source developer or team** contributing new wallet modules, protocol integrations, or developer tooling to the WDK ecosystem. -### Built-in Registry +As a Tech Contributor, you'll work closely with our SDK team to build, test, and publish modules that reach every WDK-powered wallet. You'll get early access to unreleased APIs, architecture guidance, co-marketing exposure through our documentation and community channels, and the opportunity to shape how your protocol integrates across the ecosystem. -The command has built-in definitions for 13 chains and 4 protocol modules. When a chain is enabled and its package is installed, the wallet is registered automatically. Protocol modules are also auto-registered when their packages are installed and at least one of their target chains is enabled. +[Become a Technology Partner](https://tether.to/en/partner-with-us/) -| Module | Registers | Default | -| --- | --- | --- | -| [`@tetherto/wdk-wallet-evm`](/sdk/wallet-modules/wallet-evm) | Ethereum, Arbitrum, Polygon, Optimism, Base, Avalanche, BNB, Plasma, Spark | Ethereum + Arbitrum enabled | -| [`@tetherto/wdk-wallet-btc`](/sdk/wallet-modules/wallet-btc) | Bitcoin | Enabled | -| [`@tetherto/wdk-wallet-solana`](/sdk/wallet-modules/wallet-solana) | Solana | Not enabled by default | -| [`@tetherto/wdk-wallet-ton`](/sdk/wallet-modules/wallet-ton) | TON | Not enabled by default | -| [`@tetherto/wdk-wallet-tron`](/sdk/wallet-modules/wallet-tron) | Tron | Not enabled by default | -| [`@tetherto/wdk-protocol-swap-velora-evm`](/sdk/swap-modules/swap-velora-evm) | Swap tools (Ethereum, Arbitrum) | -- | -| [`@tetherto/wdk-protocol-bridge-usdt0-evm`](/sdk/bridge-modules/bridge-usdt0-evm) | Bridge tools (Ethereum, Arbitrum) | -- | -| [`@tetherto/wdk-protocol-lending-aave-evm`](/sdk/lending-modules/lending-aave-evm) | Lending tools (Ethereum) | -- | -| [`@tetherto/wdk-protocol-fiat-moonpay`](/sdk/fiat-modules/fiat-moonpay) | Fiat tools (Ethereum) | Requires `MOONPAY_*` env vars | +*** -Missing packages are silently skipped. Install only the modules you need and `serve` will pick them up. For chains or protocols **not** in the built-in registry, use a [custom config file](#custom-config-file). +## Consulting & Implementation Partners (Alpha) -*** +Consulting companies, agencies, and systems integrators building wallet solutions with WDK for their clients. Approved Consulting & Implementation Partners will benefit from: -## Quick Start +* **Being part of Tether's partner ecosystem** +* Access to a WDK Solutions Architect to discuss product-specific implementation strategies for your clients +* Custom integration assistance +* Direct access to WDK product and engineering core team +* Privileged support channel +* WDK roadmap visibility +* Early access to APIs and SDKs +* Co-marketing support -#### Install dependencies +### Is it for you? -```bash title="Terminal" -pip install langchain-mcp-adapters langgraph langchain-openai -``` +Consulting & Implementation Partners are agencies, system integrators, and software houses that would like to deliver WDK-powered solutions on behalf of their clients. You're a good fit for this track if you are: -#### Create your agent +* A **system integrator** helping enterprise clients adopt blockchain and digital asset infrastructure. +* A **software development agency** building custom wallet or payment applications. +* A **blockchain consultancy** advising companies on self-custodial wallet strategy and architecture. +* A **digital transformation firm** integrating stablecoin payments into existing client platforms. +* A **managed services provider** offering ongoing support and maintenance for WDK-based deployments. -```python title="agent.py" -import asyncio -from langchain_mcp_adapters.client import MultiServerMCPClient -from langgraph.prebuilt import create_react_agent -from langchain_openai import ChatOpenAI +As a Consulting & Implementation Partner, you'll gain access to Tether's referral network, dedicated technical support for your client engagements. We'll equip your team with the training, documentation, and direct engineering access needed to deliver successful WDK implementations at scale. -async def main(): - client = MultiServerMCPClient({ - "wdk": { - "transport": "stdio", - "command": "npx", - "args": ["-y", "@tetherto/wdk-mcp-toolkit", "serve"], - "env": , - } - }) + + **Alpha Program** - This partnership track is currently in alpha. We're onboarding a limited number of partners as we shape the program and cannot guarantee acceptance, specific benefits, or program terms at this stage. Apply to express your interest and help shape the program as it evolves. + - tools = await client.get_tools() - agent = create_react_agent(ChatOpenAI(model="gpt-4o"), tools) +[Become a Consulting & Implementation Partner](https://tether.to/en/partner-with-us/) - result = await agent.ainvoke({ - "messages": [] - }) - print(result["messages"][-1].content) - await client.close() +# Showcase (/overview/showcase) -asyncio.run(main()) -``` -#### Run it -```bash title="Terminal" -export OPENAI_API_KEY="sk-..." -python agent.py -``` -#### Install dependencies -```bash title="Terminal" -npm install @langchain/mcp-adapters @langchain/langgraph @langchain/core @langchain/openai -``` + + Showcase projects are developed and maintained independently by third-party contributors. -#### Create your agent + Tether and the WDK Team do not endorse or assume responsibility for their code, security, or maintenance. Use your own judgment and proceed at your own risk. + -```typescript title="agent.ts" -import from "@langchain/mcp-adapters"; -import from "@langchain/langgraph/prebuilt"; -import from "@langchain/openai"; + + Looking for community-built WDK modules you can install and use in your project? Check out the [Community Modules](../sdk/community-modules/) page instead. + -const client = new MultiServerMCPClient({ - wdk: { - transport: "stdio", - command: "npx", - args: ["-y", "@tetherto/wdk-mcp-toolkit", "serve"], - env: , - }, -}); +## Featured Projects -const tools = await client.getTools(); -const agent = createReactAgent({ - llm: new ChatOpenAI(), - tools, -}); +*** -const result = await agent.invoke({ - messages: [ - , - ], -}); +### wdk-starter-browser-extension -console.log(result.messages[result.messages.length - 1].content); -await client.close(); -``` +> Self-custodial browser extension wallet starter built on WDK. -#### Run it +**Author:** Base58 ([Website](https://base58.io/), [GitHub](https://github.com/base58-io)) / alexszolowicz ([GitHub](https://github.com/alexszolowicz-blockether)) +**Repository:** [github.com/base58-io/wdk-starter-browser-extension](https://github.com/base58-io/wdk-starter-browser-extension) -```bash title="Terminal" -export OPENAI_API_KEY="sk-..." -npx tsx agent.ts -``` +A browser extension starter kit that demonstrates how to build a self-custodial wallet using WDK. Provides a ready-made template for creating Chrome-compatible extension wallets with secure key management and transaction signing. -**Security** -- Always use a dedicated development wallet with limited funds. Set `WDK_MCP_ELICITATION` to `"false"` for programmatic agents since elicitation dialogs require a human in the loop. +wdk-starter-browser-extension demo *** -## Configuration +### wdk-wallet-evm-x402-facilitator -### Environment Variables +> x402 payment facilitator adapter for WDK EVM wallets. -Control `serve` behavior through environment variables: +**Author:** SemanticPay ([Website](https://www.semanticpay.io/), [GitHub](https://github.com/SemanticPay)) +**Repository:** [github.com/SemanticPay/wdk-wallet-evm-x402-facilitator](https://github.com/SemanticPay/wdk-wallet-evm-x402-facilitator) -| Variable | Required | Default | Description | -| --- | --- | --- | --- | -| `WDK_SEED` | No | -- | BIP-39 seed phrase. If omitted, only pricing tools are available | -| `WDK_CHAINS` | No | `ethereum,arbitrum,bitcoin` | Comma-separated list of chains to enable | -| `WDK_MCP_ELICITATION` | No | `true` | Set to `"false"` for programmatic agents that cannot handle confirmation dialogs | -| `WDK_RPC_\` | No | Built-in defaults | Override the RPC endpoint for a chain (e.g. `WDK_RPC_ETHEREUM=https://my-rpc.com`) | -| `WDK_CONFIG` | No | -- | Path to a `wdk.config.json` file for custom chains and protocols | -| `WDK_INDEXER_API_KEY` | No | -- | Enables indexer tools for balance and transfer history queries | -| `MOONPAY_API_KEY` | No | -- | Enables fiat on/off-ramp tools | -| `MOONPAY_SECRET_KEY` | No | -- | Required with `MOONPAY_API_KEY` | +An adapter that enables WDK EVM wallets to act as x402 payment facilitators. Bridges the WDK wallet interface with the x402 HTTP payment protocol, allowing servers to charge for API access using on-chain payments. -### Custom Config File +*** -For chains or protocols not in the built-in defaults, create a `wdk.config.json` and pass its path via `WDK_CONFIG`: +### x402-usdt0 -```bash title="Terminal" -WDK_CONFIG=./wdk.config.json WDK_SEED="..." npx @tetherto/wdk-mcp-toolkit serve -``` +> End-to-end x402 reference implementation on Plasma with USDT0 and WDK. -```json title="wdk.config.json" -{ - "chains": { - "zksync": { - "module": "@myorg/wdk-wallet-zksync", - "config": - }, - "ethereum": { - "config": - } - }, - "protocols": [ - - ], - "enabledChains": ["ethereum", "zksync", "bitcoin"] -} -``` +**Author:** baghdadgherras ([GitHub](https://github.com/baghdadgherras)) +**Repository:** [github.com/baghdadgherras/x402-usdt0](https://github.com/baghdadgherras/x402-usdt0) -| Field | Description | -| --- | --- | -| `chains` | Add new chains or override config for built-in ones. New chains require a `module` field; overrides for existing chains can omit it | -| `protocols` | Add custom protocols. Each entry requires `module`, `label`, and `chains`. The `type` field (`swap`, `bridge`, `lending`, `fiat`) maps to the corresponding built-in tool set | -| `enabledChains` | Overrides `WDK_CHAINS` env var. If omitted, `WDK_CHAINS` is used | +A complete reference implementation demonstrating the x402 HTTP payment protocol using USDT0 on the Plasma network. Includes both client and server components, showcasing how WDK wallets can facilitate machine-to-machine payments in a real-world setup. *** -## LLM Provider Support - -Both the Python and TypeScript examples support OpenAI and Anthropic. Set the corresponding environment variable and install the matching package: +### wdk-mcp -| Provider | Environment Variable | Python Package | TypeScript Package | -| --- | --- | --- | --- | -| OpenAI | `OPENAI_API_KEY` | `langchain-openai` | `@langchain/openai` | -| Anthropic | `ANTHROPIC_API_KEY` | `langchain-anthropic` | `@langchain/anthropic` | +> AI-powered blockchain operations via Model Context Protocol. -The examples auto-detect which provider to use based on which API key is set. If both are set, OpenAI takes priority. +**Author:** Seven ([GitHub](https://github.com/rezerov)) +**Repository:** [github.com/rezerov/wdk-mcp](https://github.com/rezerov/wdk-mcp) -**Full examples** -- See the complete interactive agent examples with conversation loops on GitHub: [`examples/langchain/python/`](https://github.com/tetherto/wdk-mcp-toolkit/tree/main/examples/langchain/python) and [`examples/langchain/typescript/`](https://github.com/tetherto/wdk-mcp-toolkit/tree/main/examples/langchain/typescript). +Integrates WDK capabilities within the MCP (Model Context Protocol) ecosystem, allowing AI Agents to perform blockchain operations such as signing, transactions, and wallet interactions securely and locally. This project expands the reach of WDK to autonomous systems and AI-driven workflows. *** -## Need Help? -## OpenClaw (Community Skill) -URL: https://docs.wdk.tether.su/ai/openclaw -Description: Give your OpenClaw AI agent a self-custodial WDK wallet in minutes -The WDK skill for OpenClaw is a community skill, developed and maintained independently by a third-party contributor. +## Submit Your Project -Tether and the WDK Team do not endorse or assume responsibility for its code, security, or maintenance. Use your own judgment and proceed at your own risk. Artificial intelligence has inherent risks and limitations. You assume full responsibility for any reliance and use of artificial intelligence and agree that any such reliance and use is entirely at your own risk. +If you've built something using WDK, we'd love to showcase it. -[OpenClaw](https://openclaw.ai) is an open-source AI agent platform. With the WDK community skill, your OpenClaw agent can create wallets, send transactions, swap tokens, bridge assets, and interact with DeFi protocols. Everything stays self-custodial. +Projects listed here should: -The WDK community skill follows the [AgentSkills specification](https://agentskills.io/specification), so it works with any compatible agent platform. This page covers the OpenClaw-specific setup. +* Use one or more WDK modules or SDKs +* Be open source or publicly accessible +* Include a clear README and installation instructions -## Install the WDK Community Skill +Your work may be featured in future updates, social posts, or documentation spotlights. -Install from [ClawHub](https://clawhub.ai/HumanRupert/tether-wallet-development-kit): +Share it with us through the community form or the showcase channel below. -```bash -npx clawhub install tether-wallet-development-kit -``` + -This installs the skill into your workspace's `skills/` directory. OpenClaw picks it up automatically on the next session. -You might see a VirusTotal warning during installation. It flags the skill as suspicious because it handles crypto keys and calls external APIs. This is normal for any wallet SDK skill, nevertheless review the skill's source code on [ClawHub](https://clawhub.ai/HumanRupert/tether-wallet-development-kit) before proceeding. +# Get Support (/overview/support) -We plan to publish the official WDK skill to its own GitHub repository. Once that's live, you'll also be able to install via `git clone`. -## Configuration -The WDK community skill does not require environment variables. Your agent will ask for a seed phrase in conversation when it needs to create or recover a wallet. The skill passes the seed phrase as a constructor parameter in code rather than reading it from configuration. + -Your seed phrase controls real funds. Never share it, commit it to version control, or expose it in logs. The skill instructs agents to never log or expose seed phrases or private keys. +We're here to help you succeed with WDK. Don't hesitate to reach out. -## Verify It Works -Start a new OpenClaw session and try a simple prompt: +# Our Vision (/overview/vision) -``` -Create a multi-chain wallet with Ethereum and Bitcoin support, then show me the addresses. -``` -The agent should use the WDK community skill to create wallet accounts and return the generated addresses. All write operations (transactions, swaps, bridges) require your explicit confirmation before executing. -![OpenClaw creating a multi-chain wallet using the WDK skill](/assets/openclaw-wallet-output.png) +Imagine a world where humans, machines, and AI agents have the freedom to control their own finances. WDK is a fully open-source, self-custodial toolkit designed to be modular, independent, resilient and infinitely scalable, enabling trillions of wallets. -*Example output from the WDK skill creating a multi-chain wallet* +*** -## What Your Agent Can Do +### **Universal Unstoppable Access** -Once the skill is loaded, your agent can: +Anyone should be able to build, deploy or use a wallet and manage assets without friction or gatekeepers. Whether you're an independent developer, a startup, a corporation, an AI, or even a nation-state, WDK provides the open technology to create hyper-secure self-custodial wallets without barriers. -- **Create wallets** across 20+ blockchains (EVM, Bitcoin, Solana, TON, Tron, Spark) -- **Send transactions** and token transfers -- **Swap tokens** via DEX aggregators (Velora, StonFi) -- **Bridge assets** cross-chain with USDT0 -- **Lend and borrow** through Aave V3 -- **Buy and sell crypto** via MoonPay fiat on/off-ramps +### **Ubiquitous Deployment** -For the full list of capabilities and how skills work, see [Agent Skills](agent-skills). +Wallets need to run everywhere. Through Bare runtime compatibility, WDK can live and evolve on any embedded device, mobile apps, desktop applications, IoT devices, servers, and even autonomous systems. From smartphones to smart fridges, from trading bots to spaceships — WDK enables financial sovereignty across all environments. -## Security Risks and Safety Precautions +### **AI-Native Architecture** -OpenClaw is powerful because it runs on your system and can take real actions like creating files, fetching data from the web, and executing transactions. That same power can become a security risk if you're not careful about how and where you run it. +In a world where AI agents and robots are becoming autonomous and will permeate every single part of our lives, the machines need to have access and self-manage their own resources. WDK is the preferred choice for the digital entities of tomorrow, ensuring direct custody of funds, highly scalable transactions, and empowering the infinite AI economy of the future. -This isn't a flaw in OpenClaw. It's what happens when you give any AI agent direct system access. Knowing these risks lets you use OpenClaw safely. +*** -### Why running OpenClaw locally requires caution +## A world of opportunities -When you run OpenClaw on your own computer or a virtual server, you're allowing a chat interface to trigger actions on that system. This is a concern if your bot: + + + WDK enables a future with millions of wallets built on top of it, each tailored to specific needs and use cases + -- Has access to sensitive directories -- Runs with elevated privileges -- Is connected to a publicly accessible chat -- Receives poorly scoped instructions + + WDK enables trillions of AI agents to have their own wallet, managing resources autonomously in the digital economy + -It can unintentionally modify files, overwrite data, or expose information you didn't intend to share. The risk isn't that OpenClaw is malicious. The risk is that it will do exactly what it's told, even when the instruction is vague or unsafe. + + Any developer, company, organization, or country can build their own white-label wallet and manage their assets independently + -### How to use OpenClaw safely + + From IoT devices to autonomous vehicles, every connected device can have its own wallet and financial identity + + -To reduce risk, here are some practical safety measures: +*** -- Run OpenClaw as a non-privileged user -- Keep its working files in a dedicated directory -- Avoid connecting it to public or shared chats initially -- Be explicit when asking it to read or write files -- Test new capabilities on a disposable system or VM +## Let's build this future together -Think of OpenClaw the same way you'd think about running scripts on your system: powerful and useful, but something you need to be careful with. +WDK is more than a development kit—it's the foundation for a new era of financial sovereignty. By making wallet technology accessible, ubiquitous, and AI-native, we're enabling a world where: -### Inherent Limitations of Artificial Intelligence +* **Developers** can focus on innovation rather than infrastructure +* **Users** maintain complete control over their digital assets +* **AI Agents** can operate autonomously in the digital economy +* **Organizations** can build custom financial solutions without compromise +* **Society** benefits from more secure, efficient, and accessible financial infrastructure -OpenClaw makes use of artificial intelligence and machine learning technologies. While the use of artificial intelligence and machine learning enables capabilities, it also involves inherent limitations and risks. These include: +Join us in building this future. The tools are open-source, the vision is clear, and the possibilities are limitless. -1. The potential for inaccurate, incomplete, unexpected or misleading outputs or actions (including so-called hallucinations) -2. The risk that outputs or actions may contain biases -3. The possibility of errors related to document quality or text recognition of inputs -4. The possibility that the outputs may suggest specific immediate or near term actions that should not be relied upon -5. The risk that OpenClaw may take unexpected actions (including the sending of assets) +*** -## Next Steps +Ready to start building? Explore our [getting started guide](../start-building/nodejs-bare-quickstart) or dive into our [SDK documentation](../sdk/get-started). -- [Agent Skills](agent-skills) - Full capabilities, how skills work, and a comparison with other agentic wallet solutions -- [MCP Toolkit](mcp-toolkit/) - Programmatic wallet access for MCP-compatible agents -- [OpenClaw Skills Documentation](https://docs.openclaw.ai/tools/skills) - How OpenClaw discovers and loads skills -*** +# Concepts & Definitions (/resources/concepts) -## Need Help? -## x402 -URL: https://docs.wdk.tether.su/ai/x402 -Description: Accept and make instant USD₮ payments over HTTP using WDK self-custodial wallets -## What Is x402? -[x402](https://www.x402.org) is an open payment protocol, [originally developed by Coinbase](https://docs.x402.org/), that gives the long-reserved [HTTP 402 Payment Required](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/402) status code a concrete, blockchain-native meaning: if you want this resource, pay for it. No accounts, API keys, or checkout flows. Just plain HTTP. -This matters for AI agents because they need to pay for resources programmatically. x402 makes payment a first-class part of the web stack, so an agent can discover a price, sign a payment, and receive a resource in a single request-response cycle. +## Account Abstraction -### The Three Roles +Account Abstraction is a blockchain technology that separates the concept of a user account from the mechanism of transaction validation and fee payment. In traditional blockchain systems, users must pay transaction fees in the native token of the blockchain (like ETH on Ethereum). Account Abstraction allows users to pay fees in other tokens or have fees sponsored by third parties, enabling gasless transactions and enhanced user experiences. -| Role | Description | -| --- | --- | -| **Client (Buyer)** | The entity requesting a paid resource. Can be a human application, an AI agent, or any service with a wallet. | -| **Resource Server (Seller)** | The API or service providing the paid resource. Defines payment requirements and returns `402` for unpaid requests. | -| **Facilitator** | An intermediary that verifies payment signatures and submits transactions on-chain. Never holds funds, only executes signed authorizations. | +### WDK Implementation -### How the Protocol Works +WDK provides Account Abstraction support through specialized wallet modules: -#### Client requests a resource +* `@tetherto/wdk-wallet-evm-erc4337` - EVM chains with ERC-4337 standard +* `@tetherto/wdk-wallet-ton-gasless` - TON blockchain with gasless transactions +* `@tetherto/wdk-wallet-tron-gasfree` - TRON blockchain with gas-free transactions -A standard HTTP request. `GET`, `POST`, whatever your API expects. +These modules allow developers to implement gasless transaction flows where users can pay fees in tokens like USD₮ or XAU₮ instead of native blockchain tokens. -#### Server responds with 402 Payment Required +## ERC-4337 -The response body describes what to pay: amount, token, network, and recipient address. +ERC-4337 is an Ethereum standard that enables Account Abstraction without requiring changes to the Ethereum protocol itself. It introduces a new transaction type called "UserOperation" that allows smart contract wallets to handle transaction validation and fee payment logic through components like EntryPoint contracts, Bundlers, and Paymasters. -```json -{ - "x402Version": 1, - "accepts": [] -} -``` +## Gasless Transactions -#### Client signs a payment +Gasless transactions allow users to perform blockchain operations without holding native tokens for gas fees. Instead, transaction fees are paid by third-party services or in alternative tokens, enabling new user onboarding, cross-chain operations, and corporate applications where companies can sponsor employee transactions. -The client constructs an [EIP-3009](https://eips.ethereum.org/EIPS/eip-3009) `transferWithAuthorization` and signs it with their wallet. No tokens leave the wallet yet. It's a signed intent, not a transfer. +## Paymaster Services -#### Client retries with payment header +Paymaster services are third-party providers that sponsor transaction fees on behalf of users. They accept payment in various tokens and handle the conversion and payment of gas fees to the blockchain network, providing fee estimation, gas optimization, and high transaction success rates. -The signed payload goes in the `X-PAYMENT` header on the same request. +## Safe Accounts -#### Facilitator verifies +Safe Accounts are smart contract wallets built on the Safe protocol that provide enhanced security features and multi-signature capabilities. In the context of ERC-4337, Safe Accounts can be used as the underlying wallet implementation, combining the security benefits of multi-signature with the flexibility of Account Abstraction for enterprise, family, and institutional use cases. -The server forwards the payload to the facilitator's `/verify` endpoint. The facilitator checks that the signature is valid, the amount is sufficient, and the payer has funds. No money moves yet. +## BIP Standards -#### Server performs the work +BIP (Bitcoin Improvement Proposal) standards define common practices for Bitcoin and other blockchain wallets. WDK modules implement several key BIP standards for consistent wallet behavior across different blockchains. -Inference, database query, generation, whatever the resource requires. This only happens after verification succeeds. +### BIP-39 (Mnemonic Seed Phrases) -#### Facilitator settles on-chain +BIP-39 defines a standard for generating mnemonic seed phrases from random entropy. These phrases are human-readable and can be used to recover wallet private keys. WDK modules use BIP-39 for secure seed phrase generation and validation. -The server calls the facilitator's `/settle` endpoint. The facilitator submits the signed authorization on-chain, transferring tokens from buyer to seller. +### BIP-44 (Multi-Account Hierarchy) -#### Server returns the resource +BIP-44 defines a hierarchical deterministic wallet structure that allows creating multiple accounts from a single seed phrase. The derivation path format is `m/purpose'/coin_type'/account'/change/address_index`, where each module uses its specific coin type (e.g., 60 for Ethereum, 998 for Spark). -`200 OK` with the result in the body and a settlement receipt in the `X-PAYMENT-RESPONSE` header. +### BIP-84 (Native SegWit) -For the full protocol specification, see [x402.org](https://www.x402.org) and the [x402 GitHub repository](https://github.com/coinbase/x402). +BIP-84 defines the derivation path for native SegWit addresses (P2WPKH) in Bitcoin wallets. This standard provides better security and lower transaction fees compared to legacy Bitcoin addresses. -## How to Use x402 With WDK +## Lightning Network -WDK wallets work as drop-in signers for x402. `WalletAccountEvm` satisfies the client x402 signer interface directly. Self-custodial x402 payments on any EVM chain. +The Lightning Network is a second-layer payment protocol built on top of Bitcoin that enables instant, low-fee transactions. It works by creating payment channels between parties, allowing them to transact without broadcasting every transaction to the Bitcoin blockchain. -This guide walks through three things: +### Key Features -1. **Client (Buyer)** - Pay for x402-protected resources using a WDK wallet -2. **Server with Hosted Facilitator** - Accept x402 payments by delegating verification and settlement to a third-party facilitator -3. **Server with Self-Hosted Facilitator** - Run verification and settlement in-process using a WDK wallet, with no external dependencies +* **Instant Payments**: Transactions settle immediately within payment channels +* **Low Fees**: Minimal fees compared to on-chain Bitcoin transactions +* **Scalability**: Can handle millions of transactions per second +* **BOLT11 Invoices**: Standard format for Lightning payment requests -The x402 integration described on this page uses community-developed modules and third-party facilitator services. Tether does not endorse, operate, or assume legal or financial responsibility for any third-party facilitator. You are solely responsible for using any service. +### WDK Integration -Artificial intelligence and blockchain transactions carry inherent risks and limitations. +The Spark wallet module integrates Lightning Network functionality, allowing users to create and pay Lightning invoices directly from their Spark wallets. -### Recommended Chains +## Layer 2 Solutions -x402 with WDK works on any EVM chain where USD₮0 is deployed (see full list at [docs.usdt0.to](https://docs.usdt0.to/technical-documentation/deployments)). However, we recommend **Plasma** and **Stable** for x402 payments. Both chains are purpose-built for USD₮ transfers with near-instant finality and near-zero fees. Agents only need to hold USD₮. +Layer 2 solutions are protocols built on top of existing blockchains to improve scalability, reduce fees, and enhance transaction speed. They process transactions off the main blockchain and periodically settle to the base layer. -| Chain | CAIP-2 | RPC | USD₮0 Contract | Explorer | -| --- | --- | --- | --- | --- | -| **Plasma** | `eip155:9745` | `https://rpc.plasma.to` | `0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb` | [plasmascan.to](https://plasmascan.to/address/0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb) | -| **Stable** | `eip155:988` | `https://rpc.stable.xyz` | `0x779Ded0c9e1022225f8E0630b35a9b54bE713736` | [stablescan.xyz](https://stablescan.xyz/address/0x779Ded0c9e1022225f8E0630b35a9b54bE713736) | +### Types of Layer 2 ---- +* **Rollups**: Bundle multiple transactions and submit them as a single transaction to the main chain +* **State Channels**: Allow parties to transact off-chain and settle periodically +* **Sidechains**: Independent blockchains that connect to the main chain via bridges -## Client: Paying for Resources +### WDK Support -See the full working client example at [`x402/client.js`](https://github.com/SemanticPay/x402-usdt0-demo/blob/main/x402/client.js). +WDK modules support various Layer 2 solutions: -```bash -npm install @tetherto/wdk-wallet-evm @x402/fetch @x402/evm -``` +* **Spark**: Bitcoin Layer 2 with Lightning Network integration +* **EVM Rollups**: Support for Arbitrum, Optimism, and other EVM-compatible rollups -#### Create a wallet +## EVM (Ethereum Virtual Machine) -```javascript -import WalletManagerEvm from "@tetherto/wdk-wallet-evm"; +The Ethereum Virtual Machine is a runtime environment that executes smart contracts on Ethereum and other EVM-compatible blockchains. It provides a standardized way to run decentralized applications across different networks. -const account = await new WalletManagerEvm(process.env.SEED_PHRASE, ).getAccount(); -``` +### EVM-Compatible Chains -#### Register with x402 +Many blockchains are EVM-compatible, meaning they can run the same smart contracts and use the same tools as Ethereum: -`WalletAccountEvm` satisfies the `ClientEvmSigner` interface directly. No adapter needed. +* **Polygon**: Layer 2 scaling solution for Ethereum +* **BSC**: Binance Smart Chain +* **Arbitrum**: Optimistic rollup for Ethereum +* **Optimism**: Layer 2 scaling solution -```javascript -import from "@x402/fetch"; -import from "@x402/evm/exact/client"; +### WDK EVM Support -const client = new x402Client(); -registerExactEvmScheme(client, ); +The `@tetherto/wdk-wallet-evm` module works with any EVM-compatible blockchain, providing unified access to multiple networks through a single API. -const fetchWithPayment = wrapFetchWithPayment(fetch, client); -``` +## UTXO (Unspent Transaction Output) -#### Make a paid request +UTXO is a fundamental concept in Bitcoin and other UTXO-based blockchains. Each transaction consumes previous UTXOs and creates new ones, forming a chain of ownership. -`fetchWithPayment` intercepts any `402` response, signs an EIP-3009 authorization with your WDK wallet, and retries automatically. +### How UTXOs Work -```javascript -const response = await fetchWithPayment("https://api.example.com/weather", ); +1. **Inputs**: References to previous UTXOs that are being spent +2. **Outputs**: New UTXOs created by the transaction +3. **Change**: Remaining value returned to the sender as a new UTXO -const data = await response.json(); -console.log("Response:", data); -``` +### WDK UTXO Management -Your seed phrase controls your funds. Never commit it to version control. Use environment variables or a secrets manager. +The Bitcoin wallet module automatically handles UTXO selection and change address management, ensuring optimal transaction construction and fee calculation. -### Getting USD₮0 on Plasma or Stable +## Seed Phrases and Private Keys -Before you can make x402 payments, your wallet needs USD₮0 on the target chain. If you hold USD₮ on Ethereum (or any supported EVM chain), bridge it using `@tetherto/wdk-protocol-bridge-usdt0-evm`. +Seed phrases and private keys are the foundation of wallet security in blockchain systems. -The bridge uses [LayerZero](https://layerzero.network) for secure cross-chain transfers. USD₮ on Ethereum is automatically converted to USD₮0 on the destination chain. +### Seed Phrases (BIP-39) -```bash -npm install @tetherto/wdk-wallet-evm @tetherto/wdk-protocol-bridge-usdt0-evm -``` +* **12-24 words**: Human-readable representation of wallet entropy +* **Deterministic**: Same seed phrase always generates the same keys +* **Recovery**: Can recover entire wallet from seed phrase +* **Security**: Must be kept secure and never shared -#### Bridge USD₮ from Ethereum to Plasma / Stable +### Private Keys -#### Create wallet and bridge protocol +* **256-bit numbers**: Cryptographic keys that control wallet funds +* **Derived from seed**: Generated deterministically from seed phrase +* **Signing**: Used to sign transactions and prove ownership +* **Memory safety**: WDK modules handle private keys securely with automatic cleanup -```javascript -import WalletManagerEvm from "@tetherto/wdk-wallet-evm"; -import Usdt0ProtocolEvm from "@tetherto/wdk-protocol-bridge-usdt0-evm"; +## Network Types -const account = await new WalletManagerEvm(process.env.SEED_PHRASE, ).getAccount(); +Blockchain networks come in different types for different use cases. -const bridge = new Usdt0ProtocolEvm(account, ); -``` +### Mainnet -#### Get a quote (recommended) +Production networks where real value is transacted: -```javascript -const USDT_ETHEREUM = "0xdAC17F958D2ee523a2206206994597C13D831ec7"; +* **Ethereum Mainnet**: Production Ethereum network +* **Bitcoin Mainnet**: Production Bitcoin network +* **Spark Mainnet**: Production Spark network -const quote = await bridge.quoteBridge(); +### Testnet -console.log("Total cost:", Number(quote.fee + quote.bridgeFee) / 1e18, "ETH"); -``` +Development networks for testing without real value: -#### Execute the bridge +* **Goerli/Sepolia**: Ethereum test networks +* **Bitcoin Testnet**: Bitcoin test network +* **Spark Testnet**: Spark test network -```javascript -const result = await bridge.bridge(); +### Regtest -console.log("Bridge tx:", result.hash); -``` +Local networks for development and testing: -USD₮0 arrives on the destination chain within a few minutes. +* **Local Ethereum**: Private Ethereum network +* **Bitcoin Regtest**: Local Bitcoin network +* **Spark Regtest**: Local Spark network -You can bridge from any of 25+ supported EVM chains, not just Ethereum. Point your wallet at the source chain's RPC and use the [USD₮ token address](https://tether.to/es/supported-protocols/) on that chain. See the full [bridge module documentation](../sdk/bridge-modules/bridge-usdt0-evm/). +### Testnet Funds & Faucets ---- +To test transactions without spending real assets, developers use "Testnets"—networks that mimic the main blockchain but use tokens with no monetary value. You can obtain these tokens for free from different publicly available "Faucets". Links to common "Faucets" are below. -## Server: Accepting Payments (Hosted Facilitator) + + The below faucets are for testnets. The USD₮ tokens and other tokens available at the links below are not real and do not entitle the holder to anything. In particular, they cannot be redeemed with Tether International, S.A. de C.V. ("Tether International") and are not Tether Tokens as described in [Tether International's Terms of Service](https://tether.to/en/legal). The USD₮ tokens available at the links below on various testnets are intended for testing WDK on the applicable testnet. The links below are links to third-party websites and are Third-Party Information as described in Tether Operations, S.A. de [C.V.'s Website Terms](https://tether.io/terms/). + -Your server delegates verification and settlement to a hosted facilitator. You never interact with the chain directly. +#### Common Faucets -**About the Semantic facilitator:** [Semantic](https://docs.semanticpay.io) operates a public USD₮-enabled x402 facilitator at `https://x402.semanticpay.io`. This is a third-party service not operated, endorsed, or guaranteed by Tether. +* **USD₮ Test Tokens (Sepolia)**: [Pimlico Faucet](https://dashboard.pimlico.io/test-erc20-faucet) +* **USD₮ Test Tokens (Sepolia)**: [Candide Faucet](https://dashboard.candide.dev/faucet) +* **Ethereum (Sepolia)**: [Google Cloud Web3 Faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia) +* **Aave Test Tokens (Sepolia)**: [Aave Faucet](https://app.aave.com/faucet/) — get test USD₮, DAI and other tokens for DeFi testing +* **TON Testnet**: [Testgiver Bot](https://t.me/testgiver_ton_bot) +* **Bitcoin Testnet**: [CoinFaucet](https://coinfaucet.eu/en/btc-testnet/) -The x402 protocol is an open standard. Anyone can build a facilitator or use one of their choice. -See the full working server example at [`x402/server.js`](https://github.com/SemanticPay/x402-usdt0-demo/blob/main/x402/server.js). +# All Modules (/sdk/all-modules) -```bash -npm install @tetherto/wdk-wallet-evm @x402/express @x402/evm @x402/core express dotenv -``` -#### Create the seller wallet -```javascript -import WalletManagerEvm from "@tetherto/wdk-wallet-evm"; +A comprehensive list of all available WDK modules. Each module is designed to be modular and can be used independently or combined with others. -const sellerAccount = await new WalletManagerEvm(process.env.SEED_PHRASE, ).getAccount(); +## Core Module -const sellerAddress = await sellerAccount.getAddress(); -``` +The orchestrator that manages all WDK modules. -#### Create the facilitator client +| Module | Description | Documentation | +| ------------------------------------------------------------ | ---------------------------------------- | ---------------------- | +| [`@tetherto/wdk-core`](https://github.com/tetherto/wdk-core) | Central orchestrator for all WDK modules | [Docs](./core-module/) | -```javascript -import from "@x402/core"; +## Wallet Modules -const facilitatorClient = new HTTPFacilitatorClient(); -``` +Wallet modules provide blockchain-specific wallet functionality for managing addresses, balances, and transactions. -#### Configure payment middleware +| Module | Blockchain | Description | Documentation | +| ------------------------------------------------------------------------------------------ | ---------- | ------------------------------------------------ | --------------------------------------------- | +| [`@tetherto/wdk-wallet-btc`](https://github.com/tetherto/wdk-wallet-btc) | Bitcoin | Bitcoin SegWit wallet with BIP-39/BIP-44 support | [Docs](./wallet-modules/wallet-btc/) | +| [`@tetherto/wdk-wallet-evm`](https://github.com/tetherto/wdk-wallet-evm) | EVM | Ethereum and EVM-compatible chains wallet | [Docs](./wallet-modules/wallet-evm/) | +| [`@tetherto/wdk-wallet-evm-erc4337`](https://github.com/tetherto/wdk-wallet-evm-erc-4337) | EVM | ERC-4337 Account Abstraction for EVM chains | [Docs](./wallet-modules/wallet-evm-erc-4337/) | +| [`@tetherto/wdk-wallet-ton`](https://github.com/tetherto/wdk-wallet-ton) | TON | TON blockchain wallet | [Docs](./wallet-modules/wallet-ton/) | +| [`@tetherto/wdk-wallet-ton-gasless`](https://github.com/tetherto/wdk-wallet-ton-gasless) | TON | Gasless transactions on TON | [Docs](./wallet-modules/wallet-ton-gasless/) | +| [`@tetherto/wdk-wallet-tron`](https://github.com/tetherto/wdk-wallet-tron) | TRON | TRON blockchain wallet | [Docs](./wallet-modules/wallet-tron/) | +| [`@tetherto/wdk-wallet-tron-gasfree`](https://github.com/tetherto/wdk-wallet-tron-gasfree) | TRON | Gas-free transactions on TRON | [Docs](./wallet-modules/wallet-tron-gasfree/) | +| [`@tetherto/wdk-wallet-solana`](https://github.com/tetherto/wdk-wallet-solana) | Solana | Solana blockchain wallet | [Docs](./wallet-modules/wallet-solana/) | +| [`@tetherto/wdk-wallet-spark`](https://github.com/tetherto/wdk-wallet-spark) | Spark | Spark/Lightning Bitcoin L2 wallet | [Docs](./wallet-modules/wallet-spark/) | -```javascript -import express from "express"; -import from "@x402/express"; -import from "@x402/evm/exact/server"; +## Swidge Modules -const PLASMA_NETWORK = "eip155:9745"; -const USDT0_PLASMA = "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb"; +Swidge modules provide one interface for providers that can quote and execute swap-only, bridge-only, or combined swap and bridge routes. -const app = express(); +No released swidge provider module is listed yet. See the [swidge protocol interface](./swidge-modules/) for the shared API shape provider modules should implement. -app.use( - paymentMiddleware( - { - "GET /weather": { - accepts: [ - { - scheme: "exact", - network: PLASMA_NETWORK, - price: { - amount: "1000", // $0.001 (6 decimals) - asset: USDT0_PLASMA, - extra: , - }, - payTo: sellerAddress, - }, - ], - description: "Weather data", - mimeType: "application/json", - }, - }, - new x402ResourceServer(facilitatorClient).register( - PLASMA_NETWORK, - new ExactEvmScheme(), - ), - ), -); -``` +## Swap Modules -The `extra` fields are passed to the buyer for EIP-712 signature construction. `name` and `version` must match what the on-chain USD₮0 contract expects. +DEX swap functionality for token exchanges. -#### Add your routes +| Module | Blockchain | Description | Documentation | +| ---------------------------------------------------------------------------------------------------- | ---------- | --------------------------------- | --------------------------------------- | +| [`@tetherto/wdk-protocol-swap-velora-evm`](https://github.com/tetherto/wdk-protocol-swap-velora-evm) | EVM | DEX aggregator swap on EVM chains | [Docs](./swap-modules/swap-velora-evm/) | -```javascript -// Gated - requires payment -app.get("/weather", (req, res) => { - res.json(); -}); +## Bridge Modules -// Not gated - no payment config -app.get("/health", (req, res) => { - res.json(); -}); +Cross-chain bridge functionality for token transfers between blockchains. -app.listen(4021); -``` +| Module | Route | Description | Documentation | +| ------------------------------------------------------------------------------------------------------ | ------------------- | --------------------------------------------------------------------- | ------------------------------------------ | +| [`@tetherto/wdk-protocol-bridge-usdt0-evm`](https://github.com/tetherto/wdk-protocol-bridge-usdt0-evm) | EVM → EVM + Non-EVM | USD₮0 bridging from EVM source chains to EVM and non-EVM destinations | [Docs](./bridge-modules/bridge-usdt0-evm/) | -Routes not listed in the middleware config behave like normal Express routes. +## Lending Modules -### Multi-Chain (Plasma + Stable) +DeFi lending and borrowing functionality. -To accept payments on both chains, add both networks to the `accepts` array and register both with the resource server. The buyer's client picks whichever network it has funds on. +| Module | Blockchain | Description | Documentation | +| ------------------------------------------------------------------------------------------------------ | ---------- | --------------------------------- | ------------------------------------------- | +| [`@tetherto/wdk-protocol-lending-aave-evm`](https://github.com/tetherto/wdk-protocol-lending-aave-evm) | EVM | Aave protocol integration for EVM | [Docs](./lending-modules/lending-aave-evm/) | -```javascript -const NETWORKS = { - plasma: , - stable: , -}; +## Fiat Modules -const resourceServer = new x402ResourceServer(facilitatorClient) - .register(NETWORKS.plasma.network, new ExactEvmScheme()) - .register(NETWORKS.stable.network, new ExactEvmScheme()); -``` +On-ramp and off-ramp functionality for fiat currency integration. -### Lifecycle Events +| Module | Provider | Description | Documentation | +| ---------------------------------------------------------------------------------------------- | -------- | ------------------------------------ | ------------------------------------ | +| [`@tetherto/wdk-protocol-fiat-moonpay`](https://github.com/tetherto/wdk-protocol-fiat-moonpay) | MoonPay | MoonPay integration for fiat on-ramp | [Docs](./fiat-modules/fiat-moonpay/) | -The Semantic facilitator supports an optional `X-Event-Callback` header. When provided, the facilitator POSTs real-time events to your callback URL during verification and settlement. +## Community Modules -| Type | When | Key Fields | -| --- | --- | --- | -| `verify_started` | Facilitator begins verifying | `details.network`, `details.checks` | -| `verify_completed` | Verification finished | `details.isValid` | -| `verify_failed` | Verification error | `details.error` | -| `settle_started` | Broadcasting on-chain transaction | `details.network` | -| `settle_completed` | Transaction confirmed | `details.transactionHash` | -| `settle_failed` | Settlement error | `details.error` | +Modules built by the WDK community. See the [Community Modules](./community-modules/) page for more details. -```javascript -const facilitatorClient = new HTTPFacilitatorClient({ - url: "https://x402.semanticpay.io/", - fetch: (url, init) => - fetch(url, { - ...init, - headers: , - }), -}); -``` +| Module | Blockchain | Description | Documentation | +| --------------------------------------------------------------------------- | ------------- | ------------------------------- | ---------------------------------------------------------- | +| [`@utexo/wdk-wallet-rgb`](https://github.com/UTEXO-Protocol/wdk-wallet-rgb) | Bitcoin (RGB) | RGB protocol wallet integration | [GitHub](https://github.com/UTEXO-Protocol/wdk-wallet-rgb) | -Events are fire-and-forget. If the callback URL is unreachable, events are silently dropped. ---- +# Get Started (/sdk/get-started) -## Server: Self-Hosted Facilitator (In-Process) -Instead of relying on a hosted facilitator, you can run verification and settlement in-process using the `@semanticio/wdk-wallet-evm-x402-facilitator` community module. This wraps a WDK wallet as an x402 `FacilitatorEvmSigner`. Your server handles the entire payment lifecycle locally. -Unlike the hosted Semantic facilitator (Plasma and Stable only), a self-hosted facilitator works with **any EVM chain where USD₮0 is deployed**. See the full deployment list at [docs.usdt0.to](https://docs.usdt0.to/technical-documentation/deployments). +The SDK is a comprehensive, modular plug-in framework designed to simplify multi-chain wallet development. -`@semanticio/wdk-wallet-evm-x402-facilitator` is a community module developed and maintained by [Semantic Pay](https://www.semanticpay.io). Tether does not endorse, audit, or assume responsibility for this module. It is currently in beta. Test thoroughly before using in production. +It is built on some core principles: **self-custodial and stateless** (private keys never leave your app and no data is stored by WDK), **unified interface** (consistent API across all blockchains), and **cross-platform compatibility** (works seamlessly from Node.js to React Native to embedded systems). -See the full working self-hosted server example at [`x402/server-inprocess.js`](https://github.com/SemanticPay/x402-usdt0-demo/blob/main/x402/server-inprocess.js). +#### Capabilities -```bash -npm install @semanticio/wdk-wallet-evm-x402-facilitator @tetherto/wdk-wallet-evm @x402/core @x402/evm @x402/express express dotenv -``` +* **Multi-Chain Support**: Bitcoin, Ethereum, TON, TRON, Solana, Spark, and more +* **Account Abstraction**: Gasless transactions on supported chains +* **DeFi Integration**: Plug-in support for swidge routes, swaps, bridges, and lending protocols +* **Extensible Design**: Add custom modules for new blockchains or protocols -#### Create the facilitator signer +*** -The facilitator wallet submits settlement transactions on-chain. It needs gas tokens on the target chain. +### Modular Architecture -```javascript -import WalletManagerEvm from "@tetherto/wdk-wallet-evm"; -import WalletAccountEvmX402Facilitator from "@semanticio/wdk-wallet-evm-x402-facilitator"; +WDK's architecture is built around the concept of composable modules. Each module is a specialized component that handles specific functionality, allowing you to build exactly what you need without unnecessary complexity. -const walletAccount = await new WalletManagerEvm(process.env.FACILITATOR_MNEMONIC, ).getAccount(); +Each module has a single responsibility. Wallet modules handle blockchain operations, protocol modules manage DeFi interactions, and the core module orchestrates everything. -const evmSigner = new WalletAccountEvmX402Facilitator(walletAccount); -``` +New functionality is added through modules rather than modifying core code. Also, modules are configured through simple objects, making them easy to customize for different environments and use cases. -The facilitator wallet and the seller wallet can use different seed phrases. The facilitator pays gas; the seller receives USD₮. The facilitator wallet must have enough native token to pay gas. +*** -#### Initialize the facilitator +#### Module Types -```javascript -import from "@x402/core/facilitator"; -import from "@x402/evm/exact/facilitator"; +WDK modules are organized into six main categories, each serving a specific purpose in the blockchain application stack: -const facilitator = new x402Facilitator() - .onAfterVerify(async (ctx) => ) - .onAfterSettle(async (ctx) => ); + + + Main orchestrator and shared utilities + -registerExactEvmScheme(facilitator, ); -``` + + Blockchain-specific wallet operations + -Available hooks: `onBeforeVerify`, `onAfterVerify`, `onBeforeSettle`, `onAfterSettle`. All are `async` and receive a context object with the payment payload and result. + + Swap-only, bridge-only, or combined asset routes + -#### Wire into Express + + Token swapping across DEXs + -Same `paymentMiddleware` pattern, but pass the in-process `facilitator` directly instead of an `HTTPFacilitatorClient`. + + Cross-chain asset transfers + -```javascript -import from "@x402/express"; -import from "@x402/evm/exact/server"; + + DeFi lending and borrowing + + -const NETWORK = process.env.NETWORK_ID || "eip155:9745"; -const USDT0 = process.env.USDT0_ADDRESS || "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb"; +*** -const resourceServer = new x402ResourceServer(facilitator).register( - NETWORK, - new ExactEvmScheme(), -); +### How to use the SDK -app.use( - paymentMiddleware( - { - "GET /weather": { - accepts: [{ - scheme: "exact", - network: NETWORK, - price: { amount: "1000", asset: USDT0, extra: }, - payTo: process.env.PAY_TO_ADDRESS, - }], - description: "Weather data", - mimeType: "application/json", - }, - }, - resourceServer, - ), -); -``` +The WDK SDK uses a registration-based system where modules are added to a central orchestrator. This creates a unified interface while maintaining module independence. ---- +#### Registration Flow -## Summary +**1. Core Module Initialization** -| Role | Packages | Notes | -| --- | --- | --- | -| **Buyer (Client)** | `@tetherto/wdk-wallet-evm`, `@x402/fetch`, `@x402/evm` | `WalletAccountEvm` satisfies `ClientEvmSigner` directly. | -| **Seller (Hosted)** | `@tetherto/wdk-wallet-evm`, `@x402/express`, `@x402/evm`, `@x402/core` | Delegates to a hosted facilitator. Semantic supports Plasma and Stable. | -| **Seller (Self-Hosted)** | `@tetherto/wdk-wallet-evm`, `@semanticio/wdk-wallet-evm-x402-facilitator`, `@x402/core`, `@x402/evm`, `@x402/express` | In-process facilitator. Any USD₮0 chain. | +```typescript title="Initialize WDK" +import WDK from '@tetherto/wdk' ---- +// Generate 24-word seed phrase for higher security +const seedPhrase = WDK.getRandomSeedPhrase(24) -## Resources +// Or use 12-word seed phrase (default) +// const seedPhrase = WDK.getRandomSeedPhrase() -- [x402 Protocol Spec](https://www.x402.org) - The open standard specification -- [x402 GitHub](https://github.com/coinbase/x402) - Reference implementations and examples -- [Semantic Facilitator Docs](https://docs.semanticpay.io) - API Reference for the hosted facilitator -- [Self-Hosted Facilitator Module](https://www.npmjs.com/package/@semanticio/wdk-wallet-evm-x402-facilitator) - Community in-process facilitator -- [x402-usdt0 Demo](https://github.com/SemanticPay/x402-usdt0-demo) - Full working buyer + seller demo -- [WDK EVM Wallet Module](../sdk/wallet-modules/wallet-evm/) - WDK EVM wallet documentation -- [USD₮0 Deployments](https://docs.usdt0.to/technical-documentation/deployments) - Contract addresses on all chains -- [EIP-3009 Specification](https://eips.ethereum.org/EIPS/eip-3009) - The authorization standard enabling gasless USD₮ transfers -## React Native Starter (Alpha) -URL: https://docs.wdk.tether.su/examples-and-starters/react-native-starter -Description: Multi-chain wallet starter built with WDK, Expo, and React Native -The React Native Starter Alpha is an Expo + React Native app showing how to build a multi-chain wallet using WDK via BareKit worklets and secure secret management. This starter includes wallet creation/import flows, balances, transactions, and a modular service layer. +const wdk = new WDK(seedPhrase) +``` -*** +**2. Wallet Module Registration** -**Prerequisites:** Node.js 22+, and either Xcode (iOS) or Android SDK API 29+ (Android). See the [React Native Quickstart](../start-building/react-native-quickstart#prerequisites) for details. +```typescript title="Register Wallets" +import WalletManagerEvm from '@tetherto/wdk-wallet-evm' +import WalletManagerBtc from '@tetherto/wdk-wallet-btc' -### Quickstart +const wdkWithWallets = wdk + .registerWallet('ethereum', WalletManagerEvm, { + provider: 'https://eth.drpc.org' + }) + .registerWallet('bitcoin', WalletManagerBtc, { + provider: 'https://blockstream.info/api' + }) +``` -Get your React Native wallet running in minutes with these simple steps: +**3. Protocol Module Registration** -#### Clone and Install +```typescript title="Register Protocols" +import SwapveloraEvm from '@tetherto/wdk-protocol-swap-velora-evm' -```bash -git clone https://github.com/tetherto/wdk-starter-react-native.git && cd wdk-starter-react-native && npm install +const wdkWithProtocols = wdkWithWallets + .registerProtocol('swap-velora-evm', SwapveloraEvm) ``` -#### Configure Environment +#### Unified Operations -```bash -cp .env.example .env -``` +Once registered, all modules work through the same interface: + +```typescript title="Unified Operations" +// Get accounts from different blockchains using the same method +const ethAccount = await wdkWithProtocols.getAccount('ethereum', 0) +const btcAccount = await wdkWithProtocols.getAccount('bitcoin', 0) -Get your free WDK Indexer API key [here](../tools/indexer-api/get-started) and add it to your `.env` file: +// Check balances using unified interface +const ethBalance = await ethAccount.getBalance() +const btcBalance = await btcAccount.getBalance() -```bash -EXPO_PUBLIC_WDK_INDEXER_BASE_URL=https://wdk-api.tether.io -EXPO_PUBLIC_WDK_INDEXER_API_KEY=your_actual_api_key_here -# Optional: For Tron network support -EXPO_PUBLIC_TRON_API_KEY=your_tron_api_key -EXPO_PUBLIC_TRON_API_SECRET=your_tron_api_secret +// Send transactions with consistent API +const ethTx = await ethAccount.sendTransaction({ + to: '0x...', + value: '1000000000000000000' +}) + +const btcTx = await btcAccount.sendTransaction({ + to: '1A1z...', + value: 100000000 +}) + +// Use DeFi protocols through the same interface +const swapResult = await wdkWithProtocols.executeProtocol('swap-velora-evm', { + fromToken: 'ETH', + toToken: 'USDT', + amount: '1000000000000000000' +}) ``` -#### Run Your App +*** + +### Creating Custom Modules -For first-time setup, generate native project files: +WDK's modular architecture makes it straightforward to add support for new blockchains or protocols. Each module type has a specific interface that must be implemented. -```bash -npx expo prebuild +#### Wallet Module Interface + +```typescript title="Custom Wallet Module Setup" +interface WalletModule { + // Account management + getAccount(index: number): Promise + getAddress(index: number): Promise + getBalance(index: number): Promise + + // Transaction operations + sendTransaction(params: TransactionParams): Promise + estimateTransaction(params: TransactionParams): Promise + + // Key management + signMessage(message: string, index: number): Promise + verifySignature(message: string, signature: string, address: string): Promise + + // Blockchain-specific operations + getTransactionHistory(index: number, limit?: number): Promise + getTokenBalance(index: number, tokenAddress: string): Promise +} ``` -Then run the app: +#### Protocol Module Interface -```bash -npm run ios # iOS Simulator -npm run android # Android Emulator +```typescript title="Custom Protocol Module Setup" +interface ProtocolModule { + // Protocol execution + execute(params: ProtocolParams): Promise + estimate(params: ProtocolParams): Promise + + // Supported operations + getSupportedTokens(): Promise + getSupportedChains(): Promise + getOperationTypes(): Promise + + // Protocol-specific methods + getLiquidityPools?(): Promise + getLendingRates?(): Promise + getBridgeRoutes?(): Promise +} ``` -*** +#### Module Implementation Example -**Need detailed instructions?** Check out the complete [React Native Quickstart](../start-building/react-native-quickstart) guide for step-by-step setup, configuration, and troubleshooting. +```typescript title="Custom Wallet Module Implementation" +class CustomWalletModule implements WalletModule { + private provider: string + private chainId: number -### Features + constructor(config: { provider: string; chainId: number }) { + this.provider = config.provider + this.chainId = config.chainId + } -**Multi-Token & Chain Support** -* **BTC**: Native SegWit transfers on Bitcoin network -* **USD₮**: Gasless transactions on EVM (Ethereum, Polygon, Arbitrum), native transfers on TON and Tron -* **XAU₮**: Gasless transactions on Ethereum network + async getAccount(index: number): Promise { + // Implement account derivation logic + const privateKey = await this.derivePrivateKey(index) + return new CustomAccount(privateKey, this.provider) + } -**Wallet Management** + async getAddress(index: number): Promise { + const account = await this.getAccount(index) + return account.getAddress() + } -* **Secure Seed Generation**: Cryptographically secure entropy generation -* **Seed Import**: Import existing 12-word mnemonic phrases -* **Encrypted Storage**: Secure key storage via [`@tetherto/wdk-secret-manager`](https://github.com/tetherto/wdk-secret-manager) -* **Multi-Account Support**: Derive multiple accounts from single seed + async getBalance(index: number): Promise { + const address = await this.getAddress(index) + // Implement balance fetching logic + const balance = await this.fetchBalance(address) + return new BigNumber(balance) + } -**Asset Management** + async sendTransaction(params: TransactionParams): Promise { + // Implement transaction sending logic + const account = await this.getAccount(params.accountIndex) + const tx = await account.sendTransaction(params) + return tx + } -* **Real-Time Balances**: Live balance updates via [WDK Indexer](../tools/indexer-api/) -* **Transaction History**: Complete transaction tracking and history via [WDK Indexer](../tools/indexer-api/) -* **Price Conversion**: Real-time fiat pricing via [Pricing Provider](../tools/price-rates/) + // Additional methods... +} +``` -**User Experience** +#### Module Registration -* **QR Code Scanner**: Scan addresses and payment requests via camera -* **Send/Receive Flows**: Intuitive transfer interfaces -* **Network Selection**: Choose optimal network for each transaction -* **Token Selection**: Multi-token transfer support -* **Activity Feed**: Real-time transaction monitoring +```typescript title="Custom Wallet Module Registration" +// Register your custom module +const wdkWithCustom = wdk.registerWallet('custom-chain', CustomWalletModule, { + provider: 'https://custom-rpc-endpoint.com', + chainId: 12345 +}) + +// Use it like any other module +const customAccount = await wdkWithCustom.getAccount('custom-chain', 0) +const balance = await customAccount.getBalance() +``` *** -### Project Structure +### Quickstart Paths -The starter includes a modular architecture designed for scalability and maintainability: +Ready to start building? Choose your development environment: -```text title="Project Structure" -src/ -├── app/ # Expo Router screens (file-based routing) -│ ├── onboarding/ # First-time user flows -│ ├── wallet-setup/ # Create/import wallet screens -│ ├── send/ & receive/ # Transaction flows -│ ├── settings.tsx # Configuration & preferences -│ └── token-details.tsx # Individual asset views -├── components/ # Reusable UI components -├── config/ # Network, asset, and chain settings -├── services/ # Business logic (pricing integration) -├── hooks/ # Custom React hooks -└── utils/ # Formatting & helper functions -``` + + + Get started with WDK in a Node.js environment + -Detailed project structure can be found in the [Github Repository](https://github.com/tetherto/wdk-starter-react-native/tree/main?tab=readme-ov-file#-project-structure). + + Build mobile wallets with React Native Expo + + *** -### Available Scripts +## Need Help? -| Script | Description | -| ------------------------ | --------------------------------------------- | -| `npm start` | Start Expo development server with dev client | -| `npm run android` | Run on Android emulator/device | -| `npm run ios` | Run on iOS simulator | -| `npm run web` | Start web development server | -| `npm run prebuild` | Generate native project files | -| `npm run prebuild:clean` | Clean and regenerate native project files | -| `npm run lint` | Run ESLint | -| `npm run lint:fix` | Fix ESLint errors | -| `npm run format` | Format code with Prettier | -| `npm run format:check` | Check code formatting | -| `npm run typecheck` | Run TypeScript type checking | - -*** - -### Technology Stack + -#### Core Technologies -* **Expo**: \~54.0.8 with development client -* **React Native**: 0.81.4 -* **React**: 19.1.0 -* **TypeScript**: \~5.9.2 -* **Reanimated**: \~4.1.0 -* **New Architecture**: Enabled +# Build with AI (/start-building/build-with-ai) -#### Build Configuration -* **Android**: minSdkVersion 29 -* **iOS**: Latest Xcode toolchain -* **Build Properties**: Configured via `expo-build-properties` -*** +WDK documentation is optimized for AI coding assistants. Give your AI tool context about WDK to get accurate code generation, architecture guidance, and debugging help. -### Next Steps +There are two ways to provide WDK context to your AI: -**Customizing the UI** +1. **[Connect via MCP Server](#connect-wdk-docs-via-mcp-server)** - Native support for the `.su` docs environment is still rolling out. +2. **[Connect via Markdown](#connect-wdk-docs-via-markdown)** - Works with any AI tool. Feed documentation directly into the context window. -This starter uses components from the [WDK React Native UI Kit](../ui-kits/react-native-ui-kit/). To customize the look and feel: + + **Want to give AI agents wallet access?** The [MCP Toolkit](../ai/mcp-toolkit/) creates an MCP server that exposes WDK wallets as tools - letting AI agents check balances, send transactions, swap tokens, and more. + -* [**Theming Guide**](../ui-kits/react-native-ui-kit/theming) - Deep dive into theming capabilities -* [**Component Reference**](../ui-kits/react-native-ui-kit/api-reference) - Complete component documentation +*** -**Add new functionality** +## Connect WDK Docs via MCP Server -This starter provides a solid foundation that you can extend with additional functionality: +The dedicated MCP endpoint for `docs.wdk.tether.su` is still being finalized. If you need environment-matched context on this preview site today, use the Markdown endpoints below instead. -* **Add support for other tokens** using wallet modules in the [WDK SDK](../sdk/get-started) -* **Add DeFi protocols** like swaps, bridges, and lending using [protocol modules](../sdk/get-started) + + The `.su` docs environment does not publish its own MCP server yet. Use `/llms.txt`, `/llms-full.txt`, or the raw `.md` page URLs from this environment until the endpoint is available. + -**Or explore documentation** + + **No MCP support?** You can feed WDK documentation directly into any AI tool as Markdown. See [Connect WDK Docs via Markdown](#connect-wdk-docs-via-markdown) below. + -* [**WDK SDK Documentation**](../sdk/get-started) - Learn about the underlying SDK -* [**UI Kit Documentation**](../ui-kits/react-native-ui-kit/get-started) - Customize the interface -* [**WDK Indexer**](../tools/indexer-api/) - Understand data fetching -* [**Secret Manager**](../tools/secret-manager/) - Learn about secure key management +### Add WDK Project Rules (Optional) -*** +Project rules give your AI assistant persistent context about WDK conventions, package naming, and common patterns. This is optional but recommended for teams working extensively with WDK. -## Need Help? -## About WDK -URL: https://docs.wdk.tether.su/overview/about -Description: Learn about the Wallet Development Kit and its capabilities -The **Wallet Development Kit _by Tether_ (WDK)** is Tether's open-source toolkit that empowers humans, machines and AI agents alike to build, deploy and use secure, multi-chain, self-custodial wallets that can be integrated anywhere from the smallest embedded device to any mobile, desktop and server operating system. +Copy the rules content below and save it at the file path for your tool. -A developer-first framework designed for maximum flexibility and scalability, powering anything from consumer wallets to wallet-enabled apps, DeFi integrations (lending, swaps, ...), IoT use cases, and AI agents. +#### Rules Content -Unlike closed solutions or SaaS-based wallet infrastructure providers, WDK offers zero lock-in and is designed for maximum flexibility and extensibility. It is modular, runs on Bare, Node.js and React-Native, thus can be embedded in a wide variety of environments. +```markdown +# WDK Development Rules -*** +## Package Structure +- All WDK packages are published under the `@tetherto` scope on npm +- Core module: `@tetherto/wdk` +- Wallet modules follow the pattern: `@tetherto/wdk-wallet-\` + - Examples: `@tetherto/wdk-wallet-evm`, `@tetherto/wdk-wallet-btc`, `@tetherto/wdk-wallet-solana`, `@tetherto/wdk-wallet-ton`, `@tetherto/wdk-wallet-tron`, `@tetherto/wdk-wallet-spark` +- Specialized wallet modules: `@tetherto/wdk-wallet-evm-erc4337`, `@tetherto/wdk-wallet-ton-gasless`, `@tetherto/wdk-wallet-tron-gasfree` +- Protocol modules follow the pattern: `@tetherto/wdk-protocol-\-\-\` + - Examples: `@tetherto/wdk-protocol-swap-velora-evm`, `@tetherto/wdk-protocol-bridge-usdt0-evm`, `@tetherto/wdk-protocol-lending-aave-evm` -## What Problems Does WDK Solve? +## Platform Notes +- For Node.js or Bare runtime: Use `@tetherto/wdk` as the orchestrator, then register individual wallet modules +- For React Native: You have two options: + - Use the React Native provider package for convenience (provides hooks and managed lifecycle) + - Or use WDK packages directly in the Hermes runtime - this works the same as Node.js integration -The current blockchain ecosystem is highly fragmented, with each blockchain requiring different SDKs, APIs, and integration approaches. This fragmentation creates significant barriers for developers who want to build truly seamless user-experiences that span across any blockchain, environment and use-case. +## Architecture +- WDK is modular - each blockchain and protocol is a separate npm package +- Wallet modules expose `WalletManager`, `WalletAccount`, and `WalletAccountReadOnly` classes +- `WalletAccount` extends `WalletAccountReadOnly` - it has all read-only methods plus write methods (sign, send) +- All modules follow a consistent pattern: configuration → initialization → usage -Traditional wallet development requires months of integration work. Developers must learn different standards, implement contrasting security practices, or rely on closed-source paid solutions which act as gatekeepers. +## Documentation +- Official docs: [docs.wdk.tether.su](/) +- For any WDK question, consult the official documentation before making assumptions +- API References, configuration guides, and usage examples are available for every module +``` -### **The Missing AI Foundation** +#### Where to Save -As we move toward a world where humans, machines and AI Agents need to manage digital assets safely, existing solutions fall short. AI agents will require wallets to interact in the financial infrastructure, and WDK wants to lay secure foundation that works for human, AI and IoT use cases. WDK enables trillions of self-custodial wallets. +| AI Coding Assistant | File Path | Notes | +| ------------------- | --------------------------------- | ---------------------------- | +| Cursor | `.cursor/rules/wdk.mdc` | Project-level, auto-attached | +| Claude Code | `CLAUDE.md` | Place in project root | +| Windsurf | `.windsurf/rules/wdk.md` | Project-level rules | +| GitHub Copilot | `.github/copilot-instructions.md` | Project-level instructions | +| Cline | `.clinerules` | Place in project root | +| Continue | `.continuerules` | Place in project root | *** -## Why WDK is Different - -Works with Node.js, Bare runtime, mobile (React Native), and future embedded environments +## Connect WDK Docs via Markdown -Pick only the modules you need; extend functionality with custom modules +If your AI tool doesn't support MCP, you can feed WDK documentation directly into the context window using these endpoints: -Clear SDK design, strong TypeScript typing, extensive docs, and ready-to-use starters +| Endpoint | URL | Description | +| ---------- | -------------------------------------------------- | ---------------------------------- | +| Page index | [docs.wdk.tether.su/llms.txt](/llms.txt) | Index of all page URLs and titles | +| Full docs | [docs.wdk.tether.su/llms-full.txt](/llms-full.txt) | Complete documentation in one file | -Stateless and self-custodial architecture ensures keys never leave user control +You can also append `.md` to any documentation page URL to get the raw Markdown, ready to paste into a chat context window. -Transparent, community-driven, and free to adopt with no vendor lock-in +*** -Maintained and supported by Tether with strong community involvement +## Agent Guidelines in WDK Repos -*** +Each WDK package repository includes an `AGENTS.md` file in its root. This file provides AI agents with context about the project structure, coding conventions, testing patterns, and linting rules. -## What WDK Provides +If your AI tool has access to the WDK source repositories (e.g., via a local clone), it will automatically ingest `AGENTS.md` for additional context beyond the documentation. -WDK combines four core components to deliver a complete wallet development solution: +*** -Unified APIs for wallet and protocol operations across multiple blockchains +## Example Prompt -Reliable blockchain data access for balances, transactions, and historical data +Here's an example prompt you can use to generate a multi-chain wallet with WDK. Try it with MCP connected or paste the relevant quickstart docs for best results: -Reusable React Native components for building wallet interfaces +``` +Create a Node.js app using WDK (@tetherto/wdk) that: +1. Creates a multi-chain wallet supporting Bitcoin and Polygon +2. Use @tetherto/wdk-wallet-btc for Bitcoin and @tetherto/wdk-wallet-evm for Polygon +3. Generates wallet addresses for both chains +4. Retrieves the balance for each address +5. Use a mnemonic from environment variables -Production-ready wallet templates and reference implementations +Check the WDK documentation for the correct configuration and initialization pattern. +``` *** -## Supported Blockchains & Protocols - -WDK natively supports a broad set of blockchains and standards out of the box: +## Tips for Effective AI-Assisted Development -| Blockchain/Module | Support | -| --------------------------------------------------------------- | ------- | -| [Bitcoin](../sdk/wallet-modules/wallet-btc/) | ✅ | -| [Ethereum & EVM](../sdk/wallet-modules/wallet-evm/) | ✅ | -| [Ethereum ERC-4337](../sdk/wallet-modules/wallet-evm-erc-4337/) | ✅ | -| [TON](../sdk/wallet-modules/wallet-ton/) | ✅ | -| [TON Gasless](../sdk/wallet-modules/wallet-ton-gasless/) | ✅ | -| [TRON](../sdk/wallet-modules/wallet-tron/) | ✅ | -| [TRON Gasfree](../sdk/wallet-modules/wallet-tron-gasfree/) | ✅ | -| [Solana](../sdk/wallet-modules/wallet-solana/) | ✅ | -| [Spark/Lightning](../sdk/wallet-modules/wallet-spark/) | ✅ | - -| Protocol/Module | Support | -| -------------------------------------------------------------- | ------- | -| [velora (EVM)](../sdk/swap-modules/swap-velora-evm/) | ✅ | -| StonFi (TON) | In progress | -| [USD₮0 Bridge (EVM)](../sdk/bridge-modules/bridge-usdt0-evm/) | ✅ | -| [Aave Lending (EVM)](../sdk/lending-modules/lending-aave-evm/) | ✅ | +* **Be specific about the chain.** Tell the AI which blockchain you're targeting (e.g., "I'm building on Ethereum using `@tetherto/wdk-wallet-evm`") so it picks the right module. +* **Reference the exact package name.** Mention the full `@tetherto/wdk-*` package name in your prompt for more accurate code generation. +* **Ask the AI to check docs first.** Prompt with "Check the WDK documentation before answering" to ensure it uses the MCP-connected docs rather than outdated training data. +* **Start with a quickstart.** Point the AI at the [Node.js Quickstart](nodejs-bare-quickstart) or [React Native Quickstart](react-native-quickstart) as a working reference before building custom features. +* **Iterate in steps.** Use the AI to scaffold your WDK integration first, then refine module configuration and error handling in follow-up prompts. -The modular architecture allows new chains, tokens, or protocols to be added by implementing dedicated modules. -Ready to start building? Explore our [getting started guide](../start-building/nodejs-bare-quickstart) or dive into our [SDK documentation](../sdk/get-started). -## Changelog -URL: https://docs.wdk.tether.su/overview/changelog -Description: Updates and improvements to the Wallet Development Kit (WDK) modules and tools. -Stay up to date with the latest improvements, new features, and bug fixes across all WDK modules. +# Node.js & Bare Runtime Quickstart (/start-building/nodejs-bare-quickstart) ---- -### April 22, 2026 -**Fixes** -- **wdk-core** ([v1.0.0-beta.8](https://github.com/tetherto/wdk/releases/tag/v1.0.0-beta.8)): Fix `WDK.getRandomSeedPhrase(wordCount?)` so client code can generate 24-word BIP-39 seed phrases instead of always receiving the default 12-word mnemonic. +## What You'll Build ---- +In this quickstart, you'll create a simple application that: -### April 19, 2026 +* [ ] Sets up WDK with multiple blockchain wallets (EVM, Bitcoin, TRON) +* [ ] Generates a new secret phrase (seed phrase) +* [ ] Resolves addresses across different chains +* [ ] Checks balances and estimates transaction costs +* [ ] Sends transactions on multiple blockchains -**Changes** -- **lending-aave-evm** ([v1.0.0-beta.4](https://www.npmjs.com/package/@tetherto/wdk-protocol-lending-aave-evm/v/1.0.0-beta.4)): Expand per-operation ERC‑4337 config overrides from `paymasterToken`-only to the wallet module's paymaster-token, sponsorship-policy, and native-coin gas modes. + + **Want to build faster?** Connect your AI coding assistant to WDK docs for context-aware help. [Learn how →](build-with-ai) + -**Fixes** -- **failover-provider** ([v1.0.0-beta.2](https://www.npmjs.com/package/@tetherto/wdk-failover-provider/v/1.0.0-beta.2)): Remove unnecessary published type definitions without changing the runtime failover behavior. -- **wallet-solana** ([v1.0.0-beta.7](https://www.npmjs.com/package/@tetherto/wdk-wallet-solana/v/1.0.0-beta.7)): Fix `SolanaWalletConfig.rpcUrl` typings to accept ordered `string[]` failover endpoints and align the published TypeScript definitions with the beta.6 runtime behavior. +*** ---- +## Prerequisites -### April 15, 2026 +Before we start, make sure you have: -**Changes** -- **wallet-solana** ([v1.0.0-beta.6](https://www.npmjs.com/package/@tetherto/wdk-wallet-solana/v/1.0.0-beta.6)): Add runtime RPC failover support for ordered `rpcUrl` lists plus `retries`, and tighten custom `TransactionMessage` and derivation-path validation for durable nonce lifetimes, fee payer matching, and hardened SLIP-0010 child paths. + + + | Tool | Version | Why You Need It | + | --------------- | ------- | ---------------------- | + | **Node.js** | 20+ | To run JavaScript code | + | **npm** | Latest | To install packages | + | **Code Editor** | Any | To write code | + ---- + + | Tool | Version | Why You Need It | + | ---------------- | --------- | ------------------- | + | **Bare Runtime** | >= 1.23.5 | To run JavaScript | + | **npm** | Latest | To install packages | + | **Code Editor** | Any | To write code | -### April 14, 2026 + To install Bare runtime first include to the `package.json`: -**What's New** -- **failover-provider** ([v1.0.0-beta.1](https://github.com/tetherto/wdk-failover-provider/releases/tag/v1.0.0-beta.1)): Initial release of a generic `FailoverProvider\` that chains provider candidates and retries sync or async failures with configurable `retries` and `shouldRetryOn(error)` logic. + ``` + "type": "module" + ``` -**Changes** -- **fiat-moonpay** ([v1.0.0-beta.2](https://github.com/tetherto/wdk-protocol-fiat-moonpay/releases/tag/v1.0.0-beta.2)): [Breaking] Replace `secretKey` signing with optional backend `signUrl`, add `environment` selection for production or sandbox widget URLs, and return unsigned widget URLs when no signer is configured. + and run the command `npm i -g bare` + + ---- + + You can try all features without real funds required. You can use the Pimlico or Candide faucets to get some Sepolia USD₮. -### April 13, 2026 + [Get mock/test USD₮ on Pimlico](https://dashboard.pimlico.io/test-erc20-faucet) + [Get mock/test USD₮ on Candide](https://dashboard.candide.dev/faucet) -**What's New** -- **wdk-utils** ([v1.0.0-beta.2](https://github.com/tetherto/wdk-utils/releases/tag/v1.0.0-beta.2)): Add EIP-681 request parsing utilities for transfer deeplinks, including request detection and structured parse results. -- **wdk-core** ([v1.0.0-beta.7](https://github.com/tetherto/wdk/releases/tag/v1.0.0-beta.7)): Added `dispose(blockchains?)`, so you can dispose one or more registered wallets without tearing down every wallet in the WDK instance. -- **pear-wrk-wdk** ([v1.0.0-beta.8](../tools/pear-wrk-wdk)): Adds `resetWdkWallets()` so custom Bare hosts can selectively dispose and re-register wallet modules from a new `networks` config. + See the [configuration](../sdk/wallet-modules/wallet-evm-erc-4337/configuration) for quick setup and Sepolia testnet configuration. + -**Changes** -- **wallet-spark** ([v1.0.0-beta.13](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.13)): Refresh `@buildonspark/bare` and `@buildonspark/spark-sdk` dependencies. -- **wallet-spark** ([v1.0.0-beta.14](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.14)): Add SparkScan-backed balance polling for `getBalance()`. -- **wallet-spark** ([v1.0.0-beta.15](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.15)): Refresh `@buildonspark/bare`, `@buildonspark/spark-sdk`, and `bare-node-runtime` dependencies. -- **wallet-spark** ([v1.0.0-beta.16](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.16)): Add `syncAndRetry` and `syncWalletBalance()` for retrying failed `sendTransaction()` and `payLightningInvoice()` calls once after syncing wallet state. +*** -**Fixes** -- **worklet-bundler** ([v1.0.0-beta.3](https://github.com/tetherto/wdk-worklet-bundler/releases/tag/v1.0.0-beta.3)): Generated worklet entrypoints now suspend and resume both HTTP and HTTPS global agents with Bare thread lifecycle events. -- **wallet-btc** ([v1.0.0-beta.8](https://github.com/tetherto/wdk-wallet-btc/releases/tag/v1.0.0-beta.8)): `getBalance()` now includes unconfirmed funds when present, and `sendTransaction()` accepts an optional `timeoutMs` to keep polling after broadcast until spent inputs disappear from unspent outputs. -- **wallet-evm** ([v1.0.0-beta.11](https://github.com/tetherto/wdk-wallet-evm/releases/tag/v1.0.0-beta.11)): Pin string-backed RPC providers to a static network during EVM account setup. -- **wallet-evm-erc-4337** ([v1.0.0-beta.6](https://github.com/tetherto/wdk-wallet-evm-erc-4337/releases/tag/v1.0.0-beta.6)): Reuse the internal EVM read-only helper during ERC-4337 method calls instead of recreating it on each call. +## Step 1: Set Up Your Project ---- +First, we need to create a folder and initialize the project -### April 3, 2026 +```bash +mkdir wdk-quickstart && cd wdk-quickstart && npm init -y && npm pkg set type=module +``` -**Changes** -- **wallet-spark** ([v1.0.0-beta.12](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.12)): [`WalletAccountReadOnlySpark`](../sdk/wallet-modules/wallet-spark/api-reference) gained [`getTransfers()`](../sdk/wallet-modules/wallet-spark/api-reference), [`getUnusedDepositAddresses()`](../sdk/wallet-modules/wallet-spark/api-reference) (paginated return type), [`getStaticDepositAddresses()`](../sdk/wallet-modules/wallet-spark/api-reference), [`getUtxosForDepositAddress()`](../sdk/wallet-modules/wallet-spark/api-reference), and [`getSparkInvoices()`](../sdk/wallet-modules/wallet-spark/api-reference) (new parameter type). Removed `sparkScanApiKey` config option and `SparkTransactionReceipt` type after dropping the `@sparkscan/api-node-sdk-client` dependency. [`getTransactionReceipt()`](../sdk/wallet-modules/wallet-spark/api-reference) now returns `SparkTransfer` instead. Added [`getAccountByPath()`](../sdk/wallet-modules/wallet-spark/api-reference) to [`WalletManagerSpark`](../sdk/wallet-modules/wallet-spark/api-reference). SIGNET network support documented. Dependency upgrades: `@buildonspark/spark-sdk` 0.7.3, `@buildonspark/bare` 0.0.53. +Then install necessary WDK modules ---- +```bash +npm install @tetherto/wdk @tetherto/wdk-wallet-evm @tetherto/wdk-wallet-tron @tetherto/wdk-wallet-btc +``` -### April 2, 2026 + + Learn more about WDK modules: -**Changes** -- **react-native-core** ([v1.0.0-beta.7](https://www.npmjs.com/package/@tetherto/wdk-react-native-core/v/1.0.0-beta.7)): Added missing type exports: `WdkAppState`, `TransactionParams`, `TransactionResult`, `UseAccountResponse`, `AddressInfo`, `AddressInfoResult`, `BalanceQueryOptions`, `UseWdkAppResult`. Removed `indexer` as a top-level config prop. + * [**@tetherto/wdk**](../sdk/core-module/) - The main SDK module + * [**@tetherto/wdk-wallet-evm**](../sdk/wallet-modules/wallet-evm/) - Ethereum and EVM-compatible chains support + * [**@tetherto/wdk-wallet-tron**](../sdk/wallet-modules/wallet-tron/) - TRON blockchain support + * [**@tetherto/wdk-wallet-btc**](../sdk/wallet-modules/wallet-btc/) - Bitcoin blockchain support + ---- +*** -### March 24, 2026 +## Step 2: Create Your First Wallet -**What's New** -- **[React Native Core](../tools/react-native-core/)**: Added documentation for `@tetherto/wdk-react-native-core` ([v1.0.0-beta.6](https://github.com/tetherto/wdk-core-react-native/releases/tag/v1.0.0-beta.6)), the hooks-based React Native integration layer for WDK. Includes [API Reference](../tools/react-native-core/api-reference) covering `WdkAppProvider`, `useWdkApp`, `useWalletManager`, `useAccount`, `useBalance`, and more. Updated [React Native Quickstart](../start-building/react-native-quickstart) with step-by-step integration guide. +Create a file called `app.js`: ---- +```javascript title="app.js" +import WDK from '@tetherto/wdk' +import WalletManagerEvm from '@tetherto/wdk-wallet-evm' +import WalletManagerTron from '@tetherto/wdk-wallet-tron' +import WalletManagerBtc from '@tetherto/wdk-wallet-btc' -### March 12, 2026 +console.log('Starting WDK App...') -**Changes** -- **wallet-btc** ([v1.0.0-beta.6](https://github.com/tetherto/wdk-wallet-btc/releases/tag/v1.0.0-beta.6)): Added `dispose()` method to [`WalletAccountReadOnlyBtc`](../sdk/wallet-modules/wallet-btc/api-reference) for closing internal Electrum connections. Security dependency updates. +try { + // Your code will go here +} catch (error) { + console.error('Application error:', error.message) + process.exit(1) +} +``` ---- +Now, add the following code to generate a seed phrase: -### March 6, 2026 +```typescript title="app.js" +try { + const seedPhrase = WDK.getRandomSeedPhrase() + console.log('Generated seed phrase:', seedPhrase) +} catch (error) { + console.error('Application error:', error.message) + process.exit(1) +} +``` -**Changes** -- **wallet-tron**: Fixed case-sensitive address check in `verify`, upgraded TonWeb to v6.2.0 (`v1.0.0-beta.5`) -- **lending-aave-evm**: Security dependency updates ([v1.0.0-beta.4](https://github.com/tetherto/wdk-protocol-lending-aave-evm/releases/tag/v1.0.0-beta.4)) -- **wdk**: Security dependency updates ([v1.0.0-beta.6](https://github.com/tetherto/wdk/releases/tag/v1.0.0-beta.6)) +Now, let's register wallets for different blockchains: ---- +```typescript title="app.js" +// Add this code after the seed phrase generation +console.log('Registering wallets...') -### March 5, 2026 +const wdkWithWallets = new WDK(seedPhrase) + .registerWallet('ethereum', WalletManagerEvm, { + provider: 'https://eth.drpc.org' + }) + .registerWallet('tron', WalletManagerTron, { + provider: 'https://api.trongrid.io' + }) + .registerWallet('bitcoin', WalletManagerBtc, { + network: 'mainnet', + host: 'electrum.blockstream.info', + port: 50001 + }) -**What's New** -- **create-wdk-module**: Added documentation for the [`create-wdk-module`](../tools/create-wdk-module) CLI scaffolding tool. Updated [Community Modules](../sdk/community-modules/) and [SDK Get Started](../sdk/get-started) pages with references to the new tool. +console.log('Wallets registered for Ethereum, TRON, and Bitcoin') +``` ---- + + To learn more about configuring the wallet modules: -### February 26, 2026 + * [Configuring @tetherto/wdk-wallet-evm](../sdk/wallet-modules/wallet-evm/configuration) + * [Configuring @tetherto/wdk-wallet-tron](../sdk/wallet-modules/wallet-tron/configuration) + * [Configuring @tetherto/wdk-wallet-btc](../sdk/wallet-modules/wallet-btc/configuration) + -**Changes** -- **wdk-protocol-bridge-usdt0-evm** ([v1.0.0-beta.3](https://github.com/tetherto/wdk-protocol-bridge-usdt0-evm/releases/tag/v1.0.0-beta.3)): Added per-call `BridgeOptions` overrides (`oftContractAddress`, `dstEid`) and expanded routing from EVM source chains to EVM plus non-EVM destinations (Solana, TON, TRON). +*** ---- +## Step 3: Check Balances -### February 25, 2026 +To check balances, we first need to get accounts and addresses. Let's get accounts and addresses for all blockchains: -**Changes** -- **wallet-evm** ([v1.0.0-beta.8](https://github.com/tetherto/wdk-wallet-evm/releases/tag/v1.0.0-beta.8)): Added [`getTokenBalances(tokenAddresses)`](../sdk/wallet-modules/wallet-evm/api-reference) to [`WalletAccountReadOnlyEvm`](../sdk/wallet-modules/wallet-evm/api-reference), also available on [`WalletAccountEvm`](../sdk/wallet-modules/wallet-evm/api-reference) through inheritance. -- **wallet-evm-erc-4337** ([v1.0.0-beta.5](https://github.com/tetherto/wdk-wallet-evm-erc-4337/releases/tag/v1.0.0-beta.5)): Added EIP-712 typed data methods [`signTypedData(typedData)`](../sdk/wallet-modules/wallet-evm-erc-4337/api-reference) and [`verifyTypedData(typedData, signature)`](../sdk/wallet-modules/wallet-evm-erc-4337/api-reference), plus multicall token balance method [`getTokenBalances(tokenAddresses)`](../sdk/wallet-modules/wallet-evm-erc-4337/api-reference). +```typescript title="app.js" +// Add this code after the wallet registration +console.log('Retrieving accounts...') ---- +const accounts = { + ethereum: await wdkWithWallets.getAccount('ethereum', 0), + tron: await wdkWithWallets.getAccount('tron', 0), + bitcoin: await wdkWithWallets.getAccount('bitcoin', 0) +} -### February 24, 2026 +console.log('Resolving addresses:') -**Changes** -- **wallet-spark** ([v1.0.0-beta.11](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.11)): Added Pear runtime entrypoint support (`pear.js`), removed static import causing runtime issues, and bumped spark bare SDK (`@buildonspark/bare`) to `0.0.47`. +for (const [chain, account] of Object.entries(accounts)) { + const address = await account.getAddress() + console.log(` ${chain.toUpperCase()}: ${address}`) +} +``` ---- +Now, let's check balances across all chains: -### February 20, 2026 +```typescript +// Add this code after the address resolution +console.log('Checking balances...') -**What's New** -- **[Showcase](../overview/showcase)**: More visibility for our showcase page, we value contributions! Added 4 featured community projects: [wdk-mcp](https://github.com/dieselftw/wdk-mcp), [wdk-starter-browser-extension](https://github.com/base58-io/wdk-starter-browser-extension), [wdk-wallet-evm-x402-facilitator](https://github.com/SemanticPay/wdk-wallet-evm-x402-facilitator), and [x402-usdt0](https://github.com/baghdadgherras/x402-usdt0). -- **[Community Modules](../sdk/community-modules)**: Added [`@base58-io/wdk-wallet-cosmos`](https://github.com/base58-io/wdk-wallet-cosmos) — wallet module for Cosmos-compatible blockchains by [Base58](https://base58.io/). +for (const [chain, account] of Object.entries(accounts)) { + const balance = await account.getBalance() + console.log(` ${chain.toUpperCase()}: ${balance.toString()} units`) +} +``` ---- +Here is the complete `app.js` file: -### February 18, 2026 +```javascript title="app.js" +import WDK from '@tetherto/wdk' +import WalletManagerEvm from '@tetherto/wdk-wallet-evm' +import WalletManagerTron from '@tetherto/wdk-wallet-tron' +import WalletManagerBtc from '@tetherto/wdk-wallet-btc' -**What's New** -- **[x402 Payments](../ai/x402)**: New guide for accepting and making instant USD₮ payments over HTTP using WDK self-custodial wallets. Covers the x402 protocol, buyer integration with `@tetherto/wdk-wallet-evm`, seller setup with hosted and self-hosted facilitators, and bridging USD₮ to Plasma and Stable chains. +console.log('Starting WDK App...') ---- +try { + const seedPhrase = WDK.getRandomSeedPhrase() + console.log('Generated seed phrase:', seedPhrase) -### February 15, 2026 + console.log('Registering wallets...') -**Changes** -- **wallet-spark**: Added [`getIdentityKey()`](../sdk/wallet-modules/wallet-spark/api-reference) method to [`WalletAccountReadOnlySpark`](../sdk/wallet-modules/wallet-spark/api-reference) for retrieving the account's identity public key ([v1.0.0-beta.10](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.10)) + const wdkWithWallets = new WDK(seedPhrase) + .registerWallet('ethereum', WalletManagerEvm, { + provider: 'https://eth.drpc.org' + }) + .registerWallet('tron', WalletManagerTron, { + provider: 'https://api.trongrid.io' + }) + .registerWallet('bitcoin', WalletManagerBtc, { + network: 'mainnet', + host: 'electrum.blockstream.info', + port: 50001 + }) ---- + console.log('Wallets registered for Ethereum, TRON, and Bitcoin') -### February 14, 2026 + const accounts = { + ethereum: await wdkWithWallets.getAccount('ethereum', 0), + tron: await wdkWithWallets.getAccount('tron', 0), + bitcoin: await wdkWithWallets.getAccount('bitcoin', 0) + } -**Changes** -- **wallet-spark**: Upgrade spark-sdk from `0.6.1` to `0.6.4` and spark bare SDK to `0.0.43` ([v1.0.0-beta.9](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.9)) + console.log('Resolving addresses:') ---- + for (const [chain, account] of Object.entries(accounts)) { + const address = await account.getAddress() + console.log(` ${chain.toUpperCase()}: ${address}`) + } -### February 12, 2026 + console.log('Checking balances...') -**What's New** -- **[Agent Skills](../ai/agent-skills)**: New page covering WDK's agent skill capabilities, self-custodial vs hosted comparison, and platform compatibility with OpenClaw, Claude, Cursor, and other agent platforms. -- **[OpenClaw Integration](../ai/openclaw)**: New page for installing and configuring the WDK skill in OpenClaw via ClawHub, including security precautions for running agents locally. + for (const [chain, account] of Object.entries(accounts)) { + const balance = await account.getBalance() + console.log(` ${chain.toUpperCase()}: ${balance.toString()} units`) + } -**Changes** -- **wallet-evm** ([v1.0.0-beta.7](https://github.com/tetherto/wdk-wallet-evm/releases/tag/v1.0.0-beta.7)): Added [EIP-712](https://eips.ethereum.org/EIPS/eip-712) typed data support: - - Added [`signTypedData(typedData)`](../sdk/wallet-modules/wallet-evm/api-reference) method to [`WalletAccountEvm`](../sdk/wallet-modules/wallet-evm/api-reference) for signing structured data - - Added [`verifyTypedData(typedData, signature)`](../sdk/wallet-modules/wallet-evm/api-reference) method to [`WalletAccountEvm`](../sdk/wallet-modules/wallet-evm/api-reference) and [`WalletAccountReadOnlyEvm`](../sdk/wallet-modules/wallet-evm/api-reference) for verifying typed data signatures -- **wallet-evm-erc-4337** ([v1.0.0-beta.4](https://github.com/tetherto/wdk-wallet-evm-erc-4337/releases/tag/v1.0.0-beta.4)): - - Added 2 new gas payment modes: [Sponsorship Policy](../sdk/wallet-modules/wallet-evm-erc-4337/configuration#gas-payment-mode-flags) and [Native Coins](../sdk/wallet-modules/wallet-evm-erc-4337/configuration#gas-payment-mode-flags), alongside the existing Paymaster Token mode - - Added per-call [config override](../sdk/wallet-modules/wallet-evm-erc-4337/api-reference) parameter to `sendTransaction`, `transfer`, `quoteSendTransaction`, and `quoteTransfer` - - Added [`getUserOperationReceipt(hash)`](../sdk/wallet-modules/wallet-evm-erc-4337/api-reference) method for retrieving ERC-4337 UserOperation receipts - - Added [`ConfigurationError`](../sdk/wallet-modules/wallet-evm-erc-4337/api-reference) error type for invalid configuration validation - ---- + console.log('Application completed successfully!') + process.exit(0) +} catch (error) { + console.error('Application error:', error.message) + process.exit(1) +} +``` -### February 10, 2026 +*** -**What's New** -- **[Build with AI](../start-building/build-with-ai)**: New guide for using AI coding assistants with WDK. Includes MCP server setup, Markdown context endpoints, project rules, and example prompts. Supports Cursor, Claude Code, GitHub Copilot, Windsurf, Cline, and Continue. -- **[MCP Toolkit](../ai/mcp-toolkit)**: New documentation for `@tetherto/wdk-mcp-toolkit` (`v1.0.0-beta.1`). Covers the `WdkMcpServer` class, 35 built-in MCP tools across 7 categories (wallet, pricing, indexer, swap, bridge, lending, fiat), setup wizard, multi-tool configuration, and full API Reference. +## Step 4: Run Your App ---- +Execute your app: -### February 08, 2026 + + + ```bash + node app.js + ``` + -**Changes** -- **wallet-spark**: Fixed import causing wallet init failure. Upgrade spark-sdk from `0.5.7` to `0.6.1` ([v1.0.0-beta.8](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.8)) + + ```bash + bare app.js + ``` + + ---- +You should see an output similar to this: -### February 02, 2026 +``` +Starting WDK App... +Generated seed phrase: abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about +Registering wallets... +Wallets registered for Ethereum, TRON, and Bitcoin +Resolving addresses: + ETHEREUM: 0x742d35Cc6634C0532925a3b8D9C5c8b7b6e5f6e5 + TRON: TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH + BITCOIN: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa +Checking balances... + ETHEREUM: 0 units + TRON: 0 units + BITCOIN: 0 units +Application completed successfully! +``` -**Changes** -- **wallet-ton-gasless**: Added `verify` method to [`WalletAccountReadOnlyTonGasless`](../sdk/wallet-modules/wallet-ton-gasless/api-reference#walletaccountreadonlytongasless) ([v1.0.0-beta.4](https://github.com/tetherto/wdk-wallet-ton-gasless/releases/tag/v1.0.0-beta.4)) -- **wallet-tron-gasfree**: Added `verify` method to [`WalletAccountReadOnlyTronGasfree`](../sdk/wallet-modules/wallet-tron-gasfree/api-reference#walletaccountreadonlytrongasfree) ([v1.0.0-beta.4](https://github.com/tetherto/wdk-wallet-tron-gasfree/releases/tag/v1.0.0-beta.4)) +*** -### January 29, 2026 +## What Just Happened? -**What's New** -- **wdk-indexer** - - Updated Ethereum indexer supported tokens list to add USA₮. +**Congratulations!** You've successfully created your first multi-chain WDK application that works in both Node.js and Bare runtime environments. Here's what happened: -**Changes** -- **wdk-indexer docs** - - Fixed the USD₮, XAU₮ token names. +* [x] You generated a single seed phrase that works across all blockchains +* [x] You registered wallets for Ethereum, TRON, and Bitcoin +* [x] You created accounts derived from the same seed phrase using BIP-44 +* [x] You used the same API to interact with different blockchains +* [x] You checked balances across multiple chains with consistent methods ---- +*** -### January 26, 2026 +## Next Steps -**Changes** -- **wallet-btc** ([v1.0.0-beta.5](https://github.com/tetherto/wdk-wallet-btc/releases/tag/v1.0.0-beta.5)): - - Added `verify` method to [`WalletAccountReadOnlyBtc`](../sdk/wallet-modules/wallet-btc/api-reference) - - Added Pluggable Transport classes: [`ElectrumTcp`](../sdk/wallet-modules/wallet-btc/api-reference), [`ElectrumTls`](../sdk/wallet-modules/wallet-btc/api-reference), [`ElectrumSsl`](../sdk/wallet-modules/wallet-btc/api-reference), [`ElectrumWs`](../sdk/wallet-modules/wallet-btc/api-reference) -- **wallet-evm**: Added `verify` method to [`WalletAccountReadOnlyEvm`](../sdk/wallet-modules/wallet-evm/api-reference) ([v1.0.0-beta.5](https://github.com/tetherto/wdk-wallet-evm/releases/tag/v1.0.0-beta.5)) -- **wallet-solana**: Added `verify` method to [`WalletAccountReadOnlySolana`](../sdk/wallet-modules/wallet-solana/api-reference) ([v1.0.0-beta.5](https://github.com/tetherto/wdk-wallet-solana/releases/tag/v1.0.0-beta.5)) -- **wallet-ton**: Added `verify` method to [`WalletAccountReadOnlyTon`](../sdk/wallet-modules/wallet-ton/api-reference) ([v1.0.0-beta.7](https://github.com/tetherto/wdk-wallet-ton/releases/tag/v1.0.0-beta.7)) -- **wallet-tron**: Added `verify` method to [`WalletAccountReadOnlyTron`](../sdk/wallet-modules/wallet-tron/api-reference) ([v1.0.0-beta.4](https://github.com/tetherto/wdk-wallet-tron/releases/tag/v1.0.0-beta.4)) -- **wallet-spark**: Added `verify` method to [`WalletAccountReadOnlySpark`](../sdk/wallet-modules/wallet-spark/api-reference) ([v1.0.0-beta.7](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.7)) +Now that you have a basic multi-chain wallet running, here's what you can explore: ---- +### Add More Blockchains -### January 23, 2026 +For example, to add Solana support: -**What's New** -- **wdk-core docs**: Added comprehensive [Core Module Guides](../sdk/core-module/guides/getting-started) covering: - - [Getting Started](../sdk/core-module/guides/getting-started) - Installation and instantiation - - [Wallet Registration](../sdk/core-module/guides/wallet-registration) - Registering wallet modules for different blockchains - - [Account Management](../sdk/core-module/guides/account-management) - Working with accounts and addresses - - [Transactions](../sdk/core-module/guides/transactions) - Sending native tokens - - [Protocol Integration](../sdk/core-module/guides/protocol-integration) - Using swaps, bridges, and lending protocols - - [Middleware](../sdk/core-module/guides/middleware) - Configuring logging and failover protection - - [Error Handling](../sdk/core-module/guides/error-handling) - Best practices and memory management -- **wdk-core**: Added support for 24-word seed phrases via `WDK.getRandomSeedPhrase(24)` -- **indexer-api**: - - Added new `/api/v1/chains` endpoint to list supported blockchains and tokens - - Added XAU₮ support for Plasma network +```bash +npm install @tetherto/wdk-wallet-solana +``` -**Changes** -- **wallet-btc docs**: - - Updated documentation with BIP-84 (Native SegWit) and BIP-44 (Legacy) support - - Improved API Reference and configuration documentation -- **wallet-spark docs**: - - Removed testnet support (now only mainnet and regtest) - - Added [Lightspark Regtest Faucet](https://app.lightspark.com/regtest-faucet) link for test funds -- **wallet-tron-gasfree docs**: - - Updated testnet from Shasta to Nile - - Updated GasFree service URLs and configuration examples -- **wallet-evm-erc-4337 docs**: Added paymaster token configuration documentation -- **docs**: - - Updated token symbols to USD₮ and XAU₮ throughout documentation - - Various documentation improvements with better cross-linking and examples +```typescript +import WalletManagerSolana from '@tetherto/wdk-wallet-solana' -**Fixes** -- **wallet-tron-gasfree docs**: Fixed typo "Gras-Free" to "Gas-Free" -- Fixed GitBook callout syntax and formatting issues across documentation +// New or existing WDK instance +const wdk = new WDK(seedPhrase) ---- +wdk.registerWallet('solana', WalletManagerSolana, { + rpcUrl: 'https://api.mainnet-beta.solana.com', + wsUrl: 'wss://api.mainnet-beta.solana.com' +}) -### December 23, 2025 +``` -**What's New** -- Added [MoonPay Fiat Module](../sdk/fiat-modules/fiat-moonpay/) for on-ramp and off-ramp functionality -- Added [Community Modules](../sdk/community-modules/) section to highlight community-built modules +### Estimate Transaction Costs -**Changes** -- Added this changelog page in the docs! -- **wallet-spark**: Updated Spark SDK to latest version ([v1.0.0-beta.6](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.6)) -- Introduced [All Modules](../sdk/all-modules) page in docs for comprehensive module listings -- Reorganized documentation structure for better navigation +```typescript +for (const [chain, account] of Object.entries(accounts)) { + try { + const quote = await account.quoteSendTransaction({ + to: await account.getAddress(), + value: chain === 'bitcoin' ? 100000000n : chain === 'tron' ? 1000000n : 1000000000000000000n + }) + console.log(` ${chain.toUpperCase()}: ${quote.fee.toString()} units`) + } catch (error) { + console.log(` ${chain.toUpperCase()}: Unable to estimate`) + } +} +``` ---- +### **Send Transactions** -### December 17, 2025 +```typescript +const result = await ethAccount.sendTransaction({ + to: '0x742d35Cc6634C05...a3b8D9C5c8b7b6e5f6e5', + value: 1000000000000000000n // 1 ETH +}) -**What's New** -- **wdk-core**: Added fiat protocol support for on-ramp integrations ([v1.0.0-beta.5](https://github.com/tetherto/wdk-core/releases/tag/v1.0.0-beta.5)) -- **wdk-wallet**: Added fiat protocol integration ([v1.0.0-beta.6](https://github.com/tetherto/wdk-wallet/releases/tag/v1.0.0-beta.6)) +console.log('Transaction hash:', result.hash) +``` ---- +### **Use DeFi Protocols** -### December 3, 2025 +```bash +npm install @tetherto/wdk-protocol-swap-velora-evm +``` -**What's New** -- **wallet-ton**: Added integration tests ([v1.0.0-beta.6](https://github.com/tetherto/wdk-wallet-ton/releases/tag/v1.0.0-beta.6)) -- **wallet-btc**: Added support for custom `feeRate` and `confirmationTarget` parameters ([v1.0.0-beta.4](https://github.com/tetherto/wdk-wallet-btc/releases/tag/v1.0.0-beta.4)) +```typescript +import VeloraProtocolEvm from '@tetherto/wdk-protocol-swap-velora-evm' -**Changes** -- **wallet-ton**: Updated default derivation path, fixed transaction receipt LT and from address -- **wallet-solana**: Updated default derivation path for better compatibility ([v1.0.0-beta.4](https://github.com/tetherto/wdk-wallet-solana/releases/tag/v1.0.0-beta.4)) -- **wallet-btc**: Multiple improvements: - - Automatic dust limit inference based on wallet type - - Performance improvements with bounded concurrency and caching for `getTransfers` - - Switched to `bitcoinjs-message` for standard message signing - - Updated default BIP to 84 (Native SegWit) - - Fixed testnet derivation path (now uses `1'`) +wdk.registerProtocol('ethereum', 'swap-velora-evm', VeloraProtocolEvm, { + provider: 'https://eth.drpc.org' +}) +``` ---- +*** -### November 14, 2025 +## Troubleshooting -**Changes** -- **wdk-wallet**: Runtime updates and dependency synchronization ([v1.0.0-beta.5](https://github.com/tetherto/wdk-wallet/releases/tag/v1.0.0-beta.5)) +### **Common Issues** ---- +**"Provider not connected"** -### November 12, 2025 +* Check your API keys and network connections +* Ensure you're using the correct provider URLs -**What's New** -- **wallet-solana**: Added `sendTransaction` support with unit tests ([v1.0.0-beta.3](https://github.com/tetherto/wdk-wallet-solana/releases/tag/v1.0.0-beta.3)) +**"Insufficient balance"** -**Changes** -- **wallet-solana**: Fixed `punycode` module resolution issue -- **lending-aave-evm**: Runtime compatibility updates ([v1.0.0-beta.3](https://github.com/tetherto/wdk-protocol-lending-aave-evm/releases/tag/v1.0.0-beta.3)) +* This is normal for new addresses +* Use testnet faucets to get test tokens ---- +**"Module not found"** -### November 11, 2025 +* Make sure you've installed all required packages +* Check your import statements -**Changes** -- **swap-velora-evm**: Runtime compatibility updates ([v1.0.0-beta.4](https://github.com/tetherto/wdk-protocol-swap-velora-evm/releases/tag/v1.0.0-beta.4)) +## Need Help? ---- + -### November 9-10, 2025 -**What's New** -- **wallet-ton-gasless**: Added unit tests ([v1.0.0-beta.3](https://github.com/tetherto/wdk-wallet-ton-gasless/releases/tag/v1.0.0-beta.3)) -- **pear-wrk-wdk**: Added seed buffer support in `workletStart` ([v1.0.0-beta.5](../tools/pear-wrk-wdk)) +# React Native Quickstart (/start-building/react-native-quickstart) -**Changes** -- **wallet-tron-gasfree**: Fixed bug interacting with Gasfree API ([v1.0.0-beta.3](https://github.com/tetherto/wdk-wallet-tron-gasfree/releases/tag/v1.0.0-beta.3)) -- **wallet-ton-gasless**: Updated TON query-id and transaction hash handling -- **wallet-evm**: Runtime updates ([v1.0.0-beta.4](https://github.com/tetherto/wdk-wallet-evm/releases/tag/v1.0.0-beta.4)) -- **wallet-tron**: Dependency and runtime updates ([v1.0.0-beta.3](https://github.com/tetherto/wdk-wallet-tron/releases/tag/v1.0.0-beta.3)) ---- -### November 8, 2025 +## What You'll Build -**Changes** -- **wdk-core**: Updated `bare-node-runtime` for improved compatibility ([v1.0.0-beta.4](https://github.com/tetherto/wdk-core/releases/tag/v1.0.0-beta.4)) -- **wallet-spark**: Updated Spark dependencies and improved `dispose` method ([v1.0.0-beta.5](https://github.com/tetherto/wdk-wallet-spark/releases/tag/v1.0.0-beta.5)) +In this quickstart, you'll integrate WDK into a React Native app to create a multi-chain wallet that: ---- +* [ ] Supports multiple blockchains (Bitcoin, Ethereum, Polygon, Arbitrum, TON, Tron) +* [ ] Manages multiple tokens (BTC, USD₮, XAU₮, and more) +* [ ] Provides secure seed generation and encrypted storage +* [ ] Shows real-time balances and transaction history +* [ ] Includes wallet creation, import, and unlock flows -### November 7, 2025 + + You can try all features without real funds required. You can use the Pimlico or Candide faucets to get some Sepolia USD₮. -**Changes** -- **wallet-evm-erc-4337**: Fixed destructuring of user operation in `getTransactionReceipt()` ([v1.0.0-beta.3](https://github.com/tetherto/wdk-wallet-evm-erc-4337/releases/tag/v1.0.0-beta.3)) -- **wallet-ton**: Replaced UUID-based message body with seqno/queryId for TON transfers, downgraded `@ton/ton` to 15.1.0 for stability ([v1.0.0-beta.5](https://github.com/tetherto/wdk-wallet-ton/releases/tag/v1.0.0-beta.5)) + * [Get mock/test USD₮ on Pimlico](https://dashboard.pimlico.io/test-erc20-faucet) + * [Get mock/test USD₮ on Candide](https://dashboard.candide.dev/faucet) ---- + See the [ERC-4337 configuration](../sdk/wallet-modules/wallet-evm-erc-4337/configuration) for quick setup and Sepolia testnet configuration. + -## How to Stay Updated + + **Want to build faster?** Connect your AI coding assistant to WDK docs for context-aware help. [Learn how →](build-with-ai) + -- Check this page for the latest updates -- Join our [Discord community](https://discord.gg/arYXDhHB2w) for real-time announcements -- Star and follow the [GitHub repositories](https://github.com/orgs/tetherto/repositories?q=wdk) for detailed release notes -## Partner with WDK -URL: https://docs.wdk.tether.su/overview/partner-program -Description: Build with WDK alongside Tether through our partnership tracks -Build with WDK alongside Tether. Whether you're integrating WDK into your product or extending the ecosystem with new capabilities, we have a partnership track designed for you. +## Prerequisites -WDK is built to be open and extensible, but we know that building great products often takes more than just great documentation. We offer a selected group of partners a direct connection with Tether's engineering and product teams so you can ship faster, with confidence. We offer 3 partnership tracks depending on how you plan to work with WDK. +Before we start, make sure you have: -- [Project Partners](#project-partners) -- [WDK Tech Contributors](#wdk-tech-contributors) -- [Consulting & Implementation Partners (Alpha)](#consulting--implementation-partners-alpha) +| Tool | Version | Why You Need It | +| ---------------- | ------- | --------------------------- | +| **Node.js** | 22+ | To run JavaScript code | +| **npm** | Latest | To install packages | +| **React Native** | 0.81.0+ | Framework version | +| **Android SDK** | API 29+ | Android minimum SDK version | +| **iOS** | 15.1+ | iOS deployment target | *** -## Project Partners - -Integrate WDK more confidently, with direct access to Tether's engineering team and WDK solutions architects. Project Partners approved for Tether-supported implementations will benefit from: - -- Access to a WDK Solutions Architect to discuss product-specific implementation strategies -- Custom integration assistance -- Privileged support channel -- WDK roadmap visibility -- Early access to APIs and SDKs -- Direct access to WDK product and engineering core team +## Quickstart Paths -### Is it for you? +You have 2 options for using WDK in a React Native. Choose your preferred starting point: -Project Partners are companies and teams building end-user products powered by WDK. You're a good fit for this track if you are: + + + Get up and running in 3 minutes with our pre-configured starter template. -- A **fintech or neobank** building a wallet, payments app, or asset management platform and looking to leverage WDK as your underlying wallet infrastructure. -- An **exchange or trading platform** adding self-custodial wallet features for your users. -- A **messaging or social platform** integrating peer-to-peer payments or tipping functionality. -- A **remittance or cross-border payments provider** looking to use stablecoins and multi-chain support to serve your customers. -- An **enterprise or institutional player** that needs WDK integrated into internal treasury, compliance, or operations tooling. -- Any team that plans to **ship a product to end users** where WDK handles key management, transaction signing, or blockchain interactions under the hood. + [**→ Jump to Starter Template Setup**](#option-1-starter-template) + -As a Project Partner, you get hands-on integration support from the team that builds WDK. We'll help you navigate architecture decisions, troubleshoot implementation challenges, and make sure your product launches on solid foundations. + + Integrate WDK into your existing React Native or Expo app. -[Become a Project Partner](https://forms.monday.com/forms/6d484c4b34949e3a238988c47bf0a1b6?r=euc1) + [**→ Jump to Library Integration**](#option-2-add-to-existing-app) + + *** -## WDK Tech Contributors +## Option 1: Starter Template -Tap into the network of WDK adopters by developing modules and extensions for the WDK ecosystem. Technology partners approved as WDK Tech Contributors will benefit from: +The fastest way to get started is with our starter template. Note: this is still in alpha, and may be subject to breaking changes. -- Build and publish WDK modules -- Visibility across WDK community and in WDK documentation -- Co-marketing opportunities -- Early access to APIs and SDKs -- Technical documentation collaboration +### Step 1: Clone the Starter -### Is it for you? +```bash +git clone https://github.com/tetherto/wdk-starter-react-native.git +cd wdk-starter-react-native +``` -Tech Contributors are protocol teams, service providers, and developer organizations building modules, plugins, or integrations that extend what WDK can do. You're a good fit for this track if you are: +### Step 2: Install Dependencies -- A **swap or DEX protocol** looking to provide liquidity and trading capabilities to WDK-powered wallets. -- A **bridge protocol** enabling cross-chain asset transfers that WDK wallets can access natively. -- An **on/off-ramp provider** connecting fiat currencies to the WDK ecosystem. -- A **lending or DeFi protocol** looking to make your services available directly within WDK wallets. -- A **hardware wallet or signing solution provider** building signer integrations for WDK. -- A **blockchain or L2 network** that wants first-class WDK wallet support for your chain. -- An **open-source developer or team** contributing new wallet modules, protocol integrations, or developer tooling to the WDK ecosystem. +```bash +npm install +``` -As a Tech Contributor, you'll work closely with our SDK team to build, test, and publish modules that reach every WDK-powered wallet. You'll get early access to unreleased APIs, architecture guidance, co-marketing exposure through our documentation and community channels, and the opportunity to shape how your protocol integrates across the ecosystem. +### Step 3: Configure Environment -[Become a Technology Partner](https://tether.to/en/partner-with-us/) +Create an environment file for the WDK Indexer API: -*** +```bash +cp .env.example .env +``` -## Consulting & Implementation Partners (Alpha) +Edit `.env` and add your WDK Indexer API key: -Consulting companies, agencies, and systems integrators building wallet solutions with WDK for their clients. Approved Consulting & Implementation Partners will benefit from: +```bash +EXPO_PUBLIC_WDK_INDEXER_BASE_URL=https://wdk-api.tether.io +EXPO_PUBLIC_WDK_INDEXER_API_KEY=your_actual_api_key_here +# Optional: For Tron network support +EXPO_PUBLIC_TRON_API_KEY=your_tron_api_key +EXPO_PUBLIC_TRON_API_SECRET=your_tron_api_secret +``` -- **Being part of Tether's partner ecosystem** -- Access to a WDK Solutions Architect to discuss product-specific implementation strategies for your clients -- Custom integration assistance -- Direct access to WDK product and engineering core team -- Privileged support channel -- WDK roadmap visibility -- Early access to APIs and SDKs -- Co-marketing support + + **Where do I get an Indexer API key?** The WDK Indexer is required for transaction history and balance indexing. Get your free API key from the [Indexer API setup guide](../tools/indexer-api/get-started). + -### Is it for you? +### Step 4: Run Your App -Consulting & Implementation Partners are agencies, system integrators, and software houses that would like to deliver WDK-powered solutions on behalf of their clients. You're a good fit for this track if you are: + + + ```bash + npm run ios + ``` + -- A **system integrator** helping enterprise clients adopt blockchain and digital asset infrastructure. -- A **software development agency** building custom wallet or payment applications. -- A **blockchain consultancy** advising companies on self-custodial wallet strategy and architecture. -- A **digital transformation firm** integrating stablecoin payments into existing client platforms. -- A **managed services provider** offering ongoing support and maintenance for WDK-based deployments. + + ```bash + npm run android + ``` + + -As a Consulting & Implementation Partner, you'll gain access to Tether's referral network, dedicated technical support for your client engagements. We'll equip your team with the training, documentation, and direct engineering access needed to deliver successful WDK implementations at scale. +**Congratulations!** You now have a multi-chain wallet running. -**Alpha Program** - This partnership track is currently in alpha. We're onboarding a limited number of partners as we shape the program and cannot guarantee acceptance, specific benefits, or program terms at this stage. Apply to express your interest and help shape the program as it evolves. +[**→ Skip to What's Next**](#whats-next) -[Become a Consulting & Implementation Partner](https://tether.to/en/partner-with-us/) -## Showcase -URL: https://docs.wdk.tether.su/overview/showcase -Description: Explore the projects built by the WDK community showcasing real-world use cases, integrations, and creative implementations using the Wallet Development Kit. -Showcase projects are developed and maintained independently by third-party contributors. +*** -Tether and the WDK Team do not endorse or assume responsibility for their code, security, or maintenance. Use your own judgment and proceed at your own risk. +## Option 2: Add to Existing App -Looking for community-built WDK modules you can install and use in your project? Check out the [Community Modules](../sdk/community-modules/) page instead. +Integrate WDK into your existing React Native or Expo project using `@tetherto/wdk-react-native-core`. -## Featured Projects +### Step 1: Install ---- +```bash +npm install @tetherto/wdk-react-native-core +``` -### wdk-starter-browser-extension +### Step 2: Configure Android minSdkVersion -> Self-custodial browser extension wallet starter built on WDK. +The library requires **Android API 29** or higher to support `react-native-bare-kit`. -**Author:** Base58 ([Website](https://base58.io/), [GitHub](https://github.com/base58-io)) / alexszolowicz ([GitHub](https://github.com/alexszolowicz-blockether)) -**Repository:** [github.com/base58-io/wdk-starter-browser-extension](https://github.com/base58-io/wdk-starter-browser-extension) + + + Add to your `app.json` or `app.config.js`: -A browser extension starter kit that demonstrates how to build a self-custodial wallet using WDK. Provides a ready-made template for creating Chrome-compatible extension wallets with secure key management and transaction signing. + ```json + { + "expo": { + "plugins": [ + [ + "expo-build-properties", + { + "android": { + "minSdkVersion": 29 + } + } + ] + ] + } + } + ``` -![wdk-starter-browser-extension demo](/assets/wdk-starter-browser-extension.gif) + If you haven't installed `expo-build-properties`: ---- + ```bash + npx expo install expo-build-properties + ``` + -### wdk-wallet-evm-x402-facilitator + + Update `android/build.gradle`: -> x402 payment facilitator adapter for WDK EVM wallets. + ```groovy + buildscript { + ext { + minSdkVersion = 29 + // ... other config + } + } + ``` + + -**Author:** SemanticPay ([Website](https://www.semanticpay.io/), [GitHub](https://github.com/SemanticPay)) -**Repository:** [github.com/SemanticPay/wdk-wallet-evm-x402-facilitator](https://github.com/SemanticPay/wdk-wallet-evm-x402-facilitator) +### Step 3: Configure the Bundle -An adapter that enables WDK EVM wallets to act as x402 payment facilitators. Bridges the WDK wallet interface with the x402 HTTP payment protocol, allowing servers to charge for API access using on-chain payments. +The WDK engine runs inside a Bare worklet. You need to provide a bundle - choose one of two approaches: ---- + + + Use the `@tetherto/wdk-worklet-bundler` CLI to generate a bundle with only the modules you need: -### x402-usdt0 + ```bash + # 1. Install the bundler CLI + npm install -g @tetherto/wdk-worklet-bundler -> End-to-end x402 reference implementation on Plasma with USDT0 and WDK. + # 2. Initialize configuration in your React Native project + wdk-worklet-bundler init -**Author:** baghdadgherras ([GitHub](https://github.com/baghdadgherras)) -**Repository:** [github.com/baghdadgherras/x402-usdt0](https://github.com/baghdadgherras/x402-usdt0) + # 3. Edit wdk.config.js to configure your networks (see example below) -A complete reference implementation demonstrating the x402 HTTP payment protocol using USDT0 on the Plasma network. Includes both client and server components, showcasing how WDK wallets can facilitate machine-to-machine payments in a real-world setup. + # 4. Install required WDK modules (pick the ones you need) + npm install @tetherto/wdk @tetherto/wdk-wallet-evm-erc-4337 ---- + # 5. Generate the bundle + wdk-worklet-bundler generate + ``` -### wdk-mcp + This generates a `.wdk/` directory in your project. Import it: -> AI-powered blockchain operations via Model Context Protocol. + ```typescript + import { bundle } from './.wdk' + ``` -**Author:** Seven ([GitHub](https://github.com/rezerov)) -**Repository:** [github.com/rezerov/wdk-mcp](https://github.com/rezerov/wdk-mcp) + + **Which WDK modules do I need?** Each blockchain requires its own wallet module (e.g., `wdk-wallet-evm-erc-4337` for Ethereum/Polygon, `wdk-wallet-btc` for Bitcoin). See the full list of available modules in the [wdk-worklet-bundler documentation](https://github.com/tetherto/wdk-worklet-bundler). + + -Integrates WDK capabilities within the MCP (Model Context Protocol) ecosystem, allowing AI Agents to perform blockchain operations such as signing, transactions, and wallet interactions securely and locally. This project expands the reach of WDK to autonomous systems and AI-driven workflows. + + For quick prototyping, install and import the ready-made bundle from `@tetherto/pear-wrk-wdk`: ---- + ```bash + npm install @tetherto/pear-wrk-wdk + ``` -## Submit Your Project + ```typescript + import { bundle } from '@tetherto/pear-wrk-wdk' + ``` -If you've built something using WDK, we'd love to showcase it. + + The pre-built bundle includes all blockchain modules, resulting in a larger bundle size. For production apps, generate a custom bundle with only the modules you need. + + + -Projects listed here should: -- Use one or more WDK modules or SDKs -- Be open source or publicly accessible -- Include a clear README and installation instructions +### Step 4: Configure WDK Settings -Your work may be featured in future updates, social posts, or documentation spotlights. +Create a configuration file for your WDK setup (e.g., `src/config/wdk.ts`): -Share it with us through the community form or the showcase channel below. -## Get Support -URL: https://docs.wdk.tether.su/overview/support -Description: Need help with WDK? We've got you covered -We're here to help you succeed with WDK. Don't hesitate to reach out. -## Our Vision -URL: https://docs.wdk.tether.su/overview/vision -Description: >- -Imagine a world where humans, machines, and AI agents have the freedom to control their own finances. WDK is a fully open-source, self-custodial toolkit designed to be modular, independent, resilient and infinitely scalable, enabling trillions of wallets. +```typescript +// src/config/wdk.ts +import type { WdkConfigs } from '@tetherto/wdk-react-native-core' -*** +export const wdkConfigs: WdkConfigs = { + networks: { + ethereum: { + blockchain: 'ethereum', + config: { + chainId: 11155111, // Sepolia testnet + provider: 'https://rpc.sepolia.org', + bundlerUrl: 'https://api.candide.dev/public/v3/sepolia', + paymasterUrl: 'https://api.candide.dev/public/v3/sepolia', + paymasterAddress: '0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba', + entrypointAddress: '0x0000000071727De22E5E9d8BAf0edAc6f37da032', + transferMaxFee: 5000000, + paymasterToken: { + address: '0xaA8E23Fb1079EA71e0a56F48a2aA51851D8433D0', // USDT on Sepolia + }, + }, + }, + // Add more networks as needed + }, +} +``` -### **Universal Unstoppable Access** + + This example uses **Sepolia testnet** with a free public RPC so you can start immediately without API keys. For production or mainnet configuration, see the [Chain Configuration Guide](../sdk/core-module/configuration). + -Anyone should be able to build, deploy or use a wallet and manage assets without friction or gatekeepers. Whether you're an independent developer, a startup, a corporation, an AI, or even a nation-state, WDK provides the open technology to create hyper-secure self-custodial wallets without barriers. +### Step 5: Add WdkAppProvider -### **Ubiquitous Deployment** +Wrap your app with `WdkAppProvider` to enable wallet functionality throughout your app. -Wallets need to run everywhere. Through Bare runtime compatibility, WDK can live and evolve on any embedded device, mobile apps, desktop applications, IoT devices, servers, and even autonomous systems. From smartphones to smart fridges, from trading bots to spaceships — WDK enables financial sovereignty across all environments. + + + Add to your `app/_layout.tsx`: + + ```tsx + // app/_layout.tsx + import { WdkAppProvider } from '@tetherto/wdk-react-native-core' + import { bundle } from './.wdk' + import { Stack } from 'expo-router' + import { wdkConfigs } from '../config/wdk' + + export default function RootLayout() { + return ( + + + + ) + } + ``` + + + + Update your `App.tsx`: + + ```tsx + // App.tsx + import React from 'react' + import { WdkAppProvider } from '@tetherto/wdk-react-native-core' + import { bundle } from './.wdk' + import { NavigationContainer } from '@react-navigation/native' + import { MainNavigator } from './src/navigation' + import { wdkConfigs } from './src/config/wdk' + + export default function App() { + return ( + + + + + + ) + } + ``` + + -### **AI-Native Architecture** +### Step 6: Use Hooks -In a world where AI agents and robots are becoming autonomous and will permeate every single part of our lives, the machines need to have access and self-manage their own resources. WDK is the preferred choice for the digital entities of tomorrow, ensuring direct custody of funds, highly scalable transactions, and empowering the infinite AI economy of the future. +Now you can use the WDK hooks in any component inside `WdkAppProvider`: -*** +```tsx +import { useWdkApp, useWalletManager, useAccount } from '@tetherto/wdk-react-native-core' -## A world of opportunities +function WalletScreen() { + const { state } = useWdkApp() + const { createWallet, unlock } = useWalletManager() + const { address } = useAccount({ network: 'ethereum', accountIndex: 0 }) + + switch (state.status) { + case 'INITIALIZING': + return Loading... + case 'NO_WALLET': + return + ) } ``` -You can isolate quote failures from [`quoteSupply()`](../api-reference) (or the other `quote*` methods) when you only need an estimate: +*** -```javascript title="Handle quote errors" -try { - const q = await aave.quoteBorrow() - console.log('Borrow fee (wei):', q.fee) -} catch (e) -``` +## Custom Themes -See [Rules & Notes](../api-reference) for address and amount validation expectations. +### Brand Themes -## Best Practices +Apply your brand colors and fonts using `createThemeFromBrand`: -You can wipe private keys after lending work by calling [`dispose()`](/sdk/wallet-modules/wallet-evm/api-reference) on [`WalletAccountEvm`](/sdk/wallet-modules/wallet-evm/api-reference), or [`dispose()`](/sdk/wallet-modules/wallet-evm/api-reference) on [`WalletManagerEvm`](/sdk/wallet-modules/wallet-evm/api-reference): +```tsx title="Brand Theme Creation" +import { ThemeProvider, createThemeFromBrand } from '@tetherto/wdk-uikit-react-native' -```javascript title="Dispose after lending session" -try { - await aave.supply() -} finally +const brandTheme = createThemeFromBrand({ + primaryColor: '#007AFF', + secondaryColor: '#FF3B30', + fontFamily: { + regular: 'Inter-Regular', + bold: 'Inter-Bold', + }, +}, 'light') + + + {/* Your branded app */} + ``` -For ERC-4337 accounts, use [`dispose()`](/sdk/wallet-modules/wallet-evm-erc-4337/api-reference) on the smart-account type. Clear references to [`AaveProtocolEvm`](../api-reference) when the session ends. +**BrandConfig Interface** -## Next Steps +```typescript title="BrandConfig Type" +type BrandConfig = { + primaryColor: string + secondaryColor?: string + fontFamily?: { + regular?: string + medium?: string + semiBold?: string + bold?: string + } +} +``` -- [Lending operations](lending-operations) -- [Get started](get-started) -- [API reference](../api-reference) -## Lending Operations -URL: https://docs.wdk.tether.su/sdk/lending-modules/lending-aave-evm/guides/lending-operations -Description: Supply, withdraw, borrow, repay, quote fees, use ERC-4337, and read account data. -This guide walks through [supply](#supply), [withdraw](#withdraw), [borrow](#borrow), [repay](#repay), [quotes](#quotes-before-sending), [ERC-4337 usage](#erc-4337-smart-accounts), and [reading account data](#reading-account-data). It assumes an [`AaveProtocolEvm`](../api-reference) instance named `aave` and the USD₮ contract on Ethereum mainnet `0xdAC17F958D2ee523a2206206994597C13D831ec7`. +### Custom Theme -## Supply +Create a completely custom theme with full control over all design tokens: -You can deposit reserves into the pool using [`supply()`](../api-reference): +```tsx title="Custom Theme" +import { ThemeProvider } from '@tetherto/wdk-uikit-react-native' -```javascript title="Supply USDT" -const USDT = '0xdAC17F958D2ee523a2206206994597C13D831ec7' +const myLightTheme = { + mode: 'light' as const, + colors: { + primary: '#007AFF', + primaryLight: '#4DA6FF', + primaryDark: '#0056CC', + onPrimary: '#FFFFFF', + secondary: '#FF3B30', + secondaryLight: '#FF6B60', + secondaryDark: '#CC2F26', + background: '#FFFFFF', + surface: '#F9FAFB', + surfaceVariant: '#F3F4F6', + surfaceElevated: '#E5E7EB', + text: '#111827', + textSecondary: '#6B7280', + textDisabled: '#9CA3AF', + border: '#E5E7EB', + borderLight: '#F3F4F6', + error: '#EF4444', + warning: '#F59E0B', + success: '#10B981', + info: '#3B82F6', + }, + typography: { + fontFamily: { + regular: 'System', + medium: 'System', + semiBold: 'System', + bold: 'System' + }, + fontSize: { + xs: 10, sm: 12, base: 14, md: 16, lg: 18, xl: 20, xxl: 24, xxxl: 30 + }, + fontWeight: { + regular: '400', medium: '500', semiBold: '600', bold: '700' + }, + }, + spacing: { + xs: 4, sm: 8, base: 12, md: 16, lg: 24, xl: 32, xxl: 48, xxxl: 64 + }, + borderRadius: { + none: 0, sm: 4, md: 8, lg: 16, xl: 24, xxl: 32, full: 9999 + }, +} -const tx = await aave.supply() -console.log('Supply tx hash:', tx.hash) + + {/* Your app */} + ``` -## Withdraw - -You can remove supplied liquidity using [`withdraw()`](../api-reference): - -```javascript title="Withdraw USDT" -const USDT = '0xdAC17F958D2ee523a2206206994597C13D831ec7' +**Theme Interface** -const tx = await aave.withdraw() -console.log('Withdraw tx hash:', tx.hash) +```typescript title="Theme Type" +type Theme = { + mode: 'light' | 'dark' | 'auto' + colors: ColorPalette + typography: Typography + spacing: Spacing + borderRadius: BorderRadius + componentVariants?: ComponentVariant + componentOverrides?: ComponentOverrides +} ``` -## Borrow - -You can draw debt against your collateral using [`borrow()`](../api-reference): - -```javascript title="Borrow USDT" -const USDT = '0xdAC17F958D2ee523a2206206994597C13D831ec7' +*** -const tx = await aave.borrow() -console.log('Borrow tx hash:', tx.hash) -``` +## Component Customization -## Repay +You can customize the components with fine-grained control. -You can pay down debt using [`repay()`](../api-reference): +Fine-grained style overrides for specific component parts: -```javascript title="Repay USDT" -const USDT = '0xdAC17F958D2ee523a2206206994597C13D831ec7' +```tsx title="Component Overrides" + + {/* Your app */} + +``` -const tx = await aave.repay() -console.log('Repay tx hash:', tx.hash) +Set default visual variants per component: + +```tsx title="Component Variants" +const customTheme = { + ...lightTheme, + componentVariants: { + 'AmountInput.default': { /* variant styles */ }, + 'TransactionItem.compact': { /* variant styles */ } + } +} ``` -## Quotes before sending +*** -You can estimate the supply fee with [`quoteSupply()`](../api-reference): +## Using Theme Anywhere -```javascript title="Quote supply fee" -const USDT = '0xdAC17F958D2ee523a2206206994597C13D831ec7' +Access theme values anywhere in your components: -const supplyQuote = await aave.quoteSupply() -console.log('Supply fee (wei):', supplyQuote.fee) -``` +**useTheme Hook** -You can estimate the withdraw fee with [`quoteWithdraw()`](../api-reference): +```tsx title="useTheme Hook" +import { useTheme } from '@tetherto/wdk-uikit-react-native' -```javascript title="Quote withdraw fee" -const USDT = '0xdAC17F958D2ee523a2206206994597C13D831ec7' +function MyComponent() { + const { theme } = useTheme() -const withdrawQuote = await aave.quoteWithdraw() -console.log('Withdraw fee (wei):', withdrawQuote.fee) + return ( + + Hello World + + ) +} ``` -You can estimate the borrow fee with [`quoteBorrow()`](../api-reference): - -```javascript title="Quote borrow fee" -const USDT = '0xdAC17F958D2ee523a2206206994597C13D831ec7' +*** -const borrowQuote = await aave.quoteBorrow() -console.log('Borrow fee (wei):', borrowQuote.fee) -``` +## Theme Structure -You can estimate the repay fee with [`quoteRepay()`](../api-reference): +### Color Palette -```javascript title="Quote repay fee" -const USDT = '0xdAC17F958D2ee523a2206206994597C13D831ec7' +The theming system uses semantic naming for colors: -const repayQuote = await aave.quoteRepay() -console.log('Repay fee (wei):', repayQuote.fee) -``` +| Token | Purpose | +| ------------------------ | -------------------------------- | +| `colors.primary` | Primary brand color | +| `colors.primaryLight` | Light variant of primary | +| `colors.primaryDark` | Dark variant of primary | +| `colors.onPrimary` | Text color on primary background | +| `colors.secondary` | Secondary brand color | +| `colors.secondaryLight` | Light variant of secondary | +| `colors.secondaryDark` | Dark variant of secondary | +| `colors.background` | Main background color | +| `colors.surface` | Card/container background | +| `colors.surfaceVariant` | Alternative surface color | +| `colors.surfaceElevated` | Elevated surface color | +| `colors.text` | Primary text color | +| `colors.textSecondary` | Secondary text color | +| `colors.textDisabled` | Disabled text color | +| `colors.border` | Border color | +| `colors.borderLight` | Light border color | +| `colors.error` | Error state color | +| `colors.warning` | Warning state color | +| `colors.success` | Success state color | +| `colors.info` | Info state color | -Health factor and collateralization limits still apply. A quote does not guarantee the transaction will succeed if on-chain state changes. +### Typography -## ERC-4337 smart accounts +| Token | Purpose | +| -------------------------------- | ----------------------------- | +| `typography.fontFamily.regular` | Regular font family | +| `typography.fontFamily.medium` | Medium font family | +| `typography.fontFamily.semiBold` | Semi-bold font family | +| `typography.fontFamily.bold` | Bold font family | +| `typography.fontSize.xs` | Extra small font size (10px) | +| `typography.fontSize.sm` | Small font size (12px) | +| `typography.fontSize.base` | Base font size (14px) | +| `typography.fontSize.md` | Medium font size (16px) | +| `typography.fontSize.lg` | Large font size (18px) | +| `typography.fontSize.xl` | Extra large font size (20px) | +| `typography.fontSize.xxl` | 2X large font size (24px) | +| `typography.fontSize.xxxl` | 3X large font size (30px) | +| `typography.fontWeight.regular` | Regular font weight ('400') | +| `typography.fontWeight.medium` | Medium font weight ('500') | +| `typography.fontWeight.semiBold` | Semi-bold font weight ('600') | +| `typography.fontWeight.bold` | Bold font weight ('700') | -You can run the same methods through [`WalletAccountEvmErc4337`](/sdk/wallet-modules/wallet-evm-erc-4337/api-reference) and pass a second `config` argument to override per-call gas payment settings. In `v1.0.0-beta.4`, the lending methods accept the same override families as the wallet module: paymaster token, sponsorship policy, and native coins. See the [ERC-4337 config override](../api-reference) section for the full field list. +### Spacing -```javascript title="Supply with paymaster" -import from '@tetherto/wdk-wallet-evm-erc-4337' -import AaveProtocolEvm from '@tetherto/wdk-protocol-lending-aave-evm' +| Token | Purpose | +| -------------- | -------------------------- | +| `spacing.xs` | Extra small spacing (4px) | +| `spacing.sm` | Small spacing (8px) | +| `spacing.base` | Base spacing (12px) | +| `spacing.md` | Medium spacing (16px) | +| `spacing.lg` | Large spacing (24px) | +| `spacing.xl` | Extra large spacing (32px) | +| `spacing.xxl` | 2X large spacing (48px) | +| `spacing.xxxl` | 3X large spacing (64px) | -const aa = new WalletAccountEvmErc4337(seedPhrase, "0'/0/0", ) +### Border Radius -const aaveAA = new AaveProtocolEvm(aa) +| Token | Purpose | +| ------------------- | -------------------------------- | +| `borderRadius.none` | No border radius (0px) | +| `borderRadius.sm` | Small border radius (4px) | +| `borderRadius.md` | Medium border radius (8px) | +| `borderRadius.lg` | Large border radius (16px) | +| `borderRadius.xl` | Extra large border radius (24px) | +| `borderRadius.xxl` | 2X large border radius (32px) | +| `borderRadius.full` | Full border radius (9999px) | -const result = await aaveAA.supply( - , - { - paymasterToken: - } -) -console.log('Supply hash:', result.hash) -``` +*** -You can use the same second argument to: +## Advanced Usage -- override paymaster-token mode with `paymasterUrl`, `paymasterAddress`, `paymasterToken`, or `transferMaxFee` -- switch one call to sponsorship mode with `isSponsored`, `paymasterUrl`, and `sponsorshipPolicyId` -- switch one call to native-coin gas mode with `useNativeCoins` and `transferMaxFee` +**Dynamic Theme Updates** -Use token addresses that exist on the same chain as the smart account RPC. +Update themes dynamically at runtime: -## Reading account data +```tsx title="Dynamic Theme Updates" +function Settings() { + const { setBrandConfig, setComponentOverrides } = useTheme() -You can inspect collateral, debt, and health using [`getAccountData()`](../api-reference): + const updateBrand = () => { + setBrandConfig({ + primaryColor: '#FF6501', + }) + } -```javascript title="Read Aave account data" -const data = await aave.getAccountData() + const customizeTransactions = () => { + setComponentOverrides({ + TransactionItem: { + container: { + backgroundColor: 'rgba(255, 101, 1, 0.1)', + }, + }, + }) + } -console.log() + return ( + <> + + + + ) +} ``` ## Next Steps -- [Handle errors](handle-errors) -- [Get started](get-started) -- [API reference](../api-reference) -## Lending Aave EVM Guides -URL: https://docs.wdk.tether.su/sdk/lending-modules/lending-aave-evm/usage -Description: How to install and use @tetherto/wdk-protocol-lending-aave-evm on EVM -# Usage +* [Get Started](get-started) - Quick start guide for the UI Kit +* [Components List](api-reference) - Complete API Reference for all components +* [React Native Quickstart](../../start-building/react-native-quickstart) - See theming in action -The [@tetherto/wdk-protocol-lending-aave-evm](https://www.npmjs.com/package/@tetherto/wdk-protocol-lending-aave-evm) module exposes Aave V3 supply, borrow, and repayment flows for EVM accounts. Follow the guides below for setup, day-to-day operations, and error handling. +*** -Install the package, create AaveProtocolEvm, and review prerequisites. +## Need Help? -Supply, withdraw, borrow, repay, quotes, ERC-4337, and account data. + -Handle failures and dispose wallet secrets when finished. -Get started with WDK in a Node.js environment +# API Reference (/tools/indexer-api/api-reference) -Networks and deployment settings for the Aave lending protocol -Methods and parameters for AaveProtocolEvm -## Swap Modules Overview -URL: https://docs.wdk.tether.su/sdk/swap-modules -Description: Explore WDK swap modules for token swap integrations across supported providers. -The Swap Development Kit (WDK) provides a set of modules that support swap on top of multiple blockchain networks. All modules share a common interface, ensuring consistent behavior across different blockchain implementations. -## Swap Protocol Modules +## Base URL -DeFi swap functionality for token exchanges across different DEXs: +```text title="API Base URL" +https://wdk-api.tether.io +``` -| Module | Blockchain | Status | Documentation | -|--------|------------|--------|---------------| -| [`@tetherto/wdk-protocol-swap-velora-evm`](https://github.com/tetherto/wdk-protocol-swap-velora-evm) | EVM | ✅ Ready | [Documentation](./swap-velora-evm/) | -| `@tetherto/wdk-protocol-swap-stonfi-ton` | TON | In progress | Coming soon | +*** -## Next steps +## Authentication -To get started with WDK modules, follow these steps: +All requests require a valid API key in the `x-api-key` header: -1. Get up and running quickly with our [Quickstart Guide](../../start-building/nodejs-bare-quickstart) -2. Choose the modules that best fit your needs from the tables above -3. Check specific documentation for modules you wish to use +```http title="Authentication Header" +x-api-key: your-api-key-here +``` -You can also: + + **Don't have an API key yet?** Request one by following the steps in our [Get Started](get-started) guide. + -- Learn about key concepts like [Account Abstraction](../../resources/concepts#account-abstraction) and other important definitions -- Use one of our ready-to-use examples to be production ready -## Swap velora EVM Overview -URL: https://docs.wdk.tether.su/sdk/swap-modules/swap-velora-evm -Description: Overview of the @tetherto/wdk-protocol-swap-velora-evm module -A lightweight package that lets EVM wallet accounts swap tokens using the velora aggregator. It provides a clean SDK for token swaps on EVM chains and works with both standard wallets and ERC‑4337 smart accounts. +*** -## Features +## Rate Limiting -- **Token Swapping**: Execute token swaps through velora on supported EVM networks -- **Account Abstraction**: Compatible with standard EVM accounts and ERC‑4337 smart accounts -- **Fee Controls**: Optional `swapMaxFee` to cap gas costs -- **Allowance Safety**: Handles USD₮ mainnet pattern (reset allowance to 0 before approve) -- **Provider Flexibility**: Works with JSON‑RPC URLs and EIP‑1193 providers -- **TypeScript Support**: Full TypeScript definitions included +| Endpoint | Limit | +| --------------------------------------------------------- | --------------- | +| `GET /api/v1/health` | 10 req / 1 hour | +| `GET /api/v1/chains` | 60 req / 1 min | +| `GET /api/v1/:blockchain/:token/:address/token-balances` | 4 req / 10s | +| `GET /api/v1/:blockchain/:token/:address/token-transfers` | 8 req / 10s | +| `POST /api/v1/batch/token-transfers` | 8 req / 10s | +| `POST /api/v1/batch/token-balances` | 4 req / 10s | -## Supported Networks +*** -Works with EVM networks supported by velora (e.g., Ethereum, Polygon, Arbitrum, etc.). A working RPC provider is required. +## API Endpoints -## Wallet Compatibility +### `GET /api/v1/health` -The swap service supports multiple EVM wallet types: +Check API server status -- **Standard EVM Wallets**: `@tetherto/wdk-wallet-evm` accounts -- **ERC‑4337 Smart Accounts**: `@tetherto/wdk-wallet-evm-erc-4337` accounts with bundler/paymaster -- **Read‑Only Accounts**: For quoting swaps without sending transactions +*** -## Key Components +### `GET /api/v1/chains` -- **velora Integration**: Uses velora aggregator for routing and quotes -- **Quote System**: Pre‑transaction fee and amount estimation via `quoteSwap` -- **AA Integration**: Optional paymaster token and fee cap overrides when using ERC‑4337 -- **Allowance Management**: Approve flow handled automatically when required +Get list of supported chains and tokens -## Next Steps +*** + +### `GET /api/v1/{blockchain}/{token}/{address}/token-transfers` -Get started with WDK in a Node.js environment +Get token transfer history for an address -Get started with WDK's velora Swap Protocol configuration +*** -Get started with WDK's velora Swap Protocol API +### `GET /api/v1/{blockchain}/{token}/{address}/token-balances` -Get started with WDK's velora Swap Protocol usage +Get current token balance for an address *** -## Need Help? -## API Reference -URL: https://docs.wdk.tether.su/sdk/swap-modules/swap-velora-evm/api-reference -Description: API Reference for @tetherto/wdk-protocol-swap-velora-evm -## Class: VeloraProtocolEvm +### `POST /api/v1/batch/token-transfers` -Main class for velora token swaps on EVM. +Get batch token transfers for multiple addresses -### Constructor +*** -```javascript -new VeloraProtocolEvm(account, config?) -``` +### `POST /api/v1/batch/token-balances` -Parameters: -- `account`: `WalletAccountEvm | WalletAccountReadOnlyEvm | WalletAccountEvmErc4337 | WalletAccountReadOnlyEvmErc4337` -- `config` (optional): - - `swapMaxFee` (`bigint`): maximum total gas fee allowed (wei) +Get batch token balances for multiple addresses -Example: +*** -```javascript -const swap = new VeloraProtocolEvm(account, ) -``` +## Error Handling -### Methods +The API returns standard HTTP error codes: -| Method | Description | Returns | -|--------|-------------|---------| -| `swap(options, config?)` | Perform a token swap | `Promise` | -| `quoteSwap(options, config?)` | Get estimated fee and amounts | `Promise` | +| Status Code | Description | +| ----------- | --------------------------------------- | +| 400 | Bad Request - Invalid parameters | +| 401 | Unauthorized - Invalid API key | +| 404 | Not Found - Resource not found | +| 429 | Too Many Requests - Rate limit exceeded | +| 500 | Internal Server Error | ---- +### Error Response Format -### `swap(options, config?)` -Execute a swap via velora. +```json +{ + "error": "error_type", + "message": "Detailed error message" +} +``` -Options: -- `tokenIn` (`string`): Address of the ERC‑20 token to sell -- `tokenOut` (`string`): Address of the ERC‑20 token to buy -- `tokenInAmount` (`bigint`, optional): Exact input amount (base units) -- `tokenOutAmount` (`bigint`, optional): Exact output amount (base units) -- `to` (`string`, optional): Recipient address (defaults to account address) +*** -Config (ERC‑4337 only): -- `paymasterToken` (`string`, optional): Token symbol/address for fee sponsorship -- `swapMaxFee` (`bigint`, optional): Per‑swap fee cap (wei) +## Next Steps -Returns: -- Standard account: `` -- ERC‑4337 account: `` (approve may be bundled) +* [**Get Started**](get-started) - Quick start guide with setup instructions +* [**React Native Starter**](../../examples-and-starters/react-native-starter) - See it in action -Notes: -- On Ethereum mainnet, selling USD₮ may first set allowance to 0, then approve. -- Requires a provider; requires a non read‑only account to send transactions. +*** -Example: +## Need Help? -```javascript -const tx = await swap.swap() -``` + ---- -### `quoteSwap(options, config?)` -Get estimated fee and token in/out amounts. +# Get Started (/tools/indexer-api/get-started) -Options are the same as `swap`. -Returns: `` -Config (ERC‑4337 only): -- `paymasterToken` (`string`, optional): Token symbol/address for fee sponsorship +## Getting Started -Works with read‑only accounts. + + + #### Request API Key -Example: + Request your free API key to access the WDK Indexer API. -```javascript -const quote = await swap.quoteSwap() -``` + [Request API Key](https://wdk-api.tether.io/register) + ---- + + #### Make Your First Request -## Errors + Use your API key to query blockchain data via the REST API. + + -Common errors include: -- Insufficient liquidity / no route for pair -- Fee exceeds `swapMaxFee` -- Read‑only account cannot send swaps -- Provider/RPC errors (invalid endpoint, network mismatch) +*** ---- +## Quick Example -## Types +Here's a quick example of how to query a token balance. -- `swapMaxFee: bigint` — Upper bound for gas fees (wei) -- `tokenInAmount/tokenOutAmount: bigint` — ERC‑20 base units -- `paymasterToken: string` — token symbol or address (AA only) + + + ```bash + curl -X GET "https://wdk-api.tether.io/api/v1/ethereum/usdt/0xdac17f958d2ee523a2206206994597c13d831ec7/token-balances" \ + -H "x-api-key: your-api-key-here" + ``` + + + + ```javascript + const axios = require('axios'); + + async function getTokenBalance(blockchain, token, address) { + const response = await axios.get( + `https://wdk-api.tether.io/api/v1/${blockchain}/${token}/${address}/token-balances`, + { + headers: { + 'x-api-key': 'your-api-key-here' + } + } + ); -Get started with WDK in a Node.js environment + return response.data.tokenBalance; + } -Get started with WDK's Swap velora EVM Protocol configuration + const balance = await getTokenBalance('ethereum', 'usdt', '0xdac17f958d2ee523a2206206994597c13d831ec7'); + console.log(`Balance: ${balance.amount} ${balance.token.toUpperCase()}`); + ``` + + -Get started with WDK's Swap velora EVM Protocol usage + + **Want more info?** Check out the complete [API Reference](api-reference) for detailed method documentation, parameters, and response formats. + + +*** + +## Next Steps + +* [**API Reference**](api-reference) - Complete method documentation with examples and response formats *** ## Need Help? -## Configuration -URL: https://docs.wdk.tether.su/sdk/swap-modules/swap-velora-evm/configuration -Description: Configuration options and settings for @tetherto/wdk-protocol-swap-velora-evm -## Swap Service Configuration -The `VeloraProtocolEvm` accepts a configuration object that defines fee controls and behavior: + -```javascript -import VeloraProtocolEvm from '@tetherto/wdk-protocol-swap-velora-evm' -import from '@tetherto/wdk-wallet-evm' -// Create wallet account first -const account = new WalletAccountEvm(seedPhrase, "0'/0/0", ) +# Indexer API (/tools/indexer-api) -// Create swap service with configuration -const swapProtocol = new VeloraProtocolEvm(account, ) -``` -## Account Configuration -The swap service uses the wallet account configuration for network access and signing: +The WDK Indexer REST API provides fast, reliable access to balances, token transfers, and transaction history across multiple chains. -```javascript -import from '@tetherto/wdk-wallet-evm' + + A blockchain indexer continuously monitors and organizes blockchain transactions, making them instantly searchable through a simple REST API. + -// Full access account -const account = new WalletAccountEvm( - seedPhrase, - "0'/0/0", - -) +[Get Started](./get-started) -// Read-only account (quotes only) -const readOnly = new WalletAccountReadOnlyEvm( - '0xYourAddress', - -) +## Supported Chains and Tokens -// Create swap service -const swapProtocol = new VeloraProtocolEvm(account, ) -``` +The WDK Indexer currently supports the following blockchain networks and tokens: -## Configuration Options +| Blockchain | Supported Tokens | +| ---------------- | ---------------- | +| Ethereum Mainnet | USD₮, XAU₮, USA₮ | +| TON | USD₮, XAU₮ | +| TRON | USD₮ | +| Arbitrum | USD₮ | +| Sepolia | USD₮ | +| Plasma | USD₮, XAU₮ | +| Polygon | USD₮ | +| Bitcoin | BTC | +| Spark | BTC | -### Swap Max Fee +To get the most up-to-date list of supported chains and their tokens, use the \[`/api/v1/chains`] endpoint. -The `swapMaxFee` option sets an upper bound for total gas costs to prevent excessive fees. + + **Need support for a new chain or token?** Submit a request using the form below and our team will review it. + -**Type:** `bigint` (optional) -**Unit:** Wei +[Request Chain / Token Support](https://forms.gle/ZsuLmGNemSVEvvoA9) -**Examples:** +*** -```javascript -const config = +## Next Steps -// Usage example -try { - const result = await swapProtocol.swap() -} catch (error) { - if (error.message.includes('max fee')) -} -``` + + + Learn how to make your first API call + -## ERC‑4337 (Account Abstraction) Configuration + + Endpoints, parameters, and responses + + -When using ERC‑4337 smart accounts (`@tetherto/wdk-wallet-evm-erc-4337`), you can override fee behavior per swap and specify a paymaster token: +## Need Help? -```javascript -import from '@tetherto/wdk-wallet-evm-erc-4337' + -const aa = new WalletAccountEvmErc4337(seedPhrase, "0'/0/0", ) -const swapAA = new VeloraProtocolEvm(aa, ) +# Failover Provider API Reference (/tools/failover-provider/api-reference) -const result = await swapAA.swap(, ) -``` -### Paymaster Token (ERC‑4337) -The `paymasterToken` option indicates which token the paymaster should use to sponsor gas. +# API Reference -**Type:** `string` (optional) -**Format:** Token symbol or address +## Package: `@tetherto/wdk-failover-provider` -**Example:** +### Class: `FailoverProvider\` -```javascript -const result = await swapAA.swap(, ) +`FailoverProvider\` collects provider candidates of one shared shape and returns a proxied `T` that retries failed calls against the next provider. + +#### Constructor + +Use the constructor to set retry behavior before you add provider candidates: + +```javascript title="Create A FailoverProvider Factory" +new FailoverProvider({ + retries, // optional, defaults to 3 + shouldRetryOn // optional, defaults to (error) => error instanceof Error +}) ``` -## Network Support +* `retries` (`number`, optional): Number of additional attempts after the first failure. Total attempts are `1 + retries`. +* `shouldRetryOn` (`(error: Error) =\> boolean`, optional): Predicate that decides whether the proxy should switch to the next provider after a failure. -velora supports multiple EVM networks (e.g., Ethereum, Polygon, Arbitrum). Ensure your account is configured with a valid provider for the target network. +#### Methods -```javascript -// Ethereum Mainnet -const eth = new WalletAccountEvm(seedPhrase, "0'/0/0", ) +| Method | Description | Returns | +| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------- | +| `addProvider(provider)` | Register one provider candidate and return the same factory so you can chain more candidates. | `FailoverProvider\` | +| `initialize()` | Return a proxied provider of type `T` that reads from the active provider and retries failed calls against the next provider. | `T` | -// Polygon -const polygon = new WalletAccountEvm(seedPhrase, "0'/0/0", ) +#### `addProvider(provider)` + +Register a provider candidate. Every candidate should satisfy the same `T` shape because `initialize()` returns one proxied `T`. + +```javascript title="Register A Provider Candidate" +const factory = new FailoverProvider({ retries: 1 }) + +factory.addProvider({ + name: 'primary', + async getBlockNumber () { + return 21345678 + } +}) ``` -## Swap Options +#### `initialize()` -When calling `swap`, provide the swap parameters: +Create the failover-enabled proxy after you have added at least one provider. The runtime throws if the factory is still empty. -```javascript -const swapOptions = +```javascript title="Initialize The Failover Proxy" +const provider = new FailoverProvider({ retries: 1 }) + .addProvider(primary) + .addProvider(secondary) + .initialize() -const result = await swapProtocol.swap(swapOptions) +const blockNumber = await provider.getBlockNumber() ``` -### Parameters - -- `tokenIn` (`string`): ERC‑20 address to sell -- `tokenOut` (`string`): ERC‑20 address to buy -- `tokenInAmount` (`bigint`, optional): exact input amount in token base units -- `tokenOutAmount` (`bigint`, optional): exact output amount in token base units -- `to` (`string`, optional): recipient address (defaults to account address) +#### `FailoverProviderConfig` -> Note: Use either `tokenInAmount` OR `tokenOutAmount`, not both. +The package exports the `FailoverProviderConfig` type through its top-level type surface. -Get started with WDK in a Node.js environment +| Field | Description | +| ---------------- | --------------------------------------------------------------------------------------------------- | +| `retries?` | Additional retry attempts after the first failure. Defaults to `3`. | +| `shouldRetryOn?` | Retry predicate for thrown errors and rejected promises. Defaults to retrying any `Error` instance. | -Get started with WDK's velora Swap Protocol API +## Runtime behavior -Get started with WDK's velora Swap Protocol usage +* `initialize()` returns a JavaScript `Proxy` over the first added provider. +* Non-function properties are forwarded from the currently active provider. +* If a property getter throws and `shouldRetryOn(error)` returns `true`, the runtime advances to the next provider before retrying the property access. +* If a synchronous method throws and `shouldRetryOn(error)` returns `true`, the runtime advances to the next provider and retries the method call. +* If an asynchronous method rejects and `shouldRetryOn(error)` returns `true`, the runtime advances to the next provider and retries the method call. +* Provider switching is round-robin. If the active provider already changed while another call was failing, the runtime keeps the newer active provider instead of advancing twice. -*** +## Example -## Need Help? -## Execute Swaps -URL: https://docs.wdk.tether.su/sdk/swap-modules/swap-velora-evm/guides/execute-swaps -Description: Run exact-input swaps, exact-output swaps, and swaps with ERC-4337 accounts. -This guide explains how to run a [basic exact-input swap](#basic-exact-input-swap), an [exact-output swap](#exact-output-swap), and a [swap from an ERC-4337 smart account](#swap-with-erc-4337). You should already have a [`VeloraProtocolEvm`](../api-reference) instance. +This example shows a transient failure on the first provider and a successful retry on the second provider: -Swaps spend tokens and gas on-chain. Use amounts you control and an RPC you trust. +```javascript title="Retry Across Two Providers" +import FailoverProvider from '@tetherto/wdk-failover-provider' -## Basic exact-input swap +const primary = { + async getBlockNumber () { + throw new Error('temporary upstream outage') + } +} -You can sell an exact amount of the input token using [`swap()`](../api-reference): +const secondary = { + async getBlockNumber () { + return 21345678 + } +} -```javascript title="Exact input: USDT to WETH" -const result = await swapProtocol.swap() +const provider = new FailoverProvider({ + retries: 1, + shouldRetryOn: (error) => error.message.includes('temporary') +}) + .addProvider(primary) + .addProvider(secondary) + .initialize() -console.log('Swap transaction hash:', result.hash) -console.log('Total fee (wei):', result.fee) -console.log('Tokens sold (base units):', result.tokenInAmount) -console.log('Tokens bought (base units):', result.tokenOutAmount) +const blockNumber = await provider.getBlockNumber() ``` -## Exact output swap +*** -You can receive an exact amount of the output token by passing `tokenOutAmount` to [`swap()`](../api-reference): +## Need Help? -```javascript title="Exact output amount" -const result = await swapProtocol.swap() + -console.log('Swap hash:', result.hash) -console.log('Tokens sold (base units):', result.tokenInAmount) -console.log('Tokens bought (base units):', result.tokenOutAmount) -``` -## Swap with ERC-4337 +# Failover Provider Configuration (/tools/failover-provider/configuration) -You can perform a user-operation-backed swap by constructing [`VeloraProtocolEvm`](../api-reference) with [`WalletAccountEvmErc4337`](../../../wallet-modules/wallet-evm-erc-4337/api-reference) and passing paymaster options to [`swap()`](../api-reference): -```javascript title="Swap with smart account and paymaster" -import from '@tetherto/wdk-wallet-evm-erc-4337' -import VeloraProtocolEvm from '@tetherto/wdk-protocol-swap-velora-evm' -const aa = new WalletAccountEvmErc4337(seedPhrase, "0'/0/0", ) +This page shows how to install `@tetherto/wdk-failover-provider`, configure `retries` and `shouldRetryOn`, and build a proxied provider with `addProvider()` and `initialize()`. -const swapAA = new VeloraProtocolEvm(aa, ) +## Install the package -const result = await swapAA.swap(, ) +You can install the package from npm: -console.log('Swap hash:', result.hash) -console.log('Total fee (wei):', result.fee) +```bash title="Install @tetherto/wdk-failover-provider" +npm install @tetherto/wdk-failover-provider ``` -Token addresses must match the chain your account uses (for example, mainnet USD₮ addresses differ from Arbitrum). +## Create a failover provider -## Next Steps +You can wrap any provider-like object type. This example uses plain objects so the retry behavior is easy to see: -- [Get swap quotes](get-swap-quotes) before sending -- [Handle errors](handle-errors) -- [Get started](get-started) if you still need setup -## Get Started -URL: https://docs.wdk.tether.su/sdk/swap-modules/swap-velora-evm/guides/get-started -Description: Install the package, create VeloraProtocolEvm, and learn supported networks. -This guide covers [installation](#installation), [create the swap protocol](#create-the-swap-protocol), and [supported networks](#supported-networks). You need [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) to follow along. +```javascript title="Create A Failover Provider" +import FailoverProvider from '@tetherto/wdk-failover-provider' -## Installation +const primary = { + name: 'primary', + async getBlockNumber () { + throw new Error('temporary upstream outage') + } +} -Run the following to install [@tetherto/wdk-protocol-swap-velora-evm](https://www.npmjs.com/package/@tetherto/wdk-protocol-swap-velora-evm): +const secondary = { + name: 'secondary', + async getBlockNumber () { + return 21345678 + } +} -```bash title="Install with npm" -npm install @tetherto/wdk-protocol-swap-velora-evm +const provider = new FailoverProvider({ + retries: 1, + shouldRetryOn: (error) => error.message.includes('temporary') +}) + .addProvider(primary) + .addProvider(secondary) + .initialize() ``` -You also need an EVM wallet account from [`@tetherto/wdk-wallet-evm`](https://www.npmjs.com/package/@tetherto/wdk-wallet-evm) (or an ERC-4337 account from [`@tetherto/wdk-wallet-evm-erc-4337`](https://www.npmjs.com/package/@tetherto/wdk-wallet-evm-erc-4337)) on the same chain as your RPC provider. +## Configuration options + +### `retries` -## Create the swap protocol +`retries` controls how many additional attempts happen after the first failure. The published runtime defaults to `3`, which means a call can make up to `1 + retries` total attempts before the latest error is thrown. -You can construct a swap client with [`new VeloraProtocolEvm(account, config?)`](../api-reference) on top of [`VeloraProtocolEvm`](../api-reference): +### `shouldRetryOn` -```javascript title="Create VeloraProtocolEvm" -import VeloraProtocolEvm from '@tetherto/wdk-protocol-swap-velora-evm' -import from '@tetherto/wdk-wallet-evm' +`shouldRetryOn(error)` decides whether a thrown error or rejected promise should advance to the next provider. The published default retries on any `Error` instance. -const account = new WalletAccountEvm(seedPhrase, "0'/0/0", ) +Use a narrow predicate when you only want to retry transient failures: -const swapProtocol = new VeloraProtocolEvm(account, ) +```javascript title="Retry Only On Transient Errors" +const provider = new FailoverProvider({ + retries: 2, + shouldRetryOn: (error) => /timeout|temporary|429/.test(error.message) +}) ``` -Optional `swapMaxFee` caps the total gas fee in wei for swaps. See [configuration](../configuration) for environment-specific settings. +## Register provider candidates -## Supported networks +Call `addProvider(provider)` once per candidate before you call `initialize()`. `addProvider()` returns the same `FailoverProvider` instance, so you can chain the calls. -Velora routing works on EVM networks the aggregator supports, including **Ethereum**, **Polygon**, **Arbitrum**, and other chains where Velora exposes liquidity. Use an RPC endpoint for the network your [`WalletAccountEvm`](../../../wallet-modules/wallet-evm/api-reference) is configured for so [`swap()`](../api-reference) and [`quoteSwap()`](../api-reference) target the correct chain. +The generic type `T` applies to every added candidate, so keep the provider shape consistent across the chain. -## Next Steps +```javascript title="Add Multiple Provider Candidates" +const provider = new FailoverProvider({ retries: 2 }) + .addProvider(primary) + .addProvider(secondary) + .addProvider({ + name: 'tertiary', + async getBlockNumber () { + return 21345679 + } + }) + .initialize() +``` -- [Execute swaps](execute-swaps) -- [Get swap quotes](get-swap-quotes) -- [Handle errors](handle-errors) -## Get Swap Quotes -URL: https://docs.wdk.tether.su/sdk/swap-modules/swap-velora-evm/guides/get-swap-quotes -Description: Estimate fees and amounts with quoteSwap before executing a swap. -This guide shows how to [quote before swapping](#quote-before-swapping) and use quotes for [fee estimation](#fee-estimation). Quotes use [`quoteSwap()`](../api-reference), which works with read-only accounts as well as signing accounts. +## Initialize the proxy -## Quote before swapping +Call `initialize()` after you have added at least one provider. The returned value is a proxied provider of type `T`. -You can preview fee and token amounts for the same parameters you would pass to [`swap()`](../api-reference) using [`quoteSwap()`](../api-reference): +The runtime throws if you call `initialize()` before adding any providers: -```javascript title="Quote exact input swap" -const quote = await swapProtocol.quoteSwap() +```javascript title="Initialize Requires At Least One Provider" +const factory = new FailoverProvider() -console.log('Estimated fee (wei):', quote.fee) -console.log('Tokens in (base units):', quote.tokenInAmount) -console.log('Tokens out (base units):', quote.tokenOutAmount) +factory.initialize() +// Error: Cannot initialize an empty provider. Call `addProvider` before this function. ``` -You can quote an exact-output style trade the same way by passing `tokenOutAmount` instead of `tokenInAmount` to [`quoteSwap()`](../api-reference): +## Runtime notes -```javascript title="Quote exact output swap" -const quote = await swapProtocol.quoteSwap() +* Non-function properties are read from the currently active provider. +* When a synchronous method throws and `shouldRetryOn(error)` returns `true`, the proxy switches to the next provider and retries. +* When an asynchronous method rejects and `shouldRetryOn(error)` returns `true`, the proxy switches to the next provider and retries. +* Provider selection advances in round-robin order. If `retries` is larger than the number of providers, the runtime loops back through the list. -console.log('Estimated fee (wei):', quote.fee) -console.log('Required token in (base units):', quote.tokenInAmount) -``` +*** -## Fee estimation +## Need Help? -You can read `quote.fee` from [`quoteSwap()`](../api-reference) as the estimated total swap fee in wei before calling [`swap()`](../api-reference): + -```javascript title="Quote fee before deciding" -const quote = await swapProtocol.quoteSwap() -const maxFee = 200000000000000n -console.log('Quoted fee (wei):', quote.fee, 'cap:', maxFee) -``` +# Failover Provider (/tools/failover-provider) -You can compare that estimate to `swapMaxFee` on [`VeloraProtocolEvm`](../api-reference) and only then call [`swap()`](../api-reference) when the quote is within your cap: -```javascript title="Swap when fee is under cap" -const maxFee = 200000000000000n -const quote = await swapProtocol.quoteSwap() -if (quote.fee -On-chain conditions can change between quote and execution. The executed [`swap()`](../api-reference) may still differ slightly from the last [`quoteSwap()`](../api-reference) result. +Failover Provider wraps multiple provider-like objects behind one proxy so your integration can retry failed calls against the next candidate without rewriting each call site. Use this page to review the [Configuration](./configuration) and [API Reference](./api-reference) for the released `@tetherto/wdk-failover-provider` surface. -## Next Steps +Powered by [`@tetherto/wdk-failover-provider`](https://github.com/tetherto/wdk-failover-provider). -- [Execute swaps](execute-swaps) -- [Handle errors](handle-errors) -- [Get started](get-started) -## Handle Errors -URL: https://docs.wdk.tether.su/sdk/swap-modules/swap-velora-evm/guides/handle-errors -Description: Catch swap failures, interpret common messages, and clean up sensitive state. -This guide covers [swap errors](#swap-errors), [quote errors](#quote-errors), and [best practices](#best-practices) for clearing wallet material after use. +## Features -## Swap errors +* **Generic provider wrapper**: `FailoverProvider\` accepts any provider-like object type and returns a proxied `T` from `initialize()`. +* **Configurable retries**: Set `retries` to control how many additional attempts happen after the first failure. +* **Retry predicate**: Use `shouldRetryOn(error)` to decide which errors should advance to the next provider. +* **Sync and async failover**: The runtime retries both synchronous throws and rejected promises. +* **Zero runtime dependencies**: The published package ships a single default export with no runtime dependency tree. -You can detect failed swaps by wrapping [`swap()`](../api-reference) in `try/catch` and inspecting `error.message`: +## Why this matters -```javascript title="Handle swap failures" -try { - const result = await swapProtocol.swap() - console.log('Swap successful:', result.hash) -} catch (error) { - console.error('Swap failed:', error.message) +* You can keep one provider-shaped integration surface while rotating between browser, JSON-RPC, or custom provider implementations. +* You can narrow failover behavior to transient errors instead of retrying every exception. +* You can add redundancy to read-heavy or submission-heavy flows without building your own retry proxy. - if (error.message.includes('liquidity')) - if (error.message.includes('max fee')) - if (error.message.includes('read-only')) -} -``` + + + Install the package, add provider candidates, and tune retry behavior. + -Match string fragments only as a convenience; production apps should prefer stable error codes from your runtime when available. + + Review `FailoverProvider`, its config, and the proxied runtime behavior. + + -## Quote errors +*** -You can handle failures from [`quoteSwap()`](../api-reference) the same way, including provider or routing errors: +## Need Help? -```javascript title="Handle quote failures" -try { - const quote = await swapProtocol.quoteSwap() - console.log('Quoted fee (wei):', quote.fee) -} catch (error) -``` + -Common causes are listed under [Errors](../api-reference) in the API reference (liquidity, fee cap, read-only send attempts, RPC issues). -## Best Practices +# Wallet Modules Overview (/sdk/wallet-modules) -You can clear signing material when a session ends by calling [`dispose()`](../../../wallet-modules/wallet-evm/api-reference) on each [`WalletAccountEvm`](../../../wallet-modules/wallet-evm/api-reference), or [`dispose()`](../../../wallet-modules/wallet-evm/api-reference) on [`WalletManagerEvm`](../../../wallet-modules/wallet-evm/api-reference) if you use a manager: -```javascript title="Dispose wallet accounts" -try { - await swapProtocol.swap() -} finally -``` -If you use an ERC-4337 account, call [`dispose()`](../../../wallet-modules/wallet-evm-erc-4337/api-reference) on that account type per its API reference. Drop references to your [`VeloraProtocolEvm`](../api-reference) instance when you no longer need it. - -## Next Steps - -- [Get swap quotes](get-swap-quotes) -- [Execute swaps](execute-swaps) -- [API reference](../api-reference) -## Swap velora EVM Guides -URL: https://docs.wdk.tether.su/sdk/swap-modules/swap-velora-evm/usage -Description: How to install and use @tetherto/wdk-protocol-swap-velora-evm for swapping tokens on EVM -# Usage - -The [@tetherto/wdk-protocol-swap-velora-evm](https://www.npmjs.com/package/@tetherto/wdk-protocol-swap-velora-evm) module routes ERC-20 swaps on EVM chains through Velora. Use the guides below for setup, execution, quotes, and error handling. - -Install the package, create VeloraProtocolEvm, and review supported networks. - -Exact-input and exact-output swaps, including ERC-4337 smart accounts. - -Quote before swapping and compare fees to your max fee cap. - -Handle swap and quote failures and dispose wallet state safely. - -Get started with WDK in a Node.js environment - -RPC, fee limits, and environment settings for the Velora swap protocol - -Methods, options, and error notes for VeloraProtocolEvm -## Wallet Modules Overview -URL: https://docs.wdk.tether.su/sdk/wallet-modules -Description: Explore WDK wallet modules for building self-custodial wallets across supported chains. The Wallet Development Kit (WDK) provides a set of modules that support multiple blockchain networks. All modules share a common interface, ensuring consistent behavior across different blockchain implementations. ## Supported Networks This package works with multiple blockchain networks through wallet registration. -Bitcoin Mainnet + + + Bitcoin Mainnet + -Ethereum, Sepolia Testnet, L2s, etc. + + Ethereum, Sepolia Testnet, L2s, etc. + -Tron Mainnet + + Tron Mainnet + -TON Mainnet + + TON Mainnet + -Solana Mainnet + + Solana Mainnet + -Spark Mainnet + + Spark Mainnet + + ## Classic Wallet Modules Standard wallet implementations that use native blockchain tokens for transaction fees: -| Module | Blockchain | Status | Documentation | -|--------|------------|--------|---------------| -| [`@tetherto/wdk-wallet-evm`](https://github.com/tetherto/wdk-wallet-evm) | EVM | ✅ Ready | [Documentation](./wallet-evm) | -| [`@tetherto/wdk-wallet-ton`](https://github.com/tetherto/wdk-wallet-ton) | TON | ✅ Ready | [Documentation](./wallet-ton) | -| [`@tetherto/wdk-wallet-btc`](https://github.com/tetherto/wdk-wallet-btc) | Bitcoin | ✅ Ready | [Documentation](./wallet-btc) | -| [`@tetherto/wdk-wallet-spark`](https://github.com/tetherto/wdk-wallet-spark) | Spark | ✅ Ready | [Documentation](./wallet-spark) | -| [`@tetherto/wdk-wallet-tron`](https://github.com/tetherto/wdk-wallet-tron) | TRON | ✅ Ready | [Documentation](./wallet-tron) | -| [`@tetherto/wdk-wallet-solana`](https://github.com/tetherto/wdk-wallet-solana) | Solana | ✅ Ready | [Documentation](./wallet-solana) | -| `@tetherto/wdk-wallet-ark` | Ark | In progress | - | +| Module | Blockchain | Status | Documentation | +| ------------------------------------------------------------------------------ | ---------- | ----------- | -------------------------------- | +| [`@tetherto/wdk-wallet-evm`](https://github.com/tetherto/wdk-wallet-evm) | EVM | ✅ Ready | [Documentation](./wallet-evm) | +| [`@tetherto/wdk-wallet-ton`](https://github.com/tetherto/wdk-wallet-ton) | TON | ✅ Ready | [Documentation](./wallet-ton) | +| [`@tetherto/wdk-wallet-btc`](https://github.com/tetherto/wdk-wallet-btc) | Bitcoin | ✅ Ready | [Documentation](./wallet-btc) | +| [`@tetherto/wdk-wallet-spark`](https://github.com/tetherto/wdk-wallet-spark) | Spark | ✅ Ready | [Documentation](./wallet-spark) | +| [`@tetherto/wdk-wallet-tron`](https://github.com/tetherto/wdk-wallet-tron) | TRON | ✅ Ready | [Documentation](./wallet-tron) | +| [`@tetherto/wdk-wallet-solana`](https://github.com/tetherto/wdk-wallet-solana) | Solana | ✅ Ready | [Documentation](./wallet-solana) | +| `@tetherto/wdk-wallet-ark` | Ark | In progress | - | ## Account Abstraction Wallet Modules Wallet implementations that support [Account Abstraction](../../resources/concepts#account-abstraction) for gasless transactions using paymaster tokens like USD₮: -| Module | Blockchain | Status | Documentation | -|--------|------------|--------|---------------| -| [`@tetherto/wdk-wallet-evm-erc4337`](https://github.com/tetherto/wdk-wallet-evm-erc-4337) | EVM | ✅ Ready | [Documentation](./wallet-evm-erc-4337) | -| [`@tetherto/wdk-wallet-ton-gasless`](https://github.com/tetherto/wdk-wallet-ton-gasless) | TON | ✅ Ready | [Documentation](./wallet-ton-gasless) | -| [`@tetherto/wdk-wallet-tron-gasfree`](https://github.com/tetherto/wdk-wallet-tron-gasfree) | TRON | ✅ Ready | [Documentation](./wallet-tron-gasfree) | -| `@tetherto/wdk-wallet-solana-jupiterz` | Solana | In progress | - | +| Module | Blockchain | Status | Documentation | +| ------------------------------------------------------------------------------------------ | ---------- | ----------- | -------------------------------------- | +| [`@tetherto/wdk-wallet-evm-erc4337`](https://github.com/tetherto/wdk-wallet-evm-erc-4337) | EVM | ✅ Ready | [Documentation](./wallet-evm-erc-4337) | +| [`@tetherto/wdk-wallet-ton-gasless`](https://github.com/tetherto/wdk-wallet-ton-gasless) | TON | ✅ Ready | [Documentation](./wallet-ton-gasless) | +| [`@tetherto/wdk-wallet-tron-gasfree`](https://github.com/tetherto/wdk-wallet-tron-gasfree) | TRON | ✅ Ready | [Documentation](./wallet-tron-gasfree) | +| `@tetherto/wdk-wallet-solana-jupiterz` | Solana | In progress | - | ## Community Wallet Modules Wallet modules developed by the community. See the [Community Modules](../community-modules/) page for more details. -Community modules are developed and maintained independently. Use your own judgment and proceed at your own risk. + + Community modules are developed and maintained independently. Use your own judgment and proceed at your own risk. + -| Module | Blockchain | Description | Repository | -|--------|------------|-------------|------------| +| Module | Blockchain | Description | Repository | +| ----------------------- | ------------- | ----------------------------------------------------------------- | ---------------------------------------------------------- | | `@utexo/wdk-wallet-rgb` | Bitcoin (RGB) | RGB protocol wallet integration for Bitcoin-based smart contracts | [GitHub](https://github.com/UTEXO-Protocol/wdk-wallet-rgb) | ## Next Steps @@ -7516,4677 +8203,10191 @@ Community modules are developed and maintained independently. Use your own judgm To get started with WDK modules, follow these steps: 1. Get up and running quickly with our [Quickstart Guide](../../start-building/nodejs-bare-quickstart) -2. Choose the modules that best fit your needs from the tables above +2. Choose the modules that best fit your needs from the tables above 3. Check specific documentation for modules you wish to use You can also: -- Learn about key concepts like [Account Abstraction](../../resources/concepts#account-abstraction) and other important definitions -- Use one of our ready-to-use examples to be production ready -## Wallet BTC Overview -URL: https://docs.wdk.tether.su/sdk/wallet-modules/wallet-btc -Description: Overview of the @tetherto/wdk-wallet-btc module -A simple and secure package to manage BIP-84 (SegWit) and BIP-44 (Legacy) wallets for the Bitcoin blockchain. This package provides a clean API for creating, managing, and interacting with Bitcoin wallets using BIP-39 seed phrases and Bitcoin-specific derivation paths. - -**Default Derivation Path Change in v1.0.0-beta.4+** +* Learn about key concepts like [Account Abstraction](../../resources/concepts#account-abstraction) and other important definitions +* Use one of our ready-to-use examples to be production ready -The default derivation path was updated in v1.0.0-beta.4 to use BIP-84 (Native SegWit) instead of BIP-44 (Legacy): -- **Previous path** (<= v1.0.0-beta.3): `m/44'/0'/0'/0/` (Legacy addresses) -- **Current path** (v1.0.0-beta.4+): `m/84'/0'/0'/0/` (Native SegWit addresses) +# Pear Worklet WDK API Reference (/tools/pear-wrk-wdk/api-reference) -If you're upgrading from an earlier version, existing wallets created with the old path will generate different addresses. Make sure to migrate any existing wallets or use the old path explicitly if needed for compatibility. -Use [`getAccountByPath`](./api-reference) to supply an explicit derivation path when importing or recreating legacy wallets. -## Features - -- **BIP-39 Seed Phrase Support**: Generate and validate BIP-39 mnemonic seed phrases -- **Bitcoin Derivation Paths**: Support for BIP-84 (Native SegWit, default) and BIP-44 (Legacy) derivation paths -- **Multi-Account Management**: Create and manage multiple accounts from a single seed phrase -- **Address Types Support**: Generate Native SegWit (P2WPKH) addresses by default, with Legacy (P2PKH) support via configuration -- **UTXO Management**: Track and manage unspent transaction outputs -- **Transaction Management**: Create, sign, and broadcast Bitcoin transactions (single recipient per transaction) -- **Fee Estimation**: Dynamic fee calculation via mempool.space API -- **Electrum Support**: Connect to Electrum servers for network interaction -- **TypeScript Support**: Full TypeScript definitions included -- **Memory Safety**: Secure private key management with memory-safe implementation -- **Network Flexibility**: Support for mainnet, testnet, and regtest +## Package: `@tetherto/pear-wrk-wdk` -## Supported Networks +### Export: `HRPC` -This package works with Bitcoin networks: +#### Command Methods -- **Bitcoin Mainnet** (`"bitcoin"`) -- **Bitcoin Testnet** (`"testnet"`) -- **Bitcoin Regtest** (`"regtest"`) +| Method | Signature | Description | +| --------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| `log()` | `log(args: LogRequest): void` | Sends a log payload over the HRPC stream. | +| `workletStart()` | `workletStart(args: WorkletStartRequest): Promise\` | Deprecated worklet startup request. Prefer `initializeWDK()`. | +| `initializeWDK()` | `initializeWDK(args: WdkInitializeParams): Promise\<{ status: string }\>` | Creates or reinitializes the worklet WDK instance and registers wallets and optional protocols from `config`. | +| `resetWdkWallets()` | `resetWdkWallets(args: WdkResetWalletParams): Promise\<{ status: string }\>` | Selectively disposes and re-registers only the wallets listed in `config.networks`. | +| `generateEntropyAndEncrypt()` | `generateEntropyAndEncrypt(args: WdkGenerateEntropyParams): Promise\` | Generates encrypted seed and entropy buffers inside the worklet. | +| `getMnemonicFromEntropy()` | `getMnemonicFromEntropy(args: WdkGetMnemonicParams): Promise\<{ mnemonic: string }\>` | Decrypts an encrypted entropy payload and returns the mnemonic. | +| `getSeedAndEntropyFromMnemonic()` | `getSeedAndEntropyFromMnemonic(args: { mnemonic: string }): Promise\` | Converts a mnemonic into encrypted seed and entropy buffers. | +| `dispose()` | `dispose(args: DisposeRequest): void` | Disposes the worklet WDK instance. | +| `callMethod()` | `callMethod(args: CallMethodRequest): Promise\` | Looks up the target account and invokes one wallet or protocol method by name. | +| `registerWallet()` | `registerWallet(args: { config: string }): Promise\<{ status: string, blockchains: string }\>` | Dynamically registers additional wallets from a JSON config string. | +| `registerProtocol()` | `registerProtocol(args: { config: string }): Promise\<{ status: string }\>` | Dynamically registers additional protocols from a JSON config string. | -### Electrum Server Configuration +#### Handler Registration Methods -**Important**: While the package defaults to `electrum.blockstream.info:50001` for convenience, **we strongly recommend configuring your own Electrum server** for production use. +| Method | Signature | Description | +| ----------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------- | +| `onLog()` | `onLog(responseFn): void` | Registers the server-side handler for `log()`. | +| `onWorkletStart()` | `onWorkletStart(responseFn): void` | Registers the server-side handler for `workletStart()`. | +| `onInitializeWDK()` | `onInitializeWDK(responseFn): void` | Registers the server-side handler for `initializeWDK()`. | +| `onResetWdkWallets()` | `onResetWdkWallets(responseFn): void` | Registers the server-side handler for `resetWdkWallets()`. | +| `onGenerateEntropyAndEncrypt()` | `onGenerateEntropyAndEncrypt(responseFn): void` | Registers the server-side handler for encrypted entropy generation. | +| `onGetMnemonicFromEntropy()` | `onGetMnemonicFromEntropy(responseFn): void` | Registers the server-side handler for mnemonic recovery. | +| `onGetSeedAndEntropyFromMnemonic()` | `onGetSeedAndEntropyFromMnemonic(responseFn): void` | Registers the server-side handler for mnemonic migration. | +| `onDispose()` | `onDispose(responseFn): void` | Registers the server-side handler for `dispose()`. | +| `onCallMethod()` | `onCallMethod(responseFn): void` | Registers the server-side handler for `callMethod()`. | +| `onRegisterWallet()` | `onRegisterWallet(responseFn): void` | Registers the server-side handler for `registerWallet()`. | +| `onRegisterProtocol()` | `onRegisterProtocol(responseFn): void` | Registers the server-side handler for `registerProtocol()`. | -#### Recommended Approach: +#### `log` -**For Production:** -- Set up your own Fulcrum server for optimal performance and reliability -- Use recent Fulcrum versions that support pagination for high-transaction addresses +* `type?` (`LogType`): Optional numeric log level. +* `data?` (`string | null`): Optional log payload. -**For Development/Testing:** -- `fulcrum.frznode.com:50001` - Generally faster than default -- `electrum.blockstream.info:50001` - Default fallback +#### `workletStart` -## Next Steps +Deprecated startup request retained in the shipped type surface. -Get started with WDK in a Node.js environment +* `enableDebugLogs?` (`number`) +* `seedPhrase?` (`string | null`) +* `seedBuffer?` (`string | null`) +* `config` (`string`): JSON string of network configurations. -Get started with WDK's Bitcoin Wallet configuration +Returns: -Get started with WDK's Bitcoin Wallet API +* `status?` (`string | null`) -Get started with WDK's Bitcoin Wallet usage +#### `initializeWDK` -*** +* `encryptionKey?` (`string`): Base64-encoded decryption key for the encrypted seed buffer. +* `encryptedSeed?` (`string`): Base64-encoded encrypted seed buffer. +* `config` (`string`): JSON stringified `WdkWorkletConfig`. -## Need Help? -## Wallet BTC API Reference -URL: https://docs.wdk.tether.su/sdk/wallet-modules/wallet-btc/api-reference -Description: Complete API documentation for @tetherto/wdk-wallet-btc -# API Reference +The handler requires `encryptionKey` and `encryptedSeed` to be passed together or omitted together. When a seeded WDK instance already exists, the runtime disposes it before re-registering the wallets and optional protocols in `config`. -## Table of Contents +#### `resetWdkWallets` -| Class | Description | Methods | -|-------|-------------|---------| -| [WalletManagerBtc](#walletmanagerbtc) | Main class for managing Bitcoin wallets. Extends `WalletManager` from `@tetherto/wdk-wallet`. | [Constructor](#constructor), [Methods](#methods) | -| [WalletAccountBtc](#walletaccountbtc) | Individual Bitcoin wallet account implementation. Implements `IWalletAccount`. | [Constructor](#constructor-1), [Methods](#methods-1), [Properties](#properties) | -| [WalletAccountReadOnlyBtc](#walletaccountreadonlybtc) | Read-only Bitcoin wallet account. Extends `WalletAccountReadOnly` from `@tetherto/wdk-wallet`. | [Constructor](#constructor-2), [Methods](#methods-2) | -| [ElectrumTcp](#electrumtcp) | Standard TCP Electrum client. Implements `IElectrumClient`. | [Constructor](#constructor-3) | -| [ElectrumTls](#electrumtls) | TLS Electrum client. Implements `IElectrumClient`. | [Constructor](#constructor-4) | -| [ElectrumSsl](#electrumssl) | SSL Electrum client. Implements `IElectrumClient`. | [Constructor](#constructor-5) | -| [ElectrumWs](#electrumws) | WebSocket Electrum client for browser environments. Implements `IElectrumClient`. | [Constructor](#constructor-6), [Methods](#methods-3) | +* `config` (`string`): JSON stringified object containing a `networks` map. -## WalletManagerBtc +The runtime validates `config.networks`, extracts each target `blockchain`, calls `wdk.dispose(targetChains)`, and re-registers only those wallet managers. This method does not re-register protocols. -The main class for managing Bitcoin wallets. -Extends `WalletManager` from `@tetherto/wdk-wallet`. +#### `generateEntropyAndEncrypt` -#### Constructor +* `wordCount` (`12 | 24`): The mnemonic word count to generate. -```javascript -new WalletManagerBtc(seed, config) -``` -**Parameters:** -- `seed` (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytes -- `config` (BtcWalletConfig, optional): Configuration object - - `client` (IElectrumClient, optional): Electrum client instance. If provided, host/port/protocol are ignored. - - `host` (string, optional): Electrum server hostname (default: "electrum.blockstream.info"). Ignored if client is provided. - - `port` (number, optional): Electrum server port (default: 50001). Ignored if client is provided. - - `protocol` (string, optional): Transport protocol - "tcp", "tls", or "ssl" (default: "tcp"). Ignored if client is provided. - - `network` (string, optional): "bitcoin", "testnet", or "regtest" (default: "bitcoin") - - `bip` (number, optional): BIP address type - 44 (legacy) or 84 (native SegWit) (default: 84) +Returns: -### Methods +* `encryptionKey` (`string`) +* `encryptedSeedBuffer` (`string`) +* `encryptedEntropyBuffer` (`string`) -| Method | Description | Returns | -|--------|-------------|---------| -| `getAccount(index)` | Returns a wallet account at the specified index | `Promise\` | -| `getAccountByPath(path)` | Returns a wallet account at the specified derivation path | `Promise\` | -| `getFeeRates()` | Returns current fee rates for transactions | `Promise\` | -| `dispose()` | Disposes all wallet accounts, clearing private keys from memory and closing internal Electrum connections | `void` | +#### `getMnemonicFromEntropy` -##### `getAccount(index)` -Returns a wallet account at the specified index using BIP-84 (default) or BIP-44 derivation. +* `encryptedEntropy` (`string`): Base64-encoded encrypted entropy buffer. +* `encryptionKey` (`string`): Base64-encoded decryption key. -**Parameters:** -- `index` (number, optional): The index of the account to get (default: 0) +Returns: -**Returns:** `Promise\` - The wallet account +* `mnemonic` (`string`) -**Example:** -```javascript -// Returns the account with derivation path: -// For mainnet (bitcoin): m/84'/0'/0'/0/1 -// For testnet or regtest: m/84'/1'/0'/0/1 -const account = await wallet.getAccount(1) -``` +#### `getSeedAndEntropyFromMnemonic` -##### `getAccountByPath(path)` -Returns a wallet account at the specified derivation path. +* `mnemonic` (`string`): Source mnemonic to migrate into encrypted buffers. -**Parameters:** -- `path` (string): The derivation path (e.g., "0'/0/0") +Returns: -**Returns:** `Promise\` - The wallet account +* `encryptionKey` (`string`) +* `encryptedSeedBuffer` (`string`) +* `encryptedEntropyBuffer` (`string`) -**Example:** -```javascript -// Returns the account with derivation path: -// For mainnet (bitcoin): m/84'/0'/0'/0/1 -// For testnet or regtest: m/84'/1'/0'/0/1 -const account = await wallet.getAccountByPath("0'/0/1") -``` -##### `getFeeRates()` -Returns current fee rates from mempool.space API. +#### `dispose` -**Returns:** `Promise\` - Object containing fee rates in sat/vB -- `normal`: Standard fee rate for confirmation within ~1 hour -- `fast`: Higher fee rate for faster confirmation +* `args` (`DisposeRequest`): Empty request object. -**Example:** -```javascript -const feeRates = await wallet.getFeeRates() -console.log('Normal fee rate:', feeRates.normal, 'sat/vB') -console.log('Fast fee rate:', feeRates.fast, 'sat/vB') -``` +#### `callMethod` -##### `dispose()` -Disposes all wallet accounts, clears sensitive data from memory, and closes internal Electrum connections. +* `methodName` (`string`): Account method to invoke. +* `network` (`string`): Target blockchain key used to resolve the account. +* `accountIndex` (`number`): Account index passed to `wdk.getAccount(network, accountIndex)`. +* `args?` (`string`): JSON string of the method arguments. +* `options?` (`string`): JSON string of `CallMethodOptions`. -**Returns:** `void` +`options.protocolType` may be `swap`, `bridge`, `lending`, or `fiat`. When present, the runtime resolves the protocol-specific account wrapper before invoking `methodName`. -**Example:** -```javascript -wallet.dispose() -``` +#### `registerWallet` -## WalletAccountBtc +* `config` (`string`): JSON string of network config entries. -Represents an individual Bitcoin wallet account. Extends `WalletAccountReadOnlyBtc` and implements `IWalletAccount` from `@tetherto/wdk-wallet`. +Returns: -#### Constructor +* `status` (`string`) +* `blockchains` (`string`): JSON stringified array of registered blockchain names. -```javascript -new WalletAccountBtc(seed, path, config) -``` +#### `registerProtocol` -**Parameters:** -- `seed` (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytes -- `path` (string): Derivation path suffix (e.g., "0'/0/0") -- `config` (BtcWalletConfig, optional): Configuration object - - `client` (IElectrumClient, optional): Electrum client instance. If provided, host/port/protocol are ignored. - - `host` (string, optional): Electrum server hostname (default: "electrum.blockstream.info"). Ignored if client is provided. - - `port` (number, optional): Electrum server port (default: 50001). Ignored if client is provided. - - `protocol` (string, optional): Transport protocol - "tcp", "tls", or "ssl" (default: "tcp"). Ignored if client is provided. - - `network` (string, optional): "bitcoin", "testnet", or "regtest" (default: "bitcoin") - - `bip` (number, optional): BIP address type - 44 (legacy) or 84 (native SegWit) (default: 84) +* `config` (`string`): JSON string of protocol config entries. -### Methods +Returns: -| Method | Description | Returns | -|--------|-------------|---------| -| `getAddress()` | Returns the account's Bitcoin address | `Promise\` | -| `getBalance()` | Returns the total account balance in satoshis, including unconfirmed funds when present | `Promise\` | -| `sendTransaction(options, timeoutMs?)` | Sends a Bitcoin transaction and optionally polls until spent inputs disappear from unspent outputs | `Promise\` | -| `quoteSendTransaction(options)` | Estimates the fee for a transaction | `Promise\` | -| `getTransfers(options?)` | Returns the account's transfer history | `Promise\` | -| `getTransactionReceipt(hash)` | Returns a transaction's receipt | `Promise\` | -| `getMaxSpendable()` | Returns the maximum spendable amount | `Promise\` | -| `sign(message)` | Signs a message with the account's private key | `Promise\` | -| `verify(message, signature)` | Verifies a message signature | `Promise\` | -| `toReadOnlyAccount()` | Creates a read-only version of this account | `Promise\` | -| `dispose()` | Disposes the wallet account, clearing private keys from memory | `void` | +* `status` (`string`) -##### `getAddress()` -Returns the account's Bitcoin address (Native SegWit bech32 by default, or legacy if using BIP-44). +#### `onLog` -**Returns:** `Promise\` - The Bitcoin address +Registers the server-side handler used to service `log()` requests. -**Example:** -```javascript -const address = await account.getAddress() -console.log('Address:', address) // bc1q... (BIP-84) or 1... (BIP-44) -``` -##### `getBalance()` -Returns the account's total balance in satoshis, including unconfirmed funds when present. +#### `onWorkletStart` -**Returns:** `Promise\` - Balance in satoshis +Registers the server-side handler used to service the deprecated `workletStart()` request. -**Example:** -```javascript -const balance = await account.getBalance() -console.log('Balance:', balance, 'satoshis') -``` +#### `onInitializeWDK` -##### `sendTransaction(options, timeoutMs?)` -Sends a Bitcoin transaction to a single recipient and optionally polls after broadcast until spent inputs disappear from the unspent-output set. +Registers the server-side handler used to service `initializeWDK()` requests on the worklet side. -**Parameters:** -- `options` (BtcTransaction): Transaction options - - `to` (string): Recipient's Bitcoin address - - `value` (number | bigint): Amount in satoshis - - `feeRate` (number | bigint, optional): Fee rate in sat/vB. If provided, overrides the fee rate estimated from the blockchain. - - `confirmationTarget` (number, optional): Target blocks for confirmation (default: 1) -- `timeoutMs` (number, optional): Maximum milliseconds to poll after broadcast before returning (default: 10000) +#### `onResetWdkWallets` -**Returns:** `Promise\` -- `hash`: Transaction hash -- `fee`: Transaction fee in satoshis +Registers the server-side handler used to service `resetWdkWallets()` requests on the worklet side. -**Example:** -```javascript -const result = await account.sendTransaction() -console.log('Transaction hash:', result.hash) -console.log('Fee:', result.fee, 'satoshis') -``` +#### `onGenerateEntropyAndEncrypt` -##### `quoteSendTransaction(options)` -Estimates the fee for a transaction without broadcasting it. +Registers the server-side handler used to service encrypted entropy generation requests. -**Parameters:** -- `options` (BtcTransaction): Same as sendTransaction options - - `to` (string): Recipient's Bitcoin address - - `value` (number | bigint): Amount in satoshis - - `feeRate` (number | bigint, optional): Fee rate in sat/vB. If provided, overrides the fee rate estimated from the blockchain. - - `confirmationTarget` (number, optional): Target blocks for confirmation (default: 1) +#### `onGetMnemonicFromEntropy` -**Returns:** `Promise\` -- `fee`: Estimated transaction fee in satoshis +Registers the server-side handler used to service mnemonic recovery requests. -**Example:** -```javascript -const quote = await account.quoteSendTransaction() -console.log('Estimated fee:', quote.fee, 'satoshis') -``` +#### `onGetSeedAndEntropyFromMnemonic` -##### `getTransfers(options?)` -Returns the account's transfer history with detailed transaction information. +Registers the server-side handler used to service mnemonic migration requests. -**Parameters:** -- `options` (object, optional): Filter options - - `direction` (string, optional): 'incoming', 'outgoing', or 'all' (default: 'all') - - `limit` (number, optional): Maximum number of transfers (default: 10) - - `skip` (number, optional): Number of transfers to skip (default: 0) +#### `onDispose` -**Returns:** `Promise\` - Array of transfer objects -- `txid`: Transaction ID -- `address`: Account's own address -- `vout`: Output index in the transaction -- `height`: Block height (0 if unconfirmed) -- `value`: Transfer value in satoshis (bigint) -- `direction`: 'incoming' or 'outgoing' -- `fee`: Transaction fee in satoshis (bigint, for outgoing transfers) -- `recipient`: Receiving address (for outgoing transfers) +Registers the server-side handler used to service `dispose()` requests. -**Example:** -```javascript -const transfers = await account.getTransfers() -console.log('Recent incoming transfers:', transfers) -``` +#### `onCallMethod` -##### `getTransactionReceipt(hash)` -Returns a transaction's receipt if it has been included in a block. +Registers the server-side handler used to service `callMethod()` requests. -**Parameters:** -- `hash` (string): The transaction hash (64 hex characters) +#### `onRegisterWallet` -**Returns:** `Promise\` - The receipt, or null if the transaction has not been included in a block yet. +Registers the server-side handler used to service `registerWallet()` requests. -**Example:** -```javascript -const receipt = await account.getTransactionReceipt('abc123...') -if (receipt) -``` +#### `onRegisterProtocol` -##### `getMaxSpendable()` -Returns the maximum spendable amount that can be sent in a single transaction. The maximum spendable amount can differ from the wallet's total balance for several reasons: -- **Transaction fees**: Fees are subtracted from the total balance -- **Uneconomic UTXOs**: Small UTXOs where the fee to spend them exceeds their value are excluded -- **UTXO limit**: A transaction can include at most 200 inputs. Wallets with more UTXOs cannot spend their full balance in a single transaction. -- **Dust limit**: Outputs below the dust threshold (294 sats for SegWit, 546 sats for legacy) cannot be created +Registers the server-side handler used to service `registerProtocol()` requests. -**Returns:** `Promise\` - Maximum spendable result -- `amount`: Maximum spendable amount in satoshis (bigint) -- `fee`: Estimated network fee in satoshis (bigint) -- `changeValue`: Estimated change value in satoshis (bigint) +### Export: `registerRpcHandlers(rpc, context)` -**Example:** -```javascript -const = await account.getMaxSpendable() -console.log('Max spendable:', amount, 'satoshis') -console.log('Estimated fee:', fee, 'satoshis') -``` +Registers the package's server-side handlers on the provided RPC instance. -##### `sign(message)` -Signs a message using the account's private key. +* `rpc` (`any`): RPC server instance that supports the generated handler registration methods. +* `context` (`RpcContext`): Runtime context containing `wdk`, `WDK`, `walletManagers`, `protocolManagers`, and `wdkLoadError`. -**Parameters:** -- `message` (string): Message to sign +### Types -**Returns:** `Promise\` - Signature as base64 string +#### `WdkWorkletConfig` -**Example:** -```javascript -const signature = await account.sign('Hello Bitcoin!') -console.log('Signature:', signature) +```ts +interface WdkWorkletConfig { + networks: { + [blockchain: string]: { + blockchain: string + config: unknown + } + } + protocols?: { + [protocolName: string]: { + blockchain: string + protocolName: string + config: unknown + } + } +} ``` -##### `verify(message, signature)` -Verifies a message signature using the account's public key. +#### `WdkResetWalletParams` -**Parameters:** -- `message` (string): Original message -- `signature` (string): Signature as base64 string +```ts +interface WdkResetWalletParams { + config: string +} +``` -**Returns:** `Promise\` - True if signature is valid +#### `CallMethodOptions` -**Example:** -```javascript -const isValid = await account.verify('Hello Bitcoin!', signature) -console.log('Signature valid:', isValid) +```ts +interface CallMethodOptions { + transformResult: Function + defaultValue: any + protocolType: 'swap' | 'bridge' | 'lending' | 'fiat' + protocolName: string +} ``` -##### `toReadOnlyAccount()` -Creates a read-only version of this account that can query balances and transactions but cannot sign or send transactions. +*** -**Returns:** `Promise\` - Read-only account instance +## Need Help? -**Example:** -```javascript -const readOnlyAccount = await account.toReadOnlyAccount() -const balance = await readOnlyAccount.getBalance() -``` + -##### `dispose()` -Disposes the wallet account, securely erasing the private key from memory and closing the Electrum connection. -**Returns:** `void` +# Pear Worklet WDK Configuration (/tools/pear-wrk-wdk/configuration) -**Example:** -```javascript -account.dispose() -// Private key is now securely wiped from memory -``` -#### Properties -| Property | Type | Description | -|----------|------|-------------| -| `index` | `number` | The derivation path's index of this account | -| `path` | `string` | The full derivation path of this account | -| `keyPair` | `KeyPair` | The account's public and private key pair | +This page explains how to [build the worklet context](#worklet-context), [shape the worklet config payload](#worklet-config-payload), [initialize-wdk](#initialize-wdk), and [reset-selected-wallets](#reset-selected-wallets). -## WalletAccountReadOnlyBtc +## Worklet Context -Represents a read-only Bitcoin wallet account. Extends `WalletAccountReadOnly` from `@tetherto/wdk-wallet`. +You can bind the shipped RPC handlers to your Bare worklet using `registerRpcHandlers()`: -#### Constructor +```javascript title="Register RPC Handlers" +const { registerRpcHandlers } = require('@tetherto/pear-wrk-wdk/worklet') +const { WDK } = require('@tetherto/wdk') +const EvmWalletManager = require('@tetherto/wdk-wallet-evm') +const SparkWalletManager = require('@tetherto/wdk-wallet-spark') -```javascript -new WalletAccountReadOnlyBtc(address, config) +const context = { + wdk: null, + WDK, + walletManagers: { + ethereum: EvmWalletManager, + spark: SparkWalletManager + }, + protocolManagers: {}, + wdkLoadError: null +} + +module.exports = (rpc) => { + registerRpcHandlers(rpc, context) +} ``` -**Parameters:** -- `address` (string): The account's Bitcoin address -- `config` (object, optional): Configuration object (same as BtcWalletConfig but without `bip`) - - `client` (IElectrumClient, optional): Electrum client instance. If provided, host/port/protocol are ignored. - - `host` (string, optional): Electrum server hostname (default: "electrum.blockstream.info"). Ignored if client is provided. - - `port` (number, optional): Electrum server port (default: 50001). Ignored if client is provided. - - `protocol` (string, optional): Transport protocol - "tcp", "tls", or "ssl" (default: "tcp"). Ignored if client is provided. - - `network` (string, optional): "bitcoin", "testnet", or "regtest" (default: "bitcoin") +### Required Context Fields -### Methods +* `wdk`: The current WDK instance. Set this to `null` before the first initialization. +* `WDK`: The WDK constructor used to create the seeded instance. +* `walletManagers`: A map from blockchain name to wallet manager implementation. +* `protocolManagers`: A map from protocol name to protocol manager implementation. +* `wdkLoadError`: Any startup error captured while loading WDK. Use `null` when there is no load failure. -| Method | Description | Returns | -|--------|-------------|---------| -| `getAddress()` | Returns the account's Bitcoin address | `Promise\` | -| `getBalance()` | Returns the total account balance in satoshis, including unconfirmed funds when present | `Promise\` | -| `quoteSendTransaction(options)` | Estimates the fee for a transaction | `Promise\` | -| `getTransactionReceipt(hash)` | Returns a transaction's receipt | `Promise\` | -| `getMaxSpendable()` | Returns the maximum spendable amount | `Promise\` | -| `verify(message, signature)` | Verifies a message signature | `Promise\` | -| `dispose()` | Closes any internal Electrum connection | `void` | +## Worklet Config Payload -##### `getAddress()` -Returns the account's Bitcoin address. - -**Returns:** `Promise\` - The Bitcoin address +Both [`initializeWDK()`](./api-reference) and [`resetWdkWallets()`](./api-reference) expect `config` to be a JSON string. The decoded object must contain at least one entry under `networks`. -**Example:** -```javascript -const address = await readOnlyAccount.getAddress() -console.log('Address:', address) +```javascript title="Minimal Worklet Config JSON" +const workletConfig = { + networks: { + ethereum: { + blockchain: 'ethereum', + config: { + provider: 'https://rpc.ankr.com/eth_sepolia' + } + } + }, + protocols: { + moonpay: { + blockchain: 'ethereum', + protocolName: 'moonpay', + config: { + environment: 'sandbox' + } + } + } +} ``` -##### `getBalance()` -Returns the account's confirmed balance in satoshis. +### Payload Rules -**Returns:** `Promise\` - Balance in satoshis +* `networks` is required and must contain at least one network entry. +* Each network entry must include `blockchain` and an object `config`. +* `protocols` is optional during initialization. +* `resetWdkWallets()` reads only the `networks` portion of the decoded config. -**Example:** -```javascript -const balance = await readOnlyAccount.getBalance() -console.log('Balance:', balance, 'satoshis') -``` +## Initialize WDK -##### `quoteSendTransaction(options)` -Estimates the fee for a transaction without broadcasting it. +You can create and register the WDK instance inside the worklet using [`initializeWDK()`](./api-reference): -**Parameters:** -- `options` (BtcTransaction): Transaction options - - `to` (string): Recipient's Bitcoin address - - `value` (number | bigint): Amount in satoshis - - `feeRate` (number | bigint, optional): Fee rate in sat/vB - - `confirmationTarget` (number, optional): Target blocks for confirmation (default: 1) +```javascript title="Initialize WDK" +const { HRPC } = require('@tetherto/pear-wrk-wdk') -**Returns:** `Promise\` - Estimated fee in satoshis +const hrpc = new HRPC(ipcStream) -**Example:** -```javascript -const quote = await readOnlyAccount.quoteSendTransaction() -console.log('Estimated fee:', quote.fee, 'satoshis') +await hrpc.initializeWDK({ + encryptionKey: secrets.encryptionKey, + encryptedSeed: secrets.encryptedSeedBuffer, + config: JSON.stringify(workletConfig) +}) ``` -##### `getTransactionReceipt(hash)` -Returns a transaction's receipt if it has been included in a block. - -**Parameters:** -- `hash` (string): The transaction hash - -**Returns:** `Promise\` - The receipt, or null if not yet included +### Initialization Rules -**Example:** -```javascript -const receipt = await readOnlyAccount.getTransactionReceipt('abc123...') -if (receipt) -``` +* Pass both `encryptionKey` and `encryptedSeed`, or omit both together. +* On first initialization, the worklet must receive an encrypted seed pair so it can create `context.wdk`. +* If `context.wdk` already exists, a later `initializeWDK()` call disposes the existing instance before re-registering wallets and protocols from the new config. -##### `getMaxSpendable()` -Returns the maximum spendable amount that can be sent in a single transaction. +## Reset Selected Wallets -**Returns:** `Promise\` - Maximum spendable result -- `amount`: Maximum spendable amount in satoshis (bigint) -- `fee`: Estimated network fee in satoshis (bigint) -- `changeValue`: Estimated change value in satoshis (bigint) +You can selectively dispose and re-register wallet modules using [`resetWdkWallets()`](./api-reference): -**Example:** -```javascript -const = await readOnlyAccount.getMaxSpendable() -console.log('Max spendable:', amount, 'satoshis') +```javascript title="Reset Selected Wallet Modules" +await hrpc.resetWdkWallets({ + config: JSON.stringify({ + networks: { + ethereum: { + blockchain: 'ethereum', + config: { + provider: 'https://rpc.ankr.com/eth_sepolia' + } + } + } + }) +}) ``` -##### `verify(message, signature)` -Verifies a message signature using the account's public key. +### Reset Rules -**Parameters:** -- `message` (string): Original message -- `signature` (string): Signature as base64 string +* `resetWdkWallets()` requires an existing initialized `context.wdk`. +* The handler calls `wdk.dispose(targetChains)` with the blockchains extracted from `config.networks`. +* Only wallets listed in the request `networks` object are re-registered. +* The reset flow does not re-register protocols. -**Returns:** `Promise\` - True if signature is valid +## Call Wallet Methods -**Example:** -```javascript -const isValid = await readOnlyAccount.verify('Hello Bitcoin!', signature) -console.log('Signature valid:', isValid) +You can execute wallet account methods through [`callMethod()`](./api-reference): + +```javascript title="Call a Wallet Method" +const result = await hrpc.callMethod({ + methodName: 'getAddress', + network: 'ethereum', + accountIndex: 0 +}) ``` -##### `dispose()` -Closes any internal Electrum connection owned by this account. If a [`client`](/sdk/wallet-modules/wallet-btc/configuration#client) was provided via config, the connection is left open (the caller manages its lifecycle). +### Call Method Notes -**Returns:** `void` +* `args` is optional and must be a JSON string when provided. +* `options` is optional and must be a JSON string when provided. +* When `args` decodes to an array, the handler spreads the values as positional method arguments. +* When `args` decodes to an object or primitive, the handler passes it as a single argument. -**Example:** -```javascript -readOnlyAccount.dispose() -``` +*** -## ElectrumTcp +## Need Help? -Electrum client using TCP transport. Standard for command-line and server-side environments. -Implements `IElectrumClient`. + -#### Constructor -```javascript -new ElectrumTcp(config) -``` +# Pear Worklet WDK (/tools/pear-wrk-wdk) -**Parameters:** -- `config` (`Omit`): Configuration options - - `host` (string): Electrum server hostname - - `port` (number): Electrum server port -## ElectrumTls -Electrum client using TLS transport. -Implements `IElectrumClient`. +Pear Worklet WDK is the low-level transport and handler layer for running WDK inside a Bare worklet. It provides the `HRPC` client, the `registerRpcHandlers()` server helper, and the typed request payloads needed to initialize WDK, call wallet methods, and reset selected wallet modules from the host app. -#### Constructor +Powered by `@tetherto/pear-wrk-wdk`. -```javascript -new ElectrumTls(config) -``` +## Features -**Parameters:** -- `config` (`Omit`): Configuration options - - `host` (string): Electrum server hostname - - `port` (number): Electrum server port +* **Bare worklet bridge**: Connect a host app to a worklet through the shipped `HRPC` client and generated HRPC schema +* **Typed lifecycle requests**: Initialize WDK with `initializeWDK({ config, encryptionKey, encryptedSeed })` and tear it down with `dispose()` +* **Selective wallet resets**: Re-register only the wallet modules listed in a new worklet `networks` config using `resetWdkWallets({ config })` +* **Generic wallet method calls**: Call account methods through `callMethod({ methodName, network, accountIndex, args, options })` +* **Dynamic registration hooks**: Register additional wallets or protocols with `registerWallet()` and `registerProtocol()` -## ElectrumSsl +## Why this matters -Electrum client using SSL transport. -Implements `IElectrumClient`. +* You can keep WDK state and signing operations off the main thread in Bare-based apps +* You can reconfigure selected wallet modules without fully disposing the worklet +* You can use one transport layer across custom mobile, desktop, or embedded Bare integrations -#### Constructor + + Use this package when you need direct control over the worklet host and RPC layer. If you want generated worklet entry files instead, start with [`@tetherto/wdk-worklet-bundler`](https://github.com/tetherto/wdk-worklet-bundler). + -```javascript -new ElectrumSsl(config) -``` + + + Build the worklet context and pass the JSON config payloads used by initialize and reset requests + -**Parameters:** -- `config` (`Omit`): Configuration options - - `host` (string): Electrum server hostname - - `port` (number): Electrum server port + + Review the exported class, server helper, and request shapes + + -## ElectrumWs +*** -Electrum client using WebSocket transport. Compatible with browser environments where TCP sockets are not available. -Implements `IElectrumClient`. +## Need Help? -#### Constructor + -```javascript -new ElectrumWs(config) -``` -**Parameters:** -- `config` (ElectrumWsConfig): Configuration options - - `url` (string): The WebSocket URL (e.g., 'wss://electrum.example.com:50004') +# API Reference (/tools/price-rates/api-reference) -### Methods -| Method | Description | Returns | -|--------|-------------|---------| -| `connect()` | Establishes connection to Electrum server | `Promise\` | -| `close()` | Closes the connection | `Promise\` | -| `reconnect()` | Recreates the underlying socket and reinitializes the session | `Promise\` | -| `getBalance(scripthash)` | Returns balance for a script hash | `Promise\` | -| `listUnspent(scripthash)` | Returns UTXOs for a script hash | `Promise\` | -| `getHistory(scripthash)` | Returns transaction history | `Promise\` | -| `getTransaction(txHash)` | Returns raw transaction hex | `Promise\` | -| `broadcast(rawTx)` | Broadcasts raw transaction | `Promise\` | -| `estimateFee(blocks)` | Returns estimated fee rate | `Promise\` | -## Types +## Package: `@tetherto/wdk-pricing-bitfinex-http` -### BtcTransaction +### Class: `BitfinexPricingClient` -```typescript -interface BtcTransaction -``` +Simple HTTP pricing client for Bitfinex Public REST API. -### TransactionResult +#### Constructor -```typescript -interface TransactionResult +```javascript title="Create Client" +new BitfinexPricingClient(options?) ``` -### FeeRates +* `options` (optional): reserved for future use -```typescript -interface FeeRates -``` +#### Methods -### BtcTransfer +| Method | Description | Returns | +| ------------------------------------------------ | -------------------------------------------------------------- | ------------------- | +| `getCurrentPrice(base, quote)` | Fetch latest price for base/quote pair | `Promise\` | +| `getHistoricalPrice({ from, to, start?, end? })` | Fetch historical series (downscaled to ≤ 100 points if needed) | `Promise\` | -```typescript -interface BtcTransfer +##### `getCurrentPrice(base, quote)` + +```javascript title="Current Price" +const price = await client.getCurrentPrice('BTC', 'USD') ``` -### BtcMaxSpendableResult +##### `getHistoricalPrice({ from, to, start?, end? })` -```typescript -interface BtcMaxSpendableResult +If the returned series exceeds 100 points, it is downscaled by powers of two until ≤ 100. + +```javascript title="Historical Prices" +const series = await client.getHistoricalPrice({ + from: 'BTC', + to: 'USD', + start: 1709906400000, // optional + end: 1709913600000 // optional +}) ``` -### KeyPair +## Package: `@tetherto/wdk-pricing-provider` -```typescript -interface KeyPair -``` +### Class: `PricingProvider` -### BtcWalletConfig +Cache-aware wrapper providing a unified API over a `PricingClient` implementation. -```typescript -interface BtcWalletConfig +#### Constructor + +```javascript title="Create Provider" +new PricingProvider({ + client, // required: implements PricingClient + priceCacheDurationMs // optional: defaults to 1h +}) ``` -### IElectrumClient +* `client`: instance implementing the `PricingClient` contract +* `priceCacheDurationMs` (number, optional): cache TTL for last price in ms (default 3,600,000) -Interface for implementing custom Electrum clients. -```typescript -interface IElectrumClient -``` +#### Methods -### ElectrumBalance -```typescript -interface ElectrumBalance -``` +| Method | Description | Returns | +| ------------------------------------------------ | ----------------------------------------------------- | ------------------- | +| `getLastPrice(base, quote)` | Returns cached last price; refreshes when TTL expires | `Promise\` | +| `getHistoricalPrice({ from, to, start?, end? })` | Delegates to client for historical data | `Promise\` | -### ElectrumUtxo -```typescript -interface ElectrumUtxo -``` +##### `getLastPrice(base, quote)` -### ElectrumHistoryItem -```typescript -interface ElectrumHistoryItem +```javascript title="Last Price with Caching" +const provider = new PricingProvider({ client }) +const last = await provider.getLastPrice('BTC', 'USD') ``` -### MempoolElectrumConfig +##### `getHistoricalPrice({ from, to, start?, end? })` -```typescript -interface MempoolElectrumConfig +```javascript title="Historical via Provider" +const hist = await provider.getHistoricalPrice({ from: 'BTC', to: 'USD' }) ``` -Get started with WDK in a Node.js environment - -Build mobile wallets with React Native Expo +### Interface: `PricingClient` (abstract) -Get started with WDK's Bitcoin Wallet Usage +Implement this interface to plug your data source into `PricingProvider`. -Get started with WDK's Bitcoin Wallet Configuration +| Method | Signature | Notes | +| -------------------- | ----------------------------------------------------------------------------------------- | -------------------------- | +| `getCurrentPrice` | `(from: string, to: string) =\> Promise\` | Should return spot price | +| `getHistoricalPrice` | `(opts: { from: string, to: string, start?: number, end?: number }) =\> Promise\` | Return series for charting | -*** +## Notes -### Need Help? -## Configuration -URL: https://docs.wdk.tether.su/sdk/wallet-modules/wallet-btc/configuration -Description: Configuration options and settings for @tetherto/wdk-wallet-btc -## Wallet Configuration +* Uses Bitfinex Public HTTP API (`/v2/ticker` and `/v2/candles`) under the hood for the Bitfinex client +* Provider caches last price per pair using in-memory store and TTL -```javascript -import WalletManagerBtc, from '@tetherto/wdk-wallet-btc' +*** -const client = new ElectrumTcp() +## Need Help? -const wallet = new WalletManagerBtc(seedPhrase, ) -``` + -## Account Creation -```javascript -// WalletAccountBtc is created by the WalletManagerBtc -// It takes the same configuration as the manager -const account = await wallet.getAccount(0) // Get account at index 0 -const customAccount = await wallet.getAccountByPath("0'/0/5") // Custom path -``` +# Configuration (/tools/price-rates/configuration) -## Configuration Options -### Client -The `client` option specifies an Electrum client instance to use for blockchain data. When provided, the `host`, `port`, and `protocol` options are ignored. +## Bitfinex HTTP Client -**Type:** `IElectrumClient` +```javascript title="Create Client" +import { BitfinexPricingClient } from '@tetherto/wdk-pricing-bitfinex-http' -**Default:** None (falls back to host/port/protocol configuration) +// Create the client (no options needed) +const client = new BitfinexPricingClient() +``` -**Example:** -```javascript -import from '@tetherto/wdk-wallet-btc' +### Current Price -const config = { - client: new ElectrumTcp() -} +```javascript title="Get Current Price" +const price = await client.getCurrentPrice('BTC', 'USD') ``` -#### Built-in Transport Clients +### Historical Series -The package provides four built-in transport clients: +Downscales long histories to ≤ 100 points. -```javascript -import from '@tetherto/wdk-wallet-btc' +```javascript title="Get Historical Prices" +const series = await client.getHistoricalPrice({ + from: 'BTC', + to: 'USD', + start: 1709906400000, // optional (ms) + end: 1709913600000 // optional (ms) +}) +``` -// TCP (default) -const tcpClient = new ElectrumTcp() +## Provider Integration -// TLS -const tlsClient = new ElectrumTls() +Works with `@tetherto/wdk-pricing-provider` as a PricingClient implementation. -// SSL -const sslClient = new ElectrumSsl() +```javascript title="Wrap with PricingProvider" +import { PricingProvider } from '@tetherto/wdk-pricing-provider' -// WebSocket -const wsClient = new ElectrumWs() +const provider = new PricingProvider({ + client, + priceCacheDurationMs: 60 * 60 * 1000 // optional, defaults to 1h +}) + +const last = await provider.getLastPrice('BTC', 'USD') +const hist = await provider.getHistoricalPrice({ from: 'BTC', to: 'USD' }) ``` -#### Custom Electrum Client +*** -You can implement your own client by extending `IElectrumClient`: +## Need Help? -```javascript -import from '@tetherto/wdk-wallet-btc' + -class MyCustomElectrumClient implements IElectrumClient -const wallet = new WalletManagerBtc(seedPhrase, ) -``` +# Price Rates (/tools/price-rates) -### Host -The `host` option specifies the Electrum server hostname to connect to for blockchain data. Ignored if `client` is provided. -**Type:** `string` - -**Default:** `"electrum.blockstream.info"` - -**Recommended:** Configure your own Electrum server for production use. Public servers can be 10-300x slower and may fail for addresses with many transactions. +Pricing utilities for WDK apps. Includes HTTP clients and providers to retrieve current and historical prices from supported services. -**Example:** -```javascript -const config = -``` +Powered by [`@tetherto/wdk-pricing-bitfinex-http`](https://github.com/tetherto/wdk-pricing-bitfinex-http) and compatible with [`@tetherto/wdk-pricing-provider`](https://github.com/tetherto/wdk-pricing-provider). -### Port +## Features -The `port` option specifies the Electrum server port to connect to. Ignored if `client` is provided. +* **Current Prices**: Fetch latest price for a base/quote pair (e.g., BTC/USD) +* **Historical Series**: Retrieve historical price series; long histories optionally downscaled to ≤ 100 points +* **Provider Compatibility**: Works with `@tetherto/wdk-pricing-provider` +* **Lightweight HTTP Client**: Minimal dependencies; easy to integrate -**Type:** `number` +## Why this matters -**Default:** `50001` +* Consistent pricing is required for balance valuations, charts, and quotes +* A unified client reduces integration time and data handling errors -**Common Ports:** -- `50001` - TCP (default) -- `50002` - TLS/SSL -- `50003` - WebSocket + + + Get started with WDK price clients + -**Example:** -```javascript -const config = -``` + + Check the API Reference and examples + + -### Protocol +*** -The `protocol` option specifies the transport protocol to use. Ignored if `client` is provided. +## Need Help? -**Type:** `string` + -**Values:** -- `"tcp"` - TCP transport (default) -- `"tls"` - TLS transport -- `"ssl"` - SSL transport -**Default:** `"tcp"` +# API Reference (/tools/react-native-core/api-reference) -**Example:** -```javascript -const config = -``` -### Network -The `network` option specifies which Bitcoin network to use. +| Export | Type | Description | +| ----------------------------------------------- | --------- | ---------------------------------------------------- | +| [`WdkAppProvider`](#wdkappprovider) | Component | Root provider for WDK initialization | +| [`useWdkApp`](#usewdkapp) | Hook | App-level state (discriminated union) | +| [`useWalletManager`](#usewalletmanager) | Hook | Wallet lifecycle (create, restore, lock, unlock) | +| [`useAccount`](#useaccount) | Hook | Account operations (send, sign, verify, estimateFee) | +| [`useAddresses`](#useaddresses) | Hook | Load and query wallet addresses | +| [`useBalance`](#usebalance) | Hook | Single asset balance with TanStack Query | +| [`useBalancesForWallet`](#usebalancesforwallet) | Hook | Bulk balance fetch for multiple assets | +| [`useRefreshBalance`](#userefreshbalance) | Hook | Invalidate and refetch balances | +| [`BaseAsset`](#baseasset) | Class | Default `IAsset` implementation | +| [`validateMnemonic`](#validatemnemonic) | Utility | Validate BIP39 mnemonic phrases | +| [`balanceQueryKeys`](#balancequerykeys) | Utility | TanStack Query key factory | +| `WdkAppProviderProps` | Type | Props for `WdkAppProvider` | +| `WdkAppContextValue` | Type | Return type of `useWdkApp` | +| `UseAccountParams` | Type | Parameters for `useAccount` | +| `UseAccountReturn` | Type | Return type of `useAccount` | +| `UseAddressesReturn` | Type | Return type of `useAddresses` | +| `UseWalletManagerResult` | Type | Return type of `useWalletManager` | -**Type:** `string` +*** -**Values:** -- `"bitcoin"` - Bitcoin [mainnet](../../../resources/concepts#mainnet) (production) -- `"testnet"` - Bitcoin [testnet](../../../resources/concepts#testnet) (development) -- `"regtest"` - Bitcoin [regtest](../../../resources/concepts#regtest) (local testing) +## WdkAppProvider -**Default:** `"bitcoin"` +The root provider component that orchestrates WDK initialization. Wraps your app with TanStack Query, Zustand stores, and the worklet runtime. -**Example:** -```javascript -const config = -``` +Must be placed at the root of your component tree. All hooks in this library require `WdkAppProvider` as an ancestor. -### BIP +### Props -The `bip` option specifies the address type derivation standard to use. +| Prop | Type | Default | Description | +| -------------------------------- | ------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------- | +| `bundle` | [`BundleConfig`](#bundleconfig) | **required** | Worklet bundle configuration | +| `wdkConfigs` | [`WdkConfigs`](#wdkconfigs) | **required** | Network and protocol configurations | +| `enableAutoInitialization` | `boolean` | `true` | Enable automatic wallet initialization on app restart | +| `requireBiometrics` | `boolean` | `true` | Require biometric authentication for wallet operations | +| `currentUserId` | `string \| null` | `undefined` | Current user's identifier (typically email). Auto-initialization waits until this is set and matches the active wallet | +| `clearSensitiveDataOnBackground` | `boolean` | `false` | Clear sensitive data when app goes to background. When enabled, biometric auth is required on every app foreground | +| `children` | `React.ReactNode` | **required** | Child components | -**Type:** `number` +### Example -**Values:** -- `84` - [BIP-84](../../../resources/concepts#bip-84-native-segwit) (P2WPKH / Native SegWit) - addresses start with `bc1` (mainnet) or `tb1` (testnet) -- `44` - [BIP-44](../../../resources/concepts#bip-44-multi-account-hierarchy) (P2PKH / Legacy) - addresses start with `1` (mainnet) or `m`/`n` (testnet) +```tsx +import { WdkAppProvider } from '@tetherto/wdk-react-native-core' +import { bundle } from './.wdk' -**Default:** `84` +const wdkConfigs = { + networks: { + ethereum: { + blockchain: 'ethereum', + config: { + chainId: 1, + provider: 'https://eth.drpc.org', + }, + }, + }, +} -**Example:** -```javascript -// Use legacy addresses -const config = +export default function App() { + return ( + + + + ) +} ``` -## Electrum Server Configuration +*** -**Important**: While the package defaults to `electrum.blockstream.info:50001` for convenience, **we strongly recommend configuring your own Electrum server** for production use. +## useWdkApp -### Recommended Approach +Hook to access app-level state. Returns a discriminated union representing the current state of the WDK lifecycle. -**For Production:** -- Set up your own Fulcrum server for optimal performance and reliability -- Use recent Fulcrum versions that support pagination for high-transaction addresses +Must be used within `WdkAppProvider`. -**For Development/Testing:** -- `fulcrum.frznode.com:50001` - Generally faster than default -- `electrum.blockstream.info:50001` - Default fallback +### Returns -### Configuration Examples +| Property | Type | Description | +| -------- | ----------------------------- | --------------------------------------- | +| `state` | [`WdkAppState`](#wdkappstate) | Current app state (discriminated union) | +| `retry` | `() =\> void` | Retry initialization after an error | -```javascript -import from '@tetherto/wdk-wallet-btc' +### WdkAppState -// Production with custom Fulcrum server -const productionClient = new ElectrumTls() +The `state` property is a discriminated union on the `status` field: -const productionWallet = new WalletManagerBtc(seedPhrase, ) +| Status | Additional Fields | Description | +| ---------------- | ------------------ | --------------------------------------------------------- | +| `'INITIALIZING'` | - | Worklet is starting or wallet is loading | +| `'NO_WALLET'` | - | Worklet is ready, no wallet has been created | +| `'LOCKED'` | `walletId: string` | A wallet exists but is locked (requires biometric unlock) | +| `'READY'` | `walletId: string` | Wallet is unlocked and ready for operations | +| `'ERROR'` | `error: Error` | Initialization failed | -// Development with alternative public server -const developmentClient = new ElectrumTcp() +### Example + +```tsx +import { useWdkApp, useWalletManager } from '@tetherto/wdk-react-native-core' -const developmentWallet = new WalletManagerBtc(seedPhrase, ) +function AppRouter() { + const { state, retry } = useWdkApp() + const { createWallet, unlock } = useWalletManager() + + switch (state.status) { + case 'INITIALIZING': + return + case 'NO_WALLET': + return