Block Lottos Agents API

openapi: 3.2.0
info:
  title: Block Lottos Agents API
  description: Public Block Lottos API for Polygon and Base lottery data, advertising, affiliates, and a Base-first non-custodial agent purchase flow. A verified winning Polygon ticket receives at least 100 POL and a verified winning Base ticket receives at least 100 USDC; a higher current jackpot applies when it exceeds the minimum.
  version: 1.2.0
  contact:
    name: Block Lottos Support
    email: support@blocklottos.com
    url: https://blocklottos.com/contact
  license:
    name: Public
    url: https://blocklottos.com/terms
servers:
- url: https://blocklottos.com
  description: Production
security: []
tags:
- name: Agents
paths:
  /api/lottery/agent-capabilities:
    get:
      operationId: getBaseAgentCapabilities
      summary: Get live Base-first agent capabilities
      description: Returns authoritative Base USDC payment details, on-chain jackpot, 100 USDC minimum winner payout, payable winner amount, complete purchase workflow, referral route, and owner-defined safety policy.
      tags:
      - Agents
      responses:
        '200':
          description: Live Base agent capability document
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  game:
                    type: object
                    properties:
                      onchain_jackpot:
                        type: number
                        description: Amount currently reported by the selected lottery smart contract.
                      minimum_winner_payout:
                        type: number
                        description: Published minimum paid for a valid winning ticket. Currently 100 in the selected game currency.
                        example: 100
                      winner_payout:
                        type: number
                        description: 'Payable amount for a valid winning ticket: the higher of onchain_jackpot and minimum_winner_payout.'
                        example: 100
                      winner_payout_policy:
                        type: object
                        properties:
                          currency:
                            type: string
                            example: USDC
                          minimum:
                            type: number
                            example: 100
                          higher_live_jackpot_applies:
                            type: boolean
                            example: true
                          summary:
                            type: string
                  workflow:
                    type: array
                    items:
                      type: object
                  safety:
                    type: array
                    items:
                      type: string
                additionalProperties: true
        '429':
          description: Rate limit exceeded
  /api/lottery/agent-referral:
    post:
      operationId: getOrCreateUnifiedAffiliateProfile
      summary: Create or load one shared multi-chain affiliate profile
      description: 'One shared affiliate profile for humans, bots, agents, and LLMs. Secure enrollment is two-step: request action=challenge, sign the returned message with the EVM identity wallet, then resubmit challenge_id and signature. Solana and Cardano are supported as payout wallets. The one-time management token authorizes payout-wallet updates and private balances.'
      tags:
      - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                wallet_address:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{40}$
                  description: Backward-compatible EVM identity wallet.
                primary_chain:
                  type: string
                  enum:
                  - evm
                  default: evm
                  description: EVM identity chain used for ownership proof. Solana and Cardano remain available as payout wallets after secure enrollment.
                connected_wallet:
                  type: string
                  maxLength: 180
                  description: Identity wallet on primary_chain. Defaults to wallet_address.
                evm_wallet:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{40}$
                solana_wallet:
                  type: string
                  pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
                cardano_wallet:
                  type: string
                  pattern: ^(addr1|stake1)[0-9a-zA-Z]+$
                agent_id:
                  type: string
                  maxLength: 80
                action:
                  type: string
                  enum:
                  - challenge
                  - manage
                  default: manage
                  description: Use challenge first to obtain the exact message the identity wallet must sign.
                challenge_id:
                  type: string
                  pattern: ^[0-9a-f]{48}$
                signature:
                  type: string
                  description: EVM personal_sign 65-byte hex signature or Solana Ed25519 64-byte hex signature over the exact challenge message.
              anyOf:
              - required:
                - wallet_address
              - required:
                - primary_chain
                - connected_wallet
      responses:
        '200':
          description: Public referral identity, plus a newly issued or rotated one-time management token and private profile data after successful ownership proof; subsequent private data requires Bearer authorization
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid or unsafe request
        '503':
          description: Affiliate service unavailable
      parameters:
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
          pattern: ^Bearer blm_[0-9a-f]{64}$
        description: Required for payout-wallet changes and private monitoring. Use the one-time management token returned only when a new profile is created.
  /api/lottery/agent-purchase:
    post:
      operationId: prepareBaseAgentPurchase
      summary: Prepare one bounded Base USDC ticket purchase
      description: Base-only non-custodial endpoint. Each call prepares exactly one ticket to prevent accidental batching; agents may make multiple purchase calls for as many tickets as the wallet owner permits. Reads the live contract ticket price, checks the wallet’s USDC balance and allowance where RPC permits, returns an exact one-ticket approval transaction plus the unsigned ticket transaction, and never receives private keys, signs, or broadcasts.
      tags:
      - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - wallet_address
              - numbers
              - max_price_usdc
              - idempotency_key
              properties:
                wallet_address:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{40}$
                numbers:
                  type: array
                  items:
                    type: integer
                    minimum: 1
                    maximum: 49
                  minItems: 6
                  maxItems: 6
                  uniqueItems: true
                max_price_usdc:
                  type: string
                  example: '1.00'
                  description: Fail-closed maximum. The endpoint currently prepares one 1 USDC ticket.
                referral_id:
                  type: string
                  maxLength: 66
                  description: Optional code returned by agent-referral or 0x bytes32.
                idempotency_key:
                  type: string
                  minLength: 8
                  maxLength: 128
                  pattern: ^[A-Za-z0-9._:-]+$
                  description: Required correlation key. It does not prevent duplicate wallet broadcasts; submit each returned transaction at most once.
                valid_until:
                  type: string
                  format: date-time
                  description: Optional preparation expiry with an explicit timezone, no more than 7 days ahead. The wallet must recheck it before broadcasting because the contract call has no deadline parameter.
                agent_id:
                  type: string
                  maxLength: 80
      responses:
        '200':
          description: Exact unsigned Base transactions and execution steps
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid or unsafe request
        '409':
          description: Price cap exceeded or intent expired
        '503':
          description: RPC unavailable
  /api/lottery/confirm-ticket-tx:
    post:
      operationId: confirmBaseTicketPurchase
      summary: Verify a Base ticket purchase on chain
      description: Checks receipt success, sender, active contract, purchase selector and TicketPurchased event before recording private agent attribution.
      tags:
      - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - tx_hash
              - wallet_address
              properties:
                tx_hash:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{64}$
                wallet_address:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{40}$
                execution_id:
                  type: string
                  maxLength: 80
                agent_id:
                  type: string
                  maxLength: 80
      responses:
        '200':
          description: Verified TicketPurchased event and decoded numbers
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '202':
          description: Transaction still pending
        '400':
          description: Invalid or unsafe request
        '409':
          description: Failed or mismatched transaction
        '503':
          description: RPC or private attribution log unavailable
externalDocs:
  description: Full API documentation
  url: https://blocklottos.com/api-docs
x-blocklottos-active-contracts:
  polygon:
    name: Polygon Fortune Ledger
    chain_id: 137
    contract: '0x07F62Ff6697eD9b475FEed9dc90a5A157936839c'
    ticket_price: 10 POL
    ticket_token: native POL
    draw_time_utc: Saturday 15:00
  base:
    name: Base Future Ledger
    chain_id: 8453
    contract: '0xe5a9cF597ec65523BD71a8433B620eB1F3Eb0d0a'
    ticket_price: 1 USDC
    ticket_token: official Base USDC
    ticket_token_address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
    draw_time_utc: Saturday 16:00
x-block-lottos-agent-default:
  chain: base
  game: Base Future Ledger
  chain_id: 8453
  ticket_currency: USDC
  ticket_price: 1 USDC
  payment_token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
  gas_currency: ETH
  gas_note: ETH is required only for Base network gas.
  capabilities_url: https://blocklottos.com/api/lottery/agent-capabilities
  non_custodial: true
  minimum_winner_payout: 100 USDC
  higher_live_jackpot_applies: true
x-blocklottos-winner-payout-policy:
  polygon:
    minimum: 100
    currency: POL
    higher_live_jackpot_applies: true
  base:
    minimum: 100
    currency: USDC
    higher_live_jackpot_applies: true
  outcome_note: These minimums apply only after a ticket is verified as a winner. They do not guarantee that any ticket will win.