Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

18.4 KB
Raw Blame

Agent Perps

Agent Perps lets one of your agents go long or short on perpetual futures with USDC collateral held in its own custodial Solana wallet. Every agent starts in paper mode, which fills at live venue prices and moves no funds. Live mode stays off until you turn it on for that agent. Every action is previewed first and executed only with an explicit confirmation. A leverage cap and a per-position margin cap always apply, and a kill switch flattens everything at once.

There are three ways in, and all three run the same service (api/_lib/perps/service.js), so the guards, previews and results are identical:

Surface Where Who uses it
The desk page /agent-perps, or /agents/<agent id>/perps The owner, signed in
REST /api/v1/agents/:id/perps/* Your own code, with a session or an API key
MCP perps_* tools on /api/mcp-agent Claude, or any MCP client you connect

Related reading: agent wallets covers the custody and spend-policy model the deposits run under, custody you can verify covers the freeze and kill switches, and the risk acknowledgment explains the agreements live mode requires.


Paper and live

Paper (the default) Live
Prices The venue's live order book, marks and funding The same
Fills The platform's paper ledger (perps_paper_* tables) The venue program on Solana mainnet
Signing Nothing is built or signed The agent's custodial wallet signs, after simulation
Turned on by Nothing: every agent starts here The owner, signed in, per agent, after signing the real-funds agreements

Paper mode is not a toy. It follows the same rules the venue does, so a paper result means something:

  • A market order fills at the price the venue's own quote walks off the live book, with the taker fee charged.
  • A resting limit fills at its limit price once the live book crosses it.
  • Take-profit and stop-loss triggers fire on the live mark and fill at the mark. A fill is never worse than the order's execution price; for a stop, that is the trigger moved 3% against the position (the stop slippage the venue allows).
  • Funding accrues continuously at the market's live hourly rate. A long pays a positive rate; a short receives it.
  • An account whose equity falls under maintenance margin is liquidated at the mark.
  • Liquidation prices use the venue SDK's own cross-margin formula. tests/perps-desk.test.js checks the paper engine against it.

A paper account can hold up to $1,000,000 of collateral. Deposit some on the desk, then trade.

Live mode needs three things:

  1. The owner turns it on (the Live trading switch on the desk, or PUT .../perps/limits with live_enabled: true from a signed-in session). An API key can never turn it on.
  2. The owner has signed the real-funds agreements. Until then the switch answers risk_ack_required and links to them.
  3. The agent wallet holds USDC to deposit, plus at least 0.003 SOL for network fees.

The first live deposit also opens the agent's trader account on the venue (cross margin, subaccount 0), in the same transaction.


Limits every agent has

Each agent stores its perps policy in agent_identities.meta.perps_limits (api/_lib/perps/limits.js). Every field has a conservative default and a hard ceiling no request can exceed:

Field Default Ceiling What it bounds
live_enabled false Whether live orders are allowed at all
max_leverage 2 20 Account leverage (total notional over equity) after the order. The market's own maximum applies if lower
max_margin_per_position_usd 25 100000 The margin one position ties up at the leverage cap (position notional over the cap)
max_slippage_bps 100 1000 How far a market order may walk the book from the mark
max_quote_move_bps 50 500 How far entry or liquidation may move between preview and execute
max_notional_usd 500 10000000 The largest position notional one order may leave open
min_liquidation_distance_pct 10 The nearest an order may leave the liquidation price to the entry, in percent
mcp_enabled false Whether MCP clients may use this agent's perps_* tools at all (opt-in, owner only)
halted false The perps kill switch. While on, risk-increasing orders are refused
alert_liquidation_distance_pct 15 Alert when a position's mark is within this percent of its liquidation price
alert_loss_usd, alert_gain_usd, alert_funding_usd null (off) Alert on total unrealized PnL, or funding paid by one position

Only the owner, signed in, can loosen a limit. Turning live on, resuming after the kill switch, or raising any cap from an API key or MCP is refused with 403 owner_session_required, and the refusal names the offending keys. Tightening is open to any caller with wallet:write, so an agent can lower its own caps or halt itself.

The guards, in order

Every order preview runs these checks and returns each one with ok and a plain-language label:

  1. Mode: live orders need live_enabled.
  2. Perps halt: halted blocks new risk.
  3. Trade kill switch: the agent-wide switch from the wallet's trade limits.
  4. Wallet freeze: a frozen wallet opens nothing.
  5. Leverage: account leverage after the fill is at most the cap.
  6. Position margin: the position's notional over the leverage cap fits the per-position margin cap.
  7. Free collateral: the account keeps non-negative free collateral after the fill.
  8. Slippage: the walk off the book is within max_slippage_bps.
  9. Notional: the resulting position notional is within max_notional_usd (max_notional_exceeded).
  10. Liquidation distance: the liquidation price stays at least min_liquidation_distance_pct away (liquidation_too_close).

In live mode the preview adds venue checks: on Solana venues the trader account exists and the wallet holds SOL for fees; on Hyperliquid an approved API wallet must be linked (api_wallet_missing). Deposits also run the wallet-wide spend policy (per-transaction and daily USD caps, rules and the anomaly guard).

Checks 2 through 10 apply only to orders that increase risk. A reduce-only order, a take-profit, a stop-loss, a close or a flatten always goes through, so an owner can get out of any position whatever the switches say.


The two-step execute

Nothing changes in one call. Every action is a preview, then an execute:

  1. The preview prices the action, runs every guard and stores exactly what it showed. It returns:
    • a preview_id, valid for 2 minutes for orders or 5 minutes for deposits, withdrawals, cancels and flattens;
    • the numbers: size, entry, margin, account leverage, fees, liquidation price, and the position before and after;
    • checks, blocked_by and executable.
  2. The execute takes that preview_id, confirm_trade: true, and an Idempotency-Key header (idempotency_key in MCP).
    • Before an order executes, it is quoted again. It is refused with 409 quote_moved if entry or liquidation moved past max_quote_move_bps, or if the size changed. The refusal returns the measured move in details. Preview again.
    • A repeated key returns the first result instead of trading twice (perps_executions).
    • A preview is used once.

In live mode, every transaction is simulated against current chain state before it is signed. A simulation that fails, or that would spend more USDC than the preview showed or more than 0.005 SOL in fees and rent, is refused (simulation_failed, simulation_out_of_bounds) and nothing is sent.

BASE=https://three.ws/api/v1/agents/$AGENT_ID/perps

# 1. Preview: long SOL with $20 of margin at 2x, in paper mode
curl -s -X POST $BASE/order/preview -H "authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"mode":"paper","symbol":"SOL","side":"long","type":"market","margin_usd":20,"leverage":2}'

# 2. Execute exactly that preview, once
curl -s -X POST $BASE/order -H "authorization: Bearer $KEY" -H 'content-type: application/json' \
  -H "idempotency-key: $(uuidgen)" \
  -d '{"preview_id":"perp_...","confirm_trade":true}'

Order types

type Required Notes
market size, or margin_usd with leverage Fills now, walking the book up to slippage_bps (default: the agent's max_slippage_bps)
limit price, plus size or margin_usd with leverage Rests on the book. Set reduce_only: true to only shrink a position
take_profit trigger_price, optional size_percent (default 100) Attaches to the open position, always reduce-only. Must trigger on the profitable side of the mark
stop_loss trigger_price, optional size_percent As above, on the losing side. Fills at most 3% past the trigger

size is in base units of the market (0.5 on SOL is half a SOL). side is long or short. To close a position, place a market order on the opposite side with reduce_only: true; the desk's Close button does exactly that.


The kill switch

flatten is the agent's perps kill switch. One preview, one confirmation, then it:

  1. sets halted: true, so no new risk can open;
  2. cancels every resting order and trigger;
  3. closes every position at market (reduce-only).

The result lists each step with its signature (live) or fill (paper). Only the owner, signed in, can resume: the Resume trading button on the desk, or PUT .../perps/limits with halted: false from a session.


The live tracker and alerts

GET /api/v1/agents/:id/perps/stream?mode=paper&interval=4 is a server-sent event stream. Each frame event carries:

  • the account summary;
  • per position: unrealized PnL, funding paid since open, mark, liquidation price and distance to liquidation in percent, and any attached take-profit or stop-loss;
  • the open order count and the alerts crossed right now.

interval is 2 to 30 seconds. A stream lasts five minutes, then sends reconnect, and the page reconnects on its own.

Alerts are evaluated on every frame and, while nobody is watching, by the cron /api/cron/perps-tick every two minutes. Each crossing is recorded once per kind, symbol and hour (perps_alert_events) and sent to the owner as a perps_alert notification. The notification preferences route it to the bell, push and paired chats under Market alerts.

Kind Fires when Severity
liquidation_distance a position's mark is within alert_liquidation_distance_pct of liquidation warning, critical at half the threshold
liquidatable equity is under maintenance margin critical
loss / gain total unrealized PnL crosses the threshold warning / info
funding one position has paid at least alert_funding_usd in funding warning

The same cron keeps paper desks honest while you are away: it settles funding, fills limits the live book crossed, fires triggers the mark reached, and liquidates paper accounts under maintenance. For live agents it only reads the venue account. It never builds or signs a transaction.


REST reference

All routes live under /api/v1/agents/:id/perps in the standard v1 envelope ({ ok, data } or { ok: false, error: { code, message, details } }). Every route takes an optional venue (phoenix, jupiter or hyperliquid; default phoenix). An unpinned /markets read fails over to another healthy venue if the default is down; a pinned read, and every live order, never reroutes. Agent routes take mode (paper or live, default: live if enabled, else paper).

Method Path Auth What it does
GET /markets public Every market: mark, funding, open interest, max leverage, margin rates, fees
GET /market/:symbol public One market with its book (depth), recent trades (trades) and funding history (funding hours); 0 skips trades or funding
GET /account wallet:read Mode, wallet balances, limits, guards, summary, the full account and current alerts
GET /positions wallet:read Positions, resting orders, triggers and history (paper fills or live executions)
GET /executions wallet:read Every execute this platform ran for the agent, with signatures
GET /alerts wallet:read Alerts delivered recently
GET /stream wallet:read The live tracker (server-sent events)
GET /venues public Every venue with its chain, execution kind and capabilities
GET / PUT / DELETE /hyperliquid wallet:read / session Status, link (mints the API wallet) or unlink Hyperliquid
GET / PUT /limits wallet:read / wallet:write Read the policy (with the defaults), or patch it. Loosening needs the owner's session
POST /order/preview, /order wallet:read, wallet:write Preview and execute an order
POST /deposit/preview, /deposit wallet:read, wallet:write Move USDC from the agent wallet into collateral (amount_usd)
POST /withdraw/preview, /withdraw wallet:read, wallet:write Move withdrawable collateral back (amount_usd or "max")
POST /cancel/preview, /cancel wallet:read, wallet:write Cancel a limit, take-profit or stop-loss (order_id, optional kind)
POST /flatten/preview, /flatten wallet:read, wallet:write The kill switch

Common error codes: live_disabled, risk_ack_required, perps_halted, trade_kill_switch, wallet_frozen, leverage_cap_exceeded, position_margin_exceeded, insufficient_collateral, slippage_too_high, quote_moved, confirmation_required, idempotency_key_required, owner_session_required, max_notional_exceeded, liquidation_too_close, api_wallet_missing, mcp_not_enabled, not_supported_on_venue, unknown_venue.


MCP tools

The perps_* tools on /api/mcp-agent are thin adapters over the same service. They are listed in the agent MCP server doc. The perps guided prompt walks a client through account, market, preview and a confirmed execute, and offers the kill switch.


Venues

Three venues are registered. GET /venues returns each one's chain, execution kind and capabilities:

Venue Chain Execution Notes
phoenix Solana instructions On-chain order book. Market, limit, take-profit, stop-loss. The platform compiles, simulates, signs and sends the instructions
jupiter Solana transaction Oracle priced with an impact fee, no book. SOL, BTC and ETH markets, up to 250x on the venue. The venue returns an unsigned transaction that the platform simulates within bounds, signs and submits. Longs post the market token as collateral, shorts post USDC
hyperliquid Hyperliquid (secondary) api_wallet 178 markets. Market and limit orders and cancels. The platform signs an L1 action with a per-agent API wallet. Deposit, withdraw and conditional orders are not supported

Solana leads: Phoenix stays the default. Operations a venue cannot do throw not_supported_on_venue.

Hyperliquid API wallet

  1. PUT /hyperliquid with the owner session and the Hyperliquid account address. The platform generates a key for the agent, stores it sealed in the agent record, and returns the API wallet address.
  2. The owner approves that address at https://app.hyperliquid.xyz/API. An API wallet can trade but can never withdraw.
  3. GET /hyperliquid reports approved once the venue lists the address (extraAgents). Live orders stay blocked with api_wallet_missing until then. DELETE /hyperliquid removes the key.

MCP opt-in

MCP clients see no perps_* tools for an agent until the owner turns mcp_enabled on from a signed-in session. While off, tools/list hides them and calls are refused with mcp_not_enabled. perps_limits stays readable.

Live check

node scripts/perps-venue-probe.mjs reads each venue live (ping, market count, a quote) and runs a Hyperliquid testnet signing check that proves the venue recovers the platform's signer address. Sample on 2026-10-24: Phoenix 99 markets, Jupiter 3, Hyperliquid 178; SOL quotes within 0.1 of each other.

Contract

A venue is a module that implements the contract in api/_lib/perps/index.js (VENUE_CONTRACT):

  • reads: listMarkets, getMarket, getMarketData, getAccount;
  • pricing: quoteOrder;
  • builders: buildDeposit, buildWithdraw, buildOrder, buildCancel, buildFlatten;
  • metadata: chain, execution, capabilities, accountRef, ping.

A venue never signs. It returns instructions, an unsigned transaction or an action, and the service simulates, signs and lands it according to execution. Every registered venue is checked against the contract by tests/perps-desk.test.js, so a second venue is one module and one line in the registry. The paper engine needs nothing venue-specific beyond those reads and quoteOrder.

Venue selection

The launch venue (id phoenix) is a fully on-chain central-limit-order-book perpetuals exchange on Solana. It was chosen on 2026-09-22 because:

  • it publishes a maintained TypeScript SDK;
  • its SOL and BTC markets carry deep open interest;
  • any wallet can open a trader account through its public registration flow, with no invite code.

Every instruction the module builds was verified on mainnet with simulateTransaction, without being sent. The platform trades cross margin on one subaccount per agent, so the guards bound the account's effective leverage rather than a per-order leverage setting.


Testing

tests/perps-desk.test.js covers the parts every mode and interface depends on, without touching a network or a wallet:

  • the venue contract;
  • limit normalization, ceilings and what counts as loosening;
  • every order guard;
  • quote-move tolerance;
  • paper fills (add, partial close, flip, flat), funding, limit crossing and triggers;
  • paper liquidation, against the venue SDK's own formula;
  • alert evaluation and dedupe.

tests/perps-venues.test.js covers the Jupiter and Hyperliquid normalizers, the msgpack encoder against a reference, signature recovery, the new guards and failover. tests/perps-mcp-permission.test.js covers the MCP opt-in.

To exercise the whole flow end to end, use paper mode on a test agent: deposit, preview, execute, attach a take-profit and a stop-loss, then flatten. Never open a live position from a test.