# Protocolo x402 (Pay-per-Request)
URL: /docs/x402.mdx

Acesse a API da brapi.dev pagando por requisição com USDC na rede Base. Ideal para uso esporádico, agentes de IA e quem prefere pagar com crypto sem criar conta.

***

title: 'Protocolo x402 (Pay-per-Request)'
description:
'Acesse a API da brapi.dev pagando por requisição com USDC na rede Base. Ideal
para uso esporádico, agentes de IA e quem prefere pagar com crypto sem criar
conta.'
-------

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

O **x402** é um protocolo aberto de pagamentos baseado no código de status HTTP
`402 Payment Required`. Ele permite que você acesse endpoints da API pagando por
requisição com **USDC na rede Base**, sem precisar criar conta ou assinar um
plano.

## Por que usar x402?

<Callout title="Ideal para" type="info">
  * **Uso esporádico**: Pague apenas quando usar, sem mensalidade
  * **Agentes de IA**: Pagamentos programáticos machine-to-machine
  * **Crypto-native**: Pague com USDC, sem cartão de crédito
  * **Sem cadastro**: Não precisa de conta, email ou OAuth
</Callout>

| Característica | x402                      | Planos Tradicionais |
| -------------- | ------------------------- | ------------------- |
| Cadastro       | Não precisa               | Obrigatório         |
| Pagamento      | Por requisição (USDC)     | Mensal (cartão/PIX) |
| Ideal para     | Uso esporádico, AI agents | Uso frequente       |
| Settlement     | \~2 segundos (blockchain) | Instantâneo         |

## Requisitos

Para usar os endpoints x402, você precisa:

1. **Carteira crypto** com suporte à rede Base (Coinbase Wallet, MetaMask, etc.)
2. **USDC na rede Base** para pagar as requisições
3. **Cliente x402** implementado no seu código (SDK ou biblioteca)

<Callout title="Rede Base" type="warn">
  O x402 da brapi.dev opera na **rede Base** (L2 da Coinbase). Certifique-se de
  ter USDC na rede correta, não em Ethereum mainnet ou outras redes.
</Callout>

## Como Funciona

O fluxo x402 é simples:

1. Seu cliente faz uma requisição ao endpoint
2. Se não houver pagamento, o servidor responde com `402 Payment Required` e instruções de pagamento
3. Seu cliente prepara e envia o pagamento (assinatura crypto)
4. O servidor verifica o pagamento e retorna os dados

```txt title="Fluxo simplificado"
Cliente → Requisição sem pagamento
Servidor → 402 Payment Required + instruções
Cliente → Requisição com header de pagamento
Servidor → 200 OK + dados
```

## Endpoints Disponíveis

### Endpoints Pagos (x402)

| Endpoint                   | Descrição              | Exemplo                           |
| -------------------------- | ---------------------- | --------------------------------- |
| `/api/x402/stock-quotes`   | Cotações de ações B3   | `?tickers=PETR4,VALE3`            |
| `/api/x402/crypto-prices`  | Preços de criptomoedas | `?coin=BTC&currency=BRL`          |
| `/api/x402/currency-rates` | Taxas de câmbio        | `?currency=USD-BRL`               |
| `/api/x402/inflation`      | Dados de inflação      | `?country=brazil&historical=true` |
| `/api/x402/prime-rate`     | Taxa SELIC             | `?country=brazil&historical=true` |

### Endpoints Gratuitos (Discovery)

Estes endpoints não requerem pagamento e ajudam a descobrir os dados disponíveis:

| Endpoint                                  | Descrição                          |
| ----------------------------------------- | ---------------------------------- |
| `/api/x402/available-stocks`              | Lista ações disponíveis            |
| `/api/x402/available-currencies`          | Lista moedas disponíveis           |
| `/api/x402/available-cryptocurrencies`    | Lista criptomoedas disponíveis     |
| `/api/x402/available-inflation-countries` | Lista países com dados de inflação |

## Exemplos de Requisições

### Cotações de Ações

```bash
https://brapi.dev/api/x402/stock-quotes?tickers=PETR4,MGLU3,VALE3&range=1d&interval=1m&modules=summaryProfile&dividends=true
```

**Parâmetros:**

* `tickers` (obrigatório): Símbolos separados por vírgula
* `interval`: Intervalo (1m, 5m, 15m, 1d, 1wk, 1mo)
* `range`: Período (1d, 5d, 1mo, 3mo, 6mo, 1y, 5y, max)
* `modules`: Módulos adicionais (summaryProfile, balanceSheetHistory, etc.)
* `dividends`: Incluir dividendos (true/false)

### Preços de Criptomoedas

```bash
https://brapi.dev/api/x402/crypto-prices?coin=BTC&currency=BRL&range=1d&interval=1h
```

**Parâmetros:**

* `coin`: Símbolo da cripto (BTC, ETH, etc.)
* `currency`: Moeda de cotação (BRL, USD)
* `range`: Período
* `interval`: Intervalo

### Taxas de Câmbio

```bash
https://brapi.dev/api/x402/currency-rates?currency=USD-BRL
```

**Parâmetros:**

* `currency`: Par de moedas (USD-BRL, EUR-BRL, etc.)

### Inflação

```bash
https://brapi.dev/api/x402/inflation?country=brazil&historical=true&start=01/01/2023&end=31/12/2024&sortBy=date&sortOrder=desc
```

**Parâmetros:**

* `country`: País (brazil)
* `historical`: Dados históricos (true/false)
* `start`: Data inicial (DD/MM/YYYY)
* `end`: Data final (DD/MM/YYYY)
* `sortBy`: Ordenar por (date, value)
* `sortOrder`: Ordem (asc, desc)

### Taxa SELIC

```bash
https://brapi.dev/api/x402/prime-rate?country=brazil&historical=true&start=01/01/2023&end=31/12/2024
```

**Parâmetros:** Mesmos da inflação.

<Callout title="Formato de Data" type="warn">
  Para `start` e `end`, use o formato **DD/MM/YYYY** (ex: `01/01/2023`).
</Callout>

## Implementando o Cliente x402

Para fazer requisições x402, você precisa implementar o lado do cliente do
protocolo. Existem SDKs disponíveis:

<Tabs items={['TypeScript', 'Python']}>
  <Tab value="TypeScript">
    ```bash
    npm install x402-fetch
    ```

    ```typescript
    import { createX402Fetch } from 'x402-fetch';

    const x402Fetch = createX402Fetch({
      walletPrivateKey: process.env.WALLET_PRIVATE_KEY,
    });

    const response = await x402Fetch(
      'https://brapi.dev/api/x402/stock-quotes?tickers=PETR4'
    );
    const data = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```bash
    pip install x402-python
    ```

    ```python
    from x402 import X402Client

    client = X402Client(private_key=os.environ['WALLET_PRIVATE_KEY'])

    response = client.get(
        'https://brapi.dev/api/x402/stock-quotes?tickers=PETR4'
    )
    data = response.json()
    ```
  </Tab>
</Tabs>

<Callout title="Chave Privada" type="error">
  **Nunca exponha sua chave privada no código-fonte ou frontend.** Use variáveis
  de ambiente e mantenha a chave segura no servidor.
</Callout>

## Recursos Adicionais

* [Documentação oficial x402](https://x402.org)
* [Whitepaper x402](https://x402.org/x402-whitepaper.pdf)
* [GitHub x402](https://github.com/coinbase/x402)
* [Guia para Compradores](https://x402.gitbook.io/x402/getting-started/quickstart-for-buyers)

## x402 vs Planos Tradicionais

**Quando usar x402:**

* Você quer testar a API sem compromisso
* Uso esporádico (poucas requisições por mês)
* Você é um agente de IA ou sistema automatizado
* Você prefere pagar com crypto

**Quando usar planos tradicionais:**

* Uso frequente e previsível
* Você precisa de limites de requisição garantidos
* Você prefere pagamento com cartão ou PIX
* Você precisa de suporte prioritário

***

<Callout type="info">
  **Próximos Passos**

  * [Ver documentação completa da API](/docs)
  * [Explorar endpoints de ações](/docs/acoes)
  * [Consultar preços e planos tradicionais](/pricing)
</Callout>