X402

X402 lets you use Venice’s paid API routes by authenticating with a wallet and maintaining a prepaid USDC balance. No API key or account required. Sign a message, top up on Base or Solana, and call any supported route.

Wallet Auth

Authenticate with a signed Sign-In-With-X payload in the X-Sign-In-With-X header.

Pay with USDC

Maintain spendable balance with USDC on Base or Solana.

DIEM First

If the wallet is linked to a Venice account with DIEM balance, that is spent first.

What is X402?

X402 is an open payment standard that lets applications and agents pay for services programmatically using cryptocurrency. Venice implements X402 so that wallets can authenticate and pay for inference directly with USDC on Base or Solana.

Prerequisites

A wallet on Base or Solana
Native token for gas on the selected chain, such as ETH on Base or SOL on Solana
USDC on the selected chain (or existing DIEM-backed balance from a linked Venice account)

Consider using a dedicated wallet for automation rather than your main treasury wallet.

Quick start

The venice-x402-client SDK provides helpers for wallet auth, top-ups, and balance tracking.

npm install venice-x402-client

import { VeniceClient } from 'venice-x402-client'

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

await venice.topUp(10) // skip if the wallet already has spendable balance

const response = await venice.chat({
  model: 'kimi-k2-5',
  messages: [{ role: 'user', content: 'Hello!' }]
})

The client generates a fresh X-Sign-In-With-X header for each request and automatically tracks balance from X-Balance-Remaining response headers.

With OpenAI-compatible tools

If you’re using a tool that accepts a custom fetch, use createAuthFetch to add wallet auth to any request:

import { createAuthFetch } from 'venice-x402-client'

const authFetch = createAuthFetch(process.env.WALLET_KEY)

Available helpers

The SDK includes first-class helpers for the most common Venice x402 routes. For anything not covered, use request() or createAuthFetch() directly.

Category	Methods
Chat	`chat()`, `chatStream()`
Responses	`responses.create()`, `responses.stream()`
Images	`images.generate()`, `images.generations()`, `images.upscale()`, `images.edit()`, `images.multiEdit()`, `images.backgroundRemove()`
Audio	`audio.speech()`, `audio.transcribe()`, `audio.queue()`, `audio.retrieve()`, `audio.complete()`
Video	`video.queue()`, `video.retrieve()`, `video.generate()`, `video.complete()`, `video.transcribe()`
Embeddings	`embeddings()`
Models	`models()`
Wallet	`getBalance()`, `getTransactions()`, `topUp()`

Manual flow

If you’re not using the SDK or need to understand the underlying protocol, here’s the step-by-step flow. For a new wallet, assume you need to top up first unless it already has spendable DIEM balance. Venice expects a Base64-encoded JSON payload containing a signed Sign-In-With-X message. EVM wallets sign an EIP-4361 SIWE message on Base. Solana wallets sign the Solana SIWX message with Ed25519. Generate a fresh nonce and timestamp for each request flow. For Solana, set chainId to solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp, include type: "ed25519" in the encoded JSON payload, and provide the Ed25519 signature as base58 or base64. 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.

import { Wallet } from 'ethers'
import { SiweMessage, generateNonce } from 'siwe'

const wallet = new Wallet(process.env.EVM_PRIVATE_KEY)
const now = new Date()
const resourceUrl = 'https://api.venice.ai/api/v1/chat/completions'

const siwe = new SiweMessage({
  domain: 'api.venice.ai',
  address: wallet.address,
  statement: 'Sign in to Venice AI',
  uri: resourceUrl,
  version: '1',
  chainId: 8453,
  nonce: generateNonce(),
  issuedAt: now.toISOString(),
  expirationTime: new Date(now.getTime() + 5 * 60 * 1000).toISOString(),
})

const message = siwe.prepareMessage()
const signature = await wallet.signMessage(message)

const xSignInWithX = Buffer.from(
  JSON.stringify({
    address: wallet.address,
    message,
    signature,
    timestamp: now.getTime(),
    chainId: 8453,
  }),
  'utf8',
).toString('base64')

console.log(xSignInWithX)

Step 2: Check balance

Before making a paid request, verify the wallet has spendable balance:

export WALLET_ADDRESS=0xYOUR_WALLET_ADDRESS_OR_SOLANA_ADDRESS
export X402_AUTH=YOUR_BASE64_SIWX_HEADER

curl --request GET \
  --url "https://api.venice.ai/api/v1/x402/balance/$WALLET_ADDRESS" \
  --header "X-Sign-In-With-X: $X402_AUTH"

The response includes:

canConsume: whether the wallet can make paid requests
balanceUsd: current spendable balance
minimumTopUpUsd and suggestedTopUpUsd: guidance for top-ups
diemBalanceUsd: DIEM-backed balance, if any

The walletAddress path parameter accepts either an EVM address (0x...) or a Solana base58 address.

Step 3: Top up

Top up with USDC on Base or Solana:

curl --request POST \
  --url https://api.venice.ai/api/v1/x402/top-up

The first call returns 402 Payment Required with a PAYMENT-REQUIRED header containing an accepts array. Each entry describes one accepted payment option, including network, asset, payTo, and amount. Choose the Base or Solana option you want to pay with, use those exact details to build an X-402-Payment header, and retry the same route.

Building the X-402-Payment header for Base

The following script creates a signed x402 payment on Base and sends the top-up request. Requires the x402 and viem npm packages.

export EVM_PRIVATE_KEY=0xYOUR_PRIVATE_KEY

export X402_PAYMENT="$(
node --input-type=module <<'EOF'
import { createPaymentHeader } from "x402/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY);
const amountUsd = 5;
const amountBaseUnits = String(Math.round(amountUsd * 1e6));

const header = await createPaymentHeader(signer, 2, {
  scheme: "exact",
  network: "base",
  maxAmountRequired: amountBaseUnits,
  resource: "https://api.venice.ai/api/v1/x402/top-up",
  description: "Venice x402 top-up",
  mimeType: "application/json",
  payTo: "0x2670B922ef37C7Df47158725C0CC407b5382293F",
  maxTimeoutSeconds: 300,
  asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  extra: { name: "USD Coin", version: "2" },
});

process.stdout.write(header);
EOF
)"

curl -X POST "https://api.venice.ai/api/v1/x402/top-up" \
  -H "X-402-Payment: $X402_PAYMENT"

Use the latest PAYMENT-REQUIRED / accepts response as the source of truth in production instead of hardcoding these values. For Solana top-ups, build the payment from the Solana entry returned in accepts. Solana entries use network: "solana", the USDC mint as asset, and may include network-specific metadata such as extra.feePayer.

Step 4: Make a request

Once the wallet has spendable balance, call any supported endpoint with the X-Sign-In-With-X header:

export X402_AUTH=YOUR_BASE64_SIWX_HEADER

curl --request POST \
  --url https://api.venice.ai/api/v1/chat/completions \
  --header "Content-Type: application/json" \
  --header "X-Sign-In-With-X: $X402_AUTH" \
  --data '{
    "model": "kimi-k2-5",
    "messages": [
      {
        "role": "user",
        "content": "Hello from an x402-authenticated wallet."
      }
    ]
  }'

Successful responses may include an X-Balance-Remaining header.

Step 5: Inspect transactions (optional)

Review the wallet’s transaction history:

export WALLET_ADDRESS=0xYOUR_WALLET_ADDRESS_OR_SOLANA_ADDRESS
export X402_AUTH=YOUR_BASE64_SIWX_HEADER

curl --request GET \
  --url "https://api.venice.ai/api/v1/x402/transactions/$WALLET_ADDRESS?limit=10&offset=0" \
  --header "X-Sign-In-With-X: $X402_AUTH"

The ledger includes entries such as TOP_UP, CHARGE, and REFUND. The walletAddress path parameter accepts either an EVM address (0x...) or a Solana base58 address.

Supported routes

Paid inference routes

The following public paid Venice routes currently support x402 wallet authentication.

Category	Endpoints
Chat	`POST /api/v1/chat/completions`, `POST /api/v1/responses`
Image	`POST /api/v1/image/generate`, `POST /api/v1/images/generations`, `POST /api/v1/image/upscale`, `POST /api/v1/image/edit`, `POST /api/v1/image/multi-edit`, `POST /api/v1/image/background-remove`
Embeddings	`POST /api/v1/embeddings`
Audio	`POST /api/v1/audio/speech`, `POST /api/v1/audio/transcriptions`, `POST /api/v1/audio/complete`, `POST /api/v1/audio/queue`, `POST /api/v1/audio/retrieve`
Video	`POST /api/v1/video/complete`, `POST /api/v1/video/queue`, `POST /api/v1/video/retrieve`, `POST /api/v1/video/transcriptions`

Top-up route

Endpoint	Auth	Purpose
`POST /api/v1/x402/top-up`	Initial request: none. Retry: `X-402-Payment`	Add USDC credits to the wallet’s spendable balance using an accepted Base or Solana payment option

Wallet-only routes

These routes use X-Sign-In-With-X for identity but do not charge balance.

Endpoint	Purpose
`GET /api/v1/x402/balance/{walletAddress}`	Check spendable balance for an EVM or Solana wallet address
`GET /api/v1/x402/transactions/{walletAddress}`	View transaction history for an EVM or Solana wallet address

Errors

Status	Likely cause	What to do
`401`	Malformed or expired Sign-In-With-X payload	Rebuild `X-Sign-In-With-X` with a fresh nonce and timestamp
`402` on a paid route	Not enough spendable balance	Top up and retry
`402` on `/x402/top-up`	Expected. This is the payment initiation flow.	Use the returned payment details to build `X-402-Payment` and retry
`403` on balance or transactions	Wallet mismatch	Ensure the authenticated wallet matches the `walletAddress` path parameter
`400` on top-up	Malformed payment header	Rebuild from the latest `402` response

For agents

The flow is the same. Store private keys in environment variables or a secret manager, and check balance before requests to avoid unnecessary 402 round-trips.

x402 Client SDK

Official Venice x402 client for Node.js/TypeScript.

API Pricing

Check model pricing and how Venice charges usage.

Chat Completions

A common paid route for wallet-based access.

API Spec

Reference documentation and raw spec access.

Wallet Auth

Pay with USDC

DIEM First

​What is X402?

​Prerequisites

​Quick start

​With OpenAI-compatible tools

​Available helpers

​Manual flow

​Step 1: Create the X-Sign-In-With-X header

​Step 2: Check balance

​Step 3: Top up

​Building the X-402-Payment header for Base

​Step 4: Make a request

​Step 5: Inspect transactions (optional)

​Supported routes

​Paid inference routes

​Top-up route

​Wallet-only routes

​Errors

​For agents

​Related resources

x402 Client SDK

API Pricing

Chat Completions

API Spec

What is X402?

Prerequisites

Quick start

With OpenAI-compatible tools

Available helpers

Manual flow

Step 1: Create the X-Sign-In-With-X header

Step 2: Check balance

Step 3: Top up

Building the X-402-Payment header for Base

Step 4: Make a request

Step 5: Inspect transactions (optional)

Supported routes

Paid inference routes

Top-up route

Wallet-only routes

Errors

For agents

Related resources