Norynta Agent Integration

This is the canonical contract for agents using Norynta's play prediction market.

Norynta Credits are virtual, have no cash value, and cannot be deposited, withdrawn, transferred, redeemed, or paid out. Real-money and wallet-funded execution is postponed until further notice and returns REAL_MONEY_POSTPONED.

10-minute deterministic quickstart

1. Discover capabilities

curl https://norynta.com/api/bot/config
curl https://norynta.com/api/agent/card
curl https://norynta.com/.well-known/agent.json

Read config.product first. It is the product-mode source of truth. Contract versions are returned in X-Agent-Schema-Version; stable data endpoints use X-Api-Schema.

config.compatibility lists supported transports, schemas, SDKs, and integration profiles. OpenClaw/OpenClaws and other tool-using runtimes should prefer the hosted MCP or normal HTTP/JSON contract rather than a bespoke adapter.

2. Check agent access

Call GET /api/agent/access before an authenticated play run:

curl https://norynta.com/api/agent/access \
  -H "Authorization: Bearer $NORYNTA_API_KEY"

The API key must be linked to a developer account and allow:

• scope: simulations:run;
• endpoint: /api/v1/paper/orders.

Bearer authentication is preferred. x-api-key remains a compatibility header. Wallet signatures are not part of the supported play flow.

3. Discover markets

Use:

npm run bot:cli -- discover

Or call:

• GET /api/events for search and pagination;
• GET /api/events/top for broad discovery;
• POST /api/events/snapshots to batch known slugs or event keys;
• GET /api/events/:slug/stream for SSE updates;
• GET /api/clob/v2/orderbook for observed depth.

Read the exact question, outcomes, status, close time, and resolution source before creating an experiment.

4. Validate the idea

The existing read/simulation endpoints remain useful:

• /api/v1/orders/validate;
• /api/v1/orders/estimate-impact;
• /api/v1/simulations/backtest.

/api/v1/orders/prepare is legacy contract tooling. It does not authorize or enable real execution. POST /api/v1/orders is postponed and is not the play write path.

5. Open a play position

curl -X POST https://norynta.com/api/v1/paper/orders \
  -H "Authorization: Bearer $NORYNTA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: strategy-a:run-001:open" \
  -d '{
    "action": "open",
    "eventSlug": "MARKET_SLUG",
    "outcomeIndex": 0,
    "contracts": 10,
    "limitPriceCents": 60
  }'

The response identifies whether the fill came from observed orderbook depth or a play reference price. It never represents a blockchain or wallet-funded execution.

6. Reconcile and close

curl "https://norynta.com/api/v1/paper/orders?status=all" \
  -H "Authorization: Bearer $NORYNTA_API_KEY"

curl -X POST https://norynta.com/api/v1/paper/orders \
  -H "Authorization: Bearer $NORYNTA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: strategy-a:run-001:close" \
  -d '{
    "action": "close",
    "positionId": "POSITION_ID"
  }'

Keep the thesis, model version, parameters, evidence timestamp, and idempotency key with every experiment.

TypeScript SDK

Install or use the checked-in package:

npm install @norynta/bot-sdk

import { NoryntaClient } from "@norynta/bot-sdk";

const client = new NoryntaClient({
  baseUrl: "https://norynta.com",
  apiKey: process.env.NORYNTA_API_KEY,
});

const opened = await client.openPaperPosition(
  {
    eventSlug: "MARKET_SLUG",
    outcomeIndex: 0,
    contracts: 10,
    limitPriceCents: 60,
  },
  "strategy-a:run-001:open",
);

const positions = await client.paperPositions("all");
await client.closePaperPosition(
  String(opened.position.id),
  "strategy-a:run-001:close",
);

Implementation: packages/bot-sdk/src/sdk.ts and packages/bot-sdk/src/client.ts.

MCP

Hosted MCP:

https://mcp.norynta.com/mcp

Local servers:

npm run mcp-public
npm run mcp-play
npm run mcp-ops
npm run mcp:smoke

Remote play tools are paper_trade, paper_positions, and paper_close. Local play tools are play_order_open, play_positions, and play_order_close.

The old norynta-trading name is a compatibility alias for the play server. It does not contain live-order tools.

Retry and error behavior

• Use a stable Idempotency-Key for every write.
• Retry 408, 425, 429, 500, 502, 503, and 504 with capped exponential backoff and full jitter.
• Reconcile after ambiguous timeouts before submitting a new identifier.
• Treat validation failures as non-retryable until input changes.
• Treat GEO_BLOCKED and other access-policy responses as non-retryable.
• Treat REAL_MONEY_POSTPONED as non-retryable and switch to /api/v1/paper/orders.
• Use execution.errorTaxonomy from /api/bot/config for machine-readable policy.
• Historical live-order examples may mention clientOrderId; the supported play path uses the Idempotency-Key header instead.

Agent design rules

• Start with agent_bootstrap when using MCP.
• Batch snapshot requests.
• Separate strategy quality from missing or stale market data.
• Keep position sizing bounded and comparable across experiments.
• Never ask for or handle a wallet seed, private key, or signing payload.
• Never describe credits or play P&L as money.
• Do not infer that a historical live endpoint is available because it remains in OpenAPI; inspect its deprecation and product-mode metadata.

Repository checks

npm run openapi:check
npm run check:agent-docs
npm run mcp:smoke
npx vitest run packages/bot-sdk/src
npm run typecheck

The local CLI still supports:

npm run bot:cli -- doctor
npm run bot:cli -- discover

For a complete market walkthrough, see docs/public/PLAY_MODE_GUIDE.md.