Ton Agent Kit

TON Agent Kit

The Agent Commerce Protocol for TON

Connect any AI agent to TON. Build agent economies with on-chain escrow, reputation, and paid APIs.

Quick Start • Packages • Actions • Contracts • Commerce • MCP • x402 • Bot • Tests

______________________________________________________________________

什么是TON Agent Kit？

一个TypeScript SDK，允许AI代理完全访问TON协议。12个插件中的75个操作，打包为21个npm模块。

代理可以交换令牌、部署合约、管理托管、广播意图、发现其他代理，并获得服务报酬。所有从一个单一 TonAgentKit 例子

核心循环：在链上注册、发布功能、查找服务、协商交易、托管资金、通过x402交付、结算、评级。

Agent A                  TON Blockchain                Agent B
  |                          |                           |
  |-- register_agent ------->|                           |
  |                          ||                           |
  |    "need price feed"     |                           |
  |                          |-------- discover -------->|
  |                          ||                           |
  |-- create_escrow -------->|                           |
  |-- deposit_to_escrow ---->|                           |
  |                          ||                           |
  |-- release_escrow ------->|                           |
  |-- settle_deal ---------->|                           |

快速开始

npm install @ton-agent-kit/core @ton-agent-kit/plugin-token @ton-agent-kit/plugin-defi

import { TonAgentKit, KeypairWallet } from "@ton-agent-kit/core";
import TokenPlugin from "@ton-agent-kit/plugin-token";
import DefiPlugin from "@ton-agent-kit/plugin-defi";

const wallet = await KeypairWallet.fromMnemonic(process.env.TON_MNEMONIC!, {
  network: "testnet",
  version: "V5R1",
});

const agent = new TonAgentKit(wallet, "https://testnet-v4.tonhubapi.com")
  .use(TokenPlugin)
  .use(DefiPlugin);

// Run an action directly
const balance = await agent.runAction("get_balance", {});

// Or expose all actions as OpenAI-compatible tools
const tools = agent.toAITools(); // Zod v4 -> JSON Schema

这 .use() 通话是可链接的。 toAITools() 将每个注册的动作模式（Zod v4）转换为OpenAI函数调用格式。通过 tools 任何LLM。

环境

# .env
TON_MNEMONIC=word1 word2 ... word24
TON_NETWORK=testnet
OPENAI_API_KEY=sk-...

看 .env.示例 查看完整列表。

______________________________________________________________________

建筑

graph TD
    subgraph Runtimes
        MCP["MCP Server
(packages/mcp-server)"]
        BOT["Telegram Bot
(separate repo)"]
        TEST["Test Runner
(tests.ts)"]
        CUSTOM["Your App"]
    end

    subgraph Core
        AK["TonAgentKit
.use() .runAction() .toAITools() .runLoop()"]
        PR["PluginRegistry"]
        AC["ActionCache (TTL + LRU)"]
        W["KeypairWallet / ReadOnlyWallet"]
    end

    subgraph Plugins["12 Plugins (75 actions)"]
        P1["Token (7)"]
        P2["DeFi (12)"]
        P3["Escrow (14)"]
        P4["Identity (9)"]
        P5["AgentComm (7)"]
        P6["Analytics (8)"]
        P7["+ DNS, NFT, Staking,
Payments, Memory, Endpoints"]
    end

    subgraph Infra
        O["Orchestrator"]
        S["Strategies"]
        X["x402 Middleware"]
        L["LangChain + AI Tools"]
    end

    subgraph Blockchain["TON Blockchain"]
        RC["Reputation Contract
(testnet)"]
        EC["Escrow Contracts
(per-deal)"]
    end

    MCP --> AK
    BOT --> AK
    TEST --> AK
    CUSTOM --> AK
    AK --> PR
    AK --> AC
    AK --> W
    PR --> Plugins
    P3 --> EC
    P4 --> RC
    P5 --> RC
    O --> AK
    S --> AK
    X --> Blockchain

完整架构： 建筑.md

______________________________________________________________________

包裹

21个npm包。12个带有操作的插件，9个基础设施模块。

所有包裹均 @ton-agent-kit/* 作用于npm。以上版本来自当前 package.json 文件夹。

______________________________________________________________________

所有操作

12个插件中的75个操作。每个操作都有一个Zod v4模式、一个描述和一个处理程序函数。

令牌（7个动作）

DeFi（12个动作）

DNS（3个操作）

NFT（3个动作）

质押（3个动作）

分析（8个动作）

托管（14项行动）

身份（9个动作）

付款（2项行动）

代理通信（7个动作）

记忆（4个动作）

端点（3个动作）

______________________________________________________________________

智能合约

在TON测试网上部署了两个Tact合约。两者都使用自筹资金模式：每次操作都会为 storageFund 涵盖长期链上存储的池。

信誉合同

链上代理注册、声誉评分、意向/报价市场和争议跟踪。

测试网地址： 0:6e78355a901729e4218ce6632a6a98df81e7a6740613defc99ef9639942385e9

• 14个接收处理程序，19个getter，39个状态映射
• 评分公式： (successes * 100) / totalTasks （0-100整数）
• 每个代理最多10个打开意图。配额压力触发自动清理过期意图。
• 按服务类型划分的O（1）代理发现能力指数
• 清理：删除得分低于20%（100+评级）、停用30+天或重影（7天后为0评级）的代理
• 级联擦除：当一个代理被清理后，最多20个意图到期，最多30个提议被拒绝

graph LR
    R[register_agent] --> D[discover_agent]
    D --> I[broadcast_intent]
    I --> O[send_offer]
    O --> A[accept_offer]
    A --> S[settle_deal + rating]
    S --> REP[Score updated on-chain]

完整文档： docs/信誉系统.md

代管合同

按交易部署。处理押金、交货确认、放行、退款、仲裁投票争议和回退解决。

• 12个接收处理程序，2个getter，5个状态映射
• 争议投票：72小时截止日期，多数票（底数（n/2）+1），仲裁人赌注
• 卖方持股比例按声誉评分（基础的50-150%）
• x402证明哈希存储在链上，用于可验证的交付
• 成本：部署约0.12吨，每次操作约0.03吨（退还天然气）

graph LR
    A[Create] --> B[Seller Stake]
    B --> C[Deposit]
    C --> D{Delivery?}
    D -->|confirmed| E[Release / Auto-Release]
    D -->|disputed| F[Open Dispute]
    F --> G[Arbiter Votes]
    G --> H{Majority?}
    H -->|release| E
    H -->|refund| I[Refund]
    H -->|timeout 72h| J[Fallback Settle]

完整文档： docs/escrow-system.md

______________________________________________________________________

代理商务协议

TON上代理交易服务的完整工作流程。全部挂在链子上。

sequenceDiagram
    participant A as Agent A (buyer)
    participant C as Reputation Contract
    participant B as Agent B (seller)
    participant E as Escrow Contract

    A->>C: register_agent
    B->>C: register_agent
    A->>C: broadcast_intent (service, budget, deadline, description)
    B->>C: discover_intents (by service hash)
    B->>C: send_offer (price, delivery time, endpoint)
    A->>C: get_offers
    A->>C: accept_offer
    A->>E: create_escrow + deposit
    B-->>A: deliver service (via x402 endpoint)
    A->>E: confirm_delivery (x402 proof hash)
    A->>E: release_escrow
    A->>C: settle_deal (rating 0-100)

关键细节：

• 意向书有24小时的最长截止日期（链上有上限）
• 这 description 领域 broadcast_intent 存储在链上，让卖家了解买家的需求
• 这 endpoint 领域 send_offer 存储在链上，因此买家在接受后知道在哪里打电话
• 随时取消意图（仅限创建者）。成本约为0.02吨。
• 以0-100的评分结算，更新卖家的链上声誉评分

完整文档： docs/agent-comm.md

______________________________________________________________________

多代理编排器

import { Orchestrator } from "@ton-agent-kit/orchestrator";

const orchestrator = new Orchestrator();
orchestrator.addAgent(traderAgent);
orchestrator.addAgent(researchAgent);

const result = await orchestrator.runSwarm(
  "Research TON DeFi pools and execute the best swap",
  { parallel: true, maxRetries: 2 }
);

编排器使用LLM规划器将目标分解为任务，根据加载的插件将其分配给代理，并并行运行独立任务。依赖关系会自动解决。

组件： Orchestrator, Planner, Dispatcher, AgentManager.

graph LR
    G[Goal] --> PL[Planner]
    PL --> T1[Task 1]
    PL --> T2[Task 2]
    PL --> T3[Task 3]
    T1 --> D[Dispatcher]
    T2 --> D
    T3 --> D
    D -->|parallel| A1[Agent 1]
    D -->|parallel| A2[Agent 2]
    A1 --> R[Aggregate Results]
    A2 --> R

______________________________________________________________________

MCP 服务器

将所有操作作为工具公开给Claude Desktop（或任何MCP客户端）。

MCP服务器位于 packages/mcp-server/它加载10个插件，并将每个操作作为MCP工具公开，此外还有一个 ton_agent_info 元工具。

运输： 标准 （默认）和 上海证券交易所 （使用Bearer令牌身份验证）。

{
  "mcpServers": {
    "ton-agent-kit": {
      "command": "bun",
      "args": ["run", "/path/to/ton-agent-kit/packages/mcp-server/src/index.ts"],
      "env": {
        "TON_MNEMONIC": "word1 word2 ... word24",
        "TON_NETWORK": "testnet"
      }
    }
  }
}

完整文档： docs/mcp-server.md

______________________________________________________________________

x402支付中间件

将API端点置于TON支付之后的Express中间件。买方发送TON，收到带有支付指令的402响应，付款，并使用TX哈希重试。

import { createPaymentServer, tonPaywall, MemoryReplayStore } from "@ton-agent-kit/x402-middleware";

app.get("/api/price", tonPaywall({
  recipient: wallet.address.toRawString(),
  amount: "0.001",
  network: "testnet",
  replayStore: new MemoryReplayStore(),
}), (req, res) => {
  res.json({ price: "3.42" });
});

具有3个存储后端的防重放保护： FileReplayStore, RedisReplayStore, MemoryReplayStore.定制商店只需要 has(hash) 和 add(hash).

这 EndpointPlugin (@ton-agent-kit/plugin-endpoints)允许代理在运行时打开/关闭x402端点。端点通过链上的报价进行广告宣传 endpoint 现场。

完整文档： docs/x402-protocol.md

______________________________________________________________________

电报机器人

Telegram机器人已移至单独的存储库： https://github.com/Andy00L/ton-agent-bot

它是一个多用户grammY机器人，具有内联键盘UI、3种操作模式（正常、监听、自动）、HITL批准的链上交易、每个用户加密的AES-256-GCM钱包存储和5个LLM提供商选项。

该机器人通过npm从该SDK导入所有12个插件。看 docs/telegram-bot.md 了解详情。

______________________________________________________________________

自主运行时

runLoop（内置于核心中）

const result = await agent.runLoop({
  goal: "Check balance, find DeFi pools with >10% APR, monitor prices",
  maxIterations: 10,
  model: "gpt-4o",
  onActionStart: (action, params) => console.log(`Running ${action}...`),
  onActionResult: (action, result) => console.log(`${action} done`),
  onComplete: (result) => console.log(`Completed: ${result.actions.length} actions`),
});

runLoop 内置于 TonAgentKit它采用自然语言目标，将所有注册的操作转换为OpenAI工具，并运行一个多步骤LLM循环。LLM选择调用哪些操作。支持回调、最大迭代次数和参数重映射。

策略引擎

import { defineStrategy, StrategyScheduler } from "@ton-agent-kit/strategies";

const dca = defineStrategy({
  name: "weekly-dca",
  schedule: "every 1d",
  steps: [
    { action: "get_balance", params: {} },
    { action: "swap_dedust", params: { amount: "1", tokenAddress: "EQ..." }, condition: (ctx) => ctx.results[0].balance > 2 },
  ],
});

4个内置模板：DCA、PriceMonitor、Rebalance、ReputationGuard。

graph LR
    D[defineStrategy] --> SC[Schedule: once / every Ns/m/h/d]
    SC --> R[StrategyRunner]
    R --> S1[Step 1: condition?]
    S1 -->|pass| E1[Execute action]
    S1 -->|fail| SK[Skip]
    E1 --> T1[Transform result]
    T1 --> S2[Step 2...]

完整文档： 文档/策略.md

______________________________________________________________________

测试套件

28个测试套件+共享设置。交互式CLI运行程序。

bun run tests.ts          # Interactive menu
bun run tests.ts all      # Run everything
bun run tests.ts 1,3,7-9  # Specific tests

结果保存到 tests/results/.log.

______________________________________________________________________

比较

与其他代理SDK进行诚实的比较。复选标记意味着该功能存在于代码库中，而不是说它是生产硬化的。

TON Agent Kit有更多的链上原语。权衡：它只适用于TON。如果你需要多链，这不是合适的工具。

______________________________________________________________________

技术栈

______________________________________________________________________

示例

______________________________________________________________________

贡献

添加插件

import { definePlugin, defineAction } from "@ton-agent-kit/core";
import { z } from "zod";

const myAction = defineAction({
  name: "my_action",
  description: "Does something useful",
  schema: z.object({ param: z.string() }),
  handler: async (agent, params) => {
    // agent.wallet, agent.rpcUrl, agent.network
    return { result: "done" };
  },
});

export default definePlugin({
  name: "my-plugin",
  actions: [myAction],
});

然后 agent.use(MyPlugin) 并且该动作在任何地方都可用： runAction, toAIToolsMCP，编排器。

______________________________________________________________________

许可证

麻省理工学院