> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-d2fddb8a.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# X402 Balance

> Get the x402 credit balance for a wallet address. Requires Sign-in-with-x authentication for the same EVM or Solana wallet.



## OpenAPI

````yaml GET /x402/balance/{walletAddress}
openapi: 3.0.0
info:
  description: The Venice.ai API.
  termsOfService: https://venice.ai/legal/tos
  title: Venice.ai API
  version: '20260622.204854'
  x-guidance: >-
    Venice.ai is an OpenAI-compatible inference API supporting text, image,
    audio, and video generation.


    **Authentication options:**

    - API Key: Use Bearer token in Authorization header

    - x402 Wallet: Use USDC credits via EVM or Solana wallet (no account
    required)


    **For x402 wallet access:**

    1. POST /x402/top-up without headers to get payment requirements

    2. Choose one of the returned Base or Solana payment options and sign a USDC
    payment using the x402 SDK

    3. POST /x402/top-up with PAYMENT-SIGNATURE header to add credits

    4. Call any inference endpoint with SIGN-IN-WITH-X header


    **Pricing:** Prepaid credits consumed per request. Check /models for
    available models and their capabilities.
servers:
  - url: https://api.venice.ai/api/v1
security:
  - BearerAuth: []
tags:
  - description: >-
      Generate speech/audio, transcribe audio, and manage asynchronous audio
      generation jobs.
    name: Audio
  - description: >-
      Given a list of messages comprising a conversation, the model will return
      a response. Supports multimodal inputs including text, images, audio
      (input_audio), and video (video_url) for compatible models.
    name: Chat
  - description: List and describe the various models available in the API.
    name: Models
  - description: Generate and manipulate images using AI models.
    name: Image
  - description: Generate videos using AI models.
    name: Video
  - description: List and retrieve character information for use in completions.
    name: Characters
  - description: >-
      Billing and usage analytics. **Beta**: This API is currently in beta and
      may be unstable. Endpoints, request/response schemas, and behavior may
      change without notice.
    name: Billing
  - description: Proxy JSON-RPC requests to blockchain nodes. Billed per credit.
    name: Crypto RPC
  - description: >-
      Wallet-based API access using the x402 protocol. No API key required —
      authenticate with an EVM or Solana wallet.


      **How it works:**

      1. **Authenticate** — Send a `SIGN-IN-WITH-X` header (base64-encoded
      signed SIWX payload) with any request. EVM wallets sign an EIP-4361 SIWE
      message; Solana wallets sign the Solana SIWX message with Ed25519. See the
      `siwx` security scheme for the exact format.

      2. **Top up** — `POST /x402/top-up` without a payment header returns an
      `accepts` array with Base and Solana USDC payment options. Choose one
      entry, sign it using the x402 SDK (`npm install x402`), and re-submit with
      the `PAYMENT-SIGNATURE` header (the legacy `X-402-Payment` and `X-PAYMENT`
      names are also accepted).

      3. **Use any endpoint** — All inference endpoints (chat, image, audio,
      video, embeddings) accept `siwx` as an alternative to `BearerAuth`.
      Charges are deducted from your USDC credit balance.

      4. **Monitor balance** — `GET /x402/balance/{walletAddress}` returns your
      current balance. The `X-Balance-Remaining` response header on inference
      calls also reports it.


      **Quick start (5 lines):**

      ```

      import { VeniceClient } from '@venice-ai/x402-client'

      const venice = new VeniceClient(process.env.WALLET_KEY)

      await venice.topUp(10) // $10 USDC on a supported x402 rail

      const res = await venice.chat({ model: 'zai-org-glm-5-1', messages: [{
      role: 'user', content: 'Hello!' }] })

      ```


      **Payment:** USDC on Base (chain ID 8453) or Solana mainnet. Minimum
      top-up: $5. Alternatively, stake DIEM tokens for daily credits (1 DIEM =
      $1/day).
    name: x402
externalDocs:
  description: Venice.ai API documentation
  url: https://docs.venice.ai
paths:
  /x402/balance/{walletAddress}:
    get:
      tags:
        - x402
      summary: /api/v1/x402/balance/{walletAddress}
      description: >-
        Get the x402 credit balance for a wallet address. Requires
        Sign-in-with-x authentication for the same EVM or Solana wallet.
      operationId: getX402Balance
      parameters:
        - description: >-
            base64-encoded JSON SIWX payload proving EVM or Solana wallet
            ownership. The legacy `X-Sign-In-With-X` header is also accepted
            during migration.
          in: header
          name: SIGN-IN-WITH-X
          required: true
          schema:
            example: siwx_example_token
            type: string
        - schema:
            type: string
            pattern: ^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$
            description: EVM or Solana wallet address.
            example: 0xYOUR_WALLET_ADDRESS
          required: true
          name: walletAddress
          in: path
      responses:
        '200':
          description: Current x402 balance for the wallet.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      walletAddress:
                        type: string
                        description: Normalized wallet address.
                        example: 0xyour_wallet_address
                      balanceUsd:
                        type: number
                        description: Current x402 credit balance in USD.
                        example: 12.5
                      canConsume:
                        type: boolean
                        description: >-
                          Whether the wallet can currently consume paid
                          x402-backed endpoints.
                        example: true
                      minimumTopUpUsd:
                        type: number
                        description: Minimum allowed top-up amount in USD.
                        example: 5
                      suggestedTopUpUsd:
                        type: number
                        description: Suggested top-up amount in USD.
                        example: 10
                      diemBalanceUsd:
                        type: number
                        description: >-
                          Optional DIEM balance available for a linked Venice
                          user.
                        example: 5.25
                    required:
                      - walletAddress
                      - balanceUsd
                      - canConsume
                      - minimumTopUpUsd
                      - suggestedTopUpUsd
                    additionalProperties: false
                required:
                  - success
                  - data
                additionalProperties: false
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailedError'
        '401':
          description: Missing or invalid Sign-in-with-x authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardError'
        '403':
          description: Authenticated wallet does not match the requested wallet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardError'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardError'
        '500':
          description: An unknown error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardError'
      security:
        - siwx: []
components:
  schemas:
    DetailedError:
      type: object
      properties:
        details:
          type: object
          properties: {}
          description: Details about the incorrect input
          example:
            _errors: []
            field:
              _errors:
                - Field is required
        error:
          type: string
          description: A description of the error
      required:
        - error
    StandardError:
      type: object
      properties:
        error:
          type: string
          description: A description of the error
      required:
        - error
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
    siwx:
      description: >-
        Wallet-based authentication using the x402 protocol (Sign-In-With-X).
        Supports EVM SIWE signatures on Base and Ed25519 signatures on Solana
        mainnet.


        **Header format:** Base64-encoded JSON object with the following fields:

        - `address` — EVM or Solana wallet address

        - `message` — Signed SIWX message. EVM wallets use EIP-4361 SIWE; Solana
        wallets use the Solana SIWX message format.

        - `signature` — Signature of the message, signed by the wallet's private
        key. EVM signatures are hex; Solana signatures may be base58 or base64.

        - `timestamp` — Unix timestamp in milliseconds

        - `chainId` — Chain identity. Use `8453`, `"8453"`, or `"eip155:8453"`
        for Base; use `"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"` for Solana.

        - `type` — Optional signature type. Use `"ed25519"` for Solana. Omitted
        means EVM/EIP-191 for backward compatibility.


        **EVM SIWE message fields:**

        - `domain`: `api.venice.ai`

        - `uri`: `https://api.venice.ai`

        - `version`: `"1"`

        - `chainId`: `8453`

        - `nonce`: Random 16-character hex string

        - `issuedAt` / `expirationTime`: ISO timestamps (recommended TTL: 10
        minutes)

        - `statement`: `"Sign in to Venice API"`


        **Example (TypeScript):**

        ```

        import { Wallet } from 'ethers'

        import { SiweMessage } from 'siwe'


        const wallet = new Wallet(PRIVATE_KEY)

        const msg = new SiweMessage({ domain: 'api.venice.ai', address:
        wallet.address, statement: 'Sign in to Venice API', uri:
        'https://api.venice.ai', version: '1', chainId: 8453, nonce:
        crypto.randomUUID().replace(/-/g, '').slice(0, 16), issuedAt: new
        Date().toISOString(), expirationTime: new Date(Date.now() +
        600000).toISOString() })

        const signature = await wallet.signMessage(msg.prepareMessage())

        const header = btoa(JSON.stringify({ address: wallet.address, message:
        msg.prepareMessage(), signature, timestamp: Date.now(), chainId: 8453
        }))

        // Set header: SIGN-IN-WITH-X: <header>

        ```


        **Solana message fields:** The signed message starts with `<domain>
        wants you to sign in with your Solana account:`, followed by the wallet
        address and the standard `URI`, `Version`, `Chain ID`, `Nonce`, `Issued
        At`, and optional `Expiration Time` fields. Use `type: "ed25519"` and
        `chainId: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"` in the encoded JSON
        payload.


        **SDK:** `npm install @venice-ai/x402-client` provides `VeniceClient`
        and `createAuthFetch` which handle this automatically.


        **Billing:** x402 users pay from a prepaid USDC credit balance. Top up
        via `POST /x402/top-up`. When balance is insufficient, endpoints return
        `402` with structured top-up instructions.
      in: header
      name: SIGN-IN-WITH-X
      type: apiKey

````