@ton/mcp 0.1.15-alpha.0 → 0.1.15-alpha.2

package/dist/utils/cli-args.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+type JsonSchema = {
+    type?: string | string[];
+    enum?: unknown[];
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema;
+    additionalProperties?: boolean | JsonSchema;
+    anyOf?: JsonSchema[];
+    oneOf?: JsonSchema[];
+};
+export declare function parseCliArgs(args: string[], schema?: JsonSchema): Record<string, unknown>;
+export {};
+//# sourceMappingURL=cli-args.d.ts.map

package/dist/utils/cli-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../../src/utils/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,KAAK,UAAU,GAAG;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,oBAAoB,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC5C,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;CACxB,CAAC;AA6EF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwBzF"}

package/llms.txt

@@ -111,14 +111,6 @@ Parameters:
 - fromAddress (optional): sender address
 Returns: top-level normalizedHash plus details
 
-### agentic_deploy_subwallet
-Deploy a new Agentic sub-wallet from a user-root Agentic wallet.
-Parameters:
-- operatorPublicKey (required): new sub-wallet operator public key (`uint256`, decimal or `0x`-hex)
-- metadata (required): onchain NFT metadata in TEP-64 format with mandatory `name`
-- amountTon (optional): attached TON amount, default `"0.05"`
-Returns: normalizedHash, deployed sub-wallet address, sub-wallet NFT index
-
 ### get_swap_quote
 Get quote for token swap.
 Parameters:
@@ -184,6 +176,26 @@ Parameters:
 - network (optional): mainnet or testnet
 - name (optional): wallet display name
 
+### agentic_rotate_operator_key
+Registry mode only. Start agentic operator key rotation, persist a pending draft, and return a dashboard URL for the on-chain change.
+Parameters:
+- walletSelector (optional): wallet id, name, or address. Uses the active wallet when omitted
+
+### agentic_get_pending_operator_key_rotation
+Registry mode only. Read one pending operator key rotation.
+Parameters:
+- rotationId (required): pending rotation identifier
+
+### agentic_complete_rotate_operator_key
+Registry mode only. Complete an agentic operator key rotation after the dashboard transaction lands on chain, then update the stored operator key locally.
+Parameters:
+- rotationId (required): pending rotation identifier
+
+### agentic_cancel_rotate_operator_key
+Registry mode only. Cancel a pending operator key rotation and discard its stored replacement key.
+Parameters:
+- rotationId (required): pending rotation identifier
+
 ### agentic_start_root_wallet_setup
 Registry mode only. Start first root-agent setup, generate operator keys, persist a pending draft, and return a dashboard URL.
 Parameters:
@@ -244,6 +256,12 @@ Parameters:
 3. If the wallet needs write access and no pending draft was recovered, use agentic_rotate_operator_key and then agentic_complete_rotate_operator_key
 4. Only then use write tools for that wallet
 
+### Rotating an Agentic Operator Key
+1. agentic_rotate_operator_key to create a pending rotation and get the dashboard URL
+2. Optionally inspect progress with agentic_get_pending_operator_key_rotation or agentic_list_pending_operator_key_rotations
+3. agentic_complete_rotate_operator_key after the on-chain change is confirmed
+4. agentic_cancel_rotate_operator_key if the pending rotation should be discarded
+
 ### Setting Up the First Agentic Root Wallet
 1. agentic_start_root_wallet_setup
 2. Tell the user to open the returned dashboard URL and create the wallet from their main wallet

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@ton/mcp",
-  "version": "0.1.15-alpha.0",
+  "version": "0.1.15-alpha.2",
   "description": "TON MCP Server - Model Context Protocol server for TON blockchain wallet operations",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
-  "bin": "./dist/cli.js",
+  "bin": "./bin/mcp.js",
   "exports": {
     ".": {
       "import": {
@@ -34,6 +34,7 @@
     "access": "public"
   },
   "files": [
+    "bin",
     "dist",
     "skills",
     "llms.txt",

package/skills/ton-balance/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: ton-balance
+description: Check TON wallet balances, token holdings, and transaction history. Use when the user wants to check their balance, see how much TON they have, list tokens, view jettons, check transaction history, look up a token, or verify a transaction status.
+user-invocable: true
+disable-model-invocation: false
+---
+
+# TON Balance & Transaction Queries
+
+Read-only queries for wallet balances, token holdings, and transaction history on TON.
+
+## MCP Tools
+
+| Tool | Required | Optional |
+| ---- | -------- | -------- |
+| `get_wallet` | — | `walletSelector` |
+| `get_balance` | — | `walletSelector` |
+| `get_balance_by_address` | `address` | — |
+| `get_jetton_balance` | `jettonAddress` | `walletSelector` |
+| `get_jettons` | — | `walletSelector` |
+| `get_jettons_by_address` | `address` | — |
+| `get_jetton_info` | `address` | — |
+| `get_known_jettons` | — | — |
+| `get_transactions` | — | `limit`, `walletSelector` |
+| `get_transaction_status` | `normalizedHash` | `walletSelector` |
+
+## Workflows
+
+### Check Balance
+1. Call `get_wallet` for address and network info
+2. Call `get_balance` for TON balance
+3. Call `get_jettons` for all token holdings
+
+### Check Specific Token
+1. If user mentions a token by name, call `get_known_jettons` to find its address
+2. Call `get_jetton_balance` with the `jettonAddress`
+
+### View Transaction History
+1. Call `get_transactions` with an optional `limit` (default varies)
+
+### Verify a Sent Transaction
+1. Call `get_transaction_status` with the `normalizedHash` returned by a send/swap operation
+
+## Notes
+
+- All tools are read-only — no confirmation needed
+- In registry mode, pass `walletSelector` to query a specific wallet instead of the active one
+- Amounts are returned in human-readable format (e.g., "1.5" = 1.5 TON)

package/skills/ton-cli/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: ton-cli
+description: Call TON MCP tools directly from the command line. Use when you want to query wallet info, check balances, send transactions, or run any TON wallet tool without starting an MCP server session. Works via `npx @ton/mcp@alpha <tool_name> [--arg value ...]`.
+user-invocable: true
+disable-model-invocation: false
+allowed-tools: ["Bash(npx @ton/mcp@alpha *)"]
+---
+
+# TON MCP Raw CLI Mode
+
+Run any TON wallet MCP tool directly from the command line. The binary invokes the tool, prints the JSON result to stdout, and exits.
+
+## Invocation Modes
+
+| Command | Description |
+| ------- | ----------- |
+| `npx @ton/mcp@alpha` | stdio MCP server (for Claude Desktop / MCP clients) |
+| `npx @ton/mcp@alpha --http [port]` | HTTP MCP server |
+| `npx @ton/mcp@alpha <tool_name> [--arg value ...]` | **Raw CLI: call one tool and exit** |
+
+## Raw CLI Usage
+
+```bash
+# No arguments
+npx @ton/mcp@alpha get_balance
+
+# Named arguments (--key value)
+npx @ton/mcp@alpha get_transactions --limit 5
+npx @ton/mcp@alpha get_jetton_balance --jettonAddress EQAbc...
+
+# All values are passed as plain strings; JSON objects/arrays are also accepted
+npx @ton/mcp@alpha get_transactions --limit 10
+npx @ton/mcp@alpha send_ton --toAddress UQA... --amount 0.1 --comment "hi"
+```
+
+Arguments are passed as `--key value` pairs. Objects/arrays (`{...}` / `[...]`) are JSON-parsed; everything else is kept as a plain string.
+
+## Output
+
+All tools print JSON to **stdout**. Errors are printed to **stderr** and the process exits with code `1`.
+
+```bash
+# Capture output for scripting
+BALANCE=$(npx @ton/mcp@alpha get_balance)
+echo $BALANCE | jq '.balance'
+```
+
+## Environment Variables
+
+The CLI respects the same environment variables as the server:
+
+| Variable | Description |
+| -------- | ----------- |
+| `NETWORK` | `mainnet` (default) or `testnet` |
+| `MNEMONIC` | 24-word mnemonic for single-wallet mode |
+| `PRIVATE_KEY` | Hex-encoded private key (alternative to mnemonic) |
+| `WALLET_VERSION` | `v5r1` (default), `v4r2`, or `agentic` |
+| `TONCENTER_API_KEY` | Optional Toncenter API key |
+| `TON_CONFIG_PATH` | Path to config file (default: `~/.config/ton/config.json`) |
+
+Without `MNEMONIC` or `PRIVATE_KEY`, the CLI uses the local config registry at `~/.config/ton/config.json` (registry mode). In registry mode, wallet-scoped tools accept an optional `--walletSelector` to target a specific wallet by id, name, or address.
+
+## Tool Reference
+
+### Wallet & Balance
+
+| Tool | Required args | Optional args |
+| ---- | ------------- | ------------- |
+| `get_wallet` | — | `--walletSelector` |
+| `get_balance` | — | `--walletSelector` |
+| `get_balance_by_address` | `--address` | — |
+| `get_jetton_balance` | `--jettonAddress` | `--walletSelector` |
+| `get_jettons` | — | `--walletSelector` |
+| `get_jettons_by_address` | `--address` | — |
+| `get_jetton_info` | `--jettonAddress` | — |
+| `get_transactions` | — | `--limit`, `--walletSelector` |
+| `get_transaction_status` | `--normalizedHash` | `--walletSelector` |
+| `get_known_jettons` | — | — |
+
+### Wallet Registry (config-registry mode only)
+
+| Tool | Required args | Optional args |
+| ---- | ------------- | ------------- |
+| `list_wallets` | — | — |
+| `get_current_wallet` | — | — |
+| `set_active_wallet` | `--walletSelector` | — |
+| `remove_wallet` | `--walletSelector` | — |
+
+### Transfers
+
+| Tool | Required args | Optional args |
+| ---- | ------------- | ------------- |
+| `send_ton` | `--toAddress`, `--amount` | `--comment`, `--walletSelector` |
+| `send_jetton` | `--toAddress`, `--jettonAddress`, `--amount` | `--comment`, `--walletSelector` |
+| `send_nft` | `--nftAddress`, `--toAddress` | `--comment`, `--walletSelector` |
+| `send_raw_transaction` | `--messages` | `--walletSelector` |
+
+### Swaps
+
+| Tool | Required args | Optional args |
+| ---- | ------------- | ------------- |
+| `get_swap_quote` | `--fromToken`, `--toToken`, `--amount` | `--walletSelector` |
+
+### NFTs
+
+| Tool | Required args | Optional args |
+| ---- | ------------- | ------------- |
+| `get_nfts` | — | `--limit`, `--offset`, `--walletSelector` |
+| `get_nfts_by_address` | `--address` | `--limit`, `--offset` |
+| `get_nft` | `--nftAddress` | — |
+
+### DNS
+
+| Tool | Required args |
+| ---- | ------------- |
+| `resolve_dns` | `--domain` |
+| `back_resolve_dns` | `--address` |
+
+## Example Session
+
+```bash
+# Check wallet address and network
+npx @ton/mcp@alpha get_wallet
+
+# Check TON balance
+npx @ton/mcp@alpha get_balance
+
+# List all tokens
+npx @ton/mcp@alpha get_jettons
+
+# Last 10 transactions
+npx @ton/mcp@alpha get_transactions --limit 10
+
+# Get balance of a specific jetton
+npx @ton/mcp@alpha get_jetton_balance --address EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs
+
+# Resolve a .ton domain
+npx @ton/mcp@alpha resolve_dns --domain foundation.ton
+
+# In registry mode: check balances for a named wallet
+npx @ton/mcp@alpha get_balance --walletSelector "my-hot-wallet"
+
+# In registry mode: list all registered wallets
+npx @ton/mcp@alpha list_wallets
+
+# Send TON (always confirm with user first)
+npx @ton/mcp@alpha send_ton --toAddress UQA... --amount 0.5 --comment "payment"
+
+# Swap quote
+npx @ton/mcp@alpha get_swap_quote --fromToken TON --toToken EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs --amount 1
+```
+
+## Notes
+
+- Always confirm with the user before running `send_ton`, `send_jetton`, `send_nft`, or `send_raw_transaction`.
+- After sending, poll `get_transaction_status --normalizedHash <hash>` until status is `completed` or `failed` (unless the user asks to skip).
+- In registry mode the active wallet from `~/.config/ton/config.json` is used by default.

package/skills/ton-create-wallet/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: ton-create-wallet
+description: Create and deploy a TON agentic wallet. Use when the user wants to create a wallet, set up an agent wallet, deploy an agentic wallet, onboard a new wallet, or when any wallet operation fails because no wallet is configured. This skill is a prerequisite before sending, swapping, or managing assets.
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Create TON Agentic Wallet
+
+Deploy an on-chain agentic wallet on TON. The agent generates operator keys, the user deploys the wallet contract from the dashboard, then provides the wallet address to complete setup.
+
+## MCP Tools
+
+| Tool | Description |
+| ---- | ----------- |
+| `agentic_start_root_wallet_setup` | Generate operator keys, create pending setup, return dashboard URL |
+| `agentic_list_pending_root_wallet_setups` | List pending setup drafts and their callback status |
+| `agentic_get_root_wallet_setup` | Read one pending setup by `setupId` |
+| `agentic_complete_root_wallet_setup` | Finish onboarding from callback or manual wallet address |
+| `agentic_cancel_root_wallet_setup` | Cancel a pending setup |
+
+### Tool Parameters
+
+| Tool | Required | Optional |
+| ---- | -------- | -------- |
+| `agentic_start_root_wallet_setup` | — | `network`, `name`, `source`, `collectionAddress`, `tonDeposit` |
+| `agentic_get_root_wallet_setup` | `setupId` | — |
+| `agentic_complete_root_wallet_setup` | `setupId` | `walletAddress`, `ownerAddress` |
+| `agentic_cancel_root_wallet_setup` | `setupId` | — |
+
+## Workflow
+
+1. Call `agentic_start_root_wallet_setup` — this generates an operator key pair and returns a `setupId` and `dashboardUrl`
+2. Show the `dashboardUrl` to the user and tell them to open it, deploy the wallet from their TON wallet, and then come back with the deployed wallet address
+3. **Ask the user for the wallet address** — in CLI/stdio mode there is no callback, so the agent must ask the user to paste the wallet address after they finish deployment on the dashboard
+4. Call `agentic_complete_root_wallet_setup` with the `setupId` and the `walletAddress` provided by the user
+5. Confirm the wallet is active with `get_current_wallet` or `list_wallets` (see `ton-manage-wallets` skill)
+
+## How It Works
+
+- The agent keeps the **operator private key** — it can sign transactions autonomously
+- The user keeps the **owner key** — they can withdraw funds or revoke access at any time
+- The wallet is an on-chain smart contract (NFT-based), not a custodial service
+- The dashboard is at `agentic-wallets-dashboard.vercel.app`
+
+## Environment Variables
+
+| Variable | Description |
+| -------- | ----------- |
+| `NETWORK` | `mainnet` (default) or `testnet` |
+| `AGENTIC_CALLBACK_BASE_URL` | Public URL for the onboarding callback (auto in HTTP mode) |
+| `AGENTIC_CALLBACK_PORT` | Port for the callback server |
+
+## Notes
+
+- In CLI/stdio mode there is no callback — always ask the user for the wallet address after showing the dashboard URL
+- Do **not** poll for callback status in CLI mode; just wait for the user to provide the address
+- After wallet creation, fund the wallet with TON before using transfer or swap skills

package/skills/ton-manage-wallets/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: ton-manage-wallets
+description: Manage multiple TON wallets, import agentic wallets and rotate operator keys. Use when the user wants to switch wallets, list wallets, import an existing wallet, rotate an operator key, or manage their wallet registry.
+user-invocable: true
+disable-model-invocation: false
+---
+
+# TON Wallet Management
+
+Manage the local wallet registry and perform advanced agentic wallet operations including import and key rotation.
+
+## MCP Tools
+
+### Wallet Registry
+
+| Tool | Required | Optional |
+| ---- | -------- | -------- |
+| `list_wallets` | — | — |
+| `get_current_wallet` | — | — |
+| `set_active_wallet` | `walletSelector` | — |
+| `remove_wallet` | `walletSelector` | — |
+
+### Agentic Wallet Management
+
+| Tool | Required | Optional |
+| ---- | -------- | -------- |
+| `agentic_validate_wallet` | `address` | `network`, `ownerAddress`, `collectionAddress` |
+| `agentic_list_wallets_by_owner` | `ownerAddress` | `network` |
+| `agentic_import_wallet` | `address` | `name` |
+| `agentic_rotate_operator_key` | `walletSelector` | — |
+| `agentic_complete_rotate_operator_key` | `rotationId` | — |
+
+## Workflows
+
+### Switch Active Wallet
+1. Call `list_wallets` to see all stored wallets
+2. Call `set_active_wallet` with a `walletSelector` (id, name, or address)
+3. Confirm with `get_current_wallet`
+
+### Import Existing Agentic Wallet
+1. Call `agentic_validate_wallet` to verify the wallet address and contract
+2. Call `agentic_import_wallet` to add it to the registry
+3. If the agent needs to sign transactions and no operator key is available, call `agentic_rotate_operator_key` and then `agentic_complete_rotate_operator_key` after the user applies the key change on-chain via the dashboard
+
+### Rotate Operator Key
+1. Call `agentic_rotate_operator_key` — generates a new key pair and returns a dashboard URL for the user to apply the change on-chain
+2. Tell the user to open the dashboard link and confirm the key change
+3. Call `agentic_complete_rotate_operator_key` with the `rotationId` once the on-chain change is confirmed
+
+## Notes
+
+- `walletSelector` accepts wallet id, name, or address
+- For one-off queries, pass `walletSelector` directly to wallet-scoped tools instead of changing the active wallet
+- Registry data is stored in `~/.config/ton/config.json` (or `TON_CONFIG_PATH`)
+- Read tools work with imported agentic wallets that don't yet have an `operator_private_key`; write tools require it
+- Management tool responses never expose private keys, mnemonics, or API keys
+- To create a brand new agentic wallet, use the `ton-create-wallet` skill instead

package/skills/ton-nfts/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: ton-nfts
+description: View and transfer NFTs on the TON blockchain. Use when the user wants to see their NFTs, list collectibles, check NFT details, send an NFT, or transfer an NFT to someone.
+user-invocable: true
+disable-model-invocation: false
+---
+
+# TON NFT Operations
+
+View and transfer NFTs on the TON blockchain.
+
+## MCP Tools
+
+| Tool | Required | Optional |
+| ---- | -------- | -------- |
+| `get_nfts` | — | `limit`, `offset`, `walletSelector` |
+| `get_nfts_by_address` | `address` | `limit`, `offset` |
+| `get_nft` | `nftAddress` | — |
+| `send_nft` | `nftAddress`, `toAddress` | `comment`, `walletSelector` |
+
+## Workflows
+
+### List My NFTs
+1. Call `get_nfts` to list NFTs in the active wallet
+2. Use `limit` and `offset` for pagination
+
+### View NFT Details
+1. Call `get_nft` with the `nftAddress`
+
+### Send an NFT
+1. Call `get_nfts` to find the NFT address if the user doesn't have it
+2. Confirm the transfer with the user
+3. Call `send_nft` with `nftAddress` and `toAddress`
+4. Poll `get_transaction_status` with the returned `normalizedHash` until status is `completed` or `failed` (see `ton-balance` skill)
+
+## Notes
+
+- Always confirm with the user before transferring an NFT
+- If no wallet is configured, use the `ton-create-wallet` skill first

package/skills/ton-send/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: ton-send
+description: Send TON or jettons (tokens) to an address or TON DNS domain. Use when the user wants to send TON, transfer tokens, send jettons, pay someone, send funds to a .ton or .t.me domain, or transfer assets on the TON blockchain.
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Send TON & Tokens
+
+Transfer TON or jettons to any address. Supports TON DNS resolution for `.ton` and `.t.me` domains.
+
+## MCP Tools
+
+| Tool | Required | Optional |
+| ---- | -------- | -------- |
+| `send_ton` | `toAddress`, `amount` | `comment`, `walletSelector` |
+| `send_jetton` | `toAddress`, `jettonAddress`, `amount` | `comment`, `walletSelector` |
+| `resolve_dns` | `domain` | — |
+| `back_resolve_dns` | `address` | — |
+
+## Workflows
+
+### Send TON
+1. If the user provides a DNS name (e.g., `foundation.ton`, `user.t.me`) instead of a raw address, call `resolve_dns` first
+2. Confirm the amount and recipient with the user
+3. Call `send_ton` with address and amount
+4. Poll `get_transaction_status` with the returned `normalizedHash` until status is `completed` or `failed` (see `ton-balance` skill). User can ask to skip polling.
+
+### Send Jetton (Token)
+1. If user mentions a token by name, call `get_known_jettons` (see `ton-balance` skill) to find the `jettonAddress`
+2. Call `get_jetton_balance` to verify sufficient balance
+3. Confirm with the user
+4. Call `send_jetton` with the `jettonAddress`, `toAddress`, and `amount`
+5. Poll `get_transaction_status` until completed or failed
+
+## Notes
+
+- Amounts are human-readable (e.g., `"1.5"` = 1.5 TON, `"100"` = 100 tokens)
+- Always confirm with the user before executing a transfer
+- After sending, poll `get_transaction_status` by default. User can specify whether to check status.
+- If no wallet is configured, use the `ton-create-wallet` skill first

package/skills/ton-swap/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: ton-swap
+description: Swap or trade tokens on the TON blockchain via DEX. Use when the user wants to swap, trade, exchange, convert, buy, or sell tokens like TON, USDT, jUSDC, or any jetton. Covers phrases like "swap TON for USDT", "trade tokens", "buy USDT", "exchange jettons".
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Swap TON Tokens
+
+Swap tokens on TON via DEX aggregator. Two-step flow: get a quote, confirm with the user, then execute.
+
+## MCP Tools
+
+| Tool | Required | Optional |
+| ---- | -------- | -------- |
+| `get_swap_quote` | `fromToken`, `toToken`, `amount` | `walletSelector` |
+| `send_raw_transaction` | `messages` | `walletSelector` |
+| `get_known_jettons` | — | — |
+
+## Workflow
+
+1. If the user mentions a token by name (e.g., "USDT", "jUSDC"), call `get_known_jettons` to resolve the jetton address
+2. Call `get_swap_quote` with `fromToken`, `toToken`, and `amount`
+   - Use `"TON"` for native TON, or the jetton master contract address for tokens
+   - Amount is human-readable (e.g., `"1.5"` = 1.5 TON)
+3. Show the quote details to the user and ask for confirmation
+4. Call `send_raw_transaction` with the transaction params returned by the quote
+5. Poll `get_transaction_status` with the returned `normalizedHash` until status is `completed` or `failed` (see `ton-balance` skill). User can ask to skip polling.
+
+## Notes
+
+- Always confirm the swap with the user before executing
+- The quote returns transaction messages ready for `send_raw_transaction`
+- After execution, poll `get_transaction_status` by default. User can specify whether to check status.
+- If no wallet is configured, use the `ton-create-wallet` skill first

package/skills/SKILL.md

@@ -1,123 +0,0 @@
-# TON Blockchain Wallet
-
-Manage TON blockchain wallet operations including registry-backed wallet selection, balance queries, transfers, swaps, NFTs, DNS resolution, and agentic wallet onboarding.
-
-## When to Use
-
-Use this skill when the user wants to:
-- Check wallet info, TON or token balances
-- Work with multiple stored wallets or switch the active wallet
-- Configure network settings for MCP registry mode
-- Send TON, Jettons (tokens), or NFTs
-- Swap tokens on DEX
-- View transaction history
-- Resolve TON DNS-compatible domains
-- Import, validate, or finish setup of an agentic wallet
-
-## Tools Available
-
-### Wallet & Balance
-- `get_wallet` - Get wallet address and network info
-- `get_balance` - Get TON balance
-- `get_balance_by_address` - Get TON balance for any address
-- `get_jetton_balance` - Get specific token balance (needs `jettonAddress`)
-- `get_jettons` - List all tokens in wallet
-- `get_jettons_by_address` - List all tokens for any owner address
-- `get_jetton_info` - Get jetton metadata by master contract address
-- `get_transactions` - View recent transactions (optional `limit`)
-- `get_transaction_status` - Check completion status of a sent transaction by normalized hash
-- `get_known_jettons` - Get list of popular tokens with addresses
-
-### Wallet Registry Management
-- `list_wallets` - List wallets stored in the local config registry
-- `get_current_wallet` - Get the active wallet from the local registry
-- `set_active_wallet` - Switch active wallet by id, name, or address
-- `remove_wallet` - Soft-delete a stored wallet from the registry
-
-### Agentic Wallet Management
-- `agentic_validate_wallet` - Validate an agentic wallet against network/collection and optional owner
-- `agentic_list_wallets_by_owner` - Find agentic wallets owned by a given main wallet
-- `agentic_import_wallet` - Import an existing agentic wallet into the registry
-- `agentic_rotate_operator_key` - Start operator-key rotation for an imported agentic wallet
-- `agentic_complete_rotate_operator_key` - Finalize operator-key rotation after the on-chain change lands
-### Agentic Onboarding
-- `agentic_start_root_wallet_setup` - Create pending setup, generate operator keys, and return a dashboard URL
-- `agentic_list_pending_root_wallet_setups` - List pending root-agent setup drafts
-- `agentic_get_root_wallet_setup` - Read one pending setup by `setupId`
-- `agentic_complete_root_wallet_setup` - Finish onboarding from callback state or manual wallet address
-- `agentic_cancel_root_wallet_setup` - Cancel a pending setup
-
-### Transfers
-- `send_ton` - Send TON (`toAddress`, `amount` in TON like "1.5", optional `comment`); returns top-level `normalizedHash`
-- `send_jetton` - Send tokens (`toAddress`, `jettonAddress`, `amount`, optional `comment`); returns top-level `normalizedHash`
-- `send_nft` - Transfer NFT (`nftAddress`, `toAddress`, optional `comment`)
-- `send_raw_transaction` - Advanced: send raw transaction with multiple messages; returns top-level `normalizedHash`
-
-### Swaps
-- `get_swap_quote` - Get swap quote (`fromToken`, `toToken`, `amount` in human-readable format)
-  - Use "TON" or jetton address for tokens
-  - Returns transaction params for `send_raw_transaction`
-
-### NFTs
-- `get_nfts` - List wallet NFTs (optional `limit`, `offset`)
-- `get_nfts_by_address` - List NFTs for any owner address
-- `get_nft` - Get NFT details (`nftAddress`)
-
-### DNS
-- `resolve_dns` - Resolve TON DNS-compatible domain to address (`domain` like "foundation.ton" or "viqex.t.me")
-- `back_resolve_dns` - Find domain for address (`address`)
-
-## Common Workflows
-
-### Check Balance
-1. Call `get_wallet` for address and network
-2. Call `get_balance` for TON
-3. Call `get_jettons` for all tokens
-
-### Work With Multiple Wallets
-1. Call `list_wallets` to inspect stored wallets
-2. Call `get_current_wallet` to confirm the active wallet
-3. If needed, call `set_active_wallet`
-4. For one-off calls, pass `walletSelector` directly to wallet-scoped tools instead of changing active wallet
-
-### Send TON
-1. If user provides a DNS name instead of a raw address, call `resolve_dns` first
-2. Call `send_ton` with address and amount
-3. By default, poll `get_transaction_status` until status is completed or failed. User can ask to skip.
-
-### Send Token
-1. Call `get_jettons` to find token address and verify balance
-2. Call `send_jetton` with token address and amount
-3. By default, poll `get_transaction_status` until status is completed or failed. User can ask to skip.
-
-### Swap Tokens
-1. Call `get_known_jettons` if user mentions token by name
-2. Call `get_swap_quote` to get quote and transaction params
-3. Show quote to user and ask for confirmation
-4. Call `send_raw_transaction` with the transaction params
-5. By default, poll `get_transaction_status` until status is completed or failed. User can ask to skip.
-
-### Import Existing Agentic Wallet
-1. Call `agentic_validate_wallet` if the user only has an address and you need full validation
-2. Call `agentic_import_wallet` to import it into the registry
-3. If the wallet must sign and no pending draft was recovered, call `agentic_rotate_operator_key` and then `agentic_complete_rotate_operator_key`
-4. Only after that use write tools such as `send_ton`, `send_nft`, or `agentic_deploy_subwallet`
-
-### Set Up First Agentic Root Wallet
-1. Call `agentic_start_root_wallet_setup`
-2. Tell the user to open the returned dashboard URL and create the wallet from their main wallet
-3. Poll `agentic_get_root_wallet_setup` or inspect `agentic_list_pending_root_wallet_setups`
-4. If completion is manual, use `agentic_validate_wallet`
-5. Call `agentic_complete_root_wallet_setup` when callback data is available or when the user provides the created wallet address
-6. Confirm the imported wallet with `get_current_wallet` or `list_wallets`
-
-## Notes
-
-- Amounts for `send_ton`, `send_jetton`, and `get_swap_quote` are human-readable (e.g., "1.5" = 1.5 TON)
-- In registry mode, wallet-scoped tools can accept optional `walletSelector`; otherwise they use the active wallet
-- Registry mode uses the local TON config file from `~/.config/ton/config.json` or `TON_CONFIG_PATH`
-- Agentic onboarding callback state is persisted in the local config; in stdio mode use `AGENTIC_CALLBACK_BASE_URL` and/or `AGENTIC_CALLBACK_PORT` when you need a stable callback endpoint across restarts
-- Management tool responses are sanitized and do not expose mnemonic, private keys, operator private keys, or Toncenter API keys
-- Read tools can work with imported agentic wallets that do not yet have `operator_private_key`; write tools cannot
-- Always confirm with user before executing transfers or swaps
-- **Default flow:** After sending, poll `get_transaction_status` until completed or failed. User can specify whether to check status.