BASE167 Check API

openapi: 3.2.0
info:
  title: BASE167 Check API
  version: 1.0.0
  summary: Claim BASE167 and take part in Degen Games without a browser.
  description: 'Every write action follows one shape: POST a wallet address, receive a short-lived server-signed voucher plus ready-to-send calldata in `call`, then submit one transaction from that wallet. No login, session, cookie or CAPTCHA. Vouchers bind msg.sender, so the sending wallet must be the wallet the voucher was issued for. Prizes have no claim function and are paid manually. There is also a remote MCP server at https://base167.com/mcp exposing these same actions as named tools, with no API key and no OAuth.'
servers:
- url: https://base167.com
tags:
- name: Check
paths:
  /api/check:
    post:
      operationId: checkEligibility
      summary: Check a wallet against the 167-transaction gate and get a claim voucher
      description: 'Smart-contract wallets are supported: when the EOA nonce is short and the address has code, the count falls back to distinct outgoing asset-moving transactions, which can under-count a wallet whose activity is mostly non-transfer calls.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - address
              properties:
                address:
                  $ref: '#/components/schemas/Address'
      responses:
        '200':
          description: Eligibility result. When eligible, includes a voucher and a prepared call.
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  required:
                  - eligible
                  - txCount
                  - signature
                  - expiry
                  - call
                  properties:
                    eligible:
                      const: true
                    txCount:
                      type: integer
                    signature:
                      $ref: '#/components/schemas/Hex'
                    expiry:
                      type: integer
                      description: Unix seconds; the voucher is void after this.
                    call:
                      $ref: '#/components/schemas/PreparedCall'
                - type: object
                  required:
                  - eligible
                  - txCount
                  - required
                  - code
                  properties:
                    eligible:
                      const: false
                    txCount:
                      type: integer
                    required:
                      type: integer
                      const: 167
                    code:
                      type: string
                      description: Stable machine-readable refusal reason. Branch on this, never on the prose.
                      const: INSUFFICIENT_TX_COUNT
                    reason:
                      type: string
                      description: One sentence stating what is wrong, for a human.
                    nextStep:
                      type: string
                      description: What the user should do, if anything.
                    shortfall:
                      type: integer
                      description: How many further counted transactions are needed. required - txCount.
                  description: Ineligible because the wallet is under the transaction gate. Carries `required`; never carries `alreadyClaimed`.
                - type: object
                  description: Ineligible because this wallet has already claimed. The claim is one per wallet forever, so this is terminal -- do not retry. Distinguished from the under-the-gate branch by `alreadyClaimed`, and it deliberately omits `required` because the gate is not why the wallet was refused.
                  required:
                  - eligible
                  - alreadyClaimed
                  - txCount
                  - code
                  properties:
                    eligible:
                      const: false
                    alreadyClaimed:
                      const: true
                    txCount:
                      type: integer
                    code:
                      type: string
                      description: Stable machine-readable refusal reason. Branch on this, never on the prose.
                      const: ALREADY_CLAIMED
                    reason:
                      type: string
                      description: One sentence stating what is wrong, for a human.
                    nextStep:
                      type: string
                      description: What the user should do, if anything.
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/TooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Check
components:
  responses:
    BadRequest:
      description: Malformed JSON, address or signature.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
            properties:
              code:
                type: string
                enum:
                - INVALID_ADDRESS
                - BAD_CHECKSUM
                description: BAD_CHECKSUM means the address is correctly shaped but its mixed-case EIP-55 checksum does not verify -- send it all-lowercase or fix the checksum. INVALID_ADDRESS means it is not an address at all.
              reason:
                type: string
    RateLimited:
      description: 'Over 5 requests per minute. Retry-After: 60.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The request did not arrive through the expected proxy.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooLarge:
      description: Request body over the cap.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    Hex:
      type: string
      pattern: ^0x[a-fA-F0-9]*$
    Address:
      type: string
      pattern: ^0x[a-fA-F0-9]{40}$
      description: A mixed-case address MUST carry a valid EIP-55 checksum; an all-lowercase address is always accepted. A correctly-shaped address with a bad checksum returns 400 BAD_CHECKSUM.
    PreparedCall:
      type: object
      description: A ready-to-send transaction. Submit it from the same wallet the voucher was issued for; the contract binds msg.sender.
      required:
      - chainId
      - to
      - data
      - value
      properties:
        chainId:
          type: integer
          const: 8453
        to:
          $ref: '#/components/schemas/Address'
        data:
          allOf:
          - $ref: '#/components/schemas/Hex'
          description: 'Calldata for the action, with an ERC-8021 builder-code suffix appended after the ABI arguments. The suffix is data the contracts ignore -- it attributes the transaction to base167 on Base''s builder dashboard -- and every action built here carries it, whether it came from the browser, this API or the MCP server. Send the bytes EXACTLY as given: re-encoding the call from its arguments drops the suffix, and trimming it changes nothing else about what the transaction does.'
        value:
          type: string
          const: '0x0'