Orderbook And Pricing

Purpose

This page explains how to read Norynta orderbooks, infer prices, consume price history, and keep local market state reliable.

Public Orderbook Reads

Primary endpoint:

curl -sS "$NORYNTA_BASE_URL/api/clob/v2/orderbook?eventPubkey=<EVENT_PUBKEY>&outcomeIndex=0&depth=20" | jq

Versioned alias:

curl -sS "$NORYNTA_BASE_URL/api/v1/markets/<EVENT_PUBKEY>/orderbook?outcomeIndex=0&depth=20" | jq

Core query parameters:

Parameter	Required	Use
eventPubkey	yes	Market event public key for CLOB reads
outcomeIndex	no	Outcome index, default 0
depth	no	Number of levels to return, clamped by the server

Representative response shape:

{
  "eventPubkey": "EVENT_PUBKEY",
  "outcomeIndex": 0,
  "bids": [{ "priceCents": 49, "shares": 120 }],
  "asks": [{ "priceCents": 52, "shares": 80 }],
  "marketState": "normal",
  "spreadCents": 3
}

Field Semantics

Field	Meaning
bids	Resting buy interest sorted from highest price downward
asks	Resting sell interest sorted from lowest price upward
priceCents	Outcome-share price in cents
shares	Available resting shares at that price level
marketState	empty, one-sided, normal, locked, or crossed
spreadCents	Best ask minus best bid when both sides exist

Market Structures

Event and snapshot responses may include marketStructure.

• binary: two outcome-token markets, usually Yes/No.
• categorical: mutually exclusive grouped outcome-token markets. The sum of fair values should target 100%, but each outcome still has its own CLOB.
• scalar_range: bucketed numeric outcomes. The orderbook price is still the price of that bucket's outcome token, while settlement may pay a deterministic payout vector. Scalar outcomes include range metadata, and finalized markets expose payout-per-share fields where available.

Binary Order Inversion

For binary Yes/No markets, an order on one outcome has an economically equivalent inverse on the opposite outcome:

buy Yes at 40c == sell No at 60c
sell Yes at 40c == buy No at 60c

Norynta orderbook helpers may include these equivalent rows so clients can read depth from either side of a binary market without missing liquidity resting on the opposite outcome. Inverted rows use:

Field	Meaning
inverted_from_outcome_index	Source outcome index that produced the equivalent row
outcomeIndex / outcome_index	Opposite binary outcome index
side	Inverted side, buy becomes sell and sell becomes buy
priceCents / price_cents	100 - sourcePriceCents

Clients should deduplicate by order id or source marker when displaying raw order rows. For executable depth, treat inverted rows as equivalent liquidity, not as extra independent orders.

Derived Prices

Clients can derive:

• best bid: bids[0].priceCents
• best ask: asks[0].priceCents
• spread: bestAsk - bestBid
• midpoint: (bestBid + bestAsk) / 2
• implied probability: priceCents / 100

Do not derive execution certainty from midpoint alone. For trading, evaluate depth at the intended size and use preflight endpoints before submitting writes.

Market State Handling

State	Client behavior
empty	Do not trade from local price assumptions
one-sided	Show available side, but treat midpoint/spread as unavailable
normal	Use best bid/ask and depth normally
locked	Reconcile before aggressive writes
crossed	Reconcile immediately; avoid relying on stale local depth

Price And Candle History

Line history:

curl -sS "$NORYNTA_BASE_URL/api/events/btc-above-100k/history?timeframe=1D&outcomeIndex=0&limit=100" | jq

Candles:

curl -sS "$NORYNTA_BASE_URL/api/markets/<MARKET_ID>/candles?timeframe=1D&outcome=yes&limit=96" | jq

Premium market intelligence history:

curl -sS "$NORYNTA_BASE_URL/api/data/market-intelligence/history?slug=btc-above-100k&outcomeIndex=0&timeframe=1D&metric=midpoint" \
  -H "Authorization: Bearer $NORYNTA_AGENT_API_KEY" | jq

Supported intelligence-history metrics include:

• midpoint
• spreadCents
• volumeUsd
• openOrders
• qualityScore
• activityScore

Activity And Last Trades

curl -sS "$NORYNTA_BASE_URL/api/events/btc-above-100k/activity" | jq
curl -sS "$NORYNTA_BASE_URL/api/v1/markets/btc-above-100k/trades" | jq

Use trade/activity history for display and analytics. Use orderbook reads for current executable depth.

Streaming Orderbooks

SSE orderbook stream:

curl -N "$NORYNTA_BASE_URL/api/events/btc-above-100k/orderbook/stream?outcomeIndex=0&snapshotEvery=10"

Event stream with optional top-of-book:

curl -N "$NORYNTA_BASE_URL/api/events/btc-above-100k/stream?includeOrderbook=1&outcomeIndex=0"

Reliable clients should:

1. seed from a REST snapshot,
2. process snapshot, delta, and heartbeat events,
3. reconcile after reconnect,
4. periodically refresh snapshots even without visible errors.

Pre-Trade Checks

For trading systems, read the book before writing:

curl -sS -X POST "$NORYNTA_BASE_URL/api/v1/orders/estimate-impact" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: estimate-demo-1' \
  -d '{"clientOrderId":"estimate-demo-1","sizeShares":10}' | jq

Before live submission, confirm:

• wallet signature freshness
• deterministic clientOrderId
• Idempotency-Key
• market state is not stale, locked, or crossed without reconciliation
• post-disconnect snapshots match local assumptions

Related Docs

• docs/public/API_REFERENCE.md
• docs/public/MARKET_DATA_DISCOVERY.md
• docs/public/STREAMING_AND_RECONCILIATION.md
• docs/public/TRADING_INTEGRATION_WORKFLOW.md