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.