mcp-server-tronlink

TronLink MCP Server — a production-ready MCP server that enables AI agents (Claude, GPT, etc.) to interact with the TRON blockchain through natural language.

Built on @tronlink/tronlink-mcp-core, it provides two operation modes:

• Playwright Mode — browser automation to control the TronLink Chrome extension UI (navigate, click, type, screenshot, etc.)
• Direct API Mode — on-chain operations via TronGrid API, GasFree transfers, and multi-signature management — no browser required

---

Architecture

┌──────────────────────────────────────────────┐
│   AI Agent (Claude Desktop / Claude Code)    │
└──────────────────┬───────────────────────────┘
                   │ MCP Protocol (stdio)
┌──────────────────▼───────────────────────────┐
│  @tronlink/mcp-server-tronlink               │
│                                              │
│  ┌── Playwright Mode ─────────────────────┐  │
│  │  TronLinkSessionManager                │  │
│  │  ├── Browser launch & extension load   │  │
│  │  ├── Extension ID auto-detection       │  │
│  │  ├── Multi-tab tracking & role classify │  │
│  │  ├── State extraction (DOM analysis)   │  │
│  │  │   ├── TRON address (T-prefix, 34ch) │  │
│  │  │   ├── TRX balance                   │  │
│  │  │   ├── Network (Mainnet/Nile/Shasta) │  │
│  │  │   └── Screen detection (15 screens) │  │
│  │  └── Confirmation popup handling       │  │
│  └────────────────────────────────────────┘  │
│                                              │
│  ┌── Direct API Mode ─────────────────────┐  │
│  │  TronLinkOnChainCapability (14 tools)  │  │
│  │  ├── TRX/TRC20 transfer, swap, stake  │  │
│  │  ├── Account & resource queries       │  │
│  │  └── Multi-sig setup & signing        │  │
│  │                                        │  │
│  │  TronLinkGasFreeCapability (3 tools)   │  │
│  │  ├── Zero-gas TRC20 transfers         │  │
│  │  └── Account & transaction queries    │  │
│  │                                        │  │
│  │  TronLinkMultiSigCapability (5 tools)  │  │
│  │  ├── Permission queries               │  │
│  │  ├── Transaction submit & list        │  │
│  │  └── WebSocket real-time monitoring   │  │
│  └────────────────────────────────────────┘  │
│                    │ (uses)                   │
│  ┌─────────────────▼──────────────────────┐  │
│  │  @tronlink/tronlink-mcp-core               │  │
│  │  ├── MCP Server (stdio transport)      │  │
│  │  ├── 56+ tl_* tool handlers            │  │
│  │  ├── Knowledge Store                   │  │
│  │  └── Discovery Utils                   │  │
│  └────────────────────────────────────────┘  │
└──────────────────┬───────────────────────────┘
                   │ Playwright (Chromium)     ← only for Playwright mode
┌──────────────────▼───────────────────────────┐
│  Chrome Browser                              │
│  ├── TronLink Extension (MV3)                │
│  │   ├── popup.html#/home                    │
│  │   ├── popup.html#/login                   │
│  │   ├── popup.html#/settings                │
│  │   ├── popup.html#/transfer                │
│  │   └── secondary_popup.html (confirmations)│
│  └── DApp Pages                              │
└──────────────────────────────────────────────┘

---

Quick Start

Zero-Config Mode (Fastest)

Just configure TL_TRONGRID_URL. If no wallet exists, the server starts and shows two setup options instead of creating one immediately:

{
  "mcpServers": {
    "tronlink": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": ".",
      "env": {
        "TL_TRONGRID_URL": "https://nile.trongrid.io"
      }
    }
  }
}

1. Auto-create via MCP tool: call tl_wallet_create The server generates a random password, saves it to ~/.agent-wallet/runtime_secrets.json, creates an encrypted main wallet, and enables the running session to use it.
2. Manual CLI setup:
   1. Create a wallet: agent-wallet start local_secure --generate --wallet-id main
   2. Add AGENT_WALLET_PASSWORD to your .mcp.json env (must match the password used above)
   3. Restart the MCP server

Manual Setup (Existing Wallet or CLI-First)

If you prefer to create a wallet yourself or use an existing one:

1. Create a wallet: agent-wallet start local_secure --generate --wallet-id main
2. Add AGENT_WALLET_PASSWORD to your .mcp.json env (must match the password used above)
3. Restart the MCP server

Once a wallet is configured (auto or manual), on-chain tools (tl_chain_*, tl_gasfree_*, tl_multisig_*) become available.

Playwright Setup

1. Build TronLink Extension (Playwright mode only)

cd /path/to/tronlink-extension-pro
npm install
npm run build
# Output: dist/

2. Install and Build MCP Server

cd /path/to/mcp-server-tronlink
npm install
npm run build

3. Create Wallet Locally (required for on-chain tools)

npm install -g @bankofai/agent-wallet
agent-wallet start local_secure --generate --wallet-id main

4. Configure MCP JSON

All configuration is injected via the env field in the MCP JSON. The server does not read .env files.

See the "Integration" section below. For variable reference, see .env.example.

---

Two Operation Modes

Playwright Mode — Browser Automation

Controls the TronLink Chrome extension through Playwright. Requires a built TronLink extension.

Use when you need to:

• Automate wallet UI interactions (import wallet, navigate screens, click buttons)
• Test DApp integrations (connect wallet, sign transactions via popup)
• Take screenshots of wallet/DApp state
• Run end-to-end tests against the TronLink UI

Tools (27): tl_launch, tl_cleanup, tl_navigate, tl_click, tl_type, tl_screenshot, tl_get_state, tl_describe_screen, tl_accessibility_snapshot, tl_list_testids, tl_switch_to_tab, tl_close_tab, tl_wait_for, tl_wait_for_notification, tl_scroll, tl_keyboard, tl_evaluate, tl_clipboard, tl_seed_contract, tl_seed_contracts, tl_get_contract_address, tl_list_contracts, tl_set_context, tl_get_context, tl_run_steps, tl_list_flows, tl_list_testids

Direct API Mode — On-Chain Operations

Calls TRON blockchain APIs directly using TronWeb-compatible REST calls and local cryptographic signing. No browser or extension required.

Use when you need to:

• Query account balances, resources, and transaction history
• Send TRX or TRC20 tokens programmatically
• Stake/unstake TRX, delegate bandwidth/energy
• Execute token swaps via SunSwap V2/V3
• Manage multi-signature wallets and transactions
• Send gas-free TRC20 transfers

Tool groups:

Group	Tools	Required Config
On-Chain (14)	tl_chain_*	agent-wallet + TL_TRONGRID_URL
MultiSig (5)	tl_multisig_*	TL_MULTISIG_BASE_URL + credentials
GasFree (3)	tl_gasfree_*	TL_GASFREE_BASE_URL + API key

Both modes can run simultaneously — configure what you need and the server enables the corresponding tools automatically.

---

Configuration

Environment Variables

Variable	Description	Default
Playwright Mode
TRONLINK_EXTENSION_PATH	TronLink extension build directory (containing manifest.json)	Auto-detected
TRONLINK_SOURCE_PATH	TronLink extension source directory (enables Build capability)	—
TL_MODE	Working mode: e2e (test) or prod (production)	prod
TL_HEADLESS	Run browser in headless mode: true / false	false
TL_SLOW_MO	Playwright slow-motion delay in ms (for debugging)	0
TronGrid API
TL_TRONGRID_URL	TronGrid full-node API URL	—
TL_TRONGRID_API_KEY	TronGrid API Key (required for Mainnet, not needed for Nile/Shasta)	—
Wallet (agent-wallet)
AGENT_WALLET_PASSWORD	Encryption password (optional if using tl_wallet_create; required for manual or existing wallets)	Auto-generated by tl_wallet_create
AGENT_WALLET_DIR	Custom wallet storage directory	~/.agent-wallet
TL_OWNER_WALLET_ID	Owner wallet ID for multisig signing	active wallet
TL_COSIGNER_WALLET_ID	Co-signer wallet ID for multisig	—
On-Chain
TL_SUNSWAP_ROUTER	SunSwap V2 Router contract address	—
TL_SUNSWAP_V3_ROUTER	SunSwap Smart Router (V3) contract address	—
TL_WTRX_ADDRESS	WTRX contract address	Mainnet default
Multi-Signature
TL_MULTISIG_BASE_URL	Multi-sig service API URL	—
TL_MULTISIG_SECRET_ID	Multi-sig service Secret ID	—
TL_MULTISIG_SECRET_KEY	Multi-sig service Secret Key (HmacSHA256 signing key)	—
TL_MULTISIG_CHANNEL	Multi-sig service channel name	—
GasFree
TL_GASFREE_BASE_URL	GasFree service URL	—
TL_GASFREE_API_KEY	GasFree API Key	—
TL_GASFREE_API_SECRET	GasFree API Secret	—

Configuring multisig env vars (BASE_URL + SECRET_ID + SECRET_KEY + CHANNEL) auto-enables the tl_multisig_* tools.

Configuring agent-wallet + TL_TRONGRID_URL enables the tl_chain_* on-chain tool group (14 tools).

Configuring TL_GASFREE_BASE_URL + TL_GASFREE_API_KEY enables the tl_gasfree_* gas-free transfer tool group (3 tools).

Security: Private keys are managed by @bankofai/agent-wallet with encrypted local storage (local_secure). Plain-text keys in env vars are not supported. If no wallet exists at startup, the server shows two paths: call tl_wallet_create to auto-generate one (password saved to ~/.agent-wallet/runtime_secrets.json), or create one manually via CLI and set AGENT_WALLET_PASSWORD.

API Key Acquisition Guide

TronGrid API Key (required for on-chain operations)

Used by all tl_chain_* tools (balance queries, transfers, staking, swaps, etc.)

Item	Details
Portal	https://www.trongrid.io/
Cost	Free (100,000 requests/day); paid plans available
Testnet	Nile/Shasta do not require an API Key
Mainnet	API Key is required

Steps:

1. Visit https://www.trongrid.io/ → click Sign Up
2. Register with email and verify
3. Go to Dashboard → Create API Key
4. Enter project name → generate key
5. Copy the API Key into TL_TRONGRID_API_KEY

GasFree API Key (gas-free TRC20 transfers)

Used by tl_gasfree_* tools — TRC20 token transfers where gas fees are paid by the service provider

Item	Details
Developer Center	https://developer.gasfree.io/
API Spec	https://gasfree.io/specification
SDK	npm install @gasfree/gasfree-sdk (GitHub)
Testnet URL	https://open-test.gasfree.io/nile/
Mainnet URL	https://open.gasfree.io/tron/

Steps:

1. Visit https://developer.gasfree.io → register a developer account
2. Create an application → system generates API Key and API Secret
3. Fill in TL_GASFREE_API_KEY and TL_GASFREE_API_SECRET
4. Note: Nile testnet also requires a key, but approval is fast

SunSwap Smart Router Address (DEX trading)

Used by tl_chain_swap_v3 — token swaps via SunSwap V3 concentrated liquidity

Network	Smart Router Address	Source
Mainnet	TCFNp179Lg46D16zKoumd4Poa2WFFdtqYj	SUN.io Docs
Nile	TB6xBCixqRPUSKiXb45ky1GhChFJ7qrfFj	Same

No application needed — just set the address in TL_SUNSWAP_V3_ROUTER.

The Smart Router is SunSwap's unified entry point that automatically selects the optimal route across V1/V2/V3/PSM/SunCurve pools.

WTRX Contract Address

Used for TRX ↔ Token swaps (Wrapped TRX)

Network	WTRX Address
Mainnet	TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR (default, no manual config needed)
Nile	Query via SunSwap Router's WETH() method

No configuration needed for Mainnet (uses default). For Nile testnet, query the address and set TL_WTRX_ADDRESS.

Multi-Signature Service Credentials

Used by tl_multisig_* tools — permission queries, transaction submission, real-time monitoring

Item	Details
Nile Testnet	https://apinile.walletadapter.org
Mainnet	https://api.walletadapter.org
Test Credentials	SECRET_ID=TEST / SECRET_KEY=TESTTESTTEST / CHANNEL=test

Testnet works out of the box with the test credentials above.

Production: Contact the TronLink team for official credentials.

Wallet Setup (Optional — auto-created if not configured)

If no wallet exists, the server will prompt you to choose one of two paths:

1. Auto-create in the current MCP session: call tl_wallet_create
2. Manual CLI setup: create the wallet yourself, then set AGENT_WALLET_PASSWORD and restart

Manual CLI commands:

# 1. Install agent-wallet CLI
npm install -g @bankofai/agent-wallet

# 2. Create an encrypted wallet
agent-wallet start local_secure --generate --wallet-id main

# 3. (Optional) Create a cosigner wallet for multisig
agent-wallet start local_secure --generate --wallet-id cosigner

You can also manage wallets at runtime via MCP tools: tl_wallet_list, tl_wallet_create, tl_wallet_set_active.

Quick Config Reference (Nile Testnet .mcp.json)

{
  "mcpServers": {
    "tronlink": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": ".",
      "env": {
        "TRONLINK_EXTENSION_PATH": "/path/to/tronlink-extension/dist",
        "TL_MODE": "prod",
        "TL_HEADLESS": "false",
        "TL_TRONGRID_URL": "https://nile.trongrid.io",
        "AGENT_WALLET_PASSWORD": "your-wallet-password",
        "TL_SUNSWAP_ROUTER": "TKzxdSv2FZKQrEqkKVgp5DcwEXBEKMg2Ax",
        "TL_SUNSWAP_V3_ROUTER": "TB6xBCixqRPUSKiXb45ky1GhChFJ7qrfFj",
        "TL_MULTISIG_BASE_URL": "https://apinile.walletadapter.org",
        "TL_MULTISIG_SECRET_ID": "TEST",
        "TL_MULTISIG_SECRET_KEY": "TESTTESTTEST",
        "TL_MULTISIG_CHANNEL": "test",
        "TL_GASFREE_BASE_URL": "https://open-test.gasfree.io/nile/",
        "TL_GASFREE_API_KEY": "your_gasfree_api_key",
        "TL_GASFREE_API_SECRET": "your_gasfree_api_secret"
      }
    }
  }
}

Testnet TRX faucet: https://nileex.io/join/getJoinPage

API-Only Config (no Playwright, no browser)

If you only need direct API tools (on-chain, multisig, gasfree) without browser automation, you can omit TRONLINK_EXTENSION_PATH:

{
  "mcpServers": {
    "tronlink": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": ".",
      "env": {
        "TL_TRONGRID_URL": "https://nile.trongrid.io",
        "AGENT_WALLET_PASSWORD": "your-wallet-password",
        "TL_MULTISIG_BASE_URL": "https://apinile.walletadapter.org",
        "TL_MULTISIG_SECRET_ID": "TEST",
        "TL_MULTISIG_SECRET_KEY": "TESTTESTTEST",
        "TL_MULTISIG_CHANNEL": "test",
        "TL_GASFREE_BASE_URL": "https://open-test.gasfree.io/nile/",
        "TL_GASFREE_API_KEY": "your_gasfree_api_key",
        "TL_GASFREE_API_SECRET": "your_gasfree_api_secret"
      }
    }
  }
}

This configuration enables API tools (including 3 wallet management tools) without launching a browser. Playwright-based tools (tl_launch, tl_click, etc.) will not be available. If AGENT_WALLET_PASSWORD is omitted, startup will prompt you to choose either tl_wallet_create or manual CLI setup.

Extension Path Auto-Detection

If TRONLINK_EXTENSION_PATH is not set, the server searches these locations:

1. ./dist
2. ./dist/prd
3. ../tronlink-extension-pro/dist
4. ../tronlink-extension-pro/dist/prd

Condition: directory contains a manifest.json file.

---

Integration

Option 1: Project-Level .mcp.json (Recommended)

The project includes a .mcp.json file. Claude Code auto-detects it. Fill in your credentials. If no wallet exists yet, either call tl_wallet_create after startup, or create the wallet locally first and set AGENT_WALLET_PASSWORD:

# .mcp.json already exists, edit directly
# Fill in TL_MULTISIG_SECRET_ID / SECRET_KEY / CHANNEL etc.
# If you want the manual wallet path, also add AGENT_WALLET_PASSWORD after creating the wallet locally

.mcp.json example:

{
  "mcpServers": {
    "tronlink": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": ".",
      "env": {
        "TRONLINK_EXTENSION_PATH": "../tronlink-extension-pro/dist",
        "TL_MODE": "prod",
        "TL_HEADLESS": "false",
        "TL_SLOW_MO": "0",
        "TL_TRONGRID_URL": "https://nile.trongrid.io",
        "AGENT_WALLET_PASSWORD": "your-wallet-password",
        "TL_TRONGRID_API_KEY": "",
        "TL_MULTISIG_BASE_URL": "https://apinile.walletadapter.org",
        "TL_MULTISIG_SECRET_ID": "your-secret-id",
        "TL_MULTISIG_SECRET_KEY": "your-secret-key",
        "TL_MULTISIG_CHANNEL": "your-channel"
      }
    }
  }
}

.mcp.json is in .gitignore and will not be committed.

Option 2: Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tronlink": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-tronlink/dist/index.js"],
      "env": {
        "TRONLINK_EXTENSION_PATH": "/absolute/path/to/tronlink-extension-pro/dist",
        "TL_TRONGRID_URL": "https://nile.trongrid.io",
        "AGENT_WALLET_PASSWORD": "your-wallet-password",
        "TL_MULTISIG_BASE_URL": "https://apinile.walletadapter.org",
        "TL_MULTISIG_SECRET_ID": "your-secret-id",
        "TL_MULTISIG_SECRET_KEY": "your-secret-key",
        "TL_MULTISIG_CHANNEL": "your-channel"
      }
    }
  }
}

Option 3: Claude Code Global Settings

Edit ~/.claude/settings.json or project-level .claude/settings.json:

{
  "mcpServers": {
    "tronlink": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-tronlink/dist/index.js"],
      "env": {
        "TRONLINK_EXTENSION_PATH": "/absolute/path/to/tronlink-extension-pro/dist",
        "TL_TRONGRID_URL": "https://nile.trongrid.io",
        "AGENT_WALLET_PASSWORD": "your-wallet-password"
      }
    }
  }
}

Other MCP Clients

Any client supporting the MCP protocol (stdio transport) can connect. The server communicates via stdin/stdout and handles tools/list and tools/call requests.

---

Usage Examples

Example 1: Direct API — Query Account and Send TRX

User: What is the balance of my account, and send 10 TRX to TAbCdEf...

AI executes:
1. tl_chain_get_address()
   → { address: "TVGcWWdJn9EnJP1LHCJDQaVCEcGsapKrVF" }

2. tl_chain_get_account({ address: "TVGcWWdJn9EnJP1LHCJDQaVCEcGsapKrVF" })
   → { balance_trx: "100.5", bandwidth: 600, energy: 0, ... }

3. tl_chain_send({ to: "TAbCdEf...", amount: "10" })
   → { txId: "abc123...", success: true }

Example 2: Direct API — Stake TRX and Delegate Energy

User: Stake 100 TRX for energy, then delegate energy to TAbCdEf...

AI executes:
1. tl_chain_stake({ action: "freeze", amount_trx: 100, resource: "ENERGY" })
   → { txId: "...", success: true }

2. tl_chain_resource({
     action: "delegate",
     resource: "ENERGY",
     amount_trx: 50,
     receiver: "TAbCdEf..."
   })
   → { txId: "...", success: true }

Example 3: Direct API — Token Swap via SunSwap

User: Swap 10 TRX for USDT

AI executes:
1. tl_chain_swap_v3({
     from_token: "TRX",
     to_token: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
     amount: "10",
     slippage: 1
   })
   → { txId: "...", amountOut: "1.52", ... }

Example 4: Direct API — GasFree Transfer

User: Send 10 USDT to TAbCdEf... without paying gas

AI executes:
1. tl_gasfree_get_account({ address: "TVGcWWdJn9..." })
   → { eligible: true, daily_quota_remaining: 3, supported_tokens: [...] }

2. tl_gasfree_send({
     to: "TAbCdEf...",
     contract_address: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
     amount: "10"
   })
   → { txId: "...", success: true, gas_paid_by: "gasfree" }

Example 5: Direct API — Multi-Signature Workflow

User: Check my multisig permissions and submit a transaction

AI executes:
1. tl_multisig_query_auth({ address: "TXz9dfkjui6..." })
   → { permissions: [{ owner_address: "TDqGdq76...",
       active_permissions: [{ threshold: 66, weight: 35 }] }] }

2. tl_multisig_list_tx({ address: "TXz9dfkjui6...", state: 0 })
   → { total: 3, transactions: [{ hash: "18213ab5...",
       threshold: 3, currentWeight: 2, stateText: "processing" }] }

3. tl_multisig_submit_tx({
     address: "TXz9dfkjui6...",
     function_selector: "transfer(address,uint256)",
     transaction: { raw_data: {...}, signature: ["659143f5..."] }
   })
   → { success: true, code: 0, message: "OK" }

4. tl_multisig_connect_ws({ address: "TXz9dfkjui6..." })
   → { connected: true }  // real-time pending tx notifications

Example 6: Playwright — Launch Wallet and Check State

User: Launch TronLink and show me the wallet state

AI executes:
1. tl_launch({ fixture: "default" })
   → { sessionId: "tl-1741504523", extensionId: "abc...", extensionUrl: "chrome-extension://..." }

2. tl_get_state()
   → { currentScreen: "home", isUnlocked: true, accountAddress: "TXyz...",
       networkName: "Mainnet", balanceTrx: "100.5" }

Example 7: Playwright — DApp Interaction

User: Open SunSwap and connect wallet

AI executes:
1. tl_launch({ fixture: "default" })
2. tl_navigate({ target: "url", url: "https://sunswap.com" })
3. tl_click({ selector: ".connect-wallet-btn" })
4. tl_wait_for_notification({ timeout: 30000 })
5. tl_switch_to_tab({ role: "notification" })
6. tl_describe_screen()
7. tl_click({ a11yRef: "e3" })        // approve connection
8. tl_switch_to_tab({ role: "dapp" })
9. tl_screenshot()

---

Multi-Signature Guide

Network Reference

Network	TronGrid URL	Multi-Sig Service URL	API Key
Nile Testnet	https://nile.trongrid.io	https://apinile.walletadapter.org	Not needed
Shasta Testnet	https://api.shasta.trongrid.io	—	Not needed
Mainnet	https://api.trongrid.io	https://api.walletadapter.org	Required

Testnet TRX faucet: https://nileex.io/join/getJoinPage

TRON Multi-Sig Permission Model

TRON accounts have three permission levels:

Permission	ID	Description
owner	0	Highest level — can modify all permissions and execute all contracts
witness	1	Super representative only (block production)
active	2+	Custom permissions — configurable allowed contract types (up to 8)

Each permission contains:

• threshold: Minimum cumulative weight required to execute
• keys: Signer list [{address, weight}] (up to 5 per permission)
• operations: 32-byte hex bitmask defining allowed contract types (active only)

Multi-Sig Fees

• accountPermissionUpdate: 100 TRX
• Each multi-sig transaction: additional 1 TRX

Multi-Sig Complete Flow

1. Setup multi-sig permissions (accountPermissionUpdate)
   ├── Define owner permission (recommended: keep threshold=1 for recovery)
   └── Define active permission (e.g., threshold=2, two signers each weight=1)

2. Create multi-sig transaction (with Permission_id=2)
   └── Transaction specifies active permission

3. Collect signatures
   ├── Signer A signs → submit to multi-sig service
   └── Signer B signs → submit to multi-sig service

4. Auto-broadcast when threshold reached
   └── Service checks currentWeight >= threshold → broadcast

Built-in Multi-Sig Flow Recipes

View with tl_list_flows:

Flow ID	Description
multisig_query_auth	Query address multi-sig permissions (owner/active, thresholds, weights)
multisig_list_transactions	List multi-sig transactions (filter by status: pending/success/failed)
multisig_monitor	WebSocket real-time monitoring + list current pending transactions
multisig_stop_monitor	Disconnect WebSocket monitoring
multisig_submit_tx	Submit signed transaction to multi-sig service (auto-broadcast on threshold)
multisig_check	Full status check: permissions → pending txs → unsigned txs

Security Recommendations

1. Keep owner threshold=1: When setting up multi-sig, keep the owner permission as single-sig (threshold=1) so you can always recover if active signers are unavailable
2. Test on testnet first: Thoroughly test on Nile testnet before operating on Mainnet
3. Key safety: Private keys are encrypted via @bankofai/agent-wallet (local_secure type). Plain-text keys in env vars are not supported. If you use tl_wallet_create, the password is saved to ~/.agent-wallet/runtime_secrets.json; if you use the manual path, set AGENT_WALLET_PASSWORD yourself. Do not delete runtime_secrets.json — it is required to decrypt existing auto-created wallets
4. Transaction expiration: Unsigned transactions expire in ~60 seconds — collect all signatures before expiration

---

All Available Tools

The server exposes 55+ tools via MCP protocol. Tools are grouped by mode:

Playwright Mode Tools

Session Management: tl_launch / tl_cleanup

State & Discovery: tl_get_state / tl_describe_screen / tl_list_testids / tl_accessibility_snapshot

Navigation: tl_navigate / tl_switch_to_tab / tl_close_tab / tl_wait_for_notification

UI Interaction: tl_click / tl_type / tl_wait_for / tl_scroll / tl_keyboard / tl_evaluate

Screenshot & Clipboard: tl_screenshot / tl_clipboard

Contract Seeding (e2e): tl_seed_contract / tl_seed_contracts / tl_get_contract_address / tl_list_contracts

Context: tl_set_context / tl_get_context

Knowledge Store: tl_knowledge_last / tl_knowledge_search / tl_knowledge_summarize / tl_knowledge_sessions

Batch: tl_run_steps

Flow Recipes: tl_list_flows (32 built-in recipes with pre-checks)

Wallet Management Tools

Tool	Description
tl_wallet_list	List all wallets with IDs, types, active status, and TRON addresses
tl_wallet_create	Auto-generate an encrypted wallet and attach it to the running MCP session
tl_wallet_set_active	Switch the active wallet by ID (hot-swaps into all capabilities)

Direct API Tools

On-Chain (requires agent-wallet + TL_TRONGRID_URL):

Tool	Description
tl_chain_get_address	Get TRON address from encrypted agent-wallet
tl_chain_get_account	Query account: TRX balance, bandwidth, energy, permissions
tl_chain_get_tokens	Query TRC10 + TRC20 token balances
tl_chain_send	Send TRX, TRC10, or TRC20 tokens
tl_chain_get_tx	Get transaction details by txID
tl_chain_get_history	Query transaction history with pagination
tl_chain_stake	Freeze/unfreeze TRX for bandwidth or energy (Stake 2.0)
tl_chain_get_staking	Query staking status: frozen amounts, votes, pending unfreezing
tl_chain_resource	Delegate/undelegate bandwidth or energy resources
tl_chain_swap	Estimate or execute token swap via SunSwap V2
tl_chain_swap_v3	Execute token swap via SunSwap V3 Smart Router
tl_chain_setup_multisig	Configure multi-sig permissions (accountPermissionUpdate)
tl_chain_create_multisig_tx	Create unsigned multi-sig transaction with permission ID
tl_chain_sign_multisig_tx	Sign multi-sig transaction with owner or co-signer wallet

Multi-Signature (requires multisig service config):

Tool	Description
tl_multisig_query_auth	Query address multi-sig permissions (thresholds, weights)
tl_multisig_submit_tx	Submit signed transaction (auto-broadcast on threshold)
tl_multisig_list_tx	Query transaction history (pending/success/failed, signature progress)
tl_multisig_connect_ws	Connect WebSocket for real-time pending tx notifications
tl_multisig_disconnect_ws	Disconnect WebSocket listener

GasFree (requires TL_GASFREE_BASE_URL + API key):

Tool	Description
tl_gasfree_get_account	Query account eligibility, supported tokens, daily quota
tl_gasfree_get_transactions	Query gas-free transaction history with pagination
tl_gasfree_send	Send TRC20 token with zero gas fee

Pre-Check Mechanism

All transaction tools automatically perform safety checks before execution:

Operation	Pre-Check
Send TRX	Verify sufficient TRX balance
Send TRC20	Verify sufficient token balance
Stake TRX	Verify available TRX balance
Unstake TRX	Verify sufficient staked amount
Delegate resource	Verify sufficient frozen resources
Reclaim delegation	Verify active resource delegation exists
Setup multi-sig	Verify TRX balance >= 100 TRX
Create multi-sig tx	Verify multi-sig permissions configured
Swap (V2/V3)	Verify sufficient source token balance
GasFree send	Verify eligibility, token support, daily quota, token balance

---

Core Components

TronLinkSessionManager (Playwright Mode)

Full implementation of the ISessionManager interface:

Feature	Details
Browser launch	Playwright Chromium with --load-extension for TronLink
Extension ID resolution	Auto-extract 32-char ID from chrome-extension:// URL or Service Worker
Extension readiness	Wait for React mount on #root, confirm non-empty DOM
Screen detection	URL hash-based detection for 15 TronLink screens
State extraction	DOM analysis for TRON address (T-prefix, 34 chars), TRX balance, network
Tab tracking	Auto-classify page roles: extension / notification / dapp / other
Confirmation handling	Poll + waitForEvent('page') for secondary_popup detection
Safe cleanup	Sequentially close Fixture, Chain, MockServer, then browser

TronLinkOnChainCapability (Direct API Mode)

Feature	Details
API calls	Direct REST calls to TronGrid full-node API
Signing	Encrypted wallet signing via @bankofai/agent-wallet
Address derivation	Resolved from encrypted wallet
Supported operations	Transfer, stake, delegate, swap (V2/V3), multisig setup/create/sign
Pre-checks	Balance and permission validation before every transaction

TronLinkGasFreeCapability (Direct API Mode)

Feature	Details
API calls	GasFree REST API for zero-gas TRC20 transfers
Eligibility check	Validates account, token support, and daily quota before sending
Signing	Encrypted wallet signing via @bankofai/agent-wallet for GasFree authorization

TronLinkMultiSigCapability (Direct API Mode)

Feature	Details
Permission query	REST call to /multi/auth for owner/active permission data
Transaction submit	REST call to /multi/transaction with signed transaction payload
Transaction list	REST call to /multi/list with pagination and status filtering
WebSocket	Real-time /multi/socket connection for pending tx notifications
Auth signing	Auto-generated HmacSHA256 API signature (sign_version=v1)

TronLinkBuildCapability

Feature	Details
Build command	Calls TronLink project's npm run build / build:prd:chrome / build:mv2
Build detection	Checks output directory for manifest.json
Timeout	5 minutes

TronLinkStateSnapshotCapability

Feature	Details
Screen detection	URL hash matching + password input fallback
Address extraction	Regex match T[A-Za-z1-9]{33}
Balance extraction	Regex match [\d,.]+\s*TRX
Network detection	DOM scan for Mainnet / Nile / Shasta / Testnet keywords

---

Project Structure

mcp-server-tronlink/
├── src/
│   ├── index.ts                    # Entry: parse config, register capabilities, start server
│   ├── wallet.ts                   # Unified wallet entry (agent-wallet, encrypted-only, guided auto-create)
│   ├── wallet-tools.ts             # MCP wallet management tools (list, create, switch)
│   ├── session-manager.ts          # TronLinkSessionManager (full ISessionManager implementation)
│   ├── capabilities/
│   │   ├── build.ts                # TronLinkBuildCapability (webpack build)
│   │   ├── state-snapshot.ts       # TronLinkStateSnapshotCapability (UI state extraction)
│   │   ├── multisig.ts             # TronLinkMultiSigCapability (multi-sig REST + WebSocket)
│   │   ├── on-chain.ts             # TronLinkOnChainCapability (14 on-chain operations)
│   │   ├── gasfree.ts              # TronLinkGasFreeCapability (gas-free transfers)
│   │   └── tron-crypto.ts          # TRON crypto utils (address derivation, signing, Base58)
│   └── flows/
│       ├── index.ts                # Flow registration entry (32 built-in recipes)
│       ├── import-wallet.ts        # Import wallet flow (disabled — violates encrypted-only policy)
│       ├── switch-network.ts       # Switch network / enable testnet
│       ├── transfer-trx.ts         # TRX / TRC20 transfer flows
│       ├── multisig.ts             # Multi-sig flows (6 recipes)
│       ├── onchain.ts              # On-chain flows (11 recipes with pre-checks)
│       └── gasfree.ts              # GasFree flows (3 recipes)
├── .env.example                    # Environment variable reference (documentation only)
├── package.json
├── tsconfig.json
└── README.md

---

Current Limitations

• Chrome extension only: Currently supports Chrome desktop TronLink extension; mobile support planned
• DOM dependency: State extraction relies on TronLink UI DOM structure; UI refactors may require adaptation
• No data-testid: TronLink extension does not use data-testid attributes; relies on accessibility tree and CSS selectors
• Headed mode recommended: Chrome extensions may have compatibility issues in headless mode

---

Requirements

• Node.js >= 20
• Playwright >= 1.49 (with Chromium) — only needed for Playwright mode
• Built TronLink extension (dist/ with manifest.json) — only needed for Playwright mode

---

License

MIT License Copyright (c) 2026 TronLink