Back to Details

ton-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

TON MCP Raw CLI Mode

TON MCP Raw CLI模式

Run any TON wallet MCP tool directly from the command line. The binary invokes the tool, prints the JSON result to stdout, and exits.
直接从命令行运行任何TON钱包MCP工具。该二进制文件会调用工具，将JSON结果打印到标准输出（stdout）后退出。

Invocation Modes

调用模式

CommandDescription
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
Use exactly one mode for a given workflow: either MCP server mode (
stdio
/
--http
) or raw CLI. Do not combine them in the same task/session.
命令描述
npx @ton/mcp@alpha
stdio MCP服务器（适用于Claude Desktop / MCP客户端）
npx @ton/mcp@alpha --http [port]
HTTP MCP服务器
npx @ton/mcp@alpha <tool_name> [--arg value ...]
Raw CLI：调用单个工具后退出
在特定工作流中仅使用一种模式：要么是MCP服务器模式（
stdio
/
--http
），要么是Raw CLI模式。请勿在同一任务/会话中混合使用。

Raw CLI Usage

Raw CLI 使用方法

bash
undefined
bash
undefined

No arguments

无参数

npx @ton/mcp@alpha get_balance
npx @ton/mcp@alpha get_balance

Named arguments (--key value)

命名参数（--key value）

npx @ton/mcp@alpha get_transactions --limit 5 npx @ton/mcp@alpha get_jetton_balance --jettonAddress EQAbc...
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

所有值均以纯字符串传递；也接受JSON对象/数组

npx @ton/mcp@alpha get_transactions --limit 10 npx @ton/mcp@alpha build_ton_transfer --toAddress UQA... --amount 0.1 --comment "hi" npx @ton/mcp@alpha generate_ton_proof --domain getgems.io --payload getgems-llm

Arguments are passed as `--key value` pairs. Objects/arrays (`{...}` / `[...]`) are JSON-parsed; everything else is kept as a plain string.
npx @ton/mcp@alpha get_transactions --limit 10 npx @ton/mcp@alpha build_ton_transfer --toAddress UQA... --amount 0.1 --comment "hi" npx @ton/mcp@alpha generate_ton_proof --domain getgems.io --payload getgems-llm

参数以`--key value`对的形式传递。对象/数组（`{...}` / `[...]`）会被JSON解析；其他所有内容均保留为纯字符串。

Output

输出

All tools print JSON to stdout. Errors are printed to stderr and the process exits with code 
1
.
bash
undefined
所有工具都会将JSON打印到标准输出（stdout）。错误信息会打印到标准错误（stderr），进程会以代码
1
退出。
bash
undefined

Capture output for scripting

捕获输出用于脚本编写

BALANCE=$(npx @ton/mcp@alpha get_balance) echo $BALANCE | jq '.balance'
undefined
BALANCE=$(npx @ton/mcp@alpha get_balance) echo $BALANCE | jq '.balance'
undefined

Environment Variables

环境变量

The CLI respects the same environment variables as the server:
VariableDescription
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.
该CLI支持与服务器相同的环境变量：
变量描述
NETWORK
mainnet
（默认值）或
testnet
MNEMONIC
单钱包模式下的24助记词
PRIVATE_KEY
十六进制编码的私钥（助记词的替代方案）
WALLET_VERSION
v5r1
（默认值）、
v4r2
或
agentic
TONCENTER_API_KEY
可选的Toncenter API密钥
TON_CONFIG_PATH
配置文件路径（默认值：
~/.config/ton/config.json
）
如果没有
MNEMONIC
或
PRIVATE_KEY
，CLI会使用本地配置注册表
~/.config/ton/config.json
（注册表模式）。在注册表模式下，钱包范围的工具接受可选的
--walletSelector
参数，通过ID、名称或地址指定特定钱包。

Tool Reference

工具参考

Wallet & Balance

钱包与余额

ToolRequired argsOptional args
get_wallet
—
--walletSelector
get_balance
—
--walletSelector
get_balance_by_address
--address
--walletSelector
get_jetton_balance
--jettonAddress
--walletSelector
get_jettons
—
--walletSelector
get_jettons_by_address
--address
--limit
, 
--offset
, 
--walletSelector
get_jetton_info
--jettonAddress
--walletSelector
get_transactions
—
--limit
, 
--walletSelector
get_transaction_status
--normalizedHash
--walletSelector
get_known_jettons
——
工具必填参数可选参数
get_wallet
—
--walletSelector
get_balance
—
--walletSelector
get_balance_by_address
--address
--walletSelector
get_jetton_balance
--jettonAddress
--walletSelector
get_jettons
—
--walletSelector
get_jettons_by_address
--address
--limit
, 
--offset
, 
--walletSelector
get_jetton_info
--jettonAddress
--walletSelector
get_transactions
—
--limit
, 
--walletSelector
get_transaction_status
--normalizedHash
--walletSelector
get_known_jettons
——

Wallet Registry (config-registry mode only)

钱包注册表（仅配置注册表模式）

ToolRequired argsOptional args
list_wallets
——
get_current_wallet
——
set_active_wallet
--walletSelector
—
remove_wallet
--walletSelector
—
工具必填参数可选参数
list_wallets
——
get_current_wallet
——
set_active_wallet
--walletSelector
—
remove_wallet
--walletSelector
—

Transfers

转账

ToolRequired argsOptional args
build_ton_transfer
--toAddress
, 
--amount
--comment
, 
--walletSelector
build_jetton_transfer
--toAddress
, 
--jettonAddress
, 
--amount
--comment
, 
--walletSelector
build_nft_transfer
--nftAddress
, 
--toAddress
--comment
, 
--walletSelector
send_raw_transaction
--messages
--validUntil
, 
--fromAddress
, 
--walletSelector
emulate_transaction
--messages
--validUntil
, 
--walletSelector
build_ton_transfer
/
build_jetton_transfer
/
build_nft_transfer
only build a transaction (return 
transaction.messages
plus 
transaction.fromAddress
); they do not broadcast. Preview with 
emulate_transaction
, then broadcast with 
send_raw_transaction --messages ... --fromAddress ...
.
工具必填参数可选参数
build_ton_transfer
--toAddress
, 
--amount
--comment
, 
--walletSelector
build_jetton_transfer
--toAddress
, 
--jettonAddress
, 
--amount
--comment
, 
--walletSelector
build_nft_transfer
--nftAddress
, 
--toAddress
--comment
, 
--walletSelector
send_raw_transaction
--messages
--validUntil
, 
--fromAddress
, 
--walletSelector
emulate_transaction
--messages
--validUntil
, 
--walletSelector
build_ton_transfer
/
build_jetton_transfer
/
build_nft_transfer
仅构建交易（返回
transaction.messages
和
transaction.fromAddress
）；不会广播交易。可使用
emulate_transaction
预览，然后通过
send_raw_transaction --messages ... --fromAddress ...
进行广播。

Swaps

兑换

ToolRequired argsOptional args
get_swap_quote
--fromToken
, 
--toToken
, 
--amount
--slippageBps
, 
--walletSelector
工具必填参数可选参数
get_swap_quote
--fromToken
, 
--toToken
, 
--amount
--slippageBps
, 
--walletSelector

NFTs

NFT

ToolRequired argsOptional args
get_nfts
—
--limit
, 
--offset
, 
--walletSelector
get_nfts_by_address
--address
--limit
, 
--offset
, 
--walletSelector
get_nft
--nftAddress
--walletSelector
工具必填参数可选参数
get_nfts
—
--limit
, 
--offset
, 
--walletSelector
get_nfts_by_address
--address
--limit
, 
--offset
, 
--walletSelector
get_nft
--nftAddress
--walletSelector

DNS

DNS

ToolRequired argsOptional args
resolve_dns
--domain
--walletSelector
back_resolve_dns
--address
--walletSelector
工具必填参数可选参数
resolve_dns
--domain
--walletSelector
back_resolve_dns
--address
--walletSelector

Authentication

认证

ToolRequired argsOptional args
generate_ton_proof
--domain
, 
--payload
--walletSelector
工具必填参数可选参数
generate_ton_proof
--domain
, 
--payload
--walletSelector

Example Session

示例会话

bash
undefined
bash
undefined

Check wallet address and network

查看钱包地址和网络

npx @ton/mcp@alpha get_wallet
npx @ton/mcp@alpha get_wallet

Check GRAM (ex. TON) balance

查看GRAM（如TON）余额

npx @ton/mcp@alpha get_balance
npx @ton/mcp@alpha get_balance

List all tokens

列出所有代币

npx @ton/mcp@alpha get_jettons
npx @ton/mcp@alpha get_jettons

Last 10 transactions

最近10笔交易

npx @ton/mcp@alpha get_transactions --limit 10
npx @ton/mcp@alpha get_transactions --limit 10

Get balance of a specific jetton

查看特定Jetton的余额

npx @ton/mcp@alpha get_jetton_balance --jettonAddress EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs
npx @ton/mcp@alpha get_jetton_balance --jettonAddress EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs

Resolve a .ton domain

解析.ton域名

npx @ton/mcp@alpha resolve_dns --domain foundation.ton
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"
npx @ton/mcp@alpha get_balance --walletSelector "my-hot-wallet"

In registry mode: list all registered wallets

注册表模式：列出所有已注册钱包

npx @ton/mcp@alpha list_wallets
npx @ton/mcp@alpha list_wallets

Send GRAM (ex. TON) — build, preview, then broadcast (confirm with user before the broadcast step)

发送GRAM（如TON）——构建、预览，然后广播（广播步骤前需用户确认）

npx @ton/mcp@alpha build_ton_transfer --toAddress UQA... --amount 0.5 --comment "payment" npx @ton/mcp@alpha emulate_transaction --messages '<transaction.messages>' # recommended preview npx @ton/mcp@alpha send_raw_transaction --messages '<transaction.messages>' --fromAddress '<transaction.fromAddress>'
npx @ton/mcp@alpha build_ton_transfer --toAddress UQA... --amount 0.5 --comment "payment" npx @ton/mcp@alpha emulate_transaction --messages '<transaction.messages>' # 推荐预览 npx @ton/mcp@alpha send_raw_transaction --messages '<transaction.messages>' --fromAddress '<transaction.fromAddress>'

Swap quote

获取兑换报价

npx @ton/mcp@alpha get_swap_quote --fromToken TON --toToken EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs --amount 1
npx @ton/mcp@alpha get_swap_quote --fromToken TON --toToken EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs --amount 1

Generate a TonProof for a service challenge

为服务挑战生成TonProof

npx @ton/mcp@alpha generate_ton_proof --domain getgems.io --payload getgems-llm
undefined
npx @ton/mcp@alpha generate_ton_proof --domain getgems.io --payload getgems-llm
undefined

Notes

注意事项

  • build_ton_transfer
    /
    build_jetton_transfer
    /
    build_nft_transfer
    build a transaction only; 
    send_raw_transaction
    is the tool that signs and broadcasts the prepared 
    transaction.messages
    (pass 
    transaction.fromAddress
    too — jetton/NFT messages are bound to the wallet they were built for)
  • Use 
    emulate_transaction
    to preview expected balance changes before broadcasting (fake signature)
  • Use 
    generate_ton_proof
    only with the exact domain and payload supplied by the user or verifying service; do not alter the payload before signing
  • generate_ton_proof
    requires signing access even though it does not broadcast a transaction
  • build_ton_transfer
    /
    build_jetton_transfer
    /
    build_nft_transfer
    and 
    emulate_transaction
    do not sign or broadcast — run them freely. Confirm with the user only before 
    send_raw_transaction
    (the broadcast), after previewing with 
    emulate_transaction
    ;
  • For confirmations and small option sets, prefer the host client's structured confirmation/choice UI when available; otherwise use a short natural-language yes/no prompt and never require an exact magic word;
  • 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.
  • build_ton_transfer
    /
    build_jetton_transfer
    /
    build_nft_transfer
    仅构建交易；
    send_raw_transaction
    是对已准备好的
    transaction.messages
    进行签名和广播的工具（同时传递
    transaction.fromAddress
    ——Jetton/NFT消息与构建它们的钱包绑定）
  • 使用
    emulate_transaction
    在广播前预览预期的余额变化（模拟签名）
  • 仅使用用户或验证服务提供的准确域名和负载调用
    generate_ton_proof
    ；签名前请勿修改负载
  • 即使
    generate_ton_proof
    不广播交易，也需要签名权限
  • build_ton_transfer
    /
    build_jetton_transfer
    /
    build_nft_transfer
    和
    emulate_transaction
    不会进行签名或广播——可自由运行。仅在
    send_raw_transaction
    （广播）前，且通过
    emulate_transaction
    预览后，需用户确认；
  • 对于确认操作和小型选项集，若可用则优先使用宿主客户端的结构化确认/选择UI；否则使用简短的自然语言是/否提示，切勿要求输入特定的暗语；
  • 发送交易后，轮询
    get_transaction_status --normalizedHash <hash>
    直到状态变为
    completed
    或
    failed
    （除非用户要求跳过）。
  • 在注册表模式下，默认使用
    ~/.config/ton/config.json
    中的活跃钱包。