> ## Documentation index
> Fetch the complete documentation index at: https://docs.predictefy.com/llms.txt
> Use it to discover every available page before exploring further.

# Build, sign, and submit an order

> The five-step execution loop, what each step guarantees, and the three failures worth handling before you write any of it.

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](/guides/trading/) is the reference, including the build schema for every
venue. This page is the loop and the failures.

## 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.

:::caution[The venue segment is part of the path]
Every execution route is `/v1/exec/{venue}/…`, not `/v1/exec/…`. There is no venue-less build or
submit route.
:::

## `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

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

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

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](/guides/trading/) lists exactly what each lane expects back.

## 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.

## Related

- [Trading & execution](/guides/trading/) — the full reference, per-venue build schemas, scopes
- [Accounts & funding](/guides/accounts/) — funding a venue before you can trade on it
- [Errors](/guides/errors/) — the envelope, and which codes are worth retrying
- [Monitor a multi-venue portfolio](/guides/cookbook/monitor-portfolio/) — reading the result