> ## 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 Key**: `Authorization: Bearer ` 헤더를 통한 표준 Bearer 토큰 인증. * **x402 Wallet**: Base 또는 Solana의 지갑에서 USDC 크레딧으로 종량제 결제. Venice 계정이 필요하지 않습니다. 설정은 [x402 가이드](/guides/integrations/x402-venice-api)를 참조하세요. 두 방법 모두 동일한 속도 제한과 청구(Venice 크레딧)를 공유합니다. ## 지원되는 네트워크 실시간 권위 목록은 [`GET /crypto/rpc/networks`](/api-reference/endpoint/crypto/networks)를 참조하세요. 현재 커버리지: | Family | 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 methods (`eth_sendUserOperation`, `eth_estimateUserOperationGas`, etc.), chain-family extensions (`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 | Chains | | ----------- | --------------------------------------------------------------------------------------------------- | | **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 | 제한을 초과하면 엔드포인트는 `customMessage` 및 표준 `X-RateLimit-*` 응답 헤더와 함께 `429`를 반환합니다. ## 멱등성 안전한 재시도를 활성화하려면 `Idempotency-Key` 요청 헤더를 `[A-Za-z0-9_-]{1,255}`와 일치하는 문자열로 설정하세요. 응답은 `(user, idempotency-key)`를 키로 24시간 동안 캐시됩니다: * 동일한 본문과 함께 **동일한 키를 재생**하면 캐시된 응답과 `Idempotent-Replayed: true` 응답 헤더가 반환됩니다. 업스트림은 건드리지 않으며 새 크레딧이 청구되지 않습니다. * 다른 본문과 함께 **동일한 키를 재생**하면 무음 상태 손상을 방지하기 위해 `400`을 반환합니다. 별개의 요청에는 새 키를 선택하세요. ## 응답 헤더 | Header | Description | | ------------------------------------------------------------------- | ---------------------------------------------------------- | | `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 해시(원시 바이트의 keccak256), 네트워크 슬러그, 요청 ID 및 호출 사용자 ID와 함께 서버 측에 기록됩니다. 서명된 페이로드 자체는 보존하지 **않습니다** — 해시는 온체인 영수증에서 복구할 수 있습니다. 이 감사 추적은 고객의 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 컬렉션 27개의 예제 요청(검색, 표준/고급/대규모 호출, 다중 체인, 배치, 멱등성, 오류 사례)이 포함된 즉시 가져올 수 있는 Postman 컬렉션이 공개 워크스페이스에서 제공됩니다: **[Venice Crypto RPC — Postman Collection](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 ````