> ## Documentation Index > Fetch the complete documentation index at: https://docs.venice.ai/llms.txt > Use this file to discover all available pages before exploring further. # X402 > Acesse a Venice API sem uma chave de API pagando por requisição com o protocolo x402 e autenticando-se com uma carteira cripto na Base. 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. Autentique-se com um payload Sign-In-With-X assinado no cabeçalho `X-Sign-In-With-X`. Mantenha saldo gastável com USDC na Base ou Solana. Se a carteira estiver vinculada a uma conta Venice com saldo DIEM, esse é gasto primeiro. ## O que é o X402? O [X402](https://www.x402.org/) é 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`](https://github.com/veniceai/x402-client) oferece helpers para auth por carteira, recargas e rastreamento de saldo. ```bash theme={"system"} npm install venice-x402-client ``` ```typescript theme={"system"} 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: ```typescript theme={"system"} 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. ### Passo 1: Crie o cabeçalho X-Sign-In-With-X 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 ` 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. ```typescript theme={"system"} 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: ```bash theme={"system"} 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: ```bash theme={"system"} 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`. ```bash theme={"system"} export EVM_PRIVATE_KEY=0xYOUR_PRIVATE_KEY ``` ```bash theme={"system"} 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`: ```bash theme={"system"} 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: ```bash theme={"system"} 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 Cliente oficial Venice x402 para Node.js/TypeScript. Verifique os preços dos modelos e como a Venice cobra o uso. Uma rota paga comum para acesso baseado em carteira. Documentação de referência e acesso ao spec bruto.