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

# Topup Key

> Top up a key's prepaid balance via x402 USDC payment.

The x402 middleware prices this path at {usd} dollars and verifies payment
before this handler runs; the amount paid is credited 1:1. Each priced call
is then debited at the price in the pricing table.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/keys/topup/{usd}
openapi: 3.1.0
info:
  title: Limitguard.ai
  description: >-
    Lead validation API: the company behind each lead checked against the NL and
    BE business registers, EU VAT and sanctions lists, plus company, KYB and
    agent wallet checks for developers and AI agents
  version: 0.1.0
servers:
  - url: https://api.limitguard.ai
security: []
paths:
  /v1/keys/topup/{usd}:
    post:
      summary: Topup Key
      description: >-
        Top up a key's prepaid balance via x402 USDC payment.


        The x402 middleware prices this path at {usd} dollars and verifies
        payment

        before this handler runs; the amount paid is credited 1:1. Each priced
        call

        is then debited at the price in the pricing table.
      operationId: topup_key_v1_keys_topup__usd__post
      parameters:
        - name: usd
          in: path
          required: true
          schema:
            type: integer
            minimum: 5
            description: Whole US dollars to add to the prepaid balance
            title: Usd
          description: Whole US dollars to add to the prepaid balance
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyTopupResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    KeyTopupResponse:
      properties:
        key_id:
          type: string
          title: Key Id
          description: Key identifier (SHA-256 hash prefix)
        tier:
          type: string
          title: Tier
          description: Tier label (unchanged by a top-up)
        credited_usd:
          type: number
          title: Credited Usd
          description: USD credited to the prepaid balance by this payment (1:1)
        balance_usd:
          type: number
          title: Balance Usd
          description: Prepaid balance after this credit
      type: object
      required:
        - key_id
        - tier
        - credited_usd
        - balance_usd
      title: KeyTopupResponse
      description: Response after topping up a key's prepaid balance via x402.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.