Extracting B3-sourced tax and portfolio data from Grana

B3, the Brazilian stock exchange, feeds daily transaction and position data into Grana through its Área do Investidor channel. That feed covers every equity, REIT, ETF, BDR, option, and futures contract the investor holds. It is also the pipeline we tap when building an integration. On top of the raw B3 records, Grana adds its own computed layer: monthly DARF calculations, cost-basis adjustments, the IR Optimizer, and the annual IRPF filing pre-fill. Both layers are reachable.

Where the data originates and how to reach it

Three routes apply here.

B3 Área do Investidor — authorized data channel

B3 built an integration layer, documented at its developer portal (developers.b3.com.br), that lets contracted partners receive investor data with express consent. The channel provides D-1 positions across all listed asset classes, complete buy/sell transaction history, corporate events (dividends, JCP, bonifications, splits), and public-offering participation records. B3 controls the source data. The consent model is formalized, and the exchange has a track record of maintaining it. We handle partner registration and technical onboarding as part of the engagement.

Authorized interface integration of Grana's app layer

Grana's computed layer holds fields B3 does not provide: DARF amounts, the IR Optimizer output, cost-basis adjustments with Brazilian tax-lot rules, and the IRPF filing payload. Reaching this layer requires protocol analysis of the app's authenticated session — mapping the request/response structure, the token lifecycle, and data pagination. This is routine work for the studio.

IRPF export file parsing

Grana generates a structured file for direct import into the Receita Federal's IRPF program. Parsing it yields a clean annual snapshot of the declaration data, though it lacks month-by-month granularity.

For most use cases we combine the B3 channel — authoritative for positions and transactions — with Grana's own layer for the computed tax fields (DARF, optimizer, IRPF pre-fill). The B3 feed supplies the audit trail; Grana supplies the tax math. The export file serves as a year-end cross-check but is not the primary integration path.

Structured records inside Grana

Seven distinct record types flow through Grana, each originating from a different layer of the B3-to-app pipeline.

B3 position pull — working sketch

Below is a Python sketch of the B3 position-fetch flow. URLs and field names are illustrative; exact values are confirmed during the build.

# Illustrative — confirmed during the build
import requests

B3_BASE = "https://api-investidor.b3.com.br"  # placeholder

def refresh_token(cid, secret, rtok):
    r = requests.post(f"{B3_BASE}/oauth/token", data={
        "grant_type": "refresh_token",
        "client_id": cid,
        "client_secret": secret,
        "refresh_token": rtok,
    })
    r.raise_for_status()
    return r.json()["access_token"]

def fetch_positions(token, cpf, date):
    """Pull D-1 consolidated positions for one investor."""
    r = requests.get(f"{B3_BASE}/extrato/v1/posicao",
        headers={"Authorization": f"Bearer {token}"},
        params={"cpf": cpf, "dataReferencia": date})
    r.raise_for_status()
    return r.json()

# Example response shape:
# [{"ticker": "PETR4", "qty": 200, "avgCost": 28.45,
#    "mktValue": 6340.00, "assetType": "STOCK"},
#   {"ticker": "HGLG11", "qty": 50, "avgCost": 162.30,
#    "mktValue": 8115.00, "assetType": "FII"}, ...]

The response carries one object per position: ticker, quantity, average cost, current market value, and an asset-type tag (STOCK, FII, ETF, BDR, OPT, FUT). A second endpoint — not shown — pulls the full transaction ledger for a date range, with the same auth pattern.

Runnable code and documentation package

For a Grana integration, the deliverable package includes:

• An OpenAPI specification covering the B3 investor-data endpoints and Grana's computed-tax endpoints, with request/response schemas per asset class.
• An auth-flow report documenting the OAuth consent handshake with B3 and the session lifecycle for Grana's app layer — token refresh intervals, scope parameters, revocation signals.
• Runnable Python or Node.js source for the key data pulls: positions, transactions, corporate events, DARF history, and IRPF export parsing.
• An automated test suite validating each endpoint against live and recorded responses, with fixtures for stocks, FIIs, ETFs, BDRs, options, and futures.
• Interface documentation mapping Grana's internal data model to a normalized schema suitable for accounting systems or portfolio aggregators.

Open Finance Brasil, LGPD, and investor consent

Grana sits inside Brazil's Open Finance ecosystem, regulated by the Banco Central do Brasil (BCB) and the Conselho Monetário Nacional (CMN). Per the BCB's Open Finance overview, this framework — launched in 2021 — mandates data-sharing participation for major financial institutions and authorizes voluntary participation for others, with express investor consent as the gate for all data flows.

B3's Área do Investidor implements this consent model at the exchange level. The investor logs in, selects which contracted partner may receive their data, and can revoke that consent at any time. Only the approved scopes flow through. Data minimization applies — the partner receives only what the investor authorized, nothing broader.

The LGPD (Lei Geral de Proteção de Dados), enforced by the Autoridade Nacional de Proteção de Dados since 2020, governs all personal-data processing in Brazil. It requires explicit opt-in consent, grants data-portability rights, and mandates that data controllers maintain consent records and honor deletion requests. Our integration logs every consent event, stores only the authorized scopes, and honors revocation within the B3 channel's notification window. NDA arrangements are available where the client's compliance posture requires them.

Real-world integration scenarios

Accounting-platform sync

A Brazilian accounting firm needs monthly DARF data for hundreds of retail-investor clients. The integration pulls each client's DARF from Grana (with their individual consent), normalizes it to the firm's ledger format, and posts it to their ERP. Monthly. Automated. No manual entry of tax-payment slips.

Portfolio consolidation across brokers

A family office holds positions through multiple brokers. Grana, via B3, sees all positions regardless of broker — B3 is the central depository. The integration aggregates positions, dividends, and unrealized P&L into a single consolidated feed, updated daily at D-1.

Tax-loss harvesting automation

Grana's IR Optimizer flags open positions where a tax-efficient sale would offset realized gains. An integration can consume these signals, evaluate them against the investor's risk constraints, and either surface them in a proprietary advisory tool or route them directly to an order-management system.

What the build accounts for

We map the per-plan data boundaries so the integration handles them correctly. Grana's top-tier plan ("Mais Grana Anual," per its Play Store listing) exposes the IR Optimizer and the automatic declaration; cheaper tiers do not. The integration detects which plan a consenting user holds and adjusts its endpoint queries accordingly — no failed calls against features the user hasn't unlocked.

B3's data feed runs to D-1. We design the sync schedule around this latency so downstream systems don't display stale figures. The daily refresh fires after B3's end-of-day processing completes, and every record is timestamped with its effective date, not the retrieval time.

The consent token issued through B3's Área do Investidor has an expiry window and is revocable by the investor at any time. We build consent-status polling into the sync loop: a revocation stops data flow immediately rather than failing silently on the next scheduled pull.

Brazilian tax rules treat day trades and swing trades differently, and FIIs carry their own withholding rate. The data-normalization layer tags each transaction with its correct tax regime so a consuming system cannot misapply exemption thresholds or rate calculations.

Other Brazilian investment-tax apps

MyCapital connects to B3 for automatic trade imports and calculates income tax on stocks, FIIs, and options with DARF generation. Covering it alongside Grana gives a unified view of Brazil's IR-calculator data landscape.

myProfit handles monthly income-tax assessment for investors across domestic and international brokerages. Its international-trade coverage introduces FX-adjusted cost-basis records not present in Grana's B3-only feed.

IR Bot is a web-based platform focused on simplifying IRPF filing for individuals. It holds brokerage-note data and computed tax obligations with a lighter feature set.

IRPFBolsa offers portfolio management and IR calculation via manual brokerage-note upload. Its data is user-submitted but structured for IRPF compliance, making it a common pairing with automated tools.

Velotax calculates income tax on equities and crypto assets with automatic DARF generation. Its crypto coverage extends beyond what Grana handles on the equities side.

Trade Map is primarily a portfolio-tracking and analytics platform. Tax features are secondary, but it holds rich position and performance data across Brazilian brokers.

ReVar is the official calculator launched jointly by B3 and the Receita Federal, as reported by Agência Brasil. Free to use, it covers equities, FIIs, ETFs, and BDRs with data flowing directly from B3 — the government-backed counterpart to commercial tools like Grana.

App screenshots

Questions about Grana data access

Does the integration pull from B3 directly or from Grana's processed layer?

Both paths are viable. The primary route taps B3's Área do Investidor channel, which provides raw positions, transactions, and corporate events at D-1 granularity. Grana's own layer adds computed fields — DARF amounts, cost-basis adjustments, the IR Optimizer output — that B3 does not supply. A full integration typically combines both: raw B3 records for auditability, and Grana's computed tax layer for the numbers an accountant or back-office system actually needs.

Which asset classes come through — just equities, or REITs, BDRs, and futures too?

Grana covers stocks, REITs (FIIs), ETFs, BDRs, options, and futures contracts including IND, WIN, DOL, WDO, BIT, and CCM. The integration maps each asset class to its tax treatment under Brazilian rules — swing-trade versus day-trade thresholds, the R$20,000 monthly exemption for common stocks, and the distinct rates for FIIs and futures.

How is B3 investor consent handled for third-party data access?

The investor grants express consent through B3's logged-in Área do Investidor portal, selecting which contracted partner may receive their data. This consent is revocable at any time. We handle the full onboarding flow — registering as a contracted party, implementing the OAuth handshake, and building consent-status polling so the integration knows immediately if authorization is withdrawn.

Can retroactive DARF data going back to 2020 be extracted?

Grana calculates retroactive monthly income tax from January 2020 onward, per its plan tiers. The integration captures that full history — monthly DARF amounts, payment status, and any corrections — so a back-office system can reconcile years of tax obligations in one sync rather than month by month.

Sources checked

This assessment drew on B3's developer documentation for the Área do Investidor integration layer (developers.b3.com.br), the Banco Central do Brasil's Open Finance overview (bcb.gov.br), Grana Capital's own B3 partnership page (grana.capital/granaeb3), and Agência Brasil's reporting on B3 and the Receita Federal's ReVar launch (agenciabrasil.ebc.com.br). Play Store and App Store listings were also reviewed for feature and plan details.

Mapping reviewed June 2026 by the OpenBanking Studio integration desk.

Source-code delivery for a Grana integration starts at $300 — you pay after delivery, once the working code meets your requirements. If you'd rather not manage infrastructure, our pay-per-call hosted endpoints charge only for actual requests, with no upfront fee. Either way, expect 1–2 weeks from kickoff to delivery. Tell us the app name and what you need; access, credentials, and compliance are arranged as part of the engagement.