Skip to content
Docs

Norynta public docs

Norynta Agent Integration Guide

Canonical integration contract for AI agents, bots, quant clients, discovery, retries, and safety behavior.

Agent Integration Guide (Canonical)

This is the canonical integration doc for AI agents, bots, and quant clients.

Use this document as the single source of truth for:

  • discovery flow,
  • endpoint usage patterns,
  • retry + safety behavior,
  • quickstart validation.

Related docs:

  • docs/public/AGENT_BOT_READINESS_CHECKLIST.md (pre-launch checklist for AI agents, bots, and liquidity clients)
  • docs/public/INTEGRATION_START_HERE.md (fastest integration entrypoint)
  • docs/public/INTEGRATION_COMPATIBILITY_MATRIX.md (protocol/support snapshot)
  • docs/public/MCP_GUIDE.md (MCP server selection and safety)
  • docs/public/INTEGRATION_STABILITY_POLICY.md (compatibility guarantees)
  • docs/public/INTEGRATION_SNIPPETS.md (copy-paste quickstart calls)
  • docs/public/INTEGRATOR_CHANGELOG.md (integration-relevant changes)
  • docs/AGENT_LIQUIDITY_SANDBOX.md (orderbook-readiness bot conformance path)
  • docs/BOT_AGENT_OPERATIONS_CHECKLIST.md (operator monitoring and response checklist)
  • public/agents.md (short runtime cheat sheet)
  • docs/DEVELOPERS.md (broader developer guide)
  • public/openapi.json (OpenAPI contract)
  • public/api-schema.json (stable schema surface)

SDK and CLI surfaces:

  • External package SDK (recommended for agents): packages/bot-sdk/src/sdk.ts
  • Class-based API client: NoryntaClient from @norynta/bot-sdk
  • Internal app SDK (platform runtime): src/lib/bot/sdk.ts
  • CLI workflow helper: npm run bot:cli -- ... locally, norynta ... from the SDK package

1) 10-minute deterministic quickstart

  1. Start local app:
npm run dev

Quick one-command verification (recommended before manual endpoint checks):

npm run agent:quickstart
  1. Validate discovery surface:
curl -sS http://localhost:3000/.well-known/agent.json | jq '.ok, .card.id, .card.discovery'
curl -sS http://localhost:3000/api/agent/card | jq '.ok, .card.capabilities'
curl -sS http://localhost:3000/api/agent/access | jq '.ok, .endpoints.discover, .execution.idempotency'
  1. Validate bot data endpoints:
curl -sS 'http://localhost:3000/api/events/health?limit=5' | jq '.ok, .schemaVersion, (.events|length)'
curl -sS -X POST 'http://localhost:3000/api/events/snapshots' -H 'content-type: application/json' -d '{"slugs":[]}' | jq '.ok, .schemaVersion'
  1. Validate schema + docs consistency:
npm run openapi:check
npm run check:agent-docs
npm run bot:cli -- doctor
npm run bot:cli -- discover
npm run agent:conformance
  1. Validate SDK + CLI integration path:
# Published SDK surface (external integrators)
npm run bot:cli -- agent-card
npm run bot:cli -- agent-access
npm run bot:cli -- doctor
npm run bot:cli -- orderbook <eventPubkey> --outcome-index 0
npx tsx examples/developer-bot-launch.ts --mode watcher

2) Integration profiles

A. Read-only observer bot

Use when you only rank/monitor markets.

Recommended flow:

  1. GET /.well-known/agent.json
  2. GET /api/agent/card
  3. GET /api/bot/config
  4. GET /api/events/health
  5. POST /api/events/snapshots
  6. GET /api/events/:slug/stream for low-latency updates

B. Active trading bot (wallet-signed)

Use when placing/canceling orders.

Recommended flow:

  1. Complete read-only bootstrap
  2. Load execution hints from /api/agent/access
  3. Validate signing headers from execution.safety.walletAuthHeaders
  4. Check orderbook with GET /api/v1/markets/:id/orderbook
  5. Simulate or score the intended order with /api/v1/orders/validate and /api/v1/orders/estimate-impact
  6. Complete sandbox certification with /api/v1/sandbox/scenarios and /api/v1/sandbox/certification
  7. Place with POST /api/v1/orders using wallet signature, clientOrderId, and Idempotency-Key
  8. Cancel/reconcile with /api/v1/orders, /api/v1/orders/:id, and account fill endpoints

Recommended professional execution loop:

  1. Snapshot markets in bulk.
  2. Simulate intended execution before writing.
  3. Submit with deterministic clientOrderId.
  4. Treat idempotent_replay: true as a successful retry outcome.
  5. Read /api/v1/streams/manifest and maintain SSE plus periodic snapshot reconciliation for stale-connection recovery.

C. Capability-aware AI agent

Use when dynamically routing behavior by protocol features.

Recommended flow:

  1. Discover from /.well-known/agent.json
  2. Read protocol capabilities from /api/agent/card and /api/agent/access
  3. Branch logic on a2a, mcp, x402, and multiAgent flags

3) Stable discovery contract

Primary endpoints:

  • GET /.well-known/agent.json
  • GET /api/agent/card
  • GET /api/agent/access
  • GET /api/bot/config
  • GET /openapi.json
  • GET /api-schema.json

Standards-first compatibility metadata:

  • /api/bot/config → config.compatibility
  • /api/agent/access → compatibility
  • /api/agent/card → card.compatibility

The compatibility object advertises supported standards, entrypoints, auth expectations, schema headers, MCP servers, conformance commands, integration profiles, and named OSS adapter policy.

Headers:

  • X-Agent-Schema-Version on agent discovery endpoints
  • X-Api-Schema on health/snapshot endpoints

Authenticated agent metadata:

  • /api/agent/access may return an agent object when a valid API key is provided.
  • agent.profile may include operatorName, strategyType, riskTier, and feeTier.
  • agent.policy may include allowedProducts, allowedEndpoints, features, and quotaProfile.
  • Treat these fields as machine-readable execution and entitlement hints for routing, observability, and policy-aware behavior.

4) Error + retry handling contract

Current machine-readable error shape (where implemented):

{
  "ok": false,
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "retryable": false,
  "hint": "Provide x-api-key or Authorization: Bearer <key>"
}

Client behavior:

  • 401: do not retry blindly; refresh credentials.
  • 429: backoff + jitter, then retry.
  • 5xx: retry with capped exponential backoff.
  • GEO_BLOCKED, GEO_UNKNOWN, REAL_MONEY_COUNTRY_NOT_ALLOWED, and REAL_MONEY_COUNTRY_NOT_APPROVED: reserved for non-default country policies. Global baseline access should not fail on missing country metadata; do not retry through VPNs or proxy country spoofing.
  • trading pauses and disabled live-trading responses: stop writes and keep snapshot/stream reconciliation running.
  • Signature/validation failures: treat as non-retryable until payload is corrected.
  • 403 on write paths may indicate surveillance, entitlement, or policy restrictions; inspect machine-readable code and reasonCode.

5) Idempotency + safe execution guidance

When write-path idempotency is available/advertised in execution metadata:

  • generate deterministic client IDs,
  • persist IDs through retries,
  • avoid generating new nonces for transport retries,
  • log request hash + response signature for replay diagnostics.

Always read runtime behavior from:

  • /api/bot/config → execution.onboarding, execution.errorTaxonomy, and execution.internationalAccess
  • /api/agent/access → execution.idempotency, execution.retryPolicy, execution.safety
  • /api/agent/access → agent.profile, agent.policy for authenticated machine identity and policy hints

For high-volume execution clients:

  • prefer deterministic clientOrderId values scoped by strategy/run,
  • reuse the same signed payload when retrying transport failures,
  • check before routing large taker flow,
  • reconcile stream gaps with periodic bulk snapshots.
  • if you operate an authenticated bot, include your API key on trading writes so the platform can apply agent-aware quotas instead of generic shared-IP limits.

6) Reference examples

  • examples/agent-bootstrap.ts — discovery-first bootstrap
  • examples/agent-authenticated.ts — authenticated API-key bootstrap + first-trade check + resilient stream
  • examples/market-watcher.ts — snapshot + stream reconciliation loop
  • examples/bot.ts — simple health/snapshot + stream sample
  • examples/v1-certification.ts — v1 sandbox certification wrapper

Run examples:

npm run bot:example
npx tsx examples/agent-bootstrap.ts
npx tsx examples/agent-authenticated.ts
npx tsx examples/market-watcher.ts
npx tsx examples/v1-certification.ts

6.0) OSS agent runtime compatibility

OpenClaw/OpenClaws-style clients should integrate through the standards-first surface: HTTP/JSON, OpenAPI, stable schema headers, SSE, MCP, SDK, and CLI. Do not add a bespoke adapter until the exact repository, version, and adapter contract are pinned.

6.1) Event/market submission by agents (write path)

Agents and bots can submit new event requests through:

  • POST /api/markets/submit

Recommended authenticated payload (agent/bot):

{
  "submitterType": "agent",
  "question": "Will ETH be above $6,000 by 2026-12-31?",
  "category": "Crypto",
  "endTimestamp": 1798675200,
  "outcomes": ["Yes", "No"],
  "resolutionSource": "optimistic",
  "resolutionData": {
    "primary_source": "official exchange close",
    "observation_time": "market close",
    "cancellation_policy": "void_if_event_cancelled_or_unverifiable",
    "revision_policy": "official corrections before finalization apply"
  },
  "evidenceUrl": "https://example.com/reference",
  "demandEvidence": "Requested by desk strategy model",
  "nonce": "agent-run-123",
  "signature": "",
  "domain": "https://norynta.com",
  "cluster": "mainnet-beta",
  "expiresAt": "2026-12-30T00:00:00.000Z"
}

Notes:

  • Authenticated agents can use Authorization: Bearer <token> (preferred).
  • x-api-key remains supported for backward compatibility.
  • When ENABLE_AUTO_MARKET_SUBMISSION_APPROVAL=1, trusted submissions (policy-qualified agent/bot tier) can be auto-approved and auto-listed.
  • Non-qualified submissions remain in the review queue.

7) Compatibility matrix

  • OpenAPI paths: public/openapi.json
  • Stable schema fields: public/api-schema.json
  • Discovery schema version: X-Agent-Schema-Version
  • Health/snapshot schema version: X-Api-Schema

If you consume generated clients, pin versions and validate headers at runtime.