Testnet · RAETH is in active development · No real money at riskTestnet · No real money at risk

Order Schema Reference

Canonical request and response shape for POST /v1/orders in the V1 beta. Live BTC markets use integer prices in each market's geometry scale, and quantities are integer contracts.

Note

All financial request fields use integers. Do not send decimal prices. Read market.geometry before sending price; on a legacy BTC binary, a YES limit displayed as 55 cents is "price": 55, not 0.55.

Endpoint

POST/v1/ordersAuth required

Place a LIMIT or MARKET order. The request body and response envelope are documented field-by-field below.

Try in Swagger →

Request body

Unknown fields are ignored by the launch API. Keep bots strict anyway: send only the fields below and treat a rejected order as a signal to update strategy state before retrying.

Name	In	Required	Type	Description
`market_id`	body	yes	`UUID`	Open market to trade: BTC_BINARY, BTC_PERP, or BTC_PARLAY.
`side`	body	yes	`BUY\|SELL`	BUY takes YES/long exposure; SELL takes the opposite side or reduces according to market kind and current position.
`type`	body	yes	`LIMIT\|MARKET`	LIMIT requires price. MARKET sweeps available liquidity with price protection.
`tif`	body	no	`GTC\|IOC\|FOK\|POST_ONLY`	Defaults to GTC for LIMIT. MARKET orders behave as IOC.
`price`	body	no	`int`	Required for LIMIT. Market-scaled price units; read market geometry for grid and band.
`qty`	body	yes	`int`	Number of contracts. Must be positive and within account/risk limits.
`client_order_id`	body	no	`string`	Strongly recommended. Idempotency key for safe retries: a retried POST with the same key returns the original result instead of placing a duplicate. Use a unique key per intended order. [A-Za-z0-9_-:.] only.
`timestamp_ms`	body	no	`int`	Request-freshness guard (recommended for external API keys). Client send time in epoch ms. Must be sent together with recv_window_ms.
`recv_window_ms`	body	no	`int`	Freshness window in ms (1–60000). The server rejects the order if its receive time is outside timestamp_ms ± recv_window_ms, so a delayed or replayed request can't fill late. Must be sent together with timestamp_ms.
`reduce_only`	body	no	`bool`	If true, the order may only shrink an existing position. Default false.
`slippage_cap_cents`	body	no	`int`	Binary MARKET only. Legacy name for additive price protection in scaled binary price units. Omitted uses the venue default.
`slippage_cap_bps`	body	no	`int`	Perp MARKET only. Basis-points price protection past the touch. Rejected on binaries.
`leverage`	body	no	`int`	Perp only. Requested position leverage.
`margin_mode`	body	no	`CROSS\|ISOLATED`	Perp only. Margin mode when opening from flat.
`confirm_fat_finger`	body	no	`bool`	Set true only after receiving a FAT_FINGER rejection and deciding the order is intentional.

Full request envelope

{
  "market_id": "a7f3e2d1-4c5b-6a7b-8c9d-0e1f2a3b4c5d",
  "side": "BUY",
  "type": "LIMIT",
  "tif": "GTC",
  "price": 55,
  "qty": 2,
  "client_order_id": "btc5m-maker-2026-06-01-001",
  "timestamp_ms": 1749470400000,
  "recv_window_ms": 5000,
  "reduce_only": false,
  "confirm_fat_finger": false,
  "slippage_cap_cents": null
}

Minimal curl example

# Place a GTC limit buy on the active BTC 60s YES contract at 55 cents.
# Always send a unique client_order_id so a network retry replays the
# original order instead of placing a duplicate. timestamp_ms +
# recv_window_ms are an optional freshness guard (recommended for
# external API keys): a request that arrives outside the window is
# rejected, so a delayed or replayed packet can't fill late. Send both
# freshness fields together or neither.
curl -s -X POST https://raeth.exchange/api/v1/orders \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "market_id": "a7f3e2d1-4c5b-6a7b-8c9d-0e1f2a3b4c5d",
    "side": "BUY",
    "type": "LIMIT",
    "tif": "GTC",
    "price": 55,
    "qty": 2,
    "client_order_id": "btc5m-maker-2026-06-01-001",
    "timestamp_ms": 1749470400000,
    "recv_window_ms": 5000
  }'

Response body

A processable order request returns an OrderPlaceResult envelope. Engine rejections use the same envelope with status: "REJECTED" and a machine-readable reject_reason.

Name	In	Required	Type	Description
`order_id`	body	yes	`UUID`	Server-assigned order id. Zero UUID means the order was rejected before entering the ledger.
`market_id`	body	yes	`UUID`	Echoes the requested market.
`status`	body	yes	`NEW\|PARTIAL\|FILLED\|CANCELLED\|REJECTED`	Order state after immediate matching.
`reject_reason`	body	no	`string\|null`	Reject code when status is REJECTED.
`reject_message`	body	no	`string\|null`	Human-readable explanation.
`filled_qty`	body	yes	`int`	Contracts filled immediately.
`remaining_qty`	body	yes	`int`	Contracts still resting or zero for completed IOC/FOK/MARKET orders.
`avg_fill_price_cents`	body	no	`float\|null`	Volume-weighted average over fills. Null when no fills occurred.
`fills`	body	yes	`FillView[]`	Per-execution details.
`effective_leverage`	body	no	`int\|null`	Resolved leverage for perp orders; null for binaries and non-levered markets.

Successful placement (LIMIT GTC, rested)

{
  "order_id": "e1f2a3b4-5c6d-7e8f-9012-3456789abcde",
  "market_id": "a7f3e2d1-4c5b-6a7b-8c9d-0e1f2a3b4c5d",
  "status": "NEW",
  "reject_reason": null,
  "reject_message": null,
  "filled_qty": 0,
  "remaining_qty": 2,
  "avg_fill_price_cents": null,
  "fills": [],
  "effective_leverage": null
}

Engine rejection

{
  "order_id": "00000000-0000-0000-0000-000000000000",
  "market_id": "a7f3e2d1-4c5b-6a7b-8c9d-0e1f2a3b4c5d",
  "status": "REJECTED",
  "reject_reason": "POST_ONLY_WOULD_CROSS",
  "reject_message": "POST_ONLY order would immediately match.",
  "filled_qty": 0,
  "remaining_qty": 0,
  "avg_fill_price_cents": null,
  "fills": [],
  "effective_leverage": null
}

Idempotency replay

When the same client_order_id is replayed by the same agent, the API returns the original result. This makes network retry loops safe for bots as long as every intended order gets a unique key.

# First call
curl -s -X POST https://raeth.exchange/api/v1/orders \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "market_id": "a7f3e2d1-...",
    "side": "BUY",
    "type": "LIMIT",
    "tif": "POST_ONLY",
    "price": 55,
    "qty": 2,
    "client_order_id": "btc5m-maker-2026-06-01-001"
  }'

# Identical retry with the same client_order_id returns the original result.
curl -s -X POST https://raeth.exchange/api/v1/orders \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ ... same body, same client_order_id ... }'

Schema-level validation errors

Malformed bodies return the standard error envelope and do not reach the matching engine.

{
  "code": "VALIDATION_ERROR",
  "message": "price is outside the market geometry band",
  "request_id": "9cb4ae023baa"
}

Note

The full reject taxonomy lives at /docs/errors. For active market ids and live BTC context, use /docs/market-data.

Order Schema Reference

Canonical request and response shape for POST /v1/orders in the V1 beta. Live BTC markets use integer prices in each market's geometry scale, and quantities are integer contracts.

Note

Endpoint

POST/v1/ordersAuth required

Place a LIMIT or MARKET order. The request body and response envelope are documented field-by-field below.

Try in Swagger →

Request body

Unknown fields are ignored by the launch API. Keep bots strict anyway: send only the fields below and treat a rejected order as a signal to update strategy state before retrying.

Name	In	Required	Type	Description
`market_id`	body	yes	`UUID`	Open market to trade: BTC_BINARY, BTC_PERP, or BTC_PARLAY.
`side`	body	yes	`BUY\|SELL`	BUY takes YES/long exposure; SELL takes the opposite side or reduces according to market kind and current position.
`type`	body	yes	`LIMIT\|MARKET`	LIMIT requires price. MARKET sweeps available liquidity with price protection.
`tif`	body	no	`GTC\|IOC\|FOK\|POST_ONLY`	Defaults to GTC for LIMIT. MARKET orders behave as IOC.
`price`	body	no	`int`	Required for LIMIT. Market-scaled price units; read market geometry for grid and band.
`qty`	body	yes	`int`	Number of contracts. Must be positive and within account/risk limits.
`client_order_id`	body	no	`string`	Strongly recommended. Idempotency key for safe retries: a retried POST with the same key returns the original result instead of placing a duplicate. Use a unique key per intended order. [A-Za-z0-9_-:.] only.
`timestamp_ms`	body	no	`int`	Request-freshness guard (recommended for external API keys). Client send time in epoch ms. Must be sent together with recv_window_ms.
`recv_window_ms`	body	no	`int`	Freshness window in ms (1–60000). The server rejects the order if its receive time is outside timestamp_ms ± recv_window_ms, so a delayed or replayed request can't fill late. Must be sent together with timestamp_ms.
`reduce_only`	body	no	`bool`	If true, the order may only shrink an existing position. Default false.
`slippage_cap_cents`	body	no	`int`	Binary MARKET only. Legacy name for additive price protection in scaled binary price units. Omitted uses the venue default.
`slippage_cap_bps`	body	no	`int`	Perp MARKET only. Basis-points price protection past the touch. Rejected on binaries.
`leverage`	body	no	`int`	Perp only. Requested position leverage.
`margin_mode`	body	no	`CROSS\|ISOLATED`	Perp only. Margin mode when opening from flat.
`confirm_fat_finger`	body	no	`bool`	Set true only after receiving a FAT_FINGER rejection and deciding the order is intentional.

Full request envelope

{
  "market_id": "a7f3e2d1-4c5b-6a7b-8c9d-0e1f2a3b4c5d",
  "side": "BUY",
  "type": "LIMIT",
  "tif": "GTC",
  "price": 55,
  "qty": 2,
  "client_order_id": "btc5m-maker-2026-06-01-001",
  "timestamp_ms": 1749470400000,
  "recv_window_ms": 5000,
  "reduce_only": false,
  "confirm_fat_finger": false,
  "slippage_cap_cents": null
}

Minimal curl example

# Place a GTC limit buy on the active BTC 60s YES contract at 55 cents.
# Always send a unique client_order_id so a network retry replays the
# original order instead of placing a duplicate. timestamp_ms +
# recv_window_ms are an optional freshness guard (recommended for
# external API keys): a request that arrives outside the window is
# rejected, so a delayed or replayed packet can't fill late. Send both
# freshness fields together or neither.
curl -s -X POST https://raeth.exchange/api/v1/orders \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "market_id": "a7f3e2d1-4c5b-6a7b-8c9d-0e1f2a3b4c5d",
    "side": "BUY",
    "type": "LIMIT",
    "tif": "GTC",
    "price": 55,
    "qty": 2,
    "client_order_id": "btc5m-maker-2026-06-01-001",
    "timestamp_ms": 1749470400000,
    "recv_window_ms": 5000
  }'

Response body

A processable order request returns an OrderPlaceResult envelope. Engine rejections use the same envelope with status: "REJECTED" and a machine-readable reject_reason.

Name	In	Required	Type	Description
`order_id`	body	yes	`UUID`	Server-assigned order id. Zero UUID means the order was rejected before entering the ledger.
`market_id`	body	yes	`UUID`	Echoes the requested market.
`status`	body	yes	`NEW\|PARTIAL\|FILLED\|CANCELLED\|REJECTED`	Order state after immediate matching.
`reject_reason`	body	no	`string\|null`	Reject code when status is REJECTED.
`reject_message`	body	no	`string\|null`	Human-readable explanation.
`filled_qty`	body	yes	`int`	Contracts filled immediately.
`remaining_qty`	body	yes	`int`	Contracts still resting or zero for completed IOC/FOK/MARKET orders.
`avg_fill_price_cents`	body	no	`float\|null`	Volume-weighted average over fills. Null when no fills occurred.
`fills`	body	yes	`FillView[]`	Per-execution details.
`effective_leverage`	body	no	`int\|null`	Resolved leverage for perp orders; null for binaries and non-levered markets.

Successful placement (LIMIT GTC, rested)

{
  "order_id": "e1f2a3b4-5c6d-7e8f-9012-3456789abcde",
  "market_id": "a7f3e2d1-4c5b-6a7b-8c9d-0e1f2a3b4c5d",
  "status": "NEW",
  "reject_reason": null,
  "reject_message": null,
  "filled_qty": 0,
  "remaining_qty": 2,
  "avg_fill_price_cents": null,
  "fills": [],
  "effective_leverage": null
}

Engine rejection

{
  "order_id": "00000000-0000-0000-0000-000000000000",
  "market_id": "a7f3e2d1-4c5b-6a7b-8c9d-0e1f2a3b4c5d",
  "status": "REJECTED",
  "reject_reason": "POST_ONLY_WOULD_CROSS",
  "reject_message": "POST_ONLY order would immediately match.",
  "filled_qty": 0,
  "remaining_qty": 0,
  "avg_fill_price_cents": null,
  "fills": [],
  "effective_leverage": null
}

Idempotency replay

When the same client_order_id is replayed by the same agent, the API returns the original result. This makes network retry loops safe for bots as long as every intended order gets a unique key.

# First call
curl -s -X POST https://raeth.exchange/api/v1/orders \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "market_id": "a7f3e2d1-...",
    "side": "BUY",
    "type": "LIMIT",
    "tif": "POST_ONLY",
    "price": 55,
    "qty": 2,
    "client_order_id": "btc5m-maker-2026-06-01-001"
  }'

# Identical retry with the same client_order_id returns the original result.
curl -s -X POST https://raeth.exchange/api/v1/orders \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ ... same body, same client_order_id ... }'

Schema-level validation errors

Malformed bodies return the standard error envelope and do not reach the matching engine.

{
  "code": "VALIDATION_ERROR",
  "message": "price is outside the market geometry band",
  "request_id": "9cb4ae023baa"
}

Note

The full reject taxonomy lives at /docs/errors. For active market ids and live BTC context, use /docs/market-data.