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.

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.