traderouter.ai

Trade Router MCP

A Model Context Protocol server for TradeRouter.ai — Solana swap & limit order engine. Use it from Claude Desktop, Cursor, or any MCP host.

Requirements

• Node.js ≥ 20.18.0
• A Solana wallet private key (base58)

Installation

# npm (Node.js)
npx -y @traderouter/trade-router-mcp

# PyPI (Python equivalent, runs the same 21 tools)
uv add traderouter-mcp
traderouter-mcp

Claude Desktop setup

Add the following to your claude_desktop_config.json. Set TRADEROUTER_DRY_RUN=true on first run — every write tool returns { dry_run: true, ... } instead of touching mainnet, so you can verify everything end-to-end before allocating funds.

{
  "mcpServers": {
    "traderouter": {
      "command": "npx",
      "args": ["-y", "@traderouter/trade-router-mcp"],
      "env": {
        "TRADEROUTER_PRIVATE_KEY": "your_base58_private_key",
        "TRADEROUTER_DRY_RUN": "true"
      }
    }
  }
}

Same shape works in Cursor (~/.cursor/mcp_servers.json) and Cline.

Use with ElizaOS / LangChain / Solana Agent Kit

Both ElizaOS and LangChain ship official generic MCP-client adapters — no Trade Router-specific code needed. See github.com/TradeRouter/cookbook:

• 06-elizaos-agent — uses @fleek-platform/eliza-plugin-mcp. Drop a mcp.servers.traderouter block in your character JSON; ElizaOS auto-discovers all 21 Trade Router tools.
• 07-langchain-agent — uses langchain-mcp-adapters (Python) or @langchain/mcp-adapters (TypeScript). 6 lines of code, full MultiServerMCPClient example.
• Solana Agent Kit users: hit the REST API directly per openapi.json, or wrap the MCP server with any generic Node MCP client.

Environment variables

Available tools

Connection & registration

Connection sequence

1. Connect to wss://api.traderouter.ai/ws
2. Server sends: {"type": "challenge", "nonce": "…", "message": "…"}
3. Sign the nonce (UTF-8 bytes) with your wallet's Ed25519 private key. Encode the signature as base58.
4. Send: {"action": "register", "wallet_address": "<PUBKEY>", "signature": "<base58>"}
5. Server sends: {"type": "registered", "wallet_address": "…", "authenticated": true}
6. Only after authenticated: true may you send order actions.

WebSocket lifecycle state machine

Reconnection

On disconnect: reconnect, receive a new challenge with a new nonce, sign and re-register. Then check for any pending order_filled messages (server queues fills that arrived while you were offline). Use the staleness check on all fills after reconnect.

Server signature verification

The server signs every order_filled (and optionally order_created) with Ed25519. Clients must verify server_signature before signing and submitting the swap tx.

Trust anchor — hardcoded, never fetched

Current server signing public key (base58 Ed25519, hardcode this):

EXX3nRzfDUvbjZSmxFzHDdiSYeGVP1EGr77iziFZ4Jd4

Override via env var TRADEROUTER_SERVER_PUBKEY when using the reference MCP. For key rotation, a second key is published via TRADEROUTER_SERVER_PUBKEY_NEXT — try the current key first; if it fails, try the next; if the next key succeeds, the server has rotated, update your primary key. Rotation announcements at api.traderouter.ai/security.

Verifying order_filled.server_signature

1. If already_dispatched is true: skip sign/submit entirely (idempotent ack, fill was already sent).
2. Build canonical JSON from the message using only these keys (include only if present and not null): order_id, order_type, status, token_address, entry_mcap, triggered_mcap, filled_mcap, target_mcap, triggered_at, filled_at, data. Serialize with sorted keys, no extra whitespace: e.g. json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=True).
3. SHA-256 the UTF-8 bytes of the canonical JSON string.
4. Verify server_signature (base58 Ed25519) over that digest using the hardcoded trust anchor.
5. On failure or missing signature (when required): reject the fill. Do not sign or submit.
6. On success: sign data.swap_tx (base58 → sign → base64) and POST /protect.

Verifying order_created.server_signature (params commitment)

When order_created includes both params_hash and server_signature, the server is committing to the order parameters. Verification is optional but recommended.

Canonical params string (pipe-delimited):

For buy: holdings_percentage=0. For sell: amount=0. Compute params_hash = SHA256(canonical_string.encode("utf-8")).hexdigest(). Server signs SHA256(params_hash.encode("utf-8")) with Ed25519.

REQUIRE_SERVER_SIGNATURE

The server may require a valid server_signature on every order_filled (MCP flag: TRADEROUTER_REQUIRE_SERVER_SIGNATURE, default true). If a fill arrives without a signature when one is required, reject the fill and do not sign/submit.

Responsible disclosure

Report security issues to security@traderouter.ai.

Handling order_filled

1. Idempotency: if already_dispatched is true, skip sign/submit and log. data or data.swap_tx may be absent. This is an idempotent ack — the fill was already submitted.
2. Verify: verify server_signature against the hardcoded trust anchor (see Security section above). If verification fails or signature is missing when required, log and do not sign/submit.
3. Read order_id — use for all logging and correlation.
4. Read data.swap_tx (base58 unsigned transaction).
5. Decode base58 → raw bytes → deserialize as VersionedTransaction.
6. Sign with client wallet, serialize, encode as base64.
7. POST /protect with { "signed_tx_base64": "…" }.
8. Log order_id + returned signature together for audit trail.
9. Use sol_balance_post and token_balances to update holdings state.

Staleness check

Apply to every fill, not only after reconnect. If both triggered_mcap and filled_mcap are present and filled_mcap > 0:

if triggered_mcap / filled_mcap < 0.85:
    # fill is stale — consider skipping (do not sign/submit)

Divide-by-zero guard: if filled_mcap is 0 or null, skip the ratio check entirely — the fill is not stale by this criterion. filled_mcap can be 0 or null on valid fills; do not reject fills based on this field alone.

WebSocket message flow

Client                                    Server
│─── connect wss://api.traderouter.ai/ws ──►│
│◄── {"type":"challenge","nonce":"…"}        │  server sends challenge on connect
│─── {"action":"register",                  │
│     "wallet_address":"WALLET",             │
│     "signature":"<base58>"}         ──────►│  sign nonce with wallet private key
│◄── {"type":"registered","authenticated":true} │
│◄── {"type":"order_filled",…}               │  pending queued fills, if any
│─── {"action":"sell",…} ──────────────────►│
│◄── {"type":"order_created",…} ─────────── │
│                                            │  server polls mcap every ~5s
│◄── {"type":"order_filled","data":{"swap_tx":"…"}} │  target crossed
│    verify server_signature                 │
│    sign swap_tx → POST /protect            │
│─── {"action":"list_orders"} ─────────────►│
│◄── {"type":"order_list",…}                │
│─── {"action":"cancel_order",…} ──────────►│
│◄── {"type":"order_cancelled",…}           │
│◄── {"type":"heartbeat"}                   │  ignore, keepalive

Server → client message shapes

{"type":"challenge","nonce":"…","message":"…"}
{"type":"registered","wallet_address":"…","authenticated":true}

{
  "type":             "order_created",
  "order_id":          "uuid",
  "order_type":        "sell | buy | trailing_sell | trailing_buy | limit_twap_sell | limit_twap_buy | trailing_twap_sell | trailing_twap_buy | limit_trailing_sell | limit_trailing_buy | limit_trailing_twap_sell | limit_trailing_twap_buy",
  "token_address":     "string",
  "entry_mcap":         number,
  "target_mcap":        number,
  "target_bps":         number | null  — limit orders,
  "trail_bps":          number | null  — trailing orders,
  "slippage":           integer,
  "expiry_hours":       integer,
  "amount":             integer,
  "holdings_percentage": integer,
  "params_hash":        "sha256 hex — canonical params commitment",
  "server_signature":   "base58 — Ed25519 over params_hash (when present, verify)"
}

{
  "type":              "order_filled",
  "order_id":           "uuid",
  "order_type":         "sell | buy | trailing_sell | trailing_buy",
  "status":             "success | trigger_failed | error",
  "token_address":      "string",
  "entry_mcap":          number,
  "triggered_mcap":      number,
  "filled_mcap":         number | null  — can be 0/null on valid fills,
  "target_mcap":         number,
  "triggered_at":        number  — unix timestamp,
  "filled_at":           number  — unix timestamp,
  "server_signature":    "base58 — Ed25519 over canonical payload digest",
  "already_dispatched":  boolean — true = idempotent ack, skip sign/submit,
  "dispatched_at":       number | null,
  "target_bps":          number | null  — limit orders,
  "trail_bps":           number | null  — trailing orders,
  "data": {
    "swap_tx": "base58 unsigned transaction"
    …
  }  — absent when already_dispatched is true
}

{"type":"order_status",    "order_id":"…", "status":"…"}
{"type":"order_list",      "orders":[…]}
{"type":"order_cancelled", "order_id":"…"}
{"type":"order_extended",  "order_id":"…"}

{
  "type":             "twap_order_created",
  "order_id":          "uuid",
  "order_type":        "twap_buy | twap_sell",
  "token_address":     "string",
  "pair_address":      "string",
  "frequency":         integer,
  "duration":          integer,
  "interval_seconds":  number,
  "amount_per_execution": integer,
  "original_amount": integer,
  "slippage":          integer,
  "expires_at":        number,
  "holdings_percentage": integer | null
}

{
  "type":                 "twap_execution",
  "order_id":             "uuid",
  "order_type":           "twap_buy | twap_sell",
  "status":               "success | error",
  "token_address":        "string",
  "execution_num":        integer,
  "executions_total":     integer,
  "executions_remaining": integer,
  "next_execution_at":    number | null,
  "server_signature":     "base58",
  "data":                 { "swap_tx": "base58", … } | absent,
  "error":                string | absent
}

{"type":"twap_order_completed", "order_id":"…", "order_type":"…", "token_address":"…", "executions_completed": N, "status":"completed"}
{"type":"twap_order_cancelled", "order_id":"…", "status":"cancelled"}

{"type":"error",     "message":"…"}
{"type":"heartbeat"}   — ignore, keepalive

JavaScript — WebSocket (challenge → register → order)

Uses tweetnacl for Ed25519 signing and bs58 for base58 encoding. Sign the challenge nonce, include the signature in register, and only send order actions after authenticated: true.

import WebSocket from 'ws';
import bs58 from 'bs58';
import nacl from 'tweetnacl';

const wallet = /* Keypair from @solana/web3.js */;
const ws = new WebSocket("wss://api.traderouter.ai/ws");

ws.on('message', (raw) => {
  const msg = JSON.parse(raw);

  if (msg.type === 'challenge') {
    // Sign the nonce (UTF-8 bytes) with the wallet's Ed25519 private key
    const sigBytes = nacl.sign.detached(
      Buffer.from(msg.nonce, 'utf-8'),
      wallet.secretKey   // 64-byte secretKey from Keypair
    );
    ws.send(JSON.stringify({
      action: 'register',
      wallet_address: wallet.publicKey.toBase58(),
      signature: bs58.encode(sigBytes),
    }));
  }

  if (msg.type === 'registered') {
    if (!msg.authenticated) {
      console.error('authentication failed — check private key');
      return;
    }
    // Now safe to place orders
    ws.send(JSON.stringify({
      action: 'sell',
      token_address: 'TOKEN_MINT',
      holdings_percentage: 10000,
      slippage: 1500,
      target: 20000,       // take-profit at 2× current mcap
      expiry_hours: 144,
    }));
  }

  if (msg.type === 'order_created') {
    console.log('order placed:', msg.order_id);
  }

  if (msg.type === 'order_filled') {
    // 1. Skip if already dispatched
    if (msg.already_dispatched) return;
    // 2. Verify server_signature against hardcoded trust anchor
    // 3. Sign msg.data.swap_tx (base58 → deserialize → sign → base64)
    // 4. POST /protect with signed_tx_base64
  }
});

Python — WebSocket

import asyncio, json, base58, hashlib, websockets
from solders.keypair import Keypair

keypair = Keypair.from_base58_string("YOUR_PRIVATE_KEY_B58")

async def main():
    async with websockets.connect("wss://api.traderouter.ai/ws") as ws:
        async for raw in ws:
            msg = json.loads(raw)

            if msg.get("type") == "challenge":
                nonce = msg["nonce"]
                sig = keypair.sign_message(nonce.encode("utf-8"))
                await ws.send(json.dumps({
                    "action": "register",
                    "wallet_address": str(keypair.pubkey()),
                    "signature": base58.b58encode(bytes(sig)).decode(),
                }))

            elif msg.get("type") == "registered":
                if not msg.get("authenticated"):
                    print("authentication failed — check private key")
                    return
                await ws.send(json.dumps({
                    "action": "buy",
                    "token_address": "TOKEN_MINT",
                    "amount": 100000000,   # 0.1 SOL
                    "slippage": 1500,
                    "target": 5000,        # dip-buy at 50% of current mcap
                    "expiry_hours": 72,
                }))

            elif msg.get("type") == "order_filled":
                if msg.get("already_dispatched"):
                    continue
                # Verify server_signature, then sign and POST /protect
                print("fill received:", msg.get("order_id"))

asyncio.run(main())

JavaScript — Verifying order_filled server_signature

Call this before signing or submitting any fill. Uses tweetnacl for Ed25519 verification and Node's built-in crypto for SHA-256. Mirrors the reference implementation in trader_mcp.py.

import nacl from 'tweetnacl';
import bs58 from 'bs58';
import { createHash } from 'crypto';

// Hardcoded trust anchor — never fetch from the server at runtime
const SERVER_PUBKEY = bs58.decode('EXX3nRzfDUvbjZSmxFzHDdiSYeGVP1EGr77iziFZ4Jd4');
const SERVER_PUBKEY_NEXT = process.env.TRADEROUTER_SERVER_PUBKEY_NEXT
  ? bs58.decode(process.env.TRADEROUTER_SERVER_PUBKEY_NEXT)
  : null;

function verifyOrderFilled(msg) {
  const { server_signature, already_dispatched } = msg;

  // Step 1: idempotency — skip entirely if already dispatched
  if (already_dispatched) return { ok: true, skip: true };

  // Step 2: require signature
  if (!server_signature) {
    return { ok: false, reason: 'missing server_signature' };
  }

  // Step 3: build canonical payload — only keys present and not null
  const CANONICAL_KEYS = [
    'order_id', 'order_type', 'status', 'token_address',
    'entry_mcap', 'triggered_mcap', 'filled_mcap', 'target_mcap',
    'triggered_at', 'filled_at', 'data',
  ];
  const payload = {};
  for (const key of CANONICAL_KEYS) {
    if (msg[key] !== undefined && msg[key] !== null) payload[key] = msg[key];
  }

  // Step 4: canonical JSON — sorted keys, no whitespace
  const canonical = JSON.stringify(payload, Object.keys(payload).sort());

  // Step 5: SHA-256 digest of UTF-8 bytes
  const digest = createHash('sha256').update(Buffer.from(canonical, 'utf-8')).digest();

  // Step 6: verify Ed25519 — try current key, then rotation key
  const sigBytes = bs58.decode(server_signature);
  const keysToTry = [SERVER_PUBKEY, SERVER_PUBKEY_NEXT].filter(Boolean);

  for (const pubkey of keysToTry) {
    if (nacl.sign.detached.verify(digest, sigBytes, pubkey)) return { ok: true };
  }

  return { ok: false, reason: 'signature verification failed' };
}

// Usage in order_filled handler:
ws.on('message', async (raw) => {
  const msg = JSON.parse(raw);
  if (msg.type !== 'order_filled') return;

  const result = verifyOrderFilled(msg);

  if (result.skip) {
    console.log('already_dispatched — skipping', msg.order_id);
    return;
  }
  if (!result.ok) {
    console.error('fill rejected:', result.reason, msg.order_id);
    return;  // do NOT sign or submit
  }

  // Staleness check
  const { triggered_mcap, filled_mcap } = msg;
  if (filled_mcap != null && filled_mcap > 0 && triggered_mcap / filled_mcap < 0.85) {
    console.warn('stale fill — skipping', msg.order_id);
    return;
  }

  // Safe to sign and submit
  const signedBase64 = signVersionedTx(msg.data.swap_tx);  // base58 → sign → base64
  const protect = await fetch('https://api.traderouter.ai/protect', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ signed_tx_base64: signedBase64 }),
    signal: AbortSignal.timeout(30000),
  }).then(r => r.json());

  console.log('submitted', msg.order_id, '→', protect.signature);
});

Python — Verifying order_filled server_signature

Uses cryptography and base58. Identical logic to the MCP server's _verify_order_filled_signature.

import json, hashlib, base58
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
from cryptography.exceptions import InvalidSignature

# Hardcoded trust anchor — never fetch from the server at runtime
SERVER_PUBKEY_B58 = "EXX3nRzfDUvbjZSmxFzHDdiSYeGVP1EGr77iziFZ4Jd4"

CANONICAL_KEYS = [
    "order_id", "order_type", "status", "token_address",
    "entry_mcap", "triggered_mcap", "filled_mcap", "target_mcap",
    "triggered_at", "filled_at", "data",
]

def verify_order_filled(msg: dict, server_pubkey_b58: str = SERVER_PUBKEY_B58) -> bool:
    """Returns True if signature is valid. Raises nothing — returns False on any failure."""
    sig_b58 = msg.get("server_signature")
    if not sig_b58:
        return False  # missing — reject when REQUIRE_SERVER_SIGNATURE=true

    # Build canonical payload — only keys present and not null
    payload = {k: msg[k] for k in CANONICAL_KEYS if k in msg and msg.get(k) is not None}

    # Canonical JSON: sorted keys, no extra whitespace, ASCII-safe
    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
    digest = hashlib.sha256(canonical.encode("utf-8")).digest()

    try:
        Ed25519PublicKey.from_public_bytes(
            base58.b58decode(server_pubkey_b58)
        ).verify(base58.b58decode(sig_b58), digest)
        return True
    except (InvalidSignature, ValueError):
        return False

# Usage in fill handler:
async def handle_order_filled(msg: dict):
    if msg.get("already_dispatched"):
        print("already_dispatched — skipping", msg.get("order_id"))
        return

    if not verify_order_filled(msg):
        print("fill rejected: signature invalid", msg.get("order_id"))
        return  # do NOT sign or submit

    # Staleness check
    triggered = msg.get("triggered_mcap")
    filled = msg.get("filled_mcap")
    if filled and filled > 0 and triggered / filled < 0.85:
        print("stale fill — skipping", msg.get("order_id"))
        return

    # Safe to sign and submit
    signed_b64 = sign_tx_b58(msg["data"]["swap_tx"])  # base58 → sign → base64
    protect = await post("/protect", {"signed_tx_base64": signed_b64})
    print("submitted", msg.get("order_id"), "→", protect.get("signature"))

curl — instant swap

# 1. Build unsigned tx
curl -X POST https://api.traderouter.ai/swap \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"WALLET","token_address":"MINT","action":"sell","holdings_percentage":10000,"slippage":1500}'

# 2. Decode the returned swap_tx (base58) → sign with wallet → encode as base64

# 3. Submit signed tx via MEV-protected lane (30s timeout)
curl -X POST https://api.traderouter.ai/protect \
  -H "Content-Type: application/json" \
  -d '{"signed_tx_base64":"YOUR_SIGNED_BASE64_TX"}'

# 4. Scan holdings (set 100s timeout — this endpoint is slow)
curl -X POST https://api.traderouter.ai/holdings --max-time 100 \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"WALLET"}'

Troubleshooting

Field reference