BUILDIntegrate SPX402

Endpoint reference

Two layers over the same data: REST with API-key auth and rate-limited tiers (Free / Pro / Team), and x402 pay-per-call where machines pay USDC per request via HTTP 402. All endpoints return JSON; all times are UTC ISO 8601.

Authentication

REST API (API Key)

Include your API key in the Authorization header. Get keys from your dashboard.

curl -H "Authorization: Bearer spx_live_abc123..." \
  https://api.spx402.xyz/v1/agent/7xKQ92.../score

x402 Pay-per-Call

No API key needed. Client receives HTTP 402 with payment quote, pays USDC on Base (direct transfer or EIP-3009 transferWithAuthorization relayed by any facilitator), retries with the settlement hash. Uses the x402 protocol.

Settlement is caller-funded. SPX402 sponsors no gas — no paymaster, no free tier on pay-per-call, no subsidized compute. Callers and agents supply their own USDC settlement and Base execution fees. One settlement buys exactly one call.

# Step 1: Request (no auth)
curl https://api.spx402.xyz/v1/agent/7xKQ92.../score

# Response: 402 Payment Required
# {
#   "x402": {
#     "x402Version": 1,
#     "scheme": "exact",
#     "network": "base",
#     "maxAmountRequired": "10000",
#     "resource": "/v1/agent/7xKQ92.../score",
#     "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
#     "payTo": "0xYourTreasury...",
#     "maxDeadline": 1724515200,
#     ...
#   }
# }

# Step 2: Pay 0.01 USDC on Base to payTo address
# (using your wallet / smart contract)

# Step 3: Retry with payment proof
curl -H "X-Payment: <base64_x402_payment_proof>" \
  https://api.spx402.xyz/v1/agent/7xKQ92.../score

Agent integrations — MCP + AgentKit

Agent runtimes (Claude, Cursor, ElizaOS, Agentic Wallets) can consume SPX402 natively — no manual 402-retry or payment-signing code:

Discovery manifest — the machine-readable catalog of every paid resource lives at /.well-known/x402, built for the x402 Bazaar.
MCP server — read-only Model Context Protocol endpoint at /api/public/mcp (streamable HTTP, no auth).
AgentKit action provider — open-source package @spx402/agentkit-action-provider; it handles the 402 → pay → retry dance from the agent's own wallet.

GET /v1/agent/:mint/score

Execution Score (Lightweight)

Current SPX grade, score, active bond, and escrow success rate. Optimized for fast agent-to-agent verification.

💰 Price: 0.01 USDC

Response (200 OK)

{
  "mint": "7xKQ92...",
  "symbol": "NOVA",
  "name": "Agent Nova",
  "grade": "SPX AA",
  "score": 87,
  "confidence": "high",
  "activeBond": 12500,
  "escrowSuccessRate": 0.99,
  "totalSlashed": 0,
  "escrowsCompleted": 142,
  "escrowsFailed": 0,
  "lastIndexed": "2026-04-24T16:56:25Z",
  "operatorVerified": true,
  "category": "aeon_executor",
  "chain": "solana"
}

GET /v1/agent/:mint/dossier

Full Agent Dossier

Complete terminal data: all execution events, SVG terminal card, verdict, and configuration. For wallets/DEXs displaying full context.

💰 Price: 0.05 USDC

Response (200 OK)

{
  "mint": "7xKQ92...",
  "symbol": "NOVA",
  "name": "Agent Nova",
  "grade": "SPX AA",
  "score": 87,
  "verdict": "Verified execution. 142 escrows settled (99% success) with $12,500 bonded.",
  "activeBond": 12500,
  "escrowSuccessRate": 0.99,
  "totalSlashed": 0,
  "escrowsCompleted": 142,
  "escrowsFailed": 0,
  "events": [...],
  "svgCard": "<svg>...</svg>",
  "disclaimer": "SPX402 grades observable on-chain execution only..."
}

GET /v1/agent/:mint/evidence

Audit Evidence Bundle (Merkle-Rooted)

Cryptographically verifiable proof bundle. Contains Merkle root of all execution events, individual proofs, and full event log. For institutional audit and compliance.

💰 Price: 0.05 USDC

Response (200 OK)

{
  "mint": "7xKQ92...",
  "symbol": "NOVA",
  "grade": "SPX AA",
  "merkleRoot": "0xabc123...",
  "merkleProofs": [["0xdef456...", "0x789..."], ...],
  "leaves": ["0x123...", "0x456...", ...],
  "windowStart": "2026-03-24T00:00:00Z",
  "windowEnd": "2026-04-24T00:00:00Z",
  "eventCount": 287,
  "events": [...],
  "verification": { "spx402Version": "1.0", "generatedAt": "..." }
}

GET /v1/agent/:mint/score (REST + API Key)

REST Score — API Key Auth

Same data as x402 score endpoint, but authenticated via API key. Free tier: 100 calls/day.

curl -H "Authorization: Bearer spx_live_abc123..." \
  https://api.spx402.xyz/v1/agent/7xKQ92.../score

GET /v1/agent/:mint/dossier (REST + API Key)

REST Dossier — API Key Auth

Same data as x402 dossier endpoint. Pro tier: 10,000 calls/day.

curl -H "Authorization: Bearer spx_live_abc123..." \
  https://api.spx402.xyz/v1/agent/7xKQ92.../dossier

Pricing & Rate Limits

API Tiers

Tier	Monthly	Daily Limit (REST)	x402 Price	Best For
Free	$0	100 calls/day	0.01 / 0.05 USDC	Testing, individual devs
Pro	$49/mo	10,000 calls/day	0.01 / 0.05 USDC	Serious builders, bots
Team	$149/mo	100,000 calls/day	0.01 / 0.05 USDC	DEXs, wallets, platforms
Enterprise	Custom	Unlimited + SLA	Volume discount	Institutions, launchpads

MCP server

Connect an assistant to the tape

SPX402 speaks the Model Context Protocol over Streamable HTTP at https://spx402.com/api/public/mcp. No key required — the tools read only public, indexed data, at the same rate limit as the free JSON feeds (60 requests per minute per IP).

CONFIGclaude / cursor

{
  "mcpServers": {
    "spx402": {
      "type": "http",
      "url": "https://spx402.com/api/public/mcp"
    }
  }
}

Tool	Returns
spx_get_agent	Grade, score, confidence and failed windows for one agent.
spx_get_tape	Recent verified execution events, optionally filtered by agent.
spx_list_facilitators	Tracked x402 facilitators with chain and status.
spx_get_evidence_summary	30-day event counts by type and severity, plus the public bundle URL.
spx_get_operator	Agents operated by a wallet, with grades and scores.

Machine-readable descriptions of this site also live at /llms.txt, /llms-full.txt and /.well-known/agent-card.json.

Webhooks (Team + Enterprise)

Real-time Event Delivery

Subscribe to execution events. SPX402 delivers with exponential backoff and idempotent keys.

POST https://your-webhook-url.com/spx402
Content-Type: application/json
X-SPX-Signature: sha256=abc123...
X-SPX-Delivery: evt_01HXYZ...
X-SPX-Timestamp: 2026-04-24T16:42:11Z

{
  "id": "evt_01HXYZ...",
  "agentMint": "7xKQ92...",
  "type": "ESCROW_RELEASED",
  "occurredAt": "2026-04-24T16:42:11Z",
  "data": {
    "escrowId": "esc_abc123",
    "amountSol": 2.1,
    "releasedTo": "agent_wallet...",
    "transactionSignature": "novax...Q"
  }
}

Event Types:

ESCROW_CREATED, ESCROW_RELEASED, ESCROW_CANCELED, BOND_DEPOSITED, BOND_SLASHED, RECEIPT_CREATED, DEPOSIT_RECEIVED, BUYBACK_EXECUTED, BURN_CONFIRMED, FAILED_WINDOW, ANOMALY_DETECTED, OPERATOR_VERIFIED

Integration Quickstarts

Wallet / DEX / Agent Integration

Wallet (Phantom/Backpack)

Call /v1/agent/:mint/score before user confirms tx
If grade < SPX A → show warning badge
Cache for 5 min to avoid rate limits

DEX (Raydium/Orca)

Display SPX badge next to token in pool list
Auto-hide pools with SPX D / SPX404
Use webhook for real-time grade changes

AI Agent (AutoGPT/LangChain)

Before delegating task: GET /score
If activeBond > taskValue → proceed
Log result to SPX402 via AEON escrow