Dados financeiros do Brasil. Uma API.

Endpoint map for common agent jobs

For a current quote, call the stock quote endpoint with one or more symbols. Use /api/v2/stocks/quote?symbols=PETR4,VALE3 when you need current prices, market change, currency and basic asset identity in one JSON response.

For a time series, call /api/v2/stocks/historical?symbols=PETR4. Add startDate, endDate, range or interval when the workflow needs a defined date range or daily, weekly and monthly points.

For income events, call /api/v2/stocks/dividends?symbols=PETR4. Use this endpoint when an agent needs payment dates, ex-dates, declared values or a dividend history. Use the FII dividend endpoint for real-estate funds.

For company analysis, call the stock fundamentals endpoints and select the module that matches the question. Balance sheets, income statements, cash flow, statistics and profiles use typed JSON schemas. Do not infer a missing field from a different module.

For FIIs, use the composable routes under /api/v2/fii for indicators, history, historical prices, properties, portfolio, reports and dividends. Pass symbols in the query string and use the published date filters. The FII routes expose focused responses for research and portfolio tools.

For structured funds, use /api/v2/funds. These routes cover fund discovery, current indicators, NAV history, profiles, validated dividends, FIAGRO reports and portfolios, FIDC reports and portfolios, and FIP reports. Use the asset type and identity parameters described by OpenAPI.

For macroeconomic questions, use the macro, inflation and prime rate routes. For public bonds, use the Treasury routes. For exchange rates and digital assets, use currency and crypto routes. These endpoints help agents answer questions that do not involve a single B3 ticker.

For tool discovery, read the OpenAPI document before generating a function call. Each operation has a unique operationId, a description, typed parameters and response schemas. The OpenAPI document is the source for parameter names and response shapes.

Response and reliability contract

Most data responses use a predictable JSON envelope with a result collection, requestedAt and took. Agents should preserve the requested time and processing duration when they explain freshness or latency to a user.

Protected endpoints require a bearer token. Agents should never place a token in a URL, log it, or include it in generated public code. Use the Authorization header and keep secrets in the client's secure configuration.

The sandbox allows selected symbols without a token. Use PETR4, VALE3, MGLU3 or ITUB4 for a small integration check. A successful sandbox response confirms the request shape, not the access level for every paid dataset.

Agents should read RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset on API responses. When the server returns HTTP 429, wait for Retry-After and then retry with backoff. Do not repeat a rejected request in a tight loop.

Unknown website paths return HTTP 404. Use the sitemap, llms.txt and documentation index to discover resources. Do not treat the HTML shell, a redirect or a successful page fetch as proof that a resource path exists.

Use the versioning policy before selecting a legacy route. New integrations should prefer the versioned v2 surface. Agents should monitor Deprecation and Sunset headers and migrate before the documented removal date.

Choose MCP when the user wants a conversational research flow and the client supports Streamable HTTP. Choose REST or an official SDK when the agent must run a repeatable job, validate a schema, store a response or build a production data pipeline.

Operational guidance

Use startDate and endDate for reproducible historical questions. Use range for a common relative period and interval for the granularity. Record the requested dates with the answer so a later agent can reproduce the same query.

Use pagination parameters when a list can contain many assets. Read the pagination object instead of assuming that the first response contains every result. Keep limits small during discovery and increase them only when the user needs a complete list.

When an API response reports an error, keep the HTTP status and error code. A 401 means that the token is missing or invalid. A 403 means that the plan does not include the feature. A 404 means that the requested resource or asset does not exist. A 429 means that the client must wait before retrying.

When a request contains multiple symbols, validate every symbol in the response. Do not copy the first result to a missing symbol. If the user requests a ticker that the API cannot resolve, explain which symbol needs correction and preserve valid results.

The API aggregates public sources such as CVM, BCB and Tesouro Direto. Public source updates can have different schedules. Use the response dates and documented freshness limits when you describe a price, report, rate or financial statement.

For financial answers, identify the endpoint and reference date. Use the response data as information, not as investment advice. Link to the relevant documentation when another developer or agent needs to inspect the request contract.

For an agent that builds a portfolio view, start with ticker discovery, request the current quote, then request historical prices and dividends for the same symbols. Keep identity, valuation, price and income data in separate fields because each endpoint can have a different update time and access rule.

For an agent that writes a market report, collect the requested quote or series first, then collect the related fundamentals and events. State the reference date, source coverage and data freshness. Avoid presenting an old closing price as a real-time price when the endpoint returns EOD data.

For an agent that generates code, use the OpenAPI operationId as the function name, copy parameter schemas without renaming them, and map each response schema to a typed result. The official TypeScript and Python SDKs provide a shorter path when the application wants retries, authentication and typed models.

For an agent that monitors a company over time, store the symbol, request timestamp, reference date and endpoint name with every observation. Compare like-for-like intervals, check whether a series is annual or quarterly, and explain when the latest public filing has not yet arrived. This keeps a useful answer separate from an unsupported forecast.

These rules give agents a clear path from discovery to a safe request, a typed response and a source-aware explanation.

Consult the linked machine-readable resources before exploring unknown paths or inventing endpoint names.

The public documentation, OpenAPI schema, Markdown resources, sitemap, server card and API responses form one discoverable contract. Agents can move between them without relying on client-side navigation or private dashboard state.