Brazil Share Buyback Disclosures API: Track Treasury Repurchase Notices from CVM Filings

The problem

Buyback monitoring on B3 issuers splits into two stacks that search results often confuse:

1. Trading and market data — execution, volume, sometimes estimated shares repurchased. Good for charts, not for the filing text that defines program size, price limits, and board authorization.
2. Regulatory disclosures — fatos relevantes and occasional avisos aos acionistas that describe treasury acquisitions (aquisição de ações de emissão da própria companhia).

Scraping the CVM portal works for one ticker and breaks on a watchlist. 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 — the same pattern as Brazil IPE disclosures, scoped to repurchase events.

For payout notices (dividends and JCP), use the sibling hub Brazil dividend disclosures API. For the generic poll loop on all material facts, see Brazil material facts monitoring API.

Which filing type carries the buyback?

Brazilian issuers do not file a dedicated SEC-style "buyback form." Repurchase programs usually surface under:

Practical rule: poll FATO_RELEVANTE for each ticker on your watchlist, then filter rows by name keywords (Aquisicao, recompra, buyback, tesouraria) before downloading PDFs. Combine with AVISO_AOS_ACIONISTAS if you already run a dividend and corporate-actions poller.

On VALE3 for calendar year 2026, the demo corpus included a FATO_RELEVANTE row named Aquisicao_de_Acoes_de_Emissao_da_Propria_Companhia with dateRef 2026-07-30 (demo API, queried 2026-09-11). Active issuers file more repurchase-related facts in program-heavy years; zero rows does not prove no buyback occurred — see limitations below.

Step-by-step list queries for material facts: List fatos relevantes via API.

How apicvm helps

1. Resolve the issuer — GET /v1/companies/resolve
2. List event filings — GET /v1/documents with type=FATO_RELEVANTE or types=FATO_RELEVANTE,AVISO_AOS_ACIONISTAS
3. Scope with year and optional dateRef; sort with field=dateRef&order=desc
4. Download the PDF — GET /v1/documents/:id/file (no extraction credits)
5. 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 material facts for one ticker

curl -H "Authorization: Bearer $APICVM_KEY" \
  "$APICVM_URL/v1/documents?ticker=VALE3&type=FATO_RELEVANTE&year=2026&perPage=50&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 buyback-related rows

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&type=FATO_RELEVANTE&year=2026&perPage=50" \
  | jq '.data[] | select(.name | test("Aquisicao|recompra|Buyback|buyback"; "i")) | {id, dateRef, name}'

After download, search PDF text for programa de recompra, ações em tesouraria, or preço máximo for validation. Extraction credits apply only if you use the text-extraction endpoint.

Step 3: Download a repurchase notice PDF

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

Download does not consume extraction credits.

Example: Python watchlist for buyback filings

Poll material facts across a repurchase-focused 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 = ["VALE3", "PETR4", "ITUB4", "BBDC4", "ABEV3"]
YEAR = datetime.utcnow().year
BUYBACK_RE = re.compile(
    r"aquisicao|recompra|buyback|tesouraria", re.I
)
seen = set()  # load from your store on startup

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

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

Wire this into GitHub Actions or extend the diff pattern from Brazil material facts monitoring API.

Where buyback disclosures sit in the filings stack

Brazil regulatory filings API explains the full layer map. During earnings windows, pair this hub with Track Brazil earnings season for ITR and investor presentations alongside event filings.

Current limitations

• Documents, not execution — apicvm does not route orders or return live repurchase volume from the exchange.
• Keyword filters are heuristic — name tokens help; false negatives are possible if issuers use unusual titles.
• 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
• List fatos relevantes — focused FATO_RELEVANTE reference

Related guides

• Brazil dividend disclosures API — payouts and JCP notices
• Brazil IPE disclosures API — all five IPE types
• Extract text from CVM PDFs for AI agents — async markdown extraction
• Build a multi-ticker CVM filings watchlist