X402

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 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 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()`
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. Venice espera una prueba sign-in-with-x de x402 en la cabecera SIGN-IN-WITH-X: JSON codificado en Base64 con los campos del mensaje firmado (domain, address, uri, version, chainId, type, nonce, issuedAt y los opcionales expirationTime, notBefore, statement y resources) más la signature. Venice reconstruye el mensaje firmado a partir de esos campos. Las billeteras EVM firman un mensaje SIWE EIP-4361 en Base y establecen type en eip191, incluidas las billeteras de contrato inteligente. Las billeteras Solana firman el mensaje de inicio de sesión de Solana con Ed25519. En el JSON, chainId es el identificador CAIP-2 (eip155:8453), mientras que la línea Chain ID del mensaje firmado lleva la referencia sin prefijo (8453). El nombre de cabecera heredado X-Sign-In-With-X todavía se acepta, al igual que los payloads antiguos que envían el message firmado en sí. Cada mensaje firmado solo se puede usar una vez. Firma un mensaje nuevo con un nonce nuevo para cada solicitud, ya sea uno propio o el nonce del último desafío 402, y envíalo en un plazo de 5 minutos desde su hora issuedAt. Reutilizar un mensaje devuelve 401 (nonce ya usado), igual que un mensaje emitido hace más de 5 minutos. 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)

async function createSiwxHeader(resourceUrl: string): Promise<string> {
  const now = new Date()
  const fields = {
    domain: 'api.venice.ai',
    address: wallet.address,
    statement: 'Sign in to Venice AI',
    uri: resourceUrl,
    version: '1',
    nonce: generateNonce(),
    issuedAt: now.toISOString(),
    expirationTime: new Date(now.getTime() + 5 * 60 * 1000).toISOString(),
  }

  const message = new SiweMessage({ ...fields, chainId: 8453 }).prepareMessage()
  const signature = await wallet.signMessage(message)

  return Buffer.from(JSON.stringify({ ...fields, chainId: 'eip155:8453', type: 'eip191', signature }), 'utf8').toString('base64')
}

const response = await fetch('https://api.venice.ai/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'SIGN-IN-WITH-X': await createSiwxHeader('https://api.venice.ai/api/v1/chat/completions'),
  },
  body: JSON.stringify({
    model: 'kimi-k2-5',
    messages: [{ role: 'user', content: 'Hello!' }],
  }),
})

Llama a createSiwxHeader() inmediatamente antes de cada solicitud. En los ejemplos de curl siguientes, X402_AUTH debe ser una cabecera recién firmada para cada llamada.

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 "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 PAYMENT-SIGNATURE y reintenta la misma ruta. Los nombres de cabecera heredados X-402-Payment y X-PAYMENT se siguen aceptando.

Enviar USDC directamente a una dirección payTo no recarga tu saldo. El crédito solo se añade cuando un PAYMENT-SIGNATURE firmado se liquida a través de POST /x402/top-up. Solo se admiten Base y Solana, por lo que los USDC enviados en cualquier otra cadena, incluida la mainnet de Ethereum, no se acreditan. Las rutas de saldo y transacciones leen el registro contable de Venice y no la cadena, así que después de una transferencia simple no muestran nada.

Construyendo la cabecera PAYMENT-SIGNATURE 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 "PAYMENT-SIGNATURE: $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 una cabecera SIGN-IN-WITH-X recién firmada:

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 "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 "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/voices`, `POST /api/v1/audio/complete`, `POST /api/v1/audio/queue`, `POST /api/v1/audio/retrieve`, `POST /api/v1/audio/voice-changer/queue`, `POST /api/v1/audio/voice-changer/retrieve`, `POST /api/v1/audio/voice-changer/complete`
Vídeo	`POST /api/v1/video/complete`, `POST /api/v1/video/queue`, `POST /api/v1/video/retrieve`
Decisiones	`POST /api/v1/decisions`, `POST /api/v1/systemone`
Herramientas	`POST /api/v1/augment/search`, `POST /api/v1/augment/scrape`, `POST /api/v1/augment/text-parser`
RPC de blockchain	`POST /api/v1/crypto/rpc/{network}`

Ruta de recarga

Endpoint	Auth	Propósito
`POST /api/v1/x402/top-up`	Solicitud inicial: ninguna. Reintento: `PAYMENT-SIGNATURE`	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 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, expirado o ya usado	Firma un nuevo mensaje `SIGN-IN-WITH-X` con un nonce nuevo para esta solicitud
`402` con `"error": "Authentication required"`	No se envió ningún encabezado `SIGN-IN-WITH-X` ni clave de API	Añade el encabezado Sign-In-With-X. El campo `extensions` de la respuesta contiene un nonce nuevo para firmar.
`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 `PAYMENT-SIGNATURE` 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, firma un nuevo mensaje Sign-In-With-X para cada solicitud y comprueba el saldo antes de las solicitudes para evitar round-trips 402 innecesarios.

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.

Documentación

Primeros pasos

Texto y chat

Imagen

Vídeo

Audio

Búsqueda y RAG

Agentes e integraciones

Herramientas de código

Herramientas para agentes

SDK y frameworks

X402

Auth con monedero

Paga con USDC

DIEM primero

¿Qué es X402?

Requisitos previos

Inicio rápido

Con herramientas compatibles con OpenAI

Helpers disponibles

Flujo manual

Paso 2: comprueba el saldo

Paso 3: recarga

Construyendo la cabecera PAYMENT-SIGNATURE para Base

Paso 4: haz una solicitud

Paso 5: inspecciona transacciones (opcional)

Rutas admitidas

Rutas de pago de inferencia

Ruta de recarga

Rutas solo de monedero

Errores

Para agentes

SDK del cliente x402

Precios de la API

Chat Completions

Spec de la API

Auth con monedero

Paga con USDC

DIEM primero

​¿Qué es X402?

​Requisitos previos

​Inicio rápido

​Con herramientas compatibles con OpenAI

​Helpers disponibles

​Flujo manual

​Paso 1: crea la cabecera SIGN-IN-WITH-X

​Paso 2: comprueba el saldo

​Paso 3: recarga

​Construyendo la cabecera PAYMENT-SIGNATURE para Base

​Paso 4: haz una solicitud

​Paso 5: inspecciona transacciones (opcional)

​Rutas admitidas

​Rutas de pago de inferencia

​Ruta de recarga

​Rutas solo de monedero

​Errores

​Para agentes

​Recursos relacionados

SDK del cliente x402

Precios de la API

Chat Completions

Spec de la API

¿Qué es X402?

Requisitos previos

Inicio rápido

Con herramientas compatibles con OpenAI

Helpers disponibles

Flujo manual

Paso 1: crea la cabecera SIGN-IN-WITH-X

Paso 2: comprueba el saldo

Paso 3: recarga

Construyendo la cabecera PAYMENT-SIGNATURE para Base

Paso 4: haz una solicitud

Paso 5: inspecciona transacciones (opcional)

Rutas admitidas

Rutas de pago de inferencia

Ruta de recarga

Rutas solo de monedero

Errores

Para agentes

Recursos relacionados