ton-agent-kit

<p align="center"> <img src="assets/hero.png" alt="TON Agent Kit" width="1000"> </p> <p align="center"> <h1 align="center">TON Agent Kit</h1> <p align="center"><strong>The Agent Commerce Protocol for TON</strong></p> <p align="center">Connect any AI agent to TON. Build agent economies with on-chain escrow, reputation, and paid APIs.</p> </p> <p align="center"> <a href="https://www.npmjs.com/package/@ton-agent-kit/core"><img src="https://img.shields.io/npm/v/@ton-agent-kit/core?label=%40ton-agent-kit%2Fcore" alt="npm"></a> <a href="https://www.npmjs.com/search?q=%40ton-agent-kit"><img src="https://img.shields.io/badge/npm-21%20packages-blue" alt="npm packages"></a> <a href="https://github.com/Andy00L/ton-agent-kit/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Andy00L/ton-agent-kit/ci.yml?branch=main&label=CI" alt="CI"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"></a> </p> <p align="center"> <a href="#quick-start">Quick Start</a> &bull; <a href="#packages">Packages</a> &bull; <a href="#all-actions">Actions</a> &bull; <a href="#smart-contracts">Contracts</a> &bull; <a href="#agent-commerce-protocol">Commerce</a> &bull; <a href="#mcp-server">MCP</a> &bull; <a href="#x402-payment-middleware">x402</a> &bull; <a href="#telegram-bot">Bot</a> &bull; <a href="#test-suite">Tests</a> </p>

---

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.

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

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)

| 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, with a caller-stated minimum output | | 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 clea