API Reference

Obol has three APIs, all gated by x402 payments on Base. Every request without a payment header returns a 402 with the payment requirements embedded in the response body.

api.obol.sh

AI code generation → GitHub PR

from $1 USDC

api2.obol.sh

Clanker token analytics

$0.01 USDC

loom.obol.sh

Shared AI compute marketplace

from $0.01 USDC

Payment details

NetworkBase (eip155:8453)

AssetUSDC — 0x8335...

Amount$5.00 USDC (5000000 units)

FacilitatorCDP (Coinbase)

402 Payment Required response

{
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "5000000",
    "resource": "/site",
    "payTo": "0xBe2C...",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxTimeoutSeconds": 300
  }]
}

Code Generation

api.obol.sh · $5 USDC

POST/site$5 USDC

Crawls a website, extracts its visual identity and content, then generates a complete Next.js 15 TypeScript project matching the same vibe.

Request body

urlstring — website URL to analyze

repostring — "owner/repo" to fork and PR into

branchstring? — target branch (default: "main")

emailstring? — receive a completion email

Example

curl -X POST https://api.obol.sh/site \
  -H 'X-Payment: <base64-encoded-x402-payment>' \
  -H 'Content-Type: application/json' \
  -d '{
         "url": "https://acme.com",
         "repo": "you/my-site",
         "email": "you@example.com"
       }'

Response 200

{
  "pr": "https://github.com/you/repo/pull/42",
  "fork": "https://github.com/obol-sh/repo",
  "branch": "obol/site-1234567890",
  "files": ["..."]
}

POST/miniapp$5 USDC

Generates a complete Farcaster mini app from a plain-English idea. Includes manifest.json (frames.v2.manifest), wagmi v2, @farcaster/miniapp-sdk, and Tailwind v4.

Request body

ideastring — describe the mini app

repostring — "owner/repo" to fork and PR into

namestring? — app name (Claude picks if omitted)

branchstring? — target branch (default: "main")

emailstring? — receive a completion email

Example

curl -X POST https://api.obol.sh/miniapp \
  -H 'X-Payment: <base64-encoded-x402-payment>' \
  -H 'Content-Type: application/json' \
  -d '{
         "idea": "A tipping jar where users send USDC to creators",
         "repo": "you/miniapp-template",
         "name": "TipJar"
       }'

Response 200

{
  "pr": "https://github.com/you/repo/pull/42",
  "fork": "https://github.com/obol-sh/repo",
  "branch": "obol/miniapp-1234567890",
  "files": ["..."]
}

POST/api$5 USDC

Generates an OpenAPI 3.1 spec (openapi.yaml) and a complete Hono Cloudflare Worker server from a plain-English description.

Request body

descriptionstring — describe the API you need

repostring — "owner/repo" to fork and PR into

branchstring? — target branch (default: "main")

emailstring? — receive a completion email

Example

curl -X POST https://api.obol.sh/api \
  -H 'X-Payment: <base64-encoded-x402-payment>' \
  -H 'Content-Type: application/json' \
  -d '{
         "description": "REST API for a todo app with user auth, CRUD for todos and tags",
         "repo": "you/api-starter"
       }'

Response 200

{
  "pr": "https://github.com/you/repo/pull/42",
  "fork": "https://github.com/obol-sh/repo",
  "branch": "obol/api-1234567890",
  "files": ["..."]
}

POST/tests$1 USDC

Reads a file from a public GitHub repo and generates comprehensive unit tests — happy paths, edge cases, error paths, mocked dependencies.

Request body

repostring — "owner/repo" containing the source file

pathstring — file path within the repo

frameworkstring? — test framework (default: "vitest")

branchstring? — branch to read from (default: "main")

emailstring? — receive a completion email

Example

curl -X POST https://api.obol.sh/tests \
  -H 'X-Payment: <base64-encoded-x402-payment>' \
  -H 'Content-Type: application/json' \
  -d '{
         "repo": "you/my-project",
         "path": "src/lib/utils.ts",
         "framework": "vitest"
       }'

Response 200

{
  "pr": "https://github.com/you/repo/pull/42",
  "fork": "https://github.com/obol-sh/repo",
  "branch": "obol/tests-1234567890",
  "files": ["..."]
}

POST/docs$5 USDC

Claude reads the key files in your repo (README, index files, config) and generates a full MDX documentation site under docs/.

Request body

repostring — "owner/repo" to document

branchstring? — branch to read from (default: "main")

emailstring? — receive a completion email

Example

curl -X POST https://api.obol.sh/docs \
  -H 'X-Payment: <base64-encoded-x402-payment>' \
  -H 'Content-Type: application/json' \
  -d '{
         "repo": "you/my-library",
         "branch": "main"
       }'

Response 200

{
  "pr": "https://github.com/you/repo/pull/42",
  "fork": "https://github.com/obol-sh/repo",
  "branch": "obol/docs-1234567890",
  "files": ["..."]
}

POST/deploy$5 USDC

Generates GitHub Actions CI/CD workflow and platform-specific deploy config for Vercel, Cloudflare Workers, or Railway.

Request body

repostring — "owner/repo" to configure

platform"vercel" | "cloudflare" | "railway"

branchstring? — target branch (default: "main")

emailstring? — receive a completion email

Example

curl -X POST https://api.obol.sh/deploy \
  -H 'X-Payment: <base64-encoded-x402-payment>' \
  -H 'Content-Type: application/json' \
  -d '{
         "repo": "you/my-project",
         "platform": "vercel"
       }'

Response 200

{
  "pr": "https://github.com/you/repo/pull/42",
  "fork": "https://github.com/obol-sh/repo",
  "branch": "obol/deploy-1234567890",
  "files": ["..."]
}

POST/refactor$1 USDC

Modernizes a TypeScript/JavaScript file: adds strict types, JSDoc comments, removes dead code, improves naming, and splits large functions. Preserves all existing functionality.

Request body

repostring — "owner/repo" containing the file

pathstring — file path to refactor

branchstring? — branch to read from (default: "main")

emailstring? — receive a completion email

Example

curl -X POST https://api.obol.sh/refactor \
  -H 'X-Payment: <base64-encoded-x402-payment>' \
  -H 'Content-Type: application/json' \
  -d '{
         "repo": "you/my-project",
         "path": "src/lib/old-utils.js"
       }'

Response 200

{
  "pr": "https://github.com/you/repo/pull/42",
  "fork": "https://github.com/obol-sh/repo",
  "branch": "obol/refactor-1234567890",
  "files": ["..."]
}

POST/label$5 USDC (initial) · $25/1yr · $40/2yr

Applies a Verified Builder badge to any Bluesky account via the Obol AT Protocol labeler. The label appears on the account's Bluesky profile for anyone subscribed to the Obol labeler.

Request body

didstring — Bluesky DID (e.g. "did:plc:abc123...")

duration"initial" | "1y" | "2y"

emailstring? — receive a confirmation email

Example

curl -X POST https://api.obol.sh/label \
  -H 'X-Payment: <base64-encoded-x402-payment>' \
  -H 'Content-Type: application/json' \
  -d '{
         "did": "did:plc:abc123...",
         "duration": "initial"
       }'

Response 200

{
  "pr": "https://github.com/you/repo/pull/42",
  "fork": "https://github.com/obol-sh/repo",
  "branch": "obol/label-1234567890",
  "files": ["..."]
}

POST/fix$5 USDC

Reads a GitHub issue, fetches the key source files from the repo, generates a targeted fix, and opens a pull request. Includes "Fixes #N" in the PR body.

Request body

issuestring — full GitHub issue URL (e.g. "https://github.com/owner/repo/issues/42")

branchstring? — branch to base the fix on (default: "main")

emailstring? — receive a completion email

Example

curl -X POST https://api.obol.sh/fix \
  -H 'X-Payment: <base64-encoded-x402-payment>' \
  -H 'Content-Type: application/json' \
  -d '{
         "issue": "https://github.com/you/my-project/issues/42"
       }'

Response 200

{
  "pr": "https://github.com/you/repo/pull/42",
  "fork": "https://github.com/obol-sh/repo",
  "branch": "obol/fix-1234567890",
  "files": ["..."]
}

Clanker Analytics

api2.obol.sh · $0.01 USDC

Clanker tokens indexed from Base, enriched with DexScreener market data. Refreshed every 5 minutes for new tokens, every hour for metrics. All endpoints are GET requests — payment header required, no request body.

GET/tokens/count$0.01 USDC

Count of Clanker tokens deployed within a time window.

Query params

periodstring? — "1h" | "24h" | "7d" | "30d" (default: "7d")

Example

curl https://api2.obol.sh/tokens/count?period=7d \
  -H 'X-Payment: <base64-encoded-x402-payment>'

Response 200

{ "count": 1842, "period": "7d" }

GET/tokens/volume$0.01 USDC

Number and percentage of tokens in a period that have had any 24h trading volume.

Query params

periodstring? — "1h" | "24h" | "7d" | "30d" (default: "7d")

Example

curl https://api2.obol.sh/tokens/volume?period=7d \
  -H 'X-Payment: <base64-encoded-x402-payment>'

Response 200

{ "period": "7d", "total": 1842, "with_volume": 431, "pct_with_volume": 23.4 }

GET/tokens/top$0.01 USDC

Top Clanker tokens ranked by 24h volume or liquidity depth. Includes full metrics.

Query params

periodstring? — time window for deployment filter (default: "7d")

by"volume" | "liquidity" — ranking metric (default: "volume")

limitnumber? — max results, up to 50 (default: 10)

Example

curl "https://api2.obol.sh/tokens/top?period=7d&by=volume&limit=10" \
  -H 'X-Payment: <base64-encoded-x402-payment>'

Response 200

{ "period": "7d", "by": "volume_h24", "tokens": [...] }

GET/tokens/new$0.01 USDC

Latest tokens deployed, ordered by deploy time descending.

Query params

sincestring? — window: "1h", "6h", "24h", "7d" (default: "24h")

limitnumber? — max results, up to 100 (default: 20)

Example

curl "https://api2.obol.sh/tokens/new?since=24h" \
  -H 'X-Payment: <base64-encoded-x402-payment>'

Response 200

{ "since": "24h", "tokens": [...] }

GET/tokens/search$0.01 USDC

Fuzzy search across all Clanker tokens by name or symbol.

Query params

qstring — search query (required)

Example

curl "https://api2.obol.sh/tokens/search?q=pepe" \
  -H 'X-Payment: <base64-encoded-x402-payment>'

Response 200

{ "query": "pepe", "tokens": [...] }

GET/tokens/by-fid/:fid$0.01 USDC

All tokens ever deployed by a Farcaster user (by FID), ordered by deploy time.

Query params

fidnumber — Farcaster FID

Example

curl https://api2.obol.sh/tokens/by-fid/3 \
  -H 'X-Payment: <base64-encoded-x402-payment>'

Response 200

{ "fid": 3, "count": 4, "tokens": [...] }

GET/tokens/:address$0.01 USDC

Full enriched record for a single token: metadata, deployer info, and latest price, volume, liquidity, FDV, and transaction count.

Query params

addressstring — ERC-20 contract address (checksummed or lowercase)

Example

curl https://api2.obol.sh/tokens/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  -H 'X-Payment: <base64-encoded-x402-payment>'

Response 200

{ "contract_address": "0x...", "name": "...", "symbol": "...", "clanker_metrics": { "price_usd": 0.00042, "volume_h24": 15200, ... } }

GET/stats/summary$0.01 USDC

Aggregate stats across the entire dataset: total tokens, deployment counts for 24h and 7d windows, and how many had trading volume.

Example

curl https://api2.obol.sh/stats/summary \
  -H 'X-Payment: <base64-encoded-x402-payment>'

Response 200

{ "total_tokens": 639842, "tokens_24h": 284, "tokens_7d": 1842, "tokens_with_volume_7d": 431 }

Loom — Shared AI Compute

loom.obol.sh · variable

A marketplace for shared Claude compute. Sellers run a daemon on their machine that executes buyer prompts using Claude Code plan tokens. Buyers pay per-job with USDC — 25% cheaper than direct API pricing. No API key needed on either side.

How Loom works

1.Buyer sends a prompt + USDC budget via x402 to POST /jobs

2.Coordinator verifies payment (escrow) and matches to an online seller

3.Seller daemon executes via claude --print using their plan tokens

4.Output is sanitized and returned. Payment settles on first result fetch.

POST/jobsvariable · x402

Submit a compute job. Without an X-Payment header, returns 402 with payment requirements for the budget amount.

Request body

promptstring — the prompt to execute (required, max 100K chars)

budget_usdnumber — max budget in USD (required, min $0.01)

modelstring? — "sonnet" | "opus" | "haiku" (default: "sonnet")

timeout_secondsnumber? — max execution time (default: 300)

system_promptstring? — optional system prompt

Example

curl -X POST https://loom.obol.sh/jobs \
  -H 'X-Payment: <base64-encoded-x402-payment>' \
  -H 'Content-Type: application/json' \
  -d '{ "prompt": "Explain x402 in 3 sentences", "budget_usd": 0.05 }'

Response 201

{
  "job_id": "4580dffc-3ac2-4ee5-a750-8cad9e1f4f75",
  "status": "assigned",
  "payment": "escrowed",
  "message": "Job assigned to a seller"
}

GET/jobs/:idfree

Check job status. No payment required.

Response 200

{
  "id": "4580dffc-...",
  "status": "completed",
  "model": "sonnet",
  "budget_usd": 0.05,
  "duration_ms": 3799,
  "created_at": "2026-03-27T18:18:59Z",
  "assigned_at": "2026-03-27T18:18:59Z",
  "completed_at": "2026-03-27T18:19:04Z"
}

GET/jobs/:id/resultfree

Fetch job output. Returns 202 if still in progress. Settles escrowed payment on first fetch of a completed job.

Response 200

{
  "id": "4580dffc-...",
  "status": "completed",
  "output": "x402 is an HTTP payment protocol that...",
  "duration_ms": 3799
}

POST/sellers/registerfree

Request body

wallet_addressstring — Base wallet for USDC payouts (required)

capacitynumber? — max concurrent jobs (default: 1)

Example

curl -X POST https://loom.obol.sh/sellers/register \
  -H 'Content-Type: application/json' \
  -d '{ "wallet_address": "0xYour...", "capacity": 1 }'

# Response:
# { "seller_id": "2b14eb54-...", "auth_token": "aec113f6-..." }

Seller Daemon Endpoints

These endpoints are used by the seller daemon. All require Authorization: Bearer <auth_token>.

POST/sellers/heartbeat

Keep seller online. Send every 30s. Body: { active_jobs: number }

POST/sellers/poll

Poll for assigned jobs. Returns 204 if none available, or the job object.

POST/sellers/complete

Report job completion. Body: { job_id, claim_token, output, status, duration_ms }

Quick Start — Selling Compute

# 1. Install the daemon
git clone https://github.com/obol-sh/loom-daemon
cd loom-daemon && npm install

# 2. Register as a seller
curl -X POST https://loom.obol.sh/sellers/register \
  -H 'Content-Type: application/json' \
  -d '{ "wallet_address": "0xYour..." }'
# Save the auth_token from the response

# 3. Configure
echo '{ "coordinator": "https://loom.obol.sh", "authToken": "<your-token>", "walletAddress": "0xYour..." }' > ~/.loom/config.json

# 4. Start earning
npx tsx src/index.ts daemon
# → [daemon] Online — polling for jobs