back
loading skill details...
Solana swap execution, MEV-protected transaction submission, wallet scanning, and market-cap-based limit/trailing orders via the TradeRouter API. Use when th...
---
name: traderouter
description: >
Solana swap execution, MEV-protected transaction submission, wallet scanning, and market-cap-based
limit/trailing orders via the TradeRouter API. Use when the user wants to: swap SPL tokens on Solana
(buy or sell), check wallet token holdings, submit signed transactions through an MEV-protected
priority lane, place limit orders (buy/sell at a target market cap), set trailing stop orders
(trailing_sell/trailing_buy), place combo orders (limit+TWAP, trailing+TWAP, limit+trailing,
limit+trailing+TWAP), manage existing orders (check, list, cancel, extend), or implement
DCA strategies. No API key required — wallet address is the only identity. Supports REST endpoints
POST /swap, POST /holdings, POST /protect, and WebSocket wss://api.traderouter.ai/ws for limit orders.
---
# TradeRouter
Solana swap builder and limit-order engine.
**Base URL:** `https://api.traderouter.ai`
**WebSocket:** `wss://api.traderouter.ai/ws`
**Website:** https://traderouter.ai
**Auth:** None. No API key. Wallet address is the only identity.
**Content-Type:** All REST requests require `Content-Type: application/json`.
---
## Before you use this skill
**Maintaining the WebSocket connection:** Limit orders, trailing orders, and order management (cancel, extend, list) require an **open WebSocket connection** to `wss://api.traderouter.ai/ws`. The server delivers `order_filled` only over that connection — if the client disconnects, it will not receive fills until it reconnects and re-registers. Keep the WS connection alive for the lifetime of any active limit/trailing orders so you can receive and execute fills. On disconnect, reconnect and re-register (see Reconnection); active orders persist server-side.
**Authentication for order management:** WebSocket order placement and cancellation are gated by a **challenge–response flow**: the server sends a challenge with a nonce; the client must **sign the nonce** with the wallet’s private key (Ed25519) and send `register` with `wallet_address` and the base58 signature. Only after the server responds with `registered` and `authenticated: true` can the client place or cancel orders. Authorization is **proof-of-control** of the wallet via the signed challenge — no separate API key.
**Service origin:** This skill documents the API only. The service website is **https://traderouter.ai** (API at api.traderouter.ai).
**MEV protection:** The `POST /protect` endpoint accepts signed transactions and uses **Jito** and a **staked connection lane** to process your transaction.
**Risk:** No API key is requested; identity is the wallet address (and for WebSocket orders, proof via the signed challenge).
---
## When to use which endpoint
| User intent | Endpoint | Method |
|-------------|----------|--------|
| Instant buy or sell of a token | `POST /swap` → sign → `POST /protect` | REST |
| Check wallet token balances | `POST /holdings` | REST |
| Submit an already-signed transaction with MEV protection | `POST /protect` | REST |
| Market cap / price for token(s) | `GET /mcap?tokens=MINT1,MINT2` | REST |
| Flex trade card image for wallet + token | `GET /flex?wallet_address=…&token_address=…` | REST |
| Limit order (take-profit, stop-loss, dip buy, breakout) | WebSocket `sell` or `buy` action | WS |
| Trailing stop (auto-adjust with market) | WebSocket `trailing_sell` or `trailing_buy` | WS |
| TWAP (time-weighted buy/sell over duration) | WebSocket `twap_buy` or `twap_sell` | WS |
| Limit then TWAP | WebSocket `limit_twap_sell` or `limit_twap_buy` | WS |
| Trailing then TWAP | WebSocket `trailing_twap_sell` or `trailing_twap_buy` | WS |
| Limit then trailing (single swap on trail trigger) | WebSocket `limit_trailing_sell` or `limit_trailing_buy` | WS |
| Limit then trailing then TWAP | WebSocket `limit_trailing_twap_sell` or `limit_trailing_twap_buy` | WS |
| Manage orders (check, list, cancel, extend) | WebSocket actions | WS |
| DCA (recurring small buys) | WebSocket `buy` orders — see DCA section below | WS |
---
## POST /swap — Build unsigned swap transaction
Returns an **unsigned** transaction (base58). Client must sign it, then submit via `POST /protect`.
**Sell uses `holdings_percentage` (bps). Buy uses `amount` (lamports). Never mix them.**
### Request
```json
{
"wallet_address": "SOLANA_PUBKEY",
"token_address": "SPL_TOKEN_MINT",
"action": "buy",
"amount": 100000000,
"slippage": 1500
}
```
| Field | Type | Required | Notes |
|-------|------|----------|-------|
| wallet_address | string | yes | Solana pubkey |
| token_address | string | yes | SPL token mint address |
| action | string | yes | `"buy"` or `"sell"` |
| amount | integer | buy only | Lamports. **Only for buy.** |
| holdings_percentage | integer | sell only | Bps (10000 = 100%). **Only for sell.** |
| slippage | integer | no | Bps, default 500 (5%). **For low-liquidity or newly launched tokens, use 1500-2500 bps.** 500 bps will often fail on memecoins. |
If both `amount` and `holdings_percentage` are sent, treat the request as invalid. The reference client blocks this locally via schema validation before network calls, and the API should return 422 for malformed payloads.
### Success response
```json
{
"status": "success",
"data": {
"swap_tx": "<base58_unsigned_transaction>",
"token_address": "SPL_TOKEN_MINT",
"pool_type": "raydium",
"pool_address": "POOL_PUBKEY",
"amount_in": 100000000,
"min_amount_out": 950000,
"price_impact": 0.5,
"slippage": 1500,
"decimals": 6
}
}
```
`pool_type` tells you which DEX the swap routes through (e.g. `raydium`, `pumpswap`, `orca`, `meteora`). Treat this field as an open enum and handle unknown values gracefully.
### Error response
```json
{
"status": "error",
"error": "Insufficient balance",
"code": 400
}
```
`code` is optional. Common: 422 (validation), 400 (bad request).
**"Error running simulation"** is usually an unsellable route at that moment (dead/rugged pool, zero effective balance, or no valid route). Do not loop retries — place the token on cooldown and retry later only if strategy requires.
---
## POST /protect — Submit signed transaction (MEV protected)
Submit a **signed** transaction (**base64**). Blocks until confirmed on-chain. Returns signature and balance changes. Under the hood, the service uses **Jito** and a **staked connection lane** for MEV protection and submission.
**⚠️ Set a 30-second timeout on /protect calls.** This endpoint blocks until on-chain confirmation and can hang during network congestion.
**⚠️ Encoding mismatch:** `/swap` returns `swap_tx` as **base58**. `/protect` expects **base64**. You must convert — see the workflow section.
### Request
```json
{
"signed_tx_base64": "<base64_signed_transaction>"
}
```
### Success response
```json
{
"status": "success",
"signature": "5kyc5dMF1tybDcj8sVMZz3fCLbHYDczZ7A4mMu5JMPz1...",
"sol_balance_pre": 10399668919,
"sol_balance_post": 10399538835,
"token_balances": [
{
"mint": "FFKwi6dzaDmkGhtMDGKbt3HAyEYWk2BgwN4AwcWbbonk",
"balance": 25952334242,
"decimals": 6,
"balance_change": 2032594114,
"ui_amount_string": "25952.334242"
}
]
}
```
Use `sol_balance_post` and `token_balances` to update holdings after the swap.
### Error handling
- `{"status":"error","error":"message"}` — general error.
- **503** — protect endpoint not configured on server. `submitTx()` handles this automatically — falls back to direct RPC. You lose MEV protection but the transaction still goes through.
- **Timeout** — the tx may have landed on-chain. Check tx status via RPC before retrying.
---
## POST /holdings — Scan wallet token balances
Returns token holdings with liquid DEX pool info. **Set HTTP timeout to at least 100 seconds** — this endpoint scans all token accounts and can be slow.
### Request
```json
{
"wallet_address": "SOLANA_PUBKEY"
}
```
### Response
Empty wallet: `{}`
Wallet with holdings:
```json
{
"data": [
{
"address": "SPL_TOKEN_MINT",
"valueNative": 1500000000,
"amount": 25952334242,
"decimals": 6
}
]
}
```
`/holdings` is intended to return sellable tokens, but keep a defensive `valueNative > MIN_VALUE_NATIVE` filter (default `0`, i.e. `valueNative > 0`) in case stale or edge-case entries appear. The reference client's `getHoldings()` applies this filter automatically.
---
## GET /mcap — Market cap data
Return market cap (and optional price/pool) for given token addresses.
**Request:** `GET https://api.traderouter.ai/mcap?tokens=MINT1,MINT2` (comma-delimited Solana mint addresses).
**Response:** Object keyed by token address. Each value can include `marketCap`, `pair_address`, `pool_type`, `priceUsd`. Empty object if no tokens provided or none found.
---
## GET /flex — Flex trade card PNG
Generate a flex trade card image for a wallet and token mint.
**Request:** `GET https://api.traderouter.ai/flex?wallet_address=WALLET&token_address=MINT`.
**Response:** `image/png`. 400 on invalid params; 501 if flex_card_image deps not available; 500 on server error.
---
## Instant swap workflow (step by step)
**The encoding changes: /swap returns base58, /protect expects base64.** Do not send base58 to /protect.
1. `POST /swap` with wallet_address, token_address, action, amount or holdings_percentage, slippage
2. Read `data.swap_tx` from response — this is **base58** encoded
3. **Decode** from base58 into raw bytes
4. **Deserialize** as VersionedTransaction
5. **Sign** with wallet private key
6. **Re-serialize** the signed transaction into bytes
7. **Encode** as **base64**
8. Submit via `submitTx(signedBase64)` — this calls `/protect` first (30s timeout), auto-falls back to RPC on 503
9. On success: `signature` = tx hash, use `sol_balance_post` and `token_balances` to update state
10. On timeout: `submitTx` checks if tx landed via RPC before falling back — no manual handling needed
---
## WebSocket — Limit and trailing orders
**URL:** `wss://api.traderouter.ai/ws`
**You must keep the WebSocket connection open** for limit and trailing orders to work: the server sends `order_filled` only over this connection. If the connection drops, you will not receive fills until you reconnect and re-register. Maintain the connection for as long as you have active orders that you want to receive and execute.
Server monitors market cap every ~5 seconds. When target is crossed, server pushes `order_filled` with an unsigned swap transaction to sign and submit.
**Reference implementation:** Follow the flow below (challenge → register with signature, verification of `order_filled` and `order_created`). Use the canonical payloads, params_hash encoding, and Ed25519 verification rules in this skill as the source of truth.
### Connection sequence (MUST follow this exact order)
The server sends a **challenge** on connect (not `subscribed`). Registration is **challenge–response only**; there is no unauthenticated path for placing orders.
1. Connect to `wss://api.traderouter.ai/ws`
2. **Server sends:** `{"type": "challenge", "nonce": "<nonce>", "message": "..."}`. The current protocol always sends `challenge` as the first message.
3. **Client:** Sign the **nonce** (UTF-8 bytes) with the **wallet's private key** (Ed25519). You **must** have the wallet private key to use the WebSocket for orders; without it you cannot register successfully.
4. **Client sends:** `{"action": "register", "wallet_address": "<SOLANA_PUBKEY>", "signature": "<base58>"}`. The signature is the base58-encoded result of signing the nonce. If you omit signature after a challenge, the server responds with `{"type": "error", "message": "Missing signature. Sign the challenge nonce and send register with wallet_address and signature."}` and you will not be authenticated.
5. **Server sends:** `{"type": "registered", "wallet_address": "<pubkey>", "authenticated": true}`.
6. **Only after** receiving `registered` with `authenticated: true` may you send order actions. Sending order actions before that returns `{"type": "error", "message": "Not authenticated. Register with a valid signature to place or manage orders."}`.
**Do NOT send any order actions before receiving `{"type": "registered", "authenticated": true}`.** Plain `{"action": "register", "wallet_address": "..."}` without a signature will **fail** when the server has sent a challenge.
### Reconnection
On WebSocket disconnect:
1. Reconnect to `wss://api.traderouter.ai/ws`
2. Server sends a new **challenge** (new nonce). Send `{"action": "register", "wallet_address": "...", "signature": "<base58 of nonce signed with wallet>"}`.
3. Wait for `{"type": "registered", "authenticated": true}`
4. Check for any pending `order_filled` messages
5. Use the staleness check (`triggered_mcap / filled_mcap < 0.85`) to skip stale fills
Active orders persist server-side — you do **not** need to re-place them after reconnect.
### Limit sell (take-profit or stop-loss)
```json
{
"action": "sell",
"token_address": "SPL_TOKEN_MINT",
"holdings_percentage": 10000,
"target": 20000,
"slippage": 1500,
"expiry_hours": 144
}
```
`target` (often named `targetMcapBps` in client code) is bps vs **current mcap at order placement time** (not your wallet entry price). Any value > 0. **Sell target > 10000** = take-profit (e.g. 20000 = mcap doubles). **Sell target < 10000** = stop-loss (e.g. 5000 = mcap halves).
### Limit buy (dip buy or breakout entry)
```json
{
"action": "buy",
"token_address": "SPL_TOKEN_MINT",
"amount": 100000000,
"target": 5000,
"slippage": 1500,
"expiry_hours": 144
}
```
`target` (often named `targetMcapBps` in client code) is bps vs **current mcap at order placement time** (not your wallet entry price). Any value > 0. **Buy target < 10000** = dip buy (e.g. 5000 = mcap halves). **Buy target > 10000** = breakout entry (e.g. 20000 = mcap doubles).
### Trailing sell / Trailing buy
```json
{
"action": "trailing_sell",
"token_address": "SPL_TOKEN_MINT",
"holdings_percentage": 10000,
"trail": 1000,
"slippage": 1500,
"expiry_hours": 144
}
```
`trail` is bps — percentage callback from peak before triggering.
**Example:** `trail: 1000` (10%). Token mcap peaks at $100k. Sell triggers when mcap drops to $90k (10% below peak). If mcap later peaks at $150k, the trigger moves up to $135k.
Replace `trailing_sell` with `trailing_buy` and `holdings_percentage` with `amount` for trailing buy. For trailing buy, the trigger works in reverse: if mcap bottoms at $50k, a 10% trail triggers when mcap rises to $55k.
### Limit + TWAP (limit_twap_sell / limit_twap_buy)
Wait for limit target (bps vs entry mcap), then execute via TWAP. Required: `token_address`, `target`, `frequency`, `duration`; for sell add `amount` or `holdings_percentage`; for buy add `amount`. When limit crosses, server spawns TWAP; client receives `limit_twap_triggered` then `twap_execution` per slice.
```json
{"action": "limit_twap_sell", "token_address": "MINT", "target": 20000, "frequency": 5, "duration": 3600, "holdings_percentage": 5000, "slippage": 500, "expiry_hours": 144}
{"action": "limit_twap_buy", "token_address": "MINT", "target": 5000, "amount": 100000000, "frequency": 5, "duration": 3600, "slippage": 500, "expiry_hours": 144}
```
### Trailing + TWAP (trailing_twap_sell / trailing_twap_buy)
When trailing stop triggers, server spawns TWAP. Required: `token_address`, `trail`, `frequency`, `duration`; for sell add `amount` or `holdings_percentage`; for buy add `amount`. Client receives `trailing_twap_triggered` then `twap_execution` per slice.
```json
{"action": "trailing_twap_sell", "token_address": "MINT", "trail": 1000, "frequency": 5, "duration": 3600, "holdings_percentage": 10000, "slippage": 500, "expiry_hours": 144}
{"action": "trailing_twap_buy", "token_address": "MINT", "trail": 1000, "amount": 100000000, "frequency": 5, "duration": 3600, "slippage": 500, "expiry_hours": 144}
```
### Limit + Trailing (limit_trailing_sell / limit_trailing_buy)
Wait for limit target, then trailing phase activates (server sends `limit_trailing_activated`). When the trailing stop triggers, single swap — client receives `order_filled` with `data.swap_tx`. Required: `token_address`, `target`, `trail`; for sell add `amount` or `holdings_percentage`; for buy add `amount`.
```json
{"action": "limit_trailing_sell", "token_address": "MINT", "target": 20000, "trail": 1000, "holdings_percentage": 10000, "slippage": 500, "expiry_hours": 144}
{"action": "limit_trailing_buy", "token_address": "MINT", "target": 5000, "trail": 1000, "amount": 100000000, "slippage": 500, "expiry_hours": 144}
```
### Limit + Trailing + TWAP (limit_trailing_twap_sell / limit_trailing_twap_buy)
Limit → trailing phase → when trail triggers, server spawns TWAP. Client receives `limit_trailing_activated` when trailing starts, then `limit_trailing_twap_triggered` when trail triggers, then `twap_execution` per slice. Required: `token_address`, `target`, `trail`, `frequency`, `duration`; for sell add `amount` or `holdings_percentage`; for buy add `amount`.
```json
{"action": "limit_trailing_twap_sell", "token_address": "MINT", "target": 20000, "trail": 1000, "frequency": 5, "duration": 3600, "holdings_percentage": 5000, "slippage": 500, "expiry_hours": 144}
{"action": "limit_trailing_twap_buy", "token_address": "MINT", "target": 5000, "trail": 1000, "amount": 100000000, "frequency": 5, "duration": 3600, "slippage": 500, "expiry_hours": 144}
```
### Order management actions
```json
{"action": "check_order", "order_id": "ORDER_ID"}
{"action": "list_orders"}
{"action": "cancel_order", "order_id": "ORDER_ID"}
{"action": "extend_order", "order_id": "ORDER_ID", "expiry_hours": 336}
```
### TWAP (time-weighted average price)
`twap_buy` and `twap_sell` split a total amount into `frequency` equal slices executed every `duration / frequency` seconds. `duration` is in seconds (min 60, max 30 days). There is no separate expiry — the order lives exactly `duration` seconds.
**twap_sell:** Either `amount` (raw token units) or `holdings_percentage` (bps, e.g. 5000 = 50%). If using `holdings_percentage`, the server resolves it once at order creation to a fixed token amount, then divides by `frequency` per slice.
```json
{
"action": "twap_sell",
"token_address": "SPL_TOKEN_MINT",
"frequency": 5,
"duration": 3600,
"holdings_percentage": 5000,
"slippage": 500
}
```
**twap_buy:** Use `amount` (SOL lamports) as total to spend over the duration.
```json
{
"action": "twap_buy",
"token_address": "SPL_TOKEN_MINT",
"frequency": 5,
"duration": 3600,
"amount": 1000000000,
"slippage": 500
}
```
**Server messages:** `twap_order_created` when accepted; `twap_execution` for each slice (includes `execution_num`, `executions_total`, `executions_remaining`, `next_execution_at`; when `status` is `success`, `data.swap_tx` and `server_signature` — verify signature then sign and submit like `order_filled`); `twap_order_completed` when all slices are done. On `cancel_order` for a TWAP order, server responds with `twap_order_cancelled`. Verify `twap_execution.server_signature` (same trust anchor as `order_filled`; MCP may use a dedicated signer for the twap slice payload) before signing/submitting each slice.
### Order expiry
Orders silently expire when `expiry_hours` is reached — **the server does not send an expiry event.** To detect expired orders, periodically call `check_order` or `list_orders`. Expired orders will no longer appear in results.
### All WebSocket actions reference
| Action | Required fields | Optional |
|--------|----------------|----------|
| register | wallet_address | signature (required when server sent challenge; base58 of nonce signed with wallet) |
| sell | token_address, holdings_percentage (bps), target, slippage | expiry_hours (default 144), wallet_address |
| buy | token_address, amount (lamports), target, slippage | expiry_hours, wallet_address |
| trailing_sell | token_address, holdings_percentage, trail (bps), slippage | expiry_hours |
| trailing_buy | token_address, amount, trail (bps), slippage | expiry_hours |
| twap_sell | token_address, frequency, duration, amount or holdings_percentage (bps) | slippage (default 500) |
| twap_buy | token_address, frequency, duration, amount (SOL lamports) | slippage (default 500) |
| limit_twap_sell | token_address, target, frequency, duration, amount or holdings_percentage | slippage, expiry_hours |
| limit_twap_buy | token_address, target, amount, frequency, duration | slippage, expiry_hours |
| trailing_twap_sell | token_address, trail, frequency, duration, amount or holdings_percentage | slippage, expiry_hours |
| trailing_twap_buy | token_address, trail, amount, frequency, duration | slippage, expiry_hours |
| limit_trailing_sell | token_address, target, trail, amount or holdings_percentage | slippage, expiry_hours |
| limit_trailing_buy | token_address, target, trail, amount | slippage, expiry_hours |
| limit_trailing_twap_sell | token_address, target, trail, frequency, duration, amount or holdings_percentage | slippage, expiry_hours |
| limit_trailing_twap_buy | token_address, target, trail, amount, frequency, duration | slippage, expiry_hours |
| check_order | order_id | — |
| list_orders | — | wallet_address |
| cancel_order | order_id | — |
| extend_order | order_id, expiry_hours (max 336) | — |
**expiry_hours:** default 144, max 336.
### Server → client message types
| type | Payload fields | Description |
|------|----------------|-------------|
| challenge | nonce, message | Sent on connect; client must sign nonce and send register with wallet_address + signature |
| registered | wallet_address, authenticated | Registration confirmed; only when authenticated true can client send order actions |
| order_created | order_id, order_type, token_address, entry_mcap, target_mcap, target_bps (limit), trail_bps (trailing), slippage, expiry_hours, amount, holdings_percentage, params_hash, server_signature | Order accepted; order_type can be any of sell, buy, trailing_sell, trailing_buy, twap_*, limit_twap_*, trailing_twap_*, limit_trailing_*, limit_trailing_twap_*. When params_hash and server_signature are present, verify server_signature over params_hash (Rec 2) — see Verifying server signatures |
| order_filled | order_id, order_type, status, token_address, entry_mcap, triggered_mcap, filled_mcap, target_mcap, triggered_at, filled_at, server_signature, already_dispatched, data (optional; when already_dispatched false: data.swap_tx base58) | Target hit — verify server_signature, then sign data.swap_tx and submit; when already_dispatched true, data/swap_tx may be omitted (idempotent ack) |
| limit_trailing_activated | order_id, order_type, token_address, limit_target_mcap, current_mcap, trailing_target_mcap | Limit-trailing order: limit target crossed, trailing phase now active |
| trailing_twap_triggered | order_id, twap_order_id, token_address, … | Trailing+TWAP: trail triggered; then twap_order_created / twap_execution for the spawned TWAP |
| limit_twap_triggered | order_id, twap_order_id, token_address, … | Limit+TWAP: limit crossed; then twap_order_created / twap_execution for the spawned TWAP |
| limit_trailing_twap_triggered | order_id, twap_order_id, token_address, … | Limit+trailing+TWAP: trail triggered; then twap_order_created / twap_execution for the spawned TWAP |
| twap_order_created | order_id, order_type, token_address, frequency, duration, interval_seconds, amount_per_execution, original_amount, expires_at, slippage, holdings_percentage (optional) | TWAP order accepted (standalone or spawned from combo) |
| twap_execution | order_id, order_type, status, token_address, execution_num, executions_total, executions_remaining, next_execution_at, server_signature, data (optional), error (optional) | One TWAP slice — verify server_signature, then sign data.swap_tx and submit when status success |
| twap_order_completed | order_id, order_type, token_address, executions_completed, status | All TWAP slices done |
| twap_order_cancelled | order_id, status | TWAP order cancelled (response to cancel_order) |
| order_status | order_id, status | Response to check_order |
| order_list | orders[] | Response to list_orders |
| order_cancelled | order_id | Order cancelled |
| order_extended | order_id | TTL extended |
| error | message | Error description |
| heartbeat | — | Keepalive, ignore |
### WebSocket authentication (required for orders)
The server sends a **challenge** with a **nonce** on connect. To place or manage orders you must:
1. Sign the **nonce** (as UTF-8 bytes) with the wallet's private key (Ed25519).
2. Send **one** message: `{"action": "register", "wallet_address": "<pubkey>", "signature": "<base58 signature>"}`. There is no separate `auth` action — the signature is sent in the same `register` message.
3. Wait for `{"type": "registered", "authenticated": true}`. Only then send order actions.
If you send `register` without `signature` after a challenge, the server responds with an error and does not set `authenticated: true`. Unauthenticated sessions cannot place or manage orders.
### Verifying server signatures (order_filled and order_created)
**Trust anchor — do not fetch from the server.** The server public key must be a **hardcoded or preconfigured** trust anchor. **Never** fetch it from the same server at runtime (e.g. GET /security) to verify that server's messages; that is a TOCTOU vulnerability. Use a hardcoded default and allow override via `TRADEROUTER_SERVER_PUBKEY` (base58). Use this key to verify all server signatures (Ed25519, base58 decode key and signature).
**Key rotation:** Support a second key via `TRADEROUTER_SERVER_PUBKEY_NEXT`. On verification failure with the current key, try the next key; if the next key succeeds, the server has rotated — update your primary key and treat the order as valid. Document rotation at https://api.traderouter.ai/security.
**Rejection when signature is required:** The server may require a valid `server_signature` on every `order_filled` (`TRADEROUTER_REQUIRE_SERVER_SIGNATURE`, default true). For `order_created`, clients can require a params commitment (`TRADEROUTER_REQUIRE_ORDER_CREATED_SIGNATURE`, default true); if required and the server omits `params_hash`/`server_signature`, reject the order. If signature is present but verification fails, reject the fill or order.
**order_filled.server_signature:** The server signs a **canonical JSON** payload. Build the payload from the message using only these keys (include a key 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 (recursive for nested objects)** and no extra whitespace, and **ensure_ascii** (escape non-ASCII as `\uXXXX`); e.g. Python: `json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=True)`; then SHA-256 of the UTF-8 bytes. The server's Ed25519 signature (base58) is over this digest. Verify with the server public key (base58 decode key and signature, verify digest with Ed25519). **Always verify before signing or submitting the fill.** If verification fails or `server_signature` is missing when the server is expected to send it, do not sign/submit. If `already_dispatched` is true, skip sign/submit (idempotent ack).
**order_created.server_signature (Rec 2):** When the server includes `params_hash` and `server_signature` in `order_created`, it is committing to the order parameters. The **params_hash** is the SHA-256 hex of a pipe-delimited canonical string: for limit orders `order_id|token_address|order_type|target_bps|slippage|expiry_hours|amount|holdings_percentage`; for trailing orders the same but `trail_bps` instead of `target_bps`. The server signs the digest SHA-256(params_hash_hex.encode("utf-8")). Verify with the server public key (base58 decode key and signature, verify digest with Ed25519). If present and verification fails, treat the order as untrusted.
### Handling order_filled
When `order_filled` arrives:
1. **Idempotency:** If `already_dispatched` is true, skip sign/submit; treat as idempotent ack (fill was already sent). Log and exit.
2. **Verify:** Verify `server_signature` using the configured trust anchor (see "Verifying server signatures" above). On failure or if signature is missing when required, log and do not sign/submit.
3. Read `order_id` from the message — use for logging and correlation throughout
4. Read `data.swap_tx` — this is **base58** unsigned (when `already_dispatched` is false; when true, `data` or `data.swap_tx` may be omitted)
5. **Decode** from base58 into raw bytes
6. **Deserialize** as VersionedTransaction
7. **Sign** with client wallet
8. **Re-serialize** signed transaction into bytes
9. **Encode** as **base64**
10. Submit via `submitTx(signedBase64)` — handles /protect + fallback internally
11. Log `order_id` + `signature` together for audit trail
12. Use response to update holdings
**Idempotency:** Duplicate or late `order_filled` messages may have `already_dispatched: true` and no `data.swap_tx`; skip sign/submit and update local state only.
**Logging:** For each `order_filled`, log at least: received (order_id, order_type, token); if skipped (already_dispatched or verify failed) log reason; on submit log order_id + signature for audit.
**⚠️ `filled_mcap` can be 0 or null.** If `triggered_mcap` exists but `filled_mcap` is 0/null, the fill is still valid — the transaction will work, but mcap data at fill time is unreliable. Don't reject fills based on `filled_mcap` alone.
**Staleness check:** Apply to **every** `order_filled`, not only after reconnect. If `triggered_mcap` and `filled_mcap` are both present and **filled_mcap > 0**, and `triggered_mcap / filled_mcap < 0.85`, treat the fill as stale and consider skipping (do not sign/submit). **Divide-by-zero:** If `filled_mcap` is 0 or null, do not apply the ratio; the fill is not stale by this check. Proceed with verification and sign/submit as normal.
### `holdings_percentage` resolves at execution time
For limit sell and trailing sell orders, `holdings_percentage` is calculated **when the order triggers**, not when placed. If you sell 50% of a token via instant swap, a pending order with `holdings_percentage: 10000` (100%) will sell 100% of the *remaining* balance, not the original amount. This is a feature — it accounts for partial sells between placement and execution.
---
## DCA (Dollar-Cost Averaging)
DCA is implemented as repeated limit buy orders. It is **not automatic chaining** — each fill requires agent action:
1. Place a `buy` order via WebSocket with the desired `amount` and `target`
2. When `order_filled` arrives, sign the `swap_tx` and submit via `submitTx()` (follow the base58→base64 steps above)
3. After successful submission, place the **next** `buy` order
4. Repeat for as many intervals as desired
The server does not auto-chain orders. Each fill triggers `order_filled`, the agent must sign + submit, then explicitly place the next order.
---
## Troubleshooting
| Issue | Fix |
|-------|-----|
| /holdings times out | Set HTTP timeout to at least 100 seconds. |
| /protect hangs | Set a 30s timeout. On timeout, check tx status via RPC before retrying — tx may have landed. |
| /protect returns 503 | `submitTx()` auto-falls back to RPC. No manual action needed. |
| 422 from /swap | Invalid payload (missing fields or mixed buy/sell params). Sell needs: wallet_address, token_address, action, holdings_percentage. Buy needs: wallet_address, token_address, action, amount. |
| "Error running simulation" from /swap | Route is unsellable now (dead/rugged pool, zero effective balance, or route failure). Put token on cooldown; avoid tight retry loops. |
| Swap fails on-chain | Increase slippage (1500-2500 bps for memecoins), check SOL balance for fees, verify token/pool exists. |
| No order_filled received | Verify register was sent, `{"type":"registered"}` received, and `authenticated: true` is set. A session that registered without a valid signature will receive `registered` with `authenticated: false` and will not receive fills — check this field first. Wallet must match. |
| WebSocket disconnects | Reconnect, re-register with signature, check for pending fills. Active orders persist server-side. |
| Sell fails on token from /holdings | Keep defensive filter `valueNative > MIN_VALUE_NATIVE` (`> 0` by default) and verify balance/pool just before sell. |
| filled_mcap is 0 or null | Fill is still valid. Execute normally — mcap data is unreliable but tx works. |
| Order seems to have disappeared | Orders silently expire at `expiry_hours`. Use `list_orders` to check. |
---
## Request pacing / rate limits
No hard limits are documented in this skill. Use conservative client pacing defaults unless the API owner gives stricter numbers:
- REST (`/swap`, `/protect`, `/holdings`): target <= 2 requests/sec sustained per wallet (short bursts <= 5).
- WebSocket mutating actions (`buy`, `sell`, `trailing_*`, `cancel_order`, `extend_order`): target <= 5 messages/sec per wallet.
- On 429 or repeated 5xx: exponential backoff with jitter (1s, 2s, 4s, cap 30s).
- Never tight-loop retries on the same token after `"Error running simulation"`; honor cooldown first.
---
## Important rules
- **No API key needed.** Wallet address is the only identity.
- **Never expose private keys.** Sign only in a secure client environment.
- **Keep WebSocket connection open for limit/trailing orders.** Fills are delivered only over the open WS; disconnect means you miss fills until you reconnect and re-register.
- **Register with signature on WebSocket.** Server sends challenge; sign nonce and send register with wallet_address + signature. No orders before `{"type":"registered","authenticated":true}`.
- **Sell = holdings_percentage. Buy = amount.** Do not mix these parameters.
- **Target basis:** WS `target` is relative to **current mcap at order placement**, not to your wallet entry price.
- **Encoding: /swap returns base58, /protect expects base64.** Decode → deserialize → sign → serialize → encode base64.
- **Slippage:** Default 500 (5%). **Use 1500-2500 bps for low-liquidity or newly launched tokens.** 500 bps will fail on most memecoins.
- **Set timeouts:** 30s on /protect, 100s on /holdings.
- **All transactions from the API are unsigned.** Client always signs.
- **Always submit via `submitTx()`.** This function enforces /protect first for MEV protection. RPC fallback is internal and only fires on 503 or timeout. **Never call `connection.sendRawTransaction()` directly.**
- **Unsellable routes:** "Error running simulation" should trigger cooldown, not spam retries.
- **Holdings filtering:** Keep `valueNative > MIN_VALUE_NATIVE` (`> 0` by default) as a defensive guard before sells. The reference client's `getHoldings()` does this automatically.
- **Order expiry is silent.** Server does not notify. Poll `list_orders` to detect.
---
## Definition of Done
An agent is production-ready only when it can execute all of the following with **zero manual steps**:
- [ ] **Instant buy:** `POST /swap` (buy) → decode base58 → sign → encode base64 → `submitTx()` → verify signature
- [ ] **Instant sell:** `POST /holdings` → defensive filter `valueNative > MIN_VALUE_NATIVE` (`> 0` by default) → `POST /swap` (sell) → sign → `submitTx()`
- [ ] **WebSocket limit order:** connect → challenge → register with signature → registered → place sell order → receive `order_filled` → verify → sign → `submitTx()`
- [ ] **WebSocket trailing order:** connect → challenge → register with signature → registered → place `trailing_sell` → receive `order_filled` → verify → sign → `submitTx()`
- [ ] **TWAP order:** connect → register → place `twap_sell` or `twap_buy` (frequency, duration, amount or holdings_percentage) → receive `twap_execution` for each slice → verify server_signature → sign → `submitTx()` for each; receive `twap_order_completed` when done
- [ ] **DCA cycle:** place buy order → handle fill → `submitTx()` → place next buy order
- [ ] **Reconnection:** disconnect → reconnect → new challenge → re-register with signature → handle pending fills with staleness check (all fills)
- [ ] **Error handling:** gracefully handle unsellable routes, 503, timeouts, stale fills, expired orders
- [ ] **Preflight checks pass:** env loaded, wallet accessible, RPC reachable, WS registration succeeds
---
## Canonical Stack
**Reference implementation:** The skill text above is the source of truth for WebSocket challenge–response, verification, and params_hash. Python clients can use: `solders` (Keypair, VersionedTransaction), `websockets`, `httpx`, `cryptography` (Ed25519), `base58`.
**Node.js (skill examples):** Pin these versions unless explicitly tested.
```
Runtime: Node.js 20 LTS
crypto: built-in (createHash for SHA-256; no npm install)
web3.js: @solana/web3.js@1.95.8
bs58: bs58@6.0.0
ws: ws@8.18.0
ajv: ajv@8.17.1
tweetnacl: tweetnacl@1.0.3
```
```bash
npm init -y
npm pkg set type=module
npm install @solana/web3.js@1.95.8 bs58@6.0.0 ws@8.18.0 ajv@8.17.1 tweetnacl@1.0.3
```
**The `type=module` line is required.** All code below uses ESM imports and top-level await, which fail under CommonJS.
**Python:** `solders`, `websockets`, `httpx`, `cryptography`, `base58`. Encoding and verification logic are identical across runtimes; only library names differ.
---
## Reference Client
Minimal copy-paste implementation. **Everything is in this one code block** — safety guards, logging, kill switch, dry-run gating. There are no separate code blocks to wire in. The reference client uses `ajv` to validate requests before sending them. The inline schemas enforce the minimum required fields for each call; the Request/Response Schemas section below has the full payload definitions.
**One submission function:** All transactions go through `submitTx()`. This function tries `/protect` first (MEV-protected), and only falls back to direct RPC on 503 or timeout. There is no separate RPC submission function — the fallback is internal. **Never call `connection.sendRawTransaction()` directly.**
```javascript
import { Connection, Keypair, VersionedTransaction } from '@solana/web3.js';
import bs58 from 'bs58';
import WebSocket from 'ws';
import Ajv from 'ajv';
import nacl from 'tweetnacl';
import { createHash } from 'crypto';
const API = 'https://api.traderouter.ai';
const WS_URL = 'wss://api.traderouter.ai/ws';
const RPC_URL = process.env.RPC_URL || 'https://api.mainnet-beta.solana.com';
const connection = new Connection(RPC_URL, 'confirmed');
// SAFE-BY-DEFAULT: DRY_RUN is true unless you explicitly set DRY_RUN=false to go live.
const DRY_RUN = process.env.DRY_RUN !== 'false';
// Trust anchor: hardcoded or loaded from env. NEVER fetch from the server at runtime.
const SERVER_PUBKEY_BYTES = bs58.decode(
process.env.TRADEROUTER_SERVER_PUBKEY || 'EXX3nRzfDUvbjZSmxFzHDdiSYeGVP1EGr77iziFZ4Jd4'
);
const SERVER_PUBKEY_NEXT_BYTES = process.env.TRADEROUTER_SERVER_PUBKEY_NEXT
? bs58.decode(process.env.TRADEROUTER_SERVER_PUBKEY_NEXT)
: null;
const REQUIRE_SERVER_SIGNATURE = process.env.TRADEROUTER_REQUIRE_SERVER_SIGNATURE !== 'false';
// ---------- Schema Validation (AJV, enforced at runtime) ----------
const ajv = new Ajv({ allErrors: true, strict: false });
const swapRequestSchema = {
type: 'object',
required: ['wallet_address', 'token_address', 'action'],
properties: {
wallet_address: { type: 'string', minLength: 32, maxLength: 44 },
token_address: { type: 'string', minLength: 32, maxLength: 44 },
action: { type: 'string', enum: ['buy', 'sell'] },
amount: { type: 'integer', minimum: 1 },
holdings_percentage: { type: 'integer', minimum: 1, maximum: 10000 },
slippage: { type: 'integer', minimum: 100, maximum: 2500 },
},
if: { properties: { action: { const: 'buy' } } },
then: { required: ['amount'], not: { required: ['holdings_percentage'] } },
else: { required: ['holdings_percentage'], not: { required: ['amount'] } },
};
const protectRequestSchema = {
type: 'object',
required: ['signed_tx_base64'],
properties: {
signed_tx_base64: { type: 'string', minLength: 100, pattern: '^[A-Za-z0-9+/]+=*$' },
},
};
// When already_dispatched is true, server omits data or data.swap_tx; schema must allow that.
const orderFilledSchema = {
type: 'object',
required: ['type', 'order_id', 'order_type', 'status'],
properties: {
type: { const: 'order_filled' },
order_id: { type: 'string' },
order_type: { type: 'string', enum: ['sell', 'buy', 'trailing_sell', 'trailing_buy'] },
status: { type: 'string', enum: ['success'] },
already_dispatched: { type: 'boolean' },
data: {
type: 'object',
properties: {
swap_tx: { type: 'string', minLength: 100 },
token_address: { type: 'string' },
pool_type: { type: 'string' },
},
},
},
};
const validateSwapRequest = ajv.compile(swapRequestSchema);
const validateProtectRequest = ajv.compile(protectRequestSchema);
const validateOrderFilled = ajv.compile(orderFilledSchema);
function assertSchema(validateFn, payload, label) {
if (validateFn(payload)) return;
const detail = ajv.errorsText(validateFn.errors || [], { separator: '; ' });
throw new Error(`${label} validation failed: ${detail}`);
}
// ---------- Logging (JSON lines, one line per event) ----------
function log(fields) {
console.log(JSON.stringify({ ts: new Date().toISOString(), wallet: _wallet?.publicKey?.toBase58() || 'unknown', ...fields }));
}
// ---------- Safety Guards (enforced in buildSwap + submitTx) ----------
const SAFETY = {
MAX_BUY_LAMPORTS: 500_000_000, // 0.5 SOL max per buy (conservative starter)
MAX_SLIPPAGE_BPS: 2500, // 25% absolute ceiling
MIN_SLIPPAGE_BPS: 100, // 1% floor
MIN_VALUE_NATIVE: 0, // defensive min valueNative to attempt sell (> 0)
MAX_RETRIES_PER_TOKEN: 2, // don't hammer unsellable routes
UNSWAPPABLE_COOLDOWN_MS: 15 * 60 * 1000, // 15m cooldown for transient unsellable routes
MAX_DAILY_LOSS_LAMPORTS: 2_000_000_000, // 2 SOL daily loss limit
DENYLIST: new Map(), // token mint -> retry_after_epoch_ms (session-scoped)
dailyLoss: 0, // tracked across swaps
};
let KILL_SWITCH = false; // set true to halt all execution immediately
function isTokenOnCooldown(tokenAddress) {
const retryAfter = SAFETY.DENYLIST.get(tokenAddress);
if (!retryAfter) return false;
if (Date.now() >= retryAfter) {
SAFETY.DENYLIST.delete(tokenAddress);
return false;
}
return true;
}
function enforceSafety(action, tokenAddress, amount, slippage) {
if (KILL_SWITCH) throw new Error('KILL_SWITCH is active — all execution halted');
if (isTokenOnCooldown(tokenAddress)) {
const retryAfter = SAFETY.DENYLIST.get(tokenAddress);
log({ step: 'safety_blocked', token: tokenAddress, reason: 'cooldown_active', retry_after_ms: retryAfter });
throw new Error(`${tokenAddress} is on cooldown until ${new Date(retryAfter).toISOString()}`);
}
if (slippage > SAFETY.MAX_SLIPPAGE_BPS) throw new Error(`slippage ${slippage} exceeds max ${SAFETY.MAX_SLIPPAGE_BPS}`);
if (slippage < SAFETY.MIN_SLIPPAGE_BPS) throw new Error(`slippage ${slippage} below min ${SAFETY.MIN_SLIPPAGE_BPS}`);
if (action === 'buy' && amount > SAFETY.MAX_BUY_LAMPORTS) throw new Error(`amount ${amount} exceeds max ${SAFETY.MAX_BUY_LAMPORTS}`);
if (SAFETY.dailyLoss > SAFETY.MAX_DAILY_LOSS_LAMPORTS) {
KILL_SWITCH = true;
throw new Error('daily loss limit reached — KILL_SWITCH activated');
}
}
function markUnswappable(tokenAddress, errorMessage) {
const retryAfter = Date.now() + SAFETY.UNSWAPPABLE_COOLDOWN_MS;
SAFETY.DENYLIST.set(tokenAddress, retryAfter);
log({ step: 'safety_blocked', token: tokenAddress, reason: 'cooldown_set', retry_after_ms: retryAfter, source_error: errorMessage });
}
// ---------- Wallet (lazy init) ----------
let _wallet = null;
function getWallet() {
if (!_wallet) {
if (!process.env.PRIVATE_KEY) throw new Error('PRIVATE_KEY env var not set');
try {
_wallet = Keypair.fromSecretKey(bs58.decode(process.env.PRIVATE_KEY));
} catch (e) {
throw new Error(`Invalid PRIVATE_KEY: ${e.message}`);
}
}
return _wallet;
}
// ---------- Server Signature Verification ----------
// Canonical JSON for server signature: recursive sort_keys + ensure_ascii.
function canonicalizeForSigning(value) {
if (Array.isArray(value)) return value.map(canonicalizeForSigning);
if (value && typeof value === 'object') {
const out = {};
for (const key of Object.keys(value).sort()) out[key] = canonicalizeForSigning(value[key]);
return out;
}
return value;
}
function canonicalJsonPythonStyle(obj) {
const canonicalObj = canonicalizeForSigning(obj);
const json = JSON.stringify(canonicalObj);
return json.replace(/[^\x00-\x7F]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`);
}
// verifyOrderFilledSignature — see "Verifying server signatures" above.
// Must be called in handleOrderFilled before signVersionedTx/submitTx.
function verifyOrderFilledSignature(msg) {
const { server_signature } = msg;
if (!server_signature) {
if (REQUIRE_SERVER_SIGNATURE) {
log({ step: 'order_fill_verify_failed', order_id: msg.order_id, reason: 'missing_server_signature' });
return false;
}
// Signature not present and not required — pass through.
return true;
}
// Build canonical payload — only include 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];
}
}
// Canonical JSON: sorted keys (recursive), no extra whitespace, ensure_ascii — then SHA-256 of UTF-8 bytes.
const canonical = canonicalJsonPythonStyle(payload);
const digest = createHash('sha256').update(Buffer.from(canonical, 'utf-8')).digest();
const sigBytes = bs58.decode(server_signature);
// Try primary key, then rotation key if present.
const keysToTry = [SERVER_PUBKEY_BYTES];
if (SERVER_PUBKEY_NEXT_BYTES) keysToTry.push(SERVER_PUBKEY_NEXT_BYTES);
for (const pubkeyBytes of keysToTry) {
try {
const ok = nacl.sign.detached.verify(digest, sigBytes, pubkeyBytes);
if (ok) return true;
} catch (_) {
// Try next key.
}
}
log({ step: 'order_fill_verify_failed', order_id: msg.order_id, reason: 'signature_invalid' });
return false;
}
// ---------- REST ----------
async function buildSwap({ tokenAddress, action, amount, holdingsPercentage, slippage = 1500 }) {
// Safety check BEFORE network call
enforceSafety(action, tokenAddress, amount, slippage);
const body = {
wallet_address: getWallet().publicKey.toBase58(),
token_address: tokenAddress,
action,
slippage,
};
if (action === 'buy') body.amount = amount;
if (action === 'sell') body.holdings_percentage = holdingsPercentage;
assertSchema(validateSwapRequest, body, 'swap request');
log({ step: 'swap_request', token: tokenAddress, action, amount: amount || holdingsPercentage, slippage });
const res = await fetch(`${API}/swap`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(body),
signal: AbortSignal.timeout(15000),
});
const json = await res.json();
if (json.status !== 'success') {
// Session cooldown for unsellable routes (avoid retry loops, allow later retry).
if (json.error?.includes('Error running simulation')) {
markUnswappable(tokenAddress, json.error);
}
log({ step: 'swap_error', token: tokenAddress, error: json.error });
throw new Error(json.error || 'swap failed');
}
log({ step: 'swap_response', token: tokenAddress, pool_type: json.data.pool_type, amount_in: json.data.amount_in });
return json.data;
}
function signVersionedTx(swapTxBase58) {
const txBytes = bs58.decode(swapTxBase58);
const tx = VersionedTransaction.deserialize(txBytes);
tx.sign([getWallet()]);
const signedBytes = tx.serialize();
return Buffer.from(signedBytes).toString('base64');
}
// ⚠️ THIS IS THE ONLY FUNCTION THAT SUBMITS TRANSACTIONS.
// /protect is ALWAYS tried first. RPC fallback is internal and fires on 503,
// or after timeout only if RPC status check shows the tx did not land.
// Do NOT call connection.sendRawTransaction() directly anywhere else.
// dailyLoss is updated on every successful spend path (protect, timeout_recovery, rpc_fallback).
async function submitTx(signedTxBase64, { token, action } = {}) {
if (KILL_SWITCH) throw new Error('KILL_SWITCH is active — all execution halted');
if (DRY_RUN) {
log({ step: 'dry_run_skip', token, action, message: 'would submit but DRY_RUN=true' });
return { signature: null, dry_run: true };
}
let balanceBefore = null;
const isBuy = action === 'buy' || action === 'trailing_buy';
if (isBuy) {
balanceBefore = await connection.getBalance(getWallet().publicKey);
}
try {
const protectBody = { signed_tx_base64: signedTxBase64 };
assertSchema(validateProtectRequest, protectBody, 'protect request');
const res = await fetch(`${API}/protect`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(protectBody),
signal: AbortSignal.timeout(30000),
});
if (res.status === 503) {
log({ step: 'protect_503', message: 'falling back to RPC' });
return await _rpcFallback(signedTxBase64, { action, balanceBefore });
}
if (!res.ok) {
const text = await res.text().catch(() => '');
throw new Error(text || `protect failed with HTTP ${res.status}`);
}
const json = await res.json();
if (json.status !== 'success') throw new Error(json.error || 'protect failed');
// Track loss for daily limit (buy and trailing_buy both spend SOL)
if (isBuy && json.sol_balance_pre != null && json.sol_balance_post != null) {
SAFETY.dailyLoss += (json.sol_balance_pre - json.sol_balance_post);
}
log({ step: 'protect_success', token, signature: json.signature });
return json;
} catch (err) {
if (err.name === 'TimeoutError') {
log({ step: 'protect_timeout', token, message: 'checking if tx landed' });
const check = await checkTxLanded(signedTxBase64);
if (check.status === 'failed') {
log({ step: 'protect_timeout_failed', signature: check.sig, message: 'tx failed on-chain' });
throw new Error(`transaction ${check.sig} failed on-chain`);
}
if (check.status === 'confirmed' || check.status === 'finalized') {
if (isBuy && balanceBefore != null) {
const balanceAfter = await connection.getBalance(getWallet().publicKey);
SAFETY.dailyLoss += (balanceBefore - balanceAfter);
}
log({ step: 'protect_timeout_landed', signature: check.sig, status: check.status });
return { signature: check.sig, status: check.status, via: 'timeout_recovery' };
}
if (check.status === 'processed') {
log({ step: 'protect_timeout_processed', signature: check.sig, message: 'waiting for confirmation' });
await new Promise(r => setTimeout(r, 2000));
const recheck = await checkTxLanded(signedTxBase64);
if (recheck.status === 'failed') throw new Error(`transaction ${recheck.sig} failed on-chain`);
if (recheck.landed) {
if (isBuy && balanceBefore != null) {
const balanceAfter = await connection.getBalance(getWallet().publicKey);
SAFETY.dailyLoss += (balanceBefore - balanceAfter);
}
log({ step: 'protect_timeout_landed', signature: recheck.sig, status: recheck.status });
return { signature: recheck.sig, status: recheck.status, via: 'timeout_recovery' };
}
}
if (check.landed) {
if (isBuy && balanceBefore != null) {
const balanceAfter = await connection.getBalance(getWallet().publicKey);
SAFETY.dailyLoss += (balanceBefore - balanceAfter);
}
log({ step: 'protect_timeout_landed', signature: check.sig, status: check.status || 'unknown' });
return { signature: check.sig, status: check.status || 'unknown', via: 'timeout_recovery' };
}
log({ step: 'protect_timeout_not_landed', message: 'falling back to RPC' });
return await _rpcFallback(signedTxBase64, { action, balanceBefore });
}
throw err;
}
}
// INTERNAL ONLY — never call directly. Updates dailyLoss when action is buy/trailing_buy.
async function _rpcFallback(signedTxBase64, { action, balanceBefore } = {}) {
const txBytes = Buffer.from(signedTxBase64, 'base64');
const sig = await connection.sendRawTransaction(txBytes, { skipPreflight: false });
await connection.confirmTransaction(sig, 'confirmed');
const isBuy = action === 'buy' || action === 'trailing_buy';
if (isBuy && balanceBefore != null) {
const balanceAfter = await connection.getBalance(getWallet().publicKey);
SAFETY.dailyLoss += (balanceBefore - balanceAfter);
}
log({ step: 'rpc_fallback_success', signature: sig });
return { signature: sig, via: 'rpc_fallback' };
}
async function checkTxLanded(signedBase64) {
const txBytes = Buffer.from(signedBase64, 'base64');
const tx = VersionedTransaction.deserialize(txBytes);
const sig = bs58.encode(tx.signatures[0]);
const status = await connection.getSignatureStatuses([sig]);
const result = status.value[0];
if (!result) return { landed: false, sig, status: 'not_found' };
if (result.err) return { landed: true, sig, status: 'failed', err: result.err };
return { landed: true, sig, status: result.confirmationStatus || 'unknown' };
}
async function getHoldings() {
const res = await fetch(`${API}/holdings`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ wallet_address: getWallet().publicKey.toBase58() }),
signal: AbortSignal.timeout(100000),
});
const json = await res.json();
return (json.data || []).filter(t => t.valueNative > SAFETY.MIN_VALUE_NATIVE);
}
// ---------- WebSocket ----------
function connectWsAndRegister(onOrderFilled) {
const client = { ws: null, registered: false, pendingQueue: [] };
function connect() {
const ws = new WebSocket(WS_URL);
client.ws = ws;
client.registered = false;
ws.on('open', () => log({ step: 'ws_connected' }));
ws.on('message', async (raw) => {
const msg = JSON.parse(raw);
// Listen for 'challenge', sign nonce, send register with signature.
if (msg.type === 'challenge') {
const nonce = msg.nonce;
const sigBytes = nacl.sign.detached(Buffer.from(nonce, 'utf-8'), getWallet().secretKey);
const signature = bs58.encode(sigBytes);
ws.send(JSON.stringify({
action: 'register',
wallet_address: getWallet().publicKey.toBase58(),
signature,
}));
}
if (msg.type === 'registered') {
if (!msg.authenticated) {
log({ step: 'ws_error', error: 'registered but authenticated: false — check signature' });
return;
}
client.registered = true;
log({ step: 'ws_registered' });
while (client.pendingQueue.length > 0) {
ws.send(JSON.stringify(client.pendingQueue.shift()));
}
}
if (msg.type === 'order_filled') {
await onOrderFilled(msg);
}
if (msg.type === 'order_created') {
log({ step: 'order_placed', order_id: msg.order_id, token: msg.token_address, action: msg.order_type, target_mcap: msg.target_mcap });
}
if (msg.type === 'heartbeat') return;
if (msg.type === 'error') log({ step: 'ws_error', error: msg.message });
});
ws.on('close', () => {
log({ step: 'ws_disconnected', message: 'reconnecting in 3s' });
client.registered = false;
setTimeout(connect, 3000);
});
ws.on('error', (err) => log({ step: 'ws_error', error: err.message }));
}
connect();
return {
send: (payload) => {
// Safety: kill switch halts everything
if (KILL_SWITCH) {
log({ step: 'safety_blocked', action: payload.action, reason: 'KILL_SWITCH active' });
return;
}
// DRY_RUN: only read-only actions pass through
const readOnlyActions = ['register', 'list_orders', 'check_order'];
if (DRY_RUN && !readOnlyActions.includes(payload.action)) {
log({ step: 'dry_run_skip', action: payload.action, token: payload.token_address, message: `would send ${payload.action} but DRY_RUN=true` });
return;
}
// Safety: check denylist for order placement
if (['sell', 'buy', 'trailing_sell', 'trailing_buy'].includes(payload.action)) {
if (isTokenOnCooldown(payload.token_address)) {
const retryAfter = SAFETY.DENYLIST.get(payload.token_address);
log({ step: 'safety_blocked', token: payload.token_address, reason: 'cooldown_active', retry_after_ms: retryAfter });
return;
}
// Enforce MAX_BUY_LAMPORTS for WebSocket buy and trailing_buy (same as buildSwap)
if (payload.action === 'buy' || payload.action === 'trailing_buy') {
const amount = payload.amount;
if (typeof amount !== 'number' || amount > SAFETY.MAX_BUY_LAMPORTS) {
log({ step: 'safety_blocked', action: payload.action, token: payload.token_address, reason: 'amount exceeds MAX_BUY_LAMPORTS', amount, max: SAFETY.MAX_BUY_LAMPORTS });
return;
}
}
}
if (!client.registered) {
client.pendingQueue.push(payload);
log({ step: 'ws_queued', action: payload.action, message: 'not yet registered' });
return;
}
client.ws.send(JSON.stringify(payload));
},
close: () => client.ws.close(),
};
}
async function handleOrderFilled(msg) {
try {
assertSchema(validateOrderFilled, msg, 'order_filled message');
} catch (e) {
log({ step: 'order_fill_error', order_id: msg.order_id || 'unknown', error: e.message });
return;
}
const { order_id, order_type, triggered_mcap, filled_mcap, token_address } = msg;
const swap_tx = msg.data?.swap_tx;
log({ step: 'order_filled', order_id, order_type, token: token_address, triggered_mcap, filled_mcap });
if (msg.already_dispatched) {
log({ step: 'order_fill_skipped', order_id, reason: 'already_dispatched' });
return;
}
// Verify server_signature before signing or submitting.
const verified = await verifyOrderFilledSignature(msg);
if (!verified) {
log({ step: 'order_fill_skipped', order_id, reason: 'server_signature_verification_failed' });
return;
}
if (!swap_tx) {
log({ step: 'order_fill_error', order_id, error: 'missing swap_tx' });
return;
}
// Staleness check (all fills; skip ratio when filled_mcap is 0 or null)
if (filled_mcap != null && filled_mcap > 0 && triggered_mcap != null && triggered_mcap / filled_mcap < 0.85) {
log({ step: 'order_fill_skipped', order_id, reason: 'stale', triggered_mcap, filled_mcap });
return;
}
const signedBase64 = signVersionedTx(swap_tx);
const result = await submitTx(signedBase64, { token: token_address, action: order_type });
log({ step: 'order_fill_submitted', order_id, signature: result.signature });
}
// ---------- Preflight ----------
async function preflight() {
const checks = [];
checks.push({ name: 'PRIVATE_KEY loaded', pass: !!process.env.PRIVATE_KEY });
if (!process.env.RPC_URL) {
console.log('⚠ RPC_URL not set — using default public RPC (rate-limited, not recommended for production)');
}
checks.push({ name: 'RPC_URL configured', pass: true, url: process.env.RPC_URL ? '(custom)' : '(default public)' });
try {
const pubkey = getWallet().publicKey.toBase58();
checks.push({ name: 'Wallet loads', pass: true, pubkey });
} catch (e) {
checks.push({ name: 'Wallet loads', pass: false, error: e.message });
}
try {
const slot = await connection.getSlot();
checks.push({ name: 'RPC reachable', pass: true, slot });
} catch (e) {
checks.push({ name: 'RPC reachable', pass: false, error: e.message });
}
try {
const balance = await connection.getBalance(getWallet().publicKey);
checks.push({ name: 'SOL balance > 0.01', pass: balance > 10_000_000, balance });
} catch (e) {
checks.push({ name: 'SOL balance', pass: false, error: e.message });
}
try {
const holdings = await getHoldings();
checks.push({ name: '/holdings responds', pass: true, token_count: holdings.length });
} catch (e) {
checks.push({ name: '/holdings responds', pass: false, error: e.message });
}
// Preflight WS check — listen for 'challenge', sign nonce, send register with signature,
// then verify authenticated: true in the 'registered' response.
try {
await new Promise((resolve, reject) => {
const ws = new WebSocket(WS_URL);
const timeout = setTimeout(() => { ws.close(); reject(new Error('ws timeout')); }, 10000);
ws.on('message', (raw) => {
const msg = JSON.parse(raw);
if (msg.type === 'challenge') {
const nonce = msg.nonce;
const sigBytes = nacl.sign.detached(Buffer.from(nonce, 'utf-8'), getWallet().secretKey);
const signature = bs58.encode(sigBytes);
ws.send(JSON.stringify({
action: 'register',
wallet_address: getWallet().publicKey.toBase58(),
signature,
}));
}
if (msg.type === 'registered') {
clearTimeout(timeout);
ws.close();
if (!msg.authenticated) {
reject(new Error('registered but authenticated: false — check server signature'));
} else {
resolve();
}
}
});
ws.on('error', (err) => { clearTimeout(timeout); reject(err); });
});
checks.push({ name: 'WS register', pass: true });
} catch (e) {
checks.push({ name: 'WS register', pass: false, error: e.message });
}
console.log('\n=== PREFLIGHT ===');
checks.forEach(c => console.log(`${c.pass ? '✓' : '✗'} ${c.name}`, c.pass ? '' : `— ${c.error || ''}`));
const allPass = checks.every(c => c.pass);
console.log(`\n${allPass ? '🟢 ALL CHECKS PASSED — ready to go live' : '🔴 CHECKS FAILED — fix before going live'}\n`);
console.log(`Mode: ${DRY_RUN ? '📋 DRY RUN (set DRY_RUN=false to go live)' : '🔴 LIVE TRADING'}\n`);
return allPass;
}
// ---------- Usage (call from main, never at module load) ----------
async function main() {
const ready = await preflight();
if (!ready) process.exit(1);
const demoTokenMint = process.env.DEMO_TOKEN_MINT;
if (!demoTokenMint) {
log({ step: 'demo_skipped', message: 'set DEMO_TOKEN_MINT to run write-path examples in main()' });
return;
}
const demoBuyAmountLamports = Number(process.env.DEMO_BUY_AMOUNT_LAMPORTS || 100_000_000);
if (!Number.isFinite(demoBuyAmountLamports) || demoBuyAmountLamports <= 0) {
throw new Error('DEMO_BUY_AMOUNT_LAMPORTS must be a positive integer');
}
// Instant buy
const swap = await buildSwap({ tokenAddress: demoTokenMint, action: 'buy', amount: demoBuyAmountLamports });
const signed = signVersionedTx(swap.swap_tx);
const result = await submitTx(signed, { token: demoTokenMint, action: 'buy' });
// Instant sell (only if wallet has sellable tokens)
const holdings = await getHoldings();
if (holdings.length === 0) {
log({ step: 'sell_skipped', message: 'no sellable tokens in wallet' });
} else {
const token = holdings[0];
const swap2 = await buildSwap({ tokenAddress: token.address, action: 'sell', holdingsPercentage: 10000 });
const signed2 = signVersionedTx(swap2.swap_tx);
const result2 = await submitTx(signed2, { token: token.address, action: 'sell' });
}
// Limit order via WS
const ws = connectWsAndRegister(handleOrderFilled);
// Silent expiry guard: poll open orders periodically (expiry has no server event).
setInterval(() => ws.send({ action: 'list_orders' }), 60000);
// after registered:
ws.send({ action: 'sell', token_address: demoTokenMint, holdings_percentage: 10000, target: 20000, slippage: 1500, expiry_hours: 144 });
}
main().catch(console.error);
```
---
## Signing / Encoding Test Vectors
Use these to verify your signing pipeline produces valid output.
### Test: base58 decode → sign → base64 encode
```
Input swap_tx (base58):
(any valid base58 string from /swap response)
Expected pipeline:
bs58.decode(swap_tx) → Uint8Array (raw bytes)
VersionedTransaction.deserialize(bytes) → tx object (check: tx.message exists)
tx.sign([wallet]) → void (modifies tx in place, fills signature slots)
tx.serialize() → Uint8Array (same length — signature slots are pre-allocated)
Buffer.from(bytes).toString('base64') → string (starts with alphanumeric, contains +/=)
Self-check assertions:
1. Decoded bytes length > 0
2. tx.message exists (versioned tx from TradeRouter)
3. After sign: tx.signatures[0] is not all zeros (signature was written)
4. Signed bytes length === decoded bytes length (slots pre-allocated, signing fills them)
5. Base64 output does NOT start with a bracket or brace (not JSON)
6. Base64 output is NOT the same as the base58 input (different encoding)
```
### Quick validation function
```javascript
function validateSignedTx(swapTxBase58, signedBase64) {
const unsignedBytes = bs58.decode(swapTxBase58);
const signedBytes = Buffer.from(signedBase64, 'base64');
console.assert(unsignedBytes.length > 0, 'decoded bytes empty');
console.assert(signedBytes.length === unsignedBytes.length, 'signed and unsigned should be same length (signature slots pre-allocated)');
console.assert(signedBase64 !== swapTxBase58, 'output must differ from input (different encoding)');
console.assert(!/^[{[]/.test(signedBase64), 'base64 should not look like JSON');
// Deserialize signed to verify it's valid
const tx = VersionedTransaction.deserialize(signedBytes);
console.assert(tx.signatures[0].some(b => b !== 0), 'signature should not be zeros');
console.log('✓ signing pipeline valid');
}
```
---
## Request / Response Schemas
Machine-readable schemas for pre-validation. The reference client compiles and enforces these required fields with `ajv` before network calls.
### POST /swap — request
```json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"required": ["wallet_address", "token_address", "action"],
"properties": {
"wallet_address": { "type": "string", "minLength": 32, "maxLength": 44 },
"token_address": { "type": "string", "minLength": 32, "maxLength": 44 },
"action": { "type": "string", "enum": ["buy", "sell"] },
"amount": { "type": "integer", "minimum": 1 },
"holdings_percentage": { "type": "integer", "minimum": 1, "maximum": 10000 },
"slippage": { "type": "integer", "minimum": 100, "maximum": 2500, "default": 500 }
},
"if": { "properties": { "action": { "const": "buy" } } },
"then": { "required": ["amount"], "not": { "required": ["holdings_percentage"] } },
"else": { "required": ["holdings_percentage"], "not": { "required": ["amount"] } }
}
```
### POST /swap — success response
```json
{
"type": "object",
"required": ["status", "data"],
"properties": {
"status": { "const": "success" },
"data": {
"type": "object",
"required": ["swap_tx"],
"properties": {
"swap_tx": { "type": "string", "minLength": 100 },
"pool_type": { "type": "string" },
"pool_address": { "type": "string" },
"amount_in": { "type": "integer" },
"min_amount_out": { "type": "integer" },
"price_impact": { "type": "number" },
"slippage": { "type": "integer" },
"decimals": { "type": "integer" }
}
}
}
}
```
### POST /protect — request
```json
{
"type": "object",
"required": ["signed_tx_base64"],
"properties": {
"signed_tx_base64": { "type": "string", "minLength": 100, "pattern": "^[A-Za-z0-9+/]+=*$" }
}
}
```
### POST /holdings — response (non-empty)
```json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": ["address", "amount", "decimals"],
"properties": {
"address": { "type": "string" },
"valueNative": { "type": ["integer", "null"] },
"amount": { "type": "integer" },
"decimals": { "type": "integer" }
}
}
}
}
}
```
### WebSocket order_filled
When `already_dispatched` is true, the server may omit `data` or `data.swap_tx` (idempotent ack). Schema must not require them.
```json
{
"type": "object",
"required": ["type", "order_id", "order_type", "status"],
"properties": {
"type": { "const": "order_filled" },
"order_id": { "type": "string", "format": "uuid" },
"order_type": { "type": "string", "enum": ["sell", "buy", "trailing_sell", "trailing_buy"] },
"status": { "type": "string", "enum": ["success"] },
"already_dispatched": { "type": "boolean" },
"entry_mcap": { "type": "number" },
"triggered_mcap": { "type": "number" },
"filled_mcap": { "type": ["number", "null"] },
"target_mcap": { "type": "number" },
"triggered_at": { "type": "number" },
"filled_at": { "type": "number" },
"token_address": { "type": "string" },
"server_signature": { "type": "string" },
"data": {
"type": "object",
"properties": {
"swap_tx": { "type": "string", "minLength": 100 },
"token_address": { "type": "string" },
"pool_type": { "type": "string" },
"pool_address": { "type": "string" },
"amount_in": { "type": "integer" },
"min_amount_out": { "type": "integer" },
"price_impact": { "type": "number" },
"slippage": { "type": "integer" },
"decimals": { "type": "integer" }
}
}
}
}
```
---
## Retry / Idempotency Policy
| Error class | Retry? | Max attempts | Backoff | Notes |
|-------------|--------|-------------|---------|-------|
| 400 from /swap | **No** | 0 | — | Bad request. Fix payload. |
| 422 from /swap | **No** | 0 | — | Missing fields. Fix payload. |
| "Error running simulation" | **Cooldown** | 0 immediate | 15m | Mark token unswappable for the session and retry later only if needed. |
| 503 from /protect | **Auto-fallback** | 1 | — | `submitTx()` falls back to RPC internally. No manual action. |
| /protect timeout (30s) | **Check first** | 1 | — | Check tx status via `connection.getSignatureStatuses([sig])`. Only retry if `value[0]` is null (not found). |
| /holdings timeout | **Yes** | 2 | 5s | Endpoint is slow, not broken. |
| /swap 5xx | **Yes** | 2 | 3s | Server issue, may resolve. |
| WS disconnect | **Reconnect** | ∞ | 3s fixed | Re-register. Orders persist. |
| WS error message | **No** | 0 | — | Log and surface to user. |
| On-chain swap failure | **Maybe** | 1 | — | Increase slippage to 2500, retry once. If fails again, skip. |
**Idempotency:** Solana transactions include a recent blockhash. A signed tx can only land once. If /protect times out, the tx may have landed — always check via RPC before re-signing a new tx.
---
## Timeout and Confirmation Contracts
| Endpoint | Timeout | On timeout |
|----------|---------|------------|
| `POST /swap` | 15s | Retry once with 3s backoff |
| `POST /protect` | 30s | Call `connection.getSignatureStatuses([sig])`. If `value[0]` is null → tx didn't land, safe to retry. If `value[0].err` → tx failed on-chain, do not retry. If `confirmationStatus` is `'processed'` → transitional, wait 2s and re-check. If `'confirmed'` or `'finalized'` → landed, do not retry. `submitTx()` handles all this internally. |
| `POST /holdings` | 100s | Retry once with 5s backoff |
| WebSocket connect | 10s | Retry with 3s backoff |
### Post-timeout /protect check
`checkTxLanded()` is defined in the Reference Client above. Returns `{ landed, sig, status }`:
- `{ landed: false, sig, status: 'not_found' }` — safe to retry via RPC fallback
- `{ landed: true, sig, status: 'failed', err }` — tx errored on-chain, do not retry
- `{ landed: true, sig, status: 'processed' }` — transitional, wait 2s and re-check
- `{ landed: true, sig, status: 'confirmed' }` — tx landed, do not retry
- `{ landed: true, sig, status: 'finalized' }` — tx landed and finalized, do not retry
`sig` is the real base58 transaction signature for reconciliation. `submitTx()` handles all of this internally.
---
## WebSocket Lifecycle State Machine
```
┌──────────────┐
│ DISCONNECTED │ ←── ws.close / error / timeout
└──────┬───────┘
│ connect
▼
┌──────────────┐
│ CHALLENGE │ ←── server sends {"type":"challenge","nonce":"..."}
└──────┬───────┘
│ sign nonce; send register with wallet_address + signature
▼
┌──────────────┐
│ REGISTERED │ ←── server sends {"type":"registered","authenticated":true}
└──────┬───────┘
│ (can now send orders)
▼
┌──────────────┐
│ ACTIVE │ ←── orders placed, listening for fills
└──────────────┘
```
**Rules:**
- **DISCONNECTED:** no sends allowed. Reconnect immediately.
- **CHALLENGE:** sign nonce and send `register` with wallet_address + signature only. All other sends rejected until REGISTERED.
- **REGISTERED / ACTIVE:** all actions allowed. Only enter REGISTERED state when `authenticated: true` is confirmed.
- On any disconnect, state resets to DISCONNECTED. Orders persist server-side.
- Queue any order sends that arrive during DISCONNECTED/CHALLENGE and flush after REGISTERED.
---
## Execution Safety Guards
All safety enforcement is **built into the reference client** — `enforceSafety()` is called inside `buildSwap()`, `KILL_SWITCH` is checked in `submitTx()` and `ws.send()`, `markUnswappable()` is called on "Error running simulation" responses, token cooldown is checked before WS order placement, and **dailyLoss** is updated on every successful spend path (protect success, timeout recovery, RPC fallback) for both `buy` and `trailing_buy`. **MAX_BUY_LAMPORTS** is enforced in `ws.send()` for `buy` and `trailing_buy` orders so WebSocket orders cannot bypass the per-trade limit.
**Defaults (adjust per deployment):**
`MAX_BUY_LAMPORTS = 0.5 SOL` is intentionally conservative for first deploys. Increase only after risk limits, kill switch, and monitoring are verified.
| Guard | Default | Enforced in |
|-------|---------|-------------|
| MAX_BUY_LAMPORTS | 500,000,000 (0.5 SOL, conservative starter value) | `buildSwap()` via `enforceSafety()`, `ws.send()` for buy/trailing_buy |
| MAX_SLIPPAGE_BPS | 2500 (25%) | `buildSwap()` via `enforceSafety()` |
| MIN_SLIPPAGE_BPS | 100 (1%) | `buildSwap()` via `enforceSafety()` |
| MIN_VALUE_NATIVE | 0 (`valueNative > 0`, defensive) | `getHoldings()` filter |
| UNSWAPPABLE_COOLDOWN_MS | 900,000 (15 minutes) | `markUnswappable()` |
| MAX_DAILY_LOSS_LAMPORTS | 2,000,000,000 (2 SOL) | Updated on every spend path: `/protect` success, timeout_recovery, `_rpcFallback()`; `enforceSafety()` → activates KILL_SWITCH |
| DENYLIST | empty Map (session-scoped cooldown) | `buildSwap()`, `ws.send()`, auto-populated by `markUnswappable()` |
| KILL_SWITCH | false | `submitTx()`, `ws.send()`, auto-activated on daily loss limit |
**Unswappable token cooldown:** When `/swap` returns "Error running simulation", `buildSwap()` calls `markUnswappable(tokenAddress)`, placing that token on a 15-minute session cooldown. This avoids retry loops while allowing future retries later.
**Emergency kill:** Set `KILL_SWITCH = true` to halt all execution. Also auto-activates when `dailyLoss > MAX_DAILY_LOSS_LAMPORTS`.
---
## Logging Format
All logging is through the `log()` function in the reference client, which outputs JSON lines with automatic timestamp and wallet fields.
**Every step emitted by the reference client:**
| Step | Emitted by | Required fields |
|------|-----------|----------------|
| swap_request | `buildSwap()` | token, action, amount/holdings_percentage, slippage |
| swap_response | `buildSwap()` | token, pool_type, amount_in |
| swap_error | `buildSwap()` | token, error |
| safety_blocked | `enforceSafety()`, `markUnswappable()`, `ws.send()` | token, reason |
| dry_run_skip | `submitTx()`, `ws.send()` | token, action, message |
| protect_success | `submitTx()` | token, signature |
| protect_503 | `submitTx()` | message |
| protect_timeout | `submitTx()` | token, message |
| protect_timeout_landed | `submitTx()` | signature, status |
| protect_timeout_processed | `submitTx()` | signature, message |
| protect_timeout_failed | `submitTx()` | signature, message |
| protect_timeout_not_landed | `submitTx()` | message |
| rpc_fallback_success | `_rpcFallback()` | signature |
| sell_skipped | `main()` | message |
| ws_connected | WS `open` handler | — |
| ws_registered | WS `registered` handler | — |
| ws_disconnected | WS `close` handler | message |
| ws_error | WS `error` handler | error |
| ws_queued | `ws.send()` | action, message |
| order_placed | WS `order_created` handler | order_id, token, action, target_mcap |
| order_filled | `handleOrderFilled()` | order_id, order_type, token, triggered_mcap, filled_mcap |
| order_fill_error | `handleOrderFilled()` | order_id, error |
| order_fill_skipped | `handleOrderFilled()` | order_id, reason, triggered_mcap, filled_mcap |
| order_fill_submitted | `handleOrderFilled()` | order_id, signature |
| order_fill_verify_failed | `verifyOrderFilledSignature()` | order_id, reason |
---
## Dry-Run / Paper Mode
**Safe-by-default:** `DRY_RUN` is **true** unless you explicitly set `DRY_RUN=false`. A fresh agent runs paper mode automatically — no accidental live trades on first run.
Dry-run is enforced at the two chokepoints in the reference client — `submitTx()` and `ws.send()`. The agent runs the full pipeline (fetches swap quotes, enforces safety guards, logs everything) but:
- **`submitTx()`** short-circuits before submission and returns `{ signature: null, dry_run: true }`
- **`ws.send()`** blocks all mutating actions (`sell`, `buy`, `trailing_sell`, `trailing_buy`, `cancel_order`, `extend_order`) and logs intent
- Only read-only operations pass through: `register`, `list_orders`, `check_order`
There is no separate "paper mode function." The same `main()` code path runs in both modes — `DRY_RUN` just gates the irreversible actions.
```bash
# Paper mode (default — no DRY_RUN env needed)
PRIVATE_KEY=... node agent.js
# Live mode — must explicitly opt in
DRY_RUN=false PRIVATE_KEY=... node agent.js
```
---
## Preflight Startup Checklist
The `preflight()` function is built into the reference client. It runs automatically at the start of `main()` and exits the process if any check fails.
**Checks performed:**
| Check | Fails if |
|-------|----------|
| PRIVATE_KEY loaded | env var missing |
| RPC_URL configured | always passes (warns if using default public RPC) |
| Wallet loads | key is invalid/undecodable |
| RPC reachable | `getSlot()` fails |
| SOL balance > 0.01 | balance < 10,000,000 lamports |
| /holdings responds | endpoint unreachable or times out |
| WS register | WebSocket connect, challenge–response, or `authenticated: true` confirmation fails within 10s |
After all checks, preflight reports mode (`DRY RUN` or `LIVE TRADING`).don't have the plugin yet? install it then click "run inline in claude" again.