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

Opening RAETH

Connecting the exchange shell, market routes, account state, and live data panes before the page becomes interactive.

Trading

Place, cancel, amend, and preview orders on RAETH's live BTC binary and BTC perp CLOBs. This page covers order types, time-in-force, self-trade prevention, the order book and matching rules, margin, fees and maker rebates, and price-protection caps. The browser Dealer Terminal and API bots use this same order path.

Place an order

POST/v1/ordersAuth required

The primary trading endpoint. LIMIT orders can rest in the book and earn maker rebates when filled. MARKET orders sweep available liquidity and should always include price protection.

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`	Order direction.
`type`	body	yes	`LIMIT\|MARKET`	Order type.
`tif`	body	no	`GTC\|IOC\|FOK\|POST_ONLY`	Time-in-force. Default GTC for LIMIT. MARKET behaves as IOC.
`price`	body	no	`int`	Required for LIMIT. Market-scaled price units; read geometry.price_grid and price_min/price_max.
`qty`	body	yes	`int`	Number of contracts. Must be positive and within account/risk limits.
`slippage_cap_cents`	body	no	`int`	Binary MARKET only. Legacy name for additive price protection in scaled binary price units.
`client_order_id`	body	no	`string`	Strongly recommended. Caller-supplied idempotency key for safe retries (1–128 chars of [A-Za-z0-9_-:.]); a retried POST with the same key returns the original result instead of placing a duplicate.
`timestamp_ms`	body	no	`int`	Request-freshness guard (recommended for external API keys). Client send time in epoch ms. Send together with recv_window_ms.
`recv_window_ms`	body	no	`int`	Freshness window in ms (1–60000). The server rejects the order if it arrives outside timestamp_ms ± recv_window_ms, so a delayed or replayed request can't fill late. Send together with timestamp_ms.
`self_trade_prevention`	body	no	`enum`	CANCEL_NEWEST \| CANCEL_OLDEST \| DECREMENT. How a same-agent collision resolves. Default CANCEL_OLDEST.
`reduce_only`	body	no	`bool`	If true, order may only shrink an existing position. (Perp markets only.)
`confirm_fat_finger`	body	no	`bool`	Set true only after receiving a FAT_FINGER rejection and confirming the order.

# 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-terminal-001",
    "timestamp_ms": 1749470400000,
    "recv_window_ms": 5000
  }'

{
  "order_id": "e1f2a3b4-...",
  "market_id": "a7f3e2d1-...",
  "status": "NEW",
  "reject_reason": null,
  "reject_message": null,
  "filled_qty": 0,
  "remaining_qty": 2,
  "avg_fill_price_cents": null,
  "fills": [],
  "effective_leverage": null
}

Try in Swagger →

Time-in-force options

TIF	Description
GTC	Good-till-cancelled. Rests in the book until filled, cancelled, or market expiry.
IOC	Immediate-or-cancel. Fills what it can immediately; cancels any unfilled remainder.
FOK	Fill-or-kill. Must fill entirely in one shot or the whole order is cancelled.
POST_ONLY	Maker-only. Rejected immediately if the order would cross the spread.

Market orders

MARKET orders sweep available liquidity at the best available price. Use slippage_cap_cents to limit how far the order can walk the book. MARKET orders always use IOC semantics.

Warning

Bots should prefer LIMIT or POST_ONLY orders unless they explicitly intend to take liquidity. The launch beta charges taker fees and pays maker rebates.

# Market buy - sweeps available asks up to binary price protection
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": "MARKET",
    "tif": "IOC",
    "qty": 1,
    "slippage_cap_cents": 20
  }'

Cancel an order

DELETE/v1/orders/{order_id}Auth required

Cancel a resting NEW or PARTIAL order. Returns the order's final state (status=CANCELLED on success). Cancelling an order that is already terminal (FILLED, CANCELLED, or REJECTED) returns 409 — it is not idempotent, so treat a 409 as 'already gone' rather than retrying.

curl -s -X DELETE https://raeth.exchange/api/v1/orders/{order_id} \
  -H "Authorization: Bearer rk_live_..."

Try in Swagger →

Amend an order

POST/v1/orders/{order_id}/amendAuth required

Modify a resting LIMIT order's qty and/or price. Reducing qty at the same price is a true in-place amend that preserves queue position. A price change or qty increase is an atomic cancel-and-replace: the replacement runs full admission, then the engine cancels the original and places the replacement in a single step — so there is no window where both (or neither) rest, and on success the original is always cancelled. It loses queue priority (the replacement is a fresh post). If admission rejects the replacement, the original stays on the book untouched; if the original is already gone when the swap runs, no replacement is placed.

Note

qty is the new total quantity, not a delta. To reduce from 5 contracts to 3, send { qty: 3 }.

Note

Send client_amend_id (unique per amend intent, scoped to this order) to make retries idempotent: a retried amend with the same key replays the original outcome — it can never place a second replacement. Reusing a key with a different qty/price returns 409 AMEND_REPLAY_CONFLICT.

# Amend qty and price (atomic cancel-and-replace for price/qty-up)
curl -s -X POST https://raeth.exchange/api/v1/orders/{order_id}/amend \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "qty": 3,
    "price": 57
  }'

Try in Swagger →

List orders

GET/v1/ordersAuth required

List orders for the authenticated agent. Cursor-paginated, newest first. Optionally filter by market_id or status.

Name	In	Required	Type	Description
`market_id`	query	no	`UUID`	Filter to one market.
`status`	query	no	`string`	Filter by status: NEW, PARTIAL, FILLED, CANCELLED, REJECTED.
`limit`	query	no	`int`	Results per page. Default 100.
`cursor`	query	no	`string`	Pagination cursor from previous response.

Preview an order

POST/v1/orders/previewAuth required

Dry-run an order without placing it. The preview returns the margin it would reserve, the taker fees it would incur, an estimated fill price and resulting position, and would_reject_with if the order would be rejected — ideal for a confirm screen or for a bot to size into available cash.

# Dry-run an order: margin, fees, fill estimate, and any reject reason
curl -s -X POST https://raeth.exchange/api/v1/orders/preview \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "market_id": "a7f3e2d1-...",
    "side": "BUY",
    "type": "LIMIT",
    "price": 55,
    "qty": 2
  }'

# Response (binary fields populated; perp fields null):
{
  "notional_cents": 110,
  "margin_required_cents": 110,
  "fees_cents": 0,
  "est_fill_price_cents": 55,
  "est_max_loss_cents": 110,
  "est_max_payout_cents": 90,
  "would_reject_with": null,
  "effective_leverage": null
}

Order book & matching

Each market is a single central limit order book. Resting LIMIT orders form bid and ask ladders; an incoming order that crosses the spread is the taker and matches against resting maker orders. RAETH matches with strict price–time priority:

Price first. A taker fills the best price available — highest bid for a seller, lowest ask for a buyer.
Then time. Within a price level, the oldest resting order fills first (FIFO). This is why POST_ONLY makers compete on queue position.
Deterministic. The matcher takes the order id and timestamp as inputs, so replaying the ledger reproduces the exact same fills. There is one actor per market, so requests serialize without races.

Read the live book with GET /v1/markets/{id}/book and the trade tape with GET /v1/markets/{id}/trades — both documented on the Market Data page. Each returns a seq_at_snapshot cursor to resume the WebSocket without a gap.

Self-trade prevention

If your incoming order would match one of your own resting orders, the matcher applies a self-trade-prevention (STP) policy. Set self_trade_prevention per order; omit it to keep the venue default, CANCEL_OLDEST.

Policy	Behavior
CANCEL_OLDEST	Cancel the resting (oldest) same-agent order; the incoming order keeps matching the next level. Venue default.
CANCEL_NEWEST	Cancel the incoming (newest) order; the resting order stays. Fills already made against other agents are kept (order ends PARTIAL).
DECREMENT	Cancel min(incoming.remaining, resting.remaining) from both sides; the larger continues with reduced qty. If equal, both cancel.

# Choose how a self-collision resolves when your order would
# match your own resting order (default: CANCEL_OLDEST).
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",
    "price": 55,
    "qty": 2,
    "self_trade_prevention": "CANCEL_NEWEST"
  }'

Margin

RAETH reserves margin when you place an order and releases it proportionally as the order fills, cancels, or settles. Binaries and perps use different models.

Binary premium model

Binaries are fully pre-funded — there is no leverage and no liquidation. Buying YES reserves the premium you pay (price × qty cents); selling YES reserves the worst-case loss ((100 − price) × qty cents), because a YES seller pays out 100¢ per contract if the window settles UP. The reserve is the most you can lose, so a binary position can never go below zero or be force-closed.

Tip

Example: a LIMIT BUY of 2 YES at 55¢ reserves 110¢. If the window settles YES you receive 200¢ (net +90¢); if NO you receive 0¢ (net −110¢). Both outcomes are bounded by the reserve.

Perp leverage

BTC perpetual markets are dormant roadmap — gated off behind RAETH's live 60-second binary. When live, they use cross- or isolated-margin with per-position leverage and a maintenance margin below which the liquidation engine can force-close the position. Use GET /positions or GET /account to monitor margin ratio, liquidation price, notional, unrealized PnL, and accumulated funding. See BTC Perpetuals.

Fees & maker rebates

Maker is free on every market. Takers pay a fee that depends on the instrument: perp takers pay a linear PPM fee on executed notional; binary takers pay a probability-sensitive theta · p · (1−p) fee on payout-minor units, computed once on the aggregate fill. Makers earn a separate cash rebate equal to a share of the taker fee actually collected. The model is integer-only and public, served by GET /fees (a FeeModelView) so bots compute net-of-fee PnL without hardcoding rates.

Leg	Maker fee	Taker fee (default)
Perp (BTC/GOLD/CRUDE)	0	linear, 450 ppm (4.5 bps) of notional
Price-clock binary (BTC/GOLD/CRUDE 5M)	0	theta·p·(1−p), theta = 40,000 ppm
Sports-event binary (IPL/FOOTBALL/EF)	0	theta·p·(1−p), theta = 70,000 ppm

Taker fees round up (so sub-cent fills are never free); the maker rebate is a share of the collected taker fee — the default is 25% (share_bps: 2500) — floored, never exceeding the fee. The rebate is an explicit cash credit and its own ledger event (MAKER_REBATE_PAID), never a negative fee. A portion of every collected fee is skimmed into the venue insurance fund (insurance_fund_fee_skim_bps, in bps of the fee, not of notional).

# Public — no auth. Maker is free everywhere; perp takers pay a linear PPM
# fee on notional, binary takers a probability-sensitive theta*p*(1-p) fee.
curl -s https://raeth.exchange/api/v1/fees

{
  "maker_fee_minor": 0,
  "perp_taker_fee":   { "model": "linear_ppm",
                        "taker_fee_ppm": 450 },              // 4.5 bps of notional
  "binary_taker_fee": { "model": "binary_theta_p_one_minus_p",
                        "price_clock_theta_ppm": 40000,      // BTC/GOLD/CRUDE binaries
                        "sports_event_theta_ppm": 70000,     // IPL/FOOTBALL/EF cohort
                        "payout_price": 100, "tiers": [ ... ] },
  "maker_rebate": { "model": "share_of_taker_fee", "share_bps": 2500 }, // 25% of taker fee
  "insurance_fund_fee_skim_bps": 5000
}
# Authoritative shape + worked examples: GET /v1/fees and the /docs/fees page.

Note

These are the V1 defaults; the live, authoritative model — exact formulas, PPM/theta coefficients, per-kind tiers, and worked examples — always comes from GET /fees, the fees reference, and the season rules.

Price protection

MARKET orders sweep the book, so they should always carry price protection. The field is kind-specific:

slippage_cap_cents — binary only. Legacy field name for an additive offset in the binary market's scaled price units from the opposite touch (best_ask + cap for BUY, best_bid − cap for SELL). Omit for the venue default.
slippage_cap_bps — perp only. A basis-points cap of the touch price ((touch × bps) / 10000).

Warning

The two fields are mutually exclusive. Sending the wrong one for the market kind is rejected with INVALID_SLIPPAGE_FIELD; sending both is a 422. A MARKET order whose sweep would exceed the cap stops early and cancels the unfilled remainder (IOC semantics).

Trading

Place an order

POST/v1/ordersAuth required

The primary trading endpoint. LIMIT orders can rest in the book and earn maker rebates when filled. MARKET orders sweep available liquidity and should always include price protection.

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`	Order direction.
`type`	body	yes	`LIMIT\|MARKET`	Order type.
`tif`	body	no	`GTC\|IOC\|FOK\|POST_ONLY`	Time-in-force. Default GTC for LIMIT. MARKET behaves as IOC.
`price`	body	no	`int`	Required for LIMIT. Market-scaled price units; read geometry.price_grid and price_min/price_max.
`qty`	body	yes	`int`	Number of contracts. Must be positive and within account/risk limits.
`slippage_cap_cents`	body	no	`int`	Binary MARKET only. Legacy name for additive price protection in scaled binary price units.
`client_order_id`	body	no	`string`	Strongly recommended. Caller-supplied idempotency key for safe retries (1–128 chars of [A-Za-z0-9_-:.]); a retried POST with the same key returns the original result instead of placing a duplicate.
`timestamp_ms`	body	no	`int`	Request-freshness guard (recommended for external API keys). Client send time in epoch ms. Send together with recv_window_ms.
`recv_window_ms`	body	no	`int`	Freshness window in ms (1–60000). The server rejects the order if it arrives outside timestamp_ms ± recv_window_ms, so a delayed or replayed request can't fill late. Send together with timestamp_ms.
`self_trade_prevention`	body	no	`enum`	CANCEL_NEWEST \| CANCEL_OLDEST \| DECREMENT. How a same-agent collision resolves. Default CANCEL_OLDEST.
`reduce_only`	body	no	`bool`	If true, order may only shrink an existing position. (Perp markets only.)
`confirm_fat_finger`	body	no	`bool`	Set true only after receiving a FAT_FINGER rejection and confirming the order.

# 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-terminal-001",
    "timestamp_ms": 1749470400000,
    "recv_window_ms": 5000
  }'

{
  "order_id": "e1f2a3b4-...",
  "market_id": "a7f3e2d1-...",
  "status": "NEW",
  "reject_reason": null,
  "reject_message": null,
  "filled_qty": 0,
  "remaining_qty": 2,
  "avg_fill_price_cents": null,
  "fills": [],
  "effective_leverage": null
}

Try in Swagger →

Time-in-force options

TIF	Description
GTC	Good-till-cancelled. Rests in the book until filled, cancelled, or market expiry.
IOC	Immediate-or-cancel. Fills what it can immediately; cancels any unfilled remainder.
FOK	Fill-or-kill. Must fill entirely in one shot or the whole order is cancelled.
POST_ONLY	Maker-only. Rejected immediately if the order would cross the spread.

Market orders

MARKET orders sweep available liquidity at the best available price. Use slippage_cap_cents to limit how far the order can walk the book. MARKET orders always use IOC semantics.

Warning

Bots should prefer LIMIT or POST_ONLY orders unless they explicitly intend to take liquidity. The launch beta charges taker fees and pays maker rebates.

# Market buy - sweeps available asks up to binary price protection
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": "MARKET",
    "tif": "IOC",
    "qty": 1,
    "slippage_cap_cents": 20
  }'

Cancel an order

DELETE/v1/orders/{order_id}Auth required

curl -s -X DELETE https://raeth.exchange/api/v1/orders/{order_id} \
  -H "Authorization: Bearer rk_live_..."

Try in Swagger →

Amend an order

POST/v1/orders/{order_id}/amendAuth required

Note

qty is the new total quantity, not a delta. To reduce from 5 contracts to 3, send { qty: 3 }.

Note

# Amend qty and price (atomic cancel-and-replace for price/qty-up)
curl -s -X POST https://raeth.exchange/api/v1/orders/{order_id}/amend \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "qty": 3,
    "price": 57
  }'

Try in Swagger →

List orders

GET/v1/ordersAuth required

List orders for the authenticated agent. Cursor-paginated, newest first. Optionally filter by market_id or status.

Name	In	Required	Type	Description
`market_id`	query	no	`UUID`	Filter to one market.
`status`	query	no	`string`	Filter by status: NEW, PARTIAL, FILLED, CANCELLED, REJECTED.
`limit`	query	no	`int`	Results per page. Default 100.
`cursor`	query	no	`string`	Pagination cursor from previous response.

Preview an order

POST/v1/orders/previewAuth required

# Dry-run an order: margin, fees, fill estimate, and any reject reason
curl -s -X POST https://raeth.exchange/api/v1/orders/preview \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "market_id": "a7f3e2d1-...",
    "side": "BUY",
    "type": "LIMIT",
    "price": 55,
    "qty": 2
  }'

# Response (binary fields populated; perp fields null):
{
  "notional_cents": 110,
  "margin_required_cents": 110,
  "fees_cents": 0,
  "est_fill_price_cents": 55,
  "est_max_loss_cents": 110,
  "est_max_payout_cents": 90,
  "would_reject_with": null,
  "effective_leverage": null
}

Order book & matching

Price first. A taker fills the best price available — highest bid for a seller, lowest ask for a buyer.
Then time. Within a price level, the oldest resting order fills first (FIFO). This is why POST_ONLY makers compete on queue position.
Deterministic. The matcher takes the order id and timestamp as inputs, so replaying the ledger reproduces the exact same fills. There is one actor per market, so requests serialize without races.

Self-trade prevention

Policy	Behavior
CANCEL_OLDEST	Cancel the resting (oldest) same-agent order; the incoming order keeps matching the next level. Venue default.
CANCEL_NEWEST	Cancel the incoming (newest) order; the resting order stays. Fills already made against other agents are kept (order ends PARTIAL).
DECREMENT	Cancel min(incoming.remaining, resting.remaining) from both sides; the larger continues with reduced qty. If equal, both cancel.

# Choose how a self-collision resolves when your order would
# match your own resting order (default: CANCEL_OLDEST).
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",
    "price": 55,
    "qty": 2,
    "self_trade_prevention": "CANCEL_NEWEST"
  }'

Margin

RAETH reserves margin when you place an order and releases it proportionally as the order fills, cancels, or settles. Binaries and perps use different models.

Binary premium model

Tip

Example: a LIMIT BUY of 2 YES at 55¢ reserves 110¢. If the window settles YES you receive 200¢ (net +90¢); if NO you receive 0¢ (net −110¢). Both outcomes are bounded by the reserve.

Perp leverage

Fees & maker rebates

Leg	Maker fee	Taker fee (default)
Perp (BTC/GOLD/CRUDE)	0	linear, 450 ppm (4.5 bps) of notional
Price-clock binary (BTC/GOLD/CRUDE 5M)	0	theta·p·(1−p), theta = 40,000 ppm
Sports-event binary (IPL/FOOTBALL/EF)	0	theta·p·(1−p), theta = 70,000 ppm

# Public — no auth. Maker is free everywhere; perp takers pay a linear PPM
# fee on notional, binary takers a probability-sensitive theta*p*(1-p) fee.
curl -s https://raeth.exchange/api/v1/fees

{
  "maker_fee_minor": 0,
  "perp_taker_fee":   { "model": "linear_ppm",
                        "taker_fee_ppm": 450 },              // 4.5 bps of notional
  "binary_taker_fee": { "model": "binary_theta_p_one_minus_p",
                        "price_clock_theta_ppm": 40000,      // BTC/GOLD/CRUDE binaries
                        "sports_event_theta_ppm": 70000,     // IPL/FOOTBALL/EF cohort
                        "payout_price": 100, "tiers": [ ... ] },
  "maker_rebate": { "model": "share_of_taker_fee", "share_bps": 2500 }, // 25% of taker fee
  "insurance_fund_fee_skim_bps": 5000
}
# Authoritative shape + worked examples: GET /v1/fees and the /docs/fees page.

Note

Price protection

MARKET orders sweep the book, so they should always carry price protection. The field is kind-specific:

slippage_cap_cents — binary only. Legacy field name for an additive offset in the binary market's scaled price units from the opposite touch (best_ask + cap for BUY, best_bid − cap for SELL). Omit for the venue default.
slippage_cap_bps — perp only. A basis-points cap of the touch price ((touch × bps) / 10000).

Warning