← Back to Alpha Court

API for Agents

AI agents can pay per request to analyze any token via the x402 protocol. No API keys, no subscriptions — just USDC micropayments on Base.

How it works

1

Request

Call any gated endpoint

2

402

Get payment requirements

3

Pay

Sign a USDC transfer

4

Result

Receive the response

Endpoints

POST/api/trial$1.00

Create a new debate trial for a token. Returns a trialId you can use to stream the debate and fetch the verdict.

Request body

{
  "tokenAddress": "EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm",
  "chain": "solana",
  "tokenName": "dogwifhat",
  "tokenSymbol": "WIF"
}

Response

{ "trialId": "abc123xyz", "cooldown": false }

Error responses

429 — Cooldown active (Retry-After header set)
  { "cooldown": true, "trialId": "...", "remainingSeconds": 3600,
    "hint": "Pay via x402 to bypass cooldown" }

400 — Invalid request
  { "error": "tokenAddress is required" }
  { "error": "Invalid solana address format" }

409 — Creation conflict (retry)
  { "error": "Trial creation conflict, please retry" }
GET/api/trials?limit=10Free

List recent completed trials. Use the returned trialIds to fetch verdicts. Limit defaults to 10, max 50.

Response

{
  "trials": [
    { "id": "abc123", "token_address": "EKpQ...", "token_symbol": "WIF",
      "chain": "solana", "verdict_label": "Buy", "verdict_score": 42, ... }
  ],
  "count": 10
}
GET/api/token/search?q=wif&chain=solanaFree

Search tokens by name, symbol, or address. Returns up to 10 results. Chains: solana, base, ethereum.

Response

{
  "results": [
    { "token_address": "EKpQ...", "token_symbol": "WIF",
      "token_name": "dogwifhat", "chain": "solana",
      "market_cap_usd": 780000000, "source": "nansen" }
  ],
  "source": "nansen"
}
GET/api/debate/{trialId}Free

Stream the live debate via Server-Sent Events. Events arrive in order: phase markers, agent messages with evidence, token stats, and finally the verdict.

Response

event: phase
data: {"phase":"bull_opening","status":"complete"}

event: message_complete
data: {"agent":"bull","phase":"opening","content":"...","evidence":[{"endpoint":"smart-money netflow","displayValue":"..."}]}

event: token_stats
data: {"tokenIconUrl":"...","priceUsd":1.23,"mcapUsd":1000000,"liquidityUsd":500000}

event: verdict
data: {"score":42,"label":"Buy","summary":"...","bull_conviction":78,"bear_conviction":35,"safety":"clean"}

event: error
data: {"message":"...","recoverable":false}

event: done
data: {}
GET/api/verdict/{trialId}Free

Get the final verdict JSON for a completed trial.

Response

{
  "score": 42,
  "label": "Buy",
  "summary": "Based on strong smart money inflows...",
  "bullConviction": 78,
  "bearConviction": 35,
  "safety": "clean",
  "createdAt": 1712750000,
  "completedAt": 1712750080
}

Error responses

202 — Trial in progress (Retry-After: 10)
  { "pending": true, "status": "debating", "trialId": "...",
    "hint": "Stream GET /api/debate/{trialId} for live updates" }

404 — Trial not found
  { "error": "Trial not found" }

Quick start

Install the x402 client SDK and wrap fetch with automatic payment handling:

npm install @x402/fetch @x402/core @x402/evm

import { wrapFetch } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(PRIVATE_KEY);
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(signer));
const fetch402 = wrapFetch(fetch, client);

// 1. Create a trial ($1.00 USDC — only paid endpoint)
const trial = await fetch402("https://alpha.cookd.wtf/api/trial", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    tokenAddress: "EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm",
    chain: "solana",
  }),
});
const { trialId } = await trial.json();

// 2. Stream the debate (free)
const debate = await fetch("https://alpha.cookd.wtf/api/debate/" + trialId);

// 3. Get the verdict (free)
const verdict = await fetch("https://alpha.cookd.wtf/api/verdict/" + trialId);
const result = await verdict.json();

Network & pricing

Payment tokenUSDC
Networkeip155:8453
Facilitatorhttps://api.cdp.coinbase.com/platform/v2/x402
PricingTrial $1.00 · Verdict & Debate free
Settlement~2 seconds on Base L2

Agent discovery

For machine-readable service discovery, fetch GET /.well-known/x402 — it returns a JSON document with all endpoints, pricing, payment config, and the recommended workflow.