Skip to content
Docs

Norynta public docs

Norynta Trading Integration Workflow

Step-by-step trading integration workflow for orderbook reads, signed orders, reconciliation, and production safety gates.

Trading Integration Workflow

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