{"uid":"cap_BmaAYpywIGBj4WYuS4-d_","slug":"chainhilt-hyperliquid-perp-order-place-preview-931b11c9","name":"ChainHilt Hyperliquid Perp Order Place Preview","description":"Prepare an order for L1 signing with the configured lowercase builder and fee in tenths of a basis point. Sign and submit unchanged to the returned submitPath. Errors: 400 invalid input, 409 builder approval slots full, 428 builder fee not yet approved (sign the returned approval, then retry), 502 provider failure, 503 builder not configured. Treat spot and perp as one balance only when the account abstraction mode is \"unifiedAccount\".","url":"https://chainhilt.ai/api/v1/perp/hyperliquid/order/place/preview?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","properties":{"nonce":{"type":"integer","minimum":0,"description":"Action nonce in milliseconds since the epoch; defaults to the current time."},"action":{"type":"object","required":["type","orders","grouping"],"properties":{"type":{"type":"string","const":"order","description":"Always \"order\"."},"orders":{"type":"array","items":{"type":"object","required":["a","b","p","s","r","t"],"properties":{"a":{"type":"integer","minimum":0,"description":"Asset ID from /perp/hyperliquid/asset-id: perp index, or 10000 + spot index."},"b":{"type":"boolean","description":"true to buy, false to sell."},"c":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","maxLength":34,"minLength":34,"description":"Client order ID: 128-bit hex string, e.g. 0x1234567890abcdef1234567890abcdef."},"p":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]+)?$","description":"Limit price as a decimal string."},"r":{"type":"boolean","description":"true for reduce-only."},"s":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]+)?$","description":"Size as a decimal string, rounded to the asset's szDecimals."},"t":{"anyOf":[{"type":"object","required":["limit"],"properties":{"limit":{"type":"object","required":["tif"],"properties":{"tif":{"enum":["Gtc","Alo","Ioc"],"type":"string","description":"Alo (post only), Ioc (immediate or cancel) or Gtc (good til canceled)."}},"description":"Limit order.","additionalProperties":false}},"additionalProperties":false},{"type":"object","required":["trigger"],"properties":{"trigger":{"type":"object","required":["isMarket","triggerPx","tpsl"],"properties":{"tpsl":{"enum":["tp","sl"],"type":"string","description":"\"tp\" for take profit, \"sl\" for stop loss."},"isMarket":{"type":"boolean","description":"true to execute as a market order when triggered."},"triggerPx":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]+)?$","description":"Trigger price as a decimal string."}},"description":"Trigger (take profit or stop loss) order.","additionalProperties":false}},"additionalProperties":false}],"description":"Order type: { limit: { tif } } or { trigger: { isMarket, triggerPx, tpsl } }."}},"additionalProperties":false},"minItems":1,"description":"Orders to place, at least one."},"builder":{"type":"object","required":["b","f"],"properties":{"b":{"type":"string","pattern":"^0x[0-9a-f]{40}$","description":"Builder address, lowercase."},"f":{"type":"integer","minimum":0,"description":"Builder fee in tenths of a basis point (10 = 1 bp)."}},"description":"Ignored: preview sets the API's configured builder and fee."},"grouping":{"enum":["na","normalTpsl","positionTpsl"],"type":"string","description":"\"na\" for no grouping, \"normalTpsl\" to tie TP/SL orders to the parent order, or \"positionTpsl\" for position TP/SL."}},"description":"Order action in Hyperliquid wire order; preview adds the builder."},"expiresAfter":{"type":"integer","minimum":0,"description":"Millisecond timestamp after which Hyperliquid rejects the action. Signed with the action."},"vaultAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Vault or subaccount to act for; omit to act for the signer. Signed with the action."},"accountAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"The main account whose builder-fee approval is checked; with an API wallet, its owner, not the API wallet. Returned as response metadata; not part of the signed action."}}},"responseSchema":{"type":"json","example":{"response":{"errors":[],"actions":[{"data":{"nonce":1710000000000,"action":{"type":"order","orders":[{"a":0,"b":true,"p":"60000","r":false,"s":"0.01","t":{"limit":{"tif":"Gtc"}}}],"builder":{"b":"0x2222222222222222222222222222222222222222","f":10},"grouping":"na"},"typedData":{"types":{"Agent":[{"name":"source","type":"string"},{"name":"connectionId","type":"bytes32"}],"EIP712Domain":[{"name":"name","type":"string"},{"name":"version","type":"string"},{"name":"chainId","type":"uint256"},{"name":"verifyingContract","type":"address"}]},"domain":{"name":"Exchange","chainId":1337,"version":"1","verifyingContract":"0x0000000000000000000000000000000000000000"},"message":{"source":"a","connectionId":"0x23b1adacd61decaf45667fc4f52e61174aca749c5d8614e1d725e0108025b732"},"primaryType":"Agent"}},"type":"signature","chainId":42161,"protocol":"hyperliquid","submitPath":"/perp/hyperliquid/order/place/execute"}],"warnings":[],"accountAddress":"0x1111111111111111111111111111111111111111"}}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.01/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_33D2aNEIMnu5NNYj3bDOF","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Prepares a Hyperliquid perpetual or spot order for L1 signing by injecting the configured builder address and fee, returning typed EIP-712 data and a submit path for execution.","exampleAgentPrompt":"Prepare a Hyperliquid perp order preview so I can sign and submit it: buy 0.01 BTC (asset 0) at a limit price of 60000, GTC, non-reduce-only, with client order ID 0x1234567890abcdef1234567890abcdef, using grouping 'na'.","exampleUseCases":[{"title":"Open BTC long with GTC limit","prompt":"Set up a Hyperliquid perp order for me to sign: I want to buy 0.05 BTC (asset ID 0) at a limit price of 65000, good-til-canceled, not reduce-only, client order ID 0xabcdef1234567890abcdef1234567890, grouping 'na'."},{"title":"Place reduce-only ETH sell to close position","prompt":"Prepare a Hyperliquid perp order preview: sell 0.5 ETH (asset ID 1) at 3200 as a reduce-only IOC limit order, client order ID 0x9999999999999999999999999999999a, grouping 'na' — I'll sign and submit the result."},{"title":"Set stop-loss trigger on existing perp position","prompt":"I need a signed order preview for a stop-loss trigger on Hyperliquid: asset 2, sell side, trigger price 2800, execute as market when triggered, size 1.0, not reduce-only, client order ID 0xdeadbeefdeadbeefdeadbeefdeadbeef, grouping 'na'."}],"resultDescription":"Returns an action object with the full order payload (including injected builder address and fee in tenths of a basis point), EIP-712 typed data for L1 signing, the chain ID (42161), protocol identifier ('hyperliquid'), and a submitPath ('/perp/hyperliquid/order/place/execute') to POST the signed result to. Also includes account address, any warnings, and any errors.","failureModes":["400 invalid input — malformed order fields such as bad price/size format or invalid asset ID","409 builder approval slots full — the builder cannot accept new orders at this time","428 builder fee not yet approved — must sign the returned approval object and retry","502 provider failure — upstream Hyperliquid node or RPC is unavailable","503 builder not configured — the chainhilt.ai builder is not set up for this account or environment"],"whenToPreferThis":"Use this endpoint when your agent needs to construct and preview a Hyperliquid perp or spot order with the builder fee already injected before the user signs it — especially in automated workflows where you must present EIP-712 typed data for wallet signing and then separately submit via the returned submitPath. Prefer this over direct Hyperliquid API calls when you want the builder and fee configuration handled automatically without managing API keys.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-11-16T18:38:53.764Z","isFirstParty":false,"canonicalSlug":"chainhilt-hyperliquid-perp-order-place-preview-931b11c9"}