x402-payable · onchain queries

Codex is the read-side API surface for Atrium. Eight endpoints expose margin, positions, risk decomposition, venue health, agent performance, research backtests, proof-of-reserves attestations, and option Greeks. Every response is HMAC-signed via X-Codex-Key-Id; every request pays in USDC via x402.

Quickstart

Get an x402 payment token from your wallet, send it as the X-PAYMENT header. Codex verifies on-chain settlement before serving the response.

# 1. Generate an x402 token via your wallet's x402 SDK
X402_TOKEN=$(./gen-x402.sh 0.001 0x...codex-address)

# 2. Call any Codex endpoint with the token
curl -H "X-PAYMENT: $X402_TOKEN" \
     https://atrium-codex.prtk8899.workers.dev/v1/margin/0xYourWallet

# Response (illustrative shape; values are an example, not a live read):
# {
#   "marginUsd": "125000.00",
#   "requiredMarginUsd": "48000.00",
#   "buyingPowerUsd": "77000.00",
#   "paused": false,
#   "source": "plinth",
#   "asOfBlock": 270918668
# }
# Headers: X-Codex-Key-Id: 1
#          X-Codex-Signature: 0xabc...

Try it

Calls the local testnet read route that backs this endpoint, so it needs no x402 payment. The per-user endpoints (margin, positions) read your account, so they need a connected, signed-in wallet; GET /venues and GET /attestation are public. Production Codex requires the X-PAYMENT header shown in the curl example for each endpoint.

Authentication

Payment: every endpoint requires an x402 USDC payment header. Missing or insufficient -> 402 with the price quote in the body.
Response signing: every response is HMAC-signed. Header X-Codex-Signature is the SHA256 HMAC of the response body; X-Codex-Key-Id is the rotation index so clients verify with the correct key.
Idempotency: pass X-Idempotency-Key (any UUID) for safe retries on non-pure reads. Cached for 24h.
Rate limits: 10 req/s per IP, 100 req/min per wallet, 1000 req/h per agent. Most restrictive applies. Hit a limit -> 429 withRetry-After header.

Endpoints

GET/margin/:user

$0.001 per calllive

Plinth margin number for a wallet. Returns collateral, required margin, buying power, paused state.

curl -H "X-PAYMENT: $X402_TOKEN" \
     https://atrium-codex.prtk8899.workers.dev/v1/margin/0xYourWallet

GET/positions/:user

$0.001 per calllive

Open positions across every Portico-whitelisted venue. Includes notional, entry, mark (when oracle live), unrealised PnL.

curl -H "X-PAYMENT: $X402_TOKEN" \
     https://atrium-codex.prtk8899.workers.dev/v1/positions/0xYourWallet

GET/risk/:user

$0.002 per calllive

Per-venue risk decomposition. Maps each venue to its share of total required margin + haircut applied.

curl -H "X-PAYMENT: $X402_TOKEN" \
     https://atrium-codex.prtk8899.workers.dev/v1/risk/0xYourWallet

GET/venues

$0.0005 per calllive

Live venue health table. Per-venue: deployed address, paused state, last oracle ts, notional cap remaining this block.

curl -H "X-PAYMENT: $X402_TOKEN" https://atrium-codex.prtk8899.workers.dev/v1/venues

GET/agents/:id/perf

$0.001 per calllive

Agent performance snapshot. 7/30/90 day PnL, total actions, failure rate, deboost tier, mandate count.

curl -H "X-PAYMENT: $X402_TOKEN" https://atrium-codex.prtk8899.workers.dev/v1/agents/augur/perf

GET/backtest/:strategy

$0.005 per calllive

Replay a published ResearchAttestation backtest. Returns IPFS notebook URL + delta bps + trade count.

curl -H "X-PAYMENT: $X402_TOKEN" https://atrium-codex.prtk8899.workers.dev/v1/backtest/mean-reversion-v1

GET/attestation/:wallet

$0.0005 per calllive

Lantern proof-of-reserves Merkle proof for a wallet. Returns latest root + the inclusion path.

curl -H "X-PAYMENT: $X402_TOKEN" \
     https://atrium-codex.prtk8899.workers.dev/v1/attestation/0xYourWallet

GET/options/:symbol

$0.002 per calllive

Stoa Black-Scholes Greeks for a tokenized option. Strike + expiry inferred from symbol.

curl -H "X-PAYMENT: $X402_TOKEN" https://atrium-codex.prtk8899.workers.dev/v1/options/rTSLA-DEC25-180C

SDK snippets

TypeScript (viem + x402)

import { x402Sign } from '@x402/core';
import { createWalletClient, http } from 'viem';
import { arbitrumSepolia } from 'viem/chains';

const wallet = createWalletClient({ chain: arbitrumSepolia, transport: http() });
const token = await x402Sign(wallet, { amountUsd: 0.001, recipient: CODEX_ADDR });
const res = await fetch('https://atrium-codex.prtk8899.workers.dev/v1/margin/' + userAddr, {
  headers: { 'X-PAYMENT': token },
});
const data = await res.json();

Python (httpx + web3)

from x402 import sign as x402_sign
import httpx

token = x402_sign(amount_usd=0.001, recipient=CODEX_ADDR, signer=wallet)
r = httpx.get(
    f'https://atrium-codex.prtk8899.workers.dev/v1/margin/{user_addr}',
    headers={'X-PAYMENT': token},
)
data = r.json()

Error codes

402 missing or insufficient x402 payment; body has price quote
429 rate-limited; body has retry-after
503 upstream subgraph or RPC unavailable; honest pending
404 user / agent / strategy not found