Skip to main content
GET
/
x402
/
balance
/
{walletAddress}
/api/v1/x402/balance/{walletAddress}
curl --request GET \
  --url https://api.venice.ai/api/v1/x402/balance/{walletAddress} \
  --header 'X-Sign-In-With-X: <api-key>'
{
  "success": true,
  "data": {
    "walletAddress": "0xyour_wallet_address",
    "balanceUsd": 12.5,
    "canConsume": true,
    "minimumTopUpUsd": 5,
    "suggestedTopUpUsd": 10,
    "diemBalanceUsd": 5.25
  }
}

Authorizations

​
X-Sign-In-With-X
string
header
required

Wallet-based authentication using the x402 protocol (Sign-In-With-X / EIP-4361 SIWE).

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

  • address — Ethereum wallet address (checksummed)
  • message — EIP-4361 SIWE message string (created with SiweMessage.prepareMessage())
  • signature — Hex-encoded signature of the message, signed by the wallet's private key
  • timestamp — Unix timestamp in milliseconds
  • chainId — Chain ID (use 8453 for Base)

SIWE message fields:

  • domain: outerface.venice.ai
  • uri: https://outerface.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: 'outerface.venice.ai', address: wallet.address, statement: 'Sign in to Venice API', uri: 'https://outerface.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: X-Sign-In-With-X: <header>

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.

Headers

​
X-Sign-In-With-X
string
required

base64-encoded JSON SIWE payload message proving wallet ownership

Example:

"siwx_example_token"

Path Parameters

​
walletAddress
string
required

Ethereum wallet address.

Pattern: ^0x[a-fA-F0-9]{40}$
Example:

"0xYOUR_WALLET_ADDRESS"

Response

Current x402 balance for the wallet.

​
success
enum<boolean>
required
Available options:
true
​
data
object
required