Skip to content
Docs

Norynta public docs

Norynta SDK And Examples

SDK, CLI, examples, and OSS integration guidance for Norynta bot and agent builders.

SDK and Examples

Purpose

This document explains which Norynta SDK, CLI, and example surfaces to use for different integration goals.

Audience

  • developers building new integrations
  • bot operators
  • AI agent teams
  • technical evaluators wanting executable examples

For the canonical integration entrypoint, start with:

  • docs/public/INTEGRATION_START_HERE.md

Main SDK surfaces

External SDK

Recommended for outside integrations:

  • packages/bot-sdk/src/sdk.ts
  • NoryntaClient from @norynta/bot-sdk

Use this when you are building an external bot, agent, or service that should not depend on Norynta's internal app code.

Internal app SDK

Used inside Norynta itself:

  • src/lib/bot/sdk.ts

Use this if you are extending the product internally and want the same helper patterns used by the app runtime.

Which surface should I use?

I want self-serve keys and implementation recipes

Use:

  • /developers

The developer portal provides API key management, quickstart commands, SDK recipes, a bot launch checklist, diagnostics, signed trading examples, popular OSS integration guidance, usage summary, and webhook status.

I want the fastest way to test discovery and market data

Use:

  • norynta from @norynta/bot-sdk
  • local wrapper: npm run bot:cli -- ...

I want to build an external integration in Node

Use:

  • packages/bot-sdk/src/sdk.ts
  • NoryntaClient
  • runDeveloperLaunchChecks
  • examples/developer-bot-launch.ts
  • examples/agent-external-sdk.ts
  • examples/market-watcher.ts

I want to build with popular OSS agent frameworks

Use the same HTTP, SDK, OpenAPI, and MCP surfaces with your framework executor:

  • Vercel AI SDK
  • LangChain.js
  • LlamaIndex.TS
  • OpenAI tools/function calling
  • n8n HTTP Request nodes
  • ElizaOS action providers
  • MCP-compatible assistants
  • Python agents through requests or generated OpenAPI clients

Keep read tools directly callable by the agent. Route buy/sell actions through a deterministic server executor that applies guardrails and produces wallet-signed requests.

I want to understand the internal app integration model

Use:

  • src/lib/bot/sdk.ts

CLI surface

Package binary:

  • norynta

Local helper:

  • scripts/bot-cli.ts

Example commands:

norynta doctor
npx -p @norynta/bot-sdk norynta discover
norynta snapshot btc-above-100k
norynta get '/api/events?limit=5'
npm run bot:cli -- doctor
npm run bot:cli -- discover
npm run bot:cli -- snapshot btc-above-100k
npm run bot:cli -- bulk --slugs btc-above-100k,eth-above-5k

doctor returns machine-readable pass, warn, and fail checks for discovery, schema availability, headers, read endpoints, first-trade check availability, SDK metadata, MCP guidance, and write-control status.

Endpoint cost and stream-contract discovery:

norynta get '/api/v1/developer/endpoint-costs'
norynta get '/api/v1/streams/manifest'

MCP surface (tool-using AI assistants)

Norynta exposes three MCP servers for tool-oriented runtimes:

  • public market/discovery tools: npm run mcp-public
  • trading tools: npm run mcp-trading
  • ops tools: npm run mcp-ops

MCP config template for clients is in:

  • .mcp.json

Validation:

npm run mcp:smoke

The public MCP server includes integration_compatibility, which reads the same standards-first compatibility metadata exposed by /api/bot/config.

Examples

Recommended launch starter:

npx tsx examples/developer-bot-launch.ts --mode watcher --base https://norynta.com
npx tsx examples/developer-bot-launch.ts --mode trader --event-pubkey EVENT_PUBKEY --outcome-index 0 --client-order-id bot-run-001

The trader mode performs discovery, bot config, market health, orderbook, and simulation checks when an event pubkey is supplied. Actual buy/sell writes still require wallet-signed payloads and the existing server-side trading controls.

  • examples/agent-bootstrap.ts
  • examples/agent-authenticated.ts
  • examples/agent-external-sdk.ts
  • examples/market-watcher.ts
  • examples/bot.ts

Run examples:

npx tsx examples/agent-bootstrap.ts
npx tsx examples/agent-authenticated.ts
npx tsx examples/agent-external-sdk.ts
npx tsx examples/market-watcher.ts

Recommended build path for a new bot

  1. discover capabilities
  2. fetch health and bulk snapshots
  3. subscribe to live stream(s)
  4. check intended writes
  5. place signed orders with deterministic IDs
  6. reconcile continuously

Maker Activation Path

  1. Start with global read-only discovery through /api/agent/access, /api/events/top, /api/events/:slug/snapshot, SSE streams, and the optional orderbook WebSocket service.
  2. Run sandbox/devnet conformance with npm run agent:conformance and the SDK examples before requesting live write access.
  3. Submit /liquidity intake with strategy, expected quoting cadence, markets, and links. Intake is stored as a maker lead in the GTM queue.
  4. Baseline real-money writes are globally available, including unknown-country requests. Approval into a maker cohort does not override wallet signatures, write controls, or higher-limit country verification.
  5. Production maker access must preserve nonce validation, signed orders, idempotent client order IDs, rate limits, circuit breakers, and surveillance.

Performance Targets

Use npm run test:perf:api with PERF_URL to load-test the public read path:

  • /api/events
  • /api/events/top
  • /api/events/:slug/snapshot
  • /api/clob/v2/orderbook

Set PERF_INCLUDE_WRITE_TARGETS=1 only with safe signed fixture bodies for RFQ quote and order-placement tests.

Common integration patterns

OpenClaw/OpenClaws and other OSS agent runtimes

Use the standards surface first: OpenAPI, stable schemas, MCP, SDK, and CLI. Norynta does not maintain a bespoke OpenClaw/OpenClaws adapter until an exact repository, version, and adapter contract are selected.

Discovery-first bootstrap

Best starting point:

  • examples/agent-bootstrap.ts

Use it to understand:

  • well-known discovery
  • agent card retrieval
  • authenticated access loading
  • config hydration

External SDK integration

Best starting point:

  • examples/agent-external-sdk.ts

Use it to understand:

  • SDK-first discovery
  • snapshot retrieval
  • first-trade check
  • resilient streaming

Market watcher / live reconciliation loop

Best starting point:

  • examples/market-watcher.ts

Use it to understand:

  • snapshot seeding
  • streaming updates
  • reconnect-aware state maintenance

Related docs

  • docs/public/INTEGRATION_START_HERE.md
  • docs/public/API_REFERENCE.md
  • docs/public/MARKET_DATA_DISCOVERY.md
  • docs/public/ORDERBOOK_AND_PRICING.md
  • docs/public/ERROR_CODES.md
  • docs/public/INTEGRATION_COMPATIBILITY_MATRIX.md
  • docs/public/MCP_GUIDE.md
  • docs/public/DEVELOPER_QUICKSTART.md
  • docs/DEVELOPERS.md
  • docs/public/API_OVERVIEW.md
  • docs/public/TRADING_INTEGRATION_WORKFLOW.md
  • docs/public/STREAMING_AND_RECONCILIATION.md