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 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 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()`
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 uma prova sign-in-with-x do x402 no header SIGN-IN-WITH-X: JSON codificado em Base64 com os campos da mensagem assinada (domain, address, uri, version, chainId, type, nonce, issuedAt e os opcionais expirationTime, notBefore, statement e resources) mais a signature. A Venice reconstrói a mensagem assinada a partir desses campos. Carteiras EVM assinam uma mensagem SIWE EIP-4361 na Base e definem type como eip191, incluindo carteiras de smart contract. Carteiras Solana assinam a mensagem de login da Solana com Ed25519. No JSON, chainId é o identificador CAIP-2 (eip155:8453), enquanto a linha Chain ID da mensagem assinada traz a referência pura (8453). O nome de header legado X-Sign-In-With-X ainda é aceito, assim como payloads mais antigos que enviam a própria message assinada. Cada mensagem assinada só pode ser usada uma vez. Assine uma nova mensagem com um nonce novo para cada requisição, seja o seu próprio ou o nonce do desafio 402 mais recente, e envie-a em até 5 minutos a partir do seu horário de issuedAt. Reutilizar uma mensagem retorna 401 (nonce já utilizado), assim como uma mensagem emitida há mais de 5 minutos. 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)

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

Chame createSiwxHeader() imediatamente antes de cada requisição. Nos exemplos de curl abaixo, X402_AUTH deve ser um cabeçalho assinado novamente a cada chamada.

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 "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 PAYMENT-SIGNATURE e refaça a mesma rota. Os nomes de cabeçalho legados X-402-Payment e X-PAYMENT ainda são aceitos.

Enviar USDC diretamente para um endereço payTo não recarrega seu saldo. O crédito só é adicionado quando um PAYMENT-SIGNATURE assinado é liquidado por meio de POST /x402/top-up. Apenas Base e Solana são suportadas, então USDC enviado em qualquer outra rede, incluindo a mainnet do Ethereum, não é creditado. As rotas de saldo e de transações leem o livro-razão da Venice, não a blockchain, então após uma transferência simples elas não mostram nada.

Construindo o cabeçalho PAYMENT-SIGNATURE 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 "PAYMENT-SIGNATURE: $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 um cabeçalho SIGN-IN-WITH-X assinado novamente:

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

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 "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/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`
Vídeo	`POST /api/v1/video/complete`, `POST /api/v1/video/queue`, `POST /api/v1/video/retrieve`
Decisões	`POST /api/v1/decisions`, `POST /api/v1/systemone`
Ferramentas	`POST /api/v1/augment/search`, `POST /api/v1/augment/scrape`, `POST /api/v1/augment/text-parser`
RPC de blockchain	`POST /api/v1/crypto/rpc/{network}`

Rota de recarga

Endpoint	Auth	Finalidade
`POST /api/v1/x402/top-up`	Requisição inicial: nenhuma. Retry: `PAYMENT-SIGNATURE`	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 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, expirado ou já utilizado	Assine uma nova mensagem `SIGN-IN-WITH-X` com um nonce novo para esta requisição
`402` com `"error": "Authentication required"`	Nenhum cabeçalho `SIGN-IN-WITH-X` ou chave de API foi enviado	Adicione o cabeçalho Sign-In-With-X. O campo `extensions` da resposta contém um nonce novo para assinar.
`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 `PAYMENT-SIGNATURE` 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, assine uma nova mensagem Sign-In-With-X para cada requisição e verifique o saldo antes das requisições para evitar idas e voltas 402 desnecessárias.

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.

Documentação

Primeiros passos

Texto e chat

Imagem

Vídeo

Áudio

Pesquisa e RAG

Agentes e integrações

Ferramentas de código

Ferramentas para agentes

SDKs e frameworks

X402

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 2: Verifique o saldo

Passo 3: Recarregue

Construindo o cabeçalho PAYMENT-SIGNATURE 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

SDK do cliente x402

Preços da API

Chat Completions

Spec da API

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 SIGN-IN-WITH-X

​Passo 2: Verifique o saldo

​Passo 3: Recarregue

​Construindo o cabeçalho PAYMENT-SIGNATURE 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 SIGN-IN-WITH-X

Passo 2: Verifique o saldo

Passo 3: Recarregue

Construindo o cabeçalho PAYMENT-SIGNATURE 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