API ReferenceExecution
Build a bounded order or redemption intent
const url = 'https://exec.predictefy.com/v1/exec/hyperliquid/orders/build';const options = { method: 'POST', headers: { 'Idempotency-Key': 'example', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"dryRun":true,"outcome":"42","outcomeSide":"YES","isBuy":true,"price":0.52,"size":10,"owner":"0x1111111111111111111111111111111111111111"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://exec.predictefy.com/v1/exec/hyperliquid/orders/build \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: example' \ --data '{ "dryRun": true, "outcome": "42", "outcomeSide": "YES", "isBuy": true, "price": 0.52, "size": 10, "owner": "0x1111111111111111111111111111111111111111" }'Requires Authorization: Bearer <api-key> with the trade scope and a unique
Idempotency-Key. Returns a persisted authless or unsigned venue-shaped artifact for
the venue-specific submit step. Client-signing lanes return an unsigned artifact;
Gemini returns the exact order body that submit authenticates once with the caller's
transient HMAC key.
Set dryRun: true to run the same authentication, catalog market resolution, artifact
construction, and fail-closed bounds checks, then return the complete preview without
inserting an execution.executions row or reserving spend capacity. The header remains
required for the route contract, but a dry run never looks up, replays, or binds its
Idempotency-Key.
intent defaults to order; redeem is accepted only on settlement-capable lanes.
The body is venue-specific and is validated by the selected lane. An empty object is
not a valid build request: callers must supply every property required by the selected
venue lane, even though no top-level property is universal across order, redemption,
and legacy echoed-artifact variants.
Required fields vary by venue. owner is required by Hyperliquid, Limitless, Opinion,
Polymarket, Predict.fun, Pascal, XO, PRED, Rain, Myriad, and PredictStreet; Kalshi,
Polymarket US, Gemini, and Novig do not use it for order builds.
Per venue:
- Polymarket, Opinion and Predict.fun accept plain
outcome+outcomeSideorasset,isBuy,price,size, andowner; each lane also preserves its legacy echoedbuildResult. Polymarket's Proxy/Safe signature types additionally require their distinctfunder, and Opinion's Safe mode requiressafeAddress. - XO accepts the same plain selectors.
owneris the XO smart account for the defaultsignatureType: 3, or the direct EOA for explicitsignatureType: 0; the POLY proxy types 1 and 2 are rejected. XO has no legacy echo. - Gemini accepts the same catalog selector plus
isBuy,price, andsize, derivessymboland YES/NO from the catalog, and supports documented limit orders only. Its lane is default-off behindGEMINI_EXECUTION_ENABLED=true. - PRED accepts the same market selector,
isBuy,price, andsize, withowneras the Gnosis Safe andsigneras its controlling EOA; it resolves the parent-specific exchange from catalog truth and has no legacy echo. - Pascal accepts catalog
market, normalizedside,isBuy, price/size, walletowner, and trading-keysigner; it returns the exact unsigned binary permit and hex message, never a Solana transaction. - Polymarket US accepts normalized
marketId,outcomeId,side,type,amount, andprice, resolves its bare slug plus{slug}:long|shortoutcome through the catalog, and persists the exact authless REST body;keyIdandsecretKeyare not accepted during build. - Kalshi is default-off behind
KALSHI_EXECUTION_ENABLED=true. It accepts catalogoutcomeplus optionaloutcomeSide,isBuy, an exact whole-cent probabilityprice, a positive whole-contractsize, and optionaltimeInForce: good-til-cancel. The server resolves the ticker and binary side from catalog truth and returns an authless order body with UUIDv4client_order_id,side: bid|ask, fixed-pointcount/price,time_in_force: good_till_canceled, andself_trade_prevention_type: taker_at_cross; caller credentials are not accepted at build. - Rain resolves the pool Diamond from the Core catalog and source-verifies its
deployer plus per-pool facet routes before returning calldata. Its standard path is
action: limit(or omitted): BUY uses base-tokenamount, while SELL usesshares.action: marketis opt-in and requires nonzeroslippageBpsplusdeadlineSecondsFromNow; the server derives a nonzero minimum from a block-pinned live quote and encodes an absolute deadline from that Arbitrum block.
Server-built artifacts carry a venue-specific integer buildVersion; an incompatible
persisted artifact returns a typed 409 and must be rebuilt with a fresh
Idempotency-Key.
Successful order builds for a lane with a known hosted-relay egress block include a
top-level warnings array before the caller funds or signs. The build remains allowed
so clients with their own venue-submit path can continue. Hyperliquid builds also make
a fail-open spotClearinghouseState read: when spendable spot USDC is below order
notional, the same array names the shortfall and points to
POST /v1/funding/hyperliquid/steps. A failed balance read omits that advisory and never
blocks the order build.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Execution venue slug. Availability is deployment-specific; discover armed lanes with GET /v1/exec/venues. Settlement-only lanes may appear but report order verbs false.
Header Parameters
Section titled “Header Parameters”Caller-generated non-empty key. Build/cancel/modify keys identify newly persisted intents; a submit key identifies that relay attempt and cannot be rebound to another ID. The literal strings undefined and null are rejected with 400 VALIDATION_ERROR, so a client that stringified a missing key cannot bind or replay one. Two prefixes are RESERVED by the execution service for keys it mints itself and are rejected with 400 RESERVED_IDEMPOTENCY_KEY before anything is written: cond: (a hosted conditional order's own fire key) and dry-run: (the preview key handed to a venue lane). The match is case-sensitive.
Request Bodyrequired
Section titled “Request Bodyrequired”Plain Polymarket limit-order intent.
With no order object, Predictefy resolves the CLOB token through its catalog, requires
live CLOB GET /version to return exactly 2, and reads the current tick, operator-set fee
details, and token-bound NegRisk truth from the live condition market. It requires the CLOB
NegRisk flag to agree with Gamma, selects the V2 exchange, and returns complete unsigned
EIP-712 typed data.
assetis a catalog outcome/token id.outcomeis a catalog market id selected byoutcomeSide.
Private keys and venue credentials are never accepted by this build shape.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Catalog outcome id / Polymarket CLOB token id.
Catalog market id; pair with outcomeSide to resolve its token.
Probability dollars in (0,1), additionally bounded by the live CLOB tick.
Outcome shares; the CLOB rounds down to its two-decimal size precision.
Controlling EOA signer and CLOB POLY_ADDRESS identity. For signature type 0 it is also the maker.
Inventory-holding Proxy/Safe maker. Required and different from owner for signature types 1/2; for type 0 it must be absent or equal to owner.
0 EOA (maker = signer = owner), 1 Polymarket Proxy, or 2 Polymarket Gnosis Safe verification (types 1/2 use maker = funder and signer = owner).
Wire-only Unix seconds. 0 builds GTC; a positive value builds GTD.
Signed CLOB V2 metadata; defaults to zero bytes32.
Signed CLOB V2 builder code; defaults to zero bytes32.
Plain Polymarket limit-order intent.
With no order object, Predictefy resolves the CLOB token through its catalog, requires
live CLOB GET /version to return exactly 2, and reads the current tick, operator-set fee
details, and token-bound NegRisk truth from the live condition market. It requires the CLOB
NegRisk flag to agree with Gamma, selects the V2 exchange, and returns complete unsigned
EIP-712 typed data.
assetis a catalog outcome/token id.outcomeis a catalog market id selected byoutcomeSide.
Private keys and venue credentials are never accepted by this build shape.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Catalog outcome id / Polymarket CLOB token id.
Catalog market id; pair with outcomeSide to resolve its token.
Probability dollars in (0,1), additionally bounded by the live CLOB tick.
Outcome shares; the CLOB rounds down to its two-decimal size precision.
Controlling EOA signer and CLOB POLY_ADDRESS identity. For signature type 0 it is also the maker.
Inventory-holding Proxy/Safe maker. Required and different from owner for signature types 1/2; for type 0 it must be absent or equal to owner.
0 EOA (maker = signer = owner), 1 Polymarket Proxy, or 2 Polymarket Gnosis Safe verification (types 1/2 use maker = funder and signer = owner).
Wire-only Unix seconds. 0 builds GTC; a positive value builds GTD.
Signed CLOB V2 metadata; defaults to zero bytes32.
Signed CLOB V2 builder code; defaults to zero bytes32.
Normalized Polymarket US limit-order intent. The lane is default-off unless
POLYMARKET_US_EXECUTION_ENABLED=true.
Predictefy resolves outcomeId through its catalog and requires the stored native
identities to be the bare marketId slug and exactly {marketId}:long|short. From
server-owned catalog metadata it then:
- reads the market's
orderPriceMinTickSizeandminimumTradeQty; - rounds the caller-facing outcome price to that tick;
- requires quantity to meet and align to that minimum;
- converts short prices to the venue's long-side quote;
- persists the exact
POST /v1/ordersbody plus those rules withbuildVersion: 1.
Missing or unsupported catalog rules fail closed. keyId and secretKey are accepted only
at submit/refresh, never in this build or its persisted artifact.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Bare Polymarket US market slug; must match the catalog market.
Catalog outcome id, exactly {marketId}:long or {marketId}:short.
Market orders remain unsupported because their official shape is cash-sized.
Contract quantity sent as quantity, never cashOrderQty; must meet and align to the catalog market's minimumTradeQty.
Caller-facing outcome price; rounded to the catalog market's orderPriceMinTickSize.
Plain Opinion LIMIT-order intent. Predictefy binds the selected catalog token to Opinion's
exact market lookup, resolves that market's quote-token exchange and decimals, and returns
complete OPINION CTF Exchange v1 typed data on BSC 56.
- Signature type 0 — plain EOA (
maker == signer == owner). - Signature type 2 — requires
safeAddress; the Safe is the funds-holding maker andowneris its controlling EOA signer.
No signing key or venue credential is accepted.
The returned typed-data envelope carries buildVersion: 1; replaying or submitting a
server-built envelope with a missing or incompatible version returns typed
409 ARTIFACT_VERSION_CONFLICT. Legacy echoed artifacts have no envelope or version marker
and retain their existing behavior.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Catalog outcome id / Opinion CTF token id.
Catalog market id; pair with outcomeSide to resolve its token.
Probability dollars that round inside Opinion's 0.000001–0.999999 range.
Outcome shares, converted with the market quote token's decimals.
Controlling EOA signer; also the maker in signature type 0.
0 for EOA or 2 for Opinion Safe verification.
Required only for signature type 2; this funds-holding Safe becomes maker.
Unix seconds. 0 has no expiration; a positive value is GTD.
Specific taker, or the zero address for a public order.
Plain Opinion LIMIT-order intent. Predictefy binds the selected catalog token to Opinion's
exact market lookup, resolves that market's quote-token exchange and decimals, and returns
complete OPINION CTF Exchange v1 typed data on BSC 56.
- Signature type 0 — plain EOA (
maker == signer == owner). - Signature type 2 — requires
safeAddress; the Safe is the funds-holding maker andowneris its controlling EOA signer.
No signing key or venue credential is accepted.
The returned typed-data envelope carries buildVersion: 1; replaying or submitting a
server-built envelope with a missing or incompatible version returns typed
409 ARTIFACT_VERSION_CONFLICT. Legacy echoed artifacts have no envelope or version marker
and retain their existing behavior.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Catalog outcome id / Opinion CTF token id.
Catalog market id; pair with outcomeSide to resolve its token.
Probability dollars that round inside Opinion's 0.000001–0.999999 range.
Outcome shares, converted with the market quote token's decimals.
Controlling EOA signer; also the maker in signature type 0.
0 for EOA or 2 for Opinion Safe verification.
Required only for signature type 2; this funds-holding Safe becomes maker.
Unix seconds. 0 has no expiration; a positive value is GTD.
Specific taker, or the zero address for a public order.
Plain Predict.fun LIMIT-order intent. Predictefy binds the selected catalog token to
Predict.fun's exact market lookup, reads its fee plus NegRisk/yield-bearing type, maps that
type to the authoritative BSC exchange, and returns complete predict.fun CTF Exchange v1
typed data.
This variant is EOA-only: maker == signer == owner and signature type is 0. No signing
key, session bearer, or other venue credential is accepted during build.
The returned typed-data envelope carries buildVersion: 1; replaying or submitting a
server-built envelope with a missing or incompatible version returns typed
409 ARTIFACT_VERSION_CONFLICT. Legacy echoed artifacts have no envelope or version marker
and retain their existing behavior.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Catalog outcome id / Predict.fun on-chain token id.
Catalog market id; pair with outcomeSide to resolve its token.
Probability dollars in (0,1), truncated to the SDK's 3 significant digits.
Outcome shares, truncated to the SDK's 5 significant digits.
EOA that remains both maker and signer; signing stays client-side.
Unix seconds in the future. Omission uses the venue SDK's 2100-01-01 no-expiry sentinel.
Specific taker, or the zero address for a public order.
Plain Predict.fun LIMIT-order intent. Predictefy binds the selected catalog token to
Predict.fun's exact market lookup, reads its fee plus NegRisk/yield-bearing type, maps that
type to the authoritative BSC exchange, and returns complete predict.fun CTF Exchange v1
typed data.
This variant is EOA-only: maker == signer == owner and signature type is 0. No signing
key, session bearer, or other venue credential is accepted during build.
The returned typed-data envelope carries buildVersion: 1; replaying or submitting a
server-built envelope with a missing or incompatible version returns typed
409 ARTIFACT_VERSION_CONFLICT. Legacy echoed artifacts have no envelope or version marker
and retain their existing behavior.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Catalog outcome id / Predict.fun on-chain token id.
Catalog market id; pair with outcomeSide to resolve its token.
Probability dollars in (0,1), truncated to the SDK's 3 significant digits.
Outcome shares, truncated to the SDK's 5 significant digits.
EOA that remains both maker and signer; signing stays client-side.
Unix seconds in the future. Omission uses the venue SDK's 2100-01-01 no-expiry sentinel.
Specific taker, or the zero address for a public order.
Plain Pascal limit-order intent.
Predictefy resolves market through its catalog, derives the native symbol, tick, taker
fee, client order id, timestamp, and receive window, then returns the exact
production-deployment-3 232-byte permit as base64 permit and hex message.
sideis the normalized YES/NO outcome view;isBuymaps it to the venue's BID/ASK and complement price.- The client signs
messagebytes with its Ed25519 trading key; neither a private key nor a signature is accepted at build. - Artifacts pin permit version 1, the offchain-fields digest, and wire layout.
The lane is ARMED in production — the owner set PASCAL_TRADE_ENABLED=true on 2026-08-12
and /v1/exec/venues served it among the armed hosted lanes; the former "source-ready but
absent unless armed" note was stale.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Core Pascal catalog market id; the native symbol is server-resolved.
Normalized contract view. NO uses the exact native complement.
Probability dollars in (0,1), at most 6dp, aligned to the venue tick at that price: max(10^(floor(log10(p')) + 1 - tick_sig_figs), tick_size_min) where p' = min(p, 1 - p). Off-tick prices are refused at build, not upstream after signing.
Positive whole-contract u64 quantity.
Custody wallet public key. Its private key never enters this order flow.
Revocable, non-withdrawal Ed25519 trading-key public key. Never defaulted from owner; an account whose wallet is its own signing key names that wallet here.
Future Unix milliseconds; required for GTT and forbidden otherwise.
Plain XO limit-order intent for chain 3223.
Predictefy first resolves asset, or outcome + outcomeSide, through the indexed
catalog and signs the resulting XO token id verbatim. It then reads the public CLOB tick
and signed base_fee, rejects fees above the deployed 800 bps cap, and returns the
current 13-field EIP-712 envelope with buildVersion: 2 for domain XO Market CLOB
version 1 at 0x4bC5E872256D12E6017dfe466E04c867DC761B77.
- Signature type 3 is the default for an XO smart account (
maker == signer, ERC-1271); direct EOA integrations may explicitly request type 0. POLY proxy types 1 and 2 are rejected because XO documents no identity for them. - Private keys and venue credentials are never accepted by this build shape.
- Registration remains fail-closed behind the verified exchange allowlist. The production lane is rebuilt and armed; first live credentialed submit remains the confirmation point.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Catalog outcome id and XO signed tokenId (no translation).
Catalog market id; pair with outcomeSide to select the signed tokenId.
Probability dollars in (0,1), additionally bounded by the live XO tick.
Outcome shares; rounded with the deployed CLOB precision rules.
XO smart account for signature type 3, or direct EOA for type 0. The client signs; Predictefy never holds its key.
Type 3 is the default XO smart-account/ERC-1271 model; type 0 is the venue-documented direct-EOA path. Types 1 and 2 are rejected.
Unix SECONDS. An explicit 0 builds a never-expiring GTC order; a future value builds GTD and must be within two years (a millisecond stamp is rejected, not signed). OMITTING it no longer means GTC: the order expires at the catalog market's close date when the row carries a future one, bounded by the same two-year horizon, so a resting order cannot outlive its own market. With no usable close date, an omitted value still builds GTC.
Plain XO limit-order intent for chain 3223.
Predictefy first resolves asset, or outcome + outcomeSide, through the indexed
catalog and signs the resulting XO token id verbatim. It then reads the public CLOB tick
and signed base_fee, rejects fees above the deployed 800 bps cap, and returns the
current 13-field EIP-712 envelope with buildVersion: 2 for domain XO Market CLOB
version 1 at 0x4bC5E872256D12E6017dfe466E04c867DC761B77.
- Signature type 3 is the default for an XO smart account (
maker == signer, ERC-1271); direct EOA integrations may explicitly request type 0. POLY proxy types 1 and 2 are rejected because XO documents no identity for them. - Private keys and venue credentials are never accepted by this build shape.
- Registration remains fail-closed behind the verified exchange allowlist. The production lane is rebuilt and armed; first live credentialed submit remains the confirmation point.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Catalog outcome id and XO signed tokenId (no translation).
Catalog market id; pair with outcomeSide to select the signed tokenId.
Probability dollars in (0,1), additionally bounded by the live XO tick.
Outcome shares; rounded with the deployed CLOB precision rules.
XO smart account for signature type 3, or direct EOA for type 0. The client signs; Predictefy never holds its key.
Type 3 is the default XO smart-account/ERC-1271 model; type 0 is the venue-documented direct-EOA path. Types 1 and 2 are rejected.
Unix SECONDS. An explicit 0 builds a never-expiring GTC order; a future value builds GTD and must be within two years (a millisecond stamp is rejected, not signed). OMITTING it no longer means GTC: the order expires at the catalog market's close date when the row carries a future one, bounded by the same two-year horizon, so a resting order cannot outlive its own market. With no usable close date, an omitted value still builds GTC.
Plain PredictStreet limit-order intent for ADI Chain 36900.
Predictefy resolves asset, or outcome + outcomeSide, through the catalog, then
rechecks the live condition id, token id, open/tradable state, taker fee, and NegRisk flag.
It resolves the caller's funds-holding vault through the verified VaultFactory and selects
the binary exchange 0x90EA87493E208A14011EC700Ac9cbAf4d064acc0 or NegRisk exchange
0x79ACbb874dd01044FA38a89c1478E60FaAB40D00 without silently crossing market types.
The result is the complete 11-field VAULT order for EIP-712 domain PredictStreet version
1, carries buildVersion: 1, and pins six-decimal USDC.e amount math.
- The lane is source-ready but default-off: an empty or unknown-only
PREDICTSTREET_EXCHANGE_ADDRESSESleaves it unregistered. - Build accepts no venue credential or signing material.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
PredictStreet native token id (the catalog native outcome id).
Catalog market symbol; pair with outcomeSide to resolve its token.
Probability dollars on the verified 0.01 tick, from 0.01 through 0.99.
Outcome shares with at most six decimal places.
EOA signer whose caller-specific vault becomes the order maker.
PredictStreet VAULT signature mode only.
Unix seconds. 0 builds GTC; a future value builds GTD.
Relayed unchanged with the server-stored order.
Plain PredictStreet limit-order intent for ADI Chain 36900.
Predictefy resolves asset, or outcome + outcomeSide, through the catalog, then
rechecks the live condition id, token id, open/tradable state, taker fee, and NegRisk flag.
It resolves the caller's funds-holding vault through the verified VaultFactory and selects
the binary exchange 0x90EA87493E208A14011EC700Ac9cbAf4d064acc0 or NegRisk exchange
0x79ACbb874dd01044FA38a89c1478E60FaAB40D00 without silently crossing market types.
The result is the complete 11-field VAULT order for EIP-712 domain PredictStreet version
1, carries buildVersion: 1, and pins six-decimal USDC.e amount math.
- The lane is source-ready but default-off: an empty or unknown-only
PREDICTSTREET_EXCHANGE_ADDRESSESleaves it unregistered. - Build accepts no venue credential or signing material.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
PredictStreet native token id (the catalog native outcome id).
Catalog market symbol; pair with outcomeSide to resolve its token.
Probability dollars on the verified 0.01 tick, from 0.01 through 0.99.
Outcome shares with at most six decimal places.
EOA signer whose caller-specific vault becomes the order maker.
PredictStreet VAULT signature mode only.
Unix seconds. 0 builds GTC; a future value builds GTD.
Relayed unchanged with the server-stored order.
Plain Gemini prediction-market LIMIT-order intent. The lane is default-off until
GEMINI_EXECUTION_ENABLED=true.
Predictefy resolves asset, or outcome + outcomeSide, through the Core catalog and
derives the exact instrument symbol and yes/no outcome; callers cannot supply either
venue field directly. Build persists the exact venue body with buildVersion: 1, no
headers and no credentials.
Submit requires the caller's own Gemini apiKey + apiSecret, constructs the documented
base64 payload and HMAC-SHA384 headers in-process, relays once, and discards them. The key
must:
- have the Trader role;
- enable
Uses a time based nonce; - disable
Requires Heartbeat.
Terms acceptance is a caller-owned one-time prerequisite. Trading keys also require trusted-IP configuration; this service has no pinned egress, so callers choosing Unrestricted accept its reduced IP-layer protection. Limit orders are supported; stop-limit is not.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Core Gemini outcome id (GEMI:{eventTicker}:{instrumentSymbol}:{yes|no}).
Core Gemini market id; pair with outcomeSide to resolve the catalog outcome.
Maps to Gemini private-REST side buy or sell.
Limit price in probability dollars, emitted as Gemini's decimal string. Must align with the instrument-specific priceIncrement and priceMinimum published by Gemini.
Contract quantity, emitted as Gemini's decimal string. Must align with the instrument-specific quantityIncrement and quantityMinimum published by Gemini.
When true, Gemini cancels instead of taking resting liquidity.
Plain Gemini prediction-market LIMIT-order intent. The lane is default-off until
GEMINI_EXECUTION_ENABLED=true.
Predictefy resolves asset, or outcome + outcomeSide, through the Core catalog and
derives the exact instrument symbol and yes/no outcome; callers cannot supply either
venue field directly. Build persists the exact venue body with buildVersion: 1, no
headers and no credentials.
Submit requires the caller's own Gemini apiKey + apiSecret, constructs the documented
base64 payload and HMAC-SHA384 headers in-process, relays once, and discards them. The key
must:
- have the Trader role;
- enable
Uses a time based nonce; - disable
Requires Heartbeat.
Terms acceptance is a caller-owned one-time prerequisite. Trading keys also require trusted-IP configuration; this service has no pinned egress, so callers choosing Unrestricted accept its reduced IP-layer protection. Limit orders are supported; stop-limit is not.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Core Gemini outcome id (GEMI:{eventTicker}:{instrumentSymbol}:{yes|no}).
Core Gemini market id; pair with outcomeSide to resolve the catalog outcome.
Maps to Gemini private-REST side buy or sell.
Limit price in probability dollars, emitted as Gemini's decimal string. Must align with the instrument-specific priceIncrement and priceMinimum published by Gemini.
Contract quantity, emitted as Gemini's decimal string. Must align with the instrument-specific quantityIncrement and quantityMinimum published by Gemini.
When true, Gemini cancels instead of taking resting liquidity.
Official Kalshi V2 order intent. outcome is either a Core market id paired with outcomeSide, or a direct Core outcome id whose catalog-stamped side is authoritative. Predictefy resolves the native ticker and returns KalshiOrderArtifact; no Kalshi API credential is accepted during build.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Buy or sell the normalized catalog outcome; the server maps it to bid/ask.
Exact whole-cent probability in dollars.
Positive whole-contract count.
Forwarded as Kalshi's reduce_only: the venue caps the placed count at the member's current position, so fewer contracts than requested may rest or fill. Omitted or false builds the ordinary seven-field artifact.
Plain PRED limit-order intent on Base chain 8453.
Predictefy resolves asset, or outcome plus outcomeSide, through the indexed catalog.
The child bytes32 market id becomes the signed questionId; catalog metadata supplies the
parent market id, and the promoted parent_market_data.contract_address becomes the
EIP-712 verifying contract. That address must also appear in the operator's
PRED_EXCHANGE_ADDRESSES allowlist — empty means the lane is default-off and unregistered.
The server then:
- maps normalized Long/Short buy/sell direction to PRED intent 0/1;
- scales price and quantity to 1e6;
- generates the
02+ 10-digit salt; - fixes feeRateBps to the published zero rate and signatureType to Safe proxy 2;
- returns the complete
Pred CTF Exchangeversion1envelope withbuildVersion: 1.
owner is the funds-holding Gnosis Safe; signer is its distinct controlling EOA. Private
keys, salts, signatures, API keys, and JWTs are rejected during build.
PRED restricts users in the US, UK, France, Ontario, Singapore, Poland, Thailand, and Taiwan and prohibits location masking; eligibility and enforcement remain the operator/compliance responsibility.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Catalog PRED outcome id ({bytes32 child market id}#0 Long or #1 Short).
Catalog child market id; pair with outcomeSide to choose Long or Short.
Buy or sell the selected normalized outcome; the server derives PRED intent.
Selected-outcome probability in (0,1); Short selection is complemented for signing.
Shares, minimum 5 and at most one decimal place.
Funds-holding PRED Gnosis Safe proxy (signed maker).
EOA controlling the Safe and signing the returned digest; must differ from owner.
Unix seconds. 0 builds GTC; a future value builds GTD.
Plain PRED limit-order intent on Base chain 8453.
Predictefy resolves asset, or outcome plus outcomeSide, through the indexed catalog.
The child bytes32 market id becomes the signed questionId; catalog metadata supplies the
parent market id, and the promoted parent_market_data.contract_address becomes the
EIP-712 verifying contract. That address must also appear in the operator's
PRED_EXCHANGE_ADDRESSES allowlist — empty means the lane is default-off and unregistered.
The server then:
- maps normalized Long/Short buy/sell direction to PRED intent 0/1;
- scales price and quantity to 1e6;
- generates the
02+ 10-digit salt; - fixes feeRateBps to the published zero rate and signatureType to Safe proxy 2;
- returns the complete
Pred CTF Exchangeversion1envelope withbuildVersion: 1.
owner is the funds-holding Gnosis Safe; signer is its distinct controlling EOA. Private
keys, salts, signatures, API keys, and JWTs are rejected during build.
PRED restricts users in the US, UK, France, Ontario, Singapore, Poland, Thailand, and Taiwan and prohibits location masking; eligibility and enforcement remain the operator/compliance responsibility.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Catalog PRED outcome id ({bytes32 child market id}#0 Long or #1 Short).
Catalog child market id; pair with outcomeSide to choose Long or Short.
Buy or sell the selected normalized outcome; the server derives PRED intent.
Selected-outcome probability in (0,1); Short selection is complemented for signing.
Shares, minimum 5 and at most one decimal place.
Funds-holding PRED Gnosis Safe proxy (signed maker).
EOA controlling the Safe and signing the returned digest; must differ from owner.
Unix seconds. 0 builds GTC; a future value builds GTD.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Core Rain catalog market id.
Arbitrum USDT atoms (6dp). The spender is the catalog-resolved pool Diamond.
Compatibility echo only; when present it must equal the catalog pool.
Compatibility echo only; when present it must equal the catalog pool.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Core Rain catalog market id.
BUY requires amount; SELL requires shares. The opposite unit is rejected.
Source-verified 1-indexed option id; option 0 is invalid.
1e18-scaled price, from 0.01e18 through 0.99e18 in exact 0.01e18 ticks.
LIMIT BUY base-token amount in 6dp USDT atoms; minimum 1 USDT.
LIMIT SELL shares in 6dp atoms; shares times price must be at least 1 USDT.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Core Rain catalog market id.
BUY requires amount; SELL requires shares. The opposite unit is rejected.
Source-verified 1-indexed option id; option 0 is invalid.
1e18-scaled price, from 0.01e18 through 0.99e18 in exact 0.01e18 ticks.
LIMIT BUY base-token amount in 6dp USDT atoms; minimum 1 USDT.
LIMIT SELL shares in 6dp atoms; shares times price must be at least 1 USDT.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Core Rain catalog market id.
BUY encodes enterOption and may use live AMM or OB phase. SELL encodes sellOption and the verified source permits it only in OB phase, including post-window AMM Phase B.
Market BUY base-token amount in 6dp USDT atoms; minimum 1 USDT.
Market SELL shares in 6dp atoms; live quoted proceeds must reach 1 USDT.
Required tolerance; zero is rejected because it disables protection.
TTL added to the inspected Arbitrum block timestamp. Calldata receives the resulting absolute Unix-seconds deadline, never this duration.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Core Rain catalog market id.
BUY encodes enterOption and may use live AMM or OB phase. SELL encodes sellOption and the verified source permits it only in OB phase, including post-window AMM Phase B.
Market BUY base-token amount in 6dp USDT atoms; minimum 1 USDT.
Market SELL shares in 6dp atoms; live quoted proceeds must reach 1 USDT.
Required tolerance; zero is rejected because it disables protection.
TTL added to the inspected Arbitrum block timestamp. Calldata receives the resulting absolute Unix-seconds deadline, never this duration.
Dual-generation Rain claim. The server resolves the exact pool across both official catalog hosts, then uses the Diamond loupe to select V1 claim() or V2 claim(uint256 optionId). optionId is required for V2 and rejected for V1; unknown or ambiguous selector sets fail closed without guessing a generation.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
Core Rain catalog market id.
Required 1-indexed subpool id for V2; omit for V1.
Venue-specific order or redemption input. The selected lane validates the relevant subset; unknown fields are preserved for venue-shaped payload compatibility. No property is globally required because the registered lanes have different top-level shapes, but an empty object is invalid and every selected lane's required properties must be supplied.
object
Preview the fully resolved and bounds-checked artifact without persisting intent state. The supplied Idempotency-Key is neither looked up nor bound.
object
Client-echoed SDK build result for CTF Exchange lanes.
object
Examples
Polymarket preview; the server returns unsigned EIP-712 typed data
{ "dryRun": true, "outcome": "42", "outcomeSide": "YES", "isBuy": true, "price": 0.52, "size": 10, "owner": "0x1111111111111111111111111111111111111111"}Hyperliquid preview; resolves the catalog and returns no execution row
{ "dryRun": true, "asset": "100000070", "isBuy": true, "price": 0.5, "size": 1, "owner": "0x1111111111111111111111111111111111111111"}Opinion Safe mode; owner controls the funds-holding Safe maker
{ "outcome": "101", "outcomeSide": "YES", "isBuy": true, "price": 0.52, "size": 10, "owner": "0x1111111111111111111111111111111111111111", "signatureType": 2, "safeAddress": "0x2222222222222222222222222222222222222222"}Predict.fun EOA-only plain params
{ "asset": "987654321", "isBuy": false, "price": 0.61, "size": 5, "owner": "0x1111111111111111111111111111111111111111"}Pascal plain params; the client signs the returned 232-byte Ed25519 permit
{ "market": "SIM_EVENT_1.MARKET_1", "side": "YES", "isBuy": true, "price": 0.55, "size": 10, "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB", "signer": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1", "tif": "GTC", "postOnly": true}XO plain params; the server returns its current 13-field EIP-712 typed data
{ "asset": "101494015583034644548829266310903290769427955460966676274001973781189575535684", "isBuy": true, "price": 0.57, "size": 1, "owner": "0x1111111111111111111111111111111111111111", "signatureType": 3}Gemini plain params; the server persists the exact private-REST order body
{ "outcome": "gemi-GEMI-BTC-100K-2026", "outcomeSide": "YES", "isBuy": true, "price": 0.42, "size": 3, "timeInForce": "good-til-cancel"}Kalshi normalized params; the server returns an authless V2 order body
{ "outcome": "kalshi:KXOFFICIAL-26-A", "outcomeSide": "YES", "isBuy": true, "price": 0.42, "size": 5, "timeInForce": "good-til-cancel"}PRED Safe-maker plain params; the server resolves the parent exchange
{ "outcome": "0x00888e82b72c972a70469e0e6acbd3a1931336a4c293e03d93e97863ab457700", "outcomeSide": "YES", "isBuy": true, "price": 0.57, "size": 10, "owner": "0x2222222222222222222222222222222222222222", "signer": "0x1111111111111111111111111111111111111111"}Polymarket US normalized params; the server returns an authless REST request
{ "marketId": "will-x-happen", "outcomeId": "will-x-happen:long", "side": "buy", "type": "limit", "amount": 10, "price": 0.55}Rain default LIMIT BUY; amount is 6dp Arbitrum-USDT atoms
{ "marketId": "rain:6a79c7f5849b6fb38beb9eb4", "owner": "0x1111111111111111111111111111111111111111", "action": "limit", "orderSide": "BUY", "option": 1, "optionSide": "YES", "price": "420000000000000000", "amount": "5000000", "postOnly": true}Rain protected market SELL; shares are 6dp share atoms
{ "marketId": "rain:6a79c7f5849b6fb38beb9eb4", "owner": "0x1111111111111111111111111111111111111111", "action": "market", "orderSide": "SELL", "option": 1, "optionSide": "NO", "shares": "7000000", "slippageBps": 100, "deadlineSecondsFromNow": 120}Responses
Section titled “Responses”Persisted built execution, or a non-persisted artifact preview when dryRun: true. A duplicate key affects persisted builds only and returns the original row. Polymarket and Opinion order builds (previews included) include a warning while their hosted relay submit is region-blocked. Hyperliquid adds an advisory warning when its readable spot USDC total minus hold is below the order notional; balance-read failure is fail-open.
object
object
acked means the venue accepted/relayed the artifact; it does not by itself prove the order is resting. Use the status/refresh operations for confirmation.
object
Fixed-point whole-contract count, for example 5.00.
Fixed-point whole-cent probability strictly between zero and one.
Present only when the build requested reduceOnly; never false.
object
object
Validated client-signed or authless relayed artifact, or null before submission. Polymarket US submitted artifacts exclude keyId, secretKey, timestamp, and auth headers.
Venue fee estimate or null when no verified model is available.
Present on Hyperliquid HIP-4 order builds and their persisted responses.
object
First-party HIP-4 outcome assets have no perp-DEX component.
Optional pre-signing advisories. Polymarket and Opinion order builds currently warn that venue regional restrictions reject hosted submit from Predictefy's relay egress. Rain order builds warn when a pool cannot prove its provenance against the source-verified official deployer. Hyperliquid warns when spendable spot USDC (total minus hold) is below order notional, names the shortfall, and points to POST /v1/funding/hyperliquid/steps; its balance read is fail-open. PRED declares a matching warning that venue key binding rejects platform-key submit for a caller-owned Safe maker, but no caller can currently receive it: the PRED lane is darked and unregistered, so its build route answers 404 before any warning is composed — the advisory applies only if that lane is re-armed. Builds and client signing remain available on the armed lanes; callers may use their own submit path or, for PRED, credentials from their own venue arrangement.
object
object
Complete venue-shaped artifact after the normal fail-closed bounds checks.
Venue fee estimate or null when no verified model is available.
Present on Hyperliquid HIP-4 order previews.
object
First-party HIP-4 outcome assets have no perp-DEX component.
Same pre-signing advisories as persisted builds — including Hyperliquid's fail-open spot USDC shortfall warning. A preview is the pre-funding moment those advisories exist for.
Example
{ "success": true, "data": { "intent": "order", "status": "built", "unsigned": { "side": "bid", "time_in_force": "good_till_canceled", "self_trade_prevention_type": "taker_at_cross", "reduce_only": true }, "collateral": { "ledger": "spot" } }}Headers
Section titled “Headers”Present with value true when stored state satisfied an idempotent retry.
A missing or RESERVED Idempotency-Key, a generic invalid request, or a Rain source-level input guard.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Missing, invalid, unknown, or revoked Predictefy API key.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}The build would breach a configured execution spend cap.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}The API key lacks trade scope or the venue geofence rejected the request.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}The runtime venue lane is absent, or its catalog market/outcome was not found.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}The persisted server-built artifact is incompatible, a Rain pool is not in the source-required phase/order-count state. Rebuild or correct the request when applicable.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}A client-built artifact's structHash does not match its echoed order, or a Rain claim target cannot be bound safely to one supported on-chain contract generation.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}The authenticated execution token bucket is exhausted.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Unexpected failure or an unsigned artifact escaped its registered bounds.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}The runtime venue lane does not implement this lifecycle verb.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}A venue request or relay failed ambiguously.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}The execution service is unavailable, or a Rain pool failed its source-verified safety proof.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}