venice-auth

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

```http
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)).

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

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

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

| Field | Rule |
|---|---|
| `domain` | Use `api.venice.ai` (`venice.ai` is also accepted). Protocol, port and path are stripped before comparing, and the value is checked against Venice's allowed domains, not the request `Host`. |
| `address` | The signer. Venice compares it case-insensitively; the `siwe` library expects the EIP-55 checksummed form. |
| `uri` | Required by SIWE; not validated by Venice. `https://api.venice.ai` is conventional. |
| `version` | `"1"` |
| `chainId` | `8453` only (anything else → `X402_SIGN_IN_UNSUPPORTED_CHAIN`). A message with no `Chain ID` line is read as chain `1` and rejected the same way. |
| `nonce` | Required, single-use per wallet. The `siwe` library needs ≥ 8 alphanumeric chars; 16 hex chars is a safe choice. |
| `issuedAt` | Required. Must be at most **5 minutes** old and at most **30 s** in the future. |
| `expirationTime` | Optional, but **enforced**: past it → `X402_SIGN_IN_EXPIRED`. |
| `notBefore` | Optional, enforced (`X402_SIGN_IN_NOT_BEFORE`). |
| `statement` | Any string. Venice's own challenge uses `"Sign in to Venice AI"`. |

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.

From veniceai/skills, MIT.

More from veniceai/skills