Ghid operator pentru Venice x402

Ce face

venice-x402 acoperă fluxul Venice pentru credite de wallet: plătești per request cu USDC pe Base, fără să depinzi de billing clasic pe cont. Walletul are un sold în USD-credit; inferența consumă din acel sold; dacă soldul nu ajunge, API-ul răspunde cu 402 Payment Required și include instrucțiuni de top-up.

Capabilitatea acoperă trei endpointuri administrative:

Mai acoperă forma răspunsului x402 v2 din headerul PAYMENT-REQUIRED, returnat de endpointurile de inferență când walletul nu are credit suficient.

All guides

Când îmi folosește

Îți folosește când vrei cereri Venice plătite per request cu USDC pe Base, nu printr-un flow tradițional de account billing.

Cazuri tipice:

• testezi un client care trebuie să reacționeze corect la 402;
• verifici soldul walletului înainte de inferență;
• inspectezi costurile prin /x402/transactions;
• implementezi auto-top-up: prinzi 402, semnezi plata, faci settlement, reîncerci cererea;
• depanezi diferența dintre SIWE lipsă, SIWE invalid, wallet mismatch și plată invalidă.

Constantele importante: Base mainnet, chain ID 8453 (eip155:8453), USDC nativ pe Base cu 6 decimals, nu USDbC. Minimum top-up este în mod normal $5, dar nu îl hardcoda: folosește minimumTopUpUsd din răspuns. Receiver walletul și contractul tokenului vin din API; nu le îngropa în cod ca fosile optimiste.

Cum îl invoc / declanșez

Capabilitatea venice-x402 nu definește o comandă conversațională publică fixă. Este un ghid pentru implementare API.

Flow-ul canonic:

1. chemi un endpoint de inferență cu wallet fără sold suficient;
2. primești 402, cu topUpInstructions și siwxChallenge;
3. faci POST /x402/top-up fără X-402-Payment ca să descoperi cerințele;
4. semnezi transferul USDC cu x402 SDK;
5. repeți POST /x402/top-up cu headerul X-402-Payment;
6. reîncerci inferența.

Pentru semnare brută:

npm install x402

Există și venice-x402-client, care poate prinde 402, face auto-top-up până la o sumă configurată și reîncerca requestul. Nu îl trata ca magie: setează limite clare, loghează settlementul și nu semna plăți fără o politică explicită de plafon.

Exemplu practic

Discovery pentru cerințele de plată:

curl -X POST https://api.venice.ai/api/v1/x402/top-up

Răspunsul așteptat este 402. Aici 402 înseamnă discovery, nu dezastru. Primești x402Version și accepts[], cu network, asset, amount în base units și payTo.

Settlement cu SDK:

import { createPaymentHeader } from 'x402'
import { Wallet } from 'ethers'
 
const wallet = new Wallet(process.env.WALLET_KEY!)
const discover = await fetch(`${base}/x402/top-up`, { method: 'POST' })
const { accepts: [req] } = await discover.json()
 
const amount = '10000000' // 10 USDC, base units
const header = await createPaymentHeader({ ...req, amount }, wallet)
 
const settle = await fetch(`${base}/x402/top-up`, {
  method: 'POST',
  headers: { 'X-402-Payment': header },
})

Sold:

curl "https://api.venice.ai/api/v1/x402/balance/0xYOUR_WALLET" \
  -H "X-Sign-In-With-X: <base64 siwe>"

Tranzacții:

curl "https://api.venice.ai/api/v1/x402/transactions/0xYOUR_WALLET?limit=50&offset=0" \
  -H "X-Sign-In-With-X: <base64 siwe>"

Output / unde aterizează

Settlementul /x402/top-up reușit întoarce success: true și date precum walletAddress, amountCredited, newBalance, paymentId.

/x402/balance/{walletAddress} întoarce balanceUsd, canConsume, minimumTopUpUsd, suggestedTopUpUsd și opțional diemBalanceUsd. balanceUsd este doar soldul wallet-credit USDC; diemBalanceUsd, când există, este separat.

/x402/transactions/{walletAddress} întoarce currentBalance, transactions[] și pagination. Parametrii sunt limit între 1 și 100, default 50, și offset, default 0. Folosește pagination.hasMore pentru paginare.

Limite / gotchas

Nu semna manual EIP-712 transferWithAuthorization dacă poți evita. Folosește x402 SDK. Nonce reuse produce INVALID_PAYMENT.

SIWE trebuie semnat de același wallet ca walletAddress din path. Altfel primești 403. Dacă headerul SIWE lipsește pe balance sau transactions, răspunsul este 402, nu 401; 401 este pentru header prezent, dar invalid.

PAYMENT-REQUIRED este headerul uppercase cu obiect x402 v2 base64-encoded. Nu îl confunda cu body-ul 402, care poate include code: "PAYMENT_REQUIRED", balans și instrucțiuni.

accepts[].amount este în base units. Pentru USDC, "5000000" înseamnă 5 USDC. Nu mai multiplica încă o dată.

Erori: 400 validare sau top-up sub minim; 401 SIWE invalid; 402 discovery, auth lipsă sau sold insuficient; 403 wallet mismatch; 429 prea multe cereri; 500 settlement failure. La 500, reîncearcă doar cu nonce proaspăt și verifică ledgerul înainte să presupui că plata nu a trecut.