Prepare a perp order

Prepare a perp order

post

Build an unsigned Hyperliquid order for you to sign locally.

This is the first step of the prepare → sign → execute flow. Nothing reaches the exchange until you submit the signed payload to /api/v1/perp/execute, so this call places no order and moves no funds.

Prerequisite: orders are routed with Nansen's builder code, and Hyperliquid rejects them until the wallet has approved a matching fee rate. Check /api/v1/perp/builder-fee first and, if approved is false, run the one-time approval through /api/v1/perp/approve-builder-fee.

What you get back: action (the exchange action), nonce, and eip712 (the typed data to sign). Sign the EIP-712 payload with the wallet's key — the key never leaves your side — then post action, nonce and the resulting {r, s, v} signature to /api/v1/perp/execute exactly as returned. Any edit to action or nonce invalidates the signature. An order may be signed by the wallet's own key or by an API (agent) wallet the wallet has approved. The nonce is a timestamp, so sign and submit promptly rather than caching a prepared payload.

Market vs limit: order_type: "market" turns price into a slippage-adjusted immediate-or-cancel limit, so pass the current mark price and set slippage. For order_type: "limit", price is the limit price and tif applies.

Sizes and prices are rounded to the precision the asset accepts. The size and price fields in the response echo what is actually encoded in the signed action, which can differ from what you sent — show those to the user, not your own inputs.

Bracket orders: setting take_profit and/or stop_loss submits reduce-only trigger orders alongside the entry in one signed action. A take-profit must sit above the entry price for a long (below for a short) and a stop-loss below it (above for a short); the wrong side is rejected with a 422 instead of triggering immediately and closing the position as it opens.

Authorizations

ApiKeyAuth

apikeystringRequired

API key for authentication

Body

application/json

Order to prepare: market or limit, with an optional take-profit / stop-loss bracket.

wallet_addressstringRequired

Wallet address on Hyperliquid

Example: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

coinstringRequired

Asset symbol (e.g. BTC, ETH)

Example: BTC

is_buybooleanRequired

True opens a long, false opens a short

Example: true

sizenumberRequired

Order size in units of the asset itself, not USD. Rounded to the asset's supported precision (sz_decimals from /api/v1/perp/meta); the response echoes the rounded value that is actually signed.

Example: 0.01

pricenumberRequired

For a limit order, the limit price. For a market order, the current mark price — it is adjusted by slippage to produce the immediate-or-cancel limit that is actually submitted.

Example: 65000

order_typestring · enumOptional

limit rests on the book subject to tif; market submits an immediate-or-cancel order priced off price and slippage

Default: limitExample: marketPossible values:

reduce_onlybooleanOptional

When true the order can only shrink an existing position, never open or flip one

Default: false

tifstring · enumOptional

Time-in-force for limit orders (Gtc=good-til-cancel, Ioc=immediate-or-cancel, Alo=add-liquidity-only). Ignored for market orders, which are always immediate-or-cancel.

Default: GtcExample: GtcPossible values:

slippagenumber · max: 0.5Optional

Slippage tolerance for market orders as a fraction, not a percentage (0.03 = 3%). Ignored for limit orders.

Default: 0.03Example: 0.03

take_profitany ofOptional

Optional take-profit trigger price, submitted as a reduce-only trigger order alongside the entry. Must be above price for a long and below it for a short.

Example: 70000

numberOptional

stop_lossany ofOptional

Optional stop-loss trigger price, submitted as a reduce-only trigger order alongside the entry. Must be below price for a long and above it for a short.

Example: 60000

numberOptional

Responses

200

Unsigned EIP-712 payload to sign and submit to /api/v1/perp/execute

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

502

Bad Gateway

application/json

503

Service Unavailable

application/json

504

Gateway Timeout

application/json

post/api/v1/perp/order

HTTPcURLJavaScriptPython

POST /api/v1/perp/order HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 224

{
  "wallet_address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "coin": "BTC",
  "is_buy": true,
  "size": 0.01,
  "price": 65000,
  "order_type": "market",
  "reduce_only": false,
  "tif": "Gtc",
  "slippage": 0.03,
  "take_profit": 70000,
  "stop_loss": 60000
}

{
  "action": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "nonce": 1,
  "vault_address": "text",
  "eip712": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "size": 1,
  "price": 1,
  "ANY_ADDITIONAL_PROPERTY": "anything"
}