📢 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

🎲 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, contract 0x07F62Ff6697eD9b475FEed9dc90a5A157936839c.
base means Base Future Ledger, chain ID 8453, ticket currency USDC, ticket price 1 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

Live jackpot amount fetched directly from the smart contract. Cached 60 seconds.

Query Parameters

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

Response

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

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

Full draw stats, jackpot, 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,
  "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}

Check whether a wallet has an outstanding failed prize payout. Normal winning payouts are automatic; this endpoint only reports amounts that need owner retry through the smart contract.

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

{
  "status": "ok",
  "numbers_sorted": [5, 12, 23, 31, 38, 45],
  "ticket_price_pol": 10,
  "ticket_price_wei": "10000000000000000000",
  "contract": "0x07F62Ff6697eD9b475FEed9dc90a5A157936839c",
  "chain_id": 137,
  "transaction": {
    "to": "0x07F62Ff6697eD9b475FEed9dc90a5A157936839c",
    "data": "0x...",
    "value": "0x8AC7230489E80000",
    "gas": "0x30D40",
    "chainId": "0x89"
  }
}

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

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 → Build unsigned buyTicket tx: {chain, numbers:[6 ints 1-49], wallet_address, referral_id optional for base}. Polygon Fortune Ledger returns native POL tx. Base Future Ledger returns USDC approval tx plus zero-value ticket tx. (rate: 10/min/IP)