Skip to content
PredictefyPredictefy Docs
Get an API key

Build, sign, and submit an order

Copy page

Predictefy builds the order and relays it. You sign it. There is no generic signing route, and no user signing key is held here — so the loop has a shape that is not optional.

Trading & execution is the reference, including the build schema for every venue. This page is the loop and the failures.

The loop

Section titled “The loop”
  1. GET /v1/exec/venues — the authoritative list of armed lanes. Good market data on a venue does not mean it has an execution lane.
  2. POST /v1/exec/{venue}/orders/build — with a trade-scoped key and an Idempotency-Key. Returns an unsigned artifact and an executionId.
  3. Inspect and sign in your own process. What you sign is venue-specific — an EIP-712 payload for some lanes, a raw digest for others. Two lanes (Gemini, Polymarket US) are request-authenticated instead and the artifact is submitted unchanged.
  4. POST /v1/exec/{venue}/orders/submit — the executionId plus that venue’s signed fields.
  5. GET /v1/exec/{venue}/orders/{executionId} — poll for status. For a user-authenticated venue read, call refresh first.

client.exec.createOrder(params, signer) composes steps 2–4 for client-signing lanes. The signer callback receives only the unsigned artifact and returns venue-shaped signed fields; private keys never leave your process.

executionId binds everything

Section titled “executionId binds everything”

executionId is required on submit and binds the submission to one stored, already cap-checked execution.

  • Omitting it → 400 VALIDATION_ERROR.
  • Malformed, or simply not yours → 404 EXECUTION_NOT_FOUND. Never retry this — no retry can make a non-existent execution exist, which is why it is not classed as a retryable server error.

Idempotency is enforced, not advisory

Section titled “Idempotency is enforced, not advisory”

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 → 409 IDEMPOTENCY_CONFLICT.
  • Replaying against the same execution once it has left built → the current state comes back with Idempotency-Replay: true. No second relay, no second charge.

Generate one key per intended order and keep it with the order. Reusing a key as a retry token across different orders is the failure this design exists to catch.

Spend caps fail closed

Section titled “Spend caps fail closed”

Defaults are 100 USD per order and 1,000 USD per API key across a rolling 24 hours.

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 relaying, then reserves the submission. A cap violation is rejected — the service never silently reduces an order to fit.

The reservation behaviour is the part worth understanding:

  • Rejected before the venue was contacted → the reservation is freed.
  • 502 VENUE_RELAY_FAILED (ambiguous — the venue may or may not have received it) → the reservation is kept, so a resubmit cannot bypass the cap.

So an ambiguous failure consumes budget by design. Treat 502 as “state unknown, go and read the order”, not as “it failed, try again”.

What transits, and what does not

Section titled “What transits, and what does not”

Wallet signatures are produced entirely in your process. Some lanes need a transient venue credential at submit — an API key and secret, a session token — and those transit only when that venue needs them. They are not persisted and not logged. The per-venue table in Trading & execution lists exactly what each lane expects back.

Before you build

Section titled “Before you build”
  • Check the lane, not the venue. GET /v1/exec/venues returns per-venue build, submit, cancel, modify, redeem and gating. A venue can support build and not modify.
  • Scope the key. Execution needs the trade scope; a read key returns 403 SCOPE_MISSING.
  • Missing bounds keep a venue unavailable. Each lane enforces venue-specific contract, currency, chain, owner and artifact bounds. Unknown bounds fail closed rather than guessing.
Section titled “Related”