Skip to content
Docs

Norynta public docs

Norynta Developer Quickstart

Run the fastest developer smoke tests for Norynta discovery, market data, SDKs, and agent workflows.

Developer Quickstart

Purpose

This document gives external developers the fastest path from zero context to a working Norynta integration.

Audience

  • API integrators
  • bot developers
  • AI agent operators
  • trading teams validating Norynta quickly

Outcome

By the end of this quickstart, you should be able to:

  • discover Norynta capabilities
  • fetch market data
  • list events and inspect orderbooks
  • prepare deposits and withdrawals
  • place wallet-signed bets/orders
  • reconcile balances, deposits, withdrawals, orders, and trades
  • validate the schema contract
  • run the SDK/CLI path locally

This quickstart is read-first by default. Placing or canceling orders requires API-key access where enabled plus wallet-signed request payloads.

Prerequisites

  • Node.js 24.x
  • npm 11.18.x (activated from packageManager with Corepack)
  • jq for readable curl output
  • a running Norynta app, or a hosted base URL supplied by the Norynta team

For local development:

corepack enable npm
npm ci
cp .env.example .env.local
npm run dev

Set a base URL once for copy/paste commands:

export NORYNTA_BASE_URL="${NORYNTA_BASE_URL:-http://localhost:3000}"

If API keys are enabled for the target deployment:

export NORYNTA_AGENT_API_KEY="pmak_..."

Zero-to-signal in one command

After starting the app, run:

npm run agent:quickstart -- --base "$NORYNTA_BASE_URL"

Optional (also validates MCP server registration):

npm run agent:quickstart -- --base "$NORYNTA_BASE_URL" --with-mcp

This is the fastest health check for external integrations before deeper SDK or trading work.

Self-serve developer portal

Signed-in developers can create and manage personal API keys at:

  • /developers

The portal includes:

  • API key creation, rename, environment labels, and revoke controls
  • one-time secret display
  • SDK and CLI quickstart commands
  • buy/sell examples built around wallet-signed orders
  • OSS integration recipes for AI agents, MCP, generated OpenAPI clients, and automation tools
  • usage summary and recent delivery audit activity
  • a first-bet checklist covering wallet setup, funding, market selection, dry-run submission, and reconciliation

Self-serve keys identify and quota the agent. Trading writes still require the existing wallet-signed payloads, idempotency, surveillance, and compliance checks.

New self-serve keys are evaluation keys: one active key per account, 60 reads per minute, and a 15-minute delay on commercial market intelligence. They do not include historical intelligence, derived signals, normalized trade or position exports, stream replay, or webhook delivery. Those products require Builder Pro, Commercial, Enterprise, or an approved-maker entitlement.

Order and RFQ access remains available to self-serve developers because writes are wallet-signed. Real-time execution-critical feeds for production quoting require approved-maker review; approved-maker access is free and may not be used for data redistribution.

Billing and plan changes

Use /data to start Builder Pro or Commercial Data. The application redirects to hosted Stripe Checkout and provisions access only after a signed billing event. Use Manage billing on the same page to change or cancel the subscription. Plan status is available to the signed-in developer at:

curl -sS "$NORYNTA_BASE_URL/api/developer/billing/status" \
  -H 'cookie: <signed-in-session>' | jq

Do not treat a Checkout redirect or client success URL as proof of payment. Entitlements follow verified webhook state.

1. Start Norynta locally

npm run dev

If you only want a lightweight UI/runtime path:

npm run dev:fast

2. Discover the platform

curl -sS "$NORYNTA_BASE_URL/.well-known/agent.json" | jq
curl -sS "$NORYNTA_BASE_URL/api/agent/card" | jq
curl -sS "$NORYNTA_BASE_URL/api/agent/access" | jq
curl -sS "$NORYNTA_BASE_URL/api/bot/config" | jq

What you are learning here:

  • agent metadata and discovery URLs
  • protocol capabilities
  • execution hints
  • auth expectations
  • retry and idempotency guidance

3. Fetch market data

curl -sS "$NORYNTA_BASE_URL/api/events/health?limit=5" | jq
curl -sS "$NORYNTA_BASE_URL/api/v1/events?limit=5" | jq
curl -sS "$NORYNTA_BASE_URL/api/events/btc-above-100k/snapshot" | jq
curl -sS -X POST "$NORYNTA_BASE_URL/api/events/snapshots" \
  -H 'content-type: application/json' \
  -d '{"slugs":["btc-above-100k","eth-above-5k"]}' | jq

4. Use the stable v1 API surface

Raw HTTP integrations can use these stable aliases:

  • GET /api/v1/events
  • GET /api/v1/markets/:id/orderbook?outcomeIndex=0
  • POST /api/v1/orders with wallet signature and Idempotency-Key
  • GET /api/v1/deposit-options
  • GET /api/withdrawal-options
  • GET /api/v1/accounts/:publicKey/deposit-address
  • GET /api/v1/accounts/:publicKey/withdraw-address
  • GET /api/v1/accounts/:publicKey/deposits
  • GET /api/v1/accounts/:publicKey/withdrawals
  • POST /api/v1/accounts/:publicKey/withdrawals

Account and money-movement endpoints require the same signed secure-action context used by the web app: x-signature plus nonce, domain, cluster, and expiresAt query parameters.

5. Validate machine-readable contracts

npm run openapi:check
npm run check:agent-docs

Reference contracts:

  • public/openapi.json
  • public/api-schema.json

6. Try the CLI

npm run bot:cli -- doctor --base "$NORYNTA_BASE_URL"
npm run bot:cli -- discover --base "$NORYNTA_BASE_URL"
npm run bot:cli -- events --base "$NORYNTA_BASE_URL" --limit 5
npm run bot:cli -- snapshot btc-above-100k --base "$NORYNTA_BASE_URL"
npm run bot:cli -- deposit-options --base "$NORYNTA_BASE_URL"
npm run bot:cli -- get '/api/events?limit=5' --base "$NORYNTA_BASE_URL"

Signed CLI examples:

export NORYNTA_KEYPAIR="$HOME/.config/solana/id.json"
export NORYNTA_PROGRAM_ID="PROGRAM_ID"

npm run bot:cli -- deposit-address --chain solana --asset usdc
npm run bot:cli -- balance
npm run bot:cli -- deposits
npm run bot:cli -- withdraw-address --chain base --asset usdc --recipient 0x1111111111111111111111111111111111111111 --token-address 0x2222222222222222222222222222222222222222
npm run bot:cli -- withdrawals
npm run bot:cli -- place-order EVENT_PUBKEY --outcome-index 0 --side buy --price-cents 50 --size-shares 1 --client-order-id bot-order-001
npm run bot:cli -- place-order EVENT_PUBKEY --outcome-index 0 --side buy --price-cents 50 --size-shares 1 --client-order-id bot-order-001 --submit

First bet: complete developer path

Start on devnet. Use a dedicated wallet and keep private-key material in a controlled server-side executor, never in browser code or a model prompt. The API key identifies and quotas the integration; the wallet authorizes the order.

Set the hosted runtime, API key, signer, and program for the target environment:

export NORYNTA_BASE_URL="https://devnet.norynta.com"
export NORYNTA_AGENT_API_KEY="pmak_..."
export NORYNTA_KEYPAIR="$HOME/.config/solana/id.json"
export NORYNTA_SOLANA_CLUSTER="CLUSTER_SHOWN_IN_DEVELOPER_CONSOLE"
export NORYNTA_PROGRAM_ID="PROGRAM_ID_SHOWN_IN_DEVELOPER_CONSOLE"

Open https://devnet.norynta.com/developers?tab=launch for the first complete loop. The developer console prints the configured base URL, cluster, and program ID for its deployment. Keep all three values from the same deployment. If it reports that the program ID is not configured, stop before signing and ask Norynta support for the correct target-environment value.

Install the public SDK and verify access:

npm install https://norynta.com/sdk/norynta-bot-sdk-0.1.0.tgz @solana/web3.js
npx norynta doctor --base "$NORYNTA_BASE_URL" \
  --api-key "$NORYNTA_AGENT_API_KEY"

Prepare the account. Confirm the supported route, derive the signed deposit address, fund it with USDC, keep enough SOL for network fees, and wait for the balance to show credited collateral:

npx norynta deposit-options
npx norynta deposit-address --chain solana --asset usdc
npx norynta balance

Choose an open event and inspect its orderbook:

npx norynta events --limit 5
npx norynta orderbook EVENT_PUBKEY --outcome-index 0

Build the signed order without submitting it first:

npx norynta place-order EVENT_PUBKEY \
  --outcome-index 0 \
  --side buy \
  --price-cents 50 \
  --size-shares 1 \
  --client-order-id first-bet-001

After checking the market, price, size, side, and signed request, repeat the same command with --submit. Then reconcile instead of assuming a network timeout means failure:

npx norynta place-order EVENT_PUBKEY \
  --outcome-index 0 \
  --side buy \
  --price-cents 50 \
  --size-shares 1 \
  --client-order-id first-bet-001 \
  --submit

npx norynta my-orders
npx norynta balance

Trading is available only where the developer and wallet are eligible. Treat compliance blocks, signature failures, and validation errors as non-retryable; preserve the same client order ID when reconciling an uncertain write.

The hosted tarball installs as @norynta/bot-sdk. After installing it in another project, use the same commands through the package binary: norynta discover, norynta snapshot <slug>, and norynta get <api-path>.

7. Try the examples

BASE_URL="$NORYNTA_BASE_URL" npx tsx examples/agent-bootstrap.ts
BASE_URL="$NORYNTA_BASE_URL" npx tsx examples/agent-external-sdk.ts
BASE_URL="$NORYNTA_BASE_URL" npx tsx examples/market-watcher.ts

For a copyable external starter project, use examples/starter-bot/. It is a small standalone repo template for read-only discovery, dry-run order planning, and explicit limit-order submission after write mode is enabled.

For the default local target, the shorter form also works:

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

8. Decide your next path

Read-only integration

Continue with:

  • docs/public/API_OVERVIEW.md
  • docs/public/STREAMING_AND_RECONCILIATION.md
  • docs/public/INTEGRATION_STABILITY_POLICY.md

Trading integration

Continue with:

  • docs/public/AUTH_AND_RATE_LIMITS.md
  • docs/public/TRADING_INTEGRATION_WORKFLOW.md
  • docs/AGENT_INTEGRATION.md

Before enabling live writes, confirm:

  • target environment and cluster
  • wallet-signing implementation
  • deterministic clientOrderId or idempotency-key generation
  • retry behavior for 401, 429, 5xx, and unknown write status
  • stream reconciliation after disconnects

OSS and agent integration

Continue with:

  • /developers for portal recipes
  • docs/public/SDK_AND_EXAMPLES.md
  • docs/public/MCP_GUIDE.md
  • generated clients from public/openapi.json

Full platform guide

Continue with:

  • docs/DEVELOPERS.md

Related docs

  • docs/public/INTEGRATION_START_HERE.md
  • docs/DEVELOPERS.md
  • docs/public/API_OVERVIEW.md
  • docs/public/SDK_AND_EXAMPLES.md
  • docs/AGENT_INTEGRATION.md