DataBR Python SDK

Python SDK for DataBR — Brazilian public data API with automatic x402 payments.

Install

pip install databr

Quick Start

from databr import DataBR

client = DataBR(private_key="0x...")

# BCB — Taxa Selic
selic = client.bcb.selic()
print(selic.data)  # {"valor": "14.25", ...}

# Empresa por CNPJ
empresa = client.empresas.consultar("33000167000101")
print(empresa.data["razao_social"])

# Compliance check
compliance = client.compliance.verificar("33000167000101")

How It Works

The SDK handles the x402 payment protocol automatically:

1. You call client.bcb.selic()
2. The API returns HTTP 402 (Payment Required)
3. The SDK signs a USDC payment on Base network
4. The SDK retries with the payment proof
5. You get the data back

You need USDC on Base network in the wallet corresponding to your private key.

API Reference

Low-Level API

# Direct path access
resp = client.get("/v1/bcb/selic")
resp = client.get("/v1/empresas/33000167000101", format="context")

# Query parameters
resp = client.get("/v1/economia/ipca", fields=["valor"], since="2026-01-01")

# POST endpoints
resp = client.post("/v1/carteira/risco", body={"cnpjs": ["33000167000101"]})

Namespaces

Query Parameters

All methods accept these keyword arguments:

Response

resp = client.bcb.selic()
resp.source           # "bcb_sgs"
resp.data             # {"valor": "14.25", ...}
resp.context          # None (or LLM text if format="context")
resp.updated_at       # datetime(2026, 2, 23, ...)
resp.cached           # True
resp.cache_age_seconds # 3600
resp.cost_usdc        # "0.003"
resp.raw              # full JSON dict

Error Handling

from databr import DataBR, NotFoundError, PaymentError, RateLimitError

client = DataBR(private_key="0x...")

try:
    empresa = client.empresas.consultar("00000000000000")
except NotFoundError:
    print("CNPJ not found")
except PaymentError:
    print("Payment failed — check USDC balance")
except RateLimitError as e:
    print(f"Rate limited — retry in {e.retry_after}s")

Networks

# Testnet for development
client = DataBR(private_key="0x...", network="testnet")

License

MIT