Protocolo x402 (Pay-per-Request)

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?

Ideal para

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

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:

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

Rede Base

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.

Como Funciona

O fluxo x402 é simples:

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

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

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

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

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

Parâmetros:

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

Inflação

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

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.

Formato de Data

Para start e end, use o formato DD/MM/YYYY (ex: 01/01/2023).

Implementando o Cliente x402

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

npm install x402-fetch

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();

pip install x402-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()

Chave Privada

Nunca exponha sua chave privada no código-fonte ou frontend. Use variáveis de ambiente e mantenha a chave segura no servidor.

Recursos Adicionais

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

Próximos Passos

Por que usar x402?

Ideal para

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

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:

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

Rede Base

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.

Como Funciona

O fluxo x402 é simples:

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

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

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

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

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

Parâmetros:

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

Inflação

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

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.

Formato de Data

Para start e end, use o formato DD/MM/YYYY (ex: 01/01/2023).

Implementando o Cliente x402

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

npm install x402-fetch

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();

pip install x402-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()

Chave Privada

Nunca exponha sua chave privada no código-fonte ou frontend. Use variáveis de ambiente e mantenha a chave segura no servidor.

Recursos Adicionais

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

Próximos Passos

Por que usar x402?

Requisitos

Como Funciona

Endpoints Disponíveis

Endpoints Pagos (x402)

Endpoints Gratuitos (Discovery)

Exemplos de Requisições

Cotações de Ações

Preços de Criptomoedas

Taxas de Câmbio

Inflação

Taxa SELIC

Implementando o Cliente x402

Recursos Adicionais

x402 vs Planos Tradicionais

Índice

Protocolo x402 (Pay-per-Request)

Por que usar x402?

Requisitos

Como Funciona

Endpoints Disponíveis

Endpoints Pagos (x402)

Endpoints Gratuitos (Discovery)

Exemplos de Requisições

Cotações de Ações

Preços de Criptomoedas

Taxas de Câmbio

Inflação

Taxa SELIC

Implementando o Cliente x402

Recursos Adicionais

x402 vs Planos Tradicionais

Índice