diff --git a/.cspell.jsonc b/.cspell.jsonc index 513245c6c..202d93709 100644 --- a/.cspell.jsonc +++ b/.cspell.jsonc @@ -114,6 +114,12 @@ "!deny-list", // turns off the dictionary "!2lw-deny-list", // turns off the dictionary ] + }, + { + "filename": "ecosystem/ai/mcp.mdx", + "ignoreWords": [ + "mcp", + ], } ], "ignorePaths": [ diff --git a/CODEOWNERS b/CODEOWNERS index e69de29bb..47ce1a696 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -0,0 +1,29 @@ +# Default to the documentation team when there are no specific matches +* @ton-org/docs + +## +# CI +## + +/.github/ @novusnota + +## +# Contributing and components +## + +/contribute/ @novusnota @aigerimu + +## +# AI +## + +/ecosystem/ai/mcp.mdx @TrueCarry @thekiba +/ecosystem/ai/wallets.mdx @TrueCarry @thekiba + +## +# TON Connect, AppKit, WalletKit +## + +/ecosystem/ton-connect/ @TrueCarry @thekiba +/ecosystem/appkit/ @TrueCarry @thekiba +/ecosystem/walletkit/ @TrueCarry @thekiba diff --git a/docs.json b/docs.json index ea7350a15..362b4393e 100644 --- a/docs.json +++ b/docs.json @@ -38,6 +38,13 @@ "vscode" ] }, + "navbar": { + "primary": { + "type": "button", + "label": "Docs for LLMs: llms.txt", + "href": "https://docs.ton.org/llms.txt" + } + }, "navigation": { "pages": [ "start-here", @@ -52,7 +59,8 @@ "group": "AI", "expanded": true, "pages": [ - "ecosystem/ai/mcp" + "ecosystem/ai/mcp", + "ecosystem/ai/wallets" ] }, { @@ -145,7 +153,6 @@ }, { "group": "AppKit", - "tag": "new", "pages": [ "ecosystem/appkit/overview", "ecosystem/appkit/init", diff --git a/ecosystem/ai/mcp.mdx b/ecosystem/ai/mcp.mdx index 275ee406f..e1ce2c892 100644 --- a/ecosystem/ai/mcp.mdx +++ b/ecosystem/ai/mcp.mdx @@ -1,165 +1,499 @@ --- -title: "MCP servers" +title: "Agentic MCP server: @ton/mcp" +sidebarTitle: "Agentic MCP server" +tag: "new" --- import { Aside } from '/snippets/aside.jsx'; -[Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open-source standard for connecting AI applications to external systems, tools, and data sources. MCP servers expose specific capabilities to AI applications through standardized protocol interfaces. +The [`@ton/mcp` server][mcp-repo] enables AI agents to operate TON wallets and perform common blockchain operations through the [Model Context Protocol (MCP)][mcp-spec]. It handles private keys and signing internally, so agents interact only with high-level intents and confirmation flows. The server is built on top of [WalletKit](/ecosystem/walletkit/overview). + +The latest alpha release is available on [npm][mcp-npm]. Run it locally with: + +```bash +npx -y @ton/mcp@alpha +``` + +To set it up, follow the [quick start guide](#quick-start). -## Search documentation +## Features -Documentation generates and exposes a remote MCP server as a search tool for AI applications to query. Access it at `https://docs.ton.org/mcp`. +- Balance queries: check Toncoin and jetton (token) balances, view transaction history +- Transfers: send Toncoin, jettons, and NFTs +- Assets: list, inspect, and manage popular jettons and NFTs +- Swaps: get quotes for token swaps through DEX aggregators +- DNS: resolve TON DNS domains and perform reverse lookups +- Agentic wallets: create, import, and manage self-custody [agentic wallets][wallets] +- Multiple transports: standard I/O (default), multi-session HTTP, and serverless (AWS Lambda, Vercel, or custom integrations) - +## Quick start -Use the contextual menu at the top of this page to copy the MCP server URL or follow a deep link to connect from Cursor or VS Code directly. +There are two ways to set up `@ton/mcp`: -For Claude Code, run the following command: + + + Skills give an agent instructions on how to launch and use `@ton/mcp` on its own. No manual MCP client configuration is required. This approach works best with agents that support the [skills specification](https://agentskills.io/specification). -```shell -claude mcp add --transport http TonDocs https://docs.ton.org/mcp -``` + Run the following command to install the skills for `@ton/mcp`: -For [OpenCode](https://opencode.ai/docs/config/#mcp-servers), use the following configuration: + ```bash + npx skills add ton-connect/kit/packages/mcp + ``` -```json title="opencode.json" -{ - "$schema": "https://opencode.ai/config.json", - "mcp": { - "ton-docs": { - "type": "remote", - "url": "https://docs.ton.org/mcp", - "enabled": true + After installation, agents can launch and manage `@ton/mcp` on their own. No further configuration is needed. The server starts in [agentic wallets mode](#agentic-wallets-mode) by default. + + + + Register `@ton/mcp` as a server in Claude Desktop, Cursor, Windsurf, or another MCP client. Use this approach when the agent does not support skills or when finer control over server configuration is needed. + + Add the following block to the MCP client configuration file: + + ```json + { + "mcpServers": { + "ton": { + "command": "npx", + "args": ["-y", "@ton/mcp@alpha"] + } + } } - } -} + ``` + + The server starts in [agentic wallets mode](#agentic-wallets-mode) by default. For [single-wallet mode](#single-wallet-mode), add `MNEMONIC` or `PRIVATE_KEY` to the `env` object. + + See [environment variables](#environment-variables) for the full list of configuration options. + + + +To start using `@ton/mcp` in agentic wallets mode: + + + + To create a first agentic wallet, ask the agent to "create an agentic wallet" and follow the instructions. + + The process goes as follows: + + 1. The agent generates private keys for a new wallet and suggests [opening the dashboard](https://agentic-wallets-dashboard.vercel.app). + 1. On the dashboard, the user should connect their regular mainnet or testnet TON wallet: it will be the owner of an agentic wallet. + 1. Agentic wallet gets deployed from the dashboard. + 1. User provides the address of the deployed agentic wallet to the agent. + 1. Agent imports the wallet and becomes able to sign transactions using its operator key. + + The user can revoke access or withdraw funds at any time from the dashboard. + + + + An agentic wallet is a TON contract that needs Toncoin to operate. There are three ways to fund it: + + 1. During creation: use the "Initial TON deposit" field on the deployment page. + 1. From the dashboard: use the Fund button to transfer Toncoin, jettons, or NFTs. + 1. Directly: use a wallet app like Tonkeeper to transfer assets to the agentic wallet address directly. + + To check the balance, ask the agent: "What is my agent balance?" + + + + Once setup is complete, ask agent to perform desired actions. For example: + + - `Send 1 TON to UQB.._WALLET_ADDRESS` - sign and send a transfer from the agentic wallet. + - `Swap 5 TON for USDT` - get a quote and execute a swap. + - `Resolve the contract address of this DNS domain: DOMAIN_NAME.ton` - obtain the wallet address of the domain owner. + - `Show my NFTs` - query all NFTs owned by the wallet. + - `Check my balance` - current Toncoin and jetton balances. Do not use this data for any calculations, as it becomes outdated quickly. + - `Get my last transactions` - list of several latest events initiated by the wallet. + - `Import agentic wallet` - reinstate a wallet previously managed by another agent. + + + + Web dashboard allows to see all agentic wallets in one place. Monitor transactions, fund and withdraw assets, grant and revoke accesses, rotate operator keys without redeploying the wallets. + + + +## Runtime modes + +`@ton/mcp` supports two runtime modes: + +- [Agentic wallets mode](#agentic-wallets-mode) (default) - operates with self-custody wallets for autonomous AI agents. +- [Single-wallet mode](#single-wallet) - operates with a single in-memory wallet. + +### Agentic wallets mode + +[Agentic wallets][wallets] are self-custody wallets designed for autonomous agents. The user retains the owner key, and the agent holds a separate operator key. This split-key design gives agents access to transfers, swaps, and other on-chain operations without exposing the root credentials. + +Agentic wallets mode is the **default**. When neither `MNEMONIC` nor `PRIVATE_KEY` is set, the server loads wallets from a local config registry at `~/.config/ton/config.json` or the path in `TON_CONFIG_PATH`. + +In this mode the server provides additional tools for multi-wallet management, agentic wallet onboarding, operator key rotation, and wallet import. Wallet-scoped tools accept an optional selector parameter: wallet ID, name, or address. When omitted, the current active wallet is used. + +```bash +# Start in agentic wallets mode (default) +npx @ton/mcp@alpha + +# Start with a custom config path +TON_CONFIG_PATH=/path/to/config.json npx @ton/mcp@alpha ``` -## Perform blockchain operations with `@ton/mcp` +### Single-wallet mode - +Single-wallet mode starts the server with one in-memory wallet derived from a mnemonic or private key. This mode is useful for one-off tasks or for operating a single known wallet. -The [`@ton/mcp` server](https://github.com/ton-connect/kit/tree/main/packages/mcp) enables agents to operate with TON wallets and perform many common blockchain operations. It manages dangerous parts like private keys and signing, allowing agents to handle intents and confirmation flows safely. The server is built on top of [WalletKit](/ecosystem/walletkit/overview). +Set `MNEMONIC` or `PRIVATE_KEY` as an environment variable to activate this mode: -The latest alpha release is available on [npm](https://www.npmjs.com/package/@ton/mcp/v/0.1.15-alpha.0). Run it locally with the following command, passing CLI flags as needed. +```bash +# First, securely set either a MNEMONIC=" ... " +# or a PRIVATE_KEY="" -```shell -# Latest alpha version +# Then, launch the server npx @ton/mcp@alpha ``` -### Features +The default TON wallet version in the single-wallet mode is [`v5r1`][wallets-comparison]. Override it with `WALLET_VERSION`: -- Balance queries: check Toncoin and jetton (token) balances, view transaction history -- Transfers: send Toncoin, jettons, and NFTs to any TON address -- Assets: list, inspect, and manage popular jettons or NFTs -- Swaps: get quotes for token swaps via DEX aggregators -- DNS: resolve TON DNS-compatible domains and perform reverse-lookup for addresses -- Work with multiple stored wallets, active wallet selection, and local config-backed management tools -- Agentic sub-wallet deployments: deploy additional agentic wallets from a root wallet -- Multiple transports: standard I/O (default), multi-session HTTP server, and serverless +```bash +# First, securely set either a MNEMONIC or a PRIVATE_KEY +# Then, use a diffent wallet version +WALLET_VERSION=v4r2 npx @ton/mcp@alpha +``` -### Quick start +## Transport modes -The `@ton/mcp` supports two runtime modes. If neither `MNEMONIC` nor `PRIVATE_KEY` environment variables are set, the server starts in the **registry mode**, reading from a local config registry found at `~/.config/ton/config.json` or at `TON_CONFIG_PATH`, if available. Otherwise, server starts with one in-memory wallet in the **single-wallet** mode. +The `@ton/mcp` server supports three transport modes: -```shell -# Run as stdio MCP server in registry mode -# MNEMONIC and PRIVATE_KEY are both unset +- [Standard I/O](#standard-i%2Fo) (stdio, default) +- [HTTP](#http) +- [Serverless](#serverless) + +### Standard I/O + +Standard IO is the default transport. The server reads MCP requests from stdin and writes responses to stdout. Most MCP clients, including Claude Desktop and Cursor, can use this transport. They spawn the server process and interact over standard streams. + +```bash npx @ton/mcp@alpha +``` -# Run in registry mode with a custom config path -TON_CONFIG_PATH=/path/to/config.json npx @ton/mcp@alpha +### HTTP -# Run as stdio MCP server with mnemonic -MNEMONIC="word1 word2 ..." npx @ton/mcp@alpha +HTTP mode starts a multi-session HTTP server. Each MCP client session gets its own server transport, so multiple clients can initialize and reconnect independently. -# Run as HTTP server (port 3000) +```bash +# Start on the default port (3000) npx @ton/mcp@alpha --http -# Run as HTTP server on custom port +# Start on a custom port npx @ton/mcp@alpha --http 8080 -# Run with custom agentic wallet contract -PRIVATE_KEY="0x.._YOUR_PRIVATE_KEY" \ -WALLET_VERSION="agentic" \ -AGENTIC_WALLET_ADDRESS="EQ.._WALLET_ADDRESS" \ -npx @ton/mcp@alpha +# Start on a custom host and port +npx @ton/mcp@alpha --http 8080 --host 127.0.0.1 ``` -### Usage with MCP clients +The MCP endpoint is available at `http://:/mcp`. Point the MCP client to this URL to connect. + +### Serverless + +The package exports a `@ton/mcp/serverless` entry point for deployment as a serverless function on AWS Lambda, Vercel, Cloudflare Workers, and similar platforms. In serverless mode, credentials are passed via request headers rather than environment variables. + + + +Serverless mode operates in [single-wallet mode](#single-wallet-mode) only and always uses the [`v5r1` TON wallet version][wallets-comparison]. It does not use the wallet registry, nor does it expose wallet management or onboarding tools. -For Claude or Cursor, add: +| Header | Description | +| --------------- | -------------------------------------------------------------------------------------------------------- | +| `MNEMONIC` | Space-separated 24-word mnemonic phrase. | +| `PRIVATE_KEY` | Hex-encoded 32-byte or 64-byte private key (paired with the public key). Takes priority over `MNEMONIC`. | +| `NETWORK` | Either `mainnet` (default) or `testnet`. | +| `TONCENTER_KEY` | Optional API key for higher rate limits. | - ```json title="Registry mode" - { - "mcpServers": { - "ton": { - "command": "npx", - "args": ["-y", "@ton/mcp@alpha"], - "env": { - "TON_CONFIG_PATH": "/absolute/path/to/config.json" - } - } - } - } + ```typescript title="AWS Lambda" + import { createServerlessHandler } from '@ton/mcp/serverless'; + export const handler = createServerlessHandler(); ``` - ```json title="Single-wallet mode" - { - "mcpServers": { - "ton": { - "command": "npx", - "args": ["-y", "@ton/mcp@alpha"], - "env": { - "MNEMONIC": "word1 word2 word3 ...", - "PRIVATE_KEY": "0x.._YOUR_PRIVATE_KEY_HERE (optional, alternative to MNEMONIC)" - } - } - } - } + ```typescript title="Vercel" + import { createServerlessHandler } from '@ton/mcp/serverless'; + export default createServerlessHandler(); + ``` + + ```typescript title="Custom integration" + import { createServerlessHandler } from '@ton/mcp/serverless'; + const handle = createServerlessHandler(); + const response = await handle({ + method: 'POST', + url: '/mcp', + headers: { + 'MNEMONIC': ' ... ', + 'NETWORK': 'mainnet', + }, + body: {}, + }); ``` -For HTTP mode, start the server and point the MCP client to the endpoint: +## Available tools + +### Common tools + + + +- Wallet management: + - `get_wallet` - returns the current wallet address and network: `mainnet` or `testnet`. +- Balances and history: + - `get_balance` - returns the Toncoin balance of the current wallet. + - `get_balance_by_address` - returns the Toncoin balance for any address. + - `get_jetton_balance` - returns the balance of a specific jetton in the current wallet. + - `get_jettons` - lists all jettons held by the current wallet with balances and metadata. + - `get_jettons_by_address` - lists all jettons held by any address with balances and metadata. Supports pagination. + - `get_jetton_info` - returns metadata for a jetton minter (master) contract: name, symbol, decimals, image, URI. + - `get_known_jettons` - returns a built-in list of popular jettons on TON with addresses and metadata. + - `get_transactions` - returns recent transaction history: Toncoin transfers, jetton transfers, swaps. + - `get_transaction_status` - returns the status (pending, completed, or failed) and trace details for a transaction by its normalized hash. +- Transfers: + - `send_ton` - sends Toncoin to an address. Amounts are in human-readable format. For example, `"1.5"` for 1.5 Toncoin. Returns a `normalizedHash`. + - `send_jetton` - sends jettons to an address. Amounts are in human-readable format. Returns a `normalizedHash`. + - `send_nft` - transfers an NFT to another address. Returns a `normalizedHash`. + - `send_raw_transaction` - sends a raw transaction with full control over messages. Amounts are in nanoToncoin. Supports multiple messages. Returns a `normalizedHash`. +- Swaps: + - `get_swap_quote` - returns a quote for a token swap. The response includes transaction parameters ready for `send_raw_transaction`. Use `"TON"` for native Toncoin or a jetton minter (master) contract address. +- NFTs: + - `get_nfts` - lists NFTs in the current wallet with metadata, collection info, and attributes. Supports pagination. + - `get_nfts_by_address` - lists NFTs held by any address. Supports pagination. + - `get_nft` - returns detailed information about a specific NFT by its item contract address. +- DNS: + - `resolve_dns` - resolves a TON DNS domain to a wallet address. + - `back_resolve_dns` - reverse-resolves a wallet address to its associated DNS domain when one exists. + +### Agentic tools + +- Wallet management: + - `list_wallets` - lists all wallets in the local config registry. + - `get_current_wallet` - returns the active wallet from the local config registry. + - `set_active_wallet` - switches the active wallet in the local config registry by its ID, name, or address. + - `remove_wallet` - soft-deletes a wallet from the local config registry. The wallet remains in the config file but is hidden from MCP lookups. +- Agentic wallet management: + - `agentic_validate_wallet` - validates an agentic wallet address against the expected network and collection. + - `agentic_list_wallets_by_owner` - lists agentic wallets owned by a given main wallet address. + - `agentic_import_wallet` - imports existing agentic wallet into the local registry. If no matching pending draft exists, the wallet is read-only until `agentic_rotate_operator_key` completes. + - `agentic_rotate_operator_key` - starts operator key rotation: generates a replacement key, persists a pending draft, and returns a dashboard URL for the on-chain change. + - `agentic_get_pending_operator_key_rotation` - returns one pending operator key rotation by ID. + - `agentic_complete_rotate_operator_key` - completes a key rotation after the on-chain transaction confirms and updates the stored operator key locally. + - `agentic_cancel_rotate_operator_key` - cancels a pending key rotation and discards the replacement key. +- Agentic wallet onboarding: + - `agentic_start_root_wallet_setup` - starts first-time root agent setup: generates operator keys, persists a pending draft, and returns a dashboard URL. + - `agentic_list_pending_root_wallet_setups` - lists pending root agent onboarding drafts and their callback status. + - `agentic_get_root_wallet_setup` - returns one pending onboarding draft by setup ID. + - `agentic_complete_root_wallet_setup` - completes onboarding from a callback payload or a manually supplied wallet address, then imports the wallet and makes it active. + - `agentic_cancel_root_wallet_setup` - cancels a pending onboarding draft and removes its state. + +## Environment variables + +### Common + + + TON network and default env override target for `TONCENTER_API_KEY`. Use `mainnet` for production and `testnet` for development and testing. + + Defaults to `mainnet`. + + + + API key for [TON Center](/ecosystem/api/toncenter/introduction). Raises the default rate limit from 1 request per second to the limit of the selected plan. Without a key, the server uses a built-in shared key suitable for low-volume development and experiments. + + For production workloads, [obtain a dedicated key](/ecosystem/api/toncenter/get-api-key). + + + + Optional public base URL for agentic onboarding callbacks + + + + Host for the local callback server in stdio mode. Defaults to `127.0.0.1`. + + + + Port for the local callback server in stdio mode. Defaults to a random free port. + + +### Agentic wallets + + + Config path for agentic wallets mode. Defaults to `~/.config/ton/config.json`. + + +### Single-wallet + + + Space-separated 24-word mnemonic phrase for the single-wallet mode. + + Alternative to `PRIVATE_KEY`. + + + + Hex-encoded private key for the single-wallet mode. Can be given either 32-byte standalone or 64-byte when paired with the public key. + + Alternative to `MNEMONIC`. Takes priority over it. + + + + TON wallet version to use in the single-wallet mode: [`v5r1`, `v4r2`][wallets-comparison], or [`agentic`][wallets]. + + Defaults to `v5r1`. + -```shell -npx @ton/mcp@alpha --http 3000 -# MCP endpoint: http://localhost:3000/mcp + + Address of the agentic wallet in the single-wallet mode. Required for `WALLET_VERSION` set to `agentic`, unless derived from initial params. + + + + Optional index of the agentic wallet NFT contract. + + Defaults to none. + + + + Agentic collection address override for single-wallet mode. + + Defaults to `EQByQ19qvWxW7VibSbGEgZiYMqilHY5y1a_eeSL2VaXhfy07` on the mainnet. + + +## Library usage + +The package also exports a programmatic API for building custom MCP servers: + +```typescript +import { createTonWalletMCP } from '@ton/mcp'; +import { + Signer, + WalletV5R1Adapter, + TonWalletKit, + MemoryStorageAdapter, + Network, +} from '@ton/walletkit'; + +// Mnemonic as a single string of 24 words: +// " ... " +const MNEMONIC = process.env.MNEMONIC!; + +// Initialize WalletKit +const network = Network.mainnet(); +const kit = new TonWalletKit({ + networks: { [network.chainId]: {} }, + storage: new MemoryStorageAdapter(), +}); +await kit.waitForReady(); + +// Create a wallet from a mnemonic +const signer = await Signer.fromMnemonic(MNEMONIC.split(' '), { type: 'ton' }); +const walletAdapter = await WalletV5R1Adapter.create(signer, { + client: kit.getApiClient(network), + network, +}); +const wallet = await kit.addWallet(walletAdapter); + +// Create the MCP server object +const server = await createTonWalletMCP({ wallet }); ``` -HTTP mode keeps a separate MCP session (transport) per client session ID, so multiple clients can initialize and reconnect independently. - -### Environment variables - -| Variable | Default | Description | -| ---------------------------- | :------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| `NETWORK` | `mainnet` | TON network and default env override target for `TONCENTER_API_KEY`. Use `mainnet` for production and `testnet` for development and testing. | -| `MNEMONIC` | | Space-separated 24-word mnemonic phrase for single-wallet mode | -| `PRIVATE_KEY` | | Hex-encoded private key: 32-byte seed or 64-byte (private + public key), alternative to mnemonic | -| `WALLET_VERSION` | `v5r1` | Wallet version to use in single-wallet mode (`v5r1`, `v4r2`, or `agentic`) | -| `AGENTIC_WALLET_ADDRESS` | | Agentic wallet address (required for `WALLET_VERSION=agentic`, unless derived from init params) | -| `AGENTIC_WALLET_NFT_INDEX` | | Agentic wallet NFT index or subwallet ID (`uint256`, optional) | -| `AGENTIC_COLLECTION_ADDRESS` | `EQByQ19qvWxW7VibSbGEgZiYMqilHY5y1a_eeSL2VaXhfy07` | Agentic collection address override for single-wallet mode | -| `TONCENTER_API_KEY` | | API key for TON Center (optional, for higher rate limits) | -| `TON_CONFIG_PATH` | `~/.config/ton/config.json` | Config path for registry mode | -| `AGENTIC_CALLBACK_BASE_URL` | | Optional public base URL for agentic onboarding callbacks | -| `AGENTIC_CALLBACK_HOST` | `127.0.0.1` | Host for the local callback server in stdio mode | -| `AGENTIC_CALLBACK_PORT` | random free port | Port for the local callback server in stdio mode | +Agentic wallets mode: + +```typescript +import { createTonWalletMCP } from '@ton/mcp'; + +// A key for higher RPS limits +const TONCENTER_API_KEY = process.env.TONCENTER_API_KEY!; + +// Create the MCP server object +const server = await createTonWalletMCP({ + networks: { + mainnet: { apiKey: TONCENTER_API_KEY }, + }, +}); +``` + +## See also + +- [Agentic wallets][wallets] +- [`@ton/mcp` on GitHub][mcp-repo] + +[mcp-repo]: https://github.com/ton-connect/kit/tree/main/packages/mcp +[mcp-npm]: https://www.npmjs.com/package/@ton/mcp?activeTab=versions +[mcp-spec]: https://modelcontextprotocol.io/ +[wallets]: /ecosystem/ai/wallets +[wallets-comparison]: /standard/wallets/comparison#comparison-table +[changelog]: https://github.com/ton-connect/kit/blob/main/packages/mcp/CHANGELOG.md diff --git a/ecosystem/ai/wallets.mdx b/ecosystem/ai/wallets.mdx new file mode 100644 index 000000000..73c5027ea --- /dev/null +++ b/ecosystem/ai/wallets.mdx @@ -0,0 +1,103 @@ +--- +title: "Agentic wallet contracts" +sidebarTitle: "Agentic wallets" +tag: "new" +--- + +import { Aside } from '/snippets/aside.jsx'; + +Agentic wallets are self-custody wallets designed for autonomous AI agents on TON. + + + +## Split-key architecture + +Each agentic wallet is a smart contract deployed as [Soulbound Token (SBT)](/standard/tokens/nft/comparison#sbt) within a shared NFT collection. Internally, each agentic wallet retains full [wallet v5](/standard/wallets/comparison#comparison-table) functionality. It stores the user's address (owner), the agent's (operator) public key, and a nonce to protect against replay attacks. + +The deployment process goes as follows: + +1. The agent creates a pair of keys (public and private), keeping the private key in the local config registry. +1. User deploys an agentic wallet from their regular TON wallet by providing the operator's public key and wallet address (owner address). +1. The contract checks that the sender's address matches the stored owner's address. If it doesn't match, the wallet will be deployed in an uninitialized state and will not appear in explorers, preventing the creation of unwanted wallets without the user's consent. +1. If deployment is successful, the agent receives the address of the new wallet. + +With a private operator key and a new wallet address, the agent can sign and send transactions from that wallet. Alas, the user can withdraw funds, rotate the operator key, or deactivate the agent at any time by setting the operator key to zero. + +This split-key design gives agents access to transfers, swaps, and other on-chain operations without exposing the user's root credentials or violating the user's ownership and control. + +## Funding + +Transactions initiated by the agent (operator) must be signed with the operator key. Because the operator key is separate from the user's key (owner's key), the agent never controls the owner's main wallet. However, an agent with an active operator key has complete control of the balance and assets held in its own agentic wallet. + + + +## Sub-wallets + +An agent that already has at least one user-created wallet can create additional child wallets from that wallet. In that case, sender verification uses the original operator public key of the parent user-root wallet. + +Child wallets created by an agent cannot create additional child wallets. Thus, agents can only create child wallets from the user-created wallets. If a deploy request comes from an agent-created wallet, the contract rejects it. + +On the other hand, users can indefinitely deploy new wallets and form child wallet chains. Further, users can revoke access or withdraw funds from any deployed wallet at any time using the dashboard. + +## Dashboard + +The [agentic wallets dashboard](https://agentic-wallets-dashboard.vercel.app/) is a web interface for managing agentic wallets. It supports: + +- Wallet creation - deploy a new agentic wallet, assign an operator key, and fund it with Toncoin. +- Real-time monitoring - observe agent transactions as they happen. +- Key rotation - rotate operator keys without redeploying the wallet contract. +- Revocation - revoke agent access by removing the operator key. +- Funding and withdrawal - deposit or withdraw Toncoin, jettons, and NFTs. + +Connect an existing TON wallet to access the dashboard. + +## Get started + +The recommended way to create and use agentic wallets is through [`@ton/mcp`](/ecosystem/ai/mcp). The [`@ton/mcp` quick start](/ecosystem/ai/mcp#quick-start) guide covers the full setup flow and gives common usage examples. + +## FAQ + + + + The owner key is never shared with agents. The agent has its own operator key that can only be used to spend from its own agentic wallet, and any balance in that wallet is fully under the agent's control. All operations are performed on-chain with no intermediaries. + + + + The agent can only spend what was deposited into its wallet. The owner's main wallet is completely separate. + + However, if the agent behaves incorrectly or performs expensive transactions, it can spend the entire wallet balance before the owner reacts. + + The risk is capped to the deposited amount. Only deposit funds that are acceptable to lose. + + + + Not yet. This is a developer preview. The contracts are open source and [available on GitHub](https://github.com/the-ton-tech/agentic-wallet-contract), but a formal audit has not been completed. + + + + There is no limit. Each agent has its own wallet and balance. All agents are managed from a single dashboard. + + + + Select Revoke, then confirm the transaction. The operator is deactivated, and remaining funds can be withdrawn. + +