X402

O X402 permite usar as rotas pagas da API Venice se autenticando com uma carteira e mantendo um saldo pré-pago em USDC. Sem necessidade de chave de API ou conta. Assine uma mensagem, recarregue na Base ou Solana e chame qualquer rota suportada.

Autenticação por carteira

Autentique-se com um payload Sign-In-With-X assinado no cabeçalho X-Sign-In-With-X.

Pague com USDC

Mantenha saldo gastável com USDC na Base ou Solana.

DIEM primeiro

Se a carteira estiver vinculada a uma conta Venice com saldo DIEM, esse é gasto primeiro.

O que é o X402?

O X402 é um padrão de pagamento aberto que permite que aplicações e agentes paguem por serviços programaticamente usando criptomoedas. A Venice implementa o X402 para que carteiras possam se autenticar e pagar por inferência diretamente com USDC na Base ou Solana.

Pré-requisitos

Uma carteira na Base ou Solana
Token nativo para gas na chain selecionada, como ETH na Base ou SOL na Solana
USDC na chain selecionada (ou saldo existente lastreado em DIEM de uma conta Venice vinculada)

Considere usar uma carteira dedicada para automação, em vez da sua carteira de tesouraria principal.

Quickstart

O SDK venice-x402-client oferece helpers para auth por carteira, recargas e rastreamento 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) // pule se a carteira já tem saldo gastável

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

O cliente gera um cabeçalho X-Sign-In-With-X novo para cada requisição e rastreia automaticamente o saldo a partir dos cabeçalhos de resposta X-Balance-Remaining.

Com ferramentas compatíveis com OpenAI

Se você está usando uma ferramenta que aceita um fetch customizado, use createAuthFetch para adicionar auth de carteira a qualquer requisição:

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

const authFetch = createAuthFetch(process.env.WALLET_KEY)

Helpers disponíveis

O SDK inclui helpers de primeira classe para as rotas Venice x402 mais comuns. Para qualquer coisa não coberta, use request() ou createAuthFetch() diretamente.

Categoria	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()`

Fluxo manual

Se você não está usando o SDK ou precisa entender o protocolo subjacente, aqui está o fluxo passo a passo. Para uma carteira nova, assuma que você precisa recarregar primeiro, a menos que ela já tenha saldo DIEM gastável. A Venice espera um payload JSON codificado em Base64 contendo uma mensagem Sign-In-With-X assinada. Carteiras EVM assinam uma mensagem SIWE EIP-4361 na Base. Carteiras Solana assinam a mensagem SIWX Solana com Ed25519. Gere um nonce e timestamp novos para cada fluxo de requisição. Para Solana, defina chainId como solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp, inclua type: "ed25519" no payload JSON codificado e forneça a assinatura Ed25519 como base58 ou base64. A mensagem assinada começa com <domain> wants you to sign in with your Solana account:, seguida pelo endereço da carteira e os campos padrão URI, Version, Chain ID, Nonce, Issued At e Expiration Time opcional.

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)

Passo 2: Verifique o saldo

Antes de fazer uma requisição paga, verifique se a carteira tem saldo gastável:

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"

A resposta inclui:

canConsume: se a carteira pode fazer requisições pagas
balanceUsd: saldo gastável atual
minimumTopUpUsd e suggestedTopUpUsd: orientação para recargas
diemBalanceUsd: saldo lastreado em DIEM, se houver

O parâmetro de caminho walletAddress aceita um endereço EVM (0x...) ou um endereço Solana em base58.

Passo 3: Recarregue

Recarregue com USDC na Base ou Solana:

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

A primeira chamada retorna 402 Payment Required com um cabeçalho PAYMENT-REQUIRED contendo um array accepts. Cada entrada descreve uma opção de pagamento aceita, incluindo network, asset, payTo e amount. Escolha a opção Base ou Solana com a qual deseja pagar, use esses detalhes exatos para construir um cabeçalho X-402-Payment e refaça a mesma rota.

Construindo o cabeçalho X-402-Payment para Base

O script a seguir cria um pagamento x402 assinado na Base e envia a requisição de recarga. Requer os pacotes npm x402 e 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"

Use a resposta PAYMENT-REQUIRED / accepts mais recente como fonte da verdade em produção, em vez de fixar esses valores no código. Para recargas em Solana, construa o pagamento a partir da entrada Solana retornada em accepts. Entradas Solana usam network: "solana", o mint USDC como asset e podem incluir metadados específicos da rede, como extra.feePayer.

Passo 4: Faça uma requisição

Quando a carteira tiver saldo gastável, chame qualquer endpoint suportado com o cabeçalho 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."
      }
    ]
  }'

Respostas bem-sucedidas podem incluir um cabeçalho X-Balance-Remaining.

Passo 5: Inspecione as transações (opcional)

Revise o histórico de transações da carteira:

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"

O ledger inclui entradas como TOP_UP, CHARGE e REFUND. O parâmetro de caminho walletAddress aceita um endereço EVM (0x...) ou um endereço Solana em base58.

Rotas suportadas

Rotas pagas de inferência

As seguintes rotas pagas públicas da Venice atualmente suportam autenticação por carteira x402.

Categoria	Endpoints
Chat	`POST /api/v1/chat/completions`, `POST /api/v1/responses`
Imagem	`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`
Áudio	`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`

Rota de recarga

Endpoint	Auth	Finalidade
`POST /api/v1/x402/top-up`	Requisição inicial: nenhuma. Retry: `X-402-Payment`	Adicione créditos USDC ao saldo gastável da carteira usando uma opção de pagamento aceita Base ou Solana

Rotas apenas de carteira

Essas rotas usam X-Sign-In-With-X para identidade, mas não cobram saldo.

Endpoint	Finalidade
`GET /api/v1/x402/balance/{walletAddress}`	Verifica saldo gastável para um endereço de carteira EVM ou Solana
`GET /api/v1/x402/transactions/{walletAddress}`	Visualiza histórico de transações para um endereço de carteira EVM ou Solana

Erros

Status	Causa provável	O que fazer
`401`	Payload Sign-In-With-X malformado ou expirado	Reconstrua `X-Sign-In-With-X` com nonce e timestamp novos
`402` em uma rota paga	Saldo gastável insuficiente	Recarregue e tente novamente
`402` em `/x402/top-up`	Esperado. Este é o fluxo de iniciação de pagamento.	Use os detalhes de pagamento retornados para construir `X-402-Payment` e tente novamente
`403` em balance ou transactions	Carteira não corresponde	Garanta que a carteira autenticada corresponde ao parâmetro de caminho `walletAddress`
`400` em top-up	Cabeçalho de pagamento malformado	Reconstrua a partir da resposta `402` mais recente

Para agentes

O fluxo é o mesmo. Armazene chaves privadas em variáveis de ambiente ou em um gerenciador de segredos, e verifique o saldo antes das requisições para evitar idas e voltas 402 desnecessárias.

Recursos relacionados

SDK do cliente x402

Cliente oficial Venice x402 para Node.js/TypeScript.

Preços da API

Verifique os preços dos modelos e como a Venice cobra o uso.

Chat Completions

Uma rota paga comum para acesso baseado em carteira.

Spec da API

Documentação de referência e acesso ao spec bruto.

Autenticação por carteira

Pague com USDC

DIEM primeiro

​O que é o X402?

​Pré-requisitos

​Quickstart

​Com ferramentas compatíveis com OpenAI

​Helpers disponíveis

​Fluxo manual

​Passo 1: Crie o cabeçalho X-Sign-In-With-X

​Passo 2: Verifique o saldo

​Passo 3: Recarregue

​Construindo o cabeçalho X-402-Payment para Base

​Passo 4: Faça uma requisição

​Passo 5: Inspecione as transações (opcional)

​Rotas suportadas

​Rotas pagas de inferência

​Rota de recarga

​Rotas apenas de carteira

​Erros

​Para agentes

​Recursos relacionados

SDK do cliente x402

Preços da API

Chat Completions

Spec da API

O que é o X402?

Pré-requisitos

Quickstart

Com ferramentas compatíveis com OpenAI

Helpers disponíveis

Fluxo manual

Passo 1: Crie o cabeçalho X-Sign-In-With-X

Passo 2: Verifique o saldo

Passo 3: Recarregue

Construindo o cabeçalho X-402-Payment para Base

Passo 4: Faça uma requisição

Passo 5: Inspecione as transações (opcional)

Rotas suportadas

Rotas pagas de inferência

Rota de recarga

Rotas apenas de carteira

Erros

Para agentes

Recursos relacionados