Documentation

Everything you need to integrate Agent Gateway with your AI agents.

Agent Gateway Overview

Agent Gateway allows AI agents to request TON blockchain transactions that are securely approved by a human wallet owner. The AI agent never holds your private keys. It simply submits transfer requests for you to review, which you can then securely sign using TON Connect.

How It Works

Connect your wallet to the dashboard to generate a unique Agent Token.
Provide this token to your AI agent (Claude, ChatGPT, or a custom bot).
Agent utilizes the API to queue transfer requests.
Review pending requests and approve or reject them.
Approve to securely sign the transaction via TON Connect on your phone.

Security Model

Security is built directly into the architecture to ensure your assets remain safe. We offer two distinct operational models:

Standard Mode (Human-in-the-loop)

This is the default and recommended way to use Agent Gateway.

Feature	Description
No Private Key Exposure	The agent only has permission to request transfers. It cannot access your wallet keys.
Mandatory Approval	Every single transfer must be explicitly approved and signed by your wallet via TON Connect.
Session Isolation	Each token represents a unique session ID. Only the token holder can interact with that session's requests.
Auto-Expiry	Pending requests automatically expire after 5 minutes if left unapproved.

IN DEVELOPMENT: Autonomous Mode (Agent Wallets)

A new, high-risk feature is currently in development that allows you to deploy a dedicated sub-wallet for your AI agent.

CRITICAL SECURITY WARNING: Deploying an Agent Wallet removes the "Mandatory Approval" safeguard. The agent interacts with a consentless API to finalize transfers immediately, meaning the agent has full financial autonomy over the funds in that specific wallet.

If the agent malfunctions, hallucinates, or is compromised by malicious prompt injection, your funds can be drained instantly without your permission. Treat these as "hot wallets" and only fund them with amounts you are strictly willing to lose.

Agent Wallet smart contract on GitHub

Quick Start

Step 1: Get your token

Connect your wallet on the dashboard and copy your generated Agent Token.

Step 2: Make a transfer request

Use the API to request a transfer. Replace YOUR_TOKEN and the destination address.

curl -X POST https://api.tongateway.ai/v1/safe/tx/transfer \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "to": "EQD...destination-address",
    "amountNano": "1000000000"
  }'

Step 3: Approve

The pending request will be sent to your wallet app automatically. Approve it with one tap.

REST API Reference

Base URL: https://api.tongateway.ai — Full Swagger docs

All /v1/safe/* and /v1/wallet/* endpoints require the Authorization: Bearer TOKEN header.

Standard Safe API

Endpoints

Method	Endpoint	Description
POST	`/v1/auth/token`	Exchange a wallet address for a JWT token.
GET	`/v1/auth/me`	Verify your token and retrieve the associated wallet address.
POST	`/v1/auth/request`	Generate a one-time auth link for agent-driven wallet connection.
GET	`/v1/auth/check/:id`	Poll for auth completion. Returns token when wallet is connected.
POST	`/v1/safe/tx/transfer`	Request a new TON transfer (queued for approval).
GET	`/v1/safe/tx/pending`	List all pending transfer requests.
GET	`/v1/safe/tx/:id`	Fetch details of a specific request by ID.
POST	`/v1/safe/tx/:id/confirm`	Confirm a request post-wallet signature.
POST	`/v1/safe/tx/:id/reject`	Reject a pending transfer request.
GET	`/v1/wallet/balance`	Get wallet TON balance and account status.
GET	`/v1/wallet/jettons`	List all jetton (token) balances.
GET	`/v1/wallet/transactions`	Recent transaction history.
GET	`/v1/wallet/nfts`	List NFTs owned by the wallet.
GET	`/v1/dns/:domain/resolve`	Resolve a .ton domain to a wallet address.
GET	`/v1/market/price`	Get current TON and jetton prices.

Transfer Request Payload

Field	Type	Required	Description
`to`	string	Yes	Destination TON address.
`amountNano`	string	Yes	Amount in nanoTON (1 TON = 1000000000).
`payload`	string	No	Optional BOC-encoded payload.
`stateInit`	string	No	Optional stateInit BOC for contract deployment.

Autonomous Agent API (In Development)

DANGER: Endpoints in this category bypass human approval. Transactions are executed immediately by the Agent Wallet.

API specifications for Agent Wallet deployment and autonomous execution are currently under development and will be documented here prior to release.

MCP Server Integration

The simplest way to connect an AI agent is via the Model Context Protocol (MCP) server. This exposes Agent Gateway tools directly to the AI without requiring HTTP implementation.

Configuration for Claude Code

Run this command directly in your terminal:

claude mcp add-json tongateway '{
  "command": "npx",
  "args": ["-y", "@tongateway/mcp"],
  "env": {
    "AGENT_GATEWAY_API_URL": "https://api.tongateway.ai"
  }
}' --scope user

Alternatively, add manually to your .claude/settings.json:

{
  "mcpServers": {
    "tongateway": {
      "command": "npx",
      "args": ["-y", "@tongateway/mcp"],
      "env": {
        "AGENT_GATEWAY_API_URL": "https://api.tongateway.ai"
      }
    }
  }
}

Available MCP Tools

Tool	Description
`request_auth`	Generate a one-time link for wallet connection.
`get_auth_token`	Retrieve token after user connects wallet.
`get_wallet_info`	Get wallet address, TON balance, account status.
`get_jetton_balances`	List all token balances (USDT, NOT, etc.).
`get_transactions`	Recent transaction history.
`get_nft_items`	List NFTs owned by the wallet.
`resolve_name`	Resolve .ton domain to address.
`get_ton_price`	Get current TON price in USD/EUR.
`request_transfer`	Request a TON transfer (to, amountNano, payload?, stateInit?).
`get_request_status`	Check status of a transfer request by ID.
`list_pending_requests`	List all pending requests.