Use Cases

Recipes for the most common AI-agent trading strategies on Solana. Each shows the exact MCP tool call — no scaffolding, no SDK ceremony. Pair with the cookbook for full agent code.

Pattern: every recipe uses one MCP call to npx -y @traderouter/trade-router-mcp. The server signs locally with TRADEROUTER_PRIVATE_KEY, submits via /protect (Jito bundle), and returns either {signature, balance_changes} for instant swaps or {order_id} for WebSocket-managed orders. For safe iteration, set TRADEROUTER_DRY_RUN=true — every write tool short-circuits.

Recipe 01

I want to buy a token automatically when its market cap drops to X

Mcap-trigger limit buy

"Buy 0.5 SOL of BONK if its market cap falls to $1.2B."

{
  "tool": "place_limit_order",
  "args": {
    "wallet_address": "WALLET",
    "token_address": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    "action": "buy",
    "amount": 500000000,
    "trigger_type": "mcap",
    "trigger_value": 1200000000,
    "slippage": 1500,
    "expiry_hours": 168
  }
}

What happens: the WebSocket monitors mcap every ~5s. When it crosses below $1.2B, the order fires through /protect, MEV-protected. Returns an Ed25519-signed order_filled event your agent can trust without re-querying chain state. Cookbook: 04-mcap-trigger.

Recipe 02

I want to DCA into a token over hours / days

TWAP buy: 1 SOL split into 10 slices over 1 hour

"Spread the buy out so I don't move the price."

{
  "tool": "place_twap_order",
  "args": {
    "wallet_address": "WALLET",
    "token_address": "TARGET_MINT",
    "action": "twap_buy",
    "total_amount": 1000000000,
    "frequency": 10,
    "duration": 3600,
    "slippage": 1500
  }
}

How it slices: frequency=10 over duration=3600s means 10 swaps of 0.1 SOL each, one every ~6 minutes. Each slice routes independently through the best DEX at that moment. Cookbook: 02-dca-bot.

DCA daily for 7 days

"Buy 0.5 SOL of MintX every day for a week."

{
  "tool": "place_twap_order",
  "args": {
    "wallet_address": "WALLET",
    "token_address": "TARGET_MINT",
    "action": "twap_buy",
    "total_amount": 3500000000,
    "frequency": 7,
    "duration": 604800,
    "slippage": 1500
  }
}

Same tool, longer window. duration is in seconds (7 × 86400). Slices fire on schedule even if your agent is offline; the server orchestrates.

Recipe 03

I want a trailing stop-loss

Trailing sell: lock in 20% drawdown from peak

"I bought at 1.0. If it pumps to 1.5 and then drops 20% from there to 1.2, sell."

{
  "tool": "place_trailing_order",
  "args": {
    "wallet_address": "WALLET",
    "token_address": "TARGET_MINT",
    "action": "sell",
    "holdings_percentage": 10000,
    "trail_percent": 2000,
    "slippage": 1500,
    "expiry_hours": 168
  }
}

Maths: trail_percent=2000 bps = 20%. holdings_percentage=10000 bps = 100% of your position. The server tracks peak price after the order goes live; sells when price falls 20% from peak. Cookbook: 03-trailing-stop.

Recipe 04

I want to chain multiple conditions

Limit-trigger → trailing-trigger → TWAP execution (the four-stage combo)

"Wait until BONK hits $1B mcap. Then start a trailing stop. When the trail fires, TWAP-sell over 30 minutes."

{
  "tool": "place_limit_trailing_twap_order",
  "args": {
    "wallet_address": "WALLET",
    "token_address": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    "action": "sell",
    "holdings_percentage": 10000,
    "limit_trigger_type": "mcap",
    "limit_trigger_value": 1000000000,
    "trail_percent": 1500,
    "frequency": 6,
    "duration": 1800,
    "slippage": 1500
  }
}

This is the heaviest order shape Trade Router supports. The server orchestrates all four stages on its side; your agent only sees a single order_id and order_filled events as each stage completes. Cookbook: 05-combo-take-profit.

Recipe 05

I want to snipe a new token launch

Instant swap with minimum slippage tolerance

"Buy 1 SOL of this token RIGHT NOW with up to 30% slippage. MEV-protected."

{
  "tool": "auto_swap",
  "args": {
    "wallet_address": "WALLET",
    "token_address": "FRESH_LAUNCH_MINT",
    "action": "buy",
    "amount": 1000000000,
    "slippage": 3000
  }
}

Why auto_swap not separate build_swap + submit_signed_swap: auto_swap collapses the round trip — server builds, MCP signs locally, submits via Jito in one call. Saves ~150-300ms vs the manual flow. On a fresh launch that matters. Cookbook: 01-instant-swap.

Recipe 06

I want to monitor and react to fills

WebSocket fill log

"Tell me every time one of my orders fills, with proof I can trust."

// 1. Open the WebSocket once at agent startup
{ "tool": "connect_websocket", "args": { "wallet_address": "WALLET" } }

// 2. Poll the fill log
{ "tool": "get_fill_log", "args": { "limit": 50 } }

// Returns: [{ order_id, token, action, amount, price, signature,
//             server_signature, timestamp }, ...]
// Each fill is Ed25519-signed by the server's trust anchor
// (EXX3nRzfDUvbjZSmxFzHDdiSYeGVP1EGr77iziFZ4Jd4 by default).
// Verify before acting on it — see SECURITY.md.

Why this matters: agents that act on unverified server callbacks are vulnerable to spoofed events. Trade Router signs every order_filled, order_created, and twap_execution message; the MCP server verifies before passing to your agent. See SECURITY.md for the trust model.