Instruments: stored vs ad-hoc

emrgex distinguishes stored instruments from ad-hoc ones by one thing: whether the bond is already in the catalog.

	Where it's defined	Cashflow schedule	Valuation
Stored	in the catalog (reference by id)	persisted (the issuer's schedule)	recomputed every call
Ad-hoc	inline in your request	generated from the characteristics	recomputed every call

Either way, prices, yields, durations, convexity and accrued are never stored — they are recomputed from the schedule on every request, against the instrument's convention.

Instrument fields

When you define an ad-hoc instrument (or inspect a stored one), these are the fields:

Field	Required	Notes
id	yes (ad-hoc)	your reference for the instrument in the request
rate_type	yes	NOMINAL / EFFECTIVE / AT_MATURITY / PRICE_QUANTITY
day_count	yes¹	FpML/ISDA name; not used for PRICE_QUANTITY
coupon_type	no	FIXED (default) or ACCRUAL
frequency	yes²	coupons per year
start	yes	issue / first-accrual date
maturity	yes
coupon_rate	no	annual coupon as a decimal (0.06 = 6%)
face_value	yes	usually 100
unit_nominal	no	minimum tradeable denomination; rounds a derived nominal
eom	no	end-of-month roll
ex_div_days	no	ex-dividend days
amortizations	no	array of { date, amount } — see below
calls	no	array of { date, price } — makes the bond callable

¹ Required except for PRICE_QUANTITY. ² AT_MATURITY / PRICE_QUANTITY force frequency to 1.

Amortizing bonds

Add an amortizations array of { date, amount } (principal repaid per date). Amortizing bonds are quoted on current outstanding face (the market standard): prices and DV01 scale to the outstanding fraction, while durations, convexity and yields are scale-invariant. A supplied amount_value is interpreted as the current outstanding nominal.

Callable bonds

Add a calls array of { date, price } (redemption price per 100 face). When you quote a callable bond by price, set options.yield_worst: true to also receive the yield-to-worst (min of yield-to-maturity and each yield-to-call). See Metrics.

Browsing the stored catalog

# list instruments (filterable, paginated)
curl "https://calc.dev.emrgex.com/v1/admin/instruments?issuer=Hacienda&limit=20"

Useful filters (all optional, AND-combined): rate_type, day_count, calculation_code, currency, issuer (substring), name (substring), q (searches id/nemo/isin/issuer/name), amortizing, callable, maturity_from / maturity_to, coupon_min / coupon_max, plus sort, order, limit, offset. limit=0 returns just the total count. See the API reference.