Parameters, response columns and types are generated from the SQL catalog and
render under Endpoints → Derivatives in the sidebar. This page carries what a
schema cannot: the conventions, the nulls that are deliberate, and the traps.
Overview
Options are the same COTAHIST tape asquotes on a different market type: tpmerc 070 = call, 080 = put. They are roughly nine in ten rows of every session, which is why both endpoints here are narrower than their cash-market equivalents — neither will scan the whole segment for you.
Everything is unadjusted; every row carries adjusted: false.
Option rows carry underlying_ticker, and it is published, not the codneg-root convention: COTAHIST’s ISIN on an option row is the underlying’s ISIN, joined here to the same session’s cash print. Measured on a full session, 14,895 of 14,900 rows matched 1:1 — PETR-prefix options split correctly between PETR3 and PETR4, which a ticker root can never do. Null when the underlying had no cash print that day, never guessed.
Also on every row: strike_points (PTOEXE, USD-referenced options; null when not points-referenced), strike_correction (INDOPC) and distribution_number (DISMES — it changes on corporate events, a useful split signal). See the COTAHIST dictionary.
POST /rpc/option_chain
One session’s chain for a codneg prefix: every strike, expiry and side that printed.
Rows are ordered by
expiry, then strike, then side, then codneg — so if an over-broad prefix hits the 2,000-row clamp, the cut is deterministic and you get whole near expiries rather than a random slice. Exactly 2,000 rows back means your prefix was broad enough to be cut; narrow it, or pin p_expiry_from.
POST /rpc/option_history
One series’ daily prints over a window, ascending by trade_date.
p_codneg is the exact series code, e.g. PETRH400, upper-cased server-side. Get one from option_chain — lookup does not resolve option codes and no endpoint enumerates them, so you need the underlying’s root (the p_prefix argument) to find a series.
Returns quote_history’s column set with side, strike and expiry in place of board / short_name.
22023) — never a truncated series. An option series lives for months, so you will not reach the page in practice. There is no cursor: narrow p_from / p_to and call again.
Prices are raw
Premiums are COTAHIST as published: no split, dividend or corporate-action adjustment anywhere in this warehouse.adjusted is a constant false so nothing here can be mistaken for an adjusted series.
close_return is deliberately not offered for options. In panel it accepts ticker ids only — and even there it adjusts the previous close across a share-count event (a split, grouping or bonus) by the share ratio, which for options would also need strike and quantity adjustments. Options are the same tape and would inherit the same flaw, with strike and quantity adjustments on top. Take close from option_history and difference it yourself, where you can see what you are assuming.
Empty and error behavior
- Unknown codneg →
200 []. Never a fabricated premium. - Known codneg, no sessions in the window (before it listed, after it expired) → also
200 []. The two cases are indistinguishable from the response; confirm the series exists withoption_chainon a session you know it traded. - A prefix under 3 characters →
400. The one case where the API errors instead of returning an empty array. p_expiry_fromdefaults to today, so anoption_chaincall against a historicalp_trade_datewill often come back empty — the series that printed that day have since expired. Pass"p_expiry_from": nullto see them.