Skip to main content
Start from Choose your integration. Use this when your backend already knows the venue and the amount. POST /execution/orders places one market order on that venue. It does not quote first, and it does not split across venues. To show a price before committing, quote and fill instead. Authenticate with x-app-id and Authorization: Bearer.
Place an order directly. The call returns pending. Statuses after that are on Order lifecycle. maxSpend is the most a buy can be charged, fees included. sellShares bounds how many contracts a sell closes, not the proceeds. Set slipCapBps on a sell when the default 5% cap is too wide.

​
externalId

externalId is required and unique within the app. Two users of the same app cannot share one. Retrying a timeout with the same value is safe: the repeat does not place a second trade. A request rejected before its order was queued, such as on a balance check, does not use up the value, so you can fix the cause and resend with the same externalId. Once the call returns pending the value stays used, even if the order later fails. GET /execution/orders?externalId= also lists the rejected attempt’s order, with status failed. The idempotency table, including the 409 and how to find the order after a timeout, is on Errors.

​
Naming the outcome

Pass the id from venueMarketOutcomes[].id for the venue you named. That is the form that pins the outcome. An id from another venue is resolved through matched outcomes instead of rejected, so a mismatched id can still place an order on the outcome the match selected. If several outcomes on the requested venue match and none is the one you named, the request fails with 400 and code: "outcome_ambiguous". On a sell, that resolution runs over the positions held on the venue, not over every outcome. Read positions first when it matters which one closes.

​
Fee overrides

appFeeBips, appFeeBipsByVenue, referrer, referrerFeeBips, and referrerFeeBipsByVenue override the fee for one order. They need x-app-api-key. For a ...ByVenue map, the entry for venue applies. See Fees. To have a wallet of yours pay Hyperliquid’s activation fee for an unactivated referrer, send referralActivationSponsorAddress. See Fees.

​
Skipping the quote

skipQuote: true skips the route solver and sends the order straight to the venue you named.
  • Venues: predict, hyperliquid, novig, and prophetx only. Any other venue returns 400. An outcome id from another venue is resolved through matched outcomes, as without skipQuote.
  • Requires a read_write x-app-api-key. 401 without a key, 403 with a read key. Do not put that key in a browser.
  • price is optional. It is a 0–1 decimal such as 0.52, not a 6-decimal integer. If you omit it, submission uses the best ask on a buy or the best bid on a sell, and an empty side returns 400. A Hyperliquid buy is sized as the whole contracts that fit maxSpend at price plus slippage.
  • prophetx ignores price. The venue prices the order within slipCapBps. The user needs a KYC-verified wallet, or the call returns 400. See KYC.
  • novig and prophetx settle in USDC on Solana, so a buy needs that USDC already there.
  • Referral fields apply to a buy as they do without skipQuote. On a sell they return 400 referral_invalid: skipQuote sells carry no fees.
  • No bridging. Funds must already sit on the venue’s own chain, in its own token. allowedSourceChainIds and chainBalances are ignored. A buy the user’s stored balance cannot fund returns 400 quote_insufficient_balance before the order is accepted, so its externalId stays free.
  • skipBalance: true together with skipQuote skips the balance check and the fund hold on a buy. Nothing checks the balance, and an underfunded order fails at the venue. skipBalance: true without skipQuote keeps the route and skips only the quote-time balance refresh, so the route uses the last stored balances. The fund hold and the balance check still run. A stale balance can fail the order after it was accepted, and it cannot overspend. Either form requires a read_write key.
  • Sells are always position-checked. skipBalance does not apply to them.
  • You own the price and the minimum checks. An order the venue refuses fails after it was accepted, and that externalId is used up. Retry with a new one.
maxSpend stays the buy ceiling, and the app fee still applies.

​
Reconciling filled orders

executionPrice on GET /execution/orders is the effective filled USD per received/sold share: filledAmountRaw / actualSharesRaw. Both inputs use 6-decimal atomic units, so their scales cancel. The decimal price is truncated to 18 fractional digits. It is null when either quantity is unavailable or invalid, or when the share quantity is zero; it never substitutes the quote. Use this ratio to reconcile the reported cash and share quantities. Fees already reflected in those quantities affect the effective price, so it is not a venue’s pre-fee VWAP. quotedPriceRaw remains the quote reference and averageFillPriceRaw remains the separate limit-order field. An accepted order is not a confirmed fill; reconcile the eventual order status and quantities.