Brazil Foreign Exchange Risk Disclosures API: Track Hedging and FX Exposure from CVM Filings

The problem

FX surveillance splits into three stacks that English search results often merge:

1. Market data terminals — show spot rates and sometimes parsed hedge ratios. They rarely store the issuer’s regulatory PDF with the full derivative note and policy text.
2. Periodic packages — DFP, ITR, and FRE with financial-instrument notes, sensitivity narratives, and board-approved hedge policies. Essential for earnings-quality work, but you still need ticker-first access and stable file IDs.
3. Event disclosures — fatos relevantes when a large FX loss, hedge unwind, or currency crisis exposure is disclosed outside the normal filing calendar.

Scraping the CVM portal works for one ticker and breaks on a diversified watchlist (miners, banks, consumer, LatAm operators). Bulk open-data ZIPs are dataset-oriented, not ticker-first. You want GET /v1/documents with stable document.id, then GET /v1/documents/:id/file for the original PDF — scoped to FX and hedging workflows.

For company-specific walkthroughs (commodity plus derivative MTM), see TTEN3 earnings quality on DFP footnotes or SMFT3 liquidity and FX risk factors in FRE. This guide focuses on the API list-and-download pattern across periodic and event layers.

Which filing type carries FX and hedging detail?

Brazilian issuers do not expose a dedicated type=FX in the apicvm document list. Currency and derivative detail usually appears under:

Practical rule: list latest ITR/DFP for each ticker during 3Q ITR season, narrow annex rows with name filters for notes (notas, notes, explicativas), poll FATO_RELEVANTE for FX keywords, and pull FRE once per year for structural risk context. After download, search PDF text for câmbio, cambio, hedge, derivativo, NDF, swap, or CPC 48 / IFRS 9 references.

Issuer titles vary: banks file long name tokens; exporters may bury hedge tables only inside note PDFs without event-layer keywords. Zero rows in a given year does not prove the issuer has no FX exposure — see limitations below.

How apicvm helps

1. Resolve the issuer — GET /v1/companies/resolve
2. List periodic packages — GET /v1/documents with type=ITR or type=DFP and year
3. Narrow annex rows — same endpoint with name prefix filters (see section name filters)
4. List event filings — GET /v1/documents with type=FATO_RELEVANTE
5. Scope with dateRef; sort with field=dateRef&order=desc
6. Download the PDF — GET /v1/documents/:id/file (no extraction credits)
7. Optional (Pro): page-level markdown — POST /v1/document-text-extractions with async callback

Auth: Authorization: Bearer or X-API-Key. Try VALE3 without a key via the demo API.

Setup

export APICVM_KEY='apicvm_...'
export APICVM_URL='https://apicvm.dev'

Step 1: List quarterly filings for one ticker

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=VALE3&type=ITR&year=2025&perPage=10&field=dateRef&order=desc"

Response rows include stable id, dateRef, name, and nested company metadata. Use id as your cache key — not name, which can be long and encoding-sensitive.

Paginate with page= when meta.lastPage > 1. perPage maxes at 50.

Step 2: Narrow to explanatory notes (derivative tables live here)

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=VALE3&type=ITR&year=2025&perPage=50&name=Notas" \
  | jq '.data[] | {id, type, dateRef, name}'

Combine with filter CVM filings by section name when your catalog uses English or abbreviated tokens.

Step 3: List FX-related material facts

Filename tokens on the CVM IPE feed are predictable enough for a first-pass filter:

curl -s -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=VALE3&types=FATO_RELEVANTE,COMUNICADO_AO_MERCADO&year=2025&perPage=50" \
  | jq '.data[] | select(.name | test("cambio|câmbio|hedge|derivativ|derivative|fx|swap|ndf"; "i")) | {id, type, dateRef, name}'

On the public demo (VALE3 only), swap the host path to /v1/demo/documents with the same query parameters for smoke tests.

For annual FX risk narrative and hedge policy, list the latest FRE:

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=VALE3&type=FRE&year=2025&perPage=5&field=dateRef&order=desc"

Then download the PDF and search risk-factor sections — or follow what is FRE for field context.

Step 4: Download a filing PDF

curl -H "Authorization: Bearer $APICVM_KEY" \
  -o fx-notes.pdf \
  "$APICVM_URL/v1/documents/<document-id>/file"

Download does not consume extraction credits.

Example: Python watchlist for FX-related events

Poll material facts across an exporter-heavy watchlist. Persist seen in your database in production.

import os, time, requests, re
from datetime import datetime

BASE = os.environ["APICVM_URL"]
H = {"Authorization": f"Bearer {os.environ['APICVM_KEY']}"}
WATCH = ["PETR4", "VALE3", "ABEV3", "SUZB3", "SMFT3"]
YEAR = datetime.utcnow().year
FX_RE = re.compile(
    r"cambio|câmbio|hedge|derivativ|derivative|fx|swap|ndf|"
    r"variacao.cambial|exchange.rate|currency",
    re.I,
)
seen = set()  # load from your store on startup

def list_events(ticker):
    r = requests.get(
        f"{BASE}/v1/documents",
        headers=H,
        params={
            "ticker": ticker,
            "types": "FATO_RELEVANTE,COMUNICADO_AO_MERCADO",
            "year": YEAR,
            "perPage": 50,
            "field": "dateRef",
            "order": "desc",
        },
    )
    if r.status_code == 429:
        time.sleep(5)
        return list_events(ticker)
    r.raise_for_status()
    return r.json()["data"]

for ticker in WATCH:
    for doc in list_events(ticker):
        if doc["id"] in seen:
            continue
        if not FX_RE.search(doc.get("name") or ""):
            continue
        seen.add(doc["id"])
        print(f"FX {ticker} {doc['dateRef']} {doc['name'][:70]}")

Wire this into GitHub Actions CVM filings monitor or extend the diff pattern from Brazil material facts monitoring API. For NLP over downloaded PDFs, see extract text from CVM PDFs for AI agents.

Where FX disclosures sit in the filings stack

Brazil regulatory filings API explains the full layer map. Pair periodic note pulls with quarterly ITR monitoring during 3Q ITR season (typically Oct–Nov). When FX-driven losses hit provisions, cross-check Brazil asset impairment write-down disclosures API. When leverage amplifies FX moves, see Brazil debt and covenant disclosures API.

Current limitations

• Documents, not parsed hedge books — apicvm does not return net FX exposure, hedge ratios, or automatic sensitivity tables.
• Keyword filters are heuristic — name tokens help on the event layer; many derivative tables appear only inside periodic PDF notes without matching keywords.
• Polling, not push — no webhook when CVM publishes a new fact. Schedule polls and diff document.id.
• Ingestion lag — sync is not real-time. A notice may appear on the portal before it is in the corpus.
• Corpus coverage — not every issuer or period is present. Validate against the portal for production compliance use cases.
• Demo scope — /v1/demo/* is limited to VALE3. Other tickers need a production key.

Next steps

• Read the API docs
• Get an API key
• Extract CVM financial footnotes from DFP — periodic note workflows

Related guides

• Brazil segment reporting disclosures API — revenue mix and operating segments
• Brazil debt and covenant disclosures API — leverage and refinancing notices
• Access DFP and ITR notes by section name — annex filters before download
• Track Brazil earnings season with the CVM filings API — seasonal ITR workflow
• Extract text from CVM PDFs for AI agents — async markdown extraction