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 'SIGN-IN-WITH-X: <api-key>'
import requests

url = "https://api.venice.ai/api/v1/x402/balance/{walletAddress}"

headers = {"SIGN-IN-WITH-X": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {'SIGN-IN-WITH-X': '<api-key>'}};

fetch('https://api.venice.ai/api/v1/x402/balance/{walletAddress}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.venice.ai/api/v1/x402/balance/{walletAddress}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "SIGN-IN-WITH-X: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.venice.ai/api/v1/x402/balance/{walletAddress}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("SIGN-IN-WITH-X", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.venice.ai/api/v1/x402/balance/{walletAddress}")
  .header("SIGN-IN-WITH-X", "<api-key>")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.venice.ai/api/v1/x402/balance/{walletAddress}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["SIGN-IN-WITH-X"] = '<api-key>'

response = http.request(request)
puts response.read_body
{
  "success": true,
  "data": {
    "walletAddress": "0xyour_wallet_address",
    "balanceUsd": 12.5,
    "canConsume": true,
    "minimumTopUpUsd": 5,
    "suggestedTopUpUsd": 10,
    "diemBalanceUsd": 5.25
  }
}
{
  "error": "<string>",
  "details": {
    "_errors": [],
    "field": {
      "_errors": [
        "Field is required"
      ]
    }
  }
}
{
  "error": "<string>"
}
{
  "error": "<string>"
}
{
  "error": "<string>"
}
{
  "error": "<string>"
}

Authorizations

​
SIGN-IN-WITH-X
string
header
required

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.

Headers

​
SIGN-IN-WITH-X
string
required

base64-encoded JSON SIWX payload proving EVM or Solana wallet ownership. The legacy X-Sign-In-With-X header is also accepted during migration.

Example:

"siwx_example_token"

Path Parameters

​
walletAddress
string
required

EVM or Solana wallet address.

Pattern: ^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$
Example:

"0xYOUR_WALLET_ADDRESS"

Response

Current x402 balance for the wallet.

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