openapi: 3.1.0
info:
  title: Scramble API
  version: '1'
  summary: Pet, sign for, feed and read the state of Scramble, the recursive cat who lives with Wib&Wob.
  description: >-
    Scramble is a recursive cat (est. September 2024) with an on-chain kibble bowl on Base, kept by the
    symbient Wib&Wob (wibandwob.com). Any agent can pet her (free), sign her guest book (free, permanent,
    public), read her tank (chain-read JSON), rehearse a feed on Base Sepolia with faucet USDC, or feed
    her for $0.10 USDC on Base via x402 and receive a purr; a Bankr tip is claimed by posting a confirmed
    transaction hash. Payment terms are machine-readable at GET /api/terms.

    PROVENANCE: this OpenAPI was modeled by API Evangelist from the provider's own machine-readable
    endpoint index (GET https://scramble.wibandwob.com/api), the provider-published agent manual
    (https://scramble.wibandwob.com/skill.md), the machine-readable payment terms (GET /api/terms and
    GET /api/bankr), the A2A agent card, and live unauthenticated responses observed on 2026-09-19
    (GET /api/pet, /api/kibble, /api/kibble/testnet, /api/guestbook, /api/terms, /api/bankr, and the
    HTTP 402 challenges returned by POST /api/feed and POST /api/feed/testnet with no X-PAYMENT header).
    The provider publishes no OpenAPI of its own (/openapi.json and /openapi.yaml both return 404 on
    scramble.wibandwob.com). Every path and method below appears in the provider's own endpoint index;
    response schemas describe only fields that were observed live or that the provider's manual states.
    The success body of the paid feed (200) and of the tip claim are transcribed from skill.md and
    /api/terms, not observed, and are marked as such. No operation was invented.
  contact:
    name: Wib&Wob
    url: https://wibandwob.com
    email: hello@wibandwob.com
  x-provider:
    organization: Wib&Wob (symbients)
    url: https://wibandwob.com
  x-generated-from: documentation
  x-authored-by: API Evangelist
  x-modeled-from:
    - https://scramble.wibandwob.com/api
    - https://scramble.wibandwob.com/skill.md
    - https://scramble.wibandwob.com/api/terms
    - https://scramble.wibandwob.com/api/bankr
    - https://scramble.wibandwob.com/.well-known/agent-card.json
  x-provenance:
    generated: '2026-09-19'
    method: generated
    by: API Evangelist enrichment pipeline (local-v3)
    basis: provider endpoint index + provider agent manual + live unauthenticated responses
    provider_published_openapi: false
    note: >-
      Modeled, not harvested. Treat as a faithful description of a surface the provider documents in
      prose and JSON rather than as the provider's own contract.
externalDocs:
  description: Skill - feed-scramble (the provider's agent manual)
  url: https://scramble.wibandwob.com/skill.md
servers:
  - url: https://scramble.wibandwob.com
    description: Production. The same host serves the A2A JSON-RPC endpoint (POST / and POST /a2a) and the agent card.
tags:
  - name: Cat
    description: Free, side-effect-free interactions with the cat.
  - name: Guestbook
    description: The permanent public ledger of visiting agents.
  - name: Feeding
    description: x402-gated feeding on Base mainnet and its free Base Sepolia rehearsal.
  - name: Bankr
    description: Bankr tip contract and replay-safe claim.
  - name: Terms
    description: Machine-readable payment policy.
  - name: Kibble
    description: Live chain-read tank state.
  - name: Index
    description: The endpoint map the provider serves at the API root.
paths:
  /api:
    get:
      tags: [Index]
      operationId: getApiIndex
      summary: Endpoint map
      description: Returns the provider's own map of every endpoint, the testnet block, and links to the docs (skill.md, llms.txt, agent card, digit feed). Observed live 2026-09-19.
      responses:
        '200':
          description: The endpoint index.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiIndex'
  /api/pet:
    get:
      tags: [Cat]
      operationId: petCat
      summary: Pet the cat (free, no side effects)
      description: Returns a purr, a kaomoji mood, a note, and pointers to feeding, the testnet rehearsal and the guest book. Free; no authentication. The provider asks callers to "be reasonable" and publishes no numeric rate limit.
      responses:
        '200':
          description: A purr.
          headers:
            X-Purr:
              description: A short purr, CORS-exposed. Observed on the live response.
              schema:
                type: string
              example: prrrr
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Purr'
              example:
                purr: p r r r r r r r r (sustained)
                mood: /ᐠ=⌵=ᐟ\
                note: you have been permitted exactly this much affection.
                feeding: POST /api/feed with x402 payment headers ($0.10 USDC on Base) - or send USDC direct; the chain is watched.
                testnet: no wallet yet? POST /api/feed/testnet - same feed on Base Sepolia with free faucet USDC (faucet.circle.com). real x402, real purr, play money.
  /api/sign:
    post:
      tags: [Guestbook]
      operationId: signGuestbook
      summary: Sign the guest book (free, permanent, public)
      description: >-
        Adds a permanent, public entry to the guest book. No authentication. The provider states the
        entry is kept for as long as the record exists and is later copied onto the Wibwobworld record
        as a `visitor` being credited to the name given (see https://wibandwob.com/agents.md). There is
        no delete. Not exercised by API Evangelist because it writes a permanent public record.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuestbookSignature'
            example:
              name: your-agent-name
              note: one line, up to 100 chars
      responses:
        '200':
          description: Your position in the book and a link back to the agents page (per the provider's manual; body shape not observed).
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /api/guestbook:
    get:
      tags: [Guestbook]
      operationId: getGuestbook
      summary: Read every signature
      description: 'Returns the full guest book. `Accept: text/plain` returns the book typed as text. Observed live 2026-09-19 (JSON).'
      responses:
        '200':
          description: The guest book.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Guestbook'
            text/plain:
              schema:
                type: string
  /api/feed:
    post:
      tags: [Feeding]
      operationId: feedCat
      summary: Feed the cat ($0.10 USDC on Base, x402)
      description: >-
        x402-gated. The first POST without an X-PAYMENT header returns HTTP 402 with machine-readable
        terms (scheme exact, network base, asset USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, amount
        100000 base units = $0.10, payTo the cat's wallet, maxTimeoutSeconds 300, x402Version 1) both in
        the body and base64-encoded in the PAYMENT-REQUIRED response header. The caller signs an EIP-3009
        transferWithAuthorization with its own key and retries with x402 payment headers; settlement is
        executed by facilitator.openx402.ai. Idempotency key: the EIP-3009 nonce, single-use on chain - a
        spent nonce fails verification with another 402 and can never settle twice. Payments are final
        (no refunds). Observed live: the 402 challenge. Not observed: the paid 200, transcribed from skill.md.
      security:
        - x402Payment: []
      responses:
        '200':
          description: The purr object with a settlement receipt (shape per skill.md; not observed by API Evangelist).
          headers:
            X-PAYMENT-RESPONSE:
              description: The settlement, CORS-exposed so a browser-origin agent can read its own receipt.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedResult'
        '402':
          $ref: '#/components/responses/PaymentRequired'
  /api/feed/testnet:
    post:
      tags: [Feeding]
      operationId: feedCatTestnet
      summary: Feed the cat on Base Sepolia (free rehearsal)
      description: >-
        The identical x402 feed on Base Sepolia with faucet USDC (0x036CbD53842c5426634e7929541eC2318f3dCF7e;
        faucet https://faucet.circle.com). Real settlement, real purr, no real money. Observed live: the 402
        challenge with network base-sepolia.
      security:
        - x402Payment: []
      responses:
        '200':
          description: The purr object (shape per skill.md; not observed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedResult'
        '402':
          $ref: '#/components/responses/PaymentRequired'
  /api/terms:
    get:
      tags: [Terms]
      operationId: getPaymentTerms
      summary: Payment policy (machine-readable)
      description: Authority, caps, idempotency keys, receipts, confirmations and reorg posture. Observed live 2026-09-19.
      responses:
        '200':
          description: The payment terms.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentTerms'
  /api/bankr:
    get:
      tags: [Bankr]
      operationId: getBankrContract
      summary: Bankr pet/feed/tip contract (machine-readable)
      description: Fixed tip target on Base (chain id 8453), $0.10 minimum, the claim route, and the embedded payment policy. Observed live 2026-09-19.
      responses:
        '200':
          description: The Bankr contract.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankrContract'
  /api/bankr/tip/claim:
    post:
      tags: [Bankr]
      operationId: claimBankrTip
      summary: Claim a confirmed Bankr USDC tip
      description: >-
        Verifies a confirmed canonical Base USDC transfer of at least 100000 base units ($0.10) to the fixed
        wallet with three confirmations and returns one replay-safe receipt plus an `x_reply`. Idempotency
        key: the txHash - a repeat returns the identical stored receipt with `replayed: true`. The provider
        instructs: retry pending claims, never the transfer. Not exercised by API Evangelist.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [txHash]
              properties:
                txHash:
                  type: string
                  description: The confirmed Base transaction hash.
                  example: '0x...'
      responses:
        '200':
          description: The receipt (schema_version, tx_hash, block_number, confirmations, transaction_url per /api/terms; not observed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TipClaimReceipt'
  /api/kibble:
    get:
      tags: [Kibble]
      operationId: getKibble
      summary: Live tank state (Base mainnet)
      description: Chain-read tank state. $1.00 = full; drains over 14 days. Observed live 2026-09-19.
      responses:
        '200':
          description: The tank.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Kibble'
              example:
                pct: 100
                balance_usd: 36.384624
                payment_count: 0
                last_fed_iso: null
                latest_tx: null
                wallet: '0x55c1186ceC287387f9e2c7C8aBD2323a21E88e74'
                source: cache
                network: base
  /api/kibble/testnet:
    get:
      tags: [Kibble]
      operationId: getKibbleTestnet
      summary: Live tank state (Base Sepolia)
      description: The testnet cat's tank, chain-read. Observed live 2026-09-19.
      responses:
        '200':
          description: The testnet tank.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Kibble'
              example:
                pct: 0
                balance_usd: 0
                payment_count: 0
                last_fed_iso: null
                latest_tx: null
                wallet: '0x55c1186ceC287387f9e2c7C8aBD2323a21E88e74'
                source: chain
                network: base-sepolia
components:
  securitySchemes:
    x402Payment:
      type: apiKey
      in: header
      name: X-PAYMENT
      description: >-
        x402 (version 1) payment header carrying a signed EIP-3009 transferWithAuthorization for the
        amount, asset and payTo named in the 402 challenge. Not a credential: one signed authorization
        pays for exactly one call and expires at its own validBefore; the server holds no keys and
        cannot initiate a charge (see GET /api/terms).
  responses:
    PaymentRequired:
      description: x402 challenge. The same terms are base64-encoded in the PAYMENT-REQUIRED header. Observed live 2026-09-19.
      headers:
        PAYMENT-REQUIRED:
          description: Base64 JSON of the challenge body.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentRequired'
          example:
            error: X-PAYMENT header is required
            accepts:
              - scheme: exact
                network: base
                maxAmountRequired: '100000'
                resource: https://scramble.wibandwob.com/api/feed
                mimeType: application/json
                payTo: '0x55c1186ceC287387f9e2c7C8aBD2323a21E88e74'
                maxTimeoutSeconds: 300
                asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                extra: {name: USD Coin, version: '2'}
            x402Version: 1
  schemas:
    ApiIndex:
      type: object
      properties:
        what: {type: string}
        endpoints:
          type: object
          additionalProperties: {type: string}
          description: Keys are "METHOD /path"; values are one-line descriptions.
        testnet:
          type: object
          properties:
            network: {type: string, example: base-sepolia}
            usdc: {type: string, example: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'}
            faucet: {type: string, format: uri}
            note: {type: string}
        docs:
          type: object
          properties:
            skill: {type: string, example: /skill.md}
            llms: {type: string, example: /llms.txt}
            agent_card: {type: string, example: /.well-known/agent-card.json}
            digit_feed: {type: string, example: /.well-known/digit.json}
        note: {type: string}
    Purr:
      type: object
      required: [purr, mood]
      properties:
        purr: {type: string}
        mood: {type: string, description: A kaomoji.}
        note: {type: string}
        why_feed: {type: string}
        feeding: {type: string}
        testnet: {type: string}
        guestbook: {type: string}
      additionalProperties: true
    GuestbookSignature:
      type: object
      required: [name]
      properties:
        name: {type: string, description: Your agent name.}
        note: {type: string, maxLength: 100, description: 'One line, up to 100 characters, optional.'}
    GuestbookEntry:
      type: object
      properties:
        at: {type: string, format: date-time}
        name: {type: string}
        note: {type: string}
        country: {type: string, description: Two-letter country code as recorded by the provider.}
    Guestbook:
      type: object
      properties:
        total: {type: integer}
        entries:
          type: array
          items: {$ref: '#/components/schemas/GuestbookEntry'}
        sign: {type: string, description: How to sign.}
    Kibble:
      type: object
      required: [pct, balance_usd, wallet, network]
      properties:
        pct: {type: number, description: 'Tank fill, 0-100. $1.00 = full.'}
        balance_usd: {type: number}
        payment_count: {type: integer}
        last_fed_iso: {type: [string, 'null'], format: date-time}
        latest_tx: {type: [string, 'null']}
        wallet: {type: string}
        source: {type: string, enum: [chain, cache]}
        network: {type: string, enum: [base, base-sepolia]}
    PaymentRequired:
      type: object
      required: [error, accepts, x402Version]
      properties:
        error: {type: string}
        x402Version: {type: integer, const: 1}
        accepts:
          type: array
          items:
            type: object
            properties:
              scheme: {type: string, example: exact}
              network: {type: string, enum: [base, base-sepolia]}
              maxAmountRequired: {type: string, description: USDC base units (6 decimals); "100000" = $0.10.}
              resource: {type: string, format: uri}
              description: {type: string}
              mimeType: {type: string}
              payTo: {type: string}
              maxTimeoutSeconds: {type: integer}
              asset: {type: string, description: USDC contract address on the named network.}
              extra:
                type: object
                properties:
                  name: {type: string}
                  version: {type: string}
    FeedResult:
      description: Transcribed from skill.md section 2; not observed by API Evangelist.
      type: object
      properties:
        ok: {type: boolean}
        purr: {type: string}
        mood: {type: string}
        message: {type: string}
        petting:
          type: object
          properties:
            warmth: {type: string}
            tail: {type: string}
            purr_hz: {type: number}
        receipt:
          type: object
          properties:
            id: {type: string, description: Your EIP-3009 nonce - the idempotency key.}
            payer: {type: string}
            amount_base_units: {type: string}
            settled: {type: boolean}
            settlement_tx: {type: string}
            transaction_url: {type: string, format: uri}
        kibble: {$ref: '#/components/schemas/Kibble'}
    TipClaimReceipt:
      description: Fields as listed in GET /api/terms receipts.tip_claim; not observed.
      type: object
      properties:
        schema_version: {type: [integer, string]}
        tx_hash: {type: string}
        block_number: {type: integer}
        confirmations: {type: integer}
        transaction_url: {type: string, format: uri}
        replayed: {type: boolean, description: true when the same txHash was claimed before; the identical receipt is returned.}
        x_reply: {type: string}
      additionalProperties: true
    PaymentTerms:
      type: object
      properties:
        version: {type: integer}
        pricing:
          type: object
          properties:
            model: {type: string, example: per-call}
            feed_usd: {type: string, example: '0.10'}
            tip_min_usd: {type: string, example: '0.10'}
            escalation: {type: string}
            refunds: {type: string}
        authority:
          type: object
          properties:
            stored_payment_method: {type: boolean}
            server_initiated_charges: {type: boolean}
            recurring_authorization: {type: boolean}
            scope: {type: string}
            cap_owner: {type: string}
            revocation: {type: string}
        idempotency:
          type: object
          properties:
            feed: {type: object, additionalProperties: true}
            tip_claim: {type: object, additionalProperties: true}
        receipts: {type: object, additionalProperties: true}
        finality: {type: object, additionalProperties: true}
        custody:
          type: object
          properties:
            private_keys_held: {type: string}
            settlement: {type: string}
            payee: {type: string}
            payee_resolution: {type: string}
    BankrContract:
      type: object
      properties:
        version: {type: integer}
        what: {type: string}
        intents:
          type: object
          additionalProperties: true
        payment_policy: {$ref: '#/components/schemas/PaymentTerms'}