> ## 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 (#434).

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: Trust Intelligence API - Entity verification and risk scoring
  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 (#434).


        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
      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
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````