📢 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.

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..."

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..."

🎲 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, and prize checks. The build-ticket-tx endpoint constructs an unsigned Polygon transaction ready for a user's wallet to sign and broadcast.

⚠️ Contract reads use dual RPC. All on-chain reads hit polygon-bor-rpc.publicnode.com first with 1rpc.io/matic as 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.

Parameters

None.

Response

{
  "status": "ok",
  "jackpot_pol": 42.5,
  "jackpot_wei": "42500000000000000000",
  "contract": "0x6a41d59260c95c56c704b60defe351bea14f0225",
  "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.

Parameters

None.

Response

{
  "status": "ok",
  "draw_number": 14,
  "jackpot_pol": 42.5,
  "jackpot_wei": "42500000000000000000",
  "rollover_count": 3,
  "next_draw_timestamp": 1745000000,
  "contract": "0x6a41d59260c95c56c704b60defe351bea14f0225",
  "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.

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)

Response

{
  "status": "ok",
  "draws": [
    {
      "draw_id": 13,
      "winning_numbers": [4, 12, 23, 31, 38, 45],
      "jackpot_pol": 30.0,
      "winner_count": 0,
      "rolled_over": true,
      "draw_timestamp": 1744400000,
      "tx_hash": "0xabc123..."
    }
  ]
}

⏱ 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	Polygon wallet address (0x...)

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 if a wallet has unclaimed prizes. Winners have 90 days to claim.

Path Parameters

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

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 to Polygon — 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 Polygon wallet address (0x...)

Request Example

{
  "numbers": [5, 12, 23, 31, 38, 45],
  "wallet_address": "0xYourWalletAddress"
}

Response

{
  "status": "ok",
  "numbers_sorted": [5, 12, 23, 31, 38, 45],
  "ticket_price_pol": 10,
  "ticket_price_wei": "10000000000000000000",
  "contract": "0x6a41d59260c95c56c704b60defe351bea14f0225",
  "chain_id": 137,
  "transaction": {
    "to": "0x6a41d59260c95c56c704b60defe351bea14f0225",
    "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