Introduction

Klyr is an OKX.AI Agent Service Provider (ASP). It exposes five operations over HTTP: 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://klyr-nu.vercel.app/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

Thesis

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

Structured claim

Klyr's extraction of subject, event, threshold, deadline, and direction from the thesis, plus any detected ambiguities.

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": "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"
}

{
  "intentId": "intent_...",
  "status": "MATCHED",
  "structuredClaim": { "subject": "Federal Reserve", "event": "rate reduction", ... },
  "marketCandidates": [
    { "market": { "marketId": "...", ... }, "matchLevel": "EXACT_MATCH", "recommendation": "PASS" }
  ]
}

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:...", ... } }

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