Endpoint
Request Body
action
action.orders[]
The account is derived from the signer; do not add a separate
user field to the action.
Use the exchange signing flow
with the account owner or an approved API wallet. The server generates Notional order IDs;
c and financing are unsupported and explicitly rejected in each order specification.
For Hyperliquid perpetuals, prices use at most 6 - szDecimals decimal places; spot prices use
at most 8 - szDecimals. Non-integer prices additionally use at most five significant figures.
Sizes must respect the market’s szDecimals. Read market metadata before constructing the order.
HIP-3 isolated perpetuals
Send the 16-characterassetId returned by
Market Metadata. HIP-3 orders require assigned
execution (hip3.executionPolicy: "exclusive_subaccount") and a valid execution-account binding.
They support FrontendMarket, Ioc, and resting Gtc/Alo orders. Select leverage through
Update Leverage.
Check Market Trading State for
isolated.permissions before submitting. A market may remain visible while new risk is disabled.
Assigned reduce-only orders use Hyperliquid’s native enforcement on your execution account.
Notional forwards the requested size with venue reduce-only enabled and relays venue acceptance
or rejection. Local position, side, size, aggregate close-capacity, and native minimum-notional
checks do not restrict these orders. You may attempt multiple resting exits or a close larger
than the locally observed position; Hyperliquid decides what can execute.
Local TP/SL intents reserve no close capacity while waiting for their trigger. When triggered,
they use the assigned execution path, including stop-limit TP/SL. An incoming close or triggered
stop does not cancel or trim resting exits to free Notional close capacity. Assignment binding,
authorization, permissions, structural validation, and the tracked TP/SL lifecycle still apply.
Assigned markets do not expose the closeCapacity projection. A missing or invalid HIP-3
assignment is rejected; orders do not fall back to the shared omnibus wallet.
Close capacity
This rule applies to perpetual markets using the shared omnibus wallet. Assignedexclusive_subaccount orders are excluded.
Closing orders are admitted against the market’s free close capacity —
|position| − Σ remaining size of your live closing orders when a live reduce-only order is
present or the incoming live order is reduce-only. Both plain and reduce-only closing orders
count. Local TP/SL intents waiting for a trigger do not reserve this capacity; admission runs
when they trigger and attempt venue submission. A resting close that exceeds capacity is rejected
with code: "CLOSE_CAPACITY_EXCEEDED" and free: "<size>" (the remaining close capacity as a
decimal string).
On native omnibus perpetual markets an immediate reduce-only close (FrontendMarket / Ioc,
or a fired TP/SL) larger than free is accepted instead: it frees only the capacity it needs from
your newest resting closing orders (whole cancellations while needed, and one reduction of the
order it straddles), waits for their outcomes, then submits clamped to what is free; older resting
closes keep resting. While that close is in progress, new closing orders on the market are
rejected with code: "CLOSE_IN_PROGRESS". If no capacity could be freed the close is rejected with
CLOSE_CAPACITY_EXCEEDED and the cancellations already sent are not reversed. Read
closeCapacity.free and closeCapacity.barrierOpen from
Market Trading State.
Automatic Polymarket borrowing
Ordinary authenticated Polymarket buys automatically use owned pUSD first, then borrow the exact reservation shortfall against eligible Notional collateral when pool policy and risk limits allow. The reservation includes the fee/rounding ceiling. No pUSDfinancing object, signed rate policy,
separate borrowing approval, or account opt-in is required. The financing field is rejected on all order requests. Normal order signing, nonce, size, price, and expiry
rules still apply.
Read account pUSD buying power and variable APR from
Asset Balances, not activeAssetData.
Unused funding returned after cancellation repays debt before becoming supplier cash. Order
responses contain execution status; read debt and buying power from balance responses. Historical
origination records remain internal accounting facts.
The pusdFundingVersion event marker is internal and cannot be supplied by clients. Sells,
withdrawals, splits, system actions, and unsupported order types gain no new borrowing permission.
Pool activation, policy, recovery, custody, liquidity, collateral, caps, and release qualification
remain authoritative. Deploy the frontend and API cutover together.
HIP-3 stored cash debt
Orders do not accept afinancing object. Normal margin-financing borrow remains governed by
protocol risk limits. An order that would increase stored cross-account USDC cash debt is rejected;
removing the request field does not grant additional stored-debt authority.
Order type configuration
Limit order config
Gtc rests until filled or canceled, Ioc and FrontendMarket execute immediately and cancel
any remainder, and Alo is post-only.
Trigger order config
Response
response.data.statuses contains exactly one result per input order, in the same order.
Each result carries its Notional oid, including rejected and pending orders. The exchange envelope
resembles Hyperliquid; these result objects use the Notional contract below.
totalSz and avgPx are decimal strings included when authoritative execution evidence is available.
A durable retry can report the current lifecycle without an aggregate fill price. Internal fills also
include executionSource: "internal", matchId, and counterparty. A venue order ID or financing
breakdown is not included.
For standalone batches, handle each result independently. Grouped TP/SL admission remains atomic.
A pending response or transport timeout is not a rejection and must not cause a new signed order to
be submitted automatically. Retrying the identical signed action preserves its original identities;
unrecorded items in a partially committed batch remain unresolved.
Outcome Order from outcomeMarkets
Use the 16-character side AssetId returned by outcomeMarkets:
FrontendMarket market orders and Gtc or Alo limits.
They use whole-share size, require a positive price, and enforce a 10 USDC minimum notional.
The example submits 20 shares at 0.55 USDC, for 11 USDC notional.
Outcome Order from a Token ID
A Polymarket outcome uses a 68-characterPM_Outcome AssetId. For decimal token ID
12345678901234567890, the AssetId is:
s values are outcome shares. p is a probability price and
also the worst acceptable price for immediate orders; never send p: "0".
Additional Time in Force Values
These additional values apply to the 68-character
PM_Outcome AssetId. Gtd expiry must be later
than the signed request nonce and at least four minutes after protocol acceptance. expiresAt is a
Unix-millisecond timestamp, separate from the request-level expiresAfter. No other TIF may
include t.limit.expiresAt.
Token-ID Outcome Validation
groupingmust be"na".- Prices must be within the live market’s
[tickSize, 1 - tickSize]range and exactly tick-aligned. - Prices support at most 8 decimal places. Share sizes support at most 6 and must meet the live minimum order size.
- Reduce-only, triggers, TP/SL, TWAP, and mixed Polymarket/Hyperliquid batches are unsupported.
- Buys reserve canonical pUSD collateral from the user’s
assetsbalance. Sells reserve outcome shares. - If placement is temporarily closed, the request returns an error instead of accepting a non-executable order.