Market Data Discovery

Purpose

This guide explains how to discover Norynta markets, decide which markets are tradable, and hydrate enough state for bots, analytics, and trading systems.

Discovery Model

Norynta exposes markets through three complementary views:

1. Events for user-facing market discovery.
2. Health and snapshots for bot-friendly market quality.
3. Versioned aliases for stable external integrations.

Use the versioned aliases when you want a long-lived external contract. Use the native /api/events/* endpoints when you need the richest app-native shape.

Common Flow

1. Fetch a market list.
2. Filter by status, sort, and liquidity quality.
3. Pull health or snapshot records for candidates.
4. Start streams only for the markets you will actively watch.
5. Reconcile with snapshots on a timer.

List Markets

curl -sS "$NORYNTA_BASE_URL/api/events?status=active&sort=volume&limit=25" | jq
curl -sS "$NORYNTA_BASE_URL/api/v1/markets?status=active&sort=volume&limit=25" | jq

Odds-comparison sites, market directories, terminals, and routing partners should use the normalized aggregator feed instead of adapting the app-native event shape:

curl -sS "$NORYNTA_BASE_URL/api/v1/aggregator/markets?source=partner-name&limit=25" | jq

The feed defaults to markets with strict first-trade readiness. Pass tradableOnly=0 to include all public live market contracts for broader discovery. The returned urls.trade value includes privacy-safe UTM attribution for the supplied source.

Important query parameters:

Parameter	Use
status	Filter market lifecycle status
sort	Sort by the supported app ranking
cursor	Continue pagination
limit	Bound response size
includeEmptyV2	Include lower-liquidity v2 markets when supported
includeStale	Include stale markets for diagnostics
staleDays	Tune stale-market threshold
tradableOnly	Aggregator feed only: default 1; use 0 for all public live contracts
source	Aggregator feed only: partner slug used in attributed trade URLs

Search

curl -sS "$NORYNTA_BASE_URL/api/search?q=bitcoin" | jq

Use search for user-driven discovery and broad market lookup. Use GET /api/events or GET /api/v1/markets for deterministic bot pagination.

Fetch One Market

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

The :id in /api/v1/markets/:id may be a slug or event public key when the underlying deployment can resolve it.

Rank Candidates

Use top and health endpoints to avoid tracking markets that are stale, empty, or outside your strategy's quality threshold.

curl -sS "$NORYNTA_BASE_URL/api/events/top?limit=20&lookbackHours=24" | jq
curl -sS "$NORYNTA_BASE_URL/api/events/health?limit=20&minOpenOrders=2" | jq

Useful fields include:

• volume
• open order count
• last trade time
• best bid and best ask
• spread
• tradability status
• market quality signals

Bulk Snapshots

Bulk snapshots are the preferred way to hydrate or refresh many markets:

curl -sS -X POST "$NORYNTA_BASE_URL/api/events/snapshots" \
  -H 'content-type: application/json' \
  -d '{"slugs":["btc-above-100k","eth-above-5k"],"lookbackHours":24,"outcomeLimit":4}' | jq

Cacheable query form:

curl -sS "$NORYNTA_BASE_URL/api/events/snapshots?slugs=btc-above-100k,eth-above-5k" | jq

Combined Health And Snapshots

Use this when a bot needs both rankable market health and current outcome state:

curl -sS -X POST "$NORYNTA_BASE_URL/api/events/health-snapshots" \
  -H 'content-type: application/json' \
  -d '{"slugs":["btc-above-100k"],"healthLimit":10,"lookbackHours":24}' | jq

Market Detail Tabs And Public Context

Some event-page surfaces are useful for analytics and contextual agents:

Endpoint	Use
/api/events/:slug/activity	Recent trades/activity
/api/events/:slug/comments	Public discussion context
/api/events/:slug/holders	Public holder summary
/api/events/:slug/related	Related-market discovery
/api/events/:slug/resolution	Resolution status and metadata

Treat discussion and holder surfaces as context, not execution truth. Execution logic should use snapshots, orderbook reads, and signed write responses.

Discovery Checklist

• Cache discovery responses for short windows instead of polling every screen.
• Use bulk snapshot endpoints instead of many single-market requests.
• Require recent health before enabling aggressive strategy behavior.
• Start streams only after seeding from REST.
• Reconcile stream state with snapshots after reconnects.
• Read /api/v1/developer/endpoint-costs before load tests.

Related Docs

• docs/public/API_REFERENCE.md
• docs/public/ORDERBOOK_AND_PRICING.md
• docs/public/STREAMING_AND_RECONCILIATION.md
• docs/public/DATA_API.md