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 X-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 X-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()`, `video.transcribe()`
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 un payload JSON encodé en Base64 contenant un message Sign-In-With-X signé. Les wallets EVM signent un message SIWE EIP-4361 sur Base. Les wallets Solana signent le message SIWX Solana avec Ed25519. Générez un nonce et un timestamp frais pour chaque flux de requête. 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)
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)

É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 "X-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 X-402-Payment et réessayez la même route.

Construction de l’en-tête X-402-Payment 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 "X-402-Payment: $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 l’en-tête 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."
      }
    ]
  }'

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 "X-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/complete`, `POST /api/v1/audio/queue`, `POST /api/v1/audio/retrieve`
Vidéo	`POST /api/v1/video/complete`, `POST /api/v1/video/queue`, `POST /api/v1/video/retrieve`, `POST /api/v1/video/transcriptions`

Route de recharge

Endpoint	Auth	Objectif
`POST /api/v1/x402/top-up`	Requête initiale : aucune. Réessai : `X-402-Payment`	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 X-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é ou expiré	Reconstruire `X-Sign-In-With-X` avec un nonce et un timestamp frais
`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 `X-402-Payment` 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, et vérifiez le solde avant les requêtes pour éviter des allers-retours 402 inutiles.

Ressources connexes

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.

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

​Étape 2 : Vérifier le solde

​Étape 3 : Recharger

​Construction de l’en-tête X-402-Payment 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 X-Sign-In-With-X

Étape 2 : Vérifier le solde

Étape 3 : Recharger

Construction de l’en-tête X-402-Payment 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