# Brazilayer — Brazilian Company Data (CNPJ) API, paid per call via x402
# Base URL: https://api.brazilayer.com

> Official registration data for all ~69 million Brazilian companies, straight from the
> Receita Federal (Brazilian IRS) CNPJ public registry, updated monthly. No API keys,
> no signup: every paid endpoint speaks the x402 payment protocol (USDC on Base).
> Try the free sample first to learn the response format.

## How to use

1. GET /v1/cnpj/amostra (free) — full sample response for one fixed company, so you can
   learn the schema before paying. GET /v1/health (free) — service status + data
   reference month.
2. Call any paid endpoint without payment: you get HTTP 402 with a `payment-required`
   header (base64 JSON) describing price, network, asset (USDC) and pay-to address.
3. Pay with the x402 protocol (scheme "exact", EIP-3009 USDC authorization) and retry
   with the payment header. Any x402 client library handles this automatically
   (e.g. @x402/fetch for TypeScript).

Response keys are in Portuguese, mirroring official Brazilian legal terms (razao_social
= legal name, nome_fantasia = trade name, situacao_cadastral = registration status,
cnae = economic activity code, socios = partners/shareholders). Every paid response
includes `fonte` (source + reference month). Full JSON schemas: /openapi.yaml

## Datasets

CNPJ Registry (live). More Brazilian public datasets (official gazettes, court
records, public tenders) are planned under the same payment rails and base URL.

## CNPJ Registry — paid endpoints (USD prices, paid in USDC)

- GET /v1/cnpj/empresa/{cnpj} — $0.005 — company registration card: legal name, status,
  legal nature, share capital, CNAE activities, address, contact, Simples/MEI flags.
- GET /v1/cnpj/empresa/{cnpj}/socios — $0.005 — partners/shareholders with role, masked
  tax id (CPF comes pre-masked from the government source), entry date, age bracket.
- GET /v1/cnpj/empresa/{cnpj}/completo — $0.01 — bundle: registration + partners + all
  branches (filiais) in one call. Best value for a full company profile.
- GET /v1/cnpj/busca — $0.01 — search companies by nome (full-text, accent-insensitive),
  uf (state), municipio (4-digit RFB city code), cnae, porte (size), situacao
  (status, default "ativa"). Paginated (max 50/page); total capped at "10000+".
- GET /v1/cnpj/socio/busca?nome=... — $0.02 — reverse lookup: every company where a person
  or entity appears as partner. The due-diligence query.

CNPJ path parameter accepts 14 digits with or without punctuation.
Errors: { "erro": { "codigo": string, "mensagem": string } } (400 invalid params,
404 not found, 402 payment required).

## Links

- /openapi.yaml — machine-readable API specification (OpenAPI 3.1)
- /termos — terms of use and data policy (Portuguese)
- /docs — human/agent-readable documentation page