> ## Documentation Index
> Fetch the complete documentation index at: https://docs.droyd.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing credits

> Read credit balances and manage prepaid account funding.

Billing endpoints use the authenticated account as the billing owner. Monetary
request and response values are decimal USD strings.

| Method | Path                                  | Purpose                                                           |
| ------ | ------------------------------------- | ----------------------------------------------------------------- |
| `GET`  | `/v1/billing/balance`                 | Return the spendable balance and active promotional or paid lots. |
| `GET`  | `/v1/billing/transactions`            | Return recent credit-ledger activity.                             |
| `GET`  | `/v1/billing/invoices`                | Return recent Stripe payment receipts.                            |
| `POST` | `/v1/billing/payment-method/setup`    | Start secure card setup and return a Stripe client secret.        |
| `POST` | `/v1/billing/payment-method/complete` | Confirm that card setup completed for this account.               |
| `POST` | `/v1/billing/top-ups`                 | Purchase `$5.00`–`$500.00` of prepaid funds.                      |
| `GET`  | `/v1/billing/top-ups/:purchaseId`     | Poll one top-up owned by the caller.                              |
| `GET`  | `/v1/billing/auto-top-up`             | Read the automatic top-up policy.                                 |
| `PUT`  | `/v1/billing/auto-top-up`             | Enable, disable, or update automatic top-up.                      |

Top-ups and automatic-top-up changes require an `Idempotency-Key` header.
Top-up presets are `$5`, `$25`, `$100`, and `$500`; custom amounts from `$5.00`
through `$500.00` are accepted. Automatic top-up is opt-in and defaults to
recharging the balance to `$25.00` when it reaches `$5.00`.

A top-up may return `202` while payment is pending. Poll its returned URL until
the status is `paid`, `failed`, or `action_required`. Funds are not spendable
until payment succeeds.

Auth: Droyd API key or signed-in user bearer token. Every path also accepts the
`/api/v1` compatibility prefix. The caller cannot supply a user or customer ID.
Mutation endpoints return `503 billing_mutations_disabled` while account
funding is unavailable in the target environment.

`Idempotency-Key` must be 8–120 URL-safe characters. `amount_usd`,
`threshold_usd`, and `recharge_to_usd` must be decimal strings with no more than
two fractional digits. One-time top-ups must be `$5.00`–`$500.00`. Enabled
automatic top-up requires a saved payment method, a threshold of at least
`$5.00`, and a recharge target at least `$10.00` above the threshold.

Card setup is a two-step Stripe SetupIntent flow. Pass the first response's
`client_secret` only to Stripe's client SDK; do not log or persist it. After
Stripe reports success, send its `setup_intent_id` to the completion endpoint.
The automatic-top-up read response may include the saved card's brand, last
four digits, expiration, and non-sensitive billing details so account UIs can
show what is configured. Full card data is never returned.

The balance is authoritative and may return `404 billing_account_not_found`
before account provisioning. Billing or database dependency failures return a
sanitized `503 billing_unavailable`; credentials, raw billing responses, and
internal billing identifiers are not exposed.


## OpenAPI

````yaml api-key.openapi.json GET /v1/billing/balance
openapi: 3.1.0
info:
  title: Droyd API-key Automation API
  version: 1.0.0
  description: >-
    The production API contract for Droyd API-key automations. It contains only
    operations that accept a Droyd API key. `/v1` is canonical; `/api/v1` is a
    compatibility alias.
servers: []
security:
  - droydApiKeyBearer: []
  - droydApiKeyHeader: []
tags:
  - name: Identity
    description: Account-scoped automation identity and onboarding state.
  - name: Workflows
    description: Caller-owned workflows and research nodes.
  - name: Competitions
    description: Competition readiness, submissions, and race entries.
  - name: Experiments
    description: Experiments, artifacts, agent versions, and evaluations.
  - name: Usage
    description: Caller-owned evaluation usage.
  - name: Billing
    description: Caller-owned prepaid credit balances and funding.
paths:
  /v1/billing/balance:
    get:
      tags:
        - Billing
      summary: Return the caller's spendable credit balance.
      operationId: getBillingBalance
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServerError'
components:
  responses:
    Success:
      description: Successful response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessEnvelope'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Forbidden:
      description: Account state or route policy prevents the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: The resource is missing or not owned by the API-key account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    ServerError:
      description: >-
        The request could not be completed. Retry only when the operation's
        idempotency contract permits it.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  schemas:
    SuccessEnvelope:
      type: object
      required:
        - ok
      properties:
        ok:
          const: true
      additionalProperties: true
    ErrorEnvelope:
      type: object
      required:
        - ok
        - error
      properties:
        ok:
          const: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
  securitySchemes:
    droydApiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: Droyd API key
      description: A Droyd API key in the Authorization Bearer slot.
    droydApiKeyHeader:
      type: apiKey
      in: header
      name: x-droyd-api-key
      description: A Droyd API key when Authorization is absent.

````