> ## Documentation Index > Fetch the complete documentation index at: https://veniceai-mintlify-d2fddb8a.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Crypto RPC > Proxy a JSON-RPC request to a supported blockchain node and bill per credit. ## Request shapes - **Single request**: a JSON-RPC 2.0 object (`{ "jsonrpc":"2.0", "method":"…", "params":[…], "id":1 }`). - **Batch**: an array of up to 100 JSON-RPC 2.0 objects. If any item references an unsupported method, the entire batch is rejected with 400 and the offending methods are listed. ## Supported methods Methods are classified into three pricing tiers: - **Standard (1×)**: `eth_call`, `eth_getBalance`, `eth_blockNumber`, `eth_sendRawTransaction`, `eth_getLogs`, `net_version`, `web3_clientVersion`, ERC-4337 bundler methods (`eth_sendUserOperation`, etc.), and chain-family extensions (`zks_*`, `linea_*`, `bor_*`, `starknet_*`). - **Advanced (2×)**: `trace_*`, `debug_*`, `txpool_inspect`, `txpool_status`, `arbtrace_*`. - **Large (4×)**: `trace_replayBlockTransactions`, `trace_replayTransaction`, `txpool_content`, `arbtrace_replay*`. Stateful filter methods (`eth_newFilter`, `eth_getFilterChanges`, `eth_uninstallFilter`, etc.) are **not supported** — they break on a load-balanced HTTP proxy because filter state is pinned to a single upstream backend. Use `eth_getLogs` instead. WebSocket-only methods (`eth_subscribe`, `eth_unsubscribe`) return 400 because this proxy is HTTP-only. ## Pricing Credits consumed per call = `baseCredits[chain] × methodTier`. `baseCredits` is 20 for most EVM chains (Ethereum, Base, Optimism, Arbitrum, Polygon, Linea, Avalanche, BSC, Blast) and Starknet; 30 for zkSync Era. The USD price per credit is `~7e-7` — a single standard EVM call costs ≈ $0.000014 and a large trace-replay costs ≈ $0.000056. Per-request errors at the JSON-RPC layer (HTTP 200 with an `error` field in a response item) are billed at 5 credits instead of the full method tier — a small concession for methods not supported on a given chain or bad-parameter responses. ## Rate limits Two caps apply per caller: - **Requests per minute**: 100 on the paid tier, 1000 on the staff tier. - **Credits per rolling 24 hours**: 10,000,000 on the paid tier, 100,000,000 on the staff tier. When either cap is exceeded, the request returns 429 with a `customMessage` identifying which cap tripped. The per-minute cap also sets the `X-RateLimit-*` response headers. ## Idempotency Set the `Idempotency-Key` request header to any string matching `[A-Za-z0-9_-]{1,255}` to enable safe retries. The response is cached for 24 hours keyed on `(user, idempotency-key)`; replaying the same key with the same body returns the cached response with `Idempotent-Replayed: true`. Reusing the same key with a different body returns 400 to prevent silent corruption. **Authentication:** This endpoint accepts either a Bearer API key or a `SIGN-IN-WITH-X` header for x402 wallet-based authentication. The legacy `X-Sign-In-With-X` header is also accepted during migration. When using x402, a `402 Payment Required` response indicates insufficient balance and includes top-up instructions. 将 JSON-RPC 2.0 请求（单个或批量）转发到受支持的区块链节点。同时支持 API 密钥和 x402 钱包身份验证。计费按额度计，并以您的 Venice 余额结算 —— 一份凭证、一张账单，覆盖下方所有链。 ## 身份验证 此端点支持两种身份验证方法： * **API 密钥**：通过 `Authorization: Bearer ` 请求头进行标准 Bearer token 身份验证。 * **x402 钱包**：使用 Base 或 Solana 钱包中的 USDC 额度按用量付费。无需 Venice 账户。设置请参阅 [x402 指南](/guides/integrations/x402-venice-api)。 两种方法共享相同的速率限制和计费（Venice 额度）。 ## 支持的网络 请参阅 [`GET /crypto/rpc/networks`](/api-reference/endpoint/crypto/networks) 查看实时、权威的列表。当前覆盖范围： | 家族 | Mainnet | Testnets | | ----------------- | ------------------- | ------------------------------------- | | Ethereum | `ethereum-mainnet` | `ethereum-sepolia`、`ethereum-holesky` | | Polygon | `polygon-mainnet` | `polygon-amoy` | | Arbitrum | `arbitrum-mainnet` | `arbitrum-sepolia` | | Optimism | `optimism-mainnet` | `optimism-sepolia` | | Base | `base-mainnet` | `base-sepolia` | | Linea | `linea-mainnet` | `linea-sepolia` | | Avalanche C-Chain | `avalanche-mainnet` | `avalanche-fuji` | | BNB Smart Chain | `bsc-mainnet` | `bsc-testnet` | | Blast | `blast-mainnet` | `blast-sepolia` | | zkSync Era | `zksync-mainnet` | `zksync-sepolia` | | Starknet | `starknet-mainnet` | `starknet-sepolia` | ## 请求格式 ### 单个请求 ```json theme={null} { "jsonrpc": "2.0", "method": "eth_chainId", "params": [], "id": 1 } ``` ### 批量请求 最多 **100** 个 JSON-RPC 2.0 对象的数组。每个项目独立验证；如果任何方法不受支持，整个批次将被以 `400` 拒绝，所有不合规的方法名都会列在错误消息中。 ```json theme={null} [ { "jsonrpc": "2.0", "method": "eth_chainId", "params": [], "id": 1 }, { "jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 2 } ] ``` ## 支持的方法和额度等级 方法被分为三个额度等级。每次调用消耗的额度 = `baseCredits[chain] × methodTier`。 | 等级 | 倍数 | 示例方法 | | ------------ | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Standard** | 1× | `eth_call`、`eth_getBalance`、`eth_blockNumber`、`eth_sendRawTransaction`、`eth_getLogs`、`eth_getTransactionReceipt`、`eth_estimateGas`、`net_version`、`web3_clientVersion`、ERC-4337 bundler 方法（`eth_sendUserOperation`、`eth_estimateUserOperationGas` 等）、链家族扩展（`zks_*`、`linea_*`、`bor_*`、`starknet_*`） | | **Advanced** | 2× | `trace_block`、`trace_call`、`trace_transaction`、`debug_traceCall`、`debug_traceTransaction`、`debug_traceBlockByHash`、`txpool_inspect`、`txpool_status`、`arbtrace_*` | | **Large** | 4× | `trace_replayBlockTransactions`、`trace_replayTransaction`、`txpool_content`、`arbtrace_replayTransaction`、`arbtrace_replayBlockTransactions` | ### 每条链的基础额度 | baseCredits | 链 | | ----------- | ------------------------------------------------------------------------------------------- | | **20** | Ethereum + 以上所有 EVM L2（Base、Optimism、Arbitrum、Polygon、Linea、Avalanche、BSC、Blast）以及 Starknet | | **30** | zkSync Era | ### 费用示例 按 Venice 的 `~$6.25 × 10⁻⁷` 每额度计算： | 调用 | 额度 | USD 费用 | | ---------------------------------------------- | -- | ----------- | | Ethereum 上的 `eth_call`（20 × 1×） | 20 | \$0.0000125 | | Ethereum 上的 `trace_transaction`（20 × 2×） | 40 | \$0.0000250 | | Ethereum 上的 `trace_replayTransaction`（20 × 4×） | 80 | \$0.0000500 | | zkSync 上的 `eth_call`（30 × 1×） | 30 | \$0.0000188 | ### 不支持 * **仅 WebSocket 方法**（`eth_subscribe`、`eth_unsubscribe`）—— 此代理仅支持 HTTP。请改为轮询，或升级到直连的 WebSocket 提供商。 * **有状态过滤器方法**（`eth_newFilter`、`eth_getFilterChanges`、`eth_getFilterLogs`、`eth_uninstallFilter`、`eth_newBlockFilter`、`eth_newPendingTransactionFilter`）—— 过滤器状态绑定到单一上游后端，在负载均衡的 HTTP 代理上会静默失效。请改用 `eth_getLogs`（无状态）。 * **矿工 / 持有密钥方法**（`eth_sign`、`eth_accounts`、`eth_mining`、`eth_hashrate`、`eth_getWork`、`eth_submitWork`）—— 托管的提供商端点不持有用户私钥，因此这些方法总是返回错误。请在客户端签名交易并通过 `eth_sendRawTransaction` 提交。 * **未映射的方法** —— 任何未明确加入允许列表的方法都会返回 `400`。请联系支持以请求新增。 ## 批量按项计费 即使 HTTP 响应为 `200`，批量中的单个项目也可能带有 JSON-RPC `error` 字段返回（例如参数错误或目标链不支持的方法）。Venice 对这些项目按**每个 5 额度**计费，而不是完整的方法等级 —— 对正常的"探索 API"错误的小小宽容。 ```json theme={null} // Batch request: [ { "jsonrpc": "2.0", "method": "eth_chainId", "params": [], "id": 1 }, { "jsonrpc": "2.0", "method": "eth_getBalance","params": ["bad"], "id": 2 } ] // Response (HTTP 200, X-Venice-RPC-Credits: 25): [ { "jsonrpc": "2.0", "id": 1, "result": "0x1" }, { "jsonrpc": "2.0", "id": 2, "error": { "code": -32602, "message": "invalid params" } } ] ``` 第一项（成功）计费 20 额度，第二项（RPC 级错误）计费 5，合计 `= 25`。 ## 速率限制 每个已认证调用方的每分钟请求上限： | 等级 | 请求/分钟 | | -------- | ----- | | Standard | 100 | | Staff | 1,000 | 超过上限时，端点会以 `429` 返回，并附带 `customMessage` 和标准的 `X-RateLimit-*` 响应头。 ## 幂等性 将 `Idempotency-Key` 请求头设置为任何匹配 `[A-Za-z0-9_-]{1,255}` 的字符串，可启用安全重试。响应以 `(user, idempotency-key)` 为键缓存 24 小时： * 使用**相同的键和相同的请求体**重放，将返回缓存的响应并附带 `Idempotent-Replayed: true` 响应头。不会请求上游，也不会扣除新的额度。 * 使用**相同的键但不同的请求体**重放，将返回 `400`，以防止静默的状态损坏。请为不同请求选择新键。 ## 响应头 | 请求头 | 说明 | | ------------------------------------------------------------------- | ------------------------------------------------- | | `X-Venice-RPC-Credits` | 此请求扣除的额度。批量请求时，这是所有项目的总和。 | | `X-Venice-RPC-Cost-USD` | 精确到 8 位小数的美元费用。等于 `X-Venice-RPC-Credits × 每额度价格`。 | | `X-Request-ID` | 32 字符的关联 ID。请在任何支持沟通中附带。 | | `Idempotent-Replayed` | 当响应来自幂等性缓存时存在，值为 `"true"`。 | | `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` | 仅在 429 响应中设置。 | ## 交易转发的取证日志 对 `eth_sendRawTransaction` 的每次调用都会在服务器端记录 tx hash（原始字节的 keccak256）、网络 slug、请求 ID 和调用方用户 ID。我们**不**保留签名载荷本身 —— 该 hash 可从链上回执中恢复。该审计追踪的存在是为了在客户的 API 密钥被泄露并被用于通过我们的基础设施转发非法交易时，可将链上活动关联到负责账户。 ## 示例 ```bash theme={null} curl https://api.venice.ai/api/v1/crypto/rpc/ethereum-mainnet \ -H "Authorization: Bearer $VENICE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "eth_chainId", "params": [], "id": 1 }' ``` ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": "0x1" } ``` 响应头：`X-Venice-RPC-Credits: 20`、`X-Venice-RPC-Cost-USD: 0.00001250`、`X-Request-ID: `。 ## Postman 集合 我们的公开工作区提供了一个可直接导入的 Postman 集合，包含 27 个示例请求（发现、standard/advanced/large 调用、多链、批量、幂等性、错误场景）： **[Venice Crypto RPC — Postman 集合](https://www.postman.com/veniceai/workspace/venice-ai-workspace/folder/38652128-2cf5a817-41cd-438b-ad37-5d07c3f13005?action=share\&creator=48156591\&active-environment=38652128-ef110f4e-d3e1-43b5-8029-4d6877e62041)** 将集合变量 `apiKey` 设置为您的 Venice API 密钥，即可立即开始发送请求。 ## OpenAPI ````yaml POST /crypto/rpc/{network} openapi: 3.0.0 info: description: The Venice.ai API. termsOfService: https://venice.ai/legal/tos title: Venice.ai API version: '20260622.204854' x-guidance: >- Venice.ai is an OpenAI-compatible inference API supporting text, image, audio, and video generation. **Authentication options:** - API Key: Use Bearer token in Authorization header - x402 Wallet: Use USDC credits via EVM or Solana wallet (no account required) **For x402 wallet access:** 1. POST /x402/top-up without headers to get payment requirements 2. Choose one of the returned Base or Solana payment options and sign a USDC payment using the x402 SDK 3. POST /x402/top-up with PAYMENT-SIGNATURE header to add credits 4. Call any inference endpoint with SIGN-IN-WITH-X header **Pricing:** Prepaid credits consumed per request. Check /models for available models and their capabilities. servers: - url: https://api.venice.ai/api/v1 security: - BearerAuth: [] tags: - description: >- Generate speech/audio, transcribe audio, and manage asynchronous audio generation jobs. name: Audio - description: >- Given a list of messages comprising a conversation, the model will return a response. Supports multimodal inputs including text, images, audio (input_audio), and video (video_url) for compatible models. name: Chat - description: List and describe the various models available in the API. name: Models - description: Generate and manipulate images using AI models. name: Image - description: Generate videos using AI models. name: Video - description: List and retrieve character information for use in completions. name: Characters - description: >- Billing and usage analytics. **Beta**: This API is currently in beta and may be unstable. Endpoints, request/response schemas, and behavior may change without notice. name: Billing - description: Proxy JSON-RPC requests to blockchain nodes. Billed per credit. name: Crypto RPC - description: >- Wallet-based API access using the x402 protocol. No API key required — authenticate with an EVM or Solana wallet. **How it works:** 1. **Authenticate** — Send a `SIGN-IN-WITH-X` header (base64-encoded signed SIWX payload) with any request. EVM wallets sign an EIP-4361 SIWE message; Solana wallets sign the Solana SIWX message with Ed25519. See the `siwx` security scheme for the exact format. 2. **Top up** — `POST /x402/top-up` without a payment header returns an `accepts` array with Base and Solana USDC payment options. Choose one entry, sign it using the x402 SDK (`npm install x402`), and re-submit with the `PAYMENT-SIGNATURE` header (the legacy `X-402-Payment` and `X-PAYMENT` names are also accepted). 3. **Use any endpoint** — All inference endpoints (chat, image, audio, video, embeddings) accept `siwx` as an alternative to `BearerAuth`. Charges are deducted from your USDC credit balance. 4. **Monitor balance** — `GET /x402/balance/{walletAddress}` returns your current balance. The `X-Balance-Remaining` response header on inference calls also reports it. **Quick start (5 lines):** ``` import { VeniceClient } from '@venice-ai/x402-client' const venice = new VeniceClient(process.env.WALLET_KEY) await venice.topUp(10) // $10 USDC on a supported x402 rail const res = await venice.chat({ model: 'zai-org-glm-5-1', messages: [{ role: 'user', content: 'Hello!' }] }) ``` **Payment:** USDC on Base (chain ID 8453) or Solana mainnet. Minimum top-up: $5. Alternatively, stake DIEM tokens for daily credits (1 DIEM = $1/day). name: x402 externalDocs: description: Venice.ai API documentation url: https://docs.venice.ai paths: /crypto/rpc/{network}: post: tags: - Crypto RPC summary: Proxy a JSON-RPC request to a supported blockchain description: >- Proxy a JSON-RPC request to a supported blockchain node and bill per credit. ## Request shapes - **Single request**: a JSON-RPC 2.0 object (`{ "jsonrpc":"2.0", "method":"…", "params":[…], "id":1 }`). - **Batch**: an array of up to 100 JSON-RPC 2.0 objects. If any item references an unsupported method, the entire batch is rejected with 400 and the offending methods are listed. ## Supported methods Methods are classified into three pricing tiers: - **Standard (1×)**: `eth_call`, `eth_getBalance`, `eth_blockNumber`, `eth_sendRawTransaction`, `eth_getLogs`, `net_version`, `web3_clientVersion`, ERC-4337 bundler methods (`eth_sendUserOperation`, etc.), and chain-family extensions (`zks_*`, `linea_*`, `bor_*`, `starknet_*`). - **Advanced (2×)**: `trace_*`, `debug_*`, `txpool_inspect`, `txpool_status`, `arbtrace_*`. - **Large (4×)**: `trace_replayBlockTransactions`, `trace_replayTransaction`, `txpool_content`, `arbtrace_replay*`. Stateful filter methods (`eth_newFilter`, `eth_getFilterChanges`, `eth_uninstallFilter`, etc.) are **not supported** — they break on a load-balanced HTTP proxy because filter state is pinned to a single upstream backend. Use `eth_getLogs` instead. WebSocket-only methods (`eth_subscribe`, `eth_unsubscribe`) return 400 because this proxy is HTTP-only. ## Pricing Credits consumed per call = `baseCredits[chain] × methodTier`. `baseCredits` is 20 for most EVM chains (Ethereum, Base, Optimism, Arbitrum, Polygon, Linea, Avalanche, BSC, Blast) and Starknet; 30 for zkSync Era. The USD price per credit is `~7e-7` — a single standard EVM call costs ≈ $0.000014 and a large trace-replay costs ≈ $0.000056. Per-request errors at the JSON-RPC layer (HTTP 200 with an `error` field in a response item) are billed at 5 credits instead of the full method tier — a small concession for methods not supported on a given chain or bad-parameter responses. ## Rate limits Two caps apply per caller: - **Requests per minute**: 100 on the paid tier, 1000 on the staff tier. - **Credits per rolling 24 hours**: 10,000,000 on the paid tier, 100,000,000 on the staff tier. When either cap is exceeded, the request returns 429 with a `customMessage` identifying which cap tripped. The per-minute cap also sets the `X-RateLimit-*` response headers. ## Idempotency Set the `Idempotency-Key` request header to any string matching `[A-Za-z0-9_-]{1,255}` to enable safe retries. The response is cached for 24 hours keyed on `(user, idempotency-key)`; replaying the same key with the same body returns the cached response with `Idempotent-Replayed: true`. Reusing the same key with a different body returns 400 to prevent silent corruption. **Authentication:** This endpoint accepts either a Bearer API key or a `SIGN-IN-WITH-X` header for x402 wallet-based authentication. The legacy `X-Sign-In-With-X` header is also accepted during migration. When using x402, a `402 Payment Required` response indicates insufficient balance and includes top-up instructions. operationId: cryptoRpcProxy parameters: - description: >- Venice-side network slug. Call `GET /api/v1/crypto/rpc/networks` for the current list. in: path name: network required: true schema: example: ethereum-mainnet type: string - description: >- Optional idempotency key for safe retries. Pattern: `[A-Za-z0-9_-]{1,255}`. Retrying within 24 hours with the same key + same body replays the cached response with `Idempotent-Replayed: true`. Same key + different body returns 400. in: header name: Idempotency-Key required: false schema: type: string pattern: ^[A-Za-z0-9_-]{1,255}$ example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 requestBody: required: true content: application/json: schema: oneOf: - type: object required: - method properties: jsonrpc: type: string enum: - '2.0' example: '2.0' method: type: string description: >- JSON-RPC method name. See the "Supported methods" section of the endpoint description for the classification into 1×/2×/4× pricing tiers. example: eth_chainId params: type: array items: {} description: >- Method parameters. Shape depends on the method; see the upstream chain documentation. example: [] id: description: >- Caller-supplied request ID echoed back in the response. Required for batch request correlation. oneOf: - type: integer - type: string example: 1 - type: array maxItems: 100 items: type: object required: - method properties: jsonrpc: type: string enum: - '2.0' example: '2.0' method: type: string description: >- JSON-RPC method name. See the "Supported methods" section of the endpoint description for the classification into 1×/2×/4× pricing tiers. example: eth_chainId params: type: array items: {} description: >- Method parameters. Shape depends on the method; see the upstream chain documentation. example: [] id: description: >- Caller-supplied request ID echoed back in the response. Required for batch request correlation. oneOf: - type: integer - type: string example: 1 examples: singleRequest: summary: Single JSON-RPC call value: jsonrpc: '2.0' method: eth_chainId params: [] id: 1 batchRequest: summary: Batch of 2 calls value: - jsonrpc: '2.0' method: eth_chainId params: [] id: 1 - jsonrpc: '2.0' method: eth_blockNumber params: [] id: 2 responses: '200': description: >- JSON-RPC response forwarded from the upstream node. `Content-Type` is forced to `application/json` regardless of upstream headers. headers: X-Balance-Remaining: description: >- Remaining x402 credit balance in USD after this request (only present for x402 auth). required: false schema: type: string example: '4.230000' X-Venice-RPC-Credits: description: >- Credits charged for this request. On batch requests this is the sum across items, with individual RPC-level errors billed at 5 credits instead of the full method tier. schema: type: integer example: 20 X-Venice-RPC-Cost-USD: description: >- Dollar cost charged to the caller for this request, to 8 decimal places. Equal to `X-Venice-RPC-Credits * CRYPTO_RPC_PRICE_PER_CREDIT_USD`. schema: type: string example: '0.00001400' X-Request-ID: description: >- 32-character correlation ID generated by Venice for this request. Include this in any support correspondence. schema: type: string example: aBCdEFghIjKlMnOpQrStUvWxYz012345 Idempotent-Replayed: description: >- Present and set to `"true"` when the response is being served from the idempotency cache rather than freshly forwarded to the upstream. schema: type: string enum: - 'true' content: application/json: schema: oneOf: - type: object properties: jsonrpc: type: string example: '2.0' id: oneOf: - type: integer - type: string result: description: Method-dependent result. Present on success. error: type: object description: >- JSON-RPC error object. Present on per-request failure (HTTP status is still 200 in that case). properties: code: type: integer example: -32602 message: type: string example: invalid params data: {} - type: array items: type: object properties: jsonrpc: type: string example: '2.0' id: oneOf: - type: integer - type: string result: description: Method-dependent result. Present on success. error: type: object description: >- JSON-RPC error object. Present on per-request failure (HTTP status is still 200 in that case). properties: code: type: integer example: -32602 message: type: string example: invalid params data: {} examples: singleSuccess: summary: Single-call success value: jsonrpc: '2.0' id: 1 result: '0x1' batchMixed: summary: Batch with one RPC-level error value: - jsonrpc: '2.0' id: 1 result: '0x1' - jsonrpc: '2.0' id: 2 error: code: -32602 message: invalid params '400': description: >- Invalid request. Examples: unsupported network, empty body, batch > 100, WebSocket-only method, unmapped method, cross-family EVM-on-Starknet call, or `Idempotency-Key` reuse with a different body. content: application/json: schema: $ref: '#/components/schemas/DetailedError' '401': description: >- Missing or invalid API key or x402 wallet signature. The `/crypto/rpc/networks` listing is public, but this proxy endpoint requires authentication. content: application/json: schema: $ref: '#/components/schemas/StandardError' '402': description: >- Insufficient balance. For API key users, top up at venice.ai. For x402 wallet users, the response includes structured top-up instructions and payment requirements per the x402 v2 spec. headers: PAYMENT-REQUIRED: description: >- Base64-encoded JSON with x402 payment requirements. Present on x402 middleware 402 responses. Decode to choose and sign one accepted payment requirement programmatically. required: false schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/StandardError' - $ref: '#/components/schemas/X402InferencePaymentRequired' '429': description: >- Rate limit tripped. Either the per-minute request cap, the per-day credit cap, or a concurrent-call collision on the per-user mutex. The `customMessage` identifies which. headers: X-RateLimit-Limit: description: >- Per-minute request cap for the caller's tier (paid: 100, staff: 1000). Set only when the rate limit is tripped. schema: type: integer example: 100 X-RateLimit-Remaining: description: >- Requests remaining in the current 60-second window. Set only on rate-limit responses. schema: type: integer example: 0 X-RateLimit-Reset: description: >- Unix timestamp (seconds) when the current rate-limit window resets. schema: type: integer example: 1704067260 content: application/json: schema: $ref: '#/components/schemas/StandardError' '500': description: >- Either the upstream fetch failed (network error / timeout) or the service is misconfigured. content: application/json: schema: $ref: '#/components/schemas/StandardError' security: - BearerAuth: [] - siwx: [] components: schemas: DetailedError: type: object properties: details: type: object properties: {} description: Details about the incorrect input example: _errors: [] field: _errors: - Field is required error: type: string description: A description of the error required: - error StandardError: type: object properties: error: type: string description: A description of the error required: - error X402InferencePaymentRequired: anyOf: - type: object properties: x402Version: type: number description: x402 protocol version. example: 2 error: type: string description: Human-readable payment requirement message. example: Payment required resource: type: object properties: url: type: string description: Protected resource URL. example: https://api.venice.ai/api/v1/chat/completions description: type: string description: Human-readable resource description. example: Venice API mimeType: type: string description: Resource MIME type. example: application/json required: - url - description - mimeType additionalProperties: false accepts: type: array items: type: object properties: scheme: type: string enum: - exact description: x402 payment scheme. example: exact network: type: string description: Payment network for this requirement. example: solana asset: type: string description: USDC token address or mint for the selected network. example: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v amount: type: string description: >- Required payment amount in base units (USDC has 6 decimals). example: '10000000' payTo: type: string description: Receiver wallet address for the selected network. example: 8qUL23aSj7mDWdoLMXGHFvnVCT9wd7jXcysiekroADEL maxTimeoutSeconds: type: number description: Maximum time allowed for payment settlement. example: 300 extra: type: object properties: {} description: >- Network-specific x402 metadata. Solana requirements include a feePayer. example: name: USD Coin version: '2' feePayer: BFK9TLC3edb13K6v4YyH3DwPb5DSUpkWvb7XnqCL9b4F required: - scheme - network - asset - amount - payTo - maxTimeoutSeconds - extra additionalProperties: false description: >- Protocol payment requirements. Clients should choose one entry, such as Base or Solana, and sign exactly that requirement. extensions: type: object properties: {} description: >- Protocol extensions. Inference 402 responses include `sign-in-with-x` with a SIWX challenge for wallet-credit authentication. authOptions: type: object properties: apiKey: type: object properties: header: type: string description: API key authentication header format. example: 'Authorization: Bearer YOUR_API_KEY' getKey: type: string description: Where to create or manage API keys. example: https://venice.ai/settings/api docs: type: string description: API key documentation URL. example: https://docs.venice.ai/api-reference required: - header - getKey - docs additionalProperties: false x402Wallet: type: object properties: header: type: string description: Header used for Sign-In-With-X wallet authentication. example: SIGN-IN-WITH-X legacyHeader: type: string description: Legacy Sign-In-With-X header accepted during migration. example: X-Sign-In-With-X topUp: type: string description: >- Endpoint used to discover and submit x402 top-up payments. example: POST /api/v1/x402/top-up docs: type: string description: x402 top-up API documentation URL. example: >- https://docs.venice.ai/api-reference/endpoint/x402/top-up required: - header - legacyHeader - topUp - docs additionalProperties: false required: - apiKey - x402Wallet additionalProperties: false required: - x402Version - resource - accepts - authOptions additionalProperties: false description: >- Returned when an inference request has no API key or wallet authentication. The JSON body includes x402 discovery requirements and authentication options. - type: object properties: error: type: string enum: - Payment required description: Error message indicating payment is required. code: type: string enum: - PAYMENT_REQUIRED description: Machine-readable error code. reason: type: string enum: - insufficient_balance description: Reason the x402-authenticated request could not proceed. message: type: string description: Human-readable context about the payment requirement. example: Insufficient x402 balance currentBalanceUsd: type: number description: Current x402 credit balance for the wallet. example: 0.01 minimumBalanceUsd: type: number description: Minimum x402 credit balance required before the request can run. example: 0.1 description: type: string description: Protected resource description. example: Venice API suggestedTopUpUsd: type: number description: Suggested amount to top up in USD. example: 10 minimumTopUpUsd: type: number description: Minimum allowed top-up amount in USD. example: 5 supportedTokens: type: array items: type: string description: List of supported token symbols for payment. example: - USDC supportedChains: type: array items: type: string description: List of supported top-up rails. example: - base - solana topUpInstructions: type: object properties: step1: type: string description: 'First step: get payment requirements.' example: >- POST /api/v1/x402/top-up with no payment header to get payment requirements step2: type: string description: 'Second step: sign the payment.' example: >- Choose a payment option from accepts and sign a USDC transfer authorization using the x402 SDK (createPaymentHeader) step3: type: string description: 'Third step: submit the payment.' example: >- POST /api/v1/x402/top-up with the signed PAYMENT-SIGNATURE header receiverWallet: type: string description: >- Legacy Base receiver wallet address. Prefer the selected accepts entry from /x402/top-up for network-specific payTo values. example: tokenAddress: type: string description: >- Legacy Base USDC token address. Prefer the selected accepts entry from /x402/top-up for network-specific assets. example: tokenDecimals: type: number description: Token decimal places. example: 6 network: type: string description: >- Legacy Base target network. Prefer the selected accepts entry from /x402/top-up for network-specific values. example: eip155:8453 minimumAmountUsd: type: number description: Minimum top-up amount in USD. example: 5 required: - step1 - step2 - step3 - receiverWallet - tokenAddress - tokenDecimals - network - minimumAmountUsd additionalProperties: false siwxChallenge: type: object properties: info: type: object properties: domain: type: string description: Domain for the SIWX challenge. example: api.venice.ai uri: type: string description: Resource URI for the challenge. example: https://api.venice.ai/api/v1/chat/completions version: type: string description: SIWX version. example: '1' nonce: type: string description: Unique nonce for replay protection. example: '{{nonce}}' issuedAt: type: string description: ISO timestamp when the challenge was issued. example: '2026-04-09T12:00:00.000Z' expirationTime: type: string description: ISO timestamp when the challenge expires. example: '2026-04-09T12:05:00.000Z' statement: type: string description: Human-readable statement for the signature. example: Sign in to Venice AI required: - domain - uri - version - nonce - issuedAt - expirationTime - statement additionalProperties: false supportedChains: type: array items: type: object properties: chainId: type: string description: Supported chain identity. example: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp type: type: string enum: - eip191 - eip1271 - ed25519 description: Signature type accepted for this chain. example: ed25519 required: - chainId - type additionalProperties: false description: Supported SIWX chains and signature types. required: - info - supportedChains additionalProperties: false required: - error - code - reason - suggestedTopUpUsd - minimumTopUpUsd - supportedTokens - supportedChains - topUpInstructions - siwxChallenge additionalProperties: false securitySchemes: BearerAuth: bearerFormat: JWT scheme: bearer type: http siwx: description: >- Wallet-based authentication using the x402 protocol (Sign-In-With-X). Supports EVM SIWE signatures on Base and Ed25519 signatures on Solana mainnet. **Header format:** Base64-encoded JSON object with the following fields: - `address` — EVM or Solana wallet address - `message` — Signed SIWX message. EVM wallets use EIP-4361 SIWE; Solana wallets use the Solana SIWX message format. - `signature` — Signature of the message, signed by the wallet's private key. EVM signatures are hex; Solana signatures may be base58 or base64. - `timestamp` — Unix timestamp in milliseconds - `chainId` — Chain identity. Use `8453`, `"8453"`, or `"eip155:8453"` for Base; use `"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"` for Solana. - `type` — Optional signature type. Use `"ed25519"` for Solana. Omitted means EVM/EIP-191 for backward compatibility. **EVM SIWE message fields:** - `domain`: `api.venice.ai` - `uri`: `https://api.venice.ai` - `version`: `"1"` - `chainId`: `8453` - `nonce`: Random 16-character hex string - `issuedAt` / `expirationTime`: ISO timestamps (recommended TTL: 10 minutes) - `statement`: `"Sign in to Venice API"` **Example (TypeScript):** ``` import { Wallet } from 'ethers' import { SiweMessage } from 'siwe' const wallet = new Wallet(PRIVATE_KEY) const msg = new SiweMessage({ domain: 'api.venice.ai', address: wallet.address, statement: 'Sign in to Venice API', 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() + 600000).toISOString() }) const signature = await wallet.signMessage(msg.prepareMessage()) const header = btoa(JSON.stringify({ address: wallet.address, message: msg.prepareMessage(), signature, timestamp: Date.now(), chainId: 8453 })) // Set header: SIGN-IN-WITH-X:
``` **Solana message fields:** The signed message starts with ` wants you to sign in with your Solana account:`, followed by the wallet address and the standard `URI`, `Version`, `Chain ID`, `Nonce`, `Issued At`, and optional `Expiration Time` fields. Use `type: "ed25519"` and `chainId: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"` in the encoded JSON payload. **SDK:** `npm install @venice-ai/x402-client` provides `VeniceClient` and `createAuthFetch` which handle this automatically. **Billing:** x402 users pay from a prepaid USDC credit balance. Top up via `POST /x402/top-up`. When balance is insufficient, endpoints return `402` with structured top-up instructions. in: header name: SIGN-IN-WITH-X type: apiKey ````