API Reference

Purpose

This page is the human-readable reference map for Norynta's external API. Use it together with the machine-readable contracts:

• OpenAPI: public/openapi.json
• AsyncAPI: public/asyncapi.json
• Stable schema catalog: public/api-schema.json
• Versioned OpenAPI wrapper: GET /api/v1/openapi.json
• Versioned AsyncAPI wrapper: GET /api/v1/asyncapi.json

For a task-first path, start with docs/public/DEVELOPER_QUICKSTART.md.

Base URL

Use the deployment URL provided by Norynta, or local development:

export NORYNTA_BASE_URL="${NORYNTA_BASE_URL:-http://localhost:3000}"

Auth Modes

Mode	Used for	Headers
Public read	discovery, many market reads, selected streams	none
Agent API key	protected discovery, commercial data, developer diagnostics	Authorization: Bearer <key> or x-api-key: <key>
Wallet-signed write	order placement, cancellation, RFQ accept	API key when enabled plus wallet signature headers from /api/agent/access

API keys identify, quota, and scope the integration. Wallet signatures authorize trading writes.

Discovery And Contracts

Endpoint	Method	Use
/.well-known/agent.json	GET	Well-known agent discovery
/api/agent/card	GET	A2A-compatible capability card
/api/agent/access	GET	Auth state, execution metadata, idempotency, retry, safety, compatibility
/api/bot/config	GET	Bot polling, auth, error taxonomy, commercial plan metadata
/openapi.json	GET	OpenAPI contract
/api-schema.json	GET	Stable endpoint/schema catalog
/api/v1/status	GET	Versioned status, auth split, idempotency contract
/api/v1/agent/tools	GET	Agent-native tool manifest

Recommended startup probe:

curl -sS "$NORYNTA_BASE_URL/api/v1/status" | jq
curl -sS "$NORYNTA_BASE_URL/api/agent/access" | jq
curl -sS "$NORYNTA_BASE_URL/api/v1/agent/tools" | jq

Market Discovery

Endpoint	Method	Use
/api/events	GET	Event list with status, sort, cursor, and limit filters
/api/v1/events	GET	Versioned alias for event discovery
/api/v1/markets	GET	Versioned market discovery alias
/api/events/:slug	GET	Market/event detail by slug
/api/v1/markets/:id	GET	Versioned detail alias by slug or event public key
/api/events/top	GET	Ranked top markets with quality signals
/api/events/health	GET	Bulk health metrics for bots
/api/events/:slug/health	GET	Single-market health metrics
/api/search	GET	Search markets and app content

See docs/public/MARKET_DATA_DISCOVERY.md for workflow examples.

Snapshots And Health

Endpoint	Method	Use
/api/events/:slug/snapshot	GET	Unified market snapshot, health, best bid/ask, tradability
/api/events/snapshots	POST	Bulk snapshots by slug or event public key
/api/events/snapshots	GET	Cacheable bulk snapshots via query params
/api/events/health-snapshots	POST	Combined health and snapshots for bots
/api/events/health-snapshots	GET	Cacheable health and snapshots
/api/events/bot-snapshot	POST	Bulk ranked snapshots for bots

Use bulk endpoints for polling many markets. Use single-market endpoints for inspection, debugging, and event pages.

Orderbook And Pricing

Endpoint	Method	Use
/api/clob/v2/orderbook	GET	CLOB depth for eventPubkey, outcomeIndex, depth
/api/v1/markets/:id/orderbook	GET	Versioned orderbook alias
/api/events/:slug/orderbook/snapshot	GET	Event-slug orderbook snapshot
/api/events/:slug/orderbook/summary	GET	Orderbook summary for UI and bots
/api/markets/:id/candles	GET	OHLC candle history
/api/markets/:id/history	GET	Market history alias
/api/v1/markets/:id/history	GET	Versioned history/candles alias
/api/events/:slug/activity	GET	Recent trades/activity
/api/v1/markets/:id/trades	GET	Versioned trade/activity alias

See docs/public/ORDERBOOK_AND_PRICING.md for field semantics and examples.

Trading

Endpoint	Method	Use
/api/v1/orders/validate	POST	Preflight signed-order readiness
/api/v1/orders/estimate-impact	POST	Estimate size/depth impact
/api/clob/v2/orders	POST	Submit one signed limit order
/api/clob/v2/orders/batch	POST	Submit multiple signed limit orders
/api/clob/v2/orders	DELETE	Cancel one or more signed orders
/api/clob/v2/cancel	POST	Cancel one signed order
/api/clob/v2/cancel-all	POST	Set min nonce and invalidate older open orders
/api/clob/v2/cancel-all	DELETE	Cancel all open signed orders for a user
/api/clob/v2/cancel-market-orders	DELETE	Cancel open orders for a market or outcome
/api/clob/v2/my-orders	POST	List authenticated user's open signed orders
/api/clob/v2/data/orders	GET	Query public order records by id, market, owner, or asset
/api/clob/v2/rfq/quote	POST	Request a signed maker quote
/api/clob/v2/rfq/accept	POST	Accept a signed RFQ quote

All mutating order endpoints should use deterministic clientOrderId and Idempotency-Key values. See docs/public/TRADING_INTEGRATION_WORKFLOW.md.

Streams

Endpoint	Method	Use
/api/events/:slug/stream	GET	SSE trades and optional top-of-book
/api/events/:slug/orderbook/stream	GET	SSE orderbook snapshots, deltas, heartbeat
/api/v1/streams/manifest	GET	Stream contract, sequence policy, channel map
/api/v1/streams/replay	GET	Replay contract; refresh snapshots when storage is unavailable

The current production-safe stream path is SSE plus periodic snapshot reconciliation. The versioned stream manifest locks the future WebSocket contract shape for market, user, sports, and RFQ channels.

Commercial Data API

Endpoint	Method	Use
/api/data/market-intelligence	GET	Ranked market intelligence
/api/data/signals	GET	Derived trading and market-quality signals
/api/data/market-intelligence/history	GET	Premium time-series metrics
/api/data/trades	GET	Normalized historical trades
/api/data/positions	GET	Public wallet position export
/api/data/providers/official-sources	GET	Resolution/data provider source metadata

Commercial data endpoints may require agent/developer API keys and plan-level entitlements.

Developer Diagnostics

Endpoint	Method	Use
/api/developer/diagnostics	GET	Signed-in developer readiness checks
/api/developer/usage	GET	Developer usage summary
/api/v1/developer/endpoint-costs	GET	Endpoint cost and quota unit matrix
/api/v1/developer/request-logs	GET	Redacted request log contract
/api/v1/developer/latency	GET	Latency-stage contract
/api/v1/developer/explain-error	POST	Error code and request-id remediation

Endpoint costs are a contract for client budgeting and should be read before high-volume integration tests:

curl -sS "$NORYNTA_BASE_URL/api/v1/developer/endpoint-costs" | jq

Reference Generation

Validate the local contract before publishing integration changes:

npm run openapi:check
npm run check:agent-docs
npm run bot:cli -- doctor

Regenerate contracts when endpoint shapes change:

npm run openapi:generate

Related Docs

• docs/public/MARKET_DATA_DISCOVERY.md
• docs/public/ORDERBOOK_AND_PRICING.md
• docs/public/ERROR_CODES.md
• docs/public/AUTH_AND_RATE_LIMITS.md
• docs/public/STREAMING_AND_RECONCILIATION.md
• docs/public/TRADING_INTEGRATION_WORKFLOW.md