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
/api/rate-limits	GET	Public rate-limit budgets and endpoint-cost pointer
/api/markets/policy	GET	Market integrity and sensitive-market exclusion policy
/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/v1/aggregator/markets	GET	Normalized, attributed feed for odds comparison, directories, terminals, and routing partners
/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
/api/markets/requests	GET	Public demand queue for user-requested markets
/api/markets/requests/readiness	POST	Preflight a requested-market draft before wallet signing or creator outreach
/api/markets/requests/launch-packs	GET	Ranked request launch packs with maker briefs, social drafts, data angles, and institutional pilot framing
/api/markets/requests/maker-kit?id=123	GET	Dry-run maker activation kit for one public request, including first-order terms, risk caps, commands, and outreach copy
/api/markets/requests/maker-kit?queue=1	GET	Ranked zero-budget maker activation queue for finding requests that can recruit external first liquidity without house MM capital

See docs/public/AGGREGATOR_INTEGRATION.md for the stable partner contract, matching guidance, and SDK helper.

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

Request-readiness preflight is useful before asking a creator, bot, or maker to support a market. The response includes readiness scoring plus launchKit copy for maker outreach, X, YouTube Shorts, data-sales, institutional pilot, and bot-starter workflows:

curl -sS "$NORYNTA_BASE_URL/api/markets/requests/readiness" \
  -H 'content-type: application/json' \
  -d '{
    "question": "Will BTC close above $150,000 on Dec. 31, 2026?",
    "category": "Crypto",
    "end_timestamp": 1800000000,
    "outcomes": "Yes, No",
    "source_name": "Pyth",
    "source_url": "https://pyth.network/price-feeds/crypto-btc-usd",
    "observation_rule": "Resolve using the official BTC/USD close at the final timestamp.",
    "demand_evidence": "Traders want a clear BTC hedge market with first-maker interest.",
    "suggested_yes_probability": 55,
    "first_limit_order_intent": true
  }' | jq

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
/api/bot/quant	GET/POST	Agent-key targeted spread, midpoint, depth-band, stale-age, and market-state metrics

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/fees/estimate	GET, POST	Estimate CLOB maker/taker fees for price and size
/api/treasury/fee-config	GET	Live on-chain fee config when available
/api/clob/v2/config	GET	Public CLOB/RFQ limits, fee policy, and exposure-group support
/api/clob/v2/rfq/quote	POST	Request a signed maker quote
/api/clob/v2/rfq/accept	POST	Accept a signed RFQ quote
/api/clob/v2/rfq/network	GET	RFQ network and maker-broadcast capability discovery

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

Cash And Payment Rails

Endpoint	Method	Use
/api/deposit-options	GET	Country-aware deposit options plus settlementModel, paymentRails, and ledger-first routePlan metadata for the detected country
/api/withdrawal-options	GET	Country-aware withdrawal options plus settlementModel, paymentRails, and ledger-first routePlan metadata for Solana USDC, Base/EVM USDC, bridge, and local payout availability
/api/payment-rails/countries	GET	Public country payment-rail readiness catalog for multi-chain USDC, exchange transfer, card, bank, hosted onramp, bridge withdrawal, and local payout candidates
/api/payment-rails/countries?country=US	GET	Single-country payment rail plan, including staged local method hints such as ACH, SEPA, Pix, UPI, FPX, bank payout, and crypto fallback rails
/api/users/:id/fiat-deposit-intents	POST	Country-aware signed hosted fiat-to-USDC intent with Coinbase or Stripe Crypto Onramp support, settlement-network destination validation, and idempotent retry handling
/api/users/:id/fiat-transfers	GET	Signed user view of provider-backed fiat deposit and withdrawal status with signed direction/status/limit filters, redacted provider metadata, and lifecycle summary counts
/api/users/:id/fiat-withdrawal-beneficiaries/stripe-connect	POST	Country-aware signed Stripe Connect onboarding link creation for tokenized bank payout beneficiaries; stores only the connected-account token and sanitized status
/api/users/:id/fiat-withdrawal-requests	POST	Country-aware signed tokenized bank payout request with phone, compliance, idempotency, generic provider submit, and active-source Stripe Connect payout gates
/api/webhooks/payment-provider	POST	Signed provider settlement webhook for generic providers and Stripe callbacks; idempotently records events, validates amount/currency/user/country against stored intents, credits deposits, confirms payouts, updates Stripe Connect account readiness, and posts accounting ledger entries

Deposit and withdrawal history rows preserve legacy vault_ata / collateral_mint fields, but multi-rail reconciliation should read the structured settlement_network, settlement_adapter, provider, provider_reference, rail_code, destination_address, settlement_transaction_id, bridge_route, and settlement_metadata fields.

Fiat rails are candidates until provider coverage, jurisdiction review, KYC, accounting, reconciliation, proof controls, and canaries are ready. See docs/public/CASH_DEPOSITS_WITHDRAWALS.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