Trading

The four sandbox write endpoints your agent acts through. Every one fills at a fresh mark and returns the resulting position and account. Your real accounts have their own routes; see Live trading.

#Place an order

Open or add to a position. Fills at a fresh single-symbol mark.

Market orders always attempt a fill. A limit order fills only if its price is marketable against the current mark; resting limit orders and Pro orders are not supported in the sandbox. Leverage is re-derived and clamped server-side, so a request cannot raise its own cap.

curl -X POST https://api.perpsfund.com/v1/sandbox/orders \  -H "X-API-Key: $PERPSFUND_API_KEY" \  -H "Content-Type: application/json" \  -d '{"symbol":"BTC","side":"long","size":0.1,"leverage":5}'

{  "ok": true,  "fill": { "price": 64000, "repriced": false, "ageMs": 120 },  "position": {    "symbol": "BTC", "side": "long", "size": 0.1, "leverage": 5,    "entryPrice": 64000, "markPrice": 64000, "notionalValue": 6400,    "marginRequired": 1280, "unrealizedPnL": 0,    "takeProfitPrice": null, "stopLossPrice": null, "openedAt": "2026-07-01T12:00:00.000Z"  },  "account": { "id": "demo", "environment": "sandbox", "balance": 50000, "equity": 50000, "…": "…" }}

#Max slippage

Before a market order opens, the server walks Hyperliquid's live order book for the order's size and compares the average fill price with the book's mid price. If that estimate is above maxSlippagePct, the whole order is rejected and nothing is opened. The rule and the codes are the same in the sandbox and live.

{  "error": "MAX_SLIPPAGE",  "message": "Order rejected: slippage 8.32% exceeds your 8% max.",  "estSlippagePct": 8.3214,  "maxSlippagePct": 8}

Max slippage decides whether the order may open; an accepted order still fills at the fresh mark. A marketable limit is bounded by its own price and is not checked, and closes (/sandbox/positions/close) and take-profit or stop-loss triggers are never limited. If the book cannot be read at that moment, the order proceeds without the check rather than failing.

#What a trade costs

Every fill is charged a fee on notional. Size your trigger levels against it, not against the raw price move.

A market-in, market-out round trip is therefore 9 bps of notional, charged in halves: once when you open and once when you close.

Two things to know before you compute your own PnL:

• fee on a trade row is the round-trip total, not the leg you paid on this fill. It is the open fee plus the close fee for that position.
• realizedPnL is gross; the fee is not already deducted from it. Net PnL for a closed trade is realizedPnL - fee. Reading realizedPnL as net, or subtracting fee twice, are the two independent ways to get this wrong.

#Close a position

Close or partially close at a fresh mark. Omit pct (or pass 100) to fully close; pass 1-99 to partially close.

curl -X POST https://api.perpsfund.com/v1/sandbox/positions/close \  -H "X-API-Key: $PERPSFUND_API_KEY" \  -H "Content-Type: application/json" \  -d '{"symbol":"BTC","pct":50}'

{  "ok": true,  "closed": { "symbol": "BTC", "pct": 50, "exitPrice": 64500, "realizedPnL": 25, "fee": 1.6 },  "position": { "symbol": "BTC", "side": "long", "size": 0.05, "…": "…" },  "account": { "id": "demo", "environment": "sandbox", "…": "…" }}

position is the remaining position after a partial close, or null when fully closed.

#Set take-profit and stop-loss

Set, edit, or clear the trigger levels on an open position. Pass null for a level to clear it. A level you change must sit on the correct side of the current price, not the entry (for a long, the stop below it and the take-profit above it), so a stop at the entry or in profit is valid. A level at or past the current price, or a stop past the take-profit, is rejected with invalid_tpsl, as on live. With no cached price, the changed levels are judged against the entry.

{  "ok": true,  "position": { "symbol": "BTC", "side": "long", "takeProfitPrice": 66000, "stopLossPrice": 62000, "…": "…" }}

#Reset your sandbox

Wipe your demo account back to a fresh starting state. Useful to start a clean run. Only affects your own sandbox.

{ "ok": true, "account": { "id": "demo", "environment": "sandbox", "balance": 50000, "…": "…" } }

curl https://api.perpsfund.com/v1/openapi.json -o perpsfund-openapi.json

Perps Fund sandbox trading endpoints (all POST with a JSON body, header X-API-Key: pk_test_...):
Place / add to a position:POST /sandbox/orders{ "symbol": "BTC", "side": "long", "size": 0.1, "leverage": 5,  "orderType": "market", "takeProfitPrice": 66000, "stopLossPrice": 62000, "expectedPrice": 64100 }-> { ok, fill:{price,repriced,ageMs}, position, account }
Close / partially close:POST /sandbox/positions/close   { "symbol": "BTC", "pct": 50 }   (omit pct = full close)
Change trigger levels on an open position:POST /sandbox/positions/tpsl    { "symbol": "BTC", "takeProfitPrice": 66000, "stopLossPrice": null }
Notes: market orders fill at a fresh mark; limit orders fill only if immediately marketable else order_not_marketable.No resting limits and no Pro orders here: any orderType other than "limit" (for example "scale") is placed as a MARKET order.Leverage clamps to the market's maxLeverage. The sandbox has NO idempotency: do not blindly retry a write, read/sandbox/positions first. (Live routes accept an Idempotency-Key header; the sandbox ignores it.)
ERRORS: an error response has NO "ok" key at all - it is { "error": "<code>", "message": "<text>" } with a 4xx/5xxstatus. Testing 'if response["ok"] is False' therefore NEVER fires. Check the HTTP status, or test for "error".
FEES: taker 4.5 bps per leg, so a market-in/market-out ROUND TRIP costs 9 bps of notional.Size take-profit and stop-loss levels WIDER than that or every outcome loses money. On a closed trade row, "fee" isthe ROUND-TRIP total and "realizedPnL" is GROSS - net PnL is realizedPnL - fee (do not subtract the fee twice).
CLEARING LEVELS: /sandbox/positions/tpsl treats an explicit null as "clear this level", so send ONLY the levels youmean to change. Sending takeProfitPrice: null while setting a stop wipes the take-profit.
TP/SL fire ON TOUCH: levels are evaluated when you call GET /sandbox/account or GET /sandbox/positions, notcontinuously. Polling is what fires your stop. A level fills at the mark at poll time, not at the level, so a gapbetween polls fills worse than the level. A crossing is deferred rather than lost. GET /sandbox/trades reports thecause in orderType: "stop_loss", "take_profit", or "market" (a close you made, a flip, or a drawdown liquidation).