Skip to main content
POST
Create RFQ

Authorizations

Authorization
string
header
required

Scoped API key (ttk_...), created in the Totalis app or by a wallet-session user through the API keys routes with a fresh wallet signature; those routes never accept a key. Each key acts for one account, yours or a maker's, and holds only scopes that account can use. Each operation lists the scopes it requires. Send no Origin.

Scopes

rfq:write

Headers

Idempotency-Key
string<uuid>
required

Lowercase UUIDv7 naming this command, unique per caller and route. A retry with the same key and body returns the original result; the same key with a different body returns 409 IDEMPOTENCY_KEY_REUSED.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Body

application/json

The entry RFQ to open: new legs and a stake, whose taker is the caller's account wallet. To sell a position you already hold, use POST /v1/me/positions/{position_id}/cashout instead.

intent_id
string<uuid>
required

Automatic-RFQ intent (UUIDv7) this RFQ belongs to. Send it with intent_generation, or omit both.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
intent_generation
string
required

Generation of the intent, as a decimal string. A higher generation atomically cancels the intent's open earlier RFQ; send it with intent_id.

Maximum string length: 19
Pattern: ^([1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$
stake
string<uint128-decimal>
required

Stake in atomic USDC (6 decimals), before taker fees; must be positive. Quotes carry the same stake.

Maximum string length: 39
Pattern: ^(0|[1-9][0-9]*)$
legs
object[]
required

1 to 5 legs in strictly increasing outcome_id order, at most one per native question. Every leg's market must have eligibility ENABLED and combo OPEN, and a chance on each side.

Required array length: 1 - 5 elements
builder_code
string

Optional partner attribution code, from any credential. From an account a partner admitted, it must be one of that partner's active codes and needs no signature; with none, the partner's account code is recorded. From any other account it needs builder_authorization_expiry and builder_signature from the partner's registered signer and is honoured only from the code's registered browser origin, so an API-key request (no Origin) from such an account cannot send one. A refused code returns INVALID_REQUEST naming /builder_code. Revocation rejects new RFQs without vetoing an already-created RFQ. Partners get codes from Totalis.

Pattern: ^tot_rfq_(local|testnet|staging|production)_[0-9a-f]{32}$
builder_authorization_expiry
string

Unix-second expiry, at most five minutes ahead, included in the builder authorization message. Send it with builder_signature only for an account no partner admitted; omit both otherwise.

Pattern: ^[1-9][0-9]{9,19}$
builder_signature
string

The partner's registered signer's personal_sign signature, made by the partner's server for one RFQ by an account no partner admitted. The message lines are Authorize Totalis RFQ builder attribution., Environment: <environment> (the environment in the builder code), Participant: <account UUID>, Idempotency key: <UUID>, Request digest: 0x<SHA-256> and Expiry: <builder_authorization_expiry>, joined by newlines. The request digest is SHA-256 of minified JSON with ordered keys intent_id and intent_generation when supplied, followed by stake, legs (as sent), builder_code and origin.

Pattern: ^0x[0-9a-f]{130}$

Response

The RFQ was created, or a retry with the same Idempotency-Key and body returned it. Makers receive it as RFQ_CREATED; their quotes reach you as QUOTE_CREATED on the account stream, and you accept one with POST /v1/quotes/{quote_id}/accept.

rfq_id
string<uuid>
required

ID of the new RFQ.