DiffiCat Balance API

openapi: 3.2.0
info:
  title: Difficat Com Balance API
  version: 3.149.0
  description: 'Operations tagged Balance across 2 of this provider''s published API definitions: difficat-com-agent-api-openapi.json, difficat-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://app.difficat.com/api/v1
tags:
- name: Balance
paths:
  /balance:
    get:
      operationId: getBalance
      summary: The prepaid key’s balance and recent ledger entries. Free
      security:
      - prepaidKey: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponse'
              example:
                keyId: 3f9c2a71
                balance: '4.94'
                currency: USD
                recent:
                - at: '2026-09-27T13:57:18.870Z'
                  type: debit
                  amount: '0.06'
                  kind: job
                  jobId: web-209369db-8b39-4981-ad1e-b43d1b5cccc7
                - at: '2026-09-27T13:57:18.870Z'
                  type: return
                  amount: '0.02'
                  kind: job
                  jobId: web-209369db-8b39-4981-ad1e-b43d1b5cccc7
                - at: '2026-09-27T13:57:14.470Z'
                  type: topup
                  amount: '5.00'
        '401':
          description: No key, or an unknown one
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Balance
    servers:
    - url: https://app.difficat.com/api/v1
components:
  schemas:
    BalanceResponse:
      type: object
      required:
      - keyId
      - balance
      - currency
      - recent
      properties:
        keyId:
          type: string
        balance:
          type: string
          description: Spendable prepaid money, decimal USD, for any key.
        currency:
          type: string
          enum:
          - USD
        allowance:
          type: object
          description: 'Pro account’s key only: the current period’s included captured pages, shared with the web app; a live pair is 2, a pair against a snapshot 1.'
          required:
          - includedPages
          - pagesUsed
          - resetsAt
          properties:
            includedPages:
              type: integer
            pagesUsed:
              type: integer
            resetsAt:
              type: string
              format: date-time
        overage:
          type: object
          description: 'Pro account’s key only: overage priced this period and the cap, decimal USD.'
          required:
          - amount
          - capUsd
          properties:
            amount:
              type: string
            capUsd:
              type: string
        recent:
          type: array
          description: The last 20 ledger entries, newest first.
          items:
            type: object
            required:
            - at
            - type
            - amount
            properties:
              at:
                type: string
                format: date-time
              type:
                type: string
                enum:
                - topup
                - debit
                - reversal
                - overage
                - return
              amount:
                type: string
              kind:
                type: string
                enum:
                - discover
                - screenshot
                - job
              jobId:
                type: string
              surface:
                type: string
                enum:
                - web
                - api
                description: 'An account key’s draw: spent in the web app or on the API.'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
  securitySchemes:
    payment:
      type: http
      scheme: Payment
      description: 'Machine Payments Protocol (mpp.dev). A first request without a credential is answered with 402 and a WWW-Authenticate: Payment challenge; the paid retry carries Authorization: Payment <credential>. Successful responses carry a Payment-Receipt header. x402 clients are accepted on the same routes for USDC on Base.'
    jobToken:
      type: http
      scheme: bearer
      description: The jobToken returned when the job or screenshot was created. The prepaid key that paid a job is accepted in its place.
    prepaidKey:
      type: http
      scheme: bearer
      description: A prepaid key (dck_…) from the account page at /account, where a signed-in human tops up by card through Stripe Checkout and copies the key. On a paid call the priced amount is debited from its balance instead of a 402 challenge; on job reads it stands in for the jobToken of the jobs it paid.
    shareToken:
      type: http
      scheme: bearer
      description: A share token (dcs_…) a snapshot’s owner issued in the web app. It reads that one snapshot and starts live compares against it; it never lists, manages or pays.
    shareTokenHeader:
      type: apiKey
      in: header
      name: X-DiffiCat-Share
      description: The same share token, sent beside a paying Authorization credential (a prepaid or Pro key, or a payment credential) on the two compare routes.
x-refined-from:
- difficat-com-agent-api-openapi.json
- difficat-com-openapi.yml
x-service-info:
  categories:
  - web
  - testing
  - monitoring
  docs:
    homepage: https://difficat.com
    llms: https://difficat.com/llms.txt
    apiReference: https://app.difficat.com/api/v1/openapi.json
  x-prepaid:
    topUp: https://app.difficat.com/account
    amountsUsd:
    - 5
    - 10
    - 25
  x-sample:
    report: https://difficat.com/agents/sample/report.json
    freePages: 40
    freeDiscoveries: 5
    freeScreenshots: 5