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.