> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Realizar Pagamentos com Agentes

> Permita que agentes de IA paguem por APIs em stablecoins a partir de uma carteira Blockradar, sem que a chave privada saia da Blockradar

<Note>
  Em resumo<br />
  Agentes de IA podem pagar por APIs e dados a cada requisição, em stablecoins, por meio de protocolos abertos de pagamento para agentes. Com a Blockradar, um agente paga a partir de uma carteira cuja chave privada nunca sai da Blockradar, usando o endpoint de [Assinatura de Dados Tipados](/pt/essentials/signing#assinatura-de-dados-tipados-apenas-evm) que você já tem.
</Note>

## Protocolos Suportados

| Protocolo | Redes e tokens |
| - | - |
| [x402](https://www.x402.org) | Chains EVM, USDC (EIP-3009) |

<Tip>
  Vende para agentes? Consulte [Aceitar Pagamentos de Agentes](/pt/use-cases/accept-agent-payments).
</Tip>

## Pré-requisitos

<Steps>
  <Step title="Chave API">
    Obtenha sua chave API no [Painel da Blockradar](https://dashboard.blockradar.co). Navegue até **Developers** para gerar uma.
  </Step>

  <Step title="Carteira Principal EVM">
    Crie uma carteira principal pelo painel na chain em que a API cobra, como a Base (consulte [Criar uma Carteira Principal](/pt/guides/create-master-wallet)). Pagamentos por agentes via Blockradar funcionam apenas em EVM.
  </Step>

  <Step title="USDC Habilitado">
    Habilite o USDC na carteira para que saldos e depósitos sejam rastreados. Consulte [Gestão de Ativos](/pt/use-cases/asset-management).
  </Step>
</Steps>

## Dê ao Agente um Orçamento Próprio

<Warning>
  A assinatura não tem limite de gasto por pagamento<br />
  Qualquer pessoa com uma chave API com acesso a uma carteira pode assinar um pagamento de qualquer valor a partir dessa carteira ou de seus endereços. A Blockradar não limita o que um agente assina. Reduza o estrago que um agente com mau comportamento ou uma chave vazada pode causar dando ao agente um endereço dedicado que guarde apenas o que ele tem permissão para gastar.
</Warning>

Um endereço filho com a varredura automática desativada funciona bem como orçamento de um agente. Abasteça-o com o valor que o agente pode gastar, e o agente nunca poderá pagar mais do que esse saldo.

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.blockradar.co/v1/wallets/{walletId}/addresses \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
      "name": "Research agent budget",
      "disableAutoSweep": true,
      "metadata": {
        "purpose": "agent-payments"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/addresses`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        name: 'Research agent budget',
        disableAutoSweep: true,
        metadata: { purpose: 'agent-payments' }
      })
    }
  ).then(r => r.json());

  console.log('Agent address:', response.data.address);
  console.log('Address ID:', response.data.id);
  ```
</CodeGroup>

<Note>
  Mantenha `disableAutoSweep: true` no endereço de um agente. Com a varredura automática ativada, o USDC que você envia para abastecer o agente é varrido para a carteira principal, e os pagamentos do agente falham por falta de fundos.
</Note>

Pagar a partir da carteira principal também funciona. Use os endpoints da carteira principal nos exemplos abaixo e omita o `addressId`. Todo o saldo da carteira principal fica então ao alcance do agente, então faça isso apenas com uma carteira principal dedicada ao agente.

No [Plano de Checkout](/pt/use-cases/checkout#plano-de-checkout), as operações com endereços filhos não estão disponíveis, então use uma carteira principal dedicada ao agente.

***

## Como o x402 Funciona

O [x402](https://www.x402.org) é um protocolo aberto que permite que uma API cobre por requisição: ela responde com HTTP `402 Payment Required`, e quem chamou repete a requisição com um pagamento em USDC assinado. O x402 tem três partes: o **comprador** (seu agente), o **vendedor** (a API que está sendo paga) e um **facilitador** que verifica o pagamento e o submete on-chain.

<Steps>
  <Step title="A API pede o pagamento">
    O agente chama um endpoint pago. A API responde com `402 Payment Required` e um header `PAYMENT-REQUIRED` listando o que aceita: rede, token, valor e o endereço `payTo`.
  </Step>

  <Step title="A Blockradar assina o pagamento">
    O agente transforma uma dessas opções em um `TransferWithAuthorization` [EIP-3009](https://eips.ethereum.org/EIPS/eip-3009) e o assina com o endpoint de dados tipados da Blockradar. Nada é enviado on-chain ainda.
  </Step>

  <Step title="O agente repete a requisição com a assinatura">
    O agente repete a requisição com o pagamento assinado no header `PAYMENT-SIGNATURE`.
  </Step>

  <Step title="O facilitador liquida">
    O facilitador do vendedor verifica a assinatura e submete a transferência on-chain, pagando ele mesmo o gas. A API retorna a resposta, com o resultado da liquidação em um header `PAYMENT-RESPONSE`.
  </Step>
</Steps>

A carteira do agente precisa de **USDC, mas não de gas**. A assinatura autoriza uma única transferência de um valor exato para um endereço exato, e o facilitador não pode alterar nenhum dos dois.

***

## Pagar com x402

Abasteça primeiro o endereço do agente, conforme descrito em [Dê ao Agente um Orçamento Próprio](#dê-ao-agente-um-orçamento-próprio).

### Opção 1: Usar o SDK cliente do x402

O cliente oficial [`@x402/fetch`](https://www.npmjs.com/package/@x402/fetch) cuida da troca 402 para você. Ele só precisa de um signer com um `address` e um método `signTypedData`. O adaptador abaixo implementa esse signer sobre o endpoint de dados tipados da Blockradar, de modo que a chave permanece na Blockradar.

```bash theme={null}
npm install @x402/fetch @x402/evm
```

```javascript JavaScript theme={null}
import { wrapFetchWithPaymentFromConfig, decodePaymentResponseHeader } from '@x402/fetch';
import { ExactEvmScheme } from '@x402/evm';

// An x402 signer whose key stays in Blockradar. Pass addressId to pay from a child address.
function blockradarSigner({ apiKey, walletId, addressId, address }) {
  const path = addressId
    ? `/wallets/${walletId}/addresses/${addressId}/signing/typed-data`
    : `/wallets/${walletId}/signing/typed-data`;

  return {
    address,
    async signTypedData({ domain, types, message }) {
      // Blockradar derives the domain type from `domain`, so EIP712Domain must not be in `types`
      const { EIP712Domain, ...signTypes } = types;

      const res = await fetch(`https://api.blockradar.co/v1${path}`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
        // x402 passes uint256 values as BigInt, which JSON.stringify cannot serialize
        body: JSON.stringify({ domain, types: signTypes, message }, (_, v) =>
          typeof v === 'bigint' ? v.toString() : v
        ),
      });
      const body = await res.json();
      if (!res.ok) {
        throw new Error(`Blockradar signing failed: ${JSON.stringify(body.message)}`);
      }
      if (body.data.senderAddress.toLowerCase() !== address.toLowerCase()) {
        throw new Error(`Signed by ${body.data.senderAddress}, expected ${address}`);
      }
      return body.data.signedTransaction.signature;
    },
  };
}

const signer = blockradarSigner({
  apiKey: process.env.BLOCKRADAR_API_KEY,
  walletId: process.env.BLOCKRADAR_WALLET_ID,
  addressId: process.env.BLOCKRADAR_ADDRESS_ID, // omit to pay from the master wallet
  address: process.env.AGENT_ADDRESS,           // the address that holds the USDC
});

const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: 'eip155:8453', client: new ExactEvmScheme(signer) }], // Base mainnet
});

const response = await fetchWithPayment('https://api.example.com/premium-data');
console.log(await response.json());

const settlement = response.headers.get('PAYMENT-RESPONSE');
if (settlement) {
  console.log(decodePaymentResponseHeader(settlement)); // { success, transaction, network, payer }
}
```

Registre um scheme por rede em que o agente paga (`eip155:84532` para a Base Sepolia durante os testes), com uma carteira nessa chain por trás de cada um.

### Opção 2: Montar o pagamento você mesmo

Sem o SDK, ou em outra linguagem, um pagamento exige três chamadas HTTP: a primeira requisição, a chamada de assinatura à Blockradar e a nova tentativa paga. Os passos abaixo pagam 0,01 USDC na Base.

#### Passo 1: Ler os requisitos de pagamento

Chame a API. Uma resposta `402` traz um header `PAYMENT-REQUIRED` codificado em base64. Decodificado, ele fica assim:

```json theme={null}
{
  "x402Version": 2,
  "error": "PAYMENT-SIGNATURE header is required",
  "resource": {
    "url": "https://api.example.com/premium-data",
    "description": "Access to premium market data",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "10000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "maxTimeoutSeconds": 60,
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ]
}
```

Escolha uma entrada em `accepts` que sua carteira possa pagar:

* `scheme` é `exact`.
* `network` é a chain da carteira. `eip155:8453` é a Base mainnet.
* `extra.assetTransferMethod` está ausente ou é `eip3009`. O método `permit2` exige antes uma aprovação de token on-chain, que custa gas, por isso este guia não o aborda.

`amount` está na menor unidade do token. O USDC tem 6 casas decimais, então `10000` equivale a 0,01 USDC.

#### Passo 2: Assinar a autorização

Monte o `TransferWithAuthorization` a partir dos requisitos e assine-o a partir do endereço do agente:

| Campo | Valor |
| - | - |
| `domain.name`, `domain.version` | `extra.name` e `extra.version` |
| `domain.chainId` | O número após `eip155:` em `network`, como um número JSON |
| `domain.verifyingContract` | `asset`, o contrato do USDC |
| `message.from` | O endereço do agente |
| `message.to` | `payTo` |
| `message.value` | `amount` |
| `message.validAfter` | Um horário Unix um pouco no passado, como agora menos 600 segundos |
| `message.validBefore` | Agora mais `maxTimeoutSeconds` |
| `message.nonce` | 32 bytes aleatórios em hex. Gere um novo para cada pagamento |

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/signing/typed-data \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
      "domain": {
        "name": "USD Coin",
        "version": "2",
        "chainId": 8453,
        "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
      },
      "types": {
        "TransferWithAuthorization": [
          { "name": "from", "type": "address" },
          { "name": "to", "type": "address" },
          { "name": "value", "type": "uint256" },
          { "name": "validAfter", "type": "uint256" },
          { "name": "validBefore", "type": "uint256" },
          { "name": "nonce", "type": "bytes32" }
        ]
      },
      "message": {
        "from": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a",
        "to": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
        "value": "10000",
        "validAfter": "1791106604",
        "validBefore": "1791107264",
        "nonce": "0x312a453ed3d129ba71de863aa623245c0e5e120bad410d995cea6739aa8ee98b"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  import { randomBytes } from 'node:crypto';

  const now = Math.floor(Date.now() / 1000);
  const authorization = {
    from: agentAddress,
    to: accepted.payTo,
    value: accepted.amount,
    validAfter: String(now - 600),
    validBefore: String(now + accepted.maxTimeoutSeconds),
    nonce: '0x' + randomBytes(32).toString('hex'),
  };

  const res = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}/signing/typed-data`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
      body: JSON.stringify({
        domain: {
          name: accepted.extra.name,
          version: accepted.extra.version,
          chainId: Number(accepted.network.split(':')[1]),
          verifyingContract: accepted.asset,
        },
        types: {
          TransferWithAuthorization: [
            { name: 'from', type: 'address' },
            { name: 'to', type: 'address' },
            { name: 'value', type: 'uint256' },
            { name: 'validAfter', type: 'uint256' },
            { name: 'validBefore', type: 'uint256' },
            { name: 'nonce', type: 'bytes32' },
          ],
        },
        message: authorization,
      }),
    }
  );
  const signed = await res.json();
  if (!res.ok) throw new Error(`Signing failed: ${JSON.stringify(signed.message)}`);

  const signature = signed.data.signedTransaction.signature;
  ```
</CodeGroup>

Para assinar a partir da carteira principal, use `POST /v1/wallets/{walletId}/signing/typed-data` e defina `from` como o endereço da carteira principal. A resposta é a [resposta de dados tipados](/pt/essentials/signing#resposta-de-dados-tipados) padrão; a assinatura fica em `data.signedTransaction.signature`.

#### Passo 3: Repetir a requisição com o pagamento

Envolva a assinatura e a autorização em um payload de pagamento, codifique-o em base64 e envie-o no header `PAYMENT-SIGNATURE` na mesma requisição:

```javascript JavaScript theme={null}
const paymentPayload = {
  x402Version: 2,
  resource: paymentRequired.resource,
  accepted,                              // the entry you chose from `accepts`
  payload: { signature, authorization },
};

const paid = await fetch('https://api.example.com/premium-data', {
  headers: {
    'PAYMENT-SIGNATURE': Buffer.from(JSON.stringify(paymentPayload)).toString('base64'),
  },
});
```

#### Passo 4: Verificar a liquidação

Uma resposta bem-sucedida inclui um header `PAYMENT-RESPONSE` codificado em base64:

```json theme={null}
{
  "success": true,
  "transaction": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "network": "eip155:8453",
  "payer": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a"
}
```

`transaction` é o hash on-chain da transferência de USDC. Se o pagamento falhar, a API responde `402` novamente, e o `PAYMENT-RESPONSE` traz um `errorReason` como `insufficient_funds`.

<Accordion title="Chamando uma API x402 v1">
  Servidores na versão 1 do x402 diferem do fluxo acima em quatro pontos:

  * Os requisitos de pagamento vêm no **corpo** da resposta `402`, não em um header.
  * As redes têm nomes (`base`, `base-sepolia`) em vez de `eip155:<chainId>`. A Base tem chain ID `8453`; a Base Sepolia, `84532`.
  * O campo de valor é `maxAmountRequired`, não `amount`.
  * O pagamento vai no header `X-PAYMENT` como JSON codificado em base64 com `x402Version: 1`, `scheme`, `network` e o mesmo objeto `payload`, e a liquidação volta em `X-PAYMENT-RESPONSE`.

  O passo de assinatura com a Blockradar é idêntico.
</Accordion>

### Regras de assinatura que costumam quebrar integrações

| Regra | O que acontece caso contrário |
| - | - |
| `domain.chainId` é um número JSON que corresponde à chain da carteira | `400 Chain ID mismatch`. `"8453"` como string também falha. |
| `types` contém apenas `TransferWithAuthorization` | Incluir `EIP712Domain` em `types` falha com um erro `ambiguous primary types or unused types`. A Blockradar monta o tipo do domínio a partir de `domain`. |
| `message.from` é o endereço que assina | O facilitador rejeita o pagamento porque a assinatura recupera um endereço diferente. |
| Um `nonce` novo para cada pagamento | O USDC rejeita um nonce reutilizado, então o pagamento não pode ser liquidado. |
| O endereço pagador tem USDC suficiente | O facilitador rejeita o pagamento com um motivo de saldo insuficiente. Gas não é necessário. |

Cada assinatura é registrada como uma transação `SIGNED` e dispara um [webhook](/pt/essentials/signing#eventos-de-webhook) `signed.success`, o que dá a você uma trilha de auditoria de cada pagamento que seu agente autorizou. Uma assinatura não é um pagamento: o USDC só se move quando o facilitador do vendedor o liquida. Quando o vendedor está fora da Blockradar, a liquidação aparece como uma transferência de saída a partir do endereço do agente. Para conciliar, compare os webhooks `signed.success` com a transação on-chain do cabeçalho `PAYMENT-RESPONSE`.

***

## Limitações do x402

* **Apenas EVM.** Os pagamentos são assinados com dados tipados EIP-712, que a Blockradar suporta apenas em chains EVM. Solana e outras redes x402 não EVM não são suportadas.
* **Apenas pagamentos `exact` EIP-3009.** Tokens com `transferWithAuthorization`, como o USDC, funcionam. O método de transferência `permit2` e outros schemes não são abordados.
* **Sem nanopagamentos do Circle Gateway.** A opção de pagamentos em lote abaixo de um centavo da Circle não foi testada com carteiras Blockradar.

***

## Melhores Práticas

* **Imponha limites no seu agente.** A Blockradar assina qualquer requisição bem formada de uma chave API válida. Coloque limites por pagamento e por dia no código do seu agente e limite a exposição total com o saldo do endereço do agente.
* **Um endereço por agente.** Orçamentos separados deixam claro qual agente gastou o quê e permitem cortar um agente esvaziando o endereço dele.
* **Verifique o preço antes de assinar.** Compare `amount` com o máximo que seu agente deveria pagar por aquele recurso e recuse qualquer valor acima disso.
* **Verifique o destinatário.** Se seu agente só paga APIs conhecidas, mantenha uma allowlist de endereços `payTo`.
* **Use `metadata` e webhooks.** Marque os endereços dos agentes com `metadata` e concilie os webhooks `signed.success` com a transação on-chain de cada `PAYMENT-RESPONSE`.
* **Restrinja o acesso à API.** Aceite requisições de API apenas dos seus próprios servidores com [IP Whitelisting](/pt/use-cases/ip-whitelist), para que uma chave vazada não possa ser usada em outro lugar.
* **Teste primeiro na Base Sepolia.** Use uma carteira de testnet, `eip155:84532`, e USDC de testnet dos [faucets](/pt/use-cases/supported-assets) antes de gastar fundos reais.

***

## Referência API

| Endpoint | Descrição |
| - | - |
| [Sign Typed Data (Master Wallet)](/pt/api-reference/signing/master-wallet-typed-data) | Assinar uma autorização de pagamento a partir de uma carteira principal |
| [Sign Typed Data (Child Address)](/pt/api-reference/signing/child-address-typed-data) | Assinar uma autorização de pagamento a partir de um endereço filho |
| [Generate Address](/pt/api-reference/addresses/generate-address) | Criar um endereço dedicado para o orçamento de um agente |
| [Update Address](/pt/api-reference/addresses/update-address) | Ativar ou desativar a varredura automática de um endereço |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.