A bond option API and an interest-rate option API can both sit inside a fixed-income research platform, but they should not share an undifferentiated price field. A bond price, a yield, a futures quotation, and a volatility parameter describe different things. The most important integration decision is therefore not which chart to draw first. It is how to preserve the meaning of each quantity.
This guide proposes a convention-first data architecture. It distinguishes product families and explains the fields a developer should verify before comparing them. It is not a valuation service, a market quotation, or a recommendation to hedge with a particular instrument. Real contracts require their own specifications and pricing assumptions.
Begin with a product taxonomy
Describe the actual underlying contract before choosing a schema. An option on a cash bond, an option on a bond futures contract, an option on a short-rate futures contract, and a swaption are not interchangeable records. The taxonomy should distinguish them even when the application groups them under a common fixed-income navigation label.
For your own model, use a product-family field and a separate underlying-instrument reference. Then add the fields required by that family rather than forcing every family into the same small set of columns. A cash-bond reference may need security-level terms, while a futures reference needs a precise contract identity. A swap-related product requires its own underlying schedule and convention information.
Keep the broad interface approachable without simplifying away the economic differences. The bond option API page focuses on security and futures relationships. The interest-rate option API page focuses on rates, reference periods, and convention metadata. They share an architecture, not a promise that every product can be valued with the same formula.
Do not confuse a price quotation with a rate
CME Group's Three-Month SOFR product overview documents a futures quotation based on 100 minus the relevant rate and describes the contract's reference quarter. This illustrates why a number that looks like a price may encode a rate convention. It is not appropriate to interpret every numeric field in a fixed-income feed as a bond price or a percentage yield.
For a synthetic illustration using that simple arithmetic form, a rate value of 4.25 corresponds to an index-style quotation of 95.75. If the rate input increases to 4.50, that quotation becomes 95.50. The subtraction explains direction within the stated convention. It is not a complete option valuation, a forecast, or a universal relationship for every rate product.
Store the raw quotation, the normalized numeric value, and a convention identifier. Do not reverse-engineer the convention from the magnitude of the number. A parser should reject unknown units or route them for review, rather than decide that anything below one must be a decimal rate and anything near one hundred must be a price.
Keep calendars and reference periods explicit
A rate-related instrument may depend on more than an expiration date. Your record should have room for the applicable reference period, observation schedule, and underlying contract maturity where relevant. Do not compress a period into a single label if the calculation needs its beginning and end. Preserve the precision actually supplied by the source.
For modeled products, record day-count and business-day conventions as named inputs rather than hidden code settings. Two calculations can disagree because they use different schedules even when the quoted numbers match. Your system should make those differences discoverable. A spreadsheet-like display can still be clear if convention details appear in an adjacent, readable record panel.
Save the version of the calendar or schedule generator used by your application. If a holiday treatment changes, you need a way to identify affected calculations. Rebuilding historical schedules from today's settings without versioning can make a previously reviewed result impossible to reproduce. The same principle applies to any manually corrected date in a research dataset.
Treat curves as versioned model inputs
A curve is not just a decorative line between several maturities. In your own pricing workflow, store its identifier, observation time, input instruments, construction method, interpolation choice, and version. This is an engineering requirement for reproducibility, not a claim that a particular curve method is correct for every product.
Keep observed inputs separate from constructed curve points. A chart can show both, but it should distinguish them visually and in exported data. Otherwise, a reader may assume that an interpolated ten-year point was directly quoted. If the application extrapolates beyond the observed region, label that region clearly rather than extend a smooth line with no explanation.
When a curve input is missing, choose an explicit policy. You may stop the calculation, use a documented fallback, or produce an output marked degraded. Do not silently reuse an old curve while updating the option quote and labeling the complete calculation current. Every important input needs its own observation time and quality state.
Preserve volatility conventions
Volatility fields need a unit and a model context. Your schema should distinguish the quotation convention used by the source rather than assume that every volatility number is a percentage suitable for the same formula. Keep the raw representation, normalization method, applicable expiry, and any underlying tenor dimension together.
For a proposed surface record, make the coordinates explicit. An expiry and an underlying tenor describe different axes. A one-year option on one underlying term is not the same point as a different option expiry sharing that term. A label such as 1Y is too ambiguous unless the interface explains which axis it belongs to.
When comparing provider analytics, investigate inputs and conventions before treating differences as pricing errors. A model output is only comparable after its assumptions are aligned with the question being asked. The general option API guide explains how to store provider metrics and internally calculated metrics as separate, traceable objects.
Label risk measures by their actual meaning
A field named risk is not sufficiently specific. Your record should state the measure, units, scaling, sign convention, input state, and calculation method. Avoid combining a price sensitivity, a yield sensitivity, and a currency amount under one unqualified heading. A shared chart legend does not make those quantities commensurate.
For a synthetic sensitivity test, record a base value and the result after a defined input change. State the size and direction of the change, which other inputs stayed fixed, and whether the output is per contract or for a stated quantity. This makes the finite-difference calculation inspectable without claiming it captures every source of risk.
Do not label an option premium as the full capital requirement or a modeled risk number as a guaranteed loss limit. Those are different concepts that depend on product terms and account arrangements. A research interface can report its own scenario results while remaining clear about the scope of the scenario and the assumptions it excludes.
Validate the convention layer before adding breadth
Check dimensions and signs
Create fixtures for a decimal rate, a percentage rate, an index-style quotation, and an explicitly unsupported convention. Verify that the application keeps their meanings distinct. Include a sign test with a known synthetic conversion and a quantity test that separates per-contract output from a portfolio total.
Check reproducibility
Save a small complete calculation bundle containing the contract record, curve version, volatility input, calendars, and expected output. Rerun it after code changes. The objective is not to prove a universal model; it is to prove that your implementation continues to perform the calculation it documents using the same stated assumptions.
Conclusion: conventions are first-class data
A useful bond and interest-rate option API workflow preserves product taxonomy, quotation meaning, reference periods, curves, volatility conventions, and risk units. Those details are not secondary metadata. They determine whether the numbers on the screen answer the question the reader thinks they answer.
For the underlying-contract layer, continue with the futures option mapping guide. Use the developer reference to practice a transparent schema with local fixtures. Broader market coverage should follow successful convention tests, not precede them, and no data model removes the need for qualified product and risk review.
