/venice-auth

name: venice-auth
description: Authenticate to the Venice API with a Bearer API key or with an x402 / SIWX wallet (EVM on Base, including EIP-1271 smart wallets, or Ed25519 on Solana). Covers which endpoints accept which scheme, the SIGN-IN-WITH-X header format, the SIWE and Solana message fields, the enforced TTL / clock-skew / nonce rules, every X402_SIGN_IN_* error code, the venice-x402-client SDK, and how to choose between the two modes.

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

| Endpoints | Bearer key | SIWX wallet | |---|---|---| | Inference: `/chat/completions`, `/responses`, `/embeddings`, `/decisions` (+ `/systemone`), `/image/*` (generate, edit, multi-edit, upscale, background-remove), `/images/generations`, `/audio/speech`, `/audio/transcriptions`, `/audio/voices`, `/audio/{queue,retrieve,complete}`, `/audio/voice-changer/{queue,retrieve,complete}`, `/video/{queue,retrieve,complete}`, `/augment/*`, `POST /crypto/rpc/{network}` | yes | yes | | `/api_keys*` (except `generate_web3_key`), `/billing/*` (except the retired `/billing/usage`, which answers `410` without auth), `/characters*` | yes | no - a SIWX header alone gets `401 Authentication failed` | | `GET /x402/balance/{wallet}`, `GET /x402/transactions/{wallet}` | no | yes - signer must be `{wallet}` (else `403`) | | `POST /x402/top-up` | - | payment header (see below) | | `/models*`, `/image/styles`, `/video/quote` (except upscale models: Bearer key required), `/audio/quote`, `/audio/voice-changer/quote`, `/crypto/rpc/networks`, `/tee/*`, `/api_keys/generate_web3_key` | not required | not required |

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`](../venice-api-keys/SKILL.md).
• 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`](../venice-billing/SKILL.md#currency--priority)).

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:

| Field | Notes | |---|---| | `address` | EVM hex address (compared case-insensitively) or Solana base58 address (must match the message exactly). | | `message` | The exact signed string. EVM: EIP-4361 SIWE. Solana: the Solana SIWX format. Optional if you send the structured fields instead (below). | | `signature` | EVM: hex. Solana: 64-byte Ed25519 signature, base58 or base64. | | `chainId` | Optional. EVM: `8453`, `"8453"`, or `"eip155:8453"` (must match the message; another format → `X402_SIGN_IN_INVALID_CHAIN_ID`). Solana: `"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"`. | | `type` | Optional. `"ed25519"` for Solana. Omit for EVM. | | `timestamp` | Optional, Unix ms (Venice-legacy). If sent, it must be within 30 s of the signed `Issued At`. |

{
  "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)

| Field | Rule | |---|---| | `domain` | Use `api.ve