Instrumentos: armazenados vs ad-hoc

O emrgex distingue instrumentos armazenados dos ad-hoc por uma única coisa: se o título já está no catálogo.

	Onde é definido	Cronograma de fluxos de caixa	Valoração
Armazenado	no catálogo (referenciado por id)	persistido (o cronograma do emissor)	recalculado a cada chamada
Ad-hoc	inline na sua requisição	gerado a partir das características	recalculado a cada chamada

De qualquer forma, preços, rendimentos, durações, convexidade e juros acumulados nunca são armazenados — eles são recalculados a partir do cronograma a cada requisição, conforme a convenção do instrumento.

Campos do instrumento

Ao definir um instrumento ad-hoc (ou inspecionar um armazenado), estes são os campos:

Campo	Obrigatório	Notas
id	sim (ad-hoc)	sua referência para o instrumento na requisição
rate_type	sim	NOMINAL / EFFECTIVE / AT_MATURITY / PRICE_QUANTITY
day_count	sim¹	nome FpML/ISDA; não usado para PRICE_QUANTITY
coupon_type	não	FIXED (padrão) ou ACCRUAL
frequency	sim²	cupons por ano
start	sim	data de emissão / primeiro acúmulo
maturity	sim
coupon_rate	não	cupom anual como decimal (0.06 = 6%)
face_value	sim	geralmente 100
unit_nominal	não	denominação mínima negociável; arredonda um nominal derivado
eom	não	rolagem de fim de mês
ex_div_days	não	dias ex-dividendo
amortizations	não	array de { date, amount } — veja abaixo
calls	não	array de { date, price } — torna o título resgatável (callable)

¹ Obrigatório exceto para PRICE_QUANTITY. ² AT_MATURITY / PRICE_QUANTITY forçam frequency para 1.

Títulos com amortização

Adicione um array amortizations de { date, amount } (principal amortizado por data). Títulos com amortização são cotados sobre o valor de face em aberto atual (o padrão de mercado): preços e DV01 escalam com a fração em aberto, enquanto durações, convexidade e rendimentos são invariantes à escala. Um amount_value fornecido é interpretado como o nominal em aberto atual.

Títulos resgatáveis (callable)

Adicione um array calls de { date, price } (preço de resgate por 100 de face). Quando você cota um título resgatável por preço, defina options.yield_worst: true para receber também o yield-to-worst (min entre o yield-to-maturity e cada yield-to-call). Veja Métricas.

Navegando pelo catálogo armazenado

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

Filtros úteis (todos opcionais, combinados por AND): rate_type, day_count, calculation_code, currency, issuer (substring), name (substring), q (busca em id/nemo/isin/issuer/name), amortizing, callable, maturity_from / maturity_to, coupon_min / coupon_max, além de sort, order, limit, offset. limit=0 retorna apenas a contagem total. Veja a referência da API.