X402

X402 lets you use Venice’s paid API routes by authenticating with an Ethereum wallet on Base. No API key or account required. Sign a message, maintain a balance, and call any supported route.

Wallet Auth

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

Pay with USDC

Maintain spendable balance with USDC on Base.

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 on Base so that wallets can authenticate and pay for inference directly.

Prerequisites

An EVM wallet on Base
A small amount of ETH on Base for gas
USDC on Base (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 SIWE 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 SIWE message. Generate a fresh nonce and timestamp for each request flow.

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

Step 3: Top up

Top up with USDC on Base:

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. Use those payment details to build an X-402-Payment header and retry the same route.

Building the X-402-Payment header

The following script creates a signed x402 payment 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.

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

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

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
`GET /api/v1/x402/transactions/{walletAddress}`	View transaction history

Errors

Status	Likely cause	What to do
`401`	Malformed or expired SIWE 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.

Overview

Agents & Integrations

Getting Started

Text & Chat

Image & Video

Coding Tools

SDKs & Frameworks

X402

Wallet Auth

Pay with USDC

DIEM First

What is X402?

Prerequisites

Quick start

With OpenAI-compatible tools

Available helpers

Manual flow

Step 2: Check balance

Step 3: Top up

Building the X-402-Payment header

Step 4: Make a request

Step 5: Inspect transactions (optional)

Supported routes

Paid inference routes

Top-up route

Wallet-only routes

Errors

For agents

x402 Client SDK

API Pricing

Chat Completions

API Spec

Overview

Agents & Integrations

Getting Started

Text & Chat

Image & Video

Coding Tools

SDKs & Frameworks

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

​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

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