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

# Create Charge

> Debits a specified amount from a user's balance. This action requires authorization from the user via their unique key.



## OpenAPI

````yaml POST /api/v1/agents/charges
openapi: 3.1.0
info:
  title: Pulsarpay API
  description: >-
    Pulsarpay is an automated payment infrastructure designed specifically for
    APIs and autonomous agents. It allows users to top up credits while agents
    execute charges for their services.
  version: 1.0.0
servers:
  - url: https://pulsarpay.io
    description: Production Server
security: []
paths:
  /api/v1/agents/charges:
    post:
      tags:
        - Payments
      summary: Create a Charge
      description: >-
        Debits a specified amount from a user's balance. This action requires
        authorization from the user via their unique key.
      operationId: createCharge
      parameters:
        - name: x-user-key
          in: header
          required: true
          schema:
            type: string
          example: >-
            Bearer
            pp_live_7698774c6d197b4b753c32536a8340f9fe6e881b961db37684f1447f246601fa
          description: >-
            The user's authorization token. This allows the agent to execute
            charges against the user's credits.
        - name: x-agent-key
          in: header
          required: true
          schema:
            type: string
          example: ag_live_9Uhh0NzB7ZrBWQN6ePd1nsLn
          description: The unique API key of the agent executing the charge.
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
          example: f77af2f2-7a83-4b60-88e1-2808a4d08779
          description: >-
            A unique, client-generated string to prevent duplicate charges in
            case of network retries. Recommended to use UUID v4.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeRequest'
      responses:
        '200':
          description: Charge processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeResponse'
        '400':
          description: Bad Request - Logic or Configuration Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCharge4XX'
              examples:
                currencyMismatch:
                  summary: Currency Mismatch
                  value:
                    error: currency mismatch
                balanceNotFound:
                  summary: Balance Not Found
                  value:
                    error: insufficient funds
        '402':
          description: Payment Required - Insufficient Funds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                insufficientFunds:
                  summary: Insufficient Funds
                  value:
                    error: insufficient funds
components:
  schemas:
    ChargeRequest:
      type: object
      required:
        - amount
        - currency
        - description
      properties:
        amount:
          type: number
          format: float
          example: 0.1
          description: >-
            The amount to be charged to the user's balance. Represented in
            decimal units of the specified currency (e.g., 1.50 for $1.50 USD or
            1.50 USDC).
        currency:
          type: string
          enum:
            - USDC
            - USD
          example: USDC
          description: >-
            The currency for the charge. Each currency has an independent
            balance — the user must have sufficient funds in the specified
            currency. Use `USDC` for Solana-based payments or `USD` for fiat.
        description:
          type: string
          maxLength: 255
          example: AI Model Inference - 500 tokens
          description: >-
            A brief description of the service or product provided. This will be
            visible to the user in their transaction history.
    ChargeResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        chargeId:
          type: string
          example: cmnnfoagf0003jk04suqxf3k9
        reused:
          type: boolean
          example: true
    ErrorCharge4XX:
      type: object
      properties:
        error:
          type: string
          example: insufficient funds
    Error:
      type: object
      properties:
        error:
          type: string
          example: invalid or disabled agent key

````