{"openapi":"3.0.0","info":{"title":"BondTerminal API","version":"1.4.0","description":"Fixed-income analytics API for Argentine bonds. Calculate YTM, duration, convexity, spreads, and more.\nYield convention: every yield is semi-annual bond-equivalent (S.A.), compounded twice a year over ACT/365 time, for every bond whatever its coupon frequency. It is the basis of US Treasury CMT yields. Modified duration, convexity and DV01 are on the same basis, and G-spread and Z-spread are measured against the semi-annual Treasury curve. YTM inputs are read as S.A. too. Every yield-bearing response carries a `conventions` block. Until 27-Sep-2026 yields were effective annual; history is restated on the S.A. basis (see the changelog).\nVersioning: the API is URL-versioned (/api/v1); breaking changes only ship in a new version, and any retirement comes with at least 90 days notice via Deprecation (RFC 9745) and Sunset (RFC 8594) headers plus the changelog. A market-convention change inside v1 changes values, not fields, and is announced in the changelog. One field is deprecated: `oas` on search and batch rows, a same-value alias of `gSpread`. Nothing is scheduled for removal.\nRate limits: every response carries an advisory RateLimit-Policy header (IETF draft-ietf-httpapi-ratelimit-headers structured format), including unauthenticated 401/402 errors; 429 responses add RateLimit and Retry-After so clients can self-throttle.\n","contact":{"name":"BondTerminal","url":"https://bondterminal.com"}},"servers":[{"url":"https://bondterminal.com/api/v1","description":"Production"}],"tags":[{"name":"Calculations","description":"Bond analytics (YTM, duration, spreads, risk metrics)"},{"name":"Bonds","description":"Bond catalog and details"},{"name":"Market Data","description":"Treasury yield curve and market data"},{"name":"Riesgo País","description":"Argentina country risk index"}],"paths":{"/calculate":{"post":{"tags":["Calculations"],"summary":"Calculate bond analytics","operationId":"calculateBondAnalytics","description":"Calculate full analytics for a single bond. Provide exactly one of price, ytm, gSpread, or zSpread as input. The response always includes all computed fields regardless of input type.\n","security":[{"BearerAuth":[]},{"X402Payment":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateRequest"},"example":{"isin":"US105756CC23","price":95.5,"settlement":"2026-06-12"}}}},"responses":{"200":{"description":"Full bond analytics","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"traceparent":{"$ref":"#/components/headers/traceparent"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BondAnalytics"},{"$ref":"#/components/schemas/ConventionsEnvelope"}]},"example":{"isin":"US105756CC23","ticker":"BRAZIL 3.875 30","price":95.5,"settlement":"2026-06-12","yields":{"ytm":5.195475,"ytw":5.195475,"currentYield":2.028796},"risk":{"modifiedDuration":3.55482,"macaulayDuration":3.739509,"effectiveDuration":3.55482,"convexity":16.556436,"dv01":0.033949},"spreads":{"gSpread":106.035215,"zSpread":106.666565,"treasuryYield":4.135123,"treasuryTenor":"4Y"},"pricing":{"cleanPrice":95.5,"accruedInterest":0,"dirtyPrice":95.5},"schedule":{"nextCouponDate":"2026-12-14","daysToNextCoupon":185,"averageLife":4.00274},"conventions":{"yield":"semi-annual","compounding":2,"spreads":"semi-annual","time":"ACT/365","methodologyUrl":"https://bondterminal.com/methodology/yields"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/calculate/batch":{"post":{"tags":["Calculations"],"summary":"Batch calculate bond analytics","operationId":"batchCalculateBondAnalytics","description":"Calculate analytics for multiple bonds in a single request (max 50). Each item can use a different input type. Results preserve input order. Batch requests count one calculation per bond and are capped by your remaining daily calculations. Requires API key subscription (x402 payments not accepted).\n","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRequest"},"example":{"bonds":[{"isin":"US105756CC23","price":95.5},{"isin":"US040114HU71","ytm":12},{"isin":"US71654QDF63","gSpread":276}],"settlement":"2026-06-12"}}}},"responses":{"200":{"description":"Batch results with per-item errors","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"traceparent":{"$ref":"#/components/headers/traceparent"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"},"example":{"results":[{"index":0,"isin":"US105756CC23","ticker":"BRAZIL 3.875 30","price":95.5,"settlement":"2026-06-12","yields":{"ytm":5.195475,"ytw":5.195475,"currentYield":2.028796},"risk":{"modifiedDuration":3.55482,"macaulayDuration":3.739509,"effectiveDuration":3.55482,"convexity":16.556436,"dv01":0.033949},"spreads":{"gSpread":106.035215,"zSpread":106.666565,"treasuryYield":4.135123,"treasuryTenor":"4Y"},"pricing":{"cleanPrice":95.5,"accruedInterest":0,"dirtyPrice":95.5},"schedule":{"nextCouponDate":"2026-12-14","daysToNextCoupon":185,"averageLife":4.00274}},{"index":1,"isin":"US040114HT09","ticker":"ARGENT 4.125 35","price":70.550514,"settlement":"2026-06-12","yields":{"ytm":11.9,"ytw":11.9,"ytc":11.934333,"currentYield":5.846874},"risk":{"modifiedDuration":4.873257,"macaulayDuration":5.453175,"effectiveDuration":4.873258,"convexity":32.560761,"dv01":0.035217},"spreads":{"gSpread":760.084521,"zSpread":713.874817,"treasuryYield":4.299155,"treasuryTenor":"7Y"},"pricing":{"cleanPrice":70.550514,"accruedInterest":1.715013,"dirtyPrice":72.265527},"schedule":{"nextCouponDate":"2026-07-13","daysToNextCoupon":31,"averageLife":6.833151}},{"index":2,"isin":"US71654QDF63","ticker":"PEMEX 6.95 60","price":95.023597,"settlement":"2026-06-12","yields":{"ytm":7.71,"ytw":7.71,"currentYield":7.313973},"risk":{"modifiedDuration":11.512979,"macaulayDuration":12.40063,"effectiveDuration":11.51299,"convexity":236.7743,"dv01":0.112379},"spreads":{"gSpread":276,"zSpread":272.473717,"treasuryYield":4.95,"treasuryTenor":"34Y"},"pricing":{"cleanPrice":95.023597,"accruedInterest":2.586944,"dirtyPrice":97.610541},"schedule":{"nextCouponDate":"2026-07-28","daysToNextCoupon":46,"averageLife":33.652055}}],"errors":[],"meta":{"requested":3,"successful":3,"failed":0},"conventions":{"yield":"semi-annual","compounding":2,"spreads":"semi-annual","time":"ACT/365","methodologyUrl":"https://bondterminal.com/methodology/yields"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/bonds":{"get":{"tags":["Bonds"],"summary":"List available bonds","operationId":"listBonds","description":"Browse the bond catalog with optional filtering by country, issuer type, or free-text search.","security":[{"BearerAuth":[]},{"X402Payment":[]}],"parameters":[{"name":"search","in":"query","schema":{"type":"string","minLength":1,"maxLength":100},"description":"Search by name, issuer, ticker, or ISIN (case-insensitive substring match)","example":"pampa"},{"name":"country","in":"query","schema":{"type":"string"},"description":"Filter by ISO country code (e.g. AR, UY, BR)","example":"AR"},{"name":"type","in":"query","schema":{"type":"string","enum":["sovereign","quasi","corporate"]},"description":"Filter by issuer type"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"description":"Max results per page"},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"Pagination offset"}],"responses":{"200":{"description":"Paginated bond list","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"traceparent":{"$ref":"#/components/headers/traceparent"}},"content":{"application/json":{"schema":{"type":"object","properties":{"bonds":{"type":"array","items":{"$ref":"#/components/schemas/BondSummary"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"example":{"bonds":[{"isin":"US040114HT09","ticker":"ARGENT 4.125 35","name":"ARGENT 4.125 35","issuer":"The Republic of Argentina","country":"AR","type":"sovereign","currency":"USD","coupon":4.125,"maturity":"2035-07-09"}],"meta":{"total":45,"limit":100,"offset":0}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/bonds/facets":{"get":{"tags":["Bonds"],"summary":"Get bond catalog facets","operationId":"getBondFacets","description":"Discover available catalog coverage before searching. Costs 1 read unit.","security":[{"BearerAuth":[]},{"X402Payment":[]}],"responses":{"200":{"description":"Catalog facets","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"traceparent":{"$ref":"#/components/headers/traceparent"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BondFacetsResponse"},"example":{"asOf":"2026-06-12","total":3071,"countries":[{"value":"US","count":1067},{"value":"AR","count":72}],"issuerTypes":[{"value":"corporate","count":2266},{"value":"sovereign","count":534}],"currencies":[{"value":"USD","count":3071}],"governingLaws":[{"value":"NY","count":2320},{"value":"UK","count":733}],"features":{"callable":1794,"amortizing":163,"variableCoupon":215,"perpetual":66}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/bonds/search":{"post":{"tags":["Bonds"],"summary":"Search and screen bonds","operationId":"searchBonds","description":"Search the full bond catalog with rich filters and optional ratings/market fields. Costs 1 read unit per row returned (minimum 1, so a search with no rows costs 1). Basic keys get at most 50 rows per page. Rows come in ISIN order unless you set another sort field. `issuer` is the legal issuer: many bonds sit in a finance subsidiary or project company, and search also matches the parent names we link. Yield and spread filters drop bonds with no current yield or spread, such as unpriced or defaulted bonds. Convertible notes are not in the catalog.","security":[{"BearerAuth":[]},{"X402Payment":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BondSearchRequest"},"example":{"q":"brazil","filters":{"country":["BR"],"issuerType":["sovereign","corporate"],"governingLaw":["NY"],"ratingMin":"BBB","ratingMax":"BB","maturityDateFrom":"2028-01-01","maturityDateTo":"2035-12-31"},"sort":{"field":"maturityDate","direction":"asc"},"page":{"size":25}}}}},"responses":{"200":{"description":"Search results","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"traceparent":{"$ref":"#/components/headers/traceparent"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BondSearchResponse"},"example":{"rows":[{"id":"US105756CC23","isin":"US105756CC23","ticker":"BRAZIL 3.875 30","issuer":"Federative Republic of Brazil","countryCode":"BR","issuerType":"sovereign","currency":"USD","governingLaw":"NY","maturityDate":"2030-06-12","couponRate":3.875,"price":95.5,"ytm":5.195475,"yieldBasis":"maturity","leadYield":5.195475,"leadYieldBasis":"ytm","modDuration":3.55482,"averageRating":"BB"}],"nextCursor":null,"estimatedTotal":1,"capped":false,"asOf":"2026-06-12","suppressedCount":0,"conventions":{"yield":"semi-annual","compounding":2,"spreads":"semi-annual","time":"ACT/365","methodologyUrl":"https://bondterminal.com/methodology/yields"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/bonds/batch":{"post":{"tags":["Bonds"],"summary":"Bulk bond lookup","operationId":"getBondsBatch","description":"Fetch many rich bond rows by ISIN, ticker, local ticker, or name. Any API key, including self-serve keys. Not available through x402. Costs 1 read unit per identifier. Basic keys send at most 10 identifiers.\n","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BondBatchLookupRequest"},"example":{"identifiers":["US040114HS26","GD35D","BRAZIL 3.875 30"],"fields":["isin","ticker","localTicker"]}}}},"responses":{"200":{"description":"Bulk bond rows and missing identifiers","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"traceparent":{"$ref":"#/components/headers/traceparent"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BondBatchLookupResponse"},"example":{"bonds":[{"id":"US040114HS26","isin":"US040114HS26","ticker":"ARGENT 0.75 30","issuer":"The Republic of Argentina","currency":"USD","maturityDate":"2030-07-09","price":65.84,"ytm":6.102119,"yieldBasis":"maturity","leadYield":6.102119,"leadYieldBasis":"ytm","averageRating":"CCC"}],"count":1,"missing":["MISSING 1"],"conventions":{"yield":"semi-annual","compounding":2,"spreads":"semi-annual","time":"ACT/365","methodologyUrl":"https://bondterminal.com/methodology/yields"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/bonds/{identifier}/cashflows":{"get":{"tags":["Bonds"],"summary":"Get future cashflow schedule","operationId":"getBondCashflows","description":"Returns the remaining cashflow schedule for a bond — all future coupon and principal payments after the settlement date, plus a summary with totals. Cashflow amounts are per face value. Fixed coupons are the contractual amounts; floating-rate, reset and PIK coupons are projected from the current reference rate, the same flows the yield prices.\n","security":[{"BearerAuth":[]},{"X402Payment":[]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string"},"description":"Bond ISIN (e.g. US040114HT09), ticker, or local ticker","example":"US040114HT09"},{"name":"settlement","in":"query","schema":{"type":"string","format":"date"},"description":"Settlement date (YYYY-MM-DD). Defaults to T+2 business days.","example":"2026-01-30"}],"responses":{"200":{"description":"Future cashflow schedule with summary","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"traceparent":{"$ref":"#/components/headers/traceparent"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashflowResponse"},"example":{"isin":"US040114HT09","ticker":"ARGENT 4.125 35","name":"ARGENT 4.125 35","settlement":"2026-01-30","cashflows":[{"date":"2026-07-09","couponPayment":250,"principalPayment":0,"totalPayment":250,"remainingNotional":10000,"paymentType":"COUPON"},{"date":"2035-07-09","couponPayment":250,"principalPayment":10000,"totalPayment":10250,"remainingNotional":0,"paymentType":"MATURITY"}],"summary":{"count":18,"totalCoupon":4500,"totalPrincipal":10000,"totalCashflow":14500,"finalDate":"2035-07-09"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/bonds/{isin}":{"get":{"tags":["Bonds"],"summary":"Get bond details","operationId":"getBondByIsin","description":"Retrieve full details for a specific bond by ISIN or ticker.","security":[{"BearerAuth":[]},{"X402Payment":[]}],"parameters":[{"name":"isin","in":"path","required":true,"schema":{"type":"string"},"description":"Bond ISIN (e.g. US040114HT09) or ticker (e.g. ARGENT 4.125 35)","example":"US040114HT09"}],"responses":{"200":{"description":"Bond details","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"traceparent":{"$ref":"#/components/headers/traceparent"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BondDetail"},"example":{"isin":"US040114HT09","ticker":"ARGENT 4.125 35","name":"ARGENT 4.125 35","issuer":"The Republic of Argentina","country":"AR","type":"sovereign","currency":"USD","faceValue":1000,"coupon":4.125,"couponFrequency":2,"dayCountConvention":"30/360","issueDate":"2020-09-04","maturity":"2035-07-09","settlementDays":2,"originalIssueAmount":16102507000,"originalIssueCurrency":"USD"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/bonds/{identifier}/analytics":{"get":{"tags":["Calculations"],"summary":"Get full analytics for a bond using latest market price","operationId":"getBondAnalytics","description":"Returns yields, risk metrics, spreads, pricing, and schedule using the most recent market price. Accepts ISIN, ticker, or local ticker as identifier. Use the `fields` query parameter to request only specific sections.\n","security":[{"BearerAuth":[]},{"X402Payment":[]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string"},"description":"Bond ISIN (e.g. US040114HS26), ticker (e.g. GD30D), or local ticker","example":"GD30D"},{"name":"fields","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of response sections to include. Valid values: market, yields, risk, spreads, pricing, schedule, issuance. Identity fields (isin, ticker, settlement) are always included. Omit to receive all sections.\n","example":"market,yields"}],"responses":{"200":{"description":"Full bond analytics with market price","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"traceparent":{"$ref":"#/components/headers/traceparent"}},"content":{"application/json":{"schema":{"type":"object","properties":{"isin":{"type":"string"},"ticker":{"type":"string"},"settlement":{"type":"string","format":"date"},"market":{"type":"object","properties":{"price":{"type":"number"},"timestamp":{"type":"string","nullable":true},"changeAsOf":{"type":"string","nullable":true},"change":{"type":"object","description":"Price changes on the clean basis: deltas difference the clean price against the previous session's clean close (accrued computed off each session's own settlement). A flat dirty market shows a small negative 1D change — one day of accrued interest decay.","properties":{"points1D":{"type":"number","nullable":true,"description":"Absolute 1D move in clean bond price points (percent of face)"},"percent1D":{"type":"number","nullable":true},"points7D":{"type":"number","nullable":true},"percent7D":{"type":"number","nullable":true},"points28D":{"type":"number","nullable":true},"percent28D":{"type":"number","nullable":true},"previousClose":{"type":"number","nullable":true,"description":"Previous session's CLEAN close (same basis as `price`)"},"baselineType":{"type":"string","enum":["prev_close","last_eod"]}}}}},"yields":{"type":"object","description":"Percent, semi-annual bond-equivalent (S.A.) for every bond.","properties":{"ytm":{"type":"number","description":"Yield to maturity (percent, S.A.)"},"ytw":{"type":"number","description":"Yield to worst (percent, S.A.)"},"ytc":{"type":"number","nullable":true,"description":"Lowest valid yield to call (percent, S.A.)"},"ytwCallDate":{"type":"string","nullable":true},"headline":{"type":"number","description":"Quoted yield (percent, S.A.) on the basis in `headlineBasis`. Spreads, duration and average life are measured on it."},"headlineBasis":{"type":"string","enum":["maturity","perpetuity","first_call","worst_call"],"description":"AT1/T2 bank capital is quoted to its first call while that call is at least six months after settlement (`first_call`); a dated callable whose yield to worst runs to a call at least six months after settlement to that call (`worst_call`, where `headline` equals `ytw`); perpetuals to perpetuity; everything else to maturity, where `headline` equals `ytm`. Spreads, duration, convexity, DV01 and average life are measured on the same flows."},"currentYield":{"type":"number"}}},"risk":{"type":"object","properties":{"modifiedDuration":{"type":"number","description":"Macaulay duration / (1 + ytm/200), on the S.A. yield"},"macaulayDuration":{"type":"number"},"effectiveDuration":{"type":"number"},"convexity":{"type":"number"},"dv01":{"type":"number"}}},"spreads":{"type":"object","properties":{"gSpread":{"type":"number","description":"S.A. yield minus the interpolated Treasury CMT yield (basis points)"},"zSpread":{"type":"number","description":"Spread over the semi-annual Treasury zero curve (basis points)"},"treasuryYield":{"type":"number","description":"Interpolated Treasury CMT yield (percent, semi-annual)"},"treasuryTenor":{"type":"string"},"discountMargin":{"type":"number","description":"SOFR floating-rate notes only. Margin over SOFR (bps) that prices the bond with SOFR held at the 30-day SOFR Average; ACT/360 basis."},"discountMarginIndex":{"type":"number","description":"SOFR floating-rate notes only. The flat SOFR level (percent) the discount margin is measured over."}}},"conventions":{"$ref":"#/components/schemas/Conventions"},"pricing":{"type":"object","properties":{"cleanPrice":{"type":"number"},"accruedInterest":{"type":"number"},"dirtyPrice":{"type":"number"}}},"schedule":{"type":"object","properties":{"nextCouponDate":{"type":"string"},"daysToNextCoupon":{"type":"integer"},"averageLife":{"type":"number","description":"Average life in years, on the flows in `yields.headlineBasis` (to the call for `first_call` and `worst_call`). Changed in 1.3.0."}}}}},"example":{"isin":"US040114HS26","ticker":"ARGENT 4.625 35","settlement":"2026-02-02","market":{"price":65.2,"timestamp":"2026-01-29T18:30:00Z","changeAsOf":"2026-02-12T14:31:05Z","change":{"points1D":0.33,"percent1D":0.46,"points7D":null,"percent7D":null,"points28D":null,"percent28D":null,"previousClose":64.87,"baselineType":"prev_close"}},"yields":{"ytm":12.1,"ytw":11.9,"ytc":11.9,"ytwCallDate":"2028-07-09","currentYield":7.09},"risk":{"modifiedDuration":5.2,"macaulayDuration":5.48,"effectiveDuration":4.93,"convexity":34.12,"dv01":0.0349},"spreads":{"gSpread":815,"zSpread":773,"treasuryYield":3.77,"treasuryTenor":"7Y"},"pricing":{"cleanPrice":65.2,"accruedInterest":1.93,"dirtyPrice":67.13},"schedule":{"nextCouponDate":"2026-07-09","daysToNextCoupon":160,"averageLife":7.32},"conventions":{"yield":"semi-annual","compounding":2,"spreads":"semi-annual","time":"ACT/365","methodologyUrl":"https://bondterminal.com/methodology/yields"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The bond exists but has no market price to calculate from","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"no_market_data","message":"No market price available for 'US040114HS26'. Send a price to POST /api/v1/calculate to get analytics at that price."}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/bonds/{identifier}/history":{"get":{"tags":["Bonds"],"summary":"Get historical price, yield, and spread data","operationId":"getBondHistory","description":"Returns daily historical series for a bond including price, YTM (with its yield basis), YTW, and spread. Use named ranges (1w, 1m, 3m, ytd, 1y, 2y) or explicit start/end dates. When both start and end are provided, they override the range parameter. Keyless x402 access costs $0.10 USDC per request. A full API-key response costs 10 read units; not-found lookups still consume them. API-key clients can resend the response ETag in If-None-Match; an unchanged 304 response costs 0 read units. x402 requests remain paid full responses.\n","security":[{"BearerAuth":[]},{"X402Payment":[]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string"},"description":"Bond ISIN (e.g. US040114HS26), ticker (e.g. GD30D), or local ticker","example":"GD30D"},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["1w","1m","3m","ytd","1y","2y"],"default":"1m"},"description":"Named date range. Ignored when both start and end are provided.","example":"1m"},{"name":"start","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start date (YYYY-MM-DD). Overrides range when both start and end are provided.","example":"2025-12-01"},{"name":"end","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End date (YYYY-MM-DD). Overrides range when both start and end are provided.","example":"2026-01-30"}],"responses":{"200":{"description":"Historical data with daily series","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-Quota-Limit":{"$ref":"#/components/headers/X-Quota-Limit"},"X-Quota-Remaining":{"$ref":"#/components/headers/X-Quota-Remaining"},"X-Quota-Reset":{"$ref":"#/components/headers/X-Quota-Reset"},"X-Read-Quota-Limit":{"$ref":"#/components/headers/X-Read-Quota-Limit"},"X-Read-Quota-Remaining":{"$ref":"#/components/headers/X-Read-Quota-Remaining"},"X-Read-Quota-Reset":{"$ref":"#/components/headers/X-Read-Quota-Reset"},"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"ETag":{"$ref":"#/components/headers/ETag"},"traceparent":{"$ref":"#/components/headers/traceparent"}},"content":{"application/json":{"schema":{"type":"object","properties":{"isin":{"type":"string","example":"US040114HS26"},"ticker":{"type":"string","example":"GD30D"},"conventions":{"$ref":"#/components/schemas/Conventions"},"range":{"type":"object","properties":{"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"},"points":{"type":"integer"}}},"series":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"price":{"type":"number","description":"Clean price as % of face"},"ytm":{"type":"number","description":"The quoted (headline) yield in percent, semi-annual bond-equivalent (S.A.); `yieldBasis` names what it is measured to on that date. Dates before 27-Sep-2026 are restated on the same basis.\n"},"yieldBasis":{"type":"string","enum":["maturity","perpetuity","first_call","worst_call"],"description":"What `ytm` is measured to on that date, by the rule of `yields.headlineBasis`: `first_call` for AT1/T2 bank capital whose first call is at least six months after that date's settlement, `worst_call` for a dated callable whose yield to worst ran to a call at least six months away (then `ytm` equals `ytw`), `perpetuity` for perpetuals, `maturity` otherwise (a bond with an announced redemption known on that date is measured to it). Present whenever `ytm` is. Added 27-Sep-2026.\n"},"ytw":{"type":"number","description":"Yield to worst in percent, S.A.: the lowest of the maturity yield and every call outcome. Equals the maturity yield for non-callable bonds. Added 27-Sep-2026.\n"},"spread":{"type":"integer","description":"G-spread in basis points, measured on `ytm`: on the S.A. basis over Treasuries, or for EUR bonds on the annual basis over Bunds (`spreadBenchmark`). Absent for US Treasuries and German Bunds.\n"},"spreadBenchmark":{"type":"string","enum":["UST","BUND"],"description":"The curve `spread` is over. Present whenever `spread` is, except on a SOFR floater (`spreadBasis`). Added 22-Oct-2026.\n"},"spreadBasis":{"type":"string","enum":["dm_flat_sofr"],"description":"SOFR floaters only. `spread` is the discount margin over flat SOFR. Added 22-Oct-2026."}}}}}},"example":{"isin":"US040114HS26","ticker":"GD30D","range":{"start":"2025-12-31","end":"2026-01-30","points":22},"series":[{"date":"2025-12-31","price":68.25,"ytm":14.82,"yieldBasis":"maturity","ytw":14.82,"spread":1052},{"date":"2026-01-02","price":68.5,"ytm":14.76,"yieldBasis":"maturity","ytw":14.76,"spread":1046}],"conventions":{"yield":"semi-annual","compounding":2,"spreads":"semi-annual","time":"ACT/365","methodologyUrl":"https://bondterminal.com/methodology/yields"}}}}},"304":{"description":"Series unchanged. API-key requests only; consumes 0 read units.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-Read-Quota-Limit":{"$ref":"#/components/headers/X-Read-Quota-Limit"},"X-Read-Quota-Remaining":{"$ref":"#/components/headers/X-Read-Quota-Remaining"},"X-Read-Quota-Reset":{"$ref":"#/components/headers/X-Read-Quota-Reset"},"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"ETag":{"$ref":"#/components/headers/ETag"},"traceparent":{"$ref":"#/components/headers/traceparent"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"description":"Bond not found (not_found), or its currency has no supported price history lane (NO_HISTORY).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"NO_HISTORY","message":"No price history for this bond's currency"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/treasury-curve":{"get":{"tags":["Market Data"],"summary":"Get US Treasury yield curve","operationId":"getTreasuryCurve","description":"Current US Treasury yield curve rates across all standard tenors. This is a public endpoint - no authentication required. `date` is the market observation date for the curve, while `lastUpdated` is when BondTerminal refreshed the cache snapshot.\n","security":[],"responses":{"200":{"description":"Current treasury rates","headers":{"traceparent":{"$ref":"#/components/headers/traceparent"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TreasuryCurve"},"example":{"date":"2026-02-17","rates":{"1M":4.1,"3M":4.2,"6M":4.3,"1Y":4.4,"2Y":4.5,"3Y":4.6,"5Y":4.7,"7Y":3.77,"10Y":4.01,"20Y":4.62,"30Y":4.67},"source":"TREASURY_GOV","lastUpdated":"2026-02-18T13:49:43Z"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/riesgo-pais":{"get":{"tags":["Riesgo País"],"summary":"Current Argentina country risk (riesgo país)","operationId":"getRiesgoPais","description":"Returns the current EMBI spread in basis points, with daily/weekly/monthly deltas.\n","security":[{"BearerAuth":[]},{"X402Payment":[]}],"responses":{"200":{"description":"Current riesgo país data","headers":{"traceparent":{"$ref":"#/components/headers/traceparent"}},"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2026-02-04"},"spreadBps":{"type":"number","nullable":true,"example":516,"description":"EMBI spread in basis points"},"deltas":{"type":"object","properties":{"1d":{"type":"number","nullable":true,"example":-15},"1w":{"type":"number","nullable":true,"example":30},"1m":{"type":"number","nullable":true,"example":-45}}},"lastUpdated":{"type":"string","example":"2026-02-04"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/riesgo-pais/methodology":{"get":{"tags":["Riesgo País"],"summary":"Riesgo país methodology and FAQ","operationId":"getRiesgoPaisMethodology","description":"Returns the same methodology overview and FAQ content shown on the flagship answer page, as structured JSON for agent/API consumers.\n","security":[{"BearerAuth":[]},{"X402Payment":[]}],"responses":{"200":{"description":"Methodology sections and FAQ","headers":{"traceparent":{"$ref":"#/components/headers/traceparent"}},"content":{"application/json":{"schema":{"type":"object","properties":{"methodology":{"type":"array","items":{"type":"object","properties":{"heading":{"type":"string"},"paragraphs":{"type":"array","items":{"type":"string"}},"list":{"type":"array","items":{"type":"string"}}}}},"faq":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/riesgo-pais/history":{"get":{"tags":["Riesgo País"],"summary":"Historical riesgo país time series","operationId":"getRiesgoPaisHistory","description":"Returns historical EMBI spread series. Use named ranges or explicit start/end dates. Costs 1 read unit.\n","security":[{"BearerAuth":[]},{"X402Payment":[]}],"parameters":[{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["1m","3m","6m","ytd","1y","2y","max"],"default":"1y"},"description":"Named range (1m, 3m, 6m, ytd, 1y, 2y, max). Ignored when both start and end are provided.","example":"1y"},{"name":"start","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start date YYYY-MM-DD (overrides range when both start and end are provided)","example":"2025-02-04"},{"name":"end","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End date YYYY-MM-DD (overrides range when both start and end are provided)","example":"2026-02-04"}],"responses":{"200":{"description":"Historical riesgo país series","headers":{"traceparent":{"$ref":"#/components/headers/traceparent"}},"content":{"application/json":{"schema":{"type":"object","properties":{"range":{"type":"object","properties":{"start":{"type":"string","format":"date","example":"2025-02-04"},"end":{"type":"string","format":"date","example":"2026-02-04"},"points":{"type":"integer","example":248}}},"series":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"spreadBps":{"type":"number"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key with bt_live_ prefix. Create your key at bondterminal.com/developers"},"X402Payment":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"x402 payment protocol. Standard requests cost $0.01 USDC on Base; bond-history requests cost $0.10, and batch endpoints require an API key. Send a signed USDC payment in the PAYMENT-SIGNATURE header (legacy X-PAYMENT also accepted). No API key required. See x402.org for details.\n"}},"headers":{"RateLimit-Policy":{"schema":{"type":"string","example":"\"default\";q=100;w=60"},"description":"Rate limit policy (quota and window in seconds)"},"RateLimit":{"schema":{"type":"string","example":"\"default\";r=99;t=60"},"description":"Current rate limit state (remaining and time to reset)"},"X-Quota-Limit":{"schema":{"type":"string","example":"1000"},"description":"Daily bond calculation quota"},"X-Quota-Remaining":{"schema":{"type":"string","example":"247"},"description":"Remaining calculations today"},"X-Quota-Reset":{"schema":{"type":"string","example":"2026-01-29T00:00:00Z"},"description":"Quota reset time (midnight UTC)"},"X-Read-Quota-Limit":{"schema":{"type":"string","example":"200"},"description":"Daily read-unit quota"},"X-Read-Quota-Remaining":{"schema":{"type":"string","example":"94"},"description":"Remaining read units today"},"X-Read-Quota-Reset":{"schema":{"type":"string","example":"2026-09-04T00:00:00.000Z"},"description":"Read-unit quota reset time (midnight UTC)"},"Cache-Control":{"schema":{"type":"string","example":"private, max-age=300"},"description":"Response cache policy"},"ETag":{"schema":{"type":"string","example":"\"0f52b69d\""},"description":"Representation validator for conditional requests"},"traceparent":{"schema":{"type":"string","example":"00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"},"description":"W3C Trace Context identifier for request correlation"},"Retry-After":{"schema":{"type":"string","example":"60"},"description":"Seconds to wait before retrying (on 429 responses)"}},"schemas":{"Conventions":{"type":"object","description":"The convention behind every yield, duration and spread in the response. Every yield-bearing response carries it from 27-Sep-2026.\n","properties":{"yield":{"type":"string","enum":["semi-annual"],"description":"Yields are semi-annual bond-equivalent for every bond, whatever its coupon frequency."},"compounding":{"type":"integer","enum":[2],"description":"Compounding periods per year of every yield."},"spreads":{"type":"string","enum":["semi-annual","annual"],"description":"`semi-annual`: G-spread and Z-spread are measured on the same basis, against the semi-annual Treasury curve. `annual`: a EUR bond's spreads over the Bund curve, measured on `yields.ytmAnnual`. Added `annual` 22-Oct-2026.\n"},"spreadBenchmark":{"type":"string","enum":["BUND"],"description":"EUR bonds only: the spreads are over the Bund curve. Absent means the Treasury curve. Added 22-Oct-2026.\n"},"annualYield":{"type":"object","description":"EUR bonds only. The yield the Bund spreads use; `ytm` stays S.A.","properties":{"field":{"type":"string","enum":["yields.ytmAnnual"]},"compounding":{"type":"integer","enum":[1]}}},"zSpread":{"type":"string","enum":["continuous"],"description":"EUR bonds only. Z-spread is continuously compounded over the Bund zero curve."},"time":{"type":"string","enum":["ACT/365"],"description":"Year-fraction basis for discounting."},"methodologyUrl":{"type":"string","format":"uri","description":"How BondTerminal calculates yields: which yield leads for each kind of bond (YTM, YTW, YTC, YTP) and what spreads and duration are measured to. Added in 1.3.0.\n"}},"example":{"yield":"semi-annual","compounding":2,"spreads":"semi-annual","time":"ACT/365","methodologyUrl":"https://bondterminal.com/methodology/yields"}},"ConventionsEnvelope":{"type":"object","properties":{"conventions":{"$ref":"#/components/schemas/Conventions"}}},"CashflowResponse":{"type":"object","properties":{"isin":{"type":"string"},"ticker":{"type":"string"},"name":{"type":"string"},"settlement":{"type":"string","format":"date"},"cashflows":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"couponPayment":{"type":"number"},"principalPayment":{"type":"number"},"totalPayment":{"type":"number"},"remainingNotional":{"type":"number"},"paymentType":{"type":"string","enum":["COUPON","AMORTIZATION","MATURITY","CALL","PUT"]}}}},"summary":{"type":"object","properties":{"count":{"type":"integer"},"totalCoupon":{"type":"number"},"totalPrincipal":{"type":"number"},"totalCashflow":{"type":"number"},"finalDate":{"type":"string","format":"date","nullable":true}}}}},"CalculateRequest":{"type":"object","properties":{"isin":{"type":"string","description":"Bond ISIN (preferred)"},"ticker":{"type":"string","description":"Bond ticker (e.g., ARGENT 0.75 30)"},"localTicker":{"type":"string","description":"Local market ticker (e.g., AL30D)"},"price":{"type":"number","description":"Clean price as % of face (e.g. 95.5)"},"ytm":{"type":"number","description":"Yield to maturity in percent, semi-annual bond-equivalent (e.g. 12.5)"},"gSpread":{"type":"number","description":"G-spread in basis points (e.g. 350), on the `yields.headlineBasis` the response reports (first call for AT1/T2 capital, worst call for a callable quoted there)"},"zSpread":{"type":"number","description":"Z-spread in basis points (e.g. 420), on the `yields.headlineBasis` the response reports (first call for AT1/T2 capital, worst call for a callable quoted there)"},"settlement":{"type":"string","format":"date","description":"Settlement date (YYYY-MM-DD). Defaults to quote-market settlement when a local market quote symbol can be resolved; otherwise each bond's settlementDays, or T+2 business days."}},"description":"Exactly one of isin, ticker, or localTicker must be provided. Exactly one of price, ytm, gSpread, or zSpread must be provided.\n"},"BatchRequest":{"type":"object","required":["bonds"],"properties":{"bonds":{"type":"array","items":{"type":"object","properties":{"isin":{"type":"string"},"ticker":{"type":"string"},"localTicker":{"type":"string"},"price":{"type":"number"},"ytm":{"type":"number","description":"Yield to maturity in percent, semi-annual bond-equivalent"},"gSpread":{"type":"number"},"zSpread":{"type":"number"}}},"minItems":1,"maxItems":50,"description":"Array of bond inputs (max 50). Each must include exactly one identifier and one input (price/ytm/gSpread/zSpread)."},"settlement":{"type":"string","format":"date","description":"Shared settlement date for all bonds"}}},"OptionAdjusted":{"type":"object","nullable":true,"description":"Live USD option-adjusted spread and duration, with model assumptions. OAS is not an input.","properties":{"status":{"type":"string","nullable":true,"enum":["ok","unavailable"]},"reason":{"type":"string","nullable":true,"description":"Unavailable reason; null when status is ok."},"oas":{"type":"number","nullable":true,"description":"Option-adjusted spread in bps, rounded to one decimal."},"zSpreadToMaturity":{"type":"number","nullable":true,"description":"Z-spread to maturity in bps, on the same semiannual curve-shift basis as OAS."},"optionValueBps":{"type":"number","nullable":true,"description":"Z-spread to maturity minus OAS, in bps."},"optionAdjustedDuration":{"type":"number","nullable":true,"description":"Effective duration in years with OAS held fixed and calls valued again."},"assumptions":{"type":"object","nullable":true,"properties":{"model":{"type":"string","enum":["hull-white-1f"]},"rateVolBps":{"type":"number"},"volSource":{"type":"string","enum":["realized","assumed"]},"volAsOf":{"type":"string","nullable":true,"format":"date"},"hwSigmaBps":{"type":"number"},"meanReversion":{"type":"number"},"curveAsOf":{"type":"string","format":"date"},"modelVersion":{"type":"string"}}}}},"BondAnalytics":{"type":"object","properties":{"optionAdjusted":{"$ref":"#/components/schemas/OptionAdjusted"},"isin":{"type":"string"},"ticker":{"type":"string"},"price":{"type":"number"},"settlement":{"type":"string","format":"date"},"yields":{"type":"object","properties":{"ytm":{"type":"number","description":"Yield to maturity (percent, semi-annual bond-equivalent)"},"ytw":{"type":"number","description":"Yield to worst (percent, S.A., lowest valid maturity/perpetuity/call workout yield)"},"ytp":{"type":"number","nullable":true,"description":"Yield to perpetuity (percent, S.A., nullable when the bond is not perpetual)"},"ytc":{"type":"number","nullable":true,"description":"Lowest valid yield to call (percent, S.A., nullable when no valid call outcome exists)"},"ytwCallDate":{"type":"string","nullable":true,"description":"Call date behind actual YTW (YYYY-MM-DD, nullable when maturity wins)"},"headline":{"type":"number","description":"Quoted yield (percent, S.A.) on the basis in `headlineBasis`. `spreads`, `risk` and `schedule.averageLife` are measured on it."},"headlineBasis":{"type":"string","enum":["maturity","perpetuity","first_call","worst_call"],"description":"AT1/T2 bank capital is quoted to its first call while that call is at least six months after settlement (`first_call`); a dated callable whose yield to worst runs to a call at least six months after settlement to that call (`worst_call`, where `headline` equals `ytw`); perpetuals to perpetuity; everything else to maturity, where `headline` equals `ytm`. Spreads, duration, convexity, DV01 and average life are measured on the same flows."},"currentYield":{"type":"number","description":"Current yield (percent)"},"ytmAnnual":{"type":"number","description":"EUR bonds only. Yield to maturity on the annual basis (percent), the basis its Bund spreads use. `ytm` stays semi-annual."},"usdHedged":{"type":"number","description":"EUR bonds only. USD-hedged yield (percent) ≈ `ytmAnnual` + (latest NY Fed SOFR − latest ECB €STR), the carry of a rolled 3-month FX hedge at today's rates. An estimate, not an FX forecast; the cross-currency basis is left out."},"usdHedgeRates":{"type":"object","description":"EUR bonds only. The two dated overnight fixings `usdHedged` uses.","properties":{"usd":{"type":"object","properties":{"series":{"type":"string","enum":["SOFR"]},"rate":{"type":"number"},"date":{"type":"string","format":"date"}}},"local":{"type":"object","properties":{"series":{"type":"string","enum":["ESTR"]},"rate":{"type":"number"},"date":{"type":"string","format":"date"}}}}}}},"risk":{"type":"object","properties":{"modifiedDuration":{"type":"number","description":"Macaulay duration / (1 + ytm/200), on the semi-annual yield"},"macaulayDuration":{"type":"number"},"effectiveDuration":{"type":"number"},"convexity":{"type":"number","description":"Convexity with respect to the semi-annual yield"},"dv01":{"type":"number","description":"Dollar value of one basis point of semi-annual yield per 100 original face, computed on dirty price (modified duration × dirty price × 0.0001). Before 2026-09-20 this used clean price; before 2026-10-28 it was per bond denomination (per 1,000 for most bonds)."}}},"spreads":{"type":"object","properties":{"benchmark":{"type":"string","enum":["UST","BUND"],"description":"The government curve the spreads are over. `UST` for USD bonds; `BUND` (Bundesbank Svensson curve of listed Federal securities) for EUR bonds. A bond whose currency has no benchmark returns no spreads."},"gSpread":{"type":"number","description":"G-spread (basis points). `UST`, semi-annual yield minus the interpolated Treasury CMT yield. `BUND`, annual yield minus the Bund par yield (annual coupons) at the matched maturity. Absent for US Treasuries and German Federal bonds, which are the reference curves."},"zSpread":{"type":"number","description":"Z-spread (basis points). `UST`, over the semi-annual Treasury zero curve. `BUND`, a continuously compounded spread over the Bund zero curve. Absent for US Treasuries and German Federal bonds."},"treasuryYield":{"type":"number","description":"`UST` only: interpolated Treasury CMT yield (percent, semi-annual)"},"treasuryTenor":{"type":"string","description":"`UST` only: matched treasury tenor"},"benchmarkYield":{"type":"number","description":"`BUND` only: Bund par yield at the matched maturity (percent, annual)"},"benchmarkTenor":{"type":"string","description":"`BUND` only: matched Bund maturity"},"discountMargin":{"type":"number","description":"SOFR floating-rate notes only. Margin over SOFR, in bps, that prices the bond with SOFR held at today's level (the 30-day SOFR Average). Quoted on the note's ACT/360 basis."},"discountMarginIndex":{"type":"number","description":"SOFR floating-rate notes only. The flat SOFR level (percent) the discount margin is measured over."}}},"pricing":{"type":"object","properties":{"cleanPrice":{"type":"number"},"accruedInterest":{"type":"number"},"dirtyPrice":{"type":"number"}}},"market":{"type":"object","description":"Latest market data (only when available)","properties":{"price":{"type":"number"},"timestamp":{"type":"string","nullable":true},"changeAsOf":{"type":"string","nullable":true},"change":{"type":"object","description":"Price changes on the clean basis: deltas difference the clean price against the previous session's clean close (accrued computed off each session's own settlement). A flat dirty market shows a small negative 1D change — one day of accrued interest decay.","properties":{"points1D":{"type":"number","nullable":true,"description":"Absolute 1D move in clean bond price points (percent of face)"},"percent1D":{"type":"number","nullable":true},"points7D":{"type":"number","nullable":true},"percent7D":{"type":"number","nullable":true},"points28D":{"type":"number","nullable":true},"percent28D":{"type":"number","nullable":true},"previousClose":{"type":"number","nullable":true,"description":"Previous session's CLEAN close (same basis as `price`)"},"baselineType":{"type":"string","enum":["prev_close","last_eod"]}}}}},"schedule":{"type":"object","properties":{"nextCouponDate":{"type":"string"},"daysToNextCoupon":{"type":"number"},"averageLife":{"type":"number","description":"Average life in years, on the flows in `yields.headlineBasis`: to the call for `first_call` and `worst_call` (the tenor of the G-spread's Treasury), else the contractual schedule. Changed in 1.3.0: it was the maturity figure for bonds quoted to a call.\n"}}},"issuance":{"type":"object","nullable":true,"description":"Issuance and outstanding amount data (null when unavailable)","properties":{"originalAmountMillions":{"type":"number"},"currentOutstandingMillions":{"type":"number"},"outstandingRatio":{"type":"number"},"currency":{"type":"string"}}},"workout":{"$ref":"#/components/schemas/WorkoutSummary"},"couponReset":{"type":"object","nullable":true,"properties":{"firstResetDate":{"type":"string","format":"date"},"resetFrequencyYears":{"type":"number"},"referenceRatePct":{"type":"number","nullable":true},"spreadBps":{"type":"number","nullable":true},"projectedCouponRatePct":{"type":"number","nullable":true}}}}},"WorkoutSummary":{"type":"object","properties":{"worstOutcomeId":{"type":"string"},"worstCaseReason":{"type":"string","description":"Human-readable reason for the selected worst workout path"},"warnings":{"type":"array","items":{"type":"string"},"description":"Deduped warning codes from the schedule and outcomes"},"outcomes":{"type":"array","items":{"$ref":"#/components/schemas/WorkoutOutcome"}}}},"WorkoutOutcome":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["maturity","call","perpetuity"]},"date":{"type":"string","description":"ISO date for dated outcomes, or PERPETUAL for perpetuity outcomes"},"redemptionPrice":{"type":"number","description":"Redemption price as percent of outstanding principal"},"yield":{"type":"number","nullable":true,"description":"Workout yield in percent"},"isWorst":{"type":"boolean"},"cashFlowCount":{"type":"integer"},"assumption":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}}},"BatchResponse":{"type":"object","properties":{"results":{"type":"array","items":{"allOf":[{"type":"object","properties":{"index":{"type":"integer","description":"Position in the input array"}}},{"$ref":"#/components/schemas/BondAnalytics"},{"type":"object","properties":{"conventions":{"$ref":"#/components/schemas/Conventions","description":"EUR results only: the Bund conventions of that result. The envelope `conventions` describes USD results. Added 22-Oct-2026.\n"}}}]}},"errors":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"isin":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"}}}},"meta":{"type":"object","properties":{"requested":{"type":"integer"},"successful":{"type":"integer"},"failed":{"type":"integer"}}},"conventions":{"$ref":"#/components/schemas/Conventions"}}},"BondSummary":{"type":"object","properties":{"isin":{"type":"string"},"ticker":{"type":"string"},"name":{"type":"string"},"issuer":{"type":"string"},"country":{"type":"string"},"type":{"type":"string","enum":["sovereign","quasi","corporate"]},"currency":{"type":"string"},"coupon":{"type":"number"},"maturity":{"type":"string","format":"date"}}},"FacetRow":{"type":"object","properties":{"value":{"type":"string"},"count":{"type":"integer"}}},"BondFacetsResponse":{"type":"object","properties":{"asOf":{"type":"string","format":"date"},"total":{"type":"integer"},"countries":{"type":"array","items":{"$ref":"#/components/schemas/FacetRow"}},"issuerTypes":{"type":"array","items":{"$ref":"#/components/schemas/FacetRow"}},"currencies":{"type":"array","items":{"$ref":"#/components/schemas/FacetRow"}},"governingLaws":{"type":"array","items":{"$ref":"#/components/schemas/FacetRow"}},"maturityYears":{"type":"array","items":{"$ref":"#/components/schemas/FacetRow"}},"features":{"type":"object","properties":{"callable":{"type":"integer"},"amortizing":{"type":"integer"},"variableCoupon":{"type":"integer"},"perpetual":{"type":"integer"}}}}},"BondSearchRequest":{"type":"object","properties":{"q":{"type":"string","maxLength":256,"description":"Search across issuer, name, ticker, ISIN, CUSIP and aliases. Every word must match. A word of 3 or more characters also matches inside a longer word; a one-word issuer name (for example Intel) matches whole words only. Separate names with commas to search several issuers in one request, for example \"CoreWeave, Oracle, Core Scientific\"."},"quoteBasis":{"type":"string","enum":["mep","cable","global_usd","global_eur"],"description":"Price lane. Argentine bonds default to cable (USD) and also support mep (USD). Other USD bonds use global_usd; EUR bonds use global_eur (EUR)."},"filters":{"type":"object","properties":{"currency":{"type":"array","description":"ISO 4217 contract currencies, e.g. `[\"EUR\"]`. Unknown codes are dropped with the warning `unknown_currency_dropped`; if every code is unknown, no row matches.\n","items":{"type":"string"}},"governingLaw":{"type":"array","items":{"type":"string"}},"country":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"issuerType":{"type":"array","items":{"type":"string","enum":["sovereign","quasi","corporate"]}},"sector":{"type":"array","items":{"type":"string"}},"ratingMin":{"type":"string"},"ratingMax":{"type":"string"},"includeUnrated":{"type":"boolean"},"includeMatured":{"type":"boolean","description":"Include matured bonds (default false). Note: search results are limited to market-active instruments. Bonds within 120 days of maturity are treated as terminal and excluded regardless of this flag, and instruments with no recent market activity are excluded unless hideStaleBonds is false."},"includeDefaultedClaims":{"type":"boolean","description":"Include defaulted/distressed claims (default false for this API; the interactive app defaults to true)."},"defaultedOnly":{"type":"boolean","description":"Only bonds in default (Venezuela, PDVSA, Lebanon, Braskem). Implies includeDefaultedClaims."},"hideStaleBonds":{"type":"boolean","description":"Exclude instruments with no recent market activity (default false for this API; the interactive app defaults to true)."},"isPerpetual":{"type":"boolean"},"maturityDateFrom":{"type":"string","format":"date"},"maturityDateTo":{"type":"string","format":"date"},"couponMin":{"type":"number"},"couponMax":{"type":"number"},"durationMinYears":{"type":"number"},"durationMaxYears":{"type":"number"},"ytwMin":{"type":"number","minimum":-50,"maximum":200,"description":"Minimum yield to worst in percent, semi-annual (10 means 10%)"},"ytwMax":{"type":"number","minimum":-50,"maximum":200,"description":"Maximum yield to worst in percent, semi-annual (10 means 10%)"},"spreadBpsMin":{"type":"number","minimum":-2000,"maximum":20000,"description":"Minimum spread in basis points (500 means 500bps)"},"spreadBpsMax":{"type":"number","minimum":-2000,"maximum":20000,"description":"Maximum spread in basis points (500 means 500bps)"},"maturityYear":{"type":"array","items":{"type":"integer"}}}},"sort":{"type":"object","description":"Omit for ISIN order. `relevance` returns the same order today.","properties":{"field":{"type":"string","enum":["relevance","maturityDate","coupon","averageRating","price"]},"direction":{"type":"string","enum":["asc","desc"]}}},"page":{"type":"object","properties":{"cursor":{"type":"string"},"size":{"type":"integer","minimum":1,"maximum":500,"description":"Rows per page. Defaults to 200; Basic keys get at most 50."}}}}},"BondSearchRow":{"type":"object","properties":{"optionAdjustedSpread":{"type":"number","nullable":true,"description":"Nightly OAS in bps, one decimal, latest current-model result at most 10 calendar days old. The deprecated oas field remains a G-spread alias."},"oasStatus":{"type":"string","nullable":true,"enum":["ok","unavailable"]},"oasReason":{"type":"string","nullable":true,"description":"Nightly OAS unavailable reason."},"oasAsOf":{"type":"string","nullable":true,"format":"date","description":"Date of the nightly OAS result."},"id":{"type":"string"},"isin":{"type":"string"},"ticker":{"type":"string"},"issuer":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string"},"countryCode":{"type":"string"},"countryName":{"type":"string"},"issuerType":{"type":"string","enum":["sovereign","quasi","corporate","other"]},"sector":{"type":"string","nullable":true},"governingLaw":{"type":"string"},"maturityDate":{"type":"string","format":"date"},"couponRate":{"type":"number","description":"Annual coupon rate in percent. Omitted entirely when the bond has no fixed coupon rate to report — floating-rate notes and bonds with an unknown coupon.\n"},"paymentFrequency":{"type":"integer","enum":[1,2,4,12],"description":"Coupons a year. With the currency it sets the basis BondTerminal displays yields on; `ytm` stays S.A."},"price":{"type":"number"},"ytm":{"type":"number","description":"The quoted (headline) yield in percent, semi-annual bond-equivalent (S.A.); `yieldBasis` names what it is measured to. For AT1/T2 bank capital quoted to a first call this is the yield to that call, not to maturity; for a dated callable quoted to its worst call it is the yield to worst.\n"},"yieldBasis":{"type":"string","enum":["maturity","perpetuity","first_call","worst_call"],"description":"What `ytm` is measured to, by the rule of `yields.headlineBasis` on the quote date: `first_call` for AT1/T2 bank capital whose first call is at least six months after settlement, `worst_call` for a dated callable whose yield to worst runs to a call at least six months away, `perpetuity` for perpetuals, `maturity` otherwise. Present when the row has a yield. Added 27-Sep-2026.\n"},"ytw":{"type":"number","description":"Yield to worst (percent, S.A.): the lowest of the terminal yield and every call outcome, for perpetuals too. Equals the maturity yield for non-callable bonds. Until 27-Sep-2026 a callable perpetual's row repeated its perpetuity yield here.\n"},"leadYield":{"type":"number","description":"The yield BondTerminal leads with for this bond (the calculator's default), in percent, S.A., on `leadYieldBasis`. Present when the row has a yield. Added 27-Sep-2026.\n"},"leadYieldBasis":{"type":"string","enum":["ytm","ytw","ytc","ytp"],"description":"What `leadYield` is: `ytc` (yield to first call) for AT1/T2 bank capital whose first call is at least six months away, `ytp` for perpetuals, `ytw` for dated callables, `ytm` for every other bond and for a dated callable whose worst call is less than six months after settlement. Present when the row has a yield. Added 27-Sep-2026.\n"},"gSpread":{"type":"number","description":"G-spread in basis points, recalculated on the current curve, over the curve `spreadBenchmark` names. `UST`: the semi-annual yield minus the interpolated Treasury CMT. `BUND` (EUR bonds): the annual yield minus the Bund par yield (annual coupons). For a SOFR floater (`spreadBasis: dm_flat_sofr`) it is the discount margin over flat SOFR. Absent for the benchmark issuer itself (US Treasuries, German Bunds). Present whenever `oas` is. Added 15-Oct-2026.\n"},"spreadBenchmark":{"type":"string","enum":["UST","BUND"],"description":"The government curve `gSpread` and `oas` are over: `UST` for USD bonds, `BUND` for EUR bonds. Present whenever `gSpread` is, except on a SOFR floater (`spreadBasis`). Added 22-Oct-2026.\n"},"usdHedgedYield":{"type":"number","description":"EUR bonds only: `leadYield` hedged into USD with a rolled 3-month FX hedge, in percent, S.A. like `leadYield`. The hedge carry (latest NY Fed SOFR minus latest ECB €STR fixing) is added on the annual basis. An estimate, not an FX forecast; the cross-currency basis is left out. Added 22-Oct-2026.\n"},"spreadBasis":{"type":"string","enum":["dm_flat_sofr"],"description":"Set only for SOFR floaters, whose `gSpread` and `oas` are a discount margin over flat SOFR. Absent means a G-spread.\n"},"oas":{"type":"number","deprecated":true,"description":"Same value as `gSpread`. Not an option-adjusted spread. Kept for compatibility; read `gSpread`. Before 1.4.0 it carried the stored end-of-day spread, which could differ from `gSpread`.\n"},"modDuration":{"type":"number","description":"Modified duration (years) on the semi-annual yield"},"outstandingMillions":{"type":"number"},"issuanceMillions":{"type":"number"},"outstandingUsdMillions":{"type":"number","description":"Non-USD bonds only. `outstandingMillions` in USD millions at the day's EUR/USD close; the size filter and size sorts use it."},"issuanceUsdMillions":{"type":"number","description":"Non-USD bonds only. `issuanceMillions` in USD millions at the day's EUR/USD close."},"parity":{"type":"number","description":"Clean price per 100 of remaining principal. Equals price for bullet bonds."},"priceToClaimPct":{"type":"number","description":"Defaulted bonds only. Flat price as a percent of the claim (unpaid principal plus interest at the original coupon since the last coupon paid before the default)."},"ratingMoody":{"type":"string","nullable":true},"ratingSp":{"type":"string","nullable":true},"ratingFitch":{"type":"string","nullable":true},"averageRating":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","matured"]}}},"BondSearchResponse":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/BondSearchRow"}},"nextCursor":{"type":"string","nullable":true},"estimatedTotal":{"type":"integer"},"capped":{"type":"boolean"},"asOf":{"type":"string","format":"date","description":"Market date of the underlying index data (latest priced session across the returned set)."},"suppressedCount":{"type":"integer"},"conventions":{"$ref":"#/components/schemas/Conventions"}}},"BondBatchLookupRequest":{"type":"object","required":["identifiers"],"properties":{"identifiers":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":50},"fields":{"type":"array","items":{"type":"string","enum":["isin","ticker","localTicker","name"]},"description":"Matching fields. Defaults to isin, ticker, and localTicker."},"quoteBasis":{"type":"string","enum":["mep","cable","global_usd","global_eur"],"description":"Price lane. Argentine bonds default to cable (USD) and also support mep (USD). Other USD bonds use global_usd; EUR bonds use global_eur (EUR)."}}},"BondBatchLookupResponse":{"type":"object","properties":{"bonds":{"type":"array","items":{"$ref":"#/components/schemas/BondSearchRow"}},"count":{"type":"integer"},"missing":{"type":"array","items":{"type":"string"}},"conventions":{"$ref":"#/components/schemas/Conventions"}}},"BondDetail":{"type":"object","properties":{"isin":{"type":"string"},"cusip":{"type":"string"},"ticker":{"type":"string"},"name":{"type":"string"},"issuer":{"type":"string"},"country":{"type":"string"},"type":{"type":"string","enum":["sovereign","quasi","corporate"]},"currency":{"type":"string"},"faceValue":{"type":"number"},"coupon":{"type":"number"},"couponFrequency":{"type":"integer","description":"Payments per year"},"dayCountConvention":{"type":"string"},"issueDate":{"type":"string","format":"date"},"maturity":{"type":"string","format":"date"},"settlementDays":{"type":"integer"},"originalIssueAmount":{"type":"number","nullable":true,"description":"Original aggregate principal amount in bond currency units"},"originalIssueCurrency":{"type":"string","nullable":true,"description":"Currency of the original issue amount (ISO 4217)"}}},"TreasuryCurve":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Market observation date for the curve values"},"rates":{"type":"object","properties":{"1M":{"type":"number"},"3M":{"type":"number"},"6M":{"type":"number"},"1Y":{"type":"number"},"2Y":{"type":"number"},"3Y":{"type":"number"},"5Y":{"type":"number"},"7Y":{"type":"number"},"10Y":{"type":"number"},"20Y":{"type":"number"},"30Y":{"type":"number"}}},"source":{"type":"string","description":"Curve provider metadata (`TREASURY_GOV`, `TREASURY_GOV+FRED`, `TREASURY_GOV_PARTIAL`, `FRED`, `FRED_PARTIAL`)"},"lastUpdated":{"type":"string","format":"date-time","description":"Timestamp when BondTerminal last refreshed the cache snapshot"}}},"ErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable error code"},"message":{"type":"string","description":"Human-readable description"},"details":{"type":"object","description":"Additional context"}}},"QuotaErrorDetails":{"type":"object","required":["dimension","limit","used","requested","remaining","resetAt"],"properties":{"dimension":{"type":"string","enum":["calculation_units","read_units"]},"limit":{"type":"integer"},"used":{"type":"integer"},"requested":{"type":"integer"},"remaining":{"type":"integer"},"resetAt":{"type":"string","format":"date-time"}}},"QuotaErrorResponse":{"type":"object","required":["error","message","details"],"properties":{"error":{"type":"string","enum":["quota_exceeded"]},"message":{"type":"string"},"details":{"$ref":"#/components/schemas/QuotaErrorDetails"}}},"RateLimitErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["rate_limited","concurrency_limited"]},"message":{"type":"string"}}},"PaginationMeta":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}},"responses":{"BadRequest":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"invalid_request","message":"Exactly one of price, ytm, gSpread, or zSpread must be provided"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"missing_auth","message":"Authorization header required. Use: Bearer bt_live_..."}}}},"PaymentRequired":{"description":"Payment required. Server returns payment requirements in the PAYMENT-REQUIRED response header. Send signed payment in PAYMENT-SIGNATURE (legacy X-PAYMENT also accepted).\n","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 payment requirements payload."}},"content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"NotFound":{"description":"Bond not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"not_found","message":"Bond not found"}}}},"TooManyRequests":{"description":"Rate limit or quota exceeded. Honor Retry-After; quota errors also include the UTC reset time and request cost.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/QuotaErrorResponse"},{"$ref":"#/components/schemas/RateLimitErrorResponse"}]},"example":{"error":"quota_exceeded","message":"Daily read quota exceeded. Limit: 200 read units per day.","details":{"dimension":"read_units","limit":200,"used":192,"requested":10,"remaining":8,"resetAt":"2026-09-04T00:00:00.000Z"}}}}},"InternalError":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"internal_error","message":"Failed to fetch treasury rates"}}}}}}}