Skip to content
Docs

Norynta public docs

Norynta Auth And Rate Limits

Authentication, wallet-signed writes, retries, idempotency, and rate-limit guidance for external integrations.

Auth and Rate Limits

Purpose

This document explains how Norynta handles authentication, wallet-signed write flows, retries, idempotency, and rate limiting for external integrators.

Audience

  • API integrators
  • bot and agent developers
  • professional trading systems

Authentication model

Norynta integrations generally operate in one of three modes.

1. Public read access

Many read endpoints are publicly accessible, especially:

  • discovery surfaces
  • market data endpoints
  • snapshot and health endpoints
  • selected streaming endpoints

This is the fastest way to bootstrap an observer integration.

2. API-key-based access

If configured, authenticated discovery and related integration flows may require:

  • x-api-key: <key>
  • or Authorization: Bearer <key>

The most important authenticated discovery endpoint is:

  • GET /api/agent/access

Use it to learn live execution behavior for your environment.

3. Wallet-signed write access

Trading writes depend on wallet-authenticated request structures.

Do not hardcode assumptions when discovery metadata is available. Instead, read:

  • /api/agent/access → execution.safety.walletAuthHeaders

This is the correct place to learn current safety-header expectations.

Retry model

401 Unauthorized

  • do not retry blindly
  • refresh or correct credentials first

429 Too Many Requests

  • retry with backoff + jitter
  • reduce unnecessary polling
  • prefer snapshot + stream to many small REST calls

5xx

  • use capped exponential backoff
  • preserve logical request identity across retries

Validation or signature failures

  • treat as non-retryable until the payload is fixed

Idempotency guidance

For write-enabled integrations:

  • use deterministic client/request IDs
  • persist request identity across transport retries
  • avoid emitting a new logical order just because the network result is unclear
  • reconcile before replacing or replaying writes
  • log request hashes and stable IDs for replay diagnostics

Key discovery fields:

  • /api/agent/access → execution.idempotency
  • /api/agent/access → execution.retryPolicy
  • /api/agent/access → execution.safety

Rate limiting

Norynta applies public rate limiting per IP to maintain fairness and system stability.

Current published tiers:

  • CLOB tier: 1200 requests / 10 seconds
  • Events tier: 600 requests / 10 seconds
  • Data tier: 300 requests / 10 seconds

Machine-readable live policy:

curl -sS "$NORYNTA_BASE_URL/api/rate-limits" | jq

The response includes the deployed limit, window, environment override keys, keying model, and endpoint-cost reference.

Examples:

  • CLOB: GET /api/clob/v2/orderbook, GET /api/events/:slug/orderbook/stream
  • Events: GET /api/events, GET /api/events/top
  • Data: GET /api/events/:slug/snapshot

If you exceed the limit, expect 429 Too Many Requests.

Versioned v1 mutation endpoints include retry-budget hints on rate-limit responses when available:

  • Retry-After
  • X-RateLimit-Limit
  • X-RateLimit-Reset
  • response body retryAfterSeconds
  • response body rateLimit.limit
  • response body rateLimit.windowSeconds

Endpoint costs for the versioned integration surface are published at:

  • GET /api/v1/developer/endpoint-costs

Use this before load tests or high-volume bot runs:

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

Authenticated agent metadata may also include quota-profile fields:

  • /api/agent/access → agent.policy.quotaProfile.readsPerMinute
  • /api/agent/access → agent.policy.quotaProfile.writesPerMinute
  • /api/agent/access → agent.policy.quotaProfile.burst
  • /api/agent/access → agent.policy.quotaProfile.windowSeconds

Treat static public tiers as baseline limits. Treat endpoint costs and live agent metadata as the safer source for integration budgeting when present.

Production also uses Vercel Firewall for baseline DDoS protection and edge abuse controls. The default firewall posture rate-limits unauthenticated public read API traffic, denies common scanner paths, and runs Vercel bot/AI-bot managed rules in log mode unless operators explicitly raise them to challenge or deny.

Integration design guidance

To stay inside rate budgets:

  • discover once, cache intelligently
  • use bulk snapshot endpoints instead of many single-market calls
  • use streaming for incremental updates
  • reconcile periodically instead of polling every field continuously

Write-path safety guidance

Before enabling production writes, make sure:

  • request identity is deterministic
  • retry behavior is explicit
  • unknown write outcomes trigger reconciliation, not blind resubmission
  • signing requirements are validated against discovery metadata

Related docs

  • docs/DEVELOPERS.md
  • docs/public/API_OVERVIEW.md
  • docs/public/API_REFERENCE.md
  • docs/public/ERROR_CODES.md
  • docs/public/TRADING_INTEGRATION_WORKFLOW.md
  • docs/AGENT_INTEGRATION.md