Simulates a hypothetical Tesouro Direto bond operation at a given trade date and rate, returning the full set of metrics for that operation: price (PU), quotation, Macaulay/modified duration, and optionally the cash-flow schedule (coupons or installments).
USE THIS for ANY question about a Tesouro Direto bond — price, quotation, duration, sale proceeds, payment schedule, etc. Single tool, all metrics. Bulk: up to 10 items per request (5 if any item sets includeSchedule).
Output is discriminated by `productFamily` ('prefixado' | 'ipca' | 'renda-educa' | 'selic'). The `schedule` field defaults to `null` to keep responses compact (a Renda+ schedule alone has 240 entries). It comes populated as `[{ date, businessDays, flow, cashFlowBrl, presentValue, kind, number? }]` (kind: 'coupon' | 'principal' | 'installment') — `flow` is the nominal cash flow before discounting (STN-style flow, not a currency amount); semantics depend on `kind`. `cashFlowBrl` is BRL per one bond unit (face 1000): `flow/100 ×` settlement snapshot of 1000 / `vnaProjected` / `vniProjected`, truncated to centavos (T-2 floor) — not a forecast of BRL actually credited on each payment date for indexed families (VNA on IPCA+ with coupons, VNI on Renda+/Educa+; both move with IPCA accrual); discounted sum of `cashFlowBrl` may differ slightly from PU (T-6). Only when the caller passes `includeSchedule: true` AND the bond family supports a schedule (zero-coupon families like prefixado / ipca-mais / selic never have one). Whenever a field is null, a structured warning in `meta.warnings[]` with `code` and `field` explains why.
Every response also carries a `calculation` object (discriminated by `kind`: 'prefixado-zero' | 'prefixado-semestrais' | 'ipca' | 'renda-educa' | 'selic') with the intermediate values used by the engine — business days to maturity, truncated discount exponent, discount factor, VNA/VNI base + projected, IPCA monthly rate, and (when auto-fetched) `automaticIpcaValidFrom`. For IPCA-linked families the `indexProjection` also splits the two projection legs: `monthsBeyondVnaBase` / `monthsCompounded` / `compoundedFactor` (the whole-month forward compounding) versus `exponent` (the sub-month pro-rata). On Tesouro Selic the `calculation` carries `vnaProjected` (the VNA the price discounts, truncated to 6 decimals), `selicTarget` (the Copom target standing in for the fixings not yet published) and an `indexProjection` with `lastFixing` / `base` / `projectedBusinessDays`. Use it to audit a price against the official methodology without re-running it.
Tesouro Selic (LFT) is priced off its VNA rather than a fixed face of 1000: `annualRate` there is the SPREAD over the Selic (`ágio/deságio`), routinely near zero and often negative (e.g. '-0.0002'), never the Selic rate itself. Because the VNA closes on the last published fixing and is projected to settlement at the Copom target, the trade date matters on top of the settlement date — a D+0 sale projects nothing, a D+1 purchase projects one business day.
Inputs: `tradeDate` (YYYY-MM-DD) is the negotiation date — NOT the settlement date. `side` ('investorBuy' | 'investorSell', optional but recommended when direction is known): semantic intent of the operation. When provided, the engine derives the correct `settlementConvention` automatically — 'investorBuy' -> 'D+1'; 'investorSell' -> 'D+0' if tradeDate >= 2021-09-13 (same-day sell-back rule), else 'D+1'. Omit `side` when simulating for pure pricing purposes without a specific trade direction. `settlementConvention` ('D+0' | 'D+1', optional): advanced override — when omitted, the engine derives from `side` (or defaults to 'D+1' when both are omitted). If both `side` and `settlementConvention` are provided and conflict, the explicit `settlementConvention` is used and a NONSTANDARD_SETTLEMENT_FOR_SIDE warning is emitted. The response echoes `side` (when provided), `settlementConvention` (resolved), and `settlementDate`. `includeSchedule` (default false) opts in to coupon/installment detail. `annualRate` MUST be a decimal string (e.g. '0.1423' for 14.23%, never '14.23'). Bond identification: prefixado/IPCA+/Selic require `maturityDate`; Renda+/Educa+ require `conversionYear` OR `maturityYear`. Optional overrides: `vnaBase`+`ipcaMonthlyRate` for IPCA+ types, `vniBase`+`ipcaMonthlyRate` for Renda+/Educa+ (auto-fetched if omitted). `ipcaMonthlyRate` is the current-month ANBIMA projection used ONLY for the sub-month pro-rata — it does NOT compound whole months forward. For a future-dated valuation (settlement months/years ahead), pass `ipcaForwardMonthlyRate` (assumed monthly IPCA) to project the VNA/VNI base forward over the whole-month gap; it is ignored when `vnaBase`/`vniBase` is overridden. Note `ipcaForwardMonthlyRate` and `annualRate` are orthogonal assumptions: the forward rate is the inflation that grows the VNA/VNI base, while `annualRate` is the REAL yield (the '+X%' of IPCA+X%) that discounts it — for IPCA-linked types it does NOT include inflation. A future-dated valuation needs BOTH set to the future scenario; passing `ipcaForwardMonthlyRate` with today's `annualRate` models future inflation at today's real yield.
Warning catalog (`meta.warnings[]`, each `{ code, field?, message }`): `NONSTANDARD_SETTLEMENT_FOR_SIDE` (both `side` and `settlementConvention` were provided and the explicit convention differs from the standard for that side — explicit value was used); `SYNTHESIZED_BOND` (bond not in catalog, synthesized for historical simulation); `SETTLEMENT_BEFORE_LAUNCH` (settlement predates the bond's launch date); `IPCA_STALE` (auto IPCA projection is over 35 days old vs settlement); `IPCA_PROJECTION_MISSING` (historical settlement before the earliest bundled IPCA projection — engine falls back to ipcaMonthlyRate=0, using the VNA of the nearest past day-15 without pro-rata; pass an explicit ipcaMonthlyRate for better precision); `IPCA_FORWARD_RATE_IGNORED` (both a `vnaBase`/`vniBase` override and `ipcaForwardMonthlyRate` were supplied — the override is authoritative so the forward rate was ignored); `IPCA_FORWARD_GAP_NOT_COMPOUNDED` (settlement is N whole months beyond the last published VNA/VNI and no `ipcaForwardMonthlyRate` was supplied — the gap was NOT compounded onto the base, only the sub-month pro-rata; pass `ipcaForwardMonthlyRate` for a future-dated valuation, or refresh bundled VNA data if the settlement is actually near-term); `SUSPICIOUS_RATE` (annualRate > 1.0 — likely passed as percentage); `CALENDAR_LAW_SWITCH` (tradeDate predates Lei 14.759/2023; legacy calendar without Nov 20 holiday is in use); `TRADE_DATE_NON_BUSINESS_DAY` (tradeDate is a weekend, holiday, or market interruption — settlement was rolled forward to the next business day, so D+0 and D+1 may resolve to the same date); `NOT_INCLUDED` (field could exist but caller did not request it — set the matching include* flag, e.g. schedule on coupon/stream families); `CASHFLOW_BRL_SETTLEMENT_VNA_SNAPSHOT` (only when `includeSchedule: true` for `bondType` `ipca-mais-com-juros-semestrais` — each `schedule[].cashFlowBrl` uses the settlement VNA snapshot; see `message`); `CASHFLOW_BRL_SETTLEMENT_VNI_SNAPSHOT` (only when `includeSchedule: true` for `bondType` `renda-mais` or `educa-mais` — each `schedule[].cashFlowBrl` uses the settlement VNI snapshot; see `message`); `NOT_AVAILABLE_FOR_OPERATION` (the provided `side` is not among the bond's current `availableFor` sides in the catalog, e.g. `investorBuy` on a bond withdrawn from new offerings and now sell-only — the simulation still runs as a hypothetical scenario, it is not blocked).
All values are pre-tax (gross), based on hypothetical inputs — this is a simulation, NOT a real-time market quote nor an offer to trade. IR and IOF apply on actual operations. Each bulk row returns `{ input, ok: true, result }` or `{ input, ok: false, error }`.
Before calling, use `catalog_list` if you need to discover available bonds or disambiguate the user's reference.