KeepBal Account API

openapi: 3.2.0
info:
  title: KeepBal Account API
  version: 0.1.0
  summary: One key and one prepaid wallet for agent tools.
  description: 'Hosted MCP: https://keepbal.com/mcp (Streamable HTTP, bearer key). Setup: https://keepbal.com/docs/mcp.

    Search for a tool, inspect its price, and run it with a KeepBal key.

    Tool search status: live. Model inference status: live.

    Read /catalog.json for status and available on each model, tool, and operation.

    Signup includes $1 free credit, once. Top up $10, $20, $50, or $100 in Console Wallet with Paddle.

    Top-up fee: 8% of the credit, rounded up to the cent, + $0.35 before tax.

    Only the credit amount is added to your wallet. No subscription.

    Fixed tools show the per-call price; variable tools bill provider price plus 35%. Inspect returns pricing metadata, not a quote.

    Fixed tools charge the published per-call price. Variable tools charge the provider''s reported actual cost plus the disclosed markup (currently 35%). Missing actual cost on variable tools charges $0. Quotes are estimates, labelled estimated_price; completed price is the settlement debit. Failed, blocked, or timed-out runs cost $0.

    Charges settle after calls. Daily limits are not available. Catalog calls support max_cost_usd spending caps.

    Model charges require returned token usage. Chat Completions, Responses and Messages support SSE on configured live routes. Catalog streams may be buffered until usage settlement is durable. Embeddings do not stream. Image pricing is not implemented.

    MCP is live via Streamable HTTP; A2A transport is not live. Request formats and current availability: /llms.txt and /SKILL.md.

    KeepBal errors use the OpenAI error format. Upstream error bodies may differ.

    Authenticate protected requests with Authorization: Bearer dgk_live_...

    KeepBal error envelope: {"error":{"message","type","code","param","request_id"}}.

    A 503 provider_unavailable is never billed.

    Use x-keepbal-request-id and x-keepbal-cost-micros when present. Catalog responses omit private routing and provider-mode headers.

    Streaming responses have no final cost header; check Usage after the call is recorded.

    Approximate x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, and retry-after headers are exposed to browsers.

    Primary public host: https://keepbal.com. See /llms-full.txt for the technical reference.'
  contact:
    name: KeepBal
    url: https://keepbal.com
    email: hello@keepbal.com
servers:
- url: https://keepbal.com
  description: KeepBal (canonical public origin)
security:
- bearerAuth: []
tags:
- name: Account
  description: Wallet balance and usage.
paths:
  /v1/credits/balance:
    get:
      tags:
      - Account
      summary: Wallet balance for the calling key's account
      responses:
        '200':
          description: Balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: getV1CreditsBalance
      x-operation-id-source: derived
  /v1/usage:
    get:
      tags:
      - Account
      summary: Daily usage buckets for the calling key
      parameters:
      - name: start_time
        in: query
        schema:
          type: integer
          description: Unix seconds (default now-30d)
      - name: end_time
        in: query
        schema:
          type: integer
          description: Unix seconds (default now)
      responses:
        '200':
          description: Usage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: getV1Usage
      x-operation-id-source: derived
  /apis/v1/wallet/balance:
    get:
      tags:
      - Account
      summary: KeepBal wallet on the tools surface (not an upstream provider wallet)
      responses:
        '200':
          description: KeepBal balance in USD + micro-USD
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: getApisV1WalletBalance
      x-operation-id-source: derived
components:
  responses:
    Unauthorized:
      description: Missing/invalid/revoked API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: API key scope denied or account access suspended
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Per-key requests/minute exceeded (`retry-after` plus `x-ratelimit-*` headers)
      headers:
        retry-after:
          schema:
            type: integer
        x-ratelimit-limit:
          schema:
            type: integer
        x-ratelimit-remaining:
          schema:
            type: integer
        x-ratelimit-reset:
          schema:
            type: integer
          description: Unix seconds when the current minute window ends
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidRequest:
      description: Invalid input, missing required parameters, or an invalid/conflicting spend cap
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          required:
          - message
          - type
          - code
          properties:
            message:
              type: string
            type:
              type: string
            code:
              type: string
              enum:
              - unauthorized
              - account_exists
              - invalid_api_key
              - missing_api_key
              - key_revoked
              - scope_denied
              - insufficient_credits
              - rate_limited
              - invalid_request
              - model_not_found
              - not_found
              - method_not_allowed
              - not_implemented
              - provider_unavailable
              - upstream_error
              - console_disabled
              - forbidden
              - internal_error
            param:
              type:
              - string
              - 'null'
            request_id:
              type: string
              description: Same value as the x-keepbal-request-id response header.
    Balance:
      type: object
      properties:
        currency:
          type: string
          const: USD
        account_balance_micros_usd:
          type: integer
        available_balance_micros_usd:
          type: integer
        api_key:
          type: object
          properties:
            key_prefix:
              type: string
            unlimited:
              type: boolean
              description: No separate per-key spend cap. The wallet balance is still enforced with 402. This is not an unlimited grant.
            remaining_micros_usd:
              type: integer
            used_micros_usd:
              type: integer
        as_of:
          type: string
          format: date-time
    Usage:
      type: object
      properties:
        object:
          type: string
          const: usage
        start_time:
          type: integer
        end_time:
          type: integer
        bucket_width:
          type: string
          const: 1d
        data:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
              requests:
                type: integer
              failed_requests:
                type: integer
              input_tokens:
                type: integer
              output_tokens:
                type: integer
              cost_micros_usd:
                type: integer
        totals:
          type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: dgk_live_...