> ## 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.

# Upgrade Key

> Buy prepaid balance via x402 USDC payment.

The x402 price is credited 1:1 to the key's prepaid balance and the tier
label is set to the higher of the current and purchased tier (the label
selects burst limits in rate_limit.py; it never downgrades). Repeat
purchases are allowed. Each priced call is then debited at the price in
the pricing table.

The x402 middleware handles payment verification before this handler runs.
Send X-API-Key header to identify which key to credit.

Ladder prices: indie $29, starter $99, growth $299, pro $999.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/keys/upgrade/{tier}
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/upgrade/{tier}:
    post:
      summary: Upgrade Key
      description: >-
        Buy prepaid balance via x402 USDC payment.


        The x402 price is credited 1:1 to the key's prepaid balance and the tier

        label is set to the higher of the current and purchased tier (the label

        selects burst limits in rate_limit.py; it never downgrades). Repeat

        purchases are allowed. Each priced call is then debited at the price in

        the pricing table.


        The x402 middleware handles payment verification before this handler
        runs.

        Send X-API-Key header to identify which key to credit.


        Ladder prices: indie $29, starter $99, growth $299, pro $999.
      operationId: upgrade_key_v1_keys_upgrade__tier__post
      parameters:
        - name: tier
          in: path
          required: true
          schema:
            type: string
            title: Tier
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyUpgradeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    KeyUpgradeResponse:
      properties:
        key_id:
          type: string
          title: Key Id
          description: Key identifier (SHA-256 hash prefix)
        previous_tier:
          type: string
          title: Previous Tier
          description: Tier label before this purchase
        new_tier:
          type: string
          title: New Tier
          description: Tier label after this purchase (never lower than before)
        monthly_limit:
          type: integer
          title: Monthly Limit
          description: >-
            Monthly request ceiling for the tier label (an abuse cap, not
            prepaid calls)
        payment_amount_usdc:
          type: number
          title: Payment Amount Usdc
          description: Amount paid in USDC
        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
        tier_expires_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Tier Expires At
          description: >-
            When the active Growth/Pro term ends (null without a term). The key
            then moves to the first queued term, or back to the tier it had
            before
        queued_terms:
          items:
            $ref: '#/components/schemas/QueuedTerm'
          type: array
          title: Queued Terms
          description: >-
            Terms bought during a higher active term (Growth during Pro), oldest
            first; each starts when the one ahead of it ends
      type: object
      required:
        - key_id
        - previous_tier
        - new_tier
        - monthly_limit
        - payment_amount_usdc
        - credited_usd
        - balance_usd
      title: KeyUpgradeResponse
      description: >-
        Response after buying prepaid balance via x402 on POST
        /v1/keys/upgrade/{tier}.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    QueuedTerm:
      properties:
        tier:
          type: string
          title: Tier
          description: Tier the key moves to when this term starts
        starts_at:
          type: string
          format: date-time
          title: Starts At
          description: When this term starts (the term ahead of it ends)
      type: object
      required:
        - tier
        - starts_at
      title: QueuedTerm
      description: A lower-tier term bought during a higher active term, waiting its turn.
    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.