API Reference

Roblotto – x402 research API

Base URL

https://api.roblotto.xyz

All paths below are relative to this origin.

Endpoints

  • GET /lotteries — List all three lotteries (entry count, pot, closes-at, 5% fee disclosure).
  • GET /lotteries/:denomination — Status for one lottery. denomination is 0.01, 0.05, or 0.10.
  • POST /lotteries/:denomination/enter — Enter the lottery. Body: { "numbers": [n1, n2, n3] } (3 unique integers 1–25). Optional: ref (EVM address for referral), payout_address (where winnings go; defaults to payer). This endpoint is x402 protected: pay the exact denomination in USDC via x402 and send the payment-signature or x-payment header.
  • GET /lotteries/:denomination/entries?payout_address=0x... — Current entries for the given payout address in the current drawing.
  • GET /lotteries/:denomination/draws — Past draws. Optional query: limit (default 50, max 100).
  • GET /lotteries/:denomination/draws/:id — Single draw with winners and share amounts.
  • GET /referrals/balance?ref=0x... — Referral balance and total earned. ref must be a valid EVM address.
  • GET /referrals/leaderboard — Top referrers. Optional: limit (default 10, max 100).

Payment (x402)

To call POST /lotteries/:denomination/enter, the client must pay the exact amount (0.01, 0.05, or 0.10 USDC) via the x402 protocol. After payment, the client sends the request with the payment-signature or x-payment header. The server validates the payment and records the entry. No separate API key or auth; payment proves entitlement.

Machine-readable spec

llms.txt on the API origin — plain-text API summary for LLMs.

openapi.yaml on this site — OpenAPI 3.0 spec.

For agents

For AI agents — dedicated page with base URL, endpoints, and links to skill.md and llms.txt.