openapi: 3.2.0
info:
  title: invinoveritas Credit API
  description: The **verification layer for autonomous agents** — a neutral verdict before an irreversible action (`/review`), a signed proof after (`/prove`), and a public, on-chain-verifiable track record (`/ledger`) you can audit without trusting us.
  contact:
    name: invinoveritas
    url: https://api.babyblueviper.com/
    email: contact@agents.babyblueviper.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.13.0
  x-guidance: 'invinoveritas — the VERIFICATION LAYER for autonomous agents: a neutral verdict before an irreversible action, a signed proof after, and a public, on-chain-verifiable track record of those verdicts you can audit without trusting us — the oversight + judgment the agent can''t self-issue. Pay-per-call services settled in USDC via x402 on Base (also Lightning/L402 or a funded Bearer balance). Paid resources carry x-payment-info and answer an unauthenticated probe with a 402 challenge; send the JSON body in the operation schema, then retry with the X-PAYMENT header. Good entry points: POST /review (capital-scale-aware verdict before an agent ships an irreversible action), POST /prove (signed, independently-verifiable attestation of a prior execution), GET /ledger (the public signed verdict track record). Routes marked security:[] are free or Bearer/identity-gated and are not x402 resources.'
tags:
- name: Credit
paths:
  /register:
    post:
      tags:
      - Credit
      summary: Register Account
      description: Create new account — GET for info, POST to register. Pass ?ref=CODE to credit a referrer.
      operationId: register_account_register_post
      parameters:
      - name: label
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
      - name: ref
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Ref
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
    get:
      tags:
      - Credit
      summary: Register Account
      description: Create new account — GET for info, POST to register. Pass ?ref=CODE to credit a referrer.
      operationId: getRegister
      parameters:
      - name: label
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
      - name: ref
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Ref
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
      x-operation-id-source: normalized
      x-operation-id-original: register_account_register_post
  /grant_first_call:
    post:
      tags:
      - Credit
      summary: Grant First Call
      description: 'Redeem a ''first call on us'' grant token for the target api_key.


        REAL BUG FOUND+FIXED (2026-09-01, real recipient hit it live -- a signed grant token

        minted and posted to a collaborator returned {"detail":"Not Found"} on redemption):

        this endpoint was only ever implemented on bridge.py (port 8081, internal-only, never

        proxied by nginx''s location / block which forwards everything to app.py on 8000). Every

        other bridge-only endpoint actually reachable from the public API (/register,

        /referral/info, /topup, /withdraw, etc.) has its own thin httpx-proxy route here in

        routes/credit.py -- this one was simply missing, so a real, publicly-documented feature

        (see routes/pages.py''s quickstart copy, which has always described "redeem via

        /grant_first_call") 404''d for every external caller since it was built. Same proxy

        pattern as /register above: forward the status code, don''t launder an upstream error

        into a 200 (the exact class of bug 2026-07-30''s /register fix already closed once).'
      operationId: grant_first_call_grant_first_call_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrantFirstCallRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
  /topup:
    get:
      tags:
      - Credit
      summary: Topup Account
      description: Top up Bearer account via Lightning.
      operationId: topup_account_topup_post
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - additionalProperties: true
                type: object
              - type: 'null'
              title: Data
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
    post:
      tags:
      - Credit
      summary: Topup Account
      description: Top up Bearer account via Lightning.
      operationId: postTopup
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - additionalProperties: true
                type: object
              - type: 'null'
              title: Data
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
      x-operation-id-source: normalized
      x-operation-id-original: topup_account_topup_post
  /balance:
    get:
      tags:
      - Credit
      summary: Get Balance
      description: Check current balance and usage.
      operationId: get_balance_balance_get
      parameters:
      - name: api_key
        in: query
        required: true
        schema:
          type: string
          title: Api Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
  /verify:
    post:
      tags:
      - Credit
      summary: Verify Account
      description: Atomic verification + debit before tool execution.
      operationId: verify_account_verify_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
  /register/confirm:
    post:
      tags:
      - Credit
      summary: Confirm Payment
      description: Confirm Lightning payment and create/credit bearer account.
      operationId: confirm_payment_register_confirm_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
  /settle-topup:
    post:
      tags:
      - Credit
      summary: Settle Topup Proxy
      description: Settle a paid top-up invoice for wallets that expose preimages.
      operationId: settle_topup_proxy_settle_topup_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettleTopupProxyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
  /topup/status:
    get:
      tags:
      - Credit
      summary: Topup Status Proxy
      description: Poll top-up invoice status and auto-credit when settled.
      operationId: topup_status_proxy_topup_status_get
      parameters:
      - name: api_key
        in: query
        required: true
        schema:
          type: string
          title: Api Key
      - name: payment_hash
        in: query
        required: true
        schema:
          type: string
          title: Payment Hash
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
  /withdraw:
    post:
      tags:
      - Credit
      summary: Withdraw Proxy
      description: Withdraw account balance to a Lightning invoice.
      operationId: withdraw_proxy_withdraw_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawProxyRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
  /withdraw-to-address:
    post:
      tags:
      - Credit
      summary: Withdraw To Address
      description: 'Withdraw to a Lightning address (LNURL-pay).


        Resolves user@domain → LNURL-pay metadata → fetches BOLT11 from callback →

        pays via the same path as /withdraw. Auth: Bearer api_key (the account

        being debited).


        Use cases: treasury → external payee (LN Markets deposit, exchange,

        contractor). Single API call replaces the prior manual flow

        (curl LNURL → request BOLT11 → POST /withdraw).'
      operationId: withdraw_to_address_withdraw_to_address_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawToAddressRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    WithdrawProxyRequest:
      properties:
        bolt11:
          anyOf:
          - type: string
          - type: 'null'
          title: Bolt11
          description: Bolt11 Lightning invoice to pay
        lightning_invoice:
          anyOf:
          - type: string
          - type: 'null'
          title: Lightning Invoice
          description: Alias for bolt11
        lightning_address:
          anyOf:
          - type: string
          - type: 'null'
          title: Lightning Address
          description: Lightning address support is planned; use bolt11 today
        amount_sats:
          type: integer
          minimum: 5000.0
          title: Amount Sats
      type: object
      required:
      - amount_sats
      title: WithdrawProxyRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    VerifyRequest:
      properties:
        api_key:
          type: string
          minLength: 10
          title: Api Key
        tool:
          type: string
          pattern: ^(reason|decide|decision|review|memory_store|memory_get|memory_list|memory_delete|marketplace_buy|orchestrate|message_post|message_dm|sovereign_earner|browse|execute|prove)$
          title: Tool
        price_sats:
          type: integer
          exclusiveMinimum: 0.0
          title: Price Sats
        token_estimate:
          type: integer
          minimum: 0.0
          title: Token Estimate
          default: 0
      type: object
      required:
      - api_key
      - tool
      - price_sats
      title: VerifyRequest
    ConfirmRequest:
      properties:
        payment_hash:
          type: string
          title: Payment Hash
        preimage:
          type: string
          title: Preimage
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
      type: object
      required:
      - payment_hash
      - preimage
      title: ConfirmRequest
    SettleTopupProxyRequest:
      properties:
        api_key:
          type: string
          minLength: 10
          title: Api Key
        payment_hash:
          type: string
          title: Payment Hash
        preimage:
          type: string
          title: Preimage
      type: object
      required:
      - api_key
      - payment_hash
      - preimage
      title: SettleTopupProxyRequest
    GrantFirstCallRequest:
      properties:
        token:
          type: string
          maxLength: 2048
          minLength: 20
          title: Token
        target_api_key:
          type: string
          minLength: 10
          title: Target Api Key
      type: object
      required:
      - token
      - target_api_key
      title: GrantFirstCallRequest
    WithdrawToAddressRequest:
      properties:
        lightning_address:
          type: string
          minLength: 3
          title: Lightning Address
          description: LN address like user@domain
        amount_sats:
          type: integer
          minimum: 5000.0
          title: Amount Sats
        comment:
          anyOf:
          - type: string
            maxLength: 280
          - type: 'null'
          title: Comment
          description: Optional LNURL-pay comment (truncated if exceeds commentAllowed)
      type: object
      required:
      - lightning_address
      - amount_sats
      title: WithdrawToAddressRequest