X402 Balance | Venice API Docs

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>'

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))

}

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
  }
}

{
  "error": "<string>",
  "details": {
    "_errors": [],
    "field": {
      "_errors": [
        "Field is required"
      ]
    }
  }
}

{
  "error": "This nonce has already been used",
  "code": "X402_SIGN_IN_NONCE_REUSED",
  "invalidReason": "invalid_siwx_nonce"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

Authorizations

Wallet-based authentication using the x402 sign-in-with-x extension. Supports EVM wallets on Base (EIP-4361 SIWE, including EIP-1271 smart contract wallets) and Ed25519 wallets on Solana mainnet.

Header format: Base64-encoded JSON proof with these fields:

domain — api.venice.ai
address — EVM or Solana wallet address
uri — URL of the requested resource
version — "1"
chainId — "eip155:8453" for Base or "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" for Solana
type — "eip191" for EVM wallets or "ed25519" for Solana
nonce — the nonce from the latest 402 challenge (extensions["sign-in-with-x"].info.nonce), or 32 random hex characters. Each nonce works once.
issuedAt — ISO 8601 time the proof was signed. Proofs older than 5 minutes are rejected.
expirationTime, notBefore, statement, resources — optional
signature — signature over the message built from these fields: an EIP-4361 SIWE message for EVM (hex) or the Solana sign-in message (base58)

Venice rebuilds the signed message from these fields, with the bare reference on its Chain ID line (8453, 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp). Proofs from older clients that send the signed message itself are still accepted.

Example (TypeScript, viem):

import { privateKeyToAccount } from 'viem/accounts'
import { createSiweMessage } from 'viem/siwe'

const account = privateKeyToAccount(PRIVATE_KEY)
const fields = { domain: 'api.venice.ai', address: account.address, uri: 'https://api.venice.ai/api/v1/chat/completions', version: '1' as const, nonce: crypto.randomUUID().replace(/-/g, ''), issuedAt: new Date().toISOString(), statement: 'Sign in to Venice AI' }
const message = createSiweMessage({ ...fields, chainId: 8453, issuedAt: new Date(fields.issuedAt) })
const signature = await account.signMessage({ message })
const header = btoa(JSON.stringify({ ...fields, chainId: 'eip155:8453', type: 'eip191', signature }))
// Set header: SIGN-IN-WITH-X: <header>

SDK: npm install venice-x402-client provides VeniceClient and createAuthFetch which handle this automatically.

Billing: x402 users pay from a prepaid x402 credit balance. Top up via POST /x402/top-up. When balance is insufficient, endpoints return 402 with structured top-up instructions.

Headers

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

Show child attributes

⌘I

/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>'

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))

}

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
  }
}

{
  "error": "<string>",
  "details": {
    "_errors": [],
    "field": {
      "_errors": [
        "Field is required"
      ]
    }
  }
}

{
  "error": "This nonce has already been used",
  "code": "X402_SIGN_IN_NONCE_REUSED",
  "invalidReason": "invalid_siwx_nonce"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}