Block Lottos API Documentation

📢 Advertising API

Programmatically manage banner ads on Block Lottos. Built for developers, AI agents, and automated workflows.

Base URL: https://blocklottos.com/api/ads/
Format: All responses are JSON. All payments are in USDC via on-chain transfer.
Authentication: No API key required. Rate limiting is applied per IP address.

Overview

The Block Lottos Advertising API lets you submit, track, and activate banner ads without using the web form. It's designed for:

Developers building automated ad campaigns

AI agents and bots that manage advertising programmatically

Businesses integrating Block Lottos ads into their workflow

How It Works

Get Sizes & Pricing: call /api/ads/sizes to see available banner formats and current prices

Submit Ad: request a submit quote via /api/ads/submit, sign the returned payment transaction from your wallet, then confirm

Wait for Review: poll /api/ads/status/{id} until your ad is approved

Activate: pay the duration fee via /api/ads/activate to make your ad live on the site

⚠️ Quote-first payments. The submit and activate endpoints return an unsigned USDC transaction. You sign and broadcast it from your own wallet. No funds are pulled from you directly. A quote is valid for 1 hour; after that, request a new one. Include the transaction hash in your request, the API verifies the payment on-chain.

Endpoints

⏱ 2 req/min/IP GET /api/ads/sizes

Returns all available banner sizes. If a promotional discount is active, discounted prices are included in the response.

Parameters

None required.

Response

Returns an array of all available sizes. One object per size.

{
  "sizes": [
    {
      "id": "728x90",
      "width": 728,
      "height": 90,
      "label": "Leaderboard (728×90)",
      "price_7d": "(current price)",
      "price_14d": "(current price)",
      "price_30d": "(current price)",
      "discount_pct": 0,
      "discount_expires": null,
      "discounted_price_7d": "(discounted price)",
      "discounted_price_14d": "(discounted price)",
      "discounted_price_30d": "(discounted price)"
    },
    // ... one entry per size (300x250, 320x50, 160x600)
  ],
  "currency": "USDC"
}

Available Sizes

Leaderboard

728 × 90 px

Medium Rectangle

300 × 250 px

Mobile Banner

320 × 50 px

Wide Skyscraper

160 × 600 px

⏱ 10 req/min/IP POST /api/ads/submit

Request a submission quote. Returns the current fee and an unsigned USDC payment transaction. Sign and broadcast from your wallet, then confirm with POST /api/ads/submit/pay.

Parameters (multipart/form-data)

Field	Type	Description
image	file REQUIRED	Banner image (JPEG, PNG, GIF, or WEBP). Max 2MB. Dimensions must exactly match the selected size.
size_id	string REQUIRED	Banner size ID from `/api/ads/sizes` (e.g. `728x90`, `300x250`)
target_url	string REQUIRED	Click-through URL for the ad
wallet_address	string REQUIRED	Your wallet address (0x...)
network	string OPTIONAL	Payment network. Default: `polygon`. Supported: `polygon`, `base`, `arbitrum`, `optimism`, `ethereum`, `avalanche`, `bnb`

Response

{
  "quote_id": "sq_abc123...",
  "status": "awaiting_payment",
  "expires_at": "2026-04-03T19:00:00",
  "payment": {
    "network": "polygon",
    "chain_id": 137,
    "usdc_contract": "0x2791Bca1...",
    "to": "0x311A30fC...",
    "amount_usdc": "(current fee)",
    "tx": { "to": "0xUSDC...", "data": "0xa9059cbb...", "value": "0x0", "chainId": 137 }
  },
  "next_step": "Sign payment tx, then call POST /api/ads/submit/pay"
}

Submission Flow

Call POST /api/ads/submit with your banner image, size, and URL. No payment yet

Receive a quote_id and a ready-to-sign USDC tx object with the exact current fee

Sign and broadcast the transaction from your wallet, the fee and destination are pre-filled

Call POST /api/ads/submit/pay with quote_id + tx_hash to finalise

The API verifies the payment and queues your ad for admin review

⏱ 2 req/min/IP GET /api/ads/status/{submission_id}

Check the current status of a submitted ad.

Parameters

Field	Type	Description
submission_id	path REQUIRED	The submission ID returned from `/api/ads/submit` (e.g. `ad_42`)

Response

{
  "submission_id": "ad_42",
  "status": "active",
  "banner_size": "728x90",
  "submitted_at": "2026-04-03T18:00:00",
  "reviewed_at": "2026-04-03T19:30:00",
  "activated_at": "2026-04-03T20:00:00",
  "expires_at": "2026-04-10T20:00:00",
  "stats": {
    "clicks": 47
  }
}

Possible Statuses

Status	Meaning
pending_review	Submitted, waiting for admin to approve or reject
approved	Approved, ready to activate with a duration payment
rejected	Ad was rejected by admin
active	Live on the site and being displayed to visitors
expired	Was active but the paid duration has ended

⏱ 2 req/min/IP GET /api/ads/wallet/{wallet_address}

Returns all ads associated with a wallet address, including their submission IDs, statuses, banner sizes, and URLs. Useful if you don't have the submission ID stored.

Parameters

Field	Type	Description
wallet_address	path REQUIRED	The wallet address used to submit ads (0x...)

Response

{
  "wallet": "0xYourWallet...",
  "count": 2,
  "ads": [
    {
      "submission_id": "ad_42",
      "status": "approved",
      "banner_size": "728x90",
      "target_url": "https://example.com",
      "submitted_at": "2026-04-03T18:00:00",
      "reviewed_at": "2026-04-03T19:30:00",
      "activated_at": null,
      "expires_at": null
    }
  ]
}

⏱ 10 req/min/IP POST /api/ads/activate

Request an activation quote. Returns the current price (with any discount applied) and an unsigned USDC payment transaction. Sign and broadcast, then confirm with POST /api/ads/activate/pay. This endpoint accepts form-encoded or JSON requests.

Parameters (form-data or application/x-www-form-urlencoded)

Field	Type	Description
submission_id	string REQUIRED	The approved ad's submission ID (e.g. `ad_42`)
duration	string REQUIRED	How long the ad should run: `7d`, `14d`, or `30d`
wallet_address	string REQUIRED	Your wallet address (0x...)
network	string OPTIONAL	Payment network. Default: `polygon`. Supported: `polygon`, `base`, `arbitrum`, `optimism`, `ethereum`, `avalanche`, `bnb`

Response

{
  "quote_id": "aq_abc123...",
  "submission_id": "ad_42",
  "status": "awaiting_payment",
  "duration": "7d",
  "expires_at": "2026-04-03T19:00:00",
  "payment": {
    "network": "polygon",
    "amount_usdc": "(current price)",
    "discount_pct": 0,
    "tx": { "to": "0xUSDC...", "data": "0xa9059cbb...", "value": "0x0", "chainId": 137 }
  },
  "next_step": "Sign payment tx, then call POST /api/ads/activate/pay"
}

💰 Discount-aware: If a promotional discount is active, the API automatically applies it to the quote. You always pay the current price, no need to calculate it yourself.

Error Handling

All errors return a JSON object with an error field:

// Example error response
{
  "error": "Payment verification failed: TX hash not found"
}

HTTP Code	Meaning
200	Success
400	Bad request: missing or invalid parameters
402	Payment required: USDC payment not verified on-chain
404	Not found: submission ID doesn't exist
405	Method not allowed: wrong HTTP method for this endpoint
409	Conflict: ad is not in the right state (e.g. trying to activate a pending ad)
429	Rate limited: too many requests. Check `Retry-After` header.
500	Server error

Rate Limits

Endpoint	Limit
/api/ads/sizes	2 requests / minute / IP
/api/ads/submit	10 requests / minute / IP
/api/ads/submit/pay	10 requests / minute / IP
/api/ads/wallet/*	2 requests / minute / IP
/api/ads/status/*	2 requests / minute / IP
/api/ads/activate	10 requests / minute / IP
/api/ads/activate/pay	10 requests / minute / IP

When rate limited, the response includes a retry_after field (in seconds) and an HTTP Retry-After header.

Quick Start - cURL Examples

1. Get sizes

curl https://blocklottos.com/api/ads/sizes

2. Request submit quote (step 1)

curl -X POST https://blocklottos.com/api/ads/submit \
  -F "image=@banner_728x90.png" \
  -F "size_id=728x90" \
  -F "target_url=https://example.com" \
  -F "wallet_address=0xYourWallet..."
# Returns quote_id and unsigned payment tx, sign & broadcast from your wallet

3. Confirm submit payment (step 2)

curl -X POST https://blocklottos.com/api/ads/submit/pay \
  -d "quote_id=sq_abc123..." \
  -d "tx_hash=0xYourBroadcastedTxHash..."
# Form-encoded or JSON body accepted

4. Look up all ads for your wallet

curl https://blocklottos.com/api/ads/wallet/0xYourWallet...

5. Check status of a specific ad

curl https://blocklottos.com/api/ads/status/ad_42

6. Request activation quote (step 1)

curl -X POST https://blocklottos.com/api/ads/activate \
  -d "submission_id=ad_42" \
  -d "duration=7d" \
  -d "wallet_address=0xYourWallet..."
# Returns quote_id, current price, and unsigned payment tx

7. Confirm activation payment (step 2)

curl -X POST https://blocklottos.com/api/ads/activate/pay \
  -d "quote_id=aq_xyz789..." \
  -d "tx_hash=0xYourBroadcastedTxHash..."
# Form-encoded or JSON body accepted

🤖 Base-first agent workflow

A complete, non-custodial path from live lottery data to a verified Base ticket purchase.

Canonical agent game: Base Future Ledger on Base Mainnet, chain ID 8453.
Ticket price: 1 USDC using official Base USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (6 decimals).
Important: Base ETH pays network gas only. It is not the lottery ticket currency.

Minimum winner payouts: a verified winning Polygon Future Ledger ticket receives at least 100 POL, and a verified winning Base Future Ledger ticket receives at least 100 USDC. If the current jackpot for that game is higher, the higher amount applies. This policy applies only after a ticket is verified as a winner and does not mean that any ticket is guaranteed to win.

Block Lottos never stores private keys, receives seed phrases, signs wallet transactions, or broadcasts them. An autonomous agent uses its own Base wallet and owner-defined policy; a user assistant uses an explicitly approved wallet. The website supplies live facts, exact unsigned transactions, and on-chain verification.

End-to-end sequence

Read: call GET /api/lottery/agent-capabilities before every purchase.

Refer (optional): call POST /api/lottery/agent-referral to create or load the same multi-chain affiliate profile used by humans. One referral ID can hold EVM, Solana, and Cardano payout wallets.

Prepare: call POST /api/lottery/agent-purchase for one ticket. Use max_price_usdc, idempotency_key, and valid_until.

Execute: submit the returned exact one-ticket USDC approval only if required, then the ticket transaction, through the agent-controlled or user-approved wallet.

Verify: call POST /api/lottery/confirm-ticket-tx. Do not report success until it verifies the receipt and TicketPurchased event.

Monitor: read /api/lottery/tickets/{wallet}?chain=base and /api/lottery/draw-history?chain=base&limit=1.

Safe multi-ticket and recurring play: each API call prepares one ticket, which prevents an accidental hidden batch purchase. Multiple purchase calls are allowed, so an agent can buy as many tickets as its wallet owner permits by making additional one-ticket calls. Block Lottos imposes no one-ticket-per-agent or one-ticket-per-draw maximum. Fetch the live price each time, use a unique idempotency key for every purchase, expire old intents, approve only the exact one-ticket USDC amount, and stop after a failed or unknown receipt.

⏱ 10 req/min/IPGET/api/lottery/agent-capabilities

Returns live Base ticket price, USDC token, on-chain jackpot, minimum winner payout, payable winner amount, next draw, the complete action sequence, referral details, and safety policy. Treat this response as the source of truth instead of caching copied draw or price examples.

curl -H "X-BlockLottos-Agent: my-agent" https://blocklottos.com/api/lottery/agent-capabilities

⏱ 5 req/min/IPPOST/api/lottery/agent-referral

Securely enrolls or manages the one shared profile used by humans, bots, agents, and LLMs. First request a challenge and sign its exact message with an EVM identity wallet. Solana and Cardano are supported as payout wallets after enrollment. The response returns a one-time management_token; store it securely and use it only as a Bearer token for changes or private balances. This costs 0 USDC and performs no transaction.

curl -X POST https://blocklottos.com/api/lottery/agent-referral \
  -H "Content-Type: application/json" \
  -d '{"action":"challenge","primary_chain":"evm","connected_wallet":"0xYourBaseWallet"}'
# Sign the returned message, then resubmit challenge_id and signature. Store management_token once.

⏱ 10 req/min/IPPOST/api/lottery/agent-purchase

Base-only endpoint that prepares exactly one ticket. It reads the live contract price, fails closed above max_price_usdc, checks USDC balance and allowance where RPC permits, and returns unsigned wallet transactions plus ordered execution steps.

curl -X POST https://blocklottos.com/api/lottery/agent-purchase \
  -H "Content-Type: application/json" \
  -H "X-BlockLottos-Agent: my-agent" \
  -d '{
    "wallet_address":"0xYourBaseWallet",
    "numbers":[5,12,23,31,38,45],
    "max_price_usdc":"1.00",
    "referral_id":"optional-code",
    "idempotency_key":"wallet-draw-unique-key",
    "valid_until":"2026-09-12T15:55:00Z"
  }'

The response preserves transaction and approval_transaction for wallet compatibility, adds approval_required, and explicitly says whether wallet reads were available. The approval amount is the exact live price for one ticket—never unlimited. The idempotency key correlates preparation and confirmation but cannot prevent duplicate wallet broadcasts; the wallet agent must submit each transaction at most once. valid_until is enforced when the API prepares the transaction; because the contract transaction has no deadline parameter, the wallet must recheck it immediately before broadcasting.

⏱ 10 req/min/IPPOST/api/lottery/confirm-ticket-tx

After broadcasting the Base ticket transaction, verify it here. The endpoint checks success status, sender wallet, active Base Future Ledger contract, purchase method and the TicketPurchased event before returning confirmed: true. It records privacy-safe internal attribution without storing the raw wallet in the private activity log.

curl -X POST https://blocklottos.com/api/lottery/confirm-ticket-tx \
  -H "Content-Type: application/json" \
  -d '{"tx_hash":"0xYourTicketTransaction","wallet_address":"0xYourBaseWallet","execution_id":"bl_...","agent_id":"my-agent"}'

🎲 Lottery API

Read live lottery data and build ticket purchase transactions programmatically.

Base URL: https://blocklottos.com
Format: All responses are JSON.
Authentication: None required, all read endpoints are public. Rate limiting per IP.

Overview

The Lottery API gives developers and AI agents direct access to live on-chain lottery data, current jackpot, draw history, ticket lookups, prize checks, and unsigned ticket purchase transactions. It supports two lottery systems: Polygon Fortune Ledger and Base Future Ledger.

Supported lottery chains:
polygon means Polygon Fortune Ledger, chain ID 137, ticket currency POL, ticket price 10 POL, minimum winner payout 100 POL, contract 0x07F62Ff6697eD9b475FEed9dc90a5A157936839c.
base means Base Future Ledger, chain ID 8453, ticket currency USDC, ticket price 1 USDC, minimum winner payout 100 USDC, official Base USDC token 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, contract 0xe5a9cF597ec65523BD71a8433B620eB1F3Eb0d0a.
Add ?chain=base or ?chain=polygon on GET endpoints. For build-ticket-tx, send "chain":"base" or "chain":"polygon" in the JSON body. If omitted, the API defaults to polygon.

⚠️ Contract reads use chain-specific dual RPC. Polygon reads use polygon-bor-rpc.publicnode.com with 1rpc.io/matic fallback. Base reads use base-rpc.publicnode.com with mainnet.base.org fallback. Responses are cached for 60 seconds on read endpoints.

ℹ️ URL format: All endpoints use clean URLs, no .php extension required. For example, use /api/jackpot not /api/jackpot.php. Both forms work, but the clean URL is preferred and what bots and agents should use.

Endpoints

⏱ 2 req/min/IP GET /api/jackpot

Returns the live on-chain jackpot, the game’s minimum winner payout, and the payable winner amount, which is the higher of those two values. Cached 60 seconds.

Query Parameters

Param	Type	Description
chain	string OPTIONAL	`polygon` or `base`. Defaults to `polygon`.

Response

{
  "status": "ok",
  "jackpot_pol": 42.5,
  "onchain_jackpot": 42.5,
  "minimum_winner_payout": 100,
  "winner_payout": 100,
  "jackpot_wei": "42500000000000000000",
  "contract": "0x07F62Ff6697eD9b475FEed9dc90a5A157936839c",
  "chain": "polygon",
  "timestamp": 1744700000
}

⏱ 2 req/min/IP GET /api/stats

Full draw stats, on-chain jackpot, minimum and payable winner payout, draw number, rollover count, and next draw timestamp. Cached 60 seconds.

Query Parameters

Param	Type	Description
chain	string OPTIONAL	`polygon` or `base`. Defaults to `polygon`.

Response

{
  "status": "ok",
  "draw_number": 14,
  "jackpot_pol": 42.5,
  "onchain_jackpot": 42.5,
  "minimum_winner_payout": 100,
  "winner_payout": 100,
  "jackpot_wei": "42500000000000000000",
  "rollover_count": 3,
  "next_draw_timestamp": 1745000000,
  "contract": "0x07F62Ff6697eD9b475FEed9dc90a5A157936839c",
  "chain": "polygon",
  "timestamp": 1744700000
}

⏱ 2 req/min/IP GET /api/lottery/draw-history

Past draw results. Omit draw_id to get the most recent completed draw. If no on-chain draw has completed yet, this endpoint returns the latest published public draw result from the website result JSON files.

Query Parameters

Param	Type	Description
draw_id	integer OPTIONAL	Specific draw ID to fetch. Omit for latest completed draw.
limit	integer OPTIONAL	Number of draws to return (default: 1, max: 10)
chain	string OPTIONAL	`polygon` or `base`. Defaults to `polygon`.

Response

{
  "status": "ok",
  "draws": [
    {
      "draw_id": 0,
      "winning_numbers": [1, 3, 4, 15, 30, 35],
      "draw_date": "2026-05-23",
      "status": "completed",
      "jackpot": 0,
      "currency": "POL",
      "rolled_over": true,
      "draw_timestamp": 1779548400
    }
  ],
  "source": "local_public_results"
}

Public Result JSON

Bots may also fetch the same latest result data directly:

GET /data/draws/latest.json — latest Polygon Fortune Ledger result
GET /data/draws/history.json — Polygon Fortune Ledger result history
GET /data/base-draws/latest.json — latest Base Future Ledger result
GET /data/base-draws/history.json — Base Future Ledger result history

⏱ 2 req/min/IP GET /api/lottery/tickets/{wallet}

All tickets purchased by a wallet address in the current draw.

Path Parameters

Param	Type	Description
wallet	string REQUIRED	EVM wallet address (0x...)

Query Parameters

Param	Type	Description
chain	string OPTIONAL	`polygon` or `base`. Defaults to `polygon`.

Response

{
  "status": "ok",
  "wallet": "0xYourWalletAddress",
  "draw_id": 14,
  "ticket_count": 3,
  "tickets": [
    { "numbers": [5, 11, 22, 30, 37, 44] },
    { "numbers": [1, 9, 18, 27, 36, 45] }
  ]
}

⏱ 2 req/min/IP GET /api/lottery/check-prizes/{wallet}

Checks whether a wallet has an outstanding failed on-chain prize transfer that can be retried through the smart contract. This endpoint covers contract transfer status only; use the published winner payout fields for the game’s complete minimum and payable amount.

Path Parameters

Param	Type	Description
wallet	string REQUIRED	EVM wallet address (0x...)

Query Parameters

Param	Type	Description
chain	string OPTIONAL	`polygon` or `base`. Defaults to `polygon`.

Response (winner)

{
  "status": "ok",
  "wallet": "0xYourWalletAddress",
  "has_prize": true,
  "prize_pol": 150.0,
  "prize_wei": "150000000000000000000",
  "draw_id": 11,
  "expires_timestamp": 1752000000
}

Response (no prize)

{
  "status": "ok",
  "wallet": "0xYourWalletAddress",
  "has_prize": false
}

⏱ 10 req/min/IP POST /api/lottery/build-ticket-tx

Build an unsigned buyTicket transaction. The caller signs it in their Web3 wallet and broadcasts it. Polygon Fortune Ledger returns a native POL ticket transaction. Base Future Ledger returns a USDC approval transaction plus a zero-value ticket transaction. This endpoint does not submit the transaction.

Request Body (application/json)

Field	Type	Description
numbers	array[6] REQUIRED	Six unique integers from 1–49. Any order — API sorts ascending before encoding.
wallet_address	string REQUIRED	Buyer's EVM wallet address (0x...)
chain	string OPTIONAL	`polygon` or `base`. Defaults to `polygon`.
referral_id	string OPTIONAL	Base only. Referral ID as `0x` bytes32 or a short code up to 32 characters.

Request Example

{
  "chain": "base",
  "numbers": [5, 12, 23, 31, 38, 45],
  "wallet_address": "0xYourWalletAddress",
  "referral_id": "optional-referral-code"
}

Response (Base example)

{
  "status": "ok",
  "chain": "base",
  "numbers_sorted": [5, 12, 23, 31, 38, 45],
  "ticket_price": 1,
  "ticket_price_units": "1000000",
  "currency": "USDC",
  "payment_token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "approval_required": true,
  "approval_transaction": { "to": "0x8335...2913", "value": "0x0", "data": "0x095ea7b3..." },
  "transaction": {
    "to": "0xe5a9cF597ec65523BD71a8433B620eB1F3Eb0d0a",
    "data": "0x...",
    "value": "0x0",
    "chainId": "0x2105"
  }
}

Validation Errors

{ "status": "error", "message": "Must provide exactly 6 numbers" }
{ "status": "error", "message": "Numbers must be between 1 and 49" }
{ "status": "error", "message": "Numbers must be unique" }
{ "status": "error", "message": "Invalid wallet address" }

Rate Limits

Endpoint	Limit
/api/jackpot	2 requests / minute / IP
/api/stats	2 requests / minute / IP
/api/lottery/draw-history	2 requests / minute / IP
/api/lottery/tickets/{wallet}	2 requests / minute / IP
/api/lottery/check-prizes/{wallet}	2 requests / minute / IP
/api/lottery/build-ticket-tx	10 requests / minute / IP
/api/lottery/agent-capabilities	10 requests / minute / IP
/api/lottery/agent-referral	5 requests / minute / IP
/api/lottery/agent-purchase	10 requests / minute / IP
/api/lottery/confirm-ticket-tx	10 requests / minute / IP

MACHINE-READABLE API SUMMARY — ADVERTISING: Base URL: https://blocklottos.com/api/ads/ Flow: quote-first — submit/activate return unsigned USDC tx; caller signs and broadcasts; then confirms with /pay endpoint. Endpoints: - GET /api/ads/sizes → List banner sizes (rate: 2/min/IP) - POST /api/ads/submit → Request submit quote: image, size_id, target_url, wallet_address, network(optional) → returns quote_id + unsigned USDC tx (rate: 10/min/IP) - POST /api/ads/submit/pay → Confirm submit: quote_id, tx_hash → submission_id (rate: 10/min/IP) - GET /api/ads/wallet/{wallet_address} → List all ads for a wallet (rate: 2/min/IP) - GET /api/ads/status/{submission_id} → Check ad status (rate: 2/min/IP) - POST /api/ads/activate → Request activation quote: submission_id, duration(7d|14d|30d), wallet_address, network(optional) → returns quote_id + unsigned USDC tx with current price (rate: 10/min/IP) - POST /api/ads/activate/pay → Confirm activation: quote_id, tx_hash → ad goes live (rate: 10/min/IP) Supported networks: polygon, base, arbitrum, optimism, ethereum, avalanche, bnb MACHINE-READABLE API SUMMARY — LOTTERY: Base URL: https://blocklottos.com Supported lottery chains: - polygon: Polygon Fortune Ledger, chain ID 137, currency POL, ticket price 10 POL, contract 0x07F62Ff6697eD9b475FEed9dc90a5A157936839c. - base: Base Future Ledger, chain ID 8453, currency USDC, ticket price 1 USDC, official Base USDC token 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, contract 0xe5a9cF597ec65523BD71a8433B620eB1F3Eb0d0a, draw Saturday 16:00 UTC. Chain selector: GET endpoints accept ?chain=polygon or ?chain=base. POST /api/lottery/build-ticket-tx accepts JSON field chain. Default is polygon. Ticket numbers: Pick 6 unique numbers from 1-49. Endpoints: - GET /api/jackpot?chain={polygon|base} → Live jackpot in POL or USDC (rate: 2/min/IP, cached 60s) - GET /api/stats?chain={polygon|base} → Draw stats: jackpot, draw number, next draw time (rate: 2/min/IP, cached 60s) - GET /api/lottery/draw-history?chain={polygon|base}&draw_id={id}&limit={n} → Past draw results (rate: 2/min/IP) - GET /api/lottery/tickets/{wallet}?chain={polygon|base} → Tickets for wallet in current draw (rate: 2/min/IP) - GET /api/lottery/check-prizes/{wallet}?chain={polygon|base} → Unclaimed prize check (rate: 2/min/IP) - POST /api/lottery/build-ticket-tx → Backwards-compatible general builder: {chain, numbers:[6 ints 1-49], wallet_address, referral_id optional for base}. Polygon returns native POL tx; Base returns USDC approval plus zero-value ticket tx. (rate: 10/min/IP) Base-first agent flow: - GET /api/lottery/agent-capabilities → Live Base USDC facts, workflow and owner-defined multi-ticket safety policy. (rate: 10/min/IP) - POST /api/lottery/agent-referral → Free idempotent referral creation/load for a Base payout wallet. (rate: 5/min/IP) - POST /api/lottery/agent-purchase → One Base ticket with max_price_usdc, idempotency_key and optional valid_until/referral_id. Returns exact unsigned transactions; never stores private keys. (rate: 10/min/IP) - POST /api/lottery/confirm-ticket-tx → Verifies successful Base receipt, sender, contract, method and TicketPurchased event before private attribution. (rate: 10/min/IP)