---
title: "Create or join a Synthetic Book definition"
method: POST
path: "/v1/synthetics"
tags: ["Synthetic Books"]
---

# Create or join a Synthetic Book definition

`POST /v1/synthetics`

## Request

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

Creates an account-owned ten-minute lease for a canonical weighted book and returns the `synthetic_id` to subscribe to at `wss://stream.kairos.trade` with provider/topic `synthetic`.

Uses the caller's existing Kairos credential triple; no separate Synthetic Books credential, scope, or account allowlist is required. The full API-key triple also satisfies the mutation gate automatically.

Equivalent canonical definitions share a data-plane materialization but receive distinct account-owned lease UUIDs. Maximum 15 legs, depth 50, 25 active leases per user, and 30 create requests/minute/user by default.

## Request body

- SyntheticBookDefinitionRequest
  - `legs` SyntheticBookLeg[], required
    - `venue` string, required
    - `contract_id` string, required: Provider market/contract identifier used by the Kairos market-data stream.
    - `token_id` string: Provider outcome-token identifier. Required except for merged-book venues that accept outcome_index.
    - `outcome_index` integer: Outcome index for a merged-book venue when token_id is omitted.
    - `weight` string, required: Signed decimal quantity weight, encoded as a string with at most nine decimals.
  - `output_mode` 'bbo' | 'aggregated_l2' | 'decomposed_l2', required
  - `depth` integer, required
  - `classification` 'arbitrary_basket' | 'relative_value' | 'exact_equivalence' | 'complement' | 'partition' | 'implication' | 'range' | 'guaranteed_payout': Reviewed economic metadata; Kairos does not infer it from the formula.

## Response `200`

Lease created and canonical synthetic id returned.

- SyntheticBookCreateResponse
  - `synthetic_id` string, required
  - `subscription_id` string, uuid, required: Opaque account-owned public lease id. This is not the materializer's private numeric handle.
  - `created` boolean, required: True when this request created the canonical materialization; false when it joined an equivalent one.
  - `fees_updated` boolean, required
  - `sources_subscribed` integer, required
  - `expires_at_ms` integer, required
  - `ttl_ms` integer, required

## Other responses

- `400`: Invalid formula, leg, mode, classification, or depth.
- `401`: Missing or invalid account credentials.
- `403`: Invalid mutation credentials (including an invalid API-key triple).
- `409`: The account already has 25 active leases.
- `413`: Request body exceeds 64 KiB.
- `415`: Request body is not JSON.
- `429`: Creation rate limit exceeded.
- `502`: Private materializer unavailable or returned an invalid response.
- `503`: Synthetic Books is not configured on this execution node.

---

[API](https://skmtc.dev/kairos/apis/kairos-order-execution-api.md) - [All operations](https://skmtc.dev/kairos/apis/kairos-order-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kairos/apis/kairos-order-execution-api/revisions/9ba7d463d505?raw)