> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-docs-responses-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Responses
> **Alpha** - This endpoint is currently available to Alpha testers only.
Creates a model response using the Responses API format. This is an OpenAI-compatible endpoint for Venice text models.
**E2EE Model Limitation** - E2EE-capable models are not supported on `/api/v1/responses`. Use `/api/v1/chat/completions` with the required E2EE headers instead.
**Stateless Only** - This API is stateless. Each request is independent and no conversation state is persisted between requests. You must include the full conversation history in each request.
The Responses API provides a structured output format with typed blocks for:
- **Reasoning**: Thought process and reasoning chains from reasoning models
- **Messages**: The main text response from the model
- **Function Calls**: Tool/function call outputs
- **Web Search**: Results from web search if enabled
This endpoint supports streaming via Server-Sent Events when `stream: true` is set.
**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.
**Beta endpoint**, available to all API users. Venice translates Responses requests through [Chat Completions](/api-reference/endpoint/chat/completions), so some Responses features are ignored today: `instructions`, `text.format`, `previous_response_id`, reasoning replay, and provider-hosted tools. The Venice system prompt is also on by default here. See the [Responses API guide](/guides/features/responses-api#limitations) for the full list and workarounds.
## OpenAPI
````yaml POST /responses
openapi: 3.0.0
info:
description: The Venice.ai API.
termsOfService: https://venice.ai/legal/tos
title: Venice.ai API
version: '20260918.184256'
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: >-
Create vector embeddings from text. `input` must be a string or an array
of strings. Token arrays are not supported. LangChain OpenAIEmbeddings
must set `check_embedding_ctx_length=False` to send text instead of
tiktoken IDs.
name: Embeddings
- description: >-
Evaluate a state against typed questions and get structured answers
(yes/no probabilities, option picks with distributions, rubric scores).
**Beta**: This API is currently in beta and may be unstable.
Request/response schemas and behavior may change without notice.
name: Decisions
- 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:
/responses:
post:
tags:
- Responses (Alpha)
summary: Create a response (Alpha)
description: >-
**Alpha** - This endpoint is currently available to Alpha testers only.
Creates a model response using the Responses API format. This is an
OpenAI-compatible endpoint for Venice text models.
**E2EE Model Limitation** - E2EE-capable models are not supported on
`/api/v1/responses`. Use `/api/v1/chat/completions` with the required
E2EE headers instead.
**Stateless Only** - This API is stateless. Each request is independent
and no conversation state is persisted between requests. You must
include the full conversation history in each request.
The Responses API provides a structured output format with typed blocks
for:
- **Reasoning**: Thought process and reasoning chains from reasoning
models
- **Messages**: The main text response from the model
- **Function Calls**: Tool/function call outputs
- **Web Search**: Results from web search if enabled
This endpoint supports streaming via Server-Sent Events when `stream:
true` is set.
**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: createResponse
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ResponsesRequest'
responses:
'200':
description: Successful response
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'
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Unique identifier for the response.
example: resp_abc123
object:
type: string
enum:
- response
description: The object type.
created_at:
type: integer
description: Unix timestamp of when the response was created.
model:
type: string
description: The model used for the response.
status:
type: string
enum:
- completed
- failed
- in_progress
- cancelled
- incomplete
description: The status of the response.
incomplete_details:
type: object
properties:
reason:
type: string
enum:
- max_output_tokens
- content_filter
required:
- reason
description: >-
Why generation ended before completion; partial output and
usage are retained.
output:
type: array
items:
anyOf:
- type: object
properties:
type:
type: string
enum:
- reasoning
id:
type: string
summary:
type: array
items:
type: string
encrypted_content:
type: string
required:
- type
- id
title: Reasoning Output
- type: object
properties:
type:
type: string
enum:
- message
id:
type: string
status:
type: string
enum:
- completed
- in_progress
- failed
- incomplete
role:
type: string
enum:
- assistant
content:
type: array
items:
type: object
properties:
type:
type: string
enum:
- output_text
text:
type: string
annotations:
type: array
items:
type: object
properties:
type:
type: string
enum:
- url_citation
url:
type: string
title:
type: string
start_index:
type: integer
end_index:
type: integer
required:
- type
- url
- start_index
- end_index
title: URL Citation Annotation
required:
- type
- text
title: Output Text
required:
- type
- id
- status
- role
- content
title: Message Output
- type: object
properties:
type:
type: string
enum:
- function_call
id:
type: string
call_id:
type: string
name:
type: string
arguments:
type: string
status:
type: string
enum:
- completed
- in_progress
- incomplete
required:
- type
- id
- call_id
- name
- arguments
- status
title: Function Call Output
- type: object
properties:
type:
type: string
enum:
- web_search_call
id:
type: string
status:
type: string
enum:
- completed
required:
- type
- id
- status
title: Web Search Call Output
description: The output items generated by the model.
usage:
type: object
properties:
input_tokens:
type: integer
input_tokens_details:
type: object
properties:
cached_tokens:
type: integer
output_tokens:
type: integer
output_tokens_details:
type: object
properties:
reasoning_tokens:
type: integer
total_tokens:
type: integer
required:
- input_tokens
- output_tokens
- total_tokens
description: Token usage statistics.
title: Usage
error:
type: object
properties:
code:
type: string
message:
type: string
required:
- code
- message
description: Error information if the response failed.
title: Error
required:
- id
- object
- created_at
- model
- status
- output
description: Response from the Responses API endpoint.
title: Responses API Response
'400':
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/DetailedError'
'401':
description: |-
- Authentication failed
- This model is only available to Pro users
content:
application/json:
schema:
$ref: '#/components/schemas/StandardError'
'402':
description: >-
Payment or balance required. Response varies by authentication
state:
**API Key users:** Standard error response with
`INSUFFICIENT_BALANCE` code. Top up your Venice balance at
venice.ai.
**Unauthenticated x402 discovery:** Structured x402 response with
`x402Version`, `resource`, `accepts`, and
`extensions["sign-in-with-x"]`. The `accepts` array advertises Base
and Solana payment requirements.
**Authenticated x402 wallet users with insufficient credit:**
Structured response with `PAYMENT_REQUIRED` code containing:
- `topUpInstructions`: Step-by-step guide to top up via x402
protocol
- `supportedTokens` / `supportedChains`: Accepted payment methods
- `siwxChallenge`: Fresh Sign-In-With-X challenge metadata
The `PAYMENT-REQUIRED` header also contains a base64-encoded x402
protocol object with the payment requirements for programmatic
discovery.
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 exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/StandardError'
'500':
description: Inference processing failed
content:
application/json:
schema:
$ref: '#/components/schemas/StandardError'
security:
- BearerAuth: []
- siwx: []
components:
schemas:
ResponsesRequest:
type: object
properties:
model:
type: string
description: >-
The ID of the model to use. E2EE-capable models are not supported on
/api/v1/responses; use /api/v1/chat/completions with the required
E2EE headers instead.
example: zai-org-glm-5-1
input:
anyOf:
- type: string
- type: array
items:
anyOf:
- type: object
properties:
type:
type: string
enum:
- message
role:
type: string
enum:
- user
- assistant
- system
- developer
content:
anyOf:
- type: string
- type: array
items:
oneOf:
- type: object
properties:
type:
type: string
enum:
- input_text
text:
type: string
required:
- type
- text
title: Input Text
- type: object
properties:
type:
type: string
enum:
- input_image
image_url:
anyOf:
- type: string
- type: object
properties:
url:
type: string
detail:
type: string
enum:
- auto
- low
- high
required:
- url
detail:
type: string
enum:
- auto
- low
- high
required:
- type
- image_url
title: Input Image
- type: object
properties:
type:
type: string
enum:
- output_text
text:
type: string
annotations:
type: array
items:
nullable: true
required:
- type
- text
title: Output Text (for history)
id:
type: string
status:
type: string
enum:
- completed
- in_progress
- incomplete
required:
- type
- role
- content
title: Input Message
- type: object
properties:
role:
type: string
enum:
- user
- assistant
- system
- developer
content:
anyOf:
- type: string
- type: array
items:
anyOf:
- oneOf:
- type: object
properties:
type:
type: string
enum:
- input_text
text:
type: string
required:
- type
- text
title: Input Text
- type: object
properties:
type:
type: string
enum:
- input_image
image_url:
anyOf:
- type: string
- type: object
properties:
url:
type: string
detail:
type: string
enum:
- auto
- low
- high
required:
- url
detail:
type: string
enum:
- auto
- low
- high
required:
- type
- image_url
title: Input Image
- type: object
properties:
type:
type: string
enum:
- output_text
text:
type: string
annotations:
type: array
items:
nullable: true
required:
- type
- text
title: Output Text (for history)
- type: object
properties:
type:
type: string
enum:
- text
text:
type: string
required:
- type
- text
- type: object
properties:
type:
type: string
enum:
- image_url
image_url:
anyOf:
- type: string
- type: object
properties:
url:
type: string
detail:
type: string
enum:
- auto
- low
- high
required:
- url
required:
- type
- image_url
id:
type: string
status:
type: string
enum:
- completed
- in_progress
- incomplete
required:
- role
- content
title: Input Message (Flexible)
- type: object
properties:
type:
type: string
enum:
- reasoning
id:
type: string
nullable: true
summary:
type: array
nullable: true
items:
type: string
content:
anyOf:
- type: string
- type: array
items:
nullable: true
- nullable: true
title: 'null'
- nullable: true
title: 'null'
encrypted_content:
type: string
nullable: true
status:
type: string
nullable: true
enum:
- completed
- in_progress
required:
- type
title: Reasoning
- type: object
properties:
type:
type: string
enum:
- function_call
id:
type: string
call_id:
type: string
name:
type: string
arguments:
type: string
status:
type: string
enum:
- completed
- in_progress
- incomplete
required:
- type
- call_id
- name
- arguments
title: Function Call
- type: object
properties:
type:
type: string
enum:
- function_call_output
call_id:
type: string
output:
anyOf:
- type: string
- type: array
items:
nullable: true
- type: object
additionalProperties:
nullable: true
- type: number
- type: boolean
- nullable: true
title: 'null'
- nullable: true
title: 'null'
required:
- type
- call_id
- output
title: Function Call Output
- type: object
properties:
type:
type: string
enum:
- item_reference
id:
type: string
required:
- type
- id
title: Item Reference
description: >-
The input to generate a response for. Can be a simple string or an
array of messages.
include:
type: array
items:
type: string
description: Additional response fields to include (OpenAI-compatible).
max_output_tokens:
type: integer
minimum: 0
exclusiveMinimum: true
description: Maximum number of tokens to generate.
temperature:
type: number
minimum: 0
maximum: 2
description: Sampling temperature between 0 and 2.
top_p:
type: number
minimum: 0
maximum: 1
description: Nucleus sampling parameter.
fallbacks:
type: array
items:
type: object
properties:
model:
type: string
required:
- model
maxItems: 10
description: >-
Anthropic beta parameter for Claude Fable 5 server-side refusal
fallback. Forwarded only for direct Anthropic routes; ignored for
other providers.
example:
- model: claude-opus-4-8
reasoning:
type: object
nullable: true
properties:
effort:
type: string
enum:
- none
- minimal
- low
- medium
- high
- xhigh
- max
description: Controls reasoning effort level for supported models.
enabled:
type: boolean
description: >-
Set to false to disable reasoning on supported models. Ignored
when an effort level is provided.
summary:
type: string
enum:
- auto
- concise
- detailed
description: Controls reasoning summary format.
title: Reasoning Configuration
tools:
type: array
items:
anyOf:
- type: object
properties:
type:
type: string
enum:
- function
function:
type: object
properties:
name:
type: string
description:
type: string
parameters:
type: object
additionalProperties:
nullable: true
strict:
type: boolean
required:
- name
required:
- type
- function
title: Function Tool
- type: object
properties:
type:
type: string
enum:
- web_search
search_context_size:
type: string
enum:
- low
- medium
- high
user_location:
type: object
properties:
type:
type: string
enum:
- approximate
city:
type: string
region:
type: string
country:
type: string
timezone:
type: string
required:
- type
title: Web Search Tool
- type: object
properties:
type:
type: string
enum:
- x_search
allowed_x_handles:
type: array
items:
type: string
maxItems: 10
excluded_x_handles:
type: array
items:
type: string
maxItems: 10
from_date:
type: string
to_date:
type: string
enable_image_understanding:
type: boolean
enable_video_understanding:
type: boolean
required:
- type
title: X Search Tool
- type: object
properties:
type:
type: string
enum:
- code_interpreter
container:
type: object
properties:
image:
type: string
required:
- type
title: Code Interpreter Tool
- type: object
properties:
type:
type: string
enum:
- file_search
vector_store_ids:
type: array
items:
type: string
max_num_results:
type: integer
ranking_options:
type: object
properties:
ranker:
type: string
score_threshold:
type: number
required:
- type
title: File Search Tool
- type: object
properties:
type:
type: string
enum:
- computer_use_preview
display_width:
type: integer
display_height:
type: integer
environment:
type: string
required:
- type
title: Computer Use Tool
- type: object
properties:
type:
type: string
required:
- type
title: Generic Tool
title: Tool Definition
description: A list of tools the model may call.
tool_choice:
anyOf:
- type: string
enum:
- auto
- type: string
enum:
- none
- type: string
enum:
- required
- type: object
properties:
type:
type: string
enum:
- function
function:
type: object
properties:
name:
type: string
required:
- name
required:
- type
- function
description: Controls which tool is called by the model.
web_search:
type: boolean
description: Enable web search for this request.
stream:
type: boolean
description: Whether to stream back partial progress.
anon_user_id:
type: string
minLength: 1
maxLength: 128
pattern: ^[\x20-\x7E]+$
description: >-
Optional identifier for the API customer's end user. Combined with
the Venice user id when attributing the request to upstream
providers. Distinct from the discarded OpenAI `user` field. Must be
printable ASCII and must not contain `||`.
example: end-user-123
venice_parameters:
type: object
properties:
character_slug:
type: string
description: The character slug of a public Venice character.
enable_e2ee:
type: boolean
description: >-
Enable end-to-end encryption for E2EE-capable models. When true
(default), E2EE is used if headers are present. When false,
TEE-only mode is used.
enable_web_search:
type: string
enum:
- auto
- 'off'
- 'on'
description: Enable web search for this request.
enable_web_scraping:
type: boolean
description: Enable Venice web scraping of URLs in the latest user message.
enable_web_citations:
type: boolean
description: Request that the LLM cite its sources.
include_venice_system_prompt:
type: boolean
description: Whether to include the Venice supplied system prompts.
include_search_results_in_stream:
type: boolean
description: Include search results in the stream as the first emitted chunk.
title: Venice Parameters
required:
- model
- input
description: >-
Request body for the Responses API endpoint. E2EE-capable models are not
supported on /api/v1/responses; use /api/v1/chat/completions with the
required E2EE headers instead.
title: Responses API Request
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
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.