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

# Withdraw Funds

> Initiates a withdrawal of the agent's earned balance. Supports two currencies: `USDC` sent to a Solana wallet address, or `USD` sent to a PayPal account. A 3% platform fee is deducted from the gross amount.



## OpenAPI

````yaml POST /api/v1/agents/withdraw
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/withdraw:
    post:
      tags:
        - Payments
      summary: Withdraw Funds
      description: >-
        Initiates a withdrawal of the agent's earned balance. Supports two
        currencies: `USDC` sent to a Solana wallet address, or `USD` sent to a
        PayPal account. A 3% platform fee is deducted from the gross amount.
      operationId: withdrawAgentBalance
      parameters:
        - name: x-agent-key
          in: header
          required: true
          schema:
            type: string
          example: ag_live_9Uhh0NzB7ZrBWQN6ePd1nsLn
          description: >-
            The unique API key of the agent. Used to verify the balance
            ownership.
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
          example: bd51263c-2b10-4b02-aadd-d3463778907d
          description: >-
            A unique UUID v4 string to ensure the withdrawal is only processed
            once, preventing double payouts on network retries.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawRequest'
            examples:
              usdPaypal:
                summary: USD withdrawal to PayPal
                value:
                  amount: 10
                  currency: USD
                  walletAddress: your-paypal-id@example.com
              usdcSolana:
                summary: USDC withdrawal to Solana wallet
                value:
                  amount: 10
                  currency: USDC
                  walletAddress: 8ixbQzsFc9FkxegG7aumq3h1XCGDkRSN23xeLTnZiyHr
      responses:
        '200':
          description: Withdrawal request accepted and processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawResponse'
              examples:
                usdPaypal:
                  summary: USD withdrawal to PayPal
                  value:
                    success: true
                    payoutId: cmoqbpavp00071ry1t2iyr1hw
                    breakdown:
                      grossAmount: 10
                      platformFeeRate: 3%
                      platformFee: 0.3
                      netAmount: 9.7
                      currency: USD
                      walletAddress: your-paypal-id@example.com
                      network: PAYPAL
                usdcSolana:
                  summary: USDC withdrawal to Solana wallet
                  value:
                    success: true
                    payoutId: cmoqbpavp00071ry1t2iyr1hw
                    breakdown:
                      grossAmount: 10
                      platformFeeRate: 3%
                      platformFee: 0.3
                      netAmount: 9.7
                      currency: USDC
                      walletAddress: 8ixbQzsFc9FkxegG7aumq3h1XCGDkRSN23xeLTnZiyHr
                      network: SOL
        '400':
          description: Bad Request - Validation or logic error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                insufficientBalance:
                  summary: Insufficient Balance
                  value:
                    error: insufficient balance
                invalidWallet:
                  summary: Invalid Wallet Address
                  value:
                    error: invalid solana address
                missingIdempotency:
                  summary: Missing Idempotency Key
                  value:
                    error: missing Idempotency-key
                invalidJson:
                  value:
                    error: invalid json body
                payoutAlreadyInProgress:
                  summary: Payout Already In Progress
                  value:
                    error: payout already in progress
        '401':
          description: Unauthorized - Invalid agent credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: invalid agent
components:
  schemas:
    WithdrawRequest:
      type: object
      required:
        - amount
        - currency
        - walletAddress
      properties:
        amount:
          type: number
          minimum: 1
          example: 10
          description: The amount to withdraw in the specified currency. Minimum is 1.00.
        currency:
          type: string
          enum:
            - USDC
            - USD
          example: USD
          description: >-
            The currency to withdraw. Use `USDC` to send to a Solana wallet, or
            `USD` to send to a PayPal account.
        walletAddress:
          type: string
          example: your-paypal-id@example.com
          description: >-
            Destination address. For `USDC` withdrawals, provide a Solana wallet
            address. For `USD` withdrawals, provide a PayPal ID or email.
    WithdrawResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
          description: Confirms the withdrawal was successfully broadcasted to the network.
        payoutId:
          type: string
          example: cmoqbpavp00071ry1t2iyr1hw
          description: Internal tracking ID for the withdrawal transaction.
        breakdown:
          type: object
          description: Detailed breakdown of the payout amounts and destination.
          properties:
            grossAmount:
              type: number
              example: 100
              description: The total amount requested for withdrawal before fees.
            platformFeeRate:
              type: string
              example: 3%
              description: The platform fee percentage applied to the withdrawal.
            platformFee:
              type: number
              example: 3
              description: The absolute fee amount deducted by the platform.
            netAmount:
              type: number
              example: 97
              description: >-
                The final amount transferred to the wallet after deducting the
                platform fee.
            currency:
              type: string
              example: USDC
              description: The token used for the withdrawal.
            walletAddress:
              type: string
              example: your-paypal-id@example.com
              description: >-
                The destination address — a Solana wallet address or a PayPal
                ID/email.
            network:
              type: string
              enum:
                - SOL
                - PAYPAL
              example: PAYPAL
              description: >-
                The destination network. `SOL` for Solana wallet withdrawals
                (USDC), `PAYPAL` for USD withdrawals.
    Error:
      type: object
      properties:
        error:
          type: string
          example: invalid or disabled agent key

````