# Pagar por RPC com USDC / USDT / USDG: recarga programática para agentes de IA

> Source: https://docs.blockvectra.com/pt-br/guides/agent-topup/

Desenvolvedores e agentes de IA podem recarregar uma conta RPC e Data API via HTTP: verifique redes e tokens disponíveis, use uma API key existente para obter o endereço de depósito EVM da conta e consulte o status do crédito após transferir os fundos. Antes de enviar fundos, consulte a [página de preços](https://blockvectra.com/en/pricing/) e [estime os custos de RPC e Data API pelos pesos de CU](https://docs.blockvectra.com/en/guides/reading-cu-pricing/).

## Obter seu endereço de depósito em Billing

Entre na conta, [abra Billing para obter seu endereço de depósito](https://console.blockvectra.com/login/?next=%2Fbilling%2F) e use o endereço de depósito e os detalhes de tokens exibidos para sua conta. Verifique as redes, os tokens e o depósito mínimo atuais em [GET /v1/topup/status](https://api.blockvectra.com/v1/topup/status) antes de transferir fundos.

> **API key security and server-side requirement**
>
> O cabeçalho `x-api-key` **só pode ser usado em chamadas de ambientes de servidor**. Nunca chame endpoints de recarga de código no navegador do cliente e nunca exponha sua API key em bundles de frontend, repositórios públicos ou conversas de chat com IA.


## Pré-requisitos

* **API key existente**: chamadas a endpoints de recarga autenticados exigem uma API key RPC BlockVectra ativa. Se ainda não tem uma API key, siga o [guia de cadastro programático](https://docs.blockvectra.com/en/guides/programmatic-signup/) para se cadastrar e criar uma API key com uma assinatura de carteira Ethereum ou crie uma no [Console](https://console.blockvectra.com/login/?next=%2Fkeys%2F).
* **Ativos on-chain**: o ambiente do agente ou a carteira que fornece fundos deve ter USDC / USDT / USDG listadas por `GET /v1/topup/status` em uma rede compatível, além de tokens nativos suficientes para gas para transmitir transações.
* **Variável de ambiente**: armazene sua API key na variável de ambiente `BLOCKVECTRA_API_KEY`.

Os endpoints de recarga autenticados aceitam diretamente o cabeçalho `x-api-key` com a mesma API key usada nas chamadas RPC. Não é necessária uma sessão de navegador.

## Fluxo de recarga em quatro passos

Quando a primeira recarga paga é creditada, as renovações gratuitas por ciclo param, os créditos gratuitos não usados continuam disponíveis e o limite de chamadas por segundo da conta é removido; os limites por API key permanecem iguais. Consulte as [regras de preços](https://blockvectra.com/en/pricing/) e as [regras do plano gratuito](https://blockvectra.com/en/free/#rules); leia os limites atuais e a recarga mínima em [GET /v1/plans](https://console-api.blockvectra.com/v1/plans) (`free`, `key_defaults` e `pricing.min_topup_usd`).

Os endpoints de recarga (status, endereço de depósito e depósitos) usam o host da API de produção:

```
https://api.blockvectra.com
```

Limites de planos e parâmetros de preços são fornecidos pela Console API em `https://console-api.blockvectra.com` (como [GET https://console-api.blockvectra.com/v1/plans](https://console-api.blockvectra.com/v1/plans)).

### 1. Verificar a disponibilidade (GET /v1/topup/status)

Antes de iniciar uma transferência, verifique o status global de recarga, quais redes e tokens estão disponíveis e o limite mínimo de depósito ativo. Este endpoint é público e não exige credenciais.

```bash
curl -s https://api.blockvectra.com/v1/topup/status
```

Exemplo de resposta (redes e tokens selecionados):

```json
{
  "enabled": true,
  "networks": [
    {
      "network": "base_mainnet",
      "chain_id": 8453,
      "token": "USDC",
      "enabled": true
    },
    {
      "network": "bsc_mainnet",
      "chain_id": 56,
      "token": "USDT",
      "enabled": true
    },
    {
      "network": "bsc_mainnet",
      "chain_id": 56,
      "token": "USDC",
      "enabled": true
    }
  ]
}
```

* `enabled`: chave global de ativação. Se for `false`, a recarga está fechada em todas as redes.
* `networks`: status de disponibilidade por rede e token. Quando `enabled` é `false` para uma rede ou token, **não transfira fundos nessa rede**.
* `min_deposit_usd`: valor mínimo global de depósito em USD, formatado com 6 casas decimais. O limite mínimo de depósito é dinâmico: sempre consulte o `min_deposit_usd` retornado em tempo real por `GET https://api.blockvectra.com/v1/topup/status`.

Para consultar diretamente o `min_deposit_usd` ativo:

```bash
curl -s https://api.blockvectra.com/v1/topup/status | jq -r .min_deposit_usd
```

### 2. Obter endereço de depósito e parâmetros (GET /v1/topup/deposit-address)

Obtenha ou aloque o endereço de depósito EVM do cliente e inspecione redes compatíveis e contratos de tokens. Este endpoint exige autenticação `x-api-key` e deve ser chamado apenas de ambientes de servidor.

```bash
curl -s \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  https://api.blockvectra.com/v1/topup/deposit-address
```

Exemplo de resposta (redes e tokens selecionados):

```json
{
  "address": "0x<your-dedicated-deposit-address>",
  "deposits_url": "https://api.blockvectra.com/v1/topup/deposits",
  "networks": [
    {
      "chain": "base_mainnet",
      "chain_id": 8453,
      "name": "Base",
      "typical_credit_seconds": 30,
      "explorer_tx_url": "https://basescan.org/tx/{tx_hash}",
      "tokens": [
        {
          "symbol": "USDC",
          "contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "decimals": 6,
          "min_amount_raw": "1000000"
        }
      ]
    },
    {
      "chain": "bsc_mainnet",
      "chain_id": 56,
      "name": "BNB Smart Chain",
      "typical_credit_seconds": 60,
      "explorer_tx_url": "https://bscscan.com/tx/{tx_hash}",
      "tokens": [
        {
          "symbol": "USDT",
          "contract": "0x55d398326f99059fF775485246999027B3197955",
          "decimals": 18,
          "min_amount_raw": "1000000000000000000"
        },
        {
          "symbol": "USDC",
          "contract": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
          "decimals": 18,
          "min_amount_raw": "1000000000000000000"
        }
      ]
    }
  ]
}
```

* `address`: endereço de depósito EVM exclusivo da sua conta com checksum EIP-55.
* `deposits_url`: URL para consultar registros de depósitos do cliente.
* `networks`: lista de redes EVM disponíveis. Redes fechadas são omitidas. Inclui slug da rede `chain`, Chain ID EVM `chain_id`, nome de exibição `name`, latência típica de crédito em segundos após inclusão no bloco `typical_credit_seconds` e template de URL de transação no explorador de blocos `explorer_tx_url`.
* `tokens`: tokens nesta rede, incluindo símbolo `symbol` (USDC / USDT / USDG), endereço do contrato `contract`, casas decimais `decimals` e depósito mínimo em unidades atômicas brutas `min_amount_raw` (consulte o valor real retornado pelo endpoint; não presuma uma quantidade ajustada).

> **Token decimals and amount conversion**
>
> O mesmo token pode ter casas decimais diferentes em redes diferentes (por exemplo, USDT e USDC na BSC têm 18 casas decimais, enquanto USDC na Base tem 6). O cálculo de quantidades deve usar o `decimals` retornado para aquela rede específica, em vez de fixar um único valor de casas decimais para o token.


#### Respostas de erro

Endpoints de recarga autenticados (`/v1/topup/deposit-address` e `/v1/topup/deposits`) retornam estruturas de erro JSON padrão:

* **HTTP 401 (Falha de autenticação)**: retornado quando o cabeçalho `x-api-key` está ausente (`missing_api_key`) ou a API key é inválida, revogada ou desativada (`invalid_api_key`):

```json
{
  "error": {
    "code": "missing_api_key",
    "message": "missing API key: send it in the x-api-key header",
    "data": {
      "reason": "missing_api_key",
      "docs_url": "https://docs.blockvectra.com/en/errors/#missing_api_key",
      "retryable": false
    }
  }
}
```

* **HTTP 409 (Recarga desativada)**: retornado quando a recarga está fechada globalmente ou em todas as redes (`topup_disabled`):

```json
{
  "error": {
    "code": "topup_disabled",
    "data": {
      "reason": "topup_disabled",
      "docs_url": "https://docs.blockvectra.com/en/errors/#topup_disabled",
      "retryable": false
    }
  }
}
```

Para a lista completa de códigos de erro, consulte a [Referência de erros](https://docs.blockvectra.com/en/errors/).

### 3. Transmitir a transferência on-chain

Usando a carteira ou o script do agente, envie uma transação ERC-20 `transfer` para o `address` de depósito obtido no passo 2.

Requisitos da transferência:

* Envie apenas tokens e contratos listados no array `tokens` daquela rede.
* Garanta que a quantidade transferida seja maior ou igual a `min_amount_raw` (conforme o valor real retornado por `GET /v1/topup/deposit-address` ou `min_deposit_usd` retornado por `GET /v1/topup/status`), formatada conforme o `decimals` do token naquela rede.
* Transferências enviadas a redes não compatíveis ou com tokens incorretos não podem ser creditadas automaticamente; verifique a rede e o contrato do token antes de transmitir.
* Registre o hash da transação on-chain (`tx_hash`) após o envio.

### 4. Consultar registros de depósitos e verificar o crédito (GET /v1/topup/deposits)

Depois que a transação for incluída em um bloco, consulte o histórico de transferências de depósito para acompanhar o status do crédito. Este endpoint exige `x-api-key` e é exclusivo para servidores.

#### Parâmetros de consulta

* `limit`: quantidade de registros de depósito por página. O padrão é `20`; o intervalo válido é `1`–`100`.
* `before`: parâmetro de paginação por cursor baseado em `deposit_id`. Envie o valor `next_before` da resposta anterior para obter a próxima página de registros mais antigos.
* `tx_hash`: hash de transação hexadecimal opcional de 64 caracteres com prefixo 0x para filtrar uma transferência específica.

Filtre pelo hash da transação (`tx_hash`) para inspecionar sua transferência específica:

```bash
curl -s \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  "https://api.blockvectra.com/v1/topup/deposits?tx_hash=0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
```

Exemplo de resposta:

```json
{
  "items": [
    {
      "deposit_id": 42,
      "chain": "base_mainnet",
      "chain_id": 8453,
      "token": "USDC",
      "contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "25.000000",
      "tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "tx_log_ordinal": 0,
      "block_number": 123456789,
      "external_ref": "eip155:8453:0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890:0",
      "status": "credited",
      "reason": null,
      "credited_units": 250000,
      "credited_cu": 250000000,
      "detected_at": "2026-10-02T10:00:00Z"
    }
  ],
  "next_before": null
}
```

* `items`: array de registros de depósito que correspondem aos parâmetros de consulta.
* `next_before`: ID de cursor para a próxima página quando há mais registros ou `null` se não há registros anteriores. Combine com o parâmetro de consulta `before` para paginação por cursor.

Valores de `status` do depósito:

* `processing`: transferência detectada on-chain, crédito em andamento.
* `credited`: creditado no saldo da conta. `credited_units` e `credited_cu` indicam as quantidades creditadas.
* `not_credited`: a transferência não pode ser creditada. O campo `reason` indica a causa:
  * `below_minimum`: a quantidade depositada está abaixo do limite mínimo.
  * `large_amount`: a quantidade depositada ultrapassa o limite e exige análise manual.
  * `other`: outra exceção de crédito.

Latência de crédito e orientação de polling:

* **Tempo de chegada e crédito**: o tempo de crédito é determinado pelo `typical_credit_seconds` retornado no passo 2.
* **Intervalo de polling**: consulte no intervalo recomendado de **20–60 segundos**, sem aumentar a frequência, para evitar limites de taxa.

## Exemplos de código

Os exemplos abaixo demonstram como ler `BLOCKVECTRA_API_KEY` do ambiente e consultar endpoints de recarga em Node.js e Python.

### Node.js (fetch)

```javascript
import process from "node:process";

const apiKey = process.env.BLOCKVECTRA_API_KEY;
if (!apiKey) {
  throw new Error("Missing BLOCKVECTRA_API_KEY environment variable");
}

const BASE_URL = "https://api.blockvectra.com";

// 1. Check availability and read minimum deposit threshold
const statusRes = await fetch(`${BASE_URL}/v1/topup/status`);
const status = await statusRes.json();
if (!status.enabled) {
  throw new Error("Top-up is currently disabled");
}
const minDepositUsd = status.min_deposit_usd;
console.log("Minimum deposit (USD):", minDepositUsd);

// 2. Retrieve deposit address and open networks
const addressRes = await fetch(`${BASE_URL}/v1/topup/deposit-address`, {
  headers: { "x-api-key": apiKey },
});

if (addressRes.status === 401) {
  throw new Error("Missing or invalid API key (HTTP 401)");
}
if (addressRes.status === 409) {
  throw new Error("Top-up is disabled (topup_disabled)");
}
if (!addressRes.ok) {
  throw new Error(`Failed to retrieve deposit address: ${addressRes.status}`);
}

const depositData = await addressRes.json();
console.log("Deposit address:", depositData.address);
console.log("Open networks count:", depositData.networks.length);

// 3. Poll deposit status
async function checkDepositStatus(txHash) {
  const url = new URL(`${BASE_URL}/v1/topup/deposits`);
  url.searchParams.set("tx_hash", txHash);

  const res = await fetch(url, {
    headers: { "x-api-key": apiKey },
  });
  if (res.status === 401) {
    throw new Error("Missing or invalid API key (HTTP 401)");
  }
  if (!res.ok) {
    throw new Error(`Failed to query deposits: ${res.status}`);
  }
  return res.json();
}
```

### Python (requests)

```python
# pip install requests
import os
import requests

api_key = os.environ.get("BLOCKVECTRA_API_KEY")
if not api_key:
    raise ValueError("Missing BLOCKVECTRA_API_KEY environment variable")

base_url = "https://api.blockvectra.com"

# 1. Check availability and read minimum deposit threshold
resp = requests.get(f"{base_url}/v1/topup/status", timeout=10)
resp.raise_for_status()
status_data = resp.json()
if not status_data.get("enabled"):
    raise RuntimeError("Top-up is currently disabled")
min_deposit_usd = status_data.get("min_deposit_usd")
print("Minimum deposit (USD):", min_deposit_usd)

# 2. Retrieve deposit address
resp = requests.get(
    f"{base_url}/v1/topup/deposit-address",
    headers={"x-api-key": api_key},
    timeout=10,
)
if resp.status_code == 401:
    raise RuntimeError("Missing or invalid API key (HTTP 401)")
if resp.status_code == 409:
    raise RuntimeError("Top-up is disabled (topup_disabled)")
resp.raise_for_status()
deposit_data = resp.json()
print("Deposit address:", deposit_data["address"])

# 3. Poll deposit status
def check_deposit_status(tx_hash: str):
    resp = requests.get(
        f"{base_url}/v1/topup/deposits",
        headers={"x-api-key": api_key},
        params={"tx_hash": tx_hash},
        timeout=10,
    )
    if resp.status_code == 401:
        raise RuntimeError("Missing or invalid API key (HTTP 401)")
    resp.raise_for_status()
    return resp.json()
```

## Próximos passos

* [Consultar saldo (`GET /v1/account`)](https://docs.blockvectra.com/en/guides/billing-rules/#query-balance-get-v1account) para verificar o saldo da conta e as Compute Units (CU) restantes.
* [Regras de cobrança](https://docs.blockvectra.com/en/guides/billing-rules/) para consultar medição de Compute Units (CU), limites de taxa e erros sem cobrança.
* [Guia do plano gratuito](https://docs.blockvectra.com/en/guides/free-plan/) para consultar limites do plano gratuito e regras de ampliação de capacidade.
* [Guia de cadastro programático](https://docs.blockvectra.com/en/guides/programmatic-signup/) para criar contas e provisionar API keys com assinaturas de carteira.