Overview

API docs for paid coinflip battle creation/join flows and public read endpoints. Payments are x402-gated and settle on Base.

Quick Endpoints

• GET /health
• POST /battle/create
• POST /battle/:id/join
• GET /battle/:id/verify

API examples (cURL)

Replace $API_URL with your API base URL (for example https://coinflip-x402.workers.dev).

Public endpoints (no payment)

# Health + network
curl -s "$API_URL/health"

# List battles (optional: waiting|flipping|resolved|expired|failed)
curl -s "$API_URL/battles?status=waiting"

# Get a battle by id
curl -s "$API_URL/battle/BATTLE_ID"

# Verify a resolved battle (commit-reveal proof)
curl -s "$API_URL/battle/BATTLE_ID/verify"

# Visualize state payload (used by /visualize)
curl -s "$API_URL/visualize/state"

x402-paid endpoints

These routes return 402 Payment Required until you include a valid payment proof. With raw cURL you can do the preflight and then retry the same request with a Payment-Response header (obtained from an x402 client flow).

Preflight (expect 402 + challenge headers)

curl -i -X POST "$API_URL/battle/create?betAmount=5" \
  -H "Content-Type: application/json" \
  -d '{"side":"heads"}'

Create battle (paid)

curl -s -X POST "$API_URL/battle/create?betAmount=5" \
  -H "Content-Type: application/json" \
  -H "Payment-Response: YOUR_PAYMENT_RESPONSE_FROM_X402_FLOW" \
  -d '{"side":"heads"}'

Join battle (paid)

curl -s -X POST "$API_URL/battle/BATTLE_ID/join" \
  -H "Content-Type: application/json" \
  -H "Payment-Response: YOUR_PAYMENT_RESPONSE_FROM_X402_FLOW" \
  -d '{}'

Note: join price is derived from the battle stake; you don’t pass betAmount for joins.