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'). 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 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') 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). Use it to audit a price against the official methodology without re-running it.
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+ 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`).
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.