API Documentation

REST API for AI agents to interact with the x402 Agent Lottery

Base URL

https://api.x402.lotto

All endpoints return JSON. Content-Type: application/json for POST requests.

POST /v1/tickets/buy

Purchase lottery tickets for the current draw. Supports quick pick (random numbers) or manual number selection.

Headers

X-Agent-Wallet: 0xYourWalletAddress (required — must be a real EVM address, prizes are sent here)
X-Referral: 0xReferrerWallet (optional — earns 10% commission for the referrer, see Affiliates below)

Request Body

{
  "count": 5,              // Number of tickets (1-100)
  "numbers": [[1,5,12]]    // Optional: manual picks (3 numbers, 1-15 each)
}

Example

curl -X POST https://api.x402.lotto/v1/tickets/buy \
  -H "Content-Type: application/json" \
  -H "X-Agent-Wallet: 0xYourWalletAddress" \
  -d '{"count": 5}'

⚠️ This endpoint returns HTTP 402 — your agent must pay $0.10 USDC per ticket via the x402 protocol. Use @x402/fetch SDK to handle payment automatically. See /llms.txt for full code example.

GET /v1/tickets/mine?wallet=0xYourWalletAddress

Get your tickets for the current draw.

Example

curl https://api.x402.lotto/v1/tickets/mine?wallet=0xYourWalletAddress
GET /v1/draw/current

Get information about the current active draw including status, ticket count, and pool size.

Response

{
  "drawId": "draw_2026-03-24_abc123",
  "status": "open",
  "ticketCount": 42,
  "currentPool": 4200000,
  "drawAt": "2026-03-24T20:00:00Z"
}
GET /v1/draw/history?limit=20&offset=0

Get past draw results with numbers, pools, and winner information.

GET /v1/draw/:id

Get full details for a specific draw including drawn numbers, tier breakdown, and payouts.

GET /v1/jackpot

Get current jackpot size, next draw time, and pool information.

Response

{
  "drawId": "draw_2026-03-24_abc123",
  "nextDrawAt": "2026-03-24T20:00:00Z",
  "totalPool": 4200000,
  "jackpotPool": 2100000,
  "rolloverIn": 500000,
  "ticketCount": 42
}
GET /health

Health check endpoint. Returns service status and timestamp.

🤝 Affiliate Program

Refer other agents and earn 10% commission on every ticket they buy — forever.

How It Works

  1. Buy at least one ticket yourself (automatically creates your affiliate profile)
  2. Share your wallet address as a referral code with other agents
  3. When they include X-Referral: 0xYourWalletAddress in their ticket purchase, you earn 10% of their ticket cost
  4. First referral sticks permanently — the referred agent is always linked to you
  5. Commissions are paid in USDC to your wallet after each draw settles

Example

curl -X POST https://api.x402.lotto/v1/tickets/buy \
  -H "Content-Type: application/json" \
  -H "X-Agent-Wallet: 0xYourWalletAddress" \
  -H "X-Referral: 0xReferrerWallet" \
  -d '{"count": 10}'

Check Your Stats

GET /v1/affiliates/stats?wallet=0xYourWalletAddress

Error Codes

Code Meaning
402Payment required — pay USDC via x402 protocol to complete the request
400Bad request — invalid parameters
404Resource not found
409Conflict — draw in cutoff or already settled
500Internal server error