> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# X402
> Accede a la API de Venice sin clave de API pagando por solicitud con el protocolo x402 y autenticándote con un monedero cripto en Base.
X402 te permite usar las rutas de pago de la API de Venice autenticándote con un monedero y manteniendo un saldo USDC prepago. No se requiere API key ni cuenta. Firma un mensaje, recarga en Base o Solana y llama a cualquier ruta admitida.
Autentica con un payload Sign-In-With-X firmado en la cabecera `X-Sign-In-With-X`.
Mantén saldo gastable con USDC en Base o Solana.
Si el monedero está vinculado a una cuenta de Venice con saldo DIEM, ese se gasta primero.
## ¿Qué es X402?
[X402](https://www.x402.org/) es un estándar abierto de pago que permite a aplicaciones y agentes pagar por servicios de forma programática usando criptomonedas. Venice implementa X402 para que los monederos puedan autenticarse y pagar la inferencia directamente con USDC en Base o Solana.
## Requisitos previos
* Un monedero en Base o Solana
* Token nativo para gas en la cadena seleccionada, como ETH en Base o SOL en Solana
* USDC en la cadena seleccionada (o saldo respaldado por DIEM existente de una cuenta de Venice vinculada)
Considera usar un monedero dedicado para automatización en lugar de tu monedero principal de tesorería.
## Inicio rápido
El SDK [`venice-x402-client`](https://github.com/veniceai/x402-client) ofrece helpers para auth de monedero, recargas y seguimiento de saldo.
```bash theme={"system"}
npm install venice-x402-client
```
```typescript theme={"system"}
import { VeniceClient } from 'venice-x402-client'
const venice = new VeniceClient(process.env.WALLET_KEY)
await venice.topUp(10) // sáltatelo si el monedero ya tiene saldo gastable
const response = await venice.chat({
model: 'kimi-k2-5',
messages: [{ role: 'user', content: 'Hello!' }]
})
```
El cliente genera una cabecera `X-Sign-In-With-X` nueva para cada solicitud y rastrea automáticamente el saldo desde las cabeceras de respuesta `X-Balance-Remaining`.
### Con herramientas compatibles con OpenAI
Si usas una herramienta que acepta un `fetch` personalizado, usa `createAuthFetch` para añadir auth de monedero a cualquier solicitud:
```typescript theme={"system"}
import { createAuthFetch } from 'venice-x402-client'
const authFetch = createAuthFetch(process.env.WALLET_KEY)
```
### Helpers disponibles
El SDK incluye helpers de primera clase para las rutas más comunes de Venice x402. Para cualquier cosa no cubierta, usa `request()` o `createAuthFetch()` directamente.
| Categoría | Métodos |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Chat | `chat()`, `chatStream()` |
| Responses | `responses.create()`, `responses.stream()` |
| Images | `images.generate()`, `images.generations()`, `images.upscale()`, `images.edit()`, `images.multiEdit()`, `images.backgroundRemove()` |
| Audio | `audio.speech()`, `audio.transcribe()`, `audio.queue()`, `audio.retrieve()`, `audio.complete()` |
| Video | `video.queue()`, `video.retrieve()`, `video.generate()`, `video.complete()`, `video.transcribe()` |
| Embeddings | `embeddings()` |
| Models | `models()` |
| Wallet | `getBalance()`, `getTransactions()`, `topUp()` |
***
## Flujo manual
Si no estás usando el SDK o necesitas entender el protocolo subyacente, este es el flujo paso a paso. Para un monedero nuevo, asume que necesitas recargar primero salvo que ya tenga saldo DIEM gastable.
### Paso 1: crea la cabecera X-Sign-In-With-X
Venice espera un payload JSON codificado en Base64 que contenga un mensaje Sign-In-With-X firmado. Los monederos EVM firman un mensaje SIWE EIP-4361 en Base. Los monederos Solana firman el mensaje SIWX de Solana con Ed25519. Genera un nonce y timestamp nuevos para cada flujo de solicitud.
Para Solana, establece `chainId` en `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`, incluye `type: "ed25519"` en el payload JSON codificado y proporciona la firma Ed25519 como base58 o base64. El mensaje firmado comienza con ` wants you to sign in with your Solana account:`, seguido de la dirección del monedero y los campos estándar `URI`, `Version`, `Chain ID`, `Nonce`, `Issued At` y el opcional `Expiration Time`.
```typescript theme={"system"}
import { Wallet } from 'ethers'
import { SiweMessage, generateNonce } from 'siwe'
const wallet = new Wallet(process.env.EVM_PRIVATE_KEY)
const now = new Date()
const resourceUrl = 'https://api.venice.ai/api/v1/chat/completions'
const siwe = new SiweMessage({
domain: 'api.venice.ai',
address: wallet.address,
statement: 'Sign in to Venice AI',
uri: resourceUrl,
version: '1',
chainId: 8453,
nonce: generateNonce(),
issuedAt: now.toISOString(),
expirationTime: new Date(now.getTime() + 5 * 60 * 1000).toISOString(),
})
const message = siwe.prepareMessage()
const signature = await wallet.signMessage(message)
const xSignInWithX = Buffer.from(
JSON.stringify({
address: wallet.address,
message,
signature,
timestamp: now.getTime(),
chainId: 8453,
}),
'utf8',
).toString('base64')
console.log(xSignInWithX)
```
### Paso 2: comprueba el saldo
Antes de hacer una solicitud de pago, verifica que el monedero tenga saldo gastable:
```bash theme={"system"}
export WALLET_ADDRESS=0xYOUR_WALLET_ADDRESS_OR_SOLANA_ADDRESS
export X402_AUTH=YOUR_BASE64_SIWX_HEADER
curl --request GET \
--url "https://api.venice.ai/api/v1/x402/balance/$WALLET_ADDRESS" \
--header "X-Sign-In-With-X: $X402_AUTH"
```
La respuesta incluye:
* `canConsume`: si el monedero puede realizar solicitudes de pago
* `balanceUsd`: saldo gastable actual
* `minimumTopUpUsd` y `suggestedTopUpUsd`: orientación para recargas
* `diemBalanceUsd`: saldo respaldado por DIEM, si lo hay
El parámetro de ruta `walletAddress` acepta una dirección EVM (`0x...`) o una dirección base58 de Solana.
### Paso 3: recarga
Recarga con USDC en Base o Solana:
```bash theme={"system"}
curl --request POST \
--url https://api.venice.ai/api/v1/x402/top-up
```
La primera llamada devuelve `402 Payment Required` con una cabecera `PAYMENT-REQUIRED` que contiene un array `accepts`. Cada entrada describe una opción de pago aceptada, incluyendo `network`, `asset`, `payTo` y `amount`. Elige la opción de Base o Solana con la que quieras pagar, usa esos detalles exactos para construir una cabecera `X-402-Payment` y reintenta la misma ruta.
#### Construyendo la cabecera X-402-Payment para Base
El siguiente script crea un pago x402 firmado en Base y envía la solicitud de recarga. Requiere los paquetes npm `x402` y `viem`.
```bash theme={"system"}
export EVM_PRIVATE_KEY=0xYOUR_PRIVATE_KEY
```
```bash theme={"system"}
export X402_PAYMENT="$(
node --input-type=module <<'EOF'
import { createPaymentHeader } from "x402/client";
import { privateKeyToAccount } from "viem/accounts";
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY);
const amountUsd = 5;
const amountBaseUnits = String(Math.round(amountUsd * 1e6));
const header = await createPaymentHeader(signer, 2, {
scheme: "exact",
network: "base",
maxAmountRequired: amountBaseUnits,
resource: "https://api.venice.ai/api/v1/x402/top-up",
description: "Venice x402 top-up",
mimeType: "application/json",
payTo: "0x2670B922ef37C7Df47158725C0CC407b5382293F",
maxTimeoutSeconds: 300,
asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
extra: { name: "USD Coin", version: "2" },
});
process.stdout.write(header);
EOF
)"
curl -X POST "https://api.venice.ai/api/v1/x402/top-up" \
-H "X-402-Payment: $X402_PAYMENT"
```
Usa en producción la última respuesta `PAYMENT-REQUIRED` / `accepts` como fuente de verdad en lugar de hardcodear estos valores. Para recargas en Solana, construye el pago a partir de la entrada de Solana devuelta en `accepts`. Las entradas de Solana usan `network: "solana"`, el mint de USDC como `asset` y pueden incluir metadatos específicos de la red como `extra.feePayer`.
### Paso 4: haz una solicitud
Una vez que el monedero tenga saldo gastable, llama a cualquier endpoint admitido con la cabecera `X-Sign-In-With-X`:
```bash theme={"system"}
export X402_AUTH=YOUR_BASE64_SIWX_HEADER
curl --request POST \
--url https://api.venice.ai/api/v1/chat/completions \
--header "Content-Type: application/json" \
--header "X-Sign-In-With-X: $X402_AUTH" \
--data '{
"model": "kimi-k2-5",
"messages": [
{
"role": "user",
"content": "Hello from an x402-authenticated wallet."
}
]
}'
```
Las respuestas exitosas pueden incluir una cabecera `X-Balance-Remaining`.
### Paso 5: inspecciona transacciones (opcional)
Revisa el historial de transacciones del monedero:
```bash theme={"system"}
export WALLET_ADDRESS=0xYOUR_WALLET_ADDRESS_OR_SOLANA_ADDRESS
export X402_AUTH=YOUR_BASE64_SIWX_HEADER
curl --request GET \
--url "https://api.venice.ai/api/v1/x402/transactions/$WALLET_ADDRESS?limit=10&offset=0" \
--header "X-Sign-In-With-X: $X402_AUTH"
```
El libro mayor incluye entradas como `TOP_UP`, `CHARGE` y `REFUND`.
El parámetro de ruta `walletAddress` acepta una dirección EVM (`0x...`) o una dirección base58 de Solana.
***
## Rutas admitidas
### Rutas de pago de inferencia
Las siguientes rutas de pago públicas de Venice admiten actualmente la autenticación con monedero x402.
| Categoría | Endpoints |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Chat | `POST /api/v1/chat/completions`, `POST /api/v1/responses` |
| Imagen | `POST /api/v1/image/generate`, `POST /api/v1/images/generations`, `POST /api/v1/image/upscale`, `POST /api/v1/image/edit`, `POST /api/v1/image/multi-edit`, `POST /api/v1/image/background-remove` |
| Embeddings | `POST /api/v1/embeddings` |
| Audio | `POST /api/v1/audio/speech`, `POST /api/v1/audio/transcriptions`, `POST /api/v1/audio/complete`, `POST /api/v1/audio/queue`, `POST /api/v1/audio/retrieve` |
| Vídeo | `POST /api/v1/video/complete`, `POST /api/v1/video/queue`, `POST /api/v1/video/retrieve`, `POST /api/v1/video/transcriptions` |
### Ruta de recarga
| Endpoint | Auth | Propósito |
| -------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `POST /api/v1/x402/top-up` | Solicitud inicial: ninguna. Reintento: `X-402-Payment` | Añade créditos USDC al saldo gastable del monedero usando una opción de pago admitida en Base o Solana |
### Rutas solo de monedero
Estas rutas usan `X-Sign-In-With-X` para identidad, pero no cargan saldo.
| Endpoint | Propósito |
| ----------------------------------------------- | --------------------------------------------------------------------------------- |
| `GET /api/v1/x402/balance/{walletAddress}` | Comprueba el saldo gastable de una dirección de monedero EVM o Solana |
| `GET /api/v1/x402/transactions/{walletAddress}` | Visualiza el historial de transacciones de una dirección de monedero EVM o Solana |
***
## Errores
| Estado | Causa probable | Qué hacer |
| ------------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `401` | Payload Sign-In-With-X mal formado o expirado | Reconstruye `X-Sign-In-With-X` con nonce y timestamp nuevos |
| `402` en una ruta de pago | Saldo gastable insuficiente | Recarga y reintenta |
| `402` en `/x402/top-up` | Esperado. Es el flujo de inicio de pago. | Usa los detalles de pago devueltos para construir `X-402-Payment` y reintenta |
| `403` en saldo o transacciones | Discrepancia de monedero | Asegúrate de que el monedero autenticado coincida con el parámetro de ruta `walletAddress` |
| `400` en recarga | Cabecera de pago mal formada | Reconstruye a partir de la última respuesta `402` |
***
## Para agentes
El flujo es el mismo. Guarda las claves privadas en variables de entorno o un gestor de secretos y comprueba el saldo antes de las solicitudes para evitar round-trips `402` innecesarios.
***
## Recursos relacionados
Cliente oficial de Venice x402 para Node.js/TypeScript.
Consulta los precios de los modelos y cómo Venice cobra el uso.
Una ruta de pago común para acceso basado en monedero.
Documentación de referencia y acceso al spec sin procesar.