@ton/mcp 0.1.12 → 0.1.15-alpha.0

package/dist/types/config.d.ts

@@ -10,6 +10,7 @@
  */
 import type { Wallet } from '@ton/walletkit';
 import type { IContactResolver } from './contacts.js';
+export type NetworkType = 'mainnet' | 'testnet' | 'tetra';
 /**
  * Network-specific configuration
  */
@@ -22,10 +23,10 @@ export interface NetworkConfig {
  */
 export interface TonMcpConfig {
     /**
-     * Wallet instance to use for operations.
-     * Required.
+     * Optional fixed wallet instance for backward-compatible single-wallet mode.
+     * If omitted, the server can run against the local config registry.
      */
-    wallet: Wallet;
+    wallet?: Wallet;
     /**
      * Optional contact resolver for name-to-address resolution.
      */

package/dist/types/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,aAAa,CAAC;QACxB,OAAO,CAAC,EAAE,aAAa,CAAC;KAC3B,CAAC;CACL"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,aAAa,CAAC;QACxB,OAAO,CAAC,EAAE,aAAa,CAAC;KAC3B,CAAC;CACL"}

package/dist/types/contacts.d.ts

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  *
  */
+import type { NetworkType } from './config.js';
 /**
  * IContactResolver - Optional interface for resolving friend names to TON addresses
  *
@@ -20,7 +21,7 @@ export interface Contact {
     /** TON address */
     address: string;
     /** Optional network specification (defaults to any) */
-    network?: 'mainnet' | 'testnet';
+    network?: NetworkType;
 }
 /**
  * Interface for contact resolution.

package/dist/types/contacts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contacts.d.ts","sourceRoot":"","sources":["../../src/types/contacts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,OAAO;IACpB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE9D;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5D;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAEjD;;;;;;OAMG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjE"}
+{"version":3,"file":"contacts.d.ts","sourceRoot":"","sources":["../../src/types/contacts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,OAAO;IACpB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,OAAO,CAAC,EAAE,WAAW,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE9D;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5D;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAEjD;;;;;;OAMG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjE"}

package/dist/utils/address.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import { Address } from '@ton/core';
+export type McpAddressNetwork = 'mainnet' | 'testnet';
+export declare function formatWalletAddress(address: string | Address, network: McpAddressNetwork): string;
+export declare function formatWalletAddressSafe(address: string | null | undefined, network: McpAddressNetwork): string | undefined;
+export declare function formatAssetAddress(address: string | Address, network: McpAddressNetwork): string;
+export declare function formatAssetAddressSafe(address: string | null | undefined, network: McpAddressNetwork): string | undefined;
+export declare function normalizeAddressForComparison(address: string): string | null;
+//# sourceMappingURL=address.d.ts.map

package/dist/utils/address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../../src/utils/address.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,SAAS,CAAC;AAEtD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAGjG;AAED,wBAAgB,uBAAuB,CACnC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAClC,OAAO,EAAE,iBAAiB,GAC3B,MAAM,GAAG,SAAS,CAUpB;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAGhG;AAED,wBAAgB,sBAAsB,CAClC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAClC,OAAO,EAAE,iBAAiB,GAC3B,MAAM,GAAG,SAAS,CAUpB;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM5E"}

package/dist/utils/agentic.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import type { ApiClient } from '@ton/walletkit';
+import type { TonNetwork } from '../registry/config.js';
+export interface AgenticImportCandidate {
+    address: string;
+    balanceNano: string;
+    balanceTon: string;
+    ownerAddress: string;
+    operatorPublicKey?: string;
+    originOperatorPublicKey?: string;
+    collectionAddress: string;
+    deployedByUser?: boolean;
+    name?: string;
+}
+type AgenticWalletValidationErrorCode = 'inactive_contract' | 'wrong_contract_type' | 'uninitialized_agentic_wallet' | 'unsupported_agentic_wallet_layout';
+export declare class AgenticWalletValidationError extends Error {
+    readonly code: AgenticWalletValidationErrorCode;
+    constructor(code: AgenticWalletValidationErrorCode, message: string);
+}
+export declare function generateOperatorKeyPair(): Promise<{
+    privateKey: string;
+    publicKey: string;
+}>;
+export declare function resolveOperatorCredentials(privateKey: string, expectedPublicKey?: string, deps?: {
+    createSigner?: (seed: Uint8Array) => Promise<{
+        publicKey: string;
+    }>;
+}): Promise<{
+    privateKey: string;
+    publicKey: string;
+}>;
+export declare function buildAgenticCreateDeepLink(input: {
+    operatorPublicKey: string;
+    callbackUrl: string;
+    agentName?: string;
+    source?: string;
+    tonDeposit?: string;
+}): string;
+export declare function buildAgenticDashboardLink(address: string): string;
+export declare function buildAgenticChangeKeyDeepLink(address: string, nextOperatorPublicKey: string): string;
+export declare function listAgenticWalletsByOwner(input: {
+    client: ApiClient;
+    ownerAddress: string;
+    collectionAddress: string;
+    network: TonNetwork;
+}): Promise<AgenticImportCandidate[]>;
+export declare function validateAgenticWalletAddress(input: {
+    client: ApiClient;
+    address: string;
+    collectionAddress?: string;
+    ownerAddress?: string;
+    network: TonNetwork;
+}): Promise<AgenticImportCandidate>;
+export {};
+//# sourceMappingURL=agentic.d.ts.map

package/dist/utils/agentic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentic.d.ts","sourceRoot":"","sources":["../../src/utils/agentic.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAoB,MAAM,gBAAgB,CAAC;AAGlE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAsBxD,MAAM,WAAW,sBAAsB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,KAAK,gCAAgC,GAC/B,mBAAmB,GACnB,qBAAqB,GACrB,8BAA8B,GAC9B,mCAAmC,CAAC;AAE1C,qBAAa,4BAA6B,SAAQ,KAAK;aAE/B,IAAI,EAAE,gCAAgC;gBAAtC,IAAI,EAAE,gCAAgC,EACtD,OAAO,EAAE,MAAM;CAKtB;AAgGD,wBAAsB,uBAAuB,IAAI,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAOlG;AAED,wBAAsB,0BAA0B,CAC5C,UAAU,EAAE,MAAM,EAClB,iBAAiB,CAAC,EAAE,MAAM,EAC1B,IAAI,CAAC,EAAE;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACvE,GACF,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAcpD;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAC9C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,MAAM,CAcT;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,GAAG,MAAM,CAKpG;AAgHD,wBAAsB,yBAAyB,CAAC,KAAK,EAAE;IACnD,MAAM,EAAE,SAAS,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,UAAU,CAAC;CACvB,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAqDpC;AAED,wBAAsB,4BAA4B,CAAC,KAAK,EAAE;IACtD,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,UAAU,CAAC;CACvB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAwClC"}

package/dist/utils/math.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ *
+ */
+export declare const UINT_256_MAX: bigint;
+//# sourceMappingURL=math.d.ts.map

package/dist/utils/math.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../../src/utils/math.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,YAAY,QAAoB,CAAC"}

package/dist/utils/private-key.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ *
+ */
+export interface ParsedPrivateKeyInput {
+    normalizedHex: string;
+    seed: Buffer;
+    wasCombinedKeypair: boolean;
+}
+export declare function parsePrivateKeyInput(privateKey: string): ParsedPrivateKeyInput;
+//# sourceMappingURL=private-key.d.ts.map

package/dist/utils/private-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"private-key.d.ts","sourceRoot":"","sources":["../../src/utils/private-key.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,qBAAqB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB,EAAE,OAAO,CAAC;CAC/B;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,qBAAqB,CAoB9E"}

package/dist/utils/ton-client.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import type { ApiClient } from '@ton/walletkit';
+import type { TonNetwork } from '../registry/config.js';
+export declare function getApiClientRequestIntervalMs(apiKey?: string): number;
+export declare function resolveToncenterApiKey(network: TonNetwork, apiKey?: string): string;
+export declare function createRateLimitedFetch(delayMs: number, fetchImpl?: typeof fetch): typeof fetch;
+export declare function createApiClient(network: TonNetwork, apiKey?: string): ApiClient;
+//# sourceMappingURL=ton-client.d.ts.map

package/dist/utils/ton-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ton-client.d.ts","sourceRoot":"","sources":["../../src/utils/ton-client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAiBxD,wBAAgB,6BAA6B,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnF;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,KAAK,CAuBrG;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAU/E"}

package/llms.txt

@@ -4,7 +4,14 @@
 
 ## Overview
 
-This MCP server provides tools for managing TON blockchain wallets. It supports wallet info, balance queries, transfers (TON, Jettons, NFTs), token swaps, transaction history, and DNS resolution.
+This MCP server provides tools for managing TON blockchain wallets. It supports wallet info, balance queries, transfers (TON, Jettons, NFTs), token swaps, transaction history, DNS resolution, local multi-wallet registry management, and agentic wallet onboarding.
+
+It has two runtime modes:
+- Registry mode: if `MNEMONIC` and `PRIVATE_KEY` are not set, wallets are loaded from the local TON config registry (`~/.config/ton/config.json` or `TON_CONFIG_PATH`)
+- Single-wallet mode: if `MNEMONIC` or `PRIVATE_KEY` is set, the server runs with one in-memory wallet
+
+In registry mode, wallet-scoped tools can also accept optional `walletSelector`. If omitted, the active wallet is used.
+HTTP mode is multi-session: each MCP client session gets its own server transport instead of sharing a process-wide singleton.
 
 ## Available Tools
 
@@ -12,10 +19,34 @@ This MCP server provides tools for managing TON blockchain wallets. It supports
 Get current wallet address and network info.
 Returns: address, network (mainnet or testnet)
 
+### list_wallets
+Registry mode only. List wallets stored in the local config registry.
+Returns: sanitized wallet list, count, active wallet id
+
+### get_current_wallet
+Registry mode only. Get the active wallet from the local config registry.
+Returns: sanitized wallet record
+
+### set_active_wallet
+Registry mode only. Switch active wallet.
+Parameters:
+- walletSelector (required): wallet id, name, or address
+
+### remove_wallet
+Registry mode only. Soft-delete a wallet from the local config registry. Removed wallets remain in config but are hidden from MCP lookups and lists.
+Parameters:
+- walletSelector (required): wallet id, name, or address
+
 ### get_balance
 Get TON balance of the wallet.
 Returns: address, balance in TON and nanoTON
 
+### get_balance_by_address
+Get TON balance for any address.
+Parameters:
+- address (required): TON wallet address
+Returns: address, balance in TON and nanoTON
+
 ### get_jetton_balance
 Get balance of a specific Jetton token.
 Parameters:
@@ -25,12 +56,32 @@ Parameters:
 List all Jettons in the wallet with balances and metadata.
 Returns: array of tokens with address, symbol, name, balance, decimals
 
+### get_jettons_by_address
+List all Jettons for any owner address.
+Parameters:
+- address (required): owner wallet address
+- limit (optional): 1-100, default 20
+- offset (optional): pagination offset
+Returns: array of tokens with address, symbol, name, balance, decimals
+
+### get_jetton_info
+Get Jetton master metadata.
+Parameters:
+- address (required): Jetton master contract address
+Returns: Jetton metadata (address, name, symbol, decimals, description, image, uri)
+
 ### get_transactions
 Get recent transaction history.
 Parameters:
 - limit (optional): 1-100, default 20
 Returns: transactions with type (TonTransfer, JettonTransfer, JettonSwap), amounts, addresses
 
+### get_transaction_status
+Get the status of a transaction by its normalized hash to know if it is pending, completed, or failed.
+Parameters:
+- normalizedHash (required): Normalized hash of the external-in transaction (Hex string)
+Returns: Transaction status (pending, completed, failed) and trace details
+
 ### get_known_jettons
 Get list of known/popular Jettons on TON.
 Returns: array with symbol, name, address, decimals
@@ -41,6 +92,7 @@ Parameters:
 - toAddress (required): recipient address
 - amount (required): amount in TON (e.g., "1.5")
 - comment (optional): transaction memo
+Returns: top-level normalizedHash plus details
 
 ### send_jetton
 Send Jettons to an address.
@@ -49,6 +101,7 @@ Parameters:
 - jettonAddress (required): token contract address
 - amount (required): human-readable amount
 - comment (optional): transaction memo
+Returns: top-level normalizedHash plus details
 
 ### send_raw_transaction
 Send raw transaction with full control.
@@ -56,6 +109,15 @@ Parameters:
 - messages (required): array of {address, amount (nanoTON), stateInit?, payload?}
 - validUntil (optional): expiry timestamp
 - 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.
@@ -72,6 +134,13 @@ Parameters:
 - limit (optional): 1-100, default 20
 - offset (optional): pagination offset
 
+### get_nfts_by_address
+List NFTs for any owner address.
+Parameters:
+- address (required): owner wallet address
+- limit (optional): 1-100, default 20
+- offset (optional): pagination offset
+
 ### get_nft
 Get NFT details.
 Parameters:
@@ -85,33 +154,109 @@ Parameters:
 - comment (optional): transaction memo
 
 ### resolve_dns
-Resolve .ton domain to wallet address.
+Resolve TON DNS-compatible domain to wallet address.
 Parameters:
-- domain (required): e.g., "foundation.ton"
+- domain (required): e.g., "foundation.ton" or "viqex.t.me"
 
 ### back_resolve_dns
-Find .ton domain for a wallet address.
+Find the associated DNS domain for a wallet address when available.
 Parameters:
 - address (required): TON wallet address
 
+### agentic_validate_wallet
+Registry mode only. Validate an agentic wallet against network/collection and optional owner.
+Parameters:
+- address (required): agentic wallet address
+- network (optional): mainnet or testnet
+- collectionAddress (optional): collection override
+- ownerAddress (optional): expected owner address
+
+### agentic_list_wallets_by_owner
+Registry mode only. Find agentic wallets owned by a main wallet.
+Parameters:
+- ownerAddress (required): owner wallet address
+- network (optional): mainnet or testnet
+
+### agentic_import_wallet
+Registry mode only. Import an existing agentic wallet into the local registry. If no matching pending draft exists, the wallet remains read-only until agentic_rotate_operator_key is completed.
+Parameters:
+- address (required): agentic wallet address
+- network (optional): mainnet or testnet
+- name (optional): wallet display name
+
+### 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:
+- network (optional): mainnet or testnet
+- name (optional): display name
+- source (optional): source or description
+- collectionAddress (optional): collection override
+- tonDeposit (optional): TON deposit hint
+
+### agentic_list_pending_root_wallet_setups
+Registry mode only. List pending root-agent onboarding drafts.
+
+### agentic_get_root_wallet_setup
+Registry mode only. Read one pending setup.
+Parameters:
+- setupId (required): pending setup identifier
+
+### agentic_complete_root_wallet_setup
+Registry mode only. Complete onboarding from callback state or a manual wallet address, then import the wallet and make it active.
+Parameters:
+- setupId (required): pending setup identifier
+- walletAddress (optional): manual wallet address if no callback was received
+- ownerAddress (optional): owner address hint for validation
+
+### agentic_cancel_root_wallet_setup
+Registry mode only. Cancel a pending setup.
+Parameters:
+- setupId (required): pending setup identifier
+
 ## Usage Patterns
 
+### Working With Multiple Wallets
+1. list_wallets to inspect stored wallets
+2. get_current_wallet to confirm the active wallet
+3. set_active_wallet if the user wants to switch
+4. For one-off calls, pass walletSelector directly to wallet-scoped tools instead of changing the active wallet
+
 ### Sending TON
-1. If recipient is .ton domain: resolve_dns first
+1. If recipient is a DNS name rather than a raw address: resolve_dns first
 2. send_ton with resolved address
+3. Default: poll get_transaction_status until completed or failed. User can ask to skip.
 
 ### Sending Tokens
 1. get_jettons to find token address
 2. send_jetton with token details
+3. Default: poll get_transaction_status until completed or failed. User can ask to skip.
 
 ### Swapping Tokens
 1. get_known_jettons if needed for addresses
 2. get_swap_quote for quote
 3. Confirm with user
 4. send_raw_transaction with quote's transaction params
+5. Default: poll get_transaction_status until completed or failed. User can ask to skip.
+
+### Importing an Existing Agentic Wallet
+1. agentic_validate_wallet if the wallet only exists as an address
+2. agentic_import_wallet to import it into the local registry
+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
+
+### 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
+3. Inspect agentic_get_root_wallet_setup or agentic_list_pending_root_wallet_setups
+4. If completion is manual, use agentic_validate_wallet
+5. agentic_complete_root_wallet_setup when callback data is available or when the user provides the created wallet address
 
 ## Important Notes
 
 - Always confirm transfers/swaps with user before executing
 - send_ton/send_jetton/get_swap_quote use human-readable amounts
-- Check transaction success in response
+- 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
+- Registry management 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 without `operator_private_key`; write tools cannot
+- **Default flow:** After any send, poll get_transaction_status until completed or failed. User can specify whether to check status.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ton/mcp",
-  "version": "0.1.12",
+  "version": "0.1.15-alpha.0",
   "description": "TON MCP Server - Model Context Protocol server for TON blockchain wallet operations",
   "license": "MIT",
   "type": "module",
@@ -54,7 +54,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",
     "zod": "^3.25.76",
-    "@ton/walletkit": "0.0.8"
+    "@ton/walletkit": "0.0.10"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1"
@@ -75,7 +75,7 @@
     "build:clean": "rimraf dist",
     "build:types": "tsc -p tsconfig.json --emitDeclarationOnly",
     "build:chmod": "chmod +x dist/cli.js",
-    "dev": "rolldown -c --watch",
+    "dev": "rolldown --watch -c",
     "dev:cli": "node --import tsx/esm src/cli.ts",
     "dev:cli:http": "node --import tsx/esm src/cli.ts --http",
     "lint": "eslint src --max-warnings 0",

package/skills/SKILL.md

@@ -1,31 +1,57 @@
 # TON Blockchain Wallet
 
-Manage TON blockchain wallet operations including balance queries, transfers, swaps, NFTs, and DNS resolution.
+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 domains
+- 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`)
-- `send_jetton` - Send tokens (`toAddress`, `jettonAddress`, `amount`, optional `comment`)
+- `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
+- `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)
@@ -34,10 +60,11 @@ Use this skill when the user wants to:
 
 ### 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 domain to address (`domain` like "foundation.ton")
+- `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
@@ -47,22 +74,50 @@ Use this skill when the user wants to:
 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 .ton domain, call `resolve_dns` first
+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
-- Transaction results include success status and details
+- **Default flow:** After sending, poll `get_transaction_status` until completed or failed. User can specify whether to check status.