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

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 X-Sign-In-With-X

​Paso 2: comprueba el saldo

​Paso 3: recarga

​Construyendo la cabecera X-402-Payment 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 X-Sign-In-With-X

Paso 2: comprueba el saldo

Paso 3: recarga

Construyendo la cabecera X-402-Payment 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