Routing

Create (or preview) a self-serve cross-venue market link

Declares that two markets on two different venues are the same real-world contract, making them routable together by GET /orders/route-quote, POST /orders/route-buy and POST /orders/route-close. Two-step by design. confirm: false (the default) returns a verified preview and writes nothing. Show the user the resolved pairing, then call again with confirm: true AND the preview's verification_fingerprint as fingerprint. The confirm re-resolves against fresh metadata and requires the result to fingerprint-match what was reviewed, so index drift between the two calls becomes a 409 ("review the pairing again") rather than a silently different link. You attest; the server verifies. Both legs are resolved against indexed market metadata and the link is REFUSED unless the venues' yes/no outcome labels pair exactly (case-insensitive). Outcome inversion is the one catastrophic failure mode here, so it is gated deterministically rather than by the user's click — a Yes/No vs Trump/Harris pair may well be the same market, but the mapping is not machine-provable and is refused rather than guessed. Scope of a created link. Links are approved but USER-SCOPED: routable only by their creator, so a bad self-link's blast radius is the creator's own wallet. Capped at 25 links per user, enforced inside the insert transaction so concurrent confirms cannot overshoot it. Expiry gaps and resolution-source divergence come back as warnings, not errors — for a self-scoped link they are the creator's risk to accept. Rate limited at 15 requests/minute per user (MARKET_LINK_RATE_LIMIT_PER_MIN), fail-closed. Previews count: every call costs two indexed-metadata lookups plus duplicate checks, and the 25-link cap only bounds completed inserts.

Error shape. This endpoint returns {"message": "..."} — NOT the {"error": ...} used everywhere else on this service, and with no code field. See OrderMarketLinkErrorResponse. Auth. Requires authentication and the mutation gate (API-key triple, X-Service-Token, or CSRF token). API keys and delegations need trade:execute, previews included; a created link steers the creator's later routed orders.

post/orders/market-links

Request

  • Base URL
    https://execution.kairos.trade
  • Auth
    API key in header X-Client-Id and API key in header X-Api-Key and API key in header X-Api-Secret

Request body

titlestring nullable

Optional display title. Trimmed, truncated to 512 characters; a blank value falls back to the first leg's market name.

similaritynumber double nullable

Matcher confidence, carried through for provenance only.

confirmboolean

false (the default) returns a verified preview and writes nothing. true inserts the link, and additionally requires fingerprint.

fingerprintstring nullable

REQUIRED when confirm is true — the verification_fingerprint from the preview. The confirm re-resolves against fresh metadata and requires the result to match what you reviewed, so index drift becomes a 409 rather than a silently different link.

Response

A verified preview, a newly created link, or an existing routable link — read status to tell which.

status'preview' | 'created' | 'exists' required

preview (nothing written), created (inserted), or exists (a link the caller can already route).

link_idstring uuid nullable

Null on a preview.

scope'global' | 'user' nullable

On exists, whether the existing link is global or the caller's own user link. Always user on created; null on preview.

titlestring nullable

Null on an exists response.

warningsstring[] required

Non-blocking advisories (venue expiry gaps, resolution-source divergence). Always includes the standing "venues may resolve on different data sources" notice.

verification_fingerprintstring required

16-hex-character hash of the verified identity material (ids, tokens, case-folded outcome labels). Echo it back as fingerprint on confirm. Change detection, not security.

Changes

No recorded changes to this operation across all 1 revision of this API.