venice-auth

Venice Authentication

Every Venice endpoint accepts one of two auth schemes, declared in the OpenAPI spec as BearerAuth and siwx. Both are first-class — pick whichever fits the deployment.

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 Authentication failed and need to check header format.
• You're implementing SIWE signing manually instead of using the SDK.

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 consumptionLimits (USD and/or DIEM caps) and apiKeyType (ADMIN or INFERENCE).
• Billing draws from DIEM (staked), USD balance, and bundled credits in order.
• Key types determine which endpoints are reachable — only ADMIN keys can manage other keys.

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-1",
    "messages": [{"role":"user","content":"hello"}]
  }'

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

Option B — x402 wallet (SIWE)

Authenticate with an Ethereum wallet. No account needed. Pay per request in USDC on Base (chain ID 8453). Balance lives under your wallet address and is consumed automatically.

Header

X-Sign-In-With-X: <base64(json)>

Where the decoded JSON is:

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

SIWE message fields (EIP-4361)

The header is short-lived — generate a fresh one at most every ~4 minutes (server accepts up to 5 min from issuedAt). The payload timestamp must be within 30 seconds of the SIWE issuedAt, and issuedAt itself must not be more than 30 seconds ahead of server time. Nonces are single-use per wallet — reuse within ~5.5 minutes is rejected with X402_SIGN_IN_NONCE_REUSED.

Domain is validated against the allow-list above — not against the incoming request's Host header. Passing any allow-listed domain (e.g. api.venice.ai) is fine regardless of which Venice host you hit.

Manual signing (TypeScript)

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

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

function makeSiwxHeader() {
  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: new Date().toISOString(),
    expirationTime: new Date(Date.now() + 4 * 60_000).toISOString(),
  })
  const message = msg.prepareMessage()
  const signature = wallet.signMessageSync(message)
  return btoa(JSON.stringify({
    address: wallet.address,
    message,
    signature,
    timestamp: Date.now(),
    chainId: 8453,
  }))
}

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

SDK shortcut

npm install venice-x402-client

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

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

await venice.topUp(10)            // $10 USDC on Base (first time only)
const res = await venice.chat({
  model: 'zai-org-glm-5-1',
  messages: [{ role: 'user', content: 'Hello!' }],
})
console.log(res.choices[0].message.content)

VeniceClient and createAuthFetch handle SIWE signing, header rotation, and 402 top-up prompts automatically.

SIWE-proxy pattern (make a Bearer-key client draw from a wallet)

When you have a client that only knows how to send Authorization: Bearer … (e.g. Hermes' provider model, the OpenAI SDK, LiteLLM, anything OpenAI-shaped) but you want to pay from an x402 wallet, run a tiny local proxy that strips the client's Authorization header and injects a fresh SIWE header per request. The client points at the proxy as if it were Venice; the proxy forwards to api.venice.ai.

This avoids:

• Needing a Venice account at all.
• Linking a wallet via the Venice dashboard (which still requires an account session).
• Modifying clients that don't expose an auth hook.

A complete working proxy is at scripts/siwe-proxy.js. Pitfalls baked in:

• Strip the client's Authorization header before forwarding — Venice rejects a request that carries both Bearer and SIWE.
• Strip host, content-length, and connection too — fetch() sets these itself.
• Sign a fresh SIWE header per request (cheap, ~ms). Don't try to cache: nonces are single-use per wallet for ~5.5 min and issuedAt must be within 30s of the request timestamp.
• Bind to 127.0.0.1 only. The private key is on the box; never expose the proxy to the network.
• Strip content-encoding, content-length, transfer-encoding from the upstream response too — Node's http will set them.

Per-account wallet linking ≠ proxy pattern

A linked wallet (Bearer key falls back to wallet credits) is a convenience on top of a Venice account, not a prerequisite. If the user has no account, the proxy pattern is the right call. If they do and want one unified balance across Bearer + wallet, link the wallet via venice.ai's dashboard — there is no headless /link-wallet API.

First-time top-up (wallet → credits)

POST /x402/top-up                # WITHOUT X-402-Payment header → returns payment requirements
→ sign a USDC transfer authorization with the x402 SDK (createPaymentHeader)
POST /x402/top-up                # WITH X-402-Payment header → credits land on your wallet address

See venice-x402 for the full flow.

Choosing between the two

Both schemes can co-exist: a Pro user may generate a Web3 API key via POST /api_keys/generate_web3_key that ties an on-chain wallet to an off-chain key with an EIP-191 signature. See venice-api-keys.

Common auth errors

Security hygiene

• Bearer keys behave like passwords — store in a secret manager, rotate on compromise, scope via consumptionLimits.
• SIWE requires a private key signer on the client side. For browsers, use a wallet provider (MetaMask, WalletConnect) — do not ship raw private keys.
• Signed headers are valid 5 minutes from issuedAt; rotate every ~4 minutes. Never reuse a signed X-Sign-In-With-X header across hours or across machines. Nonces are tracked per wallet for ~5.5 min; replaying one is rejected with X402_SIGN_IN_NONCE_REUSED.
• Rate limits are per-key (Bearer) or per-wallet (x402). See venice-api-keys and venice-errors.