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.

Auth con monedero

Autentica con un payload Sign-In-With-X firmado en la cabecera X-Sign-In-With-X.

Paga con USDC

Mantén saldo gastable con USDC en Base o Solana.

DIEM primero

Si el monedero está vinculado a una cuenta de Venice con saldo DIEM, ese se gasta primero.

​

¿Qué es X402?

X402 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 ofrece helpers para auth de monedero, recargas y seguimiento de saldo.

npm install venice-x402-client

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:

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 <domain> 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.

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:

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:

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.

export EVM_PRIVATE_KEY=0xYOUR_PRIVATE_KEY

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:

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:

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

SDK del cliente x402

Cliente oficial de Venice x402 para Node.js/TypeScript.

Precios de la API

Consulta los precios de los modelos y cómo Venice cobra el uso.

Chat Completions

Una ruta de pago común para acceso basado en monedero.

Spec de la API

Documentación de referencia y acceso al spec sin procesar.