> ## 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.

# RPC Crypto para Agentes

> Use a Venice como provedora de modelos e camada RPC blockchain para agentes autônomos: uma credencial, mais de 230 modelos, 11 chains, sem MetaMask.

A Venice oferece ao seu agente tanto inferência (mais de 230 modelos) quanto acesso a blockchain (10 chains EVM mais Starknet) por meio de uma única credencial. Seu agente pode pensar, assinar e enviar transações sem precisar gerenciar contas separadas para provedores de inferência e RPC.

<CardGroup cols={2}>
  <Card title="Uma credencial, dois superpoderes" icon="key">
    Uma única chave de API (ou carteira) para inferência LLM e chamadas JSON-RPC.
  </Card>

  <Card title="11 chains suportadas" icon="link">
    Ethereum, Base, Arbitrum, Optimism, Polygon, Linea, Avalanche, BSC, Blast, zkSync Era e Starknet (mainnet e testnets).
  </Card>

  <Card title="Faça staking de VVV para financiamento headless" icon="coins">
    Faça staking de VVV na Base para ganhar DIEM diário, o único caminho totalmente headless de financiamento para uma chave de API emitida. Recargas em USD e cripto também estão disponíveis pelo dashboard.
  </Card>

  <Card title="Autenticação sem chave via x402" icon="wallet">
    Agentes podem se autenticar com uma assinatura de carteira e pagar em USDC na Base ou Solana.
  </Card>
</CardGroup>

## Por que usar Venice para agentes on-chain?

| Capacidade        | O que seu agente ganha                                                                                              |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Inferência**    | Mais de 230 modelos de texto, imagem, vídeo, áudio e embeddings por meio de um único endpoint compatível com OpenAI |
| **RPC Crypto**    | Proxy JSON-RPC 2.0 para 10 chains EVM mais Starknet (mainnet e testnets)                                            |
| **Autenticação**  | Chave de API padrão ou autenticação por carteira x402 (sem necessidade de conta Venice)                             |
| **Financiamento** | Autônomo: staking de VVV para DIEM diário. Navegador: recargas em USD ou cripto via dashboard                       |
| **Batching**      | Até 100 chamadas JSON-RPC por requisição, multi-chain em paralelo                                                   |
| **Idempotência**  | Tentativas seguras com cabeçalho `Idempotency-Key`                                                                  |

## Autenticação

Escolha o método de autenticação que combina com a forma como seu agente roda.

| Método            | Melhor para                                   | Como funciona                                                                                                                                                                             |
| ----------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Chave de API**  | Agentes server-side, implantações fixas       | Cabeçalho `Authorization: Bearer <key>`. Obtenha uma chave em [venice.ai/settings/api](https://venice.ai/settings/api).                                                                   |
| **Carteira x402** | Agentes autônomos, cripto-nativos ou efêmeros | A carteira assina uma mensagem Sign-In-With-X e paga por requisição em USDC na Base ou Solana. Sem necessidade de conta Venice. Veja o [guia x402](/guides/integrations/x402-venice-api). |

Ambos os métodos compartilham os mesmos limites de taxa e cobrança em créditos Venice.

<Tip>
  Agentes verdadeiramente autônomos podem emitir sua própria chave de API fazendo staking de VVV na Base. Veja [Criação autônoma de chave de API para agentes](/guides/getting-started/generating-api-key-agent).
</Tip>

## Quickstart de RPC Crypto

Envie qualquer método JSON-RPC 2.0 para `POST /crypto/rpc/{network}`.

```bash theme={"system"}
curl https://api.venice.ai/api/v1/crypto/rpc/ethereum-mainnet \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_chainId",
    "params": [],
    "id": 1
  }'
```

Resposta:

```json theme={"system"}
{ "jsonrpc": "2.0", "id": 1, "result": "0x1" }
```

Os cabeçalhos da resposta incluem `X-Venice-RPC-Credits` (créditos cobrados), `X-Venice-RPC-Cost-USD` (custo em dólares) e `X-Request-ID` (ID de correlação).

### Redes suportadas

| Família           | Mainnet             | Testnets                               |
| ----------------- | ------------------- | -------------------------------------- |
| Ethereum          | `ethereum-mainnet`  | `ethereum-sepolia`, `ethereum-holesky` |
| Base              | `base-mainnet`      | `base-sepolia`                         |
| Arbitrum          | `arbitrum-mainnet`  | `arbitrum-sepolia`                     |
| Optimism          | `optimism-mainnet`  | `optimism-sepolia`                     |
| Polygon           | `polygon-mainnet`   | `polygon-amoy`                         |
| Linea             | `linea-mainnet`     | `linea-sepolia`                        |
| Avalanche C-Chain | `avalanche-mainnet` | `avalanche-fuji`                       |
| BNB Smart Chain   | `bsc-mainnet`       | `bsc-testnet`                          |
| Blast             | `blast-mainnet`     | `blast-sepolia`                        |
| zkSync Era        | `zksync-mainnet`    | `zksync-sepolia`                       |
| Starknet          | `starknet-mainnet`  | `starknet-sepolia`                     |

Use [`GET /crypto/rpc/networks`](/api-reference/endpoint/crypto/networks) para a lista oficial em tempo real.

### Níveis de método

Os métodos estão agrupados em três níveis de crédito. Custo total = `baseCredits[chain] × methodTier`.

| Nível        | Multiplicador | Exemplos                                                                                                                                 |
| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Standard** | 1x            | `eth_call`, `eth_getBalance`, `eth_blockNumber`, `eth_sendRawTransaction`, `eth_getLogs`, `eth_getTransactionReceipt`, `eth_estimateGas` |
| **Advanced** | 2x            | `trace_block`, `trace_call`, `trace_transaction`, `debug_traceCall`, `debug_traceTransaction`                                            |
| **Large**    | 4x            | `trace_replayBlockTransactions`, `trace_replayTransaction`, `txpool_content`                                                             |

Lista completa e detalhes de preços na [referência da API de RPC Crypto](/api-reference/endpoint/crypto/rpc).

## Receitas para agentes

Padrões comuns para agentes de IA que precisam ler e escrever on-chain.

### Ler o saldo nativo de uma carteira

```bash theme={"system"}
curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": ["0xYourWalletAddress", "latest"],
    "id": 1
  }'
```

### Ler saldo de token ERC-20

Chame o seletor `balanceOf(address)` com `eth_call`. O campo `data` é o seletor de 4 bytes (`0x70a08231`) seguido pelo endereço da carteira preenchido à esquerda com zeros até 32 bytes. O mais fácil é deixar uma biblioteca codificar isso:

```typescript theme={"system"}
import { encodeFunctionData, parseAbi } from 'viem'

const data = encodeFunctionData({
  abi: parseAbi(['function balanceOf(address) view returns (uint256)']),
  args: ['0xWalletAddress'],
})

const response = await fetch('https://api.venice.ai/api/v1/crypto/rpc/base-mainnet', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'eth_call',
    params: [{ to: '0xacfE6019Ed1A7Dc6f7B508C02d1b04ec88cC21bf', data }, 'latest'],
    id: 1,
  }),
})
```

O endereço de contrato acima é VVV na Base. Substitua por qualquer contrato ERC-20.

### Enviar uma transação assinada (ciclo de vida completo)

A Venice nunca guarda suas chaves privadas. O agente coleta parâmetros da transação via leituras RPC, assina localmente com uma biblioteca como [viem](https://viem.sh) ou [ethers](https://docs.ethers.org) e, em seguida, repassa o hex bruto pela Venice.

<Steps>
  <Step title="Obtenha o próximo nonce">
    ```bash theme={"system"}
    curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
      -H "Authorization: Bearer $VENICE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0xAgentWallet","pending"],"id":1}'
    ```

    Use `"pending"` para que envios consecutivos não colidam.
  </Step>

  <Step title="Obtenha o preço do gas">
    ```bash theme={"system"}
    curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
      -H "Authorization: Bearer $VENICE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":1}'
    ```

    Para chains EIP-1559, prefira `eth_feeHistory` para calcular `maxFeePerGas` e `maxPriorityFeePerGas`.
  </Step>

  <Step title="Estime o gas">
    ```bash theme={"system"}
    curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
      -H "Authorization: Bearer $VENICE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","method":"eth_estimateGas","params":[{"from":"0xAgentWallet","to":"0xRecipient","value":"0x0","data":"0x..."}],"id":1}'
    ```
  </Step>

  <Step title="Assine localmente">
    ```typescript theme={"system"}
    import { privateKeyToAccount } from 'viem/accounts'
    import { base } from 'viem/chains'

    const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY)

    const signed = await account.signTransaction({
      chainId: base.id,
      nonce,                  // do passo 1
      gas,                    // do passo 3
      maxFeePerGas,           // do passo 2 (fee history)
      maxPriorityFeePerGas,   // do passo 2 (fee history)
      to: '0xRecipient',
      value: 0n,
      data: '0x...',
    })
    ```
  </Step>

  <Step title="Envie via Venice">
    ```bash theme={"system"}
    curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
      -H "Authorization: Bearer $VENICE_API_KEY" \
      -H "Idempotency-Key: agent-tx-<id>" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0xSignedHex"],"id":1}'
    ```

    Sempre defina `Idempotency-Key` em relays para que uma instabilidade de rede não cause uma transmissão dupla.
  </Step>

  <Step title="Faça polling do recibo">
    ```bash theme={"system"}
    curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
      -H "Authorization: Bearer $VENICE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0xTxHash"],"id":1}'
    ```

    Faça polling a cada poucos segundos até que `result` seja não-nulo. Verifique `result.status` (`"0x1"` = sucesso).
  </Step>
</Steps>

<Note>
  Cada chamada `eth_sendRawTransaction` é registrada no servidor com o hash da transação, rede, ID da requisição e ID do usuário que chamou. O payload assinado em si não é retido. Esse registro de auditoria existe para que chaves comprometidas usadas em relays ilícitos possam ser rastreadas até a conta responsável.
</Note>

### Faça batch de várias chamadas (verificação de portfólio multi-chain)

Envie até 100 objetos JSON-RPC em uma única requisição. Cada um é validado e cobrado independentemente.

```bash theme={"system"}
curl https://api.venice.ai/api/v1/crypto/rpc/ethereum-mainnet \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1 },
    { "jsonrpc": "2.0", "method": "eth_getBalance", "params": ["0xWallet", "latest"], "id": 2 },
    { "jsonrpc": "2.0", "method": "eth_gasPrice", "params": [], "id": 3 }
  ]'
```

Para leituras multi-chain (uma chamada por chain), faça requisições em paralelo para diferentes endpoints `{network}`.

### Tentativas seguras com idempotência

Defina o cabeçalho `Idempotency-Key` como qualquer string correspondente a `[A-Za-z0-9_-]{1,255}`. A Venice armazena em cache a resposta por 24 horas, indexada por `(usuário, chave)`. Replays retornam o resultado em cache com `Idempotent-Replayed: true` e não cobram nada.

```bash theme={"system"}
curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Idempotency-Key: agent-tx-2026-04-21-001" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_sendRawTransaction",
    "params": ["0xSignedRawTxHex"],
    "id": 1
  }'
```

Isso é crítico para relays de transações, onde uma instabilidade de rede poderia fazer seu agente transmitir a mesma tx duas vezes.

## Financiando a chave de API do agente

Uma vez que o agente tenha uma chave de API Venice, ele precisa de saldo disponível na conta subjacente antes que endpoints pagos aceitem a chave. Há duas formas de colocar saldo lá:

| Caminho                                    | Autônomo?       | Como funciona                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **DIEM por staking de VVV**                | Sim             | Faça staking de VVV no [Smart Contract de Staking Venice](https://basescan.org/address/0x321b7ff75154472B18EDb199033fF4D116F340Ff#code) na Base. A alocação diária de DIEM da carteira é proporcional à sua parcela do pool de staking. A conta precisa acumular pelo menos 0,1 DIEM antes que qualquer DIEM seja gastável. O DIEM se renova às 00:00 UTC. Para aumentar o gasto diário, faça staking de mais VVV. |
| **Recarga em USD ou cripto via dashboard** | Não (navegador) | Faça login em [venice.ai](https://venice.ai) com a mesma carteira (Sign-In-With-Ethereum), e adicione créditos em Configurações, API. Tanto Stripe (cartão) quanto Coinbase (cripto) ficam atrás dessa página e exigem um navegador. Créditos não expiram.                                                                                                                                                         |

Para um agente que roda sem supervisão, **DIEM via staking de VVV é o único caminho totalmente headless de financiamento para uma chave de API emitida hoje**. Se o gasto diário do agente exceder sua alocação de DIEM, as opções realistas são: fazer staking de mais VVV, ou ter um operador para fazer login e recarregar em USD ou cripto.

### Staking autônomo de VVV e geração de chave

Um agente verdadeiramente autônomo pode gerenciar sua própria carteira VVV na Base, fazer staking dela e emitir sua própria chave de API Venice sem nenhum humano no processo. O fluxo completo:

<Steps>
  <Step title="Adquira VVV e ETH para gas">
    Envie VVV para a carteira do agente (ou deixe o agente fazer swap no [Aerodrome](https://aerodrome.finance) ou [Uniswap](https://app.uniswap.org)), mais uma pequena quantidade de ETH na Base para as duas transações de staking.
  </Step>

  <Step title="Faça staking de VVV">
    Faça `approve` do contrato de staking no token VVV, depois `stake(amount)` em `0x321b7ff75154472B18EDb199033fF4D116F340Ff`. O saldo sVVV da carteira é atualizado atomicamente com o stake.
  </Step>

  <Step title="Emita uma chave de API">
    `GET /api/v1/api_keys/generate_web3_key` retorna um JWT que expira 15 minutos após a emissão. Assine o token bruto com a carteira de staking, depois faça `POST` do endereço, assinatura e token de volta. A Venice retorna uma chave de API vinculada à conta de usuário derivada dessa carteira.
  </Step>
</Steps>

A emissão exige apenas um saldo de sVVV diferente de zero, então 1 VVV em staking é suficiente para receber uma chave. **Gastar** com a chave é uma questão separada, governada pela tabela de financiamento acima.

Veja [Criação autônoma de chave de API para agentes](/guides/getting-started/generating-api-key-agent) para o passo a passo completo com código e a referência completa de erros.

## Autenticação por carteira x402 em 30 segundos

Se seu agente já tem uma carteira na Base ou Solana, pule completamente a chave de API. O SDK [`venice-x402-client`](https://github.com/veniceai/x402-client) trata assinatura Sign-In-With-X, 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

const response = await venice.chat({
  model: 'kimi-k2-6',
  messages: [{ role: 'user', content: 'What is the latest block on Base?' }]
})
```

A mesma autenticação por carteira funciona contra `/crypto/rpc/{network}` para leituras e escritas em blockchain. Detalhes completos do protocolo no [guia do x402](/guides/integrations/x402-venice-api).

## Preços

O RPC Crypto é cobrado em créditos Venice. Cada resposta inclui `X-Venice-RPC-Credits` (créditos cobrados) e `X-Venice-RPC-Cost-USD` (custo em dólares) para que seu agente possa rastrear o gasto por requisição.

### Créditos base por chain

| Créditos base | Chains                                                                              |
| ------------- | ----------------------------------------------------------------------------------- |
| **20**        | Ethereum, Base, Optimism, Arbitrum, Polygon, Linea, Avalanche, BSC, Blast, Starknet |
| **30**        | zkSync Era                                                                          |

### Exemplos de custo

Preços observados para os níveis de método standard, advanced e large:

| Chamada                                         | Créditos | Custo em USD  |
| ----------------------------------------------- | -------- | ------------- |
| `eth_call` em Ethereum (20 × 1x)                | 20       | \~\$0,0000140 |
| `trace_transaction` em Ethereum (20 × 2x)       | 40       | \~\$0,0000280 |
| `trace_replayTransaction` em Ethereum (20 × 4x) | 80       | \~\$0,0000560 |
| `eth_call` em zkSync (30 × 1x)                  | 30       | \~\$0,0000210 |

Sempre confie no cabeçalho de resposta `X-Venice-RPC-Cost-USD` para o custo oficial. Itens com erro em requisições em batch são cobrados a um valor fixo de 5 créditos cada.

### Limites de taxa

| Nível    | Requisições por minuto |
| -------- | ---------------------- |
| Standard | 100                    |
| Staff    | 1.000                  |

Quando excedido, o endpoint retorna `429` com cabeçalhos de resposta `X-RateLimit-*` padrão.

## Tratamento de erros

Respostas HTTP comuns que seu agente deve tratar:

| Status | Significado                                                                                                                                                                             | O que fazer                                                                                                                                                                                                                                                  |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | Método JSON-RPC não suportado ou não mapeado, ou batch malformado                                                                                                                       | Verifique o método na [allowlist](/api-reference/endpoint/crypto/rpc). O corpo do erro identifica o método infrator.                                                                                                                                         |
| `400`  | Replay de um `Idempotency-Key` com corpo diferente                                                                                                                                      | Use uma chave nova para requisições distintas.                                                                                                                                                                                                               |
| `402`  | Sem cabeçalho de autenticação (o corpo da resposta inclui `authOptions` listando ambos os caminhos de autenticação suportados), ou sem créditos com um cabeçalho de autenticação válido | Se não há auth: anexe `Authorization: Bearer ...` ou o cabeçalho x402 `X-Sign-In-With-X`. Se sem créditos: com uma chave Bearer, financie a conta (DIEM, USD ou recarga via dashboard); com autenticação x402, chame diretamente `POST /api/v1/x402/top-up`. |
| `429`  | Limite de taxa atingido (100 req/min standard, 1.000 req/min staff)                                                                                                                     | Respeite `X-RateLimit-Reset` e faça back-off. Agrupe até 100 chamadas por requisição para amortizar o limite.                                                                                                                                                |
| `5xx`  | Soluço do nó RPC upstream                                                                                                                                                               | Tente novamente com o mesmo `Idempotency-Key` para evitar cobrança em dobro.                                                                                                                                                                                 |

Erros por item em batch (por exemplo, parâmetros inválidos em uma de N chamadas) voltam dentro de uma resposta `200 OK` com um campo `error` JSON-RPC no item infrator. Esses itens são cobrados a um valor fixo de 5 créditos cada.

## Não suportado

Estas categorias de métodos são rejeitadas intencionalmente:

* **Apenas WebSocket** (`eth_subscribe`, `eth_unsubscribe`): o proxy é apenas HTTP. Use polling.
* **Filtros com estado** (`eth_newFilter`, `eth_getFilterChanges`, etc.): o estado do filtro fica preso a um único backend e quebra em um proxy com balanceamento de carga. Use `eth_getLogs` em vez disso.
* **Métodos que requerem chaves** (`eth_sign`, `eth_accounts`, `eth_mining`): provedores hospedados não guardam chaves de usuário. Assine no cliente e envie via `eth_sendRawTransaction`.
* **Métodos não mapeados**: qualquer coisa fora da allowlist retorna `400`. Entre em contato com o suporte para solicitar adições.

## Recursos

<CardGroup cols={2}>
  <Card title="Referência da API de RPC Crypto" icon="code" href="/api-reference/endpoint/crypto/rpc">
    Lista completa de métodos, preços e cabeçalhos de resposta
  </Card>

  <Card title="Redes suportadas" icon="link" href="/api-reference/endpoint/crypto/networks">
    Lista em tempo real dos slugs de rede suportados
  </Card>

  <Card title="Autenticação por carteira x402" icon="wallet" href="/guides/integrations/x402-venice-api">
    Autentique-se e pague com uma carteira na Base ou Solana
  </Card>

  <Card title="Chave de API para agente autônomo" icon="robot" href="/guides/getting-started/generating-api-key-agent">
    Emita sua própria chave fazendo staking de VVV
  </Card>

  <Card title="Coleção Postman" icon="play" href="https://www.postman.com/veniceai/workspace/venice-ai-workspace/folder/38652128-2cf5a817-41cd-438b-ad37-5d07c3f13005?action=share&creator=48156591&active-environment=38652128-ef110f4e-d3e1-43b5-8029-4d6877e62041">
    27 exemplos de RPC Crypto prontos para executar
  </Card>

  <Card title="Preços" icon="coins" href="/overview/pricing">
    DIEM, preços de créditos e opções de pagamento
  </Card>
</CardGroup>