Endpoints and Errors

Every WakeTrades API v1 endpoint, with its method and purpose, and the stable error codes an agent can rely on.

Base URL: https://waketrades.com/api/v1/. JSON in and out. Routes marked 🔒 need Authorization: Bearer <token> (Sign In With a Wallet). The full schema is in /openapi.json.

Account and Setup

Copying

Plans

Monthly Report

GET /report answers 404 no_edition if no edition is published yet, and GET /leaders/suggested answers 404 no_suggestion: choose a trader yourself by address and check it with GET /leader/{address}.

With a paid plan in progress, access is full. Otherwise, during the free trial for example, it's preview: each entry keeps its rank, its type and what copying it would have earned and lost at that level (rounded to 1%), the trader's own return over 90 days and 6 months and win rate (leader.return90d, leader.return6m, leader.winRate90d, rounded to 1%) and profit factor (leader.profitFactor90d, one decimal), without name, address or the trader's other account figures, and has locked: true. Both views include yourCopy: for each level, the top 3 traders copied together at that level's size, by balance (1,000 to 25,000 USDC) — result, median, 1-in-10 and worst 30 days, worst drop, alerts crossed, peak exposure and margin (yourCopy is simulated: limit orders at the trader's price, then market after 1 min if unfilled, about 30 s after the trader, 0.026% average fee per side, funding not included). With full, each entry's copy also gives trades (the trader's trades in the 90 days), copies, simShare and skipped (why trades were not copied), and leader.stressBtc10 (the trader's estimated move if BTC drops 10% in a day). Both views also include yourResults, the real figures of the signed-in wallet for the edition's month: { ready: false } until a month of copy trading is closed, then from, to, startEquity, endEquity, deposits, withdrawals, change (without deposits and withdrawals), realized (closed copies, fees and funding included), closed, unrealized and open (copies still open at the end). Editions come out on the 1st of each month for the month just ended. On the test environment (Testnet USDC), full is reserved to the WakeTrades team.

Public

GET /me

• client: address, state, lang, level, leaders, leader_names, wallet_name, agent_address, agent_approved_at, agent_valid_until, telegram_chat_id, telegram_username, trial_started_at, plan_kind, plan_expires_at, paused_reason, tos_accepted_at, tos_version, created_at.
• status: the copier — state, level, leaders, orderMode, accountMode (Hyperliquid's mode: default, unifiedAccount, portfolioMargin…; null before activation), notices, trial_ends_at, plan_expires_at, advanced (Advanced settings, defaults included; on the 6-month plan also at other levels, where they are kept but not applied; null otherwise), advancedRulesActive (how many Advanced settings differ from the defaults; 0 at other levels), dailyLossUntil (ms while a daily loss limit is in progress, otherwise null).
• notices: ["standard_account"] while the account isn't a Unified Account (switch with POST /account/unified); ["unified_now"] once an account seen as standard has become unified. POST /notices/dismiss { "id" } hides one for good.
• equity: the Hyperliquid balance, read at most every 10 minutes; read again right after a payment or a switch to a Unified Account.
• unified: true when status.accountMode is unifiedAccount or portfolioMargin; before activation, read from Hyperliquid; null if unknown.
• copiesOnHold: { "held": true, "reasons": ["not_unified", "manual_positions"], "coins": ["BTC"] }. held is true when your leaders' next trades would not be copied now. Computed from what /me already reads (no extra Hyperliquid read): check it after setup and whenever copies don't appear.
• renewal: { "days": 7, "until": 1795000000000, "planKind": "1m", "founderPrice": true } while a paid plan is close to its end (30 days for a 6-month plan, 14 for 3 months, 7 for 1 month), otherwise null. Renew with GET /pay/prepare then POST /pay before until: the new plan starts at until, and founderPrice: true means the founder price is kept. A plan_expiring webhook event is sent at the start of this period and the day before.

Account States

client.state (and status.state):

Unified Account

At Prudent, Balanced and Risky, new copies open only on a Hyperliquid Unified Account with no position opened outside WakeTrades. Until then, each new trade of your leaders is skipped (skip: not_unified, or manual_positions for positions opened outside WakeTrades) and an account_blocked event is sent at most once a day. At Advanced, a standard account copies, except the xyz markets (stocks, indices, commodities), which always need a Unified Account (hip3_unified). POST /account/unified with {} switches the account with the trading key, without a wallet signature; it returns { "mode", "unified" } and sends an account_unified event. On Hyperliquid, the USDC moves from Perps to Spot, where it backs every market.

Recommended Level

An account needs a minimum balance to copy, because Hyperliquid has a minimum order size (10 USDC; WakeTrades uses 11 for rounding). Each leader is copied at their position × your balance ÷ theirs × the level's size ÷ 3; on a small balance, many copies come out under that minimum. Such a copy is not skipped: it opens at 11 USDC, larger than the level's share, so the account takes more risk than its level shows (it is skipped only when the coin's smallest size step would push it above 22 USDC, too_small, or when the exposure cap is reached, cap). Minimum practical balance: 1,100 USDC at Prudent, 550 at Balanced, 300 at Risky (Advanced: 300 with Risky's size) — see why.

recommendedLevel is the most prudent of prudent → equilibre → risque whose minimum your balance covers. Under every minimum, it is risque with belowAllMinimums: true: copies open at the 11 USDC floor whatever the level, and Risky, with the largest share per leader, stays closest to your leaders' proportions. advanced is never recommended. recommendationNote says why in one sentence. The recommendation is only advice: any level can be chosen. With a session token and USDC still in spot on a standard account (a new account's first transfer often lands there), equity is 0: the answer then adds spotUsdc and equitySource: "spot", and recommends on that spot balance. It backs copies once WakeTrades switches the account to unified (POST /account/unified, right after the trading key).

{ "equity": 150, "recommendedLevel": "risque", "belowAllMinimums": true, "recommendationNote": "Your 150 USDC is under every level's minimum balance (…)" }

GET /preview

What each level would do with your balance (or ?planned= USDC if the account has no balance yet) and your first leader, plus recommendedLevel, belowAllMinimums and recommendationNote for that balance (Recommended Level):

Warning: Copies Too Small

PUT /settings and POST /agent/verify succeed as usual and may add, at Prudent, Balanced or Risky:

{ "warning": { "code": "copies_too_small", "leader": "0x…", "tooSmallPct": 100, "equity": 65.5, "minOrderUsd": 11, "minPracticalBalanceUsd": 1100, "message": "…" } }

It means at least 90% of that leader's trades would copy under the minimum order at your balance: they open at 11 USDC, larger than your level's share, so the account takes more risk than its level shows. Nothing is blocked. Deposit more, pick a larger level, or another leader. It is computed from the same readings as /preview and the leader's card already computed; without a card, no warning.

Suggested Traders

GET /leaders/suggested?level=risque proposes a trader from our latest Monthly Report for the level (advanced uses risque's list), with the report's 90-day figures. The rule, the same on the site, the API and MCP:

1. The suggestion of each more prudent level is set aside first, in order: Prudent's, then Balanced's.
2. Among the level's #3 to #5 not set aside, the one who opened the most positions in the 30 days before the report is suggested (a tie goes to the better rank). Never #1 or #2. If #3 to #5 were all set aside, the most active of them is suggested anyway. A list shorter than 3, or an edition without this activity figure: the level's top 5 is read from #5 (or the last) up to #1 and the first trader not set aside is suggested.
3. One suggestion per level, for every account: three traders of the report in all. You can follow up to 3 leaders (5 at Advanced). The full lists are in the Monthly Report with a paid plan. count above 1 is ignored (the answer adds "countLimited": true). Risky strongly recommends 2 leaders: choose the second one yourself.

{ "level": "risque", "list": "risque", "rank": 3, "address": "0x…", "month": "2026-10",
  "stats": { "winRatePct": 58, "profitFactor": 1.6, "tradesPerMonth": 24, "medianHoldHours": 9.5 }, "note": "…",
  "liveCheck": "GET /api/v1/leader/0x…/positions",
  "suggestions": [ { "rank": 3, "address": "0x…", "liveCheck": "…", "…": "…" } ] }

The top-level fields are the first suggestion (as before count existed); suggestions lists them all, each with the same fields. The report's figures are month-end: before choosing, read each trader's live positions with liveCheck (GET /leader/{address}/positions), since a trader can hold a large losing position now. The rest of the list comes with a plan.

Order Mode

status.orderMode says how copies enter; PUT /order-mode changes it (MCP set_order_mode).

• limit (default for new accounts): a post-only order at the leader's entry price (or the best price on the book if better). Unfilled after 1 minute, it is cancelled and the copy opens at market, unless the price is more than 1% from the leader's entry. If the leader exits before it fills, nothing is copied and a limit_missed event is sent.
• market: the copy opens at market right away; skipped (late) if the price is already more than 1% from the leader's entry.

{ "mode": "market" }

Orders already waiting keep their mode.

Advanced Settings

At level advanced (every plan, free trial included), PUT /advanced changes the settings (MCP set_advanced, snake_case names). Fields you leave out keep their value. Every filter and limit below is off by default: until you set one, copying works as before. Size, exposure, alerts, automatic stop, adds and TP/SL: see Set Up Copying.

{ "markets": ["btc", "gold"], "minMarketLeverage": 20, "maxLeverage": 5, "sides": "long", "copyStopPct": 8, "dailyLossPct": 10 }

• Which trades open. The ticked markets combine with OR (["btc", "gold"] copies BTC and gold); minMarketLeverage and sides apply on top (AND). These rules decide only which new copies open: adds, reductions and closes of a copy already open are always followed, even if you change the rules afterwards.
• Skipped trades. A leader's trade not copied by these rules shows in GET /orders (and on the stream) as a skip with a stable code: market_filtered, leverage_filtered, side_filtered or daily_loss_limit.
• maxLeverage is set when the copy opens and kept for its adds.
• copyStopPct. The stop stays at that price, computed from the copy's first entry, and is resized to the whole copy after adds and reductions. If the leader's copied stop (copyLeaderTpSl) is closer to the entry, the leader's is kept instead. It is capped at 80 % of the distance to liquidation; under 1 %, the trade is skipped (liq_close). If no stop can be placed, the copy is closed right away. Copies already open keep the stop they opened with.
• dailyLossPct. The day's reference is your balance's first reading of the UTC day; a plan payment is taken out of it (it is not a loss). Deposits and withdrawals since that reading do not count: before the limit applies, WakeTrades reads your Hyperliquid ledger and takes money that came in out of your balance and adds money that left back to it (moves between your perps and spot balances are ignored). If the ledger cannot be read, the limit is not applied on that check and is checked again at the next one, 5 minutes later. When the limit is reached, a daily_loss_limit event goes to your webhook and Telegram, and status.dailyLossUntil gives the end of the 24 hours. Copies already open stay managed: adds, reductions, closes, stops. Setting dailyLossPct to null lifts a limit in progress.
• Your own take profits and stop loss (tp1Pct, tp2Pct, slPct). Placed on Hyperliquid when the copy opens, as reduce-only trigger orders at the price that gives that PnL % for the copy's leverage; they sit next to your leader's copied stop-loss and take-profit (copyLeaderTpSl) and copyStopPct: the first one reached runs, and when several stops close the whole copy, the closest is kept. After a partial close the copy keeps following the leader on what is left (its adds, reductions and close), without buying the closed part back. If the part to close, or what would be left, is under Hyperliquid's minimum order, the level closes the whole copy. They apply to copies opened after you save them.
• Kept across levels. Your settings stay saved when you switch to another level and apply again when you come back to advanced. GET /me returns them in status.advanced at every level; they apply only at advanced, so status.advancedRulesActive (how many differ from the defaults) is 0 at other levels. PUT /advanced answers { "advanced", "advancedRulesActive" }. GET /levels lists the bounds (levels.advanced.fields) and the market groups (marketGroups).

Account Deletion

GET /account/delete-check 🔒, then POST /account/delete/nonce 🔒 and POST /account/delete 🔒 with a signed message, like sign-in. Allowed when every open copy has a stop (stops_required otherwise).

Hello

GET /api/v1/hello (MCP: hello) is the first call to make. Public and cheap: no session, no Hyperliquid read.

{
  "name": "WakeTrades",
  "what": "Non-custodial copy trading on Hyperliquid: we copy the traders you choose onto your own Hyperliquid account, and funds never leave it.",
  "quickStart": [
    { "step": "Sign in with your wallet (EIP-191)", "endpoint": "POST /api/v1/session/nonce, then POST /api/v1/session/verify" },
    { "step": "Choose an exposure level, then traders", "endpoint": "GET /api/v1/levels, PUT /api/v1/settings, GET /api/v1/leaders/suggested" },
    { "step": "Sign the trading key (it can trade, never withdraw)", "endpoint": "POST /api/v1/agent, POST /api/v1/agent/approve, POST /api/v1/agent/verify" }
  ],
  "network": "Mainnet",
  "copying": "on",
  "links": { "docs": "…/docs/api/", "openapi": "…/openapi.json", "llms": "…/llms.txt", "mcp": "…/mcp", "skills": "https://github.com/waketrades/hyperliquid-copy-trading-agent-skills", "terms": "…/terms" },
  "version": "0.1.0"
}

copying is the switch for every account: pause means no new copies for anyone (open ones stay managed), halt means no order at all during an incident. The full flow, webhook and payment included, is in WakeTrades for AI Agents.

Dry Run

Add ?dryRun=true (or "dryRun": true in the body) to rehearse a call with no effect:

• PUT /settings: every check of the real call runs, with the same errors (unknown_leader, too_many_leaders, risk_ack_required…). The answer is what the call would give: { "dryRun": true, "client": { … as it would be }, "activeLeaders", "warning"?, "equity", "recommendedLevel", "belowAllMinimums", "recommendationNote" }. Nothing is saved and no event is sent.
• POST /pay: every check of the real call runs (action, plan and amount, receiver, token, signer, age), plus the balance of the signed source (perps for usdSend, spot for sendAsset: 409 insufficient_usdc). The answer is { "dryRun": true, "ok": true, "plan", "amount", "from", "source", "balanceChecked", "wouldRelay": true }, or the same error the real call would give. Nothing is relayed to Hyperliquid, no plan is applied and nothing is written. Then send the same action without dryRun, within its 10 minutes: the real call runs every check again.

MCP: dry_run: true on set_copy_settings and submit_payment.

Idempotency

POST /pay, /agent/approve, /close-all, /close-position, /emergency-stop, /pause, /resume and /account/unified accept an optional Idempotency-Key header: 1 to 255 printable ASCII characters, a UUID for example. Use a new key for each new action, and the same key to retry it.

• First call: runs normally; its answer is kept 24 hours for your account and that key.
• Same key, same request (same method, path and body) within 24 hours: the first answer comes back with the header Idempotent-Replayed: true, and nothing runs again. A payment is never relayed twice.
• Same key, different request: 422 idempotency_key_reused.
• Same key while the first call is still running: 409 idempotency_in_progress; retry a few seconds later.
• Not kept: 5xx and 429 answers (retry with the same key, it runs again), and dry runs (dryRun ignores the key).
• Errors are kept too: a 4xx answer comes back on every retry with the same key. Once you fix the cause (a new signature, more USDC…), send the corrected request with a new key.
• Keys are per account: another wallet can use the same key.

MCP: idempotency_key on submit_payment, submit_trading_key, switch_to_unified_account, pause_copying, resume_copying, close_position, close_all and emergency_stop.

Errors

Every error is { "error": "<code>", "message": "<English text>", "fix": "<what to do next>", "docs": "<URL>" }, sometimes with detail and other fields. fix is one short sentence saying what to do next; docs links to the most useful section of these pages. Codes are stable; messages and fixes may change. MCP tool errors carry the same fields.

{ "error": "stale_signature", "message": "The signed action is older than 10 minutes. Sign a new one.", "fix": "Prepare and sign a new payment, then send it within 10 minutes.", "docs": "https://waketrades.com/docs/api/payments#errors" }