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. 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. The outcome must already live on venue. It is not resolved through matched outcomes.
  • 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 with skipQuote return 400 referral_invalid.
  • No bridging. Funds must already sit on the venue’s own chain. allowedSourceChainIds and chainBalances are ignored.
  • 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.