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

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