Documentação da API

Autenticação

Todas as requisições devem incluir o header X-API-Key com sua chave de acesso. Você pode obter sua chave gratuitamente fazendo login com sua conta Google e gerenciar suas chaves (criar, rotacionar, excluir) direto no dashboard. Cada conta pode ter até 5 chaves ativas no plano Free e 20 no plano Pro.

Os limites são resetados à meia-noite UTC. Se o limite for excedido, a API retorna 429 Too Many Requests (no plano grátis, a resposta inclui upgrade_info com o link para o Pro). O header X-RateLimit-Remaining indica quantas requisições restam.

curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/fundamentals/PETR4

Exportação CSV

A maioria dos endpoints aceita o parâmetro format=csv para exportar os dados em formato CSV. Útil para importar no Excel, Google Sheets ou scripts de análise.

curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/stocks/PETR4/history?format=csv" \
  -o petr4_precos.csv

Gerenciamento de chaves

Os endpoints abaixo são usados pelo dashboard para listar, criar, rotacionar e excluir chaves. Eles autenticam por cookie de sessão (login Google) — não por X-API-Key. Para integrações via terminal, recomendamos usar o dashboard direto.

Ao rotacionar ou excluir uma chave, ela deixa de funcionar imediatamente. O limite de requisições é compartilhado entre todas as chaves de uma mesma conta — criar mais chaves não aumenta sua cota diária.

Lista as chaves ativas da conta. Os valores das chaves são retornados mascarados — o segredo completo só é exibido uma vez no momento da criação ou rotação.

[
  {
    "id": 42,
    "label": "default",
    "key_masked": "sk_697d••••••••f485",
    "is_active": true,
    "created_at": "2026-03-24T20:38:39",
    "last_used_at": "2026-05-12T13:21:04"
  }
]

Cria uma nova chave com o rótulo (label) informado. Retorna o segredo completo apenas uma vez — guarde-o em local seguro. Retorna 400 se a conta já atingiu o limite (5 no Free, 20 no Pro).

{
  "id": 43,
  "label": "laptop",
  "key": "sk_a4b9c2d1e0f8..."
}

Gera um novo segredo para a chave mantendo o mesmo rótulo e id. O segredo antigo deixa de funcionar imediatamente. O novo segredo é retornado uma única vez na resposta.

{
  "id": 43,
  "label": "laptop",
  "key": "sk_novosecreto..."
}

Exclui (revoga) a chave. A chave deixa de funcionar imediatamente. Retorna 400 se essa for a única chave ativa da conta — toda conta precisa ter pelo menos uma chave ativa.

{
  "ok": true
}

Consulte o uso atual da sua API key: requisições feitas hoje, limite diário e tier do plano.

curl "https://api.usebolsai.com/api/v1/keys/usage?api_key=sua_chave"

{
  "tier": "free",
  "used_today": 42,
  "daily_limit": 200,
  "remaining": 158
}

Lista todas as empresas registradas, com suporte a filtros por setor, status e busca por nome.

curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/companies/?search=petro&limit=2"

{
  "data": [
    {
      "ticker_primary": "PETR4",
      "corporate_name": "PETROLEO BRASILEIRO S.A. PETROBRAS",
      "trade_name": "PETROBRAS",
      "cvm_code": "9512",
      "cnpj": "33.000.167/0001-01",
      "sector": "Petroleo, Gas e Biocombustiveis",
      "status": "ATIVO"
    },
    {
      "ticker_primary": "RECV3",
      "corporate_name": "PETRO RECÔNCAVO S.A.",
      "trade_name": "PETRORECONCAVO",
      "cvm_code": "25607",
      "cnpj": "03.342.704/0001-30",
      "sector": "Petroleo, Gas e Biocombustiveis",
      "status": "ATIVO"
    }
  ],
  "count": 2,
  "total": 5,
  "offset": 0,
  "limit": 2
}

Lista todos os setores disponíveis com a contagem de empresas ativas com ticker em cada um. Útil para descobrir nomes de setores válidos para os filtros de /companies e /screener.

curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/companies/sectors

{
  "sectors": [
    { "name": "Bancos", "count": 19 },
    { "name": "Energia Elétrica", "count": 18 },
    { "name": "Construção Civil, Mat. Constr. e Decoração", "count": 16 },
    // ...
  ],
  "total": 42
}

Retorna informações detalhadas de uma empresa a partir do ticker. O campo queried_ticker ecoa o ticker consultado e tickers lista todas as classes de ação (ON/PN/Unit) da empresa.

curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/companies/PETR4

{
  "ticker_primary": "PETR4",
  "queried_ticker": "PETR4",
  "tickers": ["PETR3", "PETR4"],
  "corporate_name": "PETROLEO BRASILEIRO S.A. PETROBRAS",
  "trade_name": "PETROBRAS",
  "cvm_code": "9512",
  "cnpj": "33.000.167/0001-01",
  "sector": "Petroleo, Gas e Biocombustiveis",
  "status": "ATIVO",
  "registration_date": "1977-08-15",
  "registration_category": "A",
  "market_type": "BOLSA",
  "country": "Brasil",
  "state": "RJ",
  "city": "Rio de Janeiro",
  "email": "",
  "website": ""
}

Lista todos os tickers disponíveis, filtrados por código BDI.

curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/stocks/?bdi_code=02&limit=10"

{
  "count": 312,
  "total": 312,
  "tickers": [
    "ABEV3",
    "ALPA4",
    "AMER3",
    // ... +309 tickers
  ]
}

Retorna a cotação mais recente de um ticker, incluindo preço de abertura, máxima, mínima, fechamento e volume.

curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/stocks/PETR4/quote

{
  "ticker": "PETR4",
  "trade_date": "2026-03-21",
  "open": 45.12,
  "high": 46.03,
  "low": 44.89,
  "close": 45.67,
  "volume": 42318700,
  "traded_amount": 1932045876.54,
  "num_trades": 187432
}

Estatísticas de preço: máxima/mínima de 52 semanas, retorno YTD, variação diária e volume médio.

curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/stocks/ITUB4/stats

{
  "ticker": "ITUB4",
  "trade_date": "2026-03-21",
  "close": 34.52,
  "daily_change": 0.38,
  "daily_change_pct": 1.11,
  "week_52_low": 27.15,
  "week_52_high": 36.89,
  "avg_volume_52w": 24563100,
  "ytd_return_pct": 12.45
}

Retorna o histórico de preços de um ticker, ordenado do mais recente para o mais antigo. Inclui preços ajustados por splits, grupamentos e dividendos. Dados desde 1986. Consultar tickers antigos (ex: VIIA3) retorna histórico completo da empresa.

O Ibovespa também está disponível: /stocks/IBOV/history retorna o OHLC diário do índice desde 1993, com os mesmos parâmetros dos demais tickers (volume vem 0).

curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/stocks/VALE3/history?start=2026-01-01&limit=5"

{
  "ticker": "VALE3",
  "count": 5,
  "prices": [
    {
      "trade_date": "2026-03-21",
      "open": 62.45,
      "high": 63.10,
      "low": 61.80,
      "close": 62.87,
      "adjusted_open": 62.45,
      "adjusted_high": 63.10,
      "adjusted_low": 61.80,
      "adjusted_close": 62.87,
      "volume": 35214600,
      "adjusted_volume": 35214600,
      "traded_amount": 2213784521.30,
      "num_trades": 142567
    }
    // ... mais registros
  ]
}

Retorna desdobramentos (splits) e grupamentos (reverse splits) confirmados pela B3 para um ticker.

curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/stocks/MGLU3/corporate-events

{
  "ticker": "FESA4",
  "count": 2,
  "events": [
    {
      "date": "2024-01-23",
      "type": "SPLIT",
      "ratio_from": 1,
      "ratio_to": 4,
      "description": "1:4",
      "factor": 0.25
    }
  ]
}

Lista todos os desdobramentos e grupamentos confirmados pela B3 para todos os tickers.

curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/stocks/corporate-events?year=2025"

{
  "count": 2,
  "events": [
    {
      "ticker": "FESA4",
      "date": "2024-01-23",
      "type": "SPLIT",
      "ratio_from": 1,
      "ratio_to": 4,
      "description": "1:4",
      "factor": 0.25
    },
    {
      "ticker": "MGLU3",
      "date": "2024-05-24",
      "type": "INPLIT",
      "ratio_from": 10,
      "ratio_to": 1,
      "description": "10:1",
      "factor": 10.0
    }
  ]
}

Retorna o histórico de tickers de uma empresa, incluindo renomeações. Consultar VIIA3 ou BHIA3 retorna o mesmo resultado (dados completos da empresa).

{
  "cvm_code": "6505",
  "corporate_name": "GRUPO CASAS BAHIA S.A.",
  "current_ticker": "BHIA3",
  "tickers": [
    {
      "ticker": "BHIA3",
      "first_traded": "2023-09-20",
      "last_traded": "2026-03-25",
      "current": true
    },
    {
      "ticker": "VIIA3",
      "first_traded": "2020-09-14",
      "last_traded": "2023-09-19",
      "current": false
    }
  ]
}

Filtra todas as ~264 ações negociadas por indicadores fundamentalistas. Use sufixos _gt (maior que) e _lt (menor que) nos parâmetros. Conta como 1 requisição. Requer plano Pro. Os indicadores aqui são calculados no nível da empresa (ticker principal / mais líquido), uma linha por empresa; para múltiplos por classe de ação (ON/PN/Unit), use /fundamentals/{ticker}.

curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/screener/?dividend_yield_gt=6&roe_gt=10&sort=dividend_yield&order=desc&limit=5"

{
  "data": [
    {
      "ticker": "PETR4",
      "corporate_name": "PETRÓLEO BRASILEIRO S.A.",
      "sector": "Petróleo e Gás",
      "close_price": 49.03,
      "market_cap": 631934567271.83,
      "dividend_yield": 12.3,
      "pl": 5.74,
      "pvp": 1.52,
      "roe": 26.49,
      "net_margin": 22.23,
      "daily_change": 0.38,
      "daily_change_pct": 1.11,
      // ... 20+ mais indicadores
    }
  ],
  "count": 5,
  "total": 23,
  "offset": 0,
  "limit": 5
}

Retorna indicadores fundamentalistas calculados: P/L, EV/EBITDA, ROE, margem líquida, dívida/patrimônio e mais. Usa os dados DFP/ITR mais recentes disponíveis. Múltiplos de preço (P/L, P/VP, EV/EBITDA, market_cap) são calculados para a classe de ação consultada — ON, PN e Unit têm preços diferentes, então esses valores variam entre elas. Métricas por empresa (LPA, VPA, ROE, margens) são idênticas entre as classes. O campo queried_ticker ecoa o ticker consultado.

earnings_yield = EBIT / EV × 100, onde EV = valor de mercado + dívida líquida (já desconta o caixa); null para bancos e quando o EV não é positivo. dividend_payout = proventos (dividendos + JCP) por ação com data-ex nos últimos 12 meses ÷ LPA × 100 (no histórico, os 12 meses terminados em reference_date); null em caso de prejuízo ou sem proventos no período.

free_cash_flow (fluxo de caixa livre) = caixa líquido das atividades operacionais (conta 6.01 da DFC) − capex, em R$ mil como os demais valores absolutos (ebitda, net_income), nos últimos 12 meses (no histórico, os 12 meses terminados em reference_date). O capex soma as saídas de caixa com aquisição de imobilizado, intangível, ativos de contrato/concessão e propriedades para investimento, identificadas pela descrição da conta nas atividades de investimento (6.02), já que a CVM não fixa um código para elas. null para bancos e quando falta a DFC de algum dos períodos. cash_flow_after_investing = caixa operacional (6.01) + caixa de investimentos (6.02) inteiro, na mesma unidade e janela de 12 meses: diferente do free_cash_flow, inclui aquisições de empresas, aplicações financeiras e vendas de ativos. null para bancos e quando falta o total 6.02 de algum dos períodos.

total_debt, net_debt, debt_equity, net_debt_equity, net_debt_ebitda, net_debt_ebit, ev_ebitda, ev_ebit e roic são null para bancos: o passivo de um banco é captação (depósitos, operações compromissadas), não dívida financeira, e o plano de contas bancário da CVM não separa empréstimos e financiamentos, então não há dívida líquida, EV nem capital investido. current_ratio, current_assets e current_liabilities também são null para bancos, cujo balanço não separa circulante de não circulante. No screener, filtros por essas métricas excluem os bancos e a ordenação os coloca no fim.

curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/fundamentals/PETR4

{
  "cvm_code": "9512",
  "ticker": "PETR4",
  "queried_ticker": "PETR4",
  "reference_date": "2025-12-31",
  "close_price": 45.67,
  "shares_outstanding": 12888732761,
  "market_cap": 588628425194.87,
  "pl": 5.32,
  "pvp": 1.42,
  "ev_ebitda": 3.27,
  "ev_ebit": 4.67,
  "earnings_yield": 21.41,
  "p_ebitda": 2.65,
  "p_ebit": 2.98,
  "p_sr": 1.18,
  "lpa": 8.54,
  "vpa": 32.26,
  "roe": 26.6,
  "roa": 9.04,
  "roic": 17.4,
  "net_margin": 22.23,
  "gross_margin": 47.6,
  "ebitda_margin": 39.6,
  "ebit_margin": 33.2,
  "debt_equity": 0.92,
  "net_debt_equity": 0.8,
  "net_debt_ebitda": 1.18,
  "net_debt_ebit": 1.69,
  "current_ratio": 0.71,
  "dividend_payout": 45.2,
  "asset_turnover": 0.41,
  "p_assets": 0.48,
  "ebit_over_assets": 16.1,
  "cagr_revenue_5y": -0.8,
  "cagr_earnings_5y": null,
  "net_income": 110605000,
  "equity": 415786000,
  "net_revenue": 497549000,
  "total_debt": 384025000,
  "ebitda": 281630000,
  "ebit": 197242000,
  "free_cash_flow": 124181000,
  "cash_flow_after_investing": 131674000,
  "net_debt": 333417000,
  "cash": 50608000,
  "total_assets": 1223390000,
  "current_assets": 140026000,
  "current_liabilities": 198341000,
  "corporate_name": "PETRÓLEO BRASILEIRO  S.A.  - PETROBRAS"
}

Retorna o histórico de indicadores fundamentalistas, um por trimestre, do mais recente ao mais antigo.

curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/fundamentals/WEGE3/history?limit=2"

{
  "ticker": "WEGE3",
  "queried_ticker": "WEGE3",
  "corporate_name": "WEG S.A.",
  "count": 2,
  "history": [
    {
      "reference_date": "2025-12-31",
      "close_price": 52.30,
      "pl": 38.12,
      "pvp": 11.45,
      "roe": 30.02,
      "net_margin": 18.65,
      // ... demais indicadores
    },
    {
      "reference_date": "2025-09-30",
      "close_price": 48.75,
      "pl": 35.67,
      "pvp": 10.89,
      "roe": 29.45,
      "net_margin": 17.92,
      // ... demais indicadores
    }
  ]
}

Retorna as demonstrações financeiras (DFP anuais ou ITR trimestrais) de uma empresa. Inclui Balanço Patrimonial Ativo (BPA), Passivo (BPP), DRE, Fluxo de Caixa (DFC_MI) e DVA.

Com report_type=T4, retorna o 4º trimestre calculado: DFP anual − acumulado de 9 meses do 3º ITR do mesmo exercício (DRE, DFC_MI e DVA; o balanço é uma posição na data, então BPA/BPP retornam 400 — use a DFP). É uma informação derivada, não um documento entregue à CVM: a resposta traz "derived": true (false em DFP/ITR). reference_date é o fim do exercício (31/12, ou outra data para exercícios não civis). Linhas cuja conta não existe no 3º ITR, ou que nele têm outra descrição (códigos abaixo do 2º nível são livres por empresa), são omitidas, assim como o LPA (3.99), que não pode ser subtraído. Exercícios sem os três ITRs não têm T4. Cada linha também traz derived; com report_type=ITR&include_t4=true, o T4 da DRE entra na própria série trimestral, marcado linha a linha.

curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/financials/BBDC4?report_type=DFP&statement_type=DRE&reference_date=2025-12-31"

{
  "ticker": "BBDC4",
  "cvm_code": "9512",
  "report_type": "DFP",
  "derived": false,
  "count": 42,
  "statements": [
    {
      "reference_date": "2025-12-31",
      "statement_type": "DRE",
      "account_code": "3.01",
      "account_name": "Receita de Intermediacao Financeira",
      "value": 198432000000.0,
      "derived": false
    },
    {
      "reference_date": "2025-12-31",
      "statement_type": "DRE",
      "account_code": "3.02",
      "account_name": "Despesas da Intermediacao Financeira",
      "value": -142567000000.0,
      "derived": false
    }
    // ... mais linhas
  ]
}

Retorna o histórico de dividendos e JCP de um ticker, incluindo dividend yield dos últimos 12 meses, resumo anual e lista de pagamentos com datas de pagamento. Consultar tickers antigos (ex: VIIA3) retorna dados completos da empresa atual (BHIA3).

curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/dividends/BBAS3?years=3"

{
  "ticker": "BBAS3",
  "dividend_yield_ttm": 8.45,
  "ttm_per_share": 2.3412,
  "current_price": 27.71,
  "total_payments": 18,
  "annual_summary": [
    {
      "year": 2026,
      "total_per_share": 0.5843,
      "payments": 2
    },
    {
      "year": 2025,
      "total_per_share": 2.8756,
      "payments": 8
    }
  ],
  "payments": [
    {
      "ex_date": "2026-03-14",
      "payment_date": "2026-04-20",
      "type": "JCP",
      "value_per_share": 0.2934,
      "adjusted": false
    },
    {
      "ex_date": "2026-02-21",
      "payment_date": "2026-03-20",
      "type": "Dividendo",
      "value_per_share": 0.2909,
      "adjusted": false
    }
    // ... mais pagamentos
  ]
}

Lista todos os FIIs negociados na B3 com os dados mais recentes: nome, segmento, tipo de gestão e número de cotistas. Códigos que deixaram de ser negociados — por renomeação ou encerramento — saem da lista após 90 dias sem pregão.

curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/fiis/

{
  "count": 185,
  "total": 423,
  "fiis": [
    {
      "ticker": "HGLG11",
      "name": "CSHG LOGISTICA FDO INV IMOB - FII",
      "segment": "Logistica",
      "management_type": "Gestao Ativa",
      "total_shareholders": 487523
    },
    {
      "ticker": "KNRI11",
      "name": "KINEA RENDA IMOBILIARIA FDO INV IMOB - FII",
      "segment": "Hibrido",
      "management_type": "Gestao Ativa",
      "total_shareholders": 312456
    }
    // ... mais FIIs
  ]
}

Retorna fundamentos + perfil operacional de um FII: P/VP, dividend yield 12m, NAV, cotistas, administrator, mandate, asset composition, fund_type (Tijolo/Papel/Híbrido/Fundo de Fundos/Fiagro), vacância, inadimplência, lista das principais propriedades. Dados de imóveis (vacância/inadimplência) vêm do informe trimestral CVM.

curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/fiis/HGLG11

{
  "ticker": "HGLG11",
  "name": "CSHG LOGISTICA FDO INV IMOB - FII",
  "reference_date": "2026-02-28",
  "close_price": 162.45,
  "book_value_per_share": 148.32,
  "pvp": 1.10,
  "dividend_yield_ttm": 8.74,
  "net_asset_value": 4523000000.0,
  "shares_outstanding": 30498200,
  "total_shareholders": 487523,
  "segment": "Logistica",
  "management_type": "Gestao Ativa",
  "administrator": "CREDIT SUISSE HEDGING-GRIFFO CV S.A.",
  "administrator_cnpj": "61809182000130",
  "mandate": "Renda",
  "inception_date": "2010-06-01",
  "duration_type": "Indeterminado",
  "target_investors": "INVESTIDORES EM GERAL",
  "website": "www.cshg.com.br",
  "email": "investidores@cshg.com.br",
  "fund_type": "Tijolo",
  "asset_composition": {
    "real_estate_leased_pct": 84.31,
    "real_estate_under_construction_pct": 0.0,
    "real_estate_for_sale_pct": 0.0,
    "land_pct": 0.0,
    "other_real_estate_pct": 0.0,
    "cri_pct": 0.0,
    "lci_pct": 0.0,
    "cepac_pct": 0.0,
    "debentures_pct": 0.0,
    "fii_holdings_pct": 15.69,
    "fip_fdic_pct": 0.0,
    "stocks_pct": 0.0,
    "cash_pct": 0.49,
    "other_pct": 0.0
  },
  "fees_paid_last_month": {
    "admin": 105112.97,
    "performance": 0.0
  },
  "property_count": 28,
  "total_area_sqm": 1595382.91,
  "vacancy_pct": 2.91,
  "delinquency_pct": 0.0,
  "leased_pct": 97.09,
  "top_properties": [
    {
      "name": "Galpão Cajamar",
      "address": "Rod. Anhanguera - Cajamar/SP",
      "asset_class": "Imóveis para renda acabados",
      "area_sqm": 125000.0,
      "revenue_pct": 45.0,
      "vacancy_pct": 2.0,
      "leased_pct": 98.0
    }
  ],
  "property_reference_date": "2024-12-31"
}

Retorna o histórico mensal de um FII: evolução do P/VP, DY mensal, NAV e cotistas.

curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/fiis/HGLG11/history?limit=3"

{
  "ticker": "HGLG11",
  "name": "CSHG LOGISTICA FDO INV IMOB - FII",
  "count": 3,
  "history": [
    {
      "reference_date": "2026-02-28",
      "close_price": 162.45,
      "book_value_per_share": 148.32,
      "pvp": 1.10,
      "dy_month_pct": 0.7234,
      "value_per_share": 1.0732,
      "net_asset_value": 4523000000.0,
      "shares_outstanding": 30498200,
      "total_shareholders": 487523
    },
    {
      "reference_date": "2026-01-31",
      "close_price": 160.80,
      "book_value_per_share": 147.90,
      "pvp": 1.09,
      "dy_month_pct": 0.6892,
      "value_per_share": 1.0191,
      "net_asset_value": 4510000000.0,
      "shares_outstanding": 30498200,
      "total_shareholders": 482190
    }
    // ... mais meses
  ]
}

Retorna o histórico de distribuições de um FII: R$/cota mensal, totais anuais e dividend yield dos últimos 12 meses. Os rendimentos vêm dos proventos anunciados na B3 (atualizados assim que declarados), não do informe mensal da CVM, que tem defasagem de 1 a 2 meses.

curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/fiis/XPLG11/distributions?years=2"

{
  "ticker": "XPLG11",
  "name": "XP LOG FDO INV IMOB - FII",
  "dividend_yield_ttm": 9.12,
  "ttm_per_share": 9.2456,
  "close_price": 101.38,
  "total_payments": 24,
  "annual_summary": [
    {
      "year": 2026,
      "total_per_share": 2.3145,
      "payments": 3
    },
    {
      "year": 2025,
      "total_per_share": 9.5623,
      "payments": 12
    }
  ],
  "payments": [
    {
      "reference_date": "2026-03-01",
      "value_per_share": 0.7832,
      "dy_month_pct": 0.7612,
      "book_value_per_share": 102.89
    },
    {
      "reference_date": "2026-02-01",
      "value_per_share": 0.7654,
      "dy_month_pct": 0.7445,
      "book_value_per_share": 102.82
    }
    // ... mais pagamentos
  ]
}

Filtra todos os FIIs negociados na B3 por P/VP, dividend yield, NAV, número de cotistas e mais. Use sufixos _gt (maior que) e _lt (menor que) nos parâmetros. Conta como 1 requisição. Requer plano Pro.

curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/fiis/screener?pvp_lt=1&dividend_yield_ttm_gt=8&sort=dividend_yield_ttm&order=desc&limit=10"

{
  "data": [
    {
      "ticker": "HGLG11",
      "name": "CSHG LOGÍSTICA FII",
      "segment": "Logística",
      "management_type": "Ativa",
      "reference_date": "2026-03-31",
      "close_price": 158.40,
      "book_value_per_share": 165.50,
      "net_asset_value": 3500000000.00,
      "shares_outstanding": 21148036,
      "total_shareholders": 350000,
      "pvp": 0.96,
      "dividend_yield_ttm": 8.42,
      "dy_month_pct": 0.65,
      "mandate": "Renda",
      "administrator_name": "CREDIT SUISSE HEDGING-GRIFFO CV S.A.",
      "fund_type": "Tijolo",
      "vacancy_pct": 2.91,
      "delinquency_pct": 0.0,
      "leased_pct": 97.09,
      "property_count": 28,
      "total_area_sqm": 1595382.91
    }
  ],
  "count": 10,
  "total": 28,
  "offset": 0,
  "limit": 10
}

Retorna a concentração de receita por setor de inquilino (Comércio, Serviço, Indústria, etc.) para o trimestre mais recente. Os inquilinos individuais não são publicados pela CVM; a agregação é feita por setor de atuação.

curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/fiis/HGLG11/tenants

{
  "ticker": "HGLG11",
  "reference_date": "2024-12-31",
  "count": 3,
  "top_sector_pct": 71.0,
  "sectors": [
    {"sector": "Logística", "revenue_pct": 71.0},
    {"sector": "Comércio", "revenue_pct": 20.0},
    {"sector": "Indústria", "revenue_pct": 9.0}
  ]
}

Lista todas as séries macroeconômicas disponíveis: Selic, Meta Selic, IPCA, CDI, IGP-M, USD/BRL e EUR/BRL (PTAX). O campo kind indica se a série é um nível (level — uma taxa ou um preço) ou já é uma variação percentual mensal (pct_change — IPCA e IGP-M), o que determina quais campos o endpoint /macro/{series_name}/stats preenche. O Ibovespa diário está disponível via /stocks/IBOV/history e /stocks/IBOV/stats.

curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/macro/

{
  "series": {
    "selic": { "code": "1178", "name": "Taxa Selic", "kind": "level" },
    "selic_target": { "code": "432", "name": "Meta Selic", "kind": "level" },
    "ipca": { "code": "433", "name": "IPCA", "kind": "pct_change" },
    "cdi": { "code": "4389", "name": "CDI", "kind": "level" },
    "usd_brl": { "code": "1", "name": "USD/BRL (PTAX)", "kind": "level" },
    "eur_brl": { "code": "21620", "name": "EUR/BRL (PTAX)", "kind": "level" },
    "igpm": { "code": "189", "name": "IGP-M", "kind": "pct_change" }
  }
}

Retorna os dados históricos de uma série macroeconômica. Séries disponíveis: selic, selic_target, ipca, cdi, usd_brl, eur_brl, igpm. A série selic é a taxa Selic efetiva anualizada (base 252, % ao ano); cdi também vem anualizada (base 252, % ao ano); selic_target é a meta definida pelo Copom. ipca e igpm são mensais, em variação percentual do mês (podem ser negativas).

curl -H "X-API-Key: sua_chave" \
  "https://api.usebolsai.com/api/v1/macro/selic?start=2026-01-01&limit=5"

{
  "series": "selic",
  "series_code": "1178",
  "count": 5,
  "data": [
    { "date": "2026-03-21", "value": 14.15 },
    { "date": "2026-03-20", "value": 14.15 },
    { "date": "2026-03-19", "value": 14.15 },
    { "date": "2026-03-18", "value": 14.15 },
    { "date": "2026-03-17", "value": 14.15 }
  ]
}

Estatísticas de uma série macroeconômica: variação, máxima/mínima dos últimos 12 meses e acumulados. Útil para exibir juros, inflação ou câmbio com o mesmo formato do endpoint /stocks/{ticker}/stats. Para o Ibovespa, use /stocks/IBOV/stats.

O campo series_kind define quais métricas fazem sentido e, portanto, quais vêm preenchidas. A resposta tem sempre os mesmos campos — os que não se aplicam vêm null.

series_kind: "level" (Selic, Meta Selic, CDI, USD/BRL, EUR/BRL) — a série é uma taxa ou um preço, e o endpoint retorna daily_change_pct e ytd_return_pct.

series_kind: "pct_change" (IPCA, IGP-M) — a série já é uma variação percentual mensal. A variação percentual de uma variação percentual não tem significado e, quando o mês anterior é negativo (o IGP-M deflaciona com frequência), a divisão inverte o sinal. Por isso daily_change_pct e ytd_return_pct vêm null, e no lugar deles a série traz accumulated_12m_pct e accumulated_ytd_pct, compostos por prod(1 + v/100) - 1 — o número normalmente chamado de inflação acumulada.

daily_change é a diferença absoluta em relação à leitura anterior e vem preenchido nos dois casos — para pct_change ele está em pontos percentuais (IPCA de 0,52 para 0,16 é -0.36 p.p.). Nas séries mensais, daily_change compara meses, não dias, e week_52_low/week_52_high são a menor e a maior leitura mensal dos últimos 12 meses. Os nomes desses campos são mantidos por compatibilidade com /stocks/{ticker}/stats.

curl -H "X-API-Key: sua_chave" \
  https://api.usebolsai.com/api/v1/macro/usd_brl/stats

{
  "series": "usd_brl",
  "series_kind": "level",
  "reference_date": "2026-06-23",
  "close": 5.42,
  "daily_change": 0.03,
  "daily_change_pct": 0.56,
  "week_52_low": 4.98,
  "week_52_high": 6.21,
  "ytd_return_pct": -3.14,
  "accumulated_12m_pct": null,
  "accumulated_ytd_pct": null
}

{
  "series": "igpm",
  "series_kind": "pct_change",
  "reference_date": "2026-06-01",
  "close": -1.16,
  "daily_change": -0.66,
  "daily_change_pct": null,
  "week_52_low": -1.16,
  "week_52_high": 1.52,
  "ytd_return_pct": null,
  "accumulated_12m_pct": 3.24,
  "accumulated_ytd_pct": -1.42
}

Verifica o status de saúde da API e suas dependências (PostgreSQL e Redis). Não requer autenticação.

curl https://api.usebolsai.com/health

{
  "status": "ok",
  "environment": "production",
  "checks": {
    "postgres": "ok",
    "redis": "ok"
  }
}

Retorna 200 quando todos os serviços estão saudáveis, ou 503 se algum está indisponível (status: "degraded").