金融商品
債券は、本 API における中心的なドメイン概念です。本ページでは、商品（インストゥルメント）がどのように表現されるか、ストアド商品とアドホック商品の違い、そして各フィールドが価格評価にどのような影響を与えるかを説明します。
ストアド商品とアドホック商品
価格評価対象の債券を指定する方法は2通りあります。
- ストアド商品 —
instrument_idでカタログ内の事前定義済みの債券を参照します。 - アドホック商品 — リクエスト内で債券の条件（タームズ）を直接インラインで記述します。
リクエストでどちらを使用するかは input_kind フィールドで制御します。
ストアド商品は、定期的に価格評価する債券（例：標準的なソブリン債やコーポレート債のカタログ）に推奨されます。アドホック商品は、一回限りの計算や、カタログにまだ存在しない商品の価格評価に有用です。
ストアド商品の参照
ストアド商品を参照するには、input_kind を PRICE_QUANTITY に設定し、instrument_id を指定します。
{
"input_kind": "PRICE_QUANTITY",
"instrument_id": "BR-LTN-2027",
"amount_kind": "yield",
"amount": 0.1125,
"options": {
"with_cashflows": true
}
}
API はカタログから債券の条件を読み込み、それらを価格評価入力とマージします。
アドホック商品の定義
アドホック商品の場合は、債券の条件をインラインで記述します。
{
"input_kind": "PRICE_QUANTITY",
"instrument": {
"issue_date": "2024-01-01",
"maturity_date": "2027-01-01",
"rate_type": "NOMINAL",
"coupon_rate": 0.10,
"day_count": "BUS/252",
"calculation_code": "ACT/ACT.DRMH"
},
"amount_kind": "yield",
"amount": 0.1125
}
商品フィールド
以下の表は、商品定義における主要なフィールドをまとめたものです。
| フィールド | 型 | 説明 |
|---|---|---|
instrument_id | string | ストアド商品の一意な識別子 |
issue_date | date | 債券が発行された日付 |
maturity_date | date | 元本が償還される日付 |
rate_type | enum | NOMINAL または EFFECTIVE |
coupon_rate | number | 年率表示のクーポンレート（小数表記） |
day_count | enum | 経過期間を計算するための日数計算方式 |
calculation_code | enum | アキュリュアル方式を決定する慣行コード |
レートタイプ
rate_type フィールドは、クーポンレートの解釈方法を決定します。
NOMINAL— レートは複利の効果を考慮せずに表示されます。EFFECTIVE— レートには複利の効果が織り込まれています。
ブラジル国債のような多くのラテンアメリカ市場では、BUS/252 の日数計算方式とともに EFFECTIVE レートが使用されます。発行体のコンベンションに合わせて rate_type を必ず一致させてください。
日数計算方式と慣行コード
day_count フィールドはアキュリュアル期間の計算方法を制御し、calculation_code は適用するアキュリュアル方式を選択します。
| 日数計算方式 | 慣行コード | 典型的な用途 |
|---|---|---|
ACT/ACT.ICMA | ACT/ACT.ICMA | 欧州ソブリン債 |
BUS/252 | ACT/ACT.DRMH | ブラジル国債 |
これらのフィールドが価格評価に与える影響について詳しくは、Day Count Conventions を参照してください。
キャッシュフローの出力
options オブジェクトで with_cashflows を true に設定すると、レスポンスにはスケジュールされたキャッシュフローの完全な内訳が含まれます。
{
"options": {
"with_cashflows": true
}
}
各キャッシュフローには、支払日、クーポン金額、および元本（該当する場合）が含まれます。これは、価格評価結果の検証や、償還スケジュールの表示に有用です。
キャッシュフローの出力を有効にすると、レスポンスのサイズがわずかに増加します。多数の債券を一括で価格評価しており、かつ個々のキャッシュフローを必要としない場合は、with_cashflows を false（デフォルト）のままにしておくとよいでしょう。
次のステップ
- 価格評価のためにレートと価格を指定する方法については Amount Kinds を参照してください。
- アキュリュアル方式の詳細については Day Count Conventions を参照してください。
- 完全なフィールドリファレンスについては API Reference を参照してください。