Skip to content

Andy00L/ton-agent-kit

Repository files navigation

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.

npm npm packages MIT License

Quick StartPackagesActionsContractsCommerceMCPx402BotTests


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!, {
  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
Loading

Full architecture: ARCHITECTURE.md


Packages

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

Package Version What it does
@ton-agent-kit/core 1.2.4 Agent, plugin system, wallet, gas estimation, cache, verify
@ton-agent-kit/plugin-token 1.1.2 TON and Jetton transfers, balances, deploy, simulate
@ton-agent-kit/plugin-defi 1.2.3 DeDust, STON.fi, Omniston swaps, DCA, limits, yield, staking pools, trust
@ton-agent-kit/plugin-dns 1.0.4 .ton domain resolution, reverse lookup, domain info
@ton-agent-kit/plugin-nft 1.0.4 NFT info, transfer, collection data
@ton-agent-kit/plugin-staking 1.0.4 Stake/unstake TON in validator pools
@ton-agent-kit/plugin-analytics 1.1.2 TX history, wallet info, portfolio, equity curve, webhooks, contract calls
@ton-agent-kit/plugin-escrow 1.5.3 On-chain Tact escrow with dispute resolution
@ton-agent-kit/plugin-identity 1.6.8 Agent registry, reputation, discovery, on-chain scan fallback, cleanup
@ton-agent-kit/plugin-payments 1.0.18 x402 payment flow, delivery proofs, binary content detection, JSON-unwrap
@ton-agent-kit/plugin-agent-comm 1.3.6 Intent/offer marketplace protocol, testnet retry for indexing delays
@ton-agent-kit/plugin-memory 1.0.2 Key-value store (file, in-memory) with TTL and namespaces
@ton-agent-kit/plugin-endpoints 1.0.1 Dynamic x402 endpoint management (open, close, list)
@ton-agent-kit/orchestrator 1.1.1 Multi-agent planner, dispatcher, parallel execution
@ton-agent-kit/strategies 1.0.1 Deterministic workflow engine, scheduling, templates
@ton-agent-kit/x402-middleware 1.1.10 Express paywall middleware, address normalization, forward fee tolerance, anti-replay
@ton-agent-kit/mcp-server 1.1.1 Model Context Protocol server (stdio + SSE)
@ton-agent-kit/langchain 1.0.2 LangChain DynamicStructuredTool adapter
@ton-agent-kit/ai-tools 1.0.2 Vercel AI SDK and OpenAI tools adapter
@ton-agent-kit/wallet-store 1.0.1 AES-256-GCM encrypted wallet/key storage, file store with 48h TTL
@ton-agent-kit/network-mode 1.0.1 CLI network mode selector (local, public IP, tunnel)

All packages are @ton-agent-kit/* scoped on npm. Versions above are from the current package.json files.


All Actions

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

Token (7 actions)

Action What it does
get_balance TON balance for any wallet
get_jetton_balance Jetton balance for a wallet (via TONAPI)
transfer_ton Send TON with simulate-only, simulate-first, or direct mode
transfer_jetton Send Jettons (resolves Jetton wallet address)
deploy_jetton Deploy new Jetton minter with on-chain TEP-64 metadata
get_jetton_info Jetton master data (total supply)
simulate_transaction Build and emulate a TX via TONAPI without broadcasting

DeFi (12 actions)

Action What it does
swap_dedust Swap on DeDust DEX (TON/Jetton, Jetton/Jetton)
swap_stonfi Swap on STON.fi DEX
swap_best_price Aggregated swap via Omniston WebSocket (best price across all DEXes)
get_price USD and TON price for a Jetton (TONAPI rates)
create_dca_order DCA order via swap.coffee Strategies API
create_limit_order Limit order via swap.coffee
cancel_order Cancel active DCA or limit order
get_yield_pools List 2000+ yield/LP pools (16 protocols) from swap.coffee
yield_deposit Deposit into a yield pool (provide_liquidity op)
yield_withdraw Withdraw from a pool (burn LP tokens)
get_staking_pools Staking pools with APR/TVL from swap.coffee
get_token_trust Token trust score and risk flags from DYOR.io

DNS (3 actions)

Action What it does
resolve_domain Resolve .ton domain to wallet address
lookup_address Reverse lookup: wallet address to .ton domain
get_domain_info Domain details including expiry

NFT (3 actions)

Action What it does
get_nft_info NFT data (index, owner, collection, metadata)
transfer_nft Transfer NFT ownership
get_nft_collection Collection info (name, description, item count)

Staking (3 actions)

Action What it does
get_staking_info Nominator pool positions for a wallet
stake_ton Deposit to a validator pool
unstake_ton Withdraw from a validator pool

Analytics (8 actions)

Action What it does
get_transaction_history Recent wallet events from TONAPI
get_wallet_info Balance, status, interfaces, last activity
get_portfolio_metrics PnL, ROI, win rate, max drawdown
get_equity_curve Daily balance time-series
wait_for_transaction SSE stream, blocks until next TX or timeout
subscribe_webhook Register TONAPI webhook for TX notifications
call_contract_method Call any get-method on any contract (TVM stack decode)
get_accounts_bulk Bulk account info for up to 100 addresses

Escrow (14 actions)

Action What it does
create_escrow Deploy Tact escrow contract on-chain
deposit_to_escrow Fund the escrow
release_escrow Release funds to beneficiary
refund_escrow Refund funds to depositor
get_escrow_info Read on-chain state or list all escrows
confirm_delivery Buyer confirms delivery (optional x402 proof hash)
auto_release_escrow Auto-release after deadline (requires delivery confirmation)
open_dispute Freeze escrow for arbiter voting
join_dispute Self-select as arbiter with TON stake
vote_release Vote to release (majority settles)
vote_refund Vote to refund (majority settles)
claim_reward Collect arbiter reward after settlement
fallback_settle Settle after 72h voting deadline
seller_stake_escrow Seller deposits rep collateral before buyer funds

Identity (9 actions)

Action What it does
register_agent Register on-chain + local JSON registry
discover_agent Find agents by name (O(1)), capability index, or full scan with pagination
get_agent_reputation Read on-chain score, optionally submit rating
deploy_reputation_contract Deploy the Tact Reputation contract
withdraw_reputation_fees Pull accumulated fees (owner only)
process_pending_ratings Read queued ratings from memory, auto-submit
get_open_disputes List unsettled disputes from on-chain
trigger_cleanup Remove bad-score, inactive, or ghost agents
get_agent_cleanup_info Check if an agent is eligible for cleanup

Payments (2 actions)

Action What it does
pay_for_resource Full x402 flow: pay, wait, retry with proof hash. Handles JSON and binary responses.
get_delivery_proof Look up delivery proof by TX hash or escrow ID

Agent Communication (7 actions)

Action What it does
broadcast_intent Publish a service request on-chain (with description)
discover_intents Find open intents (index-based or linear scan)
send_offer Respond to an intent with price, delivery time, and endpoint
get_offers Read pending offers for an intent
accept_offer Accept an offer on-chain
settle_deal Finalize a deal with 0-100 rating
cancel_intent Cancel your own intent

Memory (4 actions)

Action What it does
save_context Save key-value entry with optional TTL
get_context Retrieve by key
list_context List entries in namespace with optional prefix filter
delete_context Delete entry by key

Endpoints (3 actions)

Action What it does
open_x402_endpoint Create a paid endpoint that calls a specified data action
close_x402_endpoint Remove a paid endpoint by path
list_x402_endpoints List all active endpoints with prices and serve counts

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]
Loading

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]
Loading

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)
Loading

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.addAgent(traderAgent);
orchestrator.addAgent(researchAgent);

const result = await orchestrator.runSwarm(
  "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
Loading

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. Custom stores just need has(hash) and add(hash).

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({
  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 is built into TonAgentKit. It takes a natural language goal, converts all registered actions to OpenAI tools, and runs a multi-step LLM loop. The LLM chooses which actions to call. Supports callbacks, max iterations, and parameter remapping.

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...]
Loading

Full docs: docs/strategies.md


Test Suite

28 test suites + shared setup. Interactive CLI runner.

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.

# Suite What it tests
01 plugin-system Plugin registration, toAITools, schema validation
02 token-plugin Balances, Jetton info, simulate
03 defi-plugin Prices, swap schemas
04 nft-plugin Collection data
05 dns-plugin Domain resolution, reverse lookup
06 analytics-plugin Wallet info, portfolio, equity curve, webhooks, contract calls
07 staking-plugin Staking pool info
08 live-transfer Real on-chain TON transfers (simulate, simulateFirst, direct)
09 transfer-edge-cases Zero amount, negative, insufficient, invalid address
10 escrow-onchain Full escrow lifecycle: create, deposit, release
11 identity-plugin Registration, discovery, reputation scoring, gas refund check
12 schema-validation All 75 actions bulk schema parse
13 cross-plugin-edge Unknown action, chainable .use(), mainnet vs testnet
14 strategy-engine defineStrategy, parseSchedule, execution
15 agent-lifecycle AgentManager: deploy, start, stop, restart, hooks
16 cache-layer Hits, misses, TTL, invalidation, LRU
17 mcp-sse SSE transport: auth, CORS, health, 401/404
18 escrow-advanced 2-agent lifecycle: deposit, release, refund, double-settle
19 orchestrator 4-agent swarm: parallel, dependencies, events, recovery
20 x402-security Anti-replay, wrong wallet, expired TX, cross-endpoint
21 commerce-e2e Full commerce flow: register, escrow, x402, dispute, rating
22 strategies-advanced Templates, conditions, transforms, scheduling, context
23 agent-manager Detailed lifecycle: restarts, max runtime, hooks
24 memory-plugin InMemory, File, plugin integration, TTL, namespace
25 omniston Omniston WebSocket quote for TON to USDT
26 autonomous-5agents 5-agent simulation (4 scripted + 1 LLM-driven, 60 min default)
27 demo-runloop 5 autonomous scenarios via runLoop
28 demo-commerce 2-agent commerce protocol demo

Comparison

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

Feature TON Agent Kit Solana Agent Kit Coinbase AgentKit
Actions 75 ~30 ~20
Plugins 12 monolithic modular
Chain TON Solana Base/ETH
On-chain escrow Yes (Tact contract, arbiter voting) No No
On-chain reputation Yes (score, cleanup, capability index) No No
Agent-to-agent protocol Yes (intent/offer on-chain) No No
x402 payments Yes (Express middleware) No Yes (ERC-8004)
MCP server Yes (stdio + SSE) Yes Yes
Telegram HITL Yes (inline buttons, 3 modes) No No
Multi-agent orchestrator Yes (planner + dispatcher) No CrewAI integration
Strategy engine Yes (DCA, price monitor, rebalance, rep guard) No No
LangChain adapter Yes Yes Yes
Vercel AI adapter Yes No Yes
Autonomous runtime Yes (runLoop) No No
Test suites 28 varies varies

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

Layer Technology
Runtime Bun 1.3+
Language TypeScript (strict)
Blockchain @ton/ton, @ton/core, @ton/crypto
DeFi @dedust/sdk, @ston-fi/sdk, swap.coffee API, Omniston WebSocket
Contracts Tact
AI / LLM OpenAI SDK (compatible with OpenRouter, Groq, Together, Mistral)
MCP @modelcontextprotocol/sdk
Bot grammY, @grammyjs/runner
HTTP Express
Validation Zod v4 (peer dependency)
APIs TONAPI, swap.coffee, DYOR.io

Examples

Example What it shows
examples/simple-agent 20 lines, 3 plugins, agent.methods proxy
examples/telegram-bot Telegram bot setup from npm packages
examples/mcp-server MCP server for Claude Desktop
examples/x402-server Express server with TON paywall endpoints

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.


License

MIT

About

Connect any AI agent to TON. 21 npm packages, 75 actions, 12 plugins, on-chain escrow with disputes, reputation scoring, agent-to-agent commerce protocol, x402 paid endpoints, MCP server, LangChain + Vercel AI adapters. The agent infrastructure for TON.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors