Introduction

Klyr is an OKX AI Agent Service Provider (ASP). It exposes five operations, available both over HTTP and via an MCP server (Streamable HTTP transport): submit_thesis, verify_market, preflight_execution, execute, and get_receipt. The first four are free; execute is gated by an x402 payment challenge, since it is the only operation that can result in a market action.

Quickstart

curl -X POST https://www.klyr.run/api/asp/submit_thesis \
  -H "content-type: application/json" \
  -d '{
    "thesis": "I believe the Federal Reserve will cut rates by at least 25 basis points before September 30, 2026.",
    "estimated_probability": 0.75,
    "max_position": 20,
    "mode": "review"
  }'

Core concepts

Interpretation and execution are deliberately separate. An LLM-backed interpreter turns natural language into a structured claim; everything after that is deterministic:

Natural language
  ↓
Interpreter (LLM)
  ↓
StructuredClaim
  ↓
Market Discovery
  ↓
Claim Matching
  ↓
Resolution Verification
  ↓
Risk Policy
  ↓
x402
  ↓
Execution

The interpreter fails closed: if a thesis is underspecified, it returns explicit ambiguities rather than guessing. For example, "Bitcoin will go up soon" returns status: AMBIGUOUS instead of inventing a threshold or deadline.

Thesis

The original, unstructured natural-language conviction as submitted. Preserved verbatim in every downstream artifact.

Structured claim

The interpreter's extraction of subject, event, threshold, deadline, and direction from the thesis, plus any detected ambiguities. Produced by an LLM-backed interpreter that fails closed rather than guesses.

Market candidate

A discovered market with an explicit claim-alignment comparison: subject, event, threshold, timeframe, direction - each PASS, BLOCK, or ESCALATE.

Resolution verification

Whether the selected market's actual resolution rules match the structured claim - the central question: if the thesis comes true, does this exact contract resolve YES?

Decision receipt

An immutable record of a completed decision: input, structured claim, market, verification, risk policy, execution outcome, and a decision hash.

Structures a thesis and returns ranked candidate markets. This is Stage 1-3 of the pipeline.

{
  "thesis": "Bitcoin will be above $150,000 by December 31, 2026",
  "estimated_probability": 0.65,
  "max_position": 50,
  "mode": "review"
}

{
  "intentId": "intent_...",
  "status": "CANDIDATES_FOUND",
  "structuredClaim": {
    "subject": "Bitcoin",
    "event": "price threshold",
    "threshold": "$150,000",
    "deadline": "2026-12-31T00:00:00Z",
    ...
  },
  "marketCandidates": [...]
}

Verifies a specific market's resolution rules and current state against the structured claim.

{ "intent_id": "intent_...", "market_id": "sim-fed-cut-sep30" }

{
  "status": "PASS",
  "resolutionVerification": { "status": "PASS", "extractedConditions": [...] },
  "marketState": { "overall": "PASS", ... }
}

Runs the deterministic risk policy against a proposed position size. Checks only - no execution.

{ "intent_id": "intent_...", "market_id": "sim-fed-cut-sep30", "amount": 20 }

{
  "decision": "APPROVED",
  "checks": { "marketMatch": "PASS", "resolution": "PASS", "marketState": "PASS", "riskPolicy": "PASS" },
  "riskPolicy": { "overall": "PASS", "maxPositionSize": 20, ... }
}

Runs preflight once more, then executes. Gated by x402 - an unpaid request receives HTTP 402 with a payment challenge. Idempotency-safe: replaying the same idempotency_key returns the original receipt.

{
  "intent_id": "intent_...",
  "market_id": "sim-fed-cut-sep30",
  "amount": 20,
  "idempotency_key": "unique-per-attempt"
}

{ "status": "PASS", "execution": { "status": "SIMULATED_FILLED", "dataMode": "SIMULATED" }, "receipt": { ... } }

Returns the stored decision receipt for a completed intent.

{ "receipt": { "receiptId": "receipt_...", "decision": "PASS", "decisionHash": "sha256:...", ... } }

MCP

Klyr also exposes an MCP server, for MCP-native clients that would otherwise call the HTTP endpoints above directly.

Supported tools are the same five operations described above: submit_thesis, verify_market, preflight_execution, execute, and get_receipt. An MCP client interacts with Klyr by calling tools/call with the tool name and its arguments, for example:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "submit_thesis",
    "arguments": {
      "thesis": "Bitcoin will be above $150,000 by December 31, 2026",
      "estimated_probability": 0.65,
      "max_position": 50,
      "mode": "review"
    }
  }
}

x402 payments

execute is wrapped with withX402. An unpaid request receives an HTTP 402 response with a payment-required header containing a base64-encoded payment challenge (scheme, network, amount, payTo). Payment settles only once the handler returns a successful response - a rejected (BLOCK or ESCALATE) decision still produces a real receipt, and the caller is charged for a decision either way, never for a validation error.

Error handling