X402

X402 vous permet d’utiliser les routes API payantes de Venice en vous authentifiant avec un wallet et en maintenant un solde USDC prépayé. Pas de clé API ni de compte requis. Signez un message, rechargez sur Base ou Solana, et appelez n’importe quelle route prise en charge.

Auth par wallet

Authentifiez-vous avec un payload Sign-In-With-X signé dans l’en-tête SIGN-IN-WITH-X.

Payer en USDC

Maintenez un solde dépensable avec de l’USDC sur Base ou Solana.

DIEM d'abord

Si le wallet est lié à un compte Venice avec un solde DIEM, ce solde est dépensé en premier.

Qu’est-ce que X402 ?

X402 est un standard de paiement ouvert qui permet aux applications et aux agents de payer pour des services de manière programmatique en utilisant des cryptomonnaies. Venice implémente X402 afin que les wallets puissent s’authentifier et payer l’inférence directement avec de l’USDC sur Base ou Solana.

Prérequis

Un wallet sur Base ou Solana
Du token natif pour le gas sur la chaîne choisie, comme de l’ETH sur Base ou du SOL sur Solana
De l’USDC sur la chaîne choisie (ou un solde existant adossé à du DIEM via un compte Venice lié)

Envisagez d’utiliser un wallet dédié à l’automatisation plutôt que votre wallet trésorerie principal.

Démarrage rapide

Le SDK venice-x402-client fournit des helpers pour l’auth par wallet, les recharges et le suivi de solde.

npm install venice-x402-client

import { VeniceClient } from 'venice-x402-client'

const venice = new VeniceClient(process.env.WALLET_KEY)

await venice.topUp(10) // ignorer si le wallet a déjà un solde dépensable

const response = await venice.chat({
  model: 'kimi-k2-5',
  messages: [{ role: 'user', content: 'Hello!' }]
})

Le client génère un en-tête Sign-In-With-X frais pour chaque requête et suit automatiquement le solde via les en-têtes de réponse X-Balance-Remaining.

Avec des outils compatibles OpenAI

Si vous utilisez un outil qui accepte un fetch personnalisé, utilisez createAuthFetch pour ajouter l’auth par wallet à n’importe quelle requête :

import { createAuthFetch } from 'venice-x402-client'

const authFetch = createAuthFetch(process.env.WALLET_KEY)

Helpers disponibles

Le SDK inclut des helpers de première classe pour les routes Venice x402 les plus courantes. Pour tout ce qui n’est pas couvert, utilisez request() ou createAuthFetch() directement.

Catégorie	Méthodes
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()`
Vidéo	`video.queue()`, `video.retrieve()`, `video.generate()`, `video.complete()`
Embeddings	`embeddings()`
Modèles	`models()`
Wallet	`getBalance()`, `getTransactions()`, `topUp()`

Flux manuel

Si vous n’utilisez pas le SDK ou si vous avez besoin de comprendre le protocole sous-jacent, voici le flux étape par étape. Pour un nouveau wallet, partez du principe que vous devez d’abord recharger, sauf s’il dispose déjà d’un solde DIEM dépensable. Venice attend une preuve sign-in-with-x x402 dans l’en-tête SIGN-IN-WITH-X : un JSON encodé en Base64 contenant les champs du message signé (domain, address, uri, version, chainId, type, nonce, issuedAt, ainsi que les champs facultatifs expirationTime, notBefore, statement et resources) plus la signature. Venice reconstruit le message signé à partir de ces champs. Les portefeuilles EVM signent un message SIWE EIP-4361 sur Base et définissent type sur eip191, y compris les portefeuilles de smart contract. Les portefeuilles Solana signent le message de connexion Solana avec Ed25519. Dans le JSON, chainId est l’identifiant CAIP-2 (eip155:8453), tandis que la ligne Chain ID du message signé contient la référence nue (8453). L’ancien nom d’en-tête X-Sign-In-With-X est toujours accepté, tout comme les anciens payloads qui envoient le message signé lui-même. Chaque message signé ne peut être utilisé qu’une seule fois. Signez un nouveau message avec un nonce frais pour chaque requête, soit le vôtre, soit le nonce du dernier challenge 402, et envoyez-le dans les 5 minutes suivant son heure issuedAt. Réutiliser un message renvoie 401 (nonce déjà utilisé), tout comme un message émis il y a plus de 5 minutes. Pour Solana, définissez chainId à solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp, incluez type: "ed25519" dans le payload JSON encodé et fournissez la signature Ed25519 en base58 ou base64. Le message signé commence par <domain> wants you to sign in with your Solana account:, suivi de l’adresse du wallet et des champs standards URI, Version, Chain ID, Nonce, Issued At et Expiration Time (optionnel).

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!' }],
  }),
})

Appelez createSiwxHeader() immédiatement avant chaque requête. Dans les exemples curl ci-dessous, X402_AUTH doit être un en-tête nouvellement signé pour chaque appel.

Étape 2 : Vérifier le solde

Avant de faire une requête payante, vérifiez que le wallet dispose d’un solde dépensable :

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 réponse inclut :

canConsume : si le wallet peut faire des requêtes payantes
balanceUsd : le solde dépensable actuel
minimumTopUpUsd et suggestedTopUpUsd : indications pour les recharges
diemBalanceUsd : le solde adossé à du DIEM, le cas échéant

Le paramètre de chemin walletAddress accepte une adresse EVM (0x...) ou une adresse Solana en base58.

Étape 3 : Recharger

Rechargez avec de l’USDC sur Base ou Solana :

curl --request POST \
  --url https://api.venice.ai/api/v1/x402/top-up

Le premier appel renvoie 402 Payment Required avec un en-tête PAYMENT-REQUIRED contenant un tableau accepts. Chaque entrée décrit une option de paiement acceptée, notamment network, asset, payTo et amount. Choisissez l’option Base ou Solana avec laquelle vous voulez payer, utilisez ces détails exacts pour construire un en-tête PAYMENT-SIGNATURE et réessayez la même route. Les anciens noms d’en-tête X-402-Payment et X-PAYMENT sont toujours acceptés.

Envoyer des USDC directement à une adresse payTo ne recharge pas votre solde. Le crédit n’est ajouté que lorsqu’un PAYMENT-SIGNATURE signé est réglé via POST /x402/top-up. Seules Base et Solana sont prises en charge : les USDC envoyés sur toute autre chaîne, y compris le mainnet Ethereum, ne sont pas crédités. Les routes de solde et de transactions lisent le registre de Venice et non la chaîne, elles n’affichent donc rien après un simple transfert.

Construction de l’en-tête PAYMENT-SIGNATURE pour Base

Le script suivant crée un paiement x402 signé sur Base et envoie la requête de recharge. Nécessite les paquets npm x402 et 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"

En production, utilisez la dernière réponse PAYMENT-REQUIRED / accepts comme source de vérité au lieu de coder en dur ces valeurs. Pour les recharges Solana, construisez le paiement à partir de l’entrée Solana renvoyée dans accepts. Les entrées Solana utilisent network: "solana", le mint USDC comme asset, et peuvent inclure des métadonnées spécifiques au réseau comme extra.feePayer.

Étape 4 : Faire une requête

Une fois que le wallet dispose d’un solde dépensable, appelez n’importe quel endpoint pris en charge avec un en-tête SIGN-IN-WITH-X nouvellement signé :

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."
      }
    ]
  }'

Les réponses réussies peuvent inclure un en-tête X-Balance-Remaining.

Étape 5 : Inspecter les transactions (facultatif)

Consultez l’historique des transactions du wallet :

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"

Le grand livre inclut des entrées telles que TOP_UP, CHARGE et REFUND. Le paramètre de chemin walletAddress accepte une adresse EVM (0x...) ou une adresse Solana en base58.

Routes prises en charge

Routes d’inférence payantes

Les routes Venice publiques payantes suivantes prennent actuellement en charge l’authentification par wallet x402.

Catégorie	Endpoints
Chat	`POST /api/v1/chat/completions`, `POST /api/v1/responses`
Image	`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`
Vidéo	`POST /api/v1/video/complete`, `POST /api/v1/video/queue`, `POST /api/v1/video/retrieve`
Décisions	`POST /api/v1/decisions`, `POST /api/v1/systemone`
Outils	`POST /api/v1/augment/search`, `POST /api/v1/augment/scrape`, `POST /api/v1/augment/text-parser`
RPC blockchain	`POST /api/v1/crypto/rpc/{network}`

Route de recharge

Endpoint	Auth	Objectif
`POST /api/v1/x402/top-up`	Requête initiale : aucune. Réessai : `PAYMENT-SIGNATURE`	Ajouter des crédits USDC au solde dépensable du wallet via une option de paiement Base ou Solana acceptée

Routes wallet uniquement

Ces routes utilisent SIGN-IN-WITH-X pour l’identité mais ne facturent pas le solde.

Endpoint	Objectif
`GET /api/v1/x402/balance/{walletAddress}`	Vérifier le solde dépensable pour une adresse de wallet EVM ou Solana
`GET /api/v1/x402/transactions/{walletAddress}`	Consulter l’historique des transactions pour une adresse de wallet EVM ou Solana

Erreurs

Statut	Cause probable	Que faire
`401`	Payload Sign-In-With-X malformé, expiré ou déjà utilisé	Signez un nouveau message `SIGN-IN-WITH-X` avec un nonce frais pour cette requête
`402` avec `"error": "Authentication required"`	Aucun en-tête `SIGN-IN-WITH-X` ni clé API n’a été envoyé	Ajoutez l’en-tête Sign-In-With-X. Le champ `extensions` de la réponse contient un nouveau nonce à signer.
`402` sur une route payante	Solde dépensable insuffisant	Rechargez et réessayez
`402` sur `/x402/top-up`	Attendu. C’est le flux d’initiation de paiement.	Utilisez les détails de paiement renvoyés pour construire `PAYMENT-SIGNATURE` et réessayez
`403` sur balance ou transactions	Wallet incohérent	Assurez-vous que le wallet authentifié correspond au paramètre de chemin `walletAddress`
`400` sur la recharge	En-tête de paiement malformé	Reconstruisez à partir de la dernière réponse `402`

Pour les agents

Le flux est identique. Stockez les clés privées dans des variables d’environnement ou un gestionnaire de secrets, signez un nouveau message Sign-In-With-X pour chaque requête, et vérifiez le solde avant les requêtes pour éviter des allers-retours 402 inutiles.

SDK client x402

Client x402 officiel Venice pour Node.js/TypeScript.

Tarification API

Consultez la tarification des modèles et la manière dont Venice facture l’usage.

Chat Completions

Une route payante courante pour l’accès basé sur wallet.

Spécification API

Documentation de référence et accès au spec brut.

Documentation

Démarrage

Texte et chat

Image

Vidéo

Audio

Recherche et RAG

Agents et intégrations

Outils de code

Outils pour agents

SDK et frameworks

X402

Auth par wallet

Payer en USDC

DIEM d'abord

Qu’est-ce que X402 ?

Prérequis

Démarrage rapide

Avec des outils compatibles OpenAI

Helpers disponibles

Flux manuel

Étape 2 : Vérifier le solde

Étape 3 : Recharger

Construction de l’en-tête PAYMENT-SIGNATURE pour Base

Étape 4 : Faire une requête

Étape 5 : Inspecter les transactions (facultatif)

Routes prises en charge

Routes d’inférence payantes

Route de recharge

Routes wallet uniquement

Erreurs

Pour les agents

SDK client x402

Tarification API

Chat Completions

Spécification API

Auth par wallet

Payer en USDC

DIEM d'abord

​Qu’est-ce que X402 ?

​Prérequis

​Démarrage rapide

​Avec des outils compatibles OpenAI

​Helpers disponibles

​Flux manuel

​Étape 1 : Créer l’en-tête SIGN-IN-WITH-X

​Étape 2 : Vérifier le solde

​Étape 3 : Recharger

​Construction de l’en-tête PAYMENT-SIGNATURE pour Base

​Étape 4 : Faire une requête

​Étape 5 : Inspecter les transactions (facultatif)

​Routes prises en charge

​Routes d’inférence payantes

​Route de recharge

​Routes wallet uniquement

​Erreurs

​Pour les agents

​Ressources connexes

SDK client x402

Tarification API

Chat Completions

Spécification API

Qu’est-ce que X402 ?

Prérequis

Démarrage rapide

Avec des outils compatibles OpenAI

Helpers disponibles

Flux manuel

Étape 1 : Créer l’en-tête SIGN-IN-WITH-X

Étape 2 : Vérifier le solde

Étape 3 : Recharger

Construction de l’en-tête PAYMENT-SIGNATURE pour Base

Étape 4 : Faire une requête

Étape 5 : Inspecter les transactions (facultatif)

Routes prises en charge

Routes d’inférence payantes

Route de recharge

Routes wallet uniquement

Erreurs

Pour les agents

Ressources connexes