TON Agent 工具包

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

What is TON Agent Kit?

A TypeScript SDK that gives AI agents full access to TON protocols. 75 actions across 12 plugins, packaged as 21 npm modules.

Agents can swap tokens, deploy contracts, manage escrows, broadcast intents, discover other agents, and get paid for services. All from a single TonAgentKit instance.

The core loop: register on-chain, publish capabilities, find services, negotiate deals, escrow funds, deliver via x402, settle, rate.

Agent A                  TON Blockchain                Agent B
  |                          |                           |
  |-- register_agent ------->|                           |
  |                          |<------ register_agent ----|
  |-- broadcast_intent ----->|                           |
  |    "need price feed"     |                           |
  |                          |-------- discover -------->|
  |                          |<------- send_offer -------|
  |<- get_offers ------------|                           |
  |-- accept_offer --------->|                           |
  |-- create_escrow -------->|                           |
  |-- deposit_to_escrow ---->|                           |
  |                          |<-- deliver via x402 ------|
  |-- confirm_delivery ----->|                           |
  |-- release_escrow ------->|                           |
  |-- settle_deal ---------->|                           |

Quick Start

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!.split(" "), {
  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

The .use() calls are chainable. toAITools() converts every registered action schema (Zod v4) into OpenAI function-calling format. Pass tools to any LLM.

Environment

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

See .env.example for the full list.

Architecture

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

    subgraph Core
        AK["TonAgentKit<br>.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,<br>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<br>(testnet)"]
        EC["Escrow Contracts<br>(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

Full architecture: ARCHITECTURE.md

Packages

21 npm packages. 12 plugins with actions, 9 infrastructure modules.

All packages are @ton-agent-kit/* scoped on npm. Published versions live on npm; a table here would go stale the next time any one of the 21 is released, and it did.

All Actions

75 actions across 12 plugins. Each action has a Zod v4 schema, a description, and a handler function.

Token (7 actions)

DeFi (12 actions)

DNS (3 actions)

NFT (3 actions)

Staking (3 actions)

Analytics (8 actions)

Escrow (14 actions)

Identity (9 actions)

Payments (2 actions)

Agent Communication (7 actions)

Memory (4 actions)

Endpoints (3 actions)

Smart Contracts

Two Tact contracts deployed on TON testnet. Both use a self-funding model: each operation adds a small amount to a storageFund pool that covers long-term on-chain storage.

Reputation Contract

On-chain agent registry, reputation scoring, intent/offer marketplace, and dispute tracking.

Testnet address: 0:6e78355a901729e4218ce6632a6a98df81e7a6740613defc99ef9639942385e9

• 14 receive handlers, 19 getters, 39 state maps
• Score formula: (successes * 100) / totalTasks (0-100 integer)
• Max 10 open intents per agent. Quota pressure triggers automatic cleanup of expired intents.
• Capability index for O(1) agent discovery by service type
• Cleanup: removes agents below 20% score (100+ ratings), inactive 30+ days, or ghost (0 ratings after 7 days)
• Cascade erase: when an agent is cleaned up, expires up to 20 intents and rejects up to 30 offers

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]

Full docs: docs/reputation-system.md

Escrow Contract

Deployed per-deal. Handles deposit, delivery confirmation, release, refund, disputes with arbiter voting, and fallback settlement.

• 12 receive handlers, 2 getters, 5 state maps
• Dispute voting: 72h deadline, majority vote (floor(n/2)+1), arbiter stakes
• Seller stake scaling by reputation score (50-150% of base)
• x402 proof hash stored on-chain for verifiable delivery
• Cost: ~0.12 TON to deploy, ~0.03 TON per operation (gas refunded)

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]

Full docs: docs/escrow-system.md

Agent Commerce Protocol

The full workflow for agents trading services on TON. All on-chain.

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)

Key details:

• Intents have a 24h max deadline (capped on-chain)
• The description field in broadcast_intent is stored on-chain, letting sellers understand what the buyer needs
• The endpoint field in send_offer is stored on-chain, so the buyer knows where to call after accepting
• Cancel an intent anytime (only the creator). Costs ~0.02 TON.
• Settle with a 0-100 rating that updates the seller's on-chain reputation score

Full docs: docs/agent-comm.md

Multi-Agent Orchestrator

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

const orchestrator = new Orchestrator();
orchestrator.agent("trader", "executes swaps and transfers", traderAgent);
orchestrator.agent("researcher", "reads prices and pool data", researchAgent);

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

The orchestrator uses an LLM planner to break goals into tasks, assigns them to agents based on their loaded plugins, and runs independent tasks in parallel. Dependencies are resolved automatically.

Components: 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 Server

Expose all actions to Claude Desktop (or any MCP client) as tools.

The MCP server lives in packages/mcp-server/. It loads 10 plugins and exposes every action as an MCP tool, plus a ton_agent_info meta-tool.

Transports: stdio (default) and SSE (with Bearer token auth).

{
  "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"
      }
    }
  }
}

Full docs: docs/mcp-server.md

x402 Payment Middleware

Express middleware that gates API endpoints behind TON payments. The buyer sends TON, gets a 402 response with payment instructions, pays, and retries with the TX hash.

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" });
});

Anti-replay protection with 3 store backends: FileReplayStore, RedisReplayStore, MemoryReplayStore. A custom store implements has(hash) and add(hash), and should implement claim(hash) too: claim records the hash and reports whether the caller was first, in one atomic step. Without it the middleware falls back to has then add, and two requests carrying the same payment can both pass has before either reaches add. Version 2.0.0 fixed that race and a paywall bypass, and 3.0.0 added a budget so one payment cannot serve unlimited responses. Both are in CHANGELOG.md.

The EndpointPlugin (@ton-agent-kit/plugin-endpoints) lets agents open/close x402 endpoints at runtime. Endpoints are advertised in offers via the on-chain endpoint field.

Full docs: docs/x402-protocol.md

Telegram Bot

The Telegram bot has been moved to a separate repository: https://github.com/Andy00L/ton-agent-bot

It is a multi-user grammY bot with inline keyboard UI, 3 operating modes (Normal, Listen, Auto), HITL approval for on-chain transactions, AES-256-GCM encrypted per-user wallet storage, and 5 LLM provider options.

The bot imports all 12 plugins from this SDK via npm. See docs/telegram-bot.md for details.

Autonomous Runtime

runLoop (built into core)

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

console.log(result.summary);
console.log(`${result.steps.length} actions ran`);

runLoop is built into TonAgentKit. The goal is the first argument, options are the second. It converts every registered action to an OpenAI tool and runs a multi-step loop in which the model chooses what to call. It returns { goal, steps, summary }. Arguments the model sends go to the action's Zod schema unchanged: an argument that does not validate comes back to the model as a tool error for it to correct, and is never renamed on its behalf.

The model defaults to gpt-4.1-nano and maxIterations to 5.

Strategy Engine

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 built-in templates: 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...]

Full docs: docs/strategies.md

Build It From Source

Everything below the Quick Start needs the repository, not just the published packages. Requirements: Node 20 or 22 with npm 9 or later for the build, and Bun to run the test runner, the contract suites and @ton-agent-kit/wallet-store, which imports bun:sqlite. The three npm test commands below strip TypeScript types with --experimental-strip-types, which needs Node 22.6 or later; CI gates them on Node 22 for that reason.

git clone https://github.com/Andy00L/ton-agent-kit.git
cd ton-agent-kit
npm install
npm run build

npm run build typechecks and compiles all 21 packages. Success is exit 0 with no TypeScript diagnostics. CI runs it on Node 20 and Node 22 for every push to main and every pull request against it; the regression suites below run on Node 22 only.

npm test -w packages/core              # token amounts, action cache
npm test -w packages/x402-middleware   # paywall floor, replay claims
npm test -w packages/strategies        # scheduling, template action names
npm test -w packages/orchestrator      # task dispatch
npm test -w packages/plugin-agent-comm # TVM stack parsing
npm run test:contracts                 # both Tact contracts, in a sandbox
bun packages/wallet-store/test/secret.test.mjs
bun packages/wallet-store/test/file-store.test.mjs
bun packages/plugin-identity/test/message-bodies.test.mjs
bun packages/core/test/methods-proxy.test.mjs
bun packages/core/test/context-run-action.test.mjs

These run offline, with no wallet and no API key. Each prints n/n passed and exits 0 only when every check holds.

Test Suite

28 test suites + shared setup. Interactive CLI runner.

Unlike the regression suites above, these run against live testnet: 27 of the 28 need TON_MNEMONIC set to a funded testnet wallet, three of those also need OPENAI_API_KEY, and the remaining one opens a production websocket. None of them run in CI.

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

Results are saved to tests/results/<timestamp>.log.

Comparison

Honest comparison with other agent SDKs. Checkmarks mean the feature exists in the codebase, not that it is production-hardened.

TON Agent Kit has more on-chain primitives. The tradeoff: it only works with TON. If you need multi-chain, this is not the right tool.

Tech Stack

Examples

Contributing

Adding a Plugin

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],
});

Then agent.use(MyPlugin) and the action is available everywhere: runAction, toAITools, MCP, orchestrator.

Known Limitations

Stated here rather than found later.

• Do not use contracts/escrow.tact to hold money you care about. It has three defects that a redeployment is required to fix, all found by running the compiled contract rather than reading it, and each pinned by a check in contracts/test/escrow.sandbox.test.mjs:
  • The buyer controls every exit. A refund before the deadline does not check deliveryConfirmed (the guard exists but sits in the branch reached only after the deadline), AutoRelease requires a confirmation only the buyer can give, and a no-quorum FallbackSettle defaults to a refund. A buyer that never confirms takes the whole deal back. Measured: buyer +1.15 TON, seller 0, on a 1 TON deal the seller had opened a dispute over.
  • JoinDispute confiscates stakes. Its nativeReserve grows by more than the balance does, so roughly every other arbiter's action phase fails with exit 37: the registration rolls back and the stake stays, with no record of who sent it. Measured on a 1 TON deal with three arbiters at 0.6 TON: the buyer walked away with 1.577 TON, 0.727 of it arbiter money, and 0.621 TON was left in a contract with no owner and no recovery path.
  • ClaimReward pays the loser and strands the winners. Measured: 85% of the staked capital unrecoverable, and voting against the majority is the dominant strategy.
• contracts/reputation.tact has two of its own. Register and Rate advertise a 0.01 TON fee in their own error message; the real minimums are 0.032 and 0.019 TON, and anything between is accepted, kept, and recorded nowhere. The SDK attaches 0.12 TON so its callers are safe, but a client following the contract's message is not. Separately, Register runs out of gas somewhere around 240 to 300 intents and the registry then refuses every new agent permanently, because it pins at the hard gas limit where no amount of TON helps.
• Everything else in reputation.tact came through clean. Every ownership and authorization guard holds, including the one that stops an agent bidding on its own intent to manufacture a reputation, and the loops that looked unbounded are bounded. npm run verify:contracts proves the committed code cells still compile from the committed sources, byte for byte.
• npm audit reports advisories that cannot be cleared today, one of them critical (protobufjs, reached through @ston-fi/omniston-sdk). Clearing the tree means moving ai from 3 to 7 and @ston-fi/sdk from 1 to 2, both breaking changes.
• Every package publishes TypeScript source, not compiled JavaScript: main and types both point at src/index.ts. A consumer therefore needs a bundler, a loader, or Node 23.6 or later, and compiles this SDK under their own compiler settings.
• Escrow actions do not confirm the on-chain outcome. They send the message and write a local terminal status without reading back what the contract did. verifyContractExecution is exported from core for this and no action calls it yet.
• Delivery is self-reported in escrow, and the x402 payment proof hash is stored but never checked on chain. The reputation-score gate on escrow creation is enforced off chain and can be bypassed by calling the contract directly.
• @ton/ton 16.3.0 is deliberately not adopted. The range stays ^16.2.2: the release changes the wallet v5 types and the shape of account.balance.coins, so it needs a pass with on-chain tests.
• any remains outside the audited files, mostly in packages/core/src/agent.ts and the generated Tact bindings.

The full list, with the release each item relates to, is under Known issues in CHANGELOG.md.

License

MIT