Skip to main content
Everything B3-priced in Silo comes from one file format: the COTAHIST fixed-width tape (245-byte register-01 records, latin-1). This page is the decoder ring — what each published field means, which Silo column it becomes, and the code tables the API’s classifications are built from. Layout cross-checked against the rb3 reference implementation’s template.

​
Register-01 fields

Catalog v69 publishes a machine-readable reference at catalog().cotahist: source-field aliases, route applicability and all CODBDI codes in the B3 layout revision 2.0, 2020-10-05, plus observed codes absent from that document. Descriptions for the latter stay null. The table below and the existing fund-subtype rules describe storage and classification; a dated dictionary label must not replace those rules. Existing routes expose original market, board and contract fields. Cash and termo use contract_price, contract_expiry, contract_correction and contract_points; option routes retain their existing strike/expiry names. contract_points_raw preserves PTOEXE text, including leading zeros. distribution_number is available beyond options too. Neither a code in the dictionary nor a field in a schema proves historical observations exist.
FATCOT is the quotation factor, not a lot size and not a split ratio. The quoted price refers to quotation_factor units of the paper: unit price = close / quotation_factor, and volume ≈ close × quantity / quotation_factor. It is 1 for almost everything — measured on the full 2019–2026 cash tape, only 13 tickers ever carried another factor, and only two (GOLL2 1000→1, IBOV11 1→100) ever changed factor mid-series. Prices are served as published; the factor is on every row so you can normalize. close_return is automatically null across a factor change.

​
TPMERC — market type

Exercises (012/013, ~1 print per series) and auctions (017, ~210 rows on the whole tape) are events, not series — computing returns over them is meaningless, which is why they live on their own endpoints instead of the quote surface.

​
CODBDI — board/category

The load-bearing values, validated live against cvm_etf_registry (127 of 247 codbdi-14 tickers matched; zero codbdi-12/13 did): This is what powers fund_type on fund_quotas: the ETF/FII/FIDC/FIAGRO split comes from the published board code, never from the ticker’s shape.

​
ESPECI — specification

A fixed-position 10-character field packing three things:
  • cols 1–4 — share class: ON, PN, PNA, PNB, PNC, PND, UNT, CI, DR*… Served as share_class on equities, cross-checked against the ISIN class code (chars 10–11: OR/PR/PA/PB/PC) with zero disagreements on the 2026-08 tape.
  • cols 5–8 — rights/status flags: ED (ex-dividend), EJ (ex-juros), EDJ, ATZ… Left inside spec as published.
  • cols 9–10 — listing segment: NM (Novo Mercado), N1, N2, MA, M2, MB. Served as governance_segment.

​
The ISIN carries structure too

A Brazilian ISIN is BR + 4-char issuer + 3-char security category (chars 7–9: ACN shares, UNT units, BDR, CTF fund quotas, IND indices) + 2-char class + check digit. Two consequences the API uses:
  • An option row’s ISIN is its underlying’s ISIN — B3’s published option→underlying mapping. underlying_ticker on the option endpoints joins it to the same session’s cash print (measured: 14,895 of 14,900 rows matched, 1:1). PETR-prefix options split correctly between PETR3 and PETR4 — something the ticker root can never do.
  • Index prints exist in COTAHIST (IND category: IBOV11, plus three SMLL11 prints). They are option-settlement indices, not the official close, so they are not served as an index series: use index_history. IBOV11 printed on expiry days only through 2024, weekly in 2025 and on nearly every session since December 2025.

​
Supplemental code interpretations (reviewed 2026-10-07)

The 2020 layout labels remain unchanged. Catalog cotahist.supplemental_interpretations records interpretations with source URLs and unknown validity intervals: 13 FIAGRO; 34 non-sponsored BDRs (DRN); 35 sponsored BDRs and associated instruments (DR1/DR2/DR3, also PPLA11 UNT); 36 ETF BDRs (DRE). These mappings are observed in the 2026-10-05 source file, not certified code-table labels. B3’s block-trading documentation defines M as Midpoint and Q as BBT. Source records associate 92/M and 93/Q with market 021. The previous odd-lot interpretation of 021 was incorrect. INDOPC 0 is interpreted as BRL/no correction index indicated using the related Títulos Negociáveis layout, which maps ICOATV 0 to R$; it does not explicitly define INDOPC 0.