Skip to content
Docs

Norynta public docs

Norynta Trading Integration Workflow

Step-by-step play integration workflow for orderbook reads, virtual positions, reconciliation, and experiment safety.

Trading Integration Workflow

Current product mode (2026-07-28): Norynta is play-only. Real-money trading, deposits, withdrawals, cash payouts, yield, and mainnet execution are postponed until further notice. Any such workflow retained below is historical or implementation reference, not an available product capability. See PLAY_MODE_GUIDE.md.

Purpose

This document explains how to build a safe, production-grade Norynta trading integration.

Audience

  • professional trading systems
  • active trading bots
  • AI agents that submit signed writes

Core idea

Strong trading integrations do not jump straight from market data to order placement. The safe pattern is:

  1. discover
  2. snapshot
  3. check
  4. write
  5. reconcile
  6. cancel or replace intentionally

First-order prerequisites

Before building a write request, make each dependency explicit:

  • an active developer API key with order-write access
  • the correct base URL, Solana cluster, and deployed Norynta program ID
  • a dedicated wallet signer kept outside browser and model-generated code
  • credited USDC collateral and enough SOL for network fees
  • an open event public key, outcome index, and inspected orderbook
  • a deterministic client order ID for submission and reconciliation

The /developers?tab=launch console turns these prerequisites into a copyable first-bet checklist. Use devnet for the first complete loop.

Step 1. Discover runtime behavior

Before enabling writes, read:

  • GET /.well-known/agent.json
  • GET /api/agent/card
  • GET /api/agent/access

Focus especially on /api/agent/access execution metadata:

  • execution.idempotency
  • execution.retryPolicy
  • execution.safety

Also read:

  • GET /api/bot/config
  • GET /api/clob/v2/config
  • GET /api/rate-limits

These expose fee policy, RFQ network status, exposure-group support, and public rate budgets.

Step 2. Build pre-trade market state

Typical inputs:

  • GET /api/events/:slug/snapshot
  • POST /api/events/snapshots
  • GET /api/events/:slug/stream
  • GET /api/events/:slug/orderbook/stream

Your strategy should know at least:

  • best bid/ask or current depth
  • recent trade activity
  • whether the market meets your liquidity threshold

Step 3. Simulate before writing

Use:

  • GET /api/clob/v2/orderbook

First-trade check should be the default path for:

  • large orders
  • taker-like flow
  • slippage-sensitive strategies
  • automated systems with tight loss tolerances

The goal is to understand:

  • expected fills
  • fees
  • guardrails
  • likely execution quality

Step 4. Submit signed writes safely

Primary endpoints:

  • POST /api/clob/v2/orders
  • POST /api/clob/v2/orders/batch
  • POST /api/clob/v2/rfq/quote
  • POST /api/clob/v2/rfq/accept

Safety guidance:

  • use deterministic clientOrderId values when supported
  • use exposureGroup for maker bots that need an open-share or rolling filled-share cap across related orders
  • preserve request identity across retries
  • do not treat transport uncertainty as permission to emit a new logical order
  • log request identity for replay diagnostics

Example exposure group:

{
  "clientOrderId": "maker-cpi-001",
  "exposureGroup": {
    "id": "maker:macro:cpi",
    "maxOpenShares": 250,
    "maxFilledShares": 100,
    "windowSeconds": 86400
  }
}

Step 5. Reconcile open intent and fills

Use a mix of:

  • POST /api/clob/v2/my-orders
  • live stream updates
  • periodic snapshot refresh

This protects your system from:

  • stale local books
  • unknown-write outcomes after network failure
  • duplicate intent after retry storms

Step 6. Cancel or invalidate intentionally

Use the narrowest cancel primitive that matches your need:

  • POST /api/clob/v2/cancel
  • DELETE /api/clob/v2/orders
  • DELETE /api/clob/v2/cancel-market-orders
  • DELETE /api/clob/v2/cancel-all
  • POST /api/clob/v2/cancel-all for nonce-based invalidation patterns

For single-order cancellation, treat canceled: true as the state-changing result. If the order already filled or closed, the response can be successful with canceled: false; reconcile before replacing.

Failure-handling model

401 Unauthorized

  • do not retry unchanged
  • correct credentials or auth headers first

429 Too Many Requests

  • use backoff + jitter
  • reduce polling pressure
  • prefer snapshot + stream over repeated small reads

5xx

  • retry carefully with capped exponential backoff
  • preserve logical request identity

Validation or signature failures

  • treat as non-retryable until fixed

Professional execution loop

Recommended loop:

  1. discover capabilities
  2. rank and snapshot markets
  3. check order readiness
  4. place with deterministic identity
  5. reconcile with streams and my-orders
  6. cancel or replace intentionally

Pre-production checklist

  • write retries are idempotent
  • orderbook readiness is part of the default flow
  • stream disconnect recovery is implemented
  • request logging includes stable IDs
  • auth failures are visible and actionable
  • rate-limit handling is tested

Related docs

  • docs/DEVELOPERS.md
  • docs/public/AUTH_AND_RATE_LIMITS.md
  • docs/public/STREAMING_AND_RECONCILIATION.md
  • docs/AGENT_INTEGRATION.md