Venice Auth

Venice Authentication

Venice declares two auth schemes in its OpenAPI spec: BearerAuth (API key) and siwx (x402 wallet). Inference endpoints accept either; account endpoints need a key; discovery endpoints need nothing.

Use when

• You're making your first call to api.venice.ai.
• You're building a server-side integration (usually Bearer) or an agent / no-account wallet flow (x402).
• You hit 401 / 402 and need to check header format.
• You're implementing SIWE / Solana signing manually instead of using the SDK.

Which endpoints accept what

On routes that accept a wallet, a SIGN-IN-WITH-X header wins: Venice uses wallet auth even when Authorization is also present. On Bearer-only routes the SIWX header is ignored. A request with neither header on any route that needs credentials (Bearer-only routes included) gets 402 with an x402 discovery body (payment options, SIWX challenge, authOptions), not 401.

Option A - Bearer API key

Authorization: Bearer <VENICE_API_KEY>

• Create keys at https://venice.ai/settings/api or via venice-api-keys.
• Keys carry apiKeyType (ADMIN or INFERENCE), optional consumptionLimits (usd / diem caps over a limitPeriod), and modelPrivacy (ALL, PRIVATE_TEXT, PRIVATE_ONLY) which restricts which models the key may call.
• Only ADMIN keys can list, get, create, update or delete keys, read the rate-limit log, or call /billing/balance, /billing/usage-history and /billing/usage-analytics; an INFERENCE key gets 401 "Admin API key required".
• Each request is charged to a single currency, picked in the order DIEM (staked) → earned credits → bundled credits → USD balance (see venice-billing).

curl https://api.venice.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zai-org-glm-5-2",
    "messages": [{"role":"user","content":"hello"}]
  }'

Use Bearer when you have a Venice account, want usage analytics (/billing/usage-analytics, /billing/usage-history), want scoped child keys, or need DIEM / bundled-credit priority.

Option B - x402 wallet (SIWX)

Authenticate with an EVM wallet on Base (chain 8453) or a Solana wallet on Solana mainnet. No account needed. Requests draw from a prepaid USDC credit balance tied to the wallet; a request needs at least $0.10 of balance to start. An EVM wallet that is linked to a Venice account with staked DIEM spends DIEM first: while DIEM remains, requests are billed to the linked account, so a 402 in that state is not fixed by /x402/top-up.

Header

SIGN-IN-WITH-X: <base64(json)>

SIGN-IN-WITH-X is the canonical x402 v2 header. Venice's original X-Sign-In-With-X is still accepted (header names are case-insensitive).

Decoded JSON:

{
  "address":   "0x...",
  "message":   "<SIWE message string from SiweMessage.prepareMessage()>",
  "signature": "0x...",
  "chainId":   8453
}

Instead of message you may send the structured SIWX fields (domain, address, uri, version, nonce, issuedAt, expirationTime, notBefore, statement, resources, chainId, type). Venice rebuilds the exact message bytes and verifies the signature over them - domain, address, uri, nonce, issuedAt and chainId are required. The rebuilt Chain ID line uses the bare reference (8453, 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp), not the CAIP-2 form, so sign the bare value.

SIWE message fields (EIP-4361, EVM)

EOA signatures (EIP-191) and smart-contract wallet signatures (EIP-1271) are both accepted on Base.

Effective lifetime = the earlier of issuedAt + 5 min and expirationTime, but each header is good for one request: the nonce is consumed as soon as the signature verifies (even if the request then fails, e.g. with 402), and nonces are remembered per wallet for 5.5 minutes - longer than any header can live - so re-sending a header fails with X402_SIGN_IN_NONCE_REUSED. Sign a new header for every request, including retries.

Solana message fields

Solana wallets sign the Solana SIWX message with Ed25519. It must start with <domain> wants you to sign in with your Solana account:, then the base58 address on the next line, and include URI, Version: 1, Chain ID, Nonce and Issued At lines (Expiration Time / Not Before optional and enforced):

api.venice.ai wants you to sign in with your Solana account:
7xKX...base58...

Sign in to Venice AI

URI: https://api.venice.ai
Version: 1
Chain ID: 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
Nonce: 3f2a91c4d80b7e15
Issued At: 2026-09-30T19:00:00.000Z
Expiration Time: 2026-09-30T19:05:00.000Z

In the base64 payload set type: "ed25519" and chainId: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp". The Chain ID line may carry the bare reference (canonical) or the solana:-prefixed form. The same domain allow-list, 5-minute age, 30-second skew and single-use nonce rules apply.

Manual signing (TypeScript, EVM)

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

const wallet = new Wallet(process.env.WALLET_KEY!)

function makeSiwxHeader() {
  const now = new Date()
  const msg = new SiweMessage({
    domain: 'api.venice.ai',
    address: wallet.address,
    statement: 'Sign in to Venice AI',
    uri: 'https://api.venice.ai',
    version: '1',
    chainId: 8453,
    nonce: crypto.randomUUID().replace(/-/g, '').slice(0, 16),
    issuedAt: now.toISOString(),
    expirationTime: new Date(now.getTime() + 4 * 60_000).toISOString(),
  })
  const message = msg.prepareMessage()
  const signature = wallet.signMessageSync(message)
  return btoa(JSON.stringify({ address: wallet.address, message, signature, chainId: 8453 }))
}

const res = await fetch('https://api.venice.ai/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'SIGN-IN-WITH-X': makeSiwxHeader(),
  },
  body: JSON.stringify({
    model: 'zai-org-glm-5-2',
    messages: [{ role: 'user', content: 'hello' }],
  }),
})

SDK shortcut (EVM / Base)

npm install venice-x402-client

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

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

await venice.topUp(10)            // pay $10 USDC on Base into the wallet's credit balance
const res = await venice.chat({
  model: 'zai-org-glm-5-2',
  messages: [{ role: 'user', content: 'Hello!' }],
})
console.log(res.choices[0].message.content)

The constructor takes a 0x-prefixed hex private key and optional { apiUrl, autoTopUp, timeoutMs } (default timeout 180 s). VeniceClient and createAuthFetch sign a fresh (legacy-named) X-Sign-In-With-X header for every request, including retries. VeniceClient retries 429 up to 3 times (1 s, 2 s, 4 s). On 402 it throws a VeniceError with code INSUFFICIENT_BALANCE. Leave autoTopUp off: when enabled it tops up again on every 402 with no limit and no balance check, and a wallet linked to staked DIEM can loop until the wallet is empty because a USDC top-up doesn't fix a DIEM-mode 402. Catch the error, check getBalance(), and call topUp(amount) yourself within the user's cap. topUp pays whatever recipient the server returns without the checks in Payment safety, so keep apiUrl at the default https://api.venice.ai. Other methods: chatStream, embeddings, models, getBalance, getTransactions, images.*, audio.*, video.*, responses.*. The SDK signs with an EVM private key and pays on Base; for Solana, sign manually as above.

First-time top-up (wallet → credits)

POST /x402/top-up                # no payment header → 402 with Base + Solana options in accepts[]
→ pick one accepts[] entry and sign it with the x402 SDK (createPaymentHeader)
POST /x402/top-up                # with PAYMENT-SIGNATURE header → credits land on the paying wallet

PAYMENT-SIGNATURE is the canonical x402 v2 payment header; X-402-Payment and X-PAYMENT are also accepted. Payment headers are accepted only on /x402/top-up - sending one to an inference route returns 400 PAYMENT_HEADER_NOT_ACCEPTED. Minimum top-up $5. See venice-x402.