Trading & execution

Trading on every plan

Trading ships on every plan, including Free. All API keys include the trade scope by default; there is no request-access or separate approval step. Execution is caller-authorized against your own funds. Wallet lanes are client-signed; Myriad adds bounded HMAC relay auth after wallet-signature recovery, while Gemini and Polymarket US use bounded caller-owned request auth. Spend caps and credit metering apply in every case.

Predictefy’s execution API is isolated from the reads API. SDK users opt in with the exported PREDICTEFY_EXEC_BASE_URL; direct HTTP clients can copy the execution origin from the developer dashboard.

The service never holds user funds or persists user credentials. It builds an unsigned or authless venue-shaped artifact and validates that stored artifact against venue-specific bounds before relay. Wallet lanes use your signer callback in your own process. PredictStreet verifies that signature against the server-stored digest before reading one caller API key for relay. Myriad likewise recovers its EOA signature before HMAC-authenticating one exact order request with the caller’s key and secret. Gemini is the explicit no-wallet-signature exception: it HMAC-authenticates one bounded private REST request with the caller’s transient key and secret. Polymarket US creates only the venue’s fixed Ed25519 request-auth signature from the caller’s transient key id and secret. All four discard credentials and generated headers immediately. Funds remain in the caller’s wallet or venue account, and there is no generic server-side wallet or order-signing route.

Caution

Trading can lose money. Validate every built artifact before authorization, keep keys out of application logs, and start with small orders. A cross-venue indicative price discrepancy is not evidence that a trade is executable or profitable.

Integration cost by venue

Start with GET /v1/exec/venues. It is the authoritative live list for the current deployment: an implementation below may still be absent, geo-blocked, or fail-closed when its runtime gates are not armed. The static tables explain what a builder must integrate when a capability is listed.

Predictefy never stores private signing keys and never signs for the caller. Every wallet, order, or transaction signature is created client-side. Server-built means that Predictefy performs the order math and returns a signable or authless EIP-712 artifact, transaction, or binary permit; it does not mean server-side signing. Your wallet or agent key never transits Predictefy. Some venues require API credentials for relay, cancellation, or status reads. Gemini and Myriad HMAC secrets and Polymarket US’s Ed25519 secret create request authentication in-process only after artifact validation. These transient values are immediately discarded and never persisted or logged. Pascal needs no relay credential; its private trading key remains client-side.

Before funding: prerequisites for every armed hosted venue

The first version of this table was cut on 2026-08-13, when PRED was darked. The dated correction below records its supersession rather than presenting the current rows as timeless.

Live arming correction — 2026-08-15

Production GET /v1/exec/venues returned exactly 13 armed rows: Gemini, Limitless, Myriad, Opinion, Pascal, Polymarket, Polymarket US, Predict.fun, and Rain advertise build + submit + cancel; Hyperliquid also advertises modify + approveAgent; Kalshi advertised build + submit in that snapshot, while the 2026-08-23 official REST source adds cancel and GET /v1/exec/venues remains the runtime arming truth; PredictStreet and XO advertise build + submit. PRED remains below only as a dated dark-lane reference and is not part of the armed count.

XO superseded twice since — 2026-08-18

The 2026-08-15 observation above is left exactly as production returned it. XO’s row has changed twice since that reading, and neither change is reflected in it. Its hosted build and submit were disarmed earlier on 2026-08-18, once the venue’s own API documentation showed the orderbook had migrated to a different order struct and a different exchange contract than the builder targeted; its cancel and client-credentialed status refresh were armed in the same pass. Later the same day the builder was rebuilt to that current contract and verified against the deployed exchange on-chain, so XO now advertises build + submit + cancel. Nothing has ever been submitted to XO, so the first live submit is the confirmation checkpoint. See the XO trading guide for the detail.

Check GET /v1/exec/venues again immediately before integration because runtime arming can change independently of this guide. Every cell is grounded in lane validation, the funding registry, or the repository’s no-escrow record. Where those sources do not establish a prerequisite, the table says verify with venue.

Venue and current state	Account or transient credentials needed	Wallet, signer, or smart wallet needed	Geo constraint before funding	Funding path
Hyperliquid — armed	No caller API credential. Approve a browser/mobile agent with the master wallet first, or sign directly with the master.	EVM master wallet or approved EVM agent signs the phantom L1 EIP-712 action.	Verify with venue. The repo establishes no stronger country rule.	Land USDC in Hypercore spot through POST /v1/bridge/session. HIP-4 spends spot USDC total - hold; the funding-steps route reports readiness and returns no internal-transfer step.
Kalshi — official REST; default-off	Funded Kalshi account. The caller supplies apiKeyId + RSA privateKeyPem for each submit, cancel, or status refresh; optional subaccount on submit must be a non-negative integer. Predictefy uses them in memory for that one request and never stores or logs them.	No order-body or on-chain signer; Predictefy creates RSA-PSS auth for one fixed official V2 REST method and path.	Eligibility is venue-controlled and location-dependent; verify account access before funding.	Fund the regulated Kalshi USD account through venue rails. The venue holds the balance; no Solana USDC, SOL, or Predictefy escrow is involved.
Limitless — armed, geo-gated	No caller API credential or profileId; Predictefy holds the partner HMAC credential.	Base EOA signs the order.	Verified 2026-08-16: restricted production egress receives 403 GEO_BLOCKED, including on status reads. A trusted geo edge and venue eligibility are required.	Hold Base USDC in the EOA and approve the market exchange; LI.FI can fund the wallet.
Opinion — armed, hosted submit blocked	Hosted build/submit uses Predictefy’s builder key; a caller user API key is needed for hosted cancel/status. The working direct SDK path keeps that key in-process.	BSC EOA signs; an Opinion Safe may be the type-2 maker controlled by that EOA.	Hosted submit is rejected from Predictefy’s Railway US egress, regardless of customer location. Do not fund for hosted submit while this remains true. The venue response names the US, China, and other restricted jurisdictions.	Hold the market-authoritative BSC quote token in the maker EOA/Safe and approve the exact exchange; the registry’s current route is BSC USDT through LI.FI.
Polymarket — armed, hosted submit blocked	The working SDK path derives or accepts the CLOB key, secret, and passphrase locally. The legacy hosted path accepts the triple per request but is blocked.	Polygon EOA signs; an EOA, Proxy, or Safe may hold funds according to signature type 0/1/2.	Hosted submit is rejected from Predictefy’s Railway US egress, regardless of customer location. Use only an eligible caller-direct route.	Hold Polygon pUSD and approve the V2 CTF or NegRisk exchange. LI.FI can fund pUSD; the documented steps wrap existing USDC.e.
Predict.fun — armed, hosted route blocked	Hosted submit/cancel/status needs the caller session bearer. The preferred direct SDK path keeps the venue API key and wallet key in-process.	BSC EOA only; Safe/proxy identity is rejected.	The hosted route remains region-blocked. An accepted jurisdiction and venue session are required.	Hold BSC USDT and approve the market-selected exchange; LI.FI can fund the wallet.
Rain — armed	No caller venue credential. Verify with venue whether account registration is required.	Arbitrum EOA signs and broadcasts the returned transaction.	Verify with venue. The repo establishes no stronger country rule.	Hold Arbitrum USDT and approve the operator-armed market Diamond; LI.FI can fund the wallet.
XO — armed	Caller-owned XO CLOB API key, secret, and passphrase are required at submit.	Chain-3223 XO smart account by default (signatureType: 3, maker == signer). A direct EOA (signatureType: 0) is documented by the venue’s order schema but its own auth and smart-account guides call type 3 the only model accepted today; that contradiction is unresolved, so type 0 is an explicit opt-in.	Verify with venue. Eligibility remains an operator/compliance responsibility.	Hold six-decimal Bridged USDC (XO) and approve the verified exchange. No hosted helper exists; the deposit route is verify with venue.
Gemini — armed	Funded account, accepted terms, and a Trader key/secret with time-based nonce enabled, heartbeat disabled, and trusted-IP mode Unrestricted.	No order-body signer; Predictefy HMAC-authenticates one bounded request.	Verify with venue. The repo establishes no country list.	Fund the Gemini venue account through Gemini rails. The registry pins no chain or collateral token.
PredictStreet — armed	Caller API key plus an existing caller-specific vault.	ADI Chain EOA signs a VAULT-type order.	Verify with venue. Eligibility remains an operator/compliance responsibility.	Approve and deposit ADI-chain USDC.e into the caller vault. No hosted funding helper exists.
Polymarket US — armed	Identity-verified, funded venue account plus caller UUID key ID and base64 Ed25519 API secret.	No order-body signer; the Ed25519 secret is request auth, not a Solana wallet key.	Verify with venue for account and geographic eligibility.	Fund the venue-custodied account through regulated in-venue rails; no crypto bridge helper exists.
Pascal — armed	Eligible Pascal account/custody wallet; use the registered wallet key or a revocable delegated trading key. No relay credential.	Solana-format Ed25519 signer signs the exact permit bytes.	Terms restrict Australia, Belgium, France, Germany, Italy, the Netherlands, Ontario, Poland, Quebec, Russia, Singapore, Spain, Taiwan, Thailand, the UK, the US, and comprehensively sanctioned jurisdictions including Iran, Syria, Cuba, North Korea, Crimea, Donetsk, and Luhansk.	Use the existing Pascal custody wallet. The collateral asset and deposit route are verify with venue; no hosted helper exists.
PRED — darked 2026-08-13; reference only	The venue confirmed that Predictefy platform-key submissions for caller-owned Safes are refused. The source-ready shape accepts a caller API key and access/refresh JWTs only for an independently arranged future path.	Caller-owned Base Safe is maker; a distinct controlling EOA signs type 2.	The venue restricts the US, UK, France, Ontario, Singapore, Poland, Thailand, and Taiwan and prohibits location masking.	Do not fund for hosted submit. The collateral asset and Safe funding/enablement route are unverified and no hosted helper exists.
Myriad — armed	Wallet-bound Myriad API key and secret plus the connected EOA; bare credentials are unsupported.	BSC EOA signs type 0; Safe/proxy identity is unsupported.	Verify with venue. The repo establishes no stronger country rule.	Hold manager-selected 18-decimal BSC USD1 or USDT and approve collateral or outcome shares to the exchange. No hosted helper exists.

Every row above covers getting funds in. Getting them out is always the venue’s own rail: Predictefy publishes no withdrawal and no bridge-out endpoint, so a balance at one venue cannot be moved to another through this platform. That is the no-escrow custody posture — the platform never holds the funds — and unified cross-venue funding is roadmap, not a shipped capability. See Accounts & funding for each venue’s exit path, including Hyperliquid’s Arbitrum-only two-leg withdrawal.

Polymarket and Opinion order-build responses include a top-level warnings advisory before funding or signing, warning that the hosted relay is geo-blocked. PRED’s execution lane is darked (2026-08-13) because the venue confirmed that platform-key submissions for caller-owned Safes are refused. Its source-ready build/sign contract remains documented, but there is no supported hosted credential path; only callers with their own independently arranged PRED access can use that source lane.

Build families

Family	Venues	What the builder adds
Server-built order	Hyperliquid, Limitless, Polymarket (V2), Opinion, Predict.fun, Myriad, XO, PRED (source-ready, darked), PredictStreet, Pascal	Send plain order parameters and the signing owner. Predictefy fixes the remaining order fields and returns the signable EIP-712 artifact or Pascal binary permit.
Server-built transit-auth order	Gemini	Send plain catalog-bound order parameters. Predictefy stores the exact venue body; submit HMAC-authenticates it once with the caller’s transient API key and secret.
Client-echoed venue SDK order	Polymarket (V2 EOA echo), Opinion and Predict.fun (legacy)	Existing integrations may send the venue’s exact order, EIP-712 domain, and structHash as buildResult. Polymarket requires the V2 order contract; Opinion and Predict.fun retain their legacy venue-specific shapes.
Raw/structured chain intent	Rain	Rain returns an unsigned chain transaction for client signing.
Stateless venue REST	Kalshi, Polymarket US	Send normalized catalog ids, side, contract quantity, and price. Predictefy stores an exact authless venue body; submit/refresh accepts caller credentials only for that request, and Kalshi cancel does the same.

Hosted order lanes

Venue and current state	What you add before or during build	What you sign and where	Credentials you must hold	Funding model and external prerequisites
Hyperliquid — armed: build + submit + cancel + modify + approveAgent	asset, or outcome + outcomeSide, plus isBuy, price, size, and owner.	L1 order/cancel/modify action under the phantom EIP-712 Exchange v1 domain.	Master wallet and optional approved agent key stay client-side; no venue API key.	Spend Hypercore spot USDC total - hold; the bridge session can deliver it and the funding-steps route reports readiness only.
Limitless — armed; geo-gated	owner, tokenId, side/type, marketSlug, price, shares, and any FOK budget; profileId is rejected.	EIP-712 CTF order on Base 8453.	Base EOA key stays local; Predictefy holds the partner HMAC credential.	Base USDC plus exchange approval. Verified 2026-08-16: restricted egress gets 403 GEO_BLOCKED, including on status reads.
Polymarket — armed; hosted relay blocked	Plain V2 intent or a V2 EOA buildResult.	V2 EIP-712 order on Polygon 137; caller-direct SDK is the working path.	Direct SDK keeps the EOA and CLOB triple local; legacy hosted submit accepts the triple transiently but is geo-rejected.	Polygon pUSD plus V2 CTF/NegRisk approval; direct traffic remains subject to venue eligibility.
Polymarket US — armed since 2026-08-15	Catalog marketId + outcomeId, side, type: "limit", amount, and price.	No order-body signature; Predictefy creates bounded Ed25519 request auth.	Caller UUID key ID and base64 Ed25519 secret transit only for the authenticated call.	Funded, identity-verified venue account through in-venue rails; no crypto bridge helper.
XO — build + submit + cancel; rebuilt and re-armed 2026-08-18	Outcome selector, isBuy, price, size, the owner account, and optional expiresAt.	13-field EIP-712 CTF order on chain 3223; signatureType defaults to 3 (XO smart account, ERC-1271).	Signing key stays local; caller XO CLOB key/secret/passphrase transit submit only.	Six-decimal Bridged USDC (XO) plus exchange approval; deposit route unverified and no hosted helper.
PRED — darked 2026-08-13; source-ready reference only	Outcome selector, isBuy, price, size, Safe owner, EOA signer, and optional expiresAt.	Type-2 EIP-712 order on Base 8453.	Platform-key submits for caller Safes are venue-refused. Only an independently arranged caller API key/JWT set could use the source lane.	Do not fund for hosted submit. Collateral and Safe funding/enablement route remain unverified.
PredictStreet — armed since 2026-08-15; no cancel flag	Outcome selector, isBuy, price, size, EOA owner, and optional expiry/post-only fields.	VAULT EIP-712 order on ADI Chain 36900.	EOA key stays local; caller API key transits submit only after signature recovery.	Deposit USDC.e into the caller vault; no hosted funding helper.
Pascal — armed 2026-08-12; fleet-verified 2026-08-15	Catalog market, side, direction, price, integer size, custody owner, permit signer, and optional timing fields.	Exact Ed25519 place/cancel permit bytes.	Wallet or delegated trading key stays local; no relay credential.	Existing Pascal custody wallet; collateral asset/deposit route unverified and no hosted helper.
Opinion — armed; hosted submit blocked	Plain outcome intent; type 0 EOA or type 2 Opinion Safe maker.	BSC 56 EIP-712 order signed by the controlling EOA.	Direct SDK keeps the user API key local; hosted cancel/status accepts it transiently.	Market-authoritative BSC quote token plus exchange approval; hosted Railway US egress is venue-rejected.
Predict.fun — armed; hosted route region-blocked	Plain outcome intent; EOA type 0 only.	BSC 56 EIP-712 order.	Direct SDK keeps API key/wallet key local; hosted submit/cancel/status needs a transient session bearer.	BSC USDT plus market-selected exchange approval; use an eligible direct route.
Kalshi — official REST; default-off	Catalog outcome selector, isBuy, cent-exact probability price, positive integer size, and optional good-til-cancel time in force.	No order-body or on-chain signature; Predictefy RSA-PSS-authenticates only the exact stored official V2 REST request.	Caller apiKeyId + RSA privateKeyPem transit only for submit, cancel, or refresh and are discarded; optional non-negative subaccount is submit-only.	Fund the regulated Kalshi USD account through venue rails. client.accounts.kalshi remains the venue-custodied native REST path.
Gemini — armed since 2026-08-15	Catalog selector, direction, price, size, and optional TIF/maker-only fields.	No order-body signature; Predictefy HMAC-SHA384 authenticates the stored request.	Caller Trader key/secret with time nonce, no heartbeat, and Unrestricted trusted-IP mode.	Funded Gemini account and accepted prediction-market terms; no bridge helper.
Myriad — armed since 2026-08-15	Model-qualified Order Book outcome, direction, tick-aligned price, size, and EOA owner.	BSC 56 MyriadCTFExchange EIP-712 order.	EOA key stays local; wallet-bound HMAC key/secret transit submit/cancel only after recovery.	Manager-selected 18-decimal BSC USD1 or USDT plus required approval; no hosted helper.
Rain — armed since 2026-08-15	Catalog-bound approval, limit/market order, or cancel parameters.	Raw Arbitrum 42161 transaction; caller signs and broadcasts.	No caller venue credential; EOA key/RPC stay local.	Arbitrum USDT plus per-market Diamond approval; hosted submit records signed and never claims broadcast.

Venues without a hosted trade lane

Venue group	Execution available today
Smarkets	No hosted execution lane, by owner decision on 2026-08-18 rather than as a build gap. A separate venue-direct client-side SDK trading integration is live at client.accounts.smarkets (createOrder and cancelOrder); the account email and password never transit Predictefy. See Smarkets.
SX Bet	No hosted execution lane. A separate venue-direct client-side SDK trading integration is live at client.accounts.sxbet; signing keys and venue credentials remain in the caller’s process and requests go directly to the venue. See SX Bet.

Authentication

Send a Predictefy API key as a Bearer token. Every API key includes the trade scope by default. A key without that scope receives 403 SCOPE_MISSING by design.

Authorization: Bearer pk_live_YOUR_TRADE_SCOPED_KEY

The execution origin is an explicit opt-in in the TypeScript SDK:

import { Predictefy, PREDICTEFY_EXEC_BASE_URL } from '@predictefy/sdk';

const client = new Predictefy({
  apiKey: process.env.PREDICTEFY_API_KEY,
  execBaseUrl: PREDICTEFY_EXEC_BASE_URL,
});

const openOrders = await client.exec.fetchOpenOrders({ venue: 'hyperliquid' });
console.log(openOrders);

execBaseUrl has no implicit default. The reads API does not proxy execution.

Exchange-style surface

Verb	HTTP route or SDK behavior
buildOrder	POST /v1/exec/:venue/orders/build; add dryRun: true for a non-persisted preview
submitOrder	POST /v1/exec/:venue/orders/submit
createOrder	SDK composition: buildOrder → client signer callback → submitOrder
cancelOrder	POST /v1/exec/:venue/orders/:executionId/cancel — direct relay or sign → submit, by venue
modifyOrder	Hyperliquid: POST /v1/exec/:venue/orders/:executionId/modify → sign → submitOrder
fetchOrder	GET /v1/exec/:venue/orders/:executionId
refreshOrderStatus	POST /v1/exec/:venue/orders/:executionId/refresh — client-authenticated status read
fetchOpenOrders	GET /v1/exec/:venue/orders?status=open
fetchClosedOrders	GET /v1/exec/:venue/orders?status=closed
fetchAllOrders	GET /v1/exec/:venue/orders?status=all
fetchMyTrades	GET /v1/exec/:venue/trades
fetchPositions	GET /v1/exec/:venue/positions
fetchBalance	GET /v1/exec/:venue/balance — honest 501 NOT_SUPPORTED; see limitations below

Every order-building, submission, cancellation, and modification POST requires an Idempotency-Key header. The SDK always sends one and generates a UUID when idempotencyKey is omitted. Direct HTTP clients should persist a stable key with the operation they may retry. refreshOrderStatus is the read-only exception and does not require that header. A dry-run build still requires the header for the route contract, but the service does not look it up, replay it, or bind it. The same key can therefore be used later for the persisted build.

To preview an order, add "dryRun": true to any venue build body. The service still performs trade-scope authentication, catalog market resolution, the venue’s complete artifact construction, and fail-closed artifact bounds checks. It returns dryRun: true, venue, intent, unsigned, notionalUsd, and feeEstimate, but no executionId or status. It inserts no execution.executions row and reserves no spend capacity; only a later ordinary build creates intent state.

Precheck market executability

A catalog-active market is readable, not necessarily executable. Use this official sequence for each exact order:

1. Discover the market through the catalog and confirm that GET /v1/exec/venues currently lists its venue with build: true.
2. Send the intended build with dryRun: true, or call client.exec.precheckOrder(params). This costs no execution credits, persists nothing, and returns either the existing ExecDryRunBuildResult or a typed refusal.
3. Only after a pass, send a normal persisted build, sign the returned artifact locally, and submit it. A dry-run preview has no executionId and cannot be submitted itself.

const catalogOutcomeId = '...'; // From a preceding PredictStreet catalog read.
const order = {
  venue: 'predictstreet',
  asset: catalogOutcomeId,
  isBuy: true,
  price: 0.42,
  size: 10,
  owner: '0x...',
};

const precheck = await client.exec.precheckOrder(order);
if (!precheck.ok) {
  console.log(precheck.refusal.code, precheck.refusal.retryable);
  return;
}

// Build again to create the persisted execution that can be signed and submitted.
const built = await client.exec.buildOrder(order);

precheckOrder returns server-authored API refusals instead of throwing them. A transport or invalid-response failure still throws because the server made no executability decision. retryable means that retrying the same request can reasonably succeed; a non-retryable refusal may still become passable after changing the order, account, venue state, or deployment.

Code	Meaning during an order dry run	Retryable	Venues that can emit it
ARTIFACT_BOUNDS_VIOLATION	The built artifact escaped the lane’s registered contract, chain, domain, action, or custom safety bounds.	No	Every armed hosted lane
ARTIFACT_INTEGRITY_MISMATCH	A client-echoed buildResult has a structHash that does not bind to its order.	No	Opinion, Polymarket, Predict.fun echoed-build paths
EXEC_UNAVAILABLE	API-key verification or required catalog/live execution truth is unavailable or disagrees, so execution fails closed.	Yes	Every lane for API-key verification failure; also Gemini, Myriad, Opinion, Pascal, Polymarket, Polymarket US, PRED, Predict.fun, PredictStreet, and XO for lane checks
GEO_BLOCKED	The trusted caller-country signal is absent or restricted for a geofenced lane.	No	Limitless today
IDEMPOTENCY_KEY_REQUIRED	A direct HTTP build omitted Idempotency-Key; the SDK always supplies one.	No	Every hosted lane
INTERNAL	An unexpected, non-authored server failure occurred; quote the request id to support.	Yes	Every hosted lane
MARKET_NOT_FOUND	The lane’s market/outcome selector did not resolve to an item in the venue catalog.	No	Every registered order lane
NOT_IMPLEMENTED	The venue is registered only for settlement, so its order-building stub refuses honestly.	No	Rain, Myriad, Polymarket, or Predict.fun when that deployment has only the settlement lane armed
NOT_SUPPORTED	The catalog item belongs to a deliberately unsupported execution model.	No	Myriad AMM or non-BNB Order Book ids
RATE_LIMITED	The authenticated execution request exhausted its token bucket.	Yes	Every hosted lane
RAIN_INVALID_AMOUNT	Rain amount, shares, notional, or quoted proceeds violate the verified source guards.	No	Rain
RAIN_INVALID_DEADLINE	Rain’s caller-selected deadline offset is outside the accepted range.	No	Rain
RAIN_INVALID_OPTION	The Rain option is malformed, zero, or outside the inspected pool’s option range.	No	Rain
RAIN_INVALID_PRICE	The Rain price is malformed, outside 0.01..0.99, or not on the exact source tick.	No	Rain
RAIN_INVALID_SIDE	Rain’s option side is not YES/1 or NO/2.	No	Rain
RAIN_ORDER_LIMIT_REACHED	The owner already has the source-capped number of active Rain orders for that option and direction.	No	Rain
RAIN_PHASE_NOT_OPEN	The inspected Rain pool phase does not permit the requested order action.	No	Rain
RAIN_POOL_SAFETY_CHECK_FAILED	Rain pool provenance, deployer, facet routing, base token, or catalog binding failed closed.	No	Rain
RAIN_SLIPPAGE_REQUIRED	A protected Rain market order lacks valid nonzero slippage protection or cannot derive a nonzero floor.	No	Rain
SCOPE_MISSING	The API key is valid but lacks the required trade scope.	No	Every hosted lane
UNAUTHORIZED	The Predictefy API key is missing, unknown, or revoked.	No	Every hosted lane
VALIDATION_ERROR	The shared build body or venue-specific order intent is malformed or internally inconsistent.	No	Every hosted lane
VENUE_NOT_SUPPORTED	No execution lane is armed for the requested venue in this deployment.	No	Any unknown, client-side-only, or currently unarmed venue
VENUE_RELAY_FAILED	A required build-time venue API, RPC, quote, or metadata read failed or returned unusable truth.	Yes	Kalshi, Myriad, Opinion, Pascal, Polymarket, Predict.fun, PredictStreet, Rain, and XO

A passing dry run proves only that the builder accepts this exact market and order now. It does not guarantee that a later persisted build still passes, that submit credentials or funding are valid, that the venue accepts the relay, or that the order fills. A catalog-level tradability flag could make discovery cheaper in the future, but it is not implemented here and would remain a hint rather than a substitute for this live precheck.

Caller-authorized execution flow

1. Run the per-market dry-run precheck above and handle any typed refusal.
2. Call buildOrder with the same order, a trade-scoped Predictefy key, and an idempotency key.
3. Inspect the returned unsigned/authless artifact in your process.
4. For a client-signing lane, sign it with your wallet or venue-specific signer callback. For Gemini or Polymarket US, keep the artifact unchanged and provide only that lane’s transient caller credential at submit.
5. Call submitOrder with the signed artifact, transient authorization, or client-broadcast digest. The service revalidates the stored artifact, owner binding, bounds, and spend caps before reading transient credentials, relaying, or recording a digest.
6. Poll fetchOrder. For a user-authenticated venue status read, call refreshOrderStatus first, then use the order and trade list verbs as needed.

Polymarket’s working SDK path intentionally diverges after build: it signs locally, then calls the CLOB directly for submit, status, and cancel. It does not call Predictefy’s hosted submit or refresh routes. See Client-side submit: the working Polymarket route.

client.exec.createOrder(params, signer) composes steps 2–5 for client-signing lanes; it does not run the precheck automatically. The signer receives only the unsigned artifact and returns venue-shaped signed fields. Private signing keys remain client-side, and Pascal’s trading private key never transits Predictefy. Gemini’s API key/secret, Myriad’s HMAC key/secret, PredictStreet’s API key, legacy hosted Polymarket and XO L2 CLOB credentials, Predict.fun session bearer tokens, Opinion API keys, and Polymarket US Ed25519 credentials transit only when that venue needs them. PRED’s source-ready partner/JWT shape would do the same only under a caller-owned arrangement; the hosted PRED lane is darked. They are not persisted or logged. The venue-direct Polymarket SDK path is the exception: its CLOB credentials never transit Predictefy and are sent only from the caller process to the venue.

Build request schema by venue

POST /v1/exec/{venue}/orders/build takes one JSON body whose shape is venue-specific. The venues do not agree on a single order struct. Each lane returns exactly what that venue signs or authenticates. Five families:

Family	Venues	You send	Price unit
Server-built order	Hyperliquid, Limitless, Polymarket (V2), Opinion, Predict.fun, Myriad, XO, PRED (source-ready, darked), PredictStreet, Pascal	plain order parameters; the server fixes every remaining field	probability number
Server-built transit auth	Gemini	catalog selector plus plain order parameters; credentials arrive only at submit	probability number
Client-echoed venue SDK result	Polymarket (V2 EOA echo), Opinion and Predict.fun (legacy)	the venue SDK’s exact buildResult (order + domain + structHash); Polymarket V1 echoes are rejected	atomic uint256 decimal strings
Raw/structured chain intent	Rain	chain parameters	atomic integer strings
Stateless venue REST	Kalshi, Polymarket US	catalog ids plus normalized side, contract amount, and price; the server returns an authless body	probability number

No venue on this route accepts a price in cents.

Common to every build call:

• Authorization: Bearer <trade-scoped key> and Idempotency-Key: <your stable key>. A missing header is 400 IDEMPOTENCY_KEY_REQUIRED.
• Optional intent: "order" (default) or "redeem". Anything else is 400 VALIDATION_ERROR — intent must be 'order' or 'redeem'; a venue with no redeem lane answers 501 NOT_IMPLEMENTED.
• Optional dryRun: true returns the fully resolved and bounds-checked preview without a ledger row. Omit it or send false for the existing persisted-build behavior.
• A venue with no lane in this deployment answers 404 VENUE_NOT_SUPPORTED. GET /v1/exec/venues is the authoritative live list: every build, submit, cancel, modify, and redeem flag there is derived from the same lane registry and artifact bounds the lifecycle routes consult, so a venue listed without build genuinely cannot build.
• Repeating a build with the same Idempotency-Key returns the original stored execution with an Idempotency-Replay: true response header. It is not rebuilt and spend caps are not re-checked.
• Build itself is not metered. Credits are charged on submit, cancel, and modify.
• Some lanes carry a top-level warnings advisory on order builds, including idempotent replays. Polymarket and Opinion warn that hosted submit is rejected from Predictefy’s relay egress; Rain warns when a pool cannot prove its provenance against the source-verified official deployer; and Hyperliquid warns when spendable spot USDC is below the order notional. None of these blocks build or client signing for a caller with their own submit path. PRED declares a warning of the same class about platform-key submits, but no caller can currently receive it: the PRED lane is darked and unregistered, so its build route answers 404 VENUE_NOT_SUPPORTED before any warning is composed. That advisory applies only if the lane is re-armed.
• The response carries the unsigned artifact, the server’s own notionalUsd (what the spend caps are checked against — never a caller-declared USD figure), and a fee estimate where the venue has a verified fee model. Rain has none, so its estimate is null with a feeWarning in the payload.

Each lane below has its own page. The families above tell you which one you are in.

• Hyperliquid
• Limitless
• Kalshi (Official REST API)
• Polymarket
• Polymarket US
• Opinion
• Predict.fun
• Pascal
• XO
• PredictStreet
• Gemini
• Myriad
• PRED
• Smarkets (client-side lane)
• SX Bet (client-side lane)
• Echoed build results: Polymarket V2, Opinion, and Predict.fun
• Rain
• Settlement claims (intent: “redeem”)

Submitting the authorized artifact

POST /v1/exec/{venue}/orders/submit relays what you signed. The body always carries:

{ "executionId": "<uuid returned by build>", "...": "venue-specific signed fields" }

• executionId is required and binds the submission to one stored, already cap-checked execution. Omitting it is 400 VALIDATION_ERROR — executionId (uuid) is required; an id that is malformed or simply not yours answers the same clean 404 EXECUTION_NOT_FOUND as the sibling routes. No retry can make a non-existent execution exist, so it is never a retryable server error.
• The Idempotency-Key header is required, and one caller key binds at most one execution per account, venue, and action. Reusing a key against a different execution is 409 IDEMPOTENCY_CONFLICT. An execution that has already left built status replays its current state with Idempotency-Replay: true — no second relay, no second charge.
• The service re-checks the stored notional against the per-order cap and re-sums the key’s actual submitted spend for the day before the relay, then reserves the submission. A rejection before the venue was ever contacted frees that reservation; an ambiguous relay failure (502 VENUE_RELAY_FAILED) keeps it, so a resubmit can never bypass the cap.

Wallet signatures are produced entirely in your process. Predictefy retains no user signing key, and there is no generic signing route to call. Kalshi, like Gemini and Polymarket US, is request-authenticated instead. What each venue expects back:

Venue	Signed fields you post	Signing scheme
Gemini	{ apiKey, apiSecret }	No client order signature. Predictefy HMAC-SHA384 signs one canonical stored body with an epoch-second nonce, then discards both credentials and headers.
Polymarket US	{ keyId, secretKey }	No client order signature. Predictefy creates Ed25519 request auth for the exact stored REST request, then discards both credentials and headers.
Hyperliquid	{ action, nonce, signature, owner }	EIP-712 phantom-agent over the L1 action. signature is {r,s,v} or 0x hex.
Polymarket	{ signature, owner, apiKey, apiSecret, apiPassphrase }	EOA ECDSA over the server-stored structHash (raw digest — a personal_sign wrapper is correctly rejected).
XO	{ signature, owner, apiKey, apiSecret, apiPassphrase }	65-byte ECDSA over the server-stored 13-field digest. Signature type 3 (XO smart account) is the default and is validated by ERC-1271 at the venue, so the server binds owner to the stored maker rather than recovering it; type 0 (direct EOA) must recover to the stored signer.
PRED (darked)	{ signature, owner, apiKey, accessToken, refreshToken }	Source-ready only: EOA ECDSA over the server-stored Base digest for the Safe maker; signature type 2 is fixed.
Myriad	{ signature, owner, apiKey, apiSecret }	EOA ECDSA over the server-stored BSC Order Book digest; only after recovery does Predictefy HMAC-SHA256 authenticate one exact venue request.
PredictStreet	{ signature, owner, apiKey }	EOA ECDSA over the server-stored VAULT digest; the API key is read only after recovery and is then discarded.
Pascal	{ signature, owner }	Base58 Ed25519 signature over the exact stored permit bytes. The delegated signer is already bound inside the permit.
Opinion	{ signature, owner }, plus safeAddress for Safe mode	Plain EOA ECDSA EIP-712 over the stored structHash, even in Safe mode (not EIP-1271). The EOA owner signs; the Safe remains maker.
Predict.fun	{ signature, owner, authToken }	EOA ECDSA over the stored structHash.
Limitless	{ signature, owner }	EIP-712 over the server-built order. You post only the signature; the server attaches it to the stored order.
Kalshi	{ apiKeyId, privateKeyPem, subaccount? }	No client order signature. Predictefy creates RSA-PSS request auth for the exact stored official V2 request, then discards the credentials and headers.
Rain	{ signedTransaction, owner } (0x hex raw tx)	Signed Arbitrum (chain 42161) transaction; you broadcast it yourself.

Three rules govern the client-signing lanes:

1. Identity binding. The wallet declared at build is stored with the intent. Most lanes require recovered signer = stored owner = submitted owner. Pascal instead verifies the stored delegated signer while separately requiring submitted owner = stored custody owner. PRED binds submitted owner to the stored Safe maker and recovery to its separately stored EOA signer. Cancel and modify inherit stored identity; a caller-supplied replacement is never trusted.
2. No bait-and-switch. What you submit must be what was built. Hyperliquid re-hashes your posted action and compares it to the stored connectionId (submitted action does not match the built execution). Rain’s and Predict.fun’s on-chain cancel paths byte-compare the signed transaction against the stored one. Limitless is structural — you cannot substitute an order you never send.
3. Verify before relay. The signature is verified locally first; a tampered ECDSA or Ed25519 signature is rejected before anything reaches the venue.

Gemini applies the same no-bait-and-switch principle without a wallet signature: the stored versioned body, allowlisted request path, exact shape, and notional are all revalidated before the code reads apiKey or apiSecret. Only that canonical body is included in the HMAC payload.

Kalshi likewise revalidates the stored official REST order or cancel shape before reading apiKeyId or privateKeyPem. A legacy Solana-shaped artifact refuses with 409 ARTIFACT_VERSION_CONFLICT; valid credentials and generated auth headers exist only in memory for the one bounded request.

Hyperliquid: key order is load-bearing

Hyperliquid hashes the msgpack encoding of the action, and msgpack preserves insertion order — so the key order of the object you sign is part of the digest. The canonical order is a, b, p, s, r, t then optional c for an order wire; type, orders, grouping for a place; type, cancels for a cancel; type, oid, order for a modify; and isMarket, triggerPx, tpsl inside a trigger. A JSON round-trip does not preserve key order, so the service re-canonicalizes your posted action into that exact order before hashing, recovering, and relaying — values still bind the hash, so a changed value is still caught. Build your action in the same order and sign that.

Venue credentials that appear above — Gemini and Myriad key/secrets, Polymarket US’s key ID and Ed25519 secret, the legacy hosted Polymarket and XO L2 CLOB triples, Predict.fun’s session bearer, and Opinion’s user API key — transit only for that call. PRED’s partner key/JWT shape is retained for a caller-owned arrangement but is not available through the darked hosted lane. No transient credential is persisted, logged, or used by a background job. Pascal needs no such relay credential: its private trading key remains client-side and only the signature crosses the API. That is exactly why automatic status polling is impossible for the credentialed venues, as the next section explains.

For the venue-direct Polymarket SDK path, the CLOB triple does not cross the Predictefy API at all; the SDK signs its venue requests locally and keeps status/cancel direct.

Required scopes by endpoint

A 403 SCOPE_MISSING response deliberately does not name the missing scope, so a caller cannot enumerate the scope surface by probing. This table is the answer instead.

Endpoint group	Required scope
Every /api/{exchange}/… catalog, order-book, trades, history, execution-price, capability, and cross-match verb	read
Every /api/feeds/… reference-feed verb	read
/v1/traders/… — tape, holders, leaderboards, wallet profiles, smart money	read
/v1/accounts/…, /v1/portfolio, /v1/funding/{venue}/requirements, /v1/funding/{venue}/steps, /v1/bridge/…	read
/v1/clusters, /v1/clusters/{id}, /v1/discrepancies, /v1/discrepancies/{clusterId}/qualification, /v1/mappings	read
/v1/venues/metrics, /v1/webhooks, /v1/webhooks/{id}, /v1/webhooks/{id}/deliveries	read
/v1/billing/checkout, /v1/billing/subscribe, /v1/billing/portal	read
The WebSocket streaming lane	read
POST /v1/sql (executeSql)	sql
Every /v1/exec/… route — build, submit, cancel, modify, refresh, and the order, trade, position, balance, and venue reads	trade

A few endpoints sit outside the table by design: the health and status endpoints need no key at all, POST /v1/billing/webhook/stripe is authenticated by its Stripe signature rather than an API key, and GET /api/feeds/{feed}/fetchOrderBook carries no scope mapping because it only ever answers a capability error — no feed source provides depth.

All self-serve API keys carry read and trade. The sql scope is the exception: no self-serve plan grants it, and it is provisioned on request — see the credits and plans guide. A valid key that lacks the scope a route requires is rejected before any credit is debited or usage recorded.

Client-initiated order-status refresh

Automatic status polling is available only when a status path needs no per-user credential. Gemini, Kalshi, Polymarket, Opinion, and Predict.fun authenticate order reads with the caller’s venue credential, which the execution service does not retain. That no-escrow boundary is why the caller must initiate:

POST /v1/exec/:venue/orders/:executionId/refresh

The supported body is venue-specific:

Venue	JSON body
Gemini	{ "apiKey": "...", "apiSecret": "..." } — time-based-nonce, non-heartbeat Trader key
Kalshi	{ "apiKeyId": "...", "privateKeyPem": "..." } — transient RSA credentials; no subaccount
Polymarket	{ "apiKey": "...", "apiSecret": "...", "apiPassphrase": "..." }
Opinion	{ "userApiKey": "..." }
Predict.fun	{ "authToken": "..." } — the caller’s session bearer; uses the order hash created at submission

Hyperliquid’s status path needs no user credential and serves the same POST with an empty body. Limitless implements the same credential-free shape, but as verified on 2026-08-16 its restricted production egress receives 403 GEO_BLOCKED even on status reads; an empty body does not bypass that venue policy.

The TypeScript SDK exposes the same route:

const refreshed = await client.exec.refreshOrderStatus({
  venue: 'polymarket',
  executionId,
  apiKey,
  apiSecret,
  apiPassphrase,
});

This is read-only with respect to the venue: it reads status and fills, may advance a non-terminal execution status, and never builds, signs, submits, or cancels an order. Terminal statuses never regress. The route is not metered. It is idempotent and safe to retry after a transient failure; unlike mutating POSTs, it needs no Idempotency-Key. POST keeps the transient credential in the request body instead of a URL or query string.

Spend caps and fail-closed bounds

The effective defaults are 100 USD per order and 1,000 USD per API key across the rolling 24-hour window. A cap violation is rejected; the service never silently reduces an order. Each available venue integration also enforces venue-specific contract, currency, chain, owner, and artifact bounds. Missing or unknown bounds keep that venue unavailable.

Venue execution status

Status is per venue integration, not a blanket venue claim.

Venue	Current hosted status	Current behavior and limitations
Gemini	Armed 2026-08-15: build + submit + cancel	Limit orders only. Caller-owned time-based-nonce, non-heartbeat Trader credentials transit each authenticated call and are never retained; status refresh is caller-initiated.
Hyperliquid	Armed: build + submit + cancel + modify + approveAgent	Mainnet client-signed orders and single-order modify are live. Credential-free status reconciliation and empty-body refresh are implemented.
Kalshi	Official REST source-ready; default-off: build + submit + cancel	Literal KALSHI_EXECUTION_ENABLED=true arms catalog-bound official V2 order, cancel, and caller-credentialed refresh. Caller apiKeyId + RSA privateKeyPem transit one request and are never stored or logged; optional non-negative subaccount is submit-only. client.accounts.kalshi remains the separate direct, account-backed RSA lane whose credentials stay entirely local.
Limitless	Armed; geo-gated	Build, submit, and cancel are advertised. Verified 2026-08-16: restricted production egress receives 403 GEO_BLOCKED, including on status reads, despite the credential-free status implementation.
Myriad	Armed 2026-08-15: build + submit + cancel	BSC Order Book only. Wallet-bound HMAC credentials transit submit/cancel after EOA recovery; AMM order ids and status refresh remain unsupported.
Opinion	Armed: build + submit + cancel; hosted submit blocked	The hosted builder relay remains venue-rejected from Railway US egress. The working direct SDK path keeps the caller’s key in-process; no automatic hosted poll exists.
Pascal	Armed 2026-08-12; fleet-verified 2026-08-15: build + submit + cancel	Client-signed place/cancel permits retain no private key. Status refresh CORRECTED 2026-08-18: it does exist and needs no credential — Pascal’s account reads are keyless, so the background reconciler polls it too. No account or funding-helper lane exists; collateral funding remains venue-directed.
Polymarket	Armed: build + submit + cancel; hosted submit blocked	client.accounts.polymarket is the working caller-direct architecture. The hosted relay remains venue-rejected from Railway US egress; one eligible-wallet direct lifecycle pass remains before a production-live direct claim.
Polymarket US	Armed 2026-08-15: build + submit + cancel	Catalog-bound limit order, transient Ed25519 request auth, cancel, and caller-initiated refresh are implemented. Credentials and generated headers are never retained.
Predict.fun	Armed: build + submit + cancel; hosted route region-blocked	The deployed hosted route still returns 503 VENUE_REGION_BLOCKED. The caller-direct SDK path is source-ready and awaits one eligible submit → status live pass.
PredictStreet	Armed 2026-08-15: build + submit	VAULT orders on ADI Chain 36900. No cancel: PredictStreet’s API publishes no cancel endpoint at all, so cancelOrder: false is venue truth rather than an unarmed Predictefy flag. Submit does fold the venue’s own returned order status (PENDING/OPEN/FILLED/CANCELLED/EXPIRED/REJECTED) into the stored execution, but there is no separate hosted status-refresh read, account read, settlement lane, or automatic poll.
Rain	Armed 2026-08-15: build + submit + cancel	Approval, LIMIT/protected-market, cancel, and claim builds are implemented. Submit verifies and parks at signed; the caller owns broadcast.
XO	Rebuilt and re-armed 2026-08-18: build + submit + cancel	Chain-3223 orders on the venue’s current 13-field CTF contract; cancel and a client-credentialed status refresh are served. No hosted account read, funding helper, or automatic poll — a refresh is caller-initiated. Nothing has been submitted to XO yet, so the first live submit is the confirmation checkpoint.
PRED	Darked 2026-08-13; not in /v1/exec/venues	Source-ready Base Safe build/sign code remains documented, but the venue confirmed platform-key submits are refused. PRED_EXCHANGE_ADDRESSES is empty and there is no supported hosted credential path.

SX Bet client-side SDK execution

The table above covers hosted execution. SX Bet has no hosted execution integration. Its separate venue-direct SDK integration is available at client.accounts.sxbet. The private key, signatures, and optional SX Bet API key stay in the caller’s process and go only to sx.bet.

The shipped SX Bet write surface is:

• Maker limit orders: createOrder({ type: 'limit', ... }) posts to POST /orders/new with EIP-191 signing.
• Taker fills: createOrder({ type: 'market', ... }) posts to POST /orders/fill/v2 with EIP-712 signing. The first response is honestly PENDING; track it to SUCCESS or FAILED.
• Cancellation: cancelOrder/cancelOrders, cancelOrdersByEvent, and cancelAllOrders use the three EIP-712 cancel endpoints.
• Betting enablement: client.funding.buildPermitRequest builds the one-time EIP-2612 permit. SX Network USDC uses version "1"; its contract has no version() getter.
• Dead-man switch: armHeartbeat and disarmHeartbeat require the optional SX Bet API key. Trading itself is private-key-signature-only.

SX Bet prerequisites and depth status

The trading wallet must have a registered sx.bet account. A key-only wallet is rejected with INSUFFICIENT_KYC, even when its signature is correct. Betting must also be enabled once per token per network through TokenTransferProxy approval or one manual bet in the sx.bet UI.

Healed 2026-08-15: the earlier Railway-egress honest-empty book incident is historical. Production fetchOrderBook returned real two-sided SX Bet depth with 4 bids and 5 asks. That healing changes current book availability, not the execution boundary: SX Bet remains a venue-direct client-side SDK lane with no hosted execution integration.

This client-side integration does not imply hosted execution or unlisted verb coverage.

Smarkets client-side SDK execution

Smarkets is client-side only by owner decision taken on 2026-08-18, not because the venue lane was never built. The decision is a custody one: Smarkets authenticates with a full account email and password, and there is no scoped, revocable API credential to hold instead. A hosted lane would therefore mean Predictefy relaying credentials that control the whole account, which crosses the custody line this platform does not cross. A hosted lane remains a future maybe if the venue ever ships scoped keys; it is not planned work today.

The shipped write surface at client.accounts.smarkets is:

• createOrder({ marketId, outcomeId, side, amount, type }) — POST /v3/orders/. type: 'limit' sends a good_til_halted order; type: 'market' sends an aggressive immediate_or_cancel limit at buy 9999 / sell 1.
• cancelOrder(orderId) — DELETE /v3/orders/{id}/, then a read-back of the cancelled order.

Three venue facts shape it, and none of them is a Predictefy gap:

• Credentials never transit Predictefy. The email and password are sent only from your process to api.smarkets.com. The resulting session token lives in volatile memory and is never logged, returned, persisted, or sent to Predictefy. They still exist in your process, so prefer a dedicated, restricted account.
• The account must have venue API access. Smarkets rejects an ordinary account that has not been approved as an API user; that approval is granted by the venue, not by Predictefy.
• MFA-enabled accounts are refused. The SDK does not accept MFA secrets, so a login that returns an MFA factor raises NOT_SUPPORTED instead of prompting.

There is no modify verb and no hosted relay. amount is your own money at risk — back stake on a buy, lay liability on a sell — not Smarkets’ quantity pot; the client converts and floors so the relevant contribution never exceeds what you asked for.

Honest limitations

• fetchBalance on the hosted route intentionally returns 501 NOT_SUPPORTED. The SDK account path is separate: client.accounts.<venue> performs supported balance, position, and order reads directly from the venue with credentials that remain in your process.
• fetchPositions may be derived from this account’s recorded fills; inspect meta.derivation instead of assuming a venue-native portfolio response.
• Cancellation is venue-dependent. Public execution does not imply that every optional lifecycle action is supported by that venue.
• Hyperliquid serves one modifyOrder action at a time. The venue’s separate batchModify action is not shipped.
• Automatic order-status code exists for Hyperliquid and Limitless. Hyperliquid can use it credential-free; Limitless’s restricted production egress currently receives 403 GEO_BLOCKED, including on status reads. Rain is armed, but hosted submit stops at signed and the caller must broadcast before an on-chain receipt can advance it. Gemini, Kalshi, Polymarket, Opinion, and Predict.fun require caller-initiated credentialed refresh. PRED is darked and has no refresh implementation.
• The MCP surface registers exec_quote, exec_prepare, and exec_submit by default as of 2026-08-18; set MCP_ENABLE_TRADE=false for a read-only server. No one-shot spend or signing tool exists, and exec_submit previews unless passed confirm: true.
• Live venue status does not guarantee market availability, fill probability, price, or profit.