Create Trade
Places an order, closes a perpetual position, or deposits to or withdraws from the trading balance, from the Whop-managed wallet of an account or user. Answers 201 with the trade in pending; it runs in the background, so read it with GET /trades/:id until its status is completed, failed or in_review. Trades run alongside each other, except a second order on one market at a different leverage, which answers 409. A retry with the same Idempotency-Key returns the same trade.
Authorizations
An Account API key, an account access token, an account-scoped user token, or a user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************. See Auth & API keys for how to get each one.
Headers
A unique key that makes this request safe to retry. See Idempotent requests.
255"d9105228-4a08-46b1-8b91-42fed586d383"
Pins the request to a dated API version.
"2026-11-04-1"
Body
The account or user whose wallet trades, prefixed biz_ or user_.
"biz_xxxxxxxxxxxxxx"
order places one order. A perpetual order trades from the trading balance, setting cross leverage first; when the balance is short, it bridges the USDT0 it needs from the wallet first. A spot order swaps between USDT0 and the asset in the wallet. deposit bridges amount USDT0 from the wallet to the trading balance. withdraw sends amount USDC (or all) from the trading balance back to the wallet. close closes the whole position in market with a market reduce-only order; when the account is then flat, a withdraw trade sends the trading balance back to the wallet.
close, order, deposit, withdraw "order"
Only for a deposit or withdraw, and required for both. For a deposit, the USDT0 to send from the wallet, with at most 6 decimals. For a withdraw, the USDC to send back, at least 1 with at most 6 decimals, or all.
Only for an order. Your own ID for the trade, 1 to 128 characters, unique for the account. Sending it again with the same order returns the same trade; with a different order it answers 409.
perpetual or spot. Required for an order. A spot order is a market order that swaps in the wallet and does not use the trading balance.
perpetual, spot "perpetual"
Only for a perpetual order. The cross leverage, from 1 to the market's maximum. Required unless reduce_only; not accepted on a reduce-only order.
10
The market: a perpetual such as BTC or xyz:TSLA, or for spot an asset the wallet can swap into, such as BTC or XAUT. Required for an order or close, and a close takes only a perpetual; not accepted for a deposit or withdraw.
"BTC"
Only for an order. Free-form string-to-string annotations: up to 50 keys of at most 40 characters, values up to 500 characters.
Only for an order. The order value in USD, as a decimal string; the size is rounded down to the market's decimals. Send exactly one of size or notional; a spot buy takes notional, the USDT0 to spend.
market fills now within slippage_bps of the mid price, and anything unfilled is canceled; limit fills at price or better, and how long it stays on the book follows time_in_force. take_profit and stop_loss reduce the open perpetual position with a market order once the price crosses trigger_price; the trade stays processing until then. Required for an order.
market, limit, take_profit, stop_loss "market"
Only for an order. The limit price in USD, as a decimal string Hyperliquid accepts without rounding. Required for a limit order; not accepted for a market order.
Only for a perpetual order. Only reduce an open position; defaults to false. A reduce-only order takes no leverage.
buy or sell. Required for an order, except a take_profit or stop_loss, where it defaults to the side that reduces the position.
buy, sell "buy"
Only for an order. The size in units of the market, as a decimal string, with at most the market's size decimals. Send exactly one of size or notional; a spot sell takes size. A perpetual order must be worth at least 10 USD, unless reduce-only. A take_profit or stop_loss takes size or nothing for the whole position, and a set size must be worth at least 10 USD at trigger_price.
"0.001"
Only for a market order or a close. The worst price as basis points from the mid price, from 1 to 1000; defaults to 100 for a perpetual, and to the swap route's own default for spot.
Only for a perpetual order that opens or adds to a position. A stop-loss for the order's full size, armed once the order fills and sent with it as its own trade, whose parent_id is this trade.
Only for a perpetual order that opens or adds to a position. A take-profit for the order's full size, armed once the order fills and sent with it as its own trade, whose parent_id is this trade.
Only for a perpetual limit order. good_til_canceled rests on the book until it fills; add_liquidity_only is canceled instead of filling at once; immediate_or_cancel fills what it can now and cancels the rest. Defaults to good_til_canceled. The trade stays processing while the order rests.
add_liquidity_only, good_til_canceled, immediate_or_cancel "add_liquidity_only"
Required for a take_profit or stop_loss, and only for them. The USD price, as a decimal string Hyperliquid accepts without rounding, at which it sends a market order. Closing a long, a take-profit triggers above the current price and a stop-loss below; closing a short, the reverse. It is always reduce-only, needs an open position, and takes no price, notional, leverage, time_in_force or slippage_bps.
Response
trade created
The account that owns the trading wallet, prefixed biz_. null when a user owns it.
"biz_xxxxxxxxxxxxxx"
The USDT0 that a deposit, a spot buy, or a perpetual order short of trading balance, sends from the wallet, or the USDC that a withdraw sends back, in native units, as a decimal string. A withdraw of all shows what it sent once it finishes. null otherwise.
"25"
The average fill price of the order, in USD, as a decimal string. For spot, the price the swap was quoted at. null when it is not known.
null
The caller's own ID for the trade, unique for the account. null when none was sent.
null
When the trade ended as completed or failed, as an ISO 8601 timestamp. null before that.
null
When the trade was created, as an ISO 8601 timestamp.
"2026-01-01T12:00:00.000Z"
ID Whop sends to the exchange with this trade's order, so the exchange's order updates can be matched to the trade. On Hyperliquid, the order's cloid reported in orderUpdates, a 0x-prefixed 32-character hex string. Not the caller's client_order_id. null for a deposit or withdraw.
"0x63cabad10f072c65ad84526e0c33081b"
Why the trade failed, or null.
market_unavailable, leverage_too_high, amount_too_small, isolated_position_open, trading_paused, funding_failed, margin_unavailable, builder_fee_unapproved, leverage_rejected, leverage_unconfirmed, order_rejected, close_rejected, return_failed, withdraw_failed, null "market_unavailable"
The size the order filled, in units of the market, as a decimal string. For a spot buy, the amount the swap was quoted to deliver. null until it fills.
null
Where the money is when the trade did not complete as asked: wallet, trading_account, or unknown while a person checks it. null otherwise.
wallet, trading_account, unknown, null "wallet"
Trade ID, prefixed tint_.
"tint_xxxxxxxxxxxxxx"
perpetual or spot for an order, perpetual for a close. null for a deposit or withdraw.
perpetual, spot, null "perpetual"
The cross leverage set before an opening perpetual order. null for a spot order, close, deposit, withdraw or reduce-only order.
10
The market, for example BTC for a perpetual or XAUT for spot. null for a deposit or withdraw.
"BTC"
Free-form string-to-string annotations stored on the trade.
trade "trade"
market, limit, take_profit or stop_loss for an order. null otherwise.
market, limit, take_profit, stop_loss, null "market"
For a take-profit or stop-loss sent with an order, that order's trade, prefixed tint_. null otherwise.
null
The limit price of the order in USD. A market order's price is the mid price moved by slippage_bps; a take-profit or stop-loss's is the worst price its market order may fill at once triggered. null for other types.
Whether the order can only reduce a position. null for other types.
null
buy or sell for an order. null otherwise.
buy, sell, null "buy"
The order size in units of the market, as a decimal string. null for other types.
null
pending until the trade starts. processing while it runs, also while an order that did not fill sends the money it bridged in back to the wallet. completed when it did what was asked. failed when it did not; funds_location says where the money is. in_review when the outcome is unknown and a person checks it.
pending, processing, in_review, completed, failed "pending"
partial_fill when the order filled only part of its size. null otherwise.
partial_fill, null "partial_fill"
What a live trade is doing now: depositing while the wallet's USDT0 is being sent to the bridge, landing once sent and until it reaches the trading balance, placing while the order or close is with the venue, withdrawing while USDC heads back to the wallet, returning while money an unfilled order bridged in goes back. A spot order is quoting while the swap is priced, swapping while it runs onchain, and crediting until the new balance shows in the wallet. null once the trade is no longer pending or processing.
depositing, landing, placing, withdrawing, returning, quoting, swapping, crediting, null "placing"
The price in USD at which a take-profit or stop-loss sends its market order. null for other orders and types.
order places one order: a perpetual order trades from the trading balance, a spot order swaps between USDT0 and the asset in the wallet. deposit bridges USDT0 from the wallet to the trading balance. withdraw sends USDC from the trading balance back to the wallet. close closes the whole position in one market with a market reduce-only order; when the account is then flat, a withdraw trade sends the trading balance back to the wallet.
close, order, deposit, withdraw "order"
When the trade last changed, as an ISO 8601 timestamp.
"2026-01-01T12:00:00.000Z"
The user who owns the trading wallet, prefixed user_. null when an account owns it.
null