Skip to main content
POST
/
api
/
v1
/
agency_search
US agency bond search
curl --request POST \
  --url https://terrapinfinance.com/api/v1/agency_search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "isins": [
    "US3134HCZH51"
  ]
}
'
{
  "data": [
    {
      "interest_rate": 5.2,
      "interest_type": "fixed rate",
      "is_callable": true,
      "isin": "US3134HCZH51",
      "issuer_name": "FEDERAL HOME LOAN MORTGAGE CORPORATION",
      "maturity_date": "2056-03-16",
      "ticker": "FHLMC 5.2 03/16/56"
    }
  ],
  "total": 1
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
coupon_max
number

Maximum coupon rate of the agency bond (in percentage).

​
coupon_min
number

Minimum coupon rate of the agency bond (in percentage).

​
full_reference_data
boolean

Return full reference data as in from /api/v1/agency_reference. This option requires a special account tier.

​
interest_types
enum<string>[]

Types of interest:

  • fixed rate: The bond pays a fixed interest rate throughout its life.
  • zero rate / discount rate: A bond that does not pay or accrue interest.
  • variable rate: The bond's interest rate can change over time, typically based on a reference rate or formula (e.g., SOFR, CPI).
  • step rate: The bond's interest rate increases ("steps up") at predetermined intervals.
Available options:
fixed rate,
step rate,
variable rate,
zero rate / discount rate
​
is_callable
boolean

Filter by whether the bond is callable.

​
isins
string[]

International Securities Identification Number (ISIN), unique 12-character code for the security.

Required string length: 12
​
issue_date_max
string<date>

Maximum issue date of the agency bond in ISO-8601 format (YYYY-MM-DD).

​
issue_date_min
string<date>

Minimum issue date of the agency bond in ISO-8601 format (YYYY-MM-DD).

​
issued_amount_max
integer

Maximum size of total amount issued (in nominal value).

Required range: x >= 0
​
issued_amount_min
integer

Minimum size of total amount issued (in nominal value).

Required range: x >= 0
​
issuer_name
enum<string>

Name of the issuing agency.

Available options:
FEDERAL HOME LOAN MORTGAGE CORPORATION,
FEDERAL NATIONAL MORTGAGE ASSOCIATION
​
limit
integer
default:100

Result count limit. E.g. if total number of results is 1450, limit of 100 with offset of 0 would return the first 100 results. A limit of 0 returns no results but still includes the total count, which is useful for checking how many results match the given filters.

Required range: x >= 0
​
maturity_date_max
string<date>

Maximum maturity date of the agency bond in ISO-8601 format (YYYY-MM-DD).

​
maturity_date_min
string<date>

Minimum maturity date of the agency bond in ISO-8601 format (YYYY-MM-DD).

​
offset
integer
default:0

Offset for query pagination. E.g. limit of 100 with offset of 50 would return the results 50 to 150.

Required range: x >= 0
​
sort
enum<string>[]

Sort order. Prefix with '-' for descending order.

Available options:
-interest_rate,
-interest_type,
-is_callable,
-isin,
-issuer_name,
-maturity_date,
-ticker,
interest_rate,
interest_type,
is_callable,
isin,
issuer_name,
maturity_date,
ticker
​
values_updated_since
deprecated

Optional filter to only return bonds whose reference data has been updated since the given UTC instant.

Accepts an ISO-8601 date-time (YYYY-MM-DDThh:mm:ssZ), which is recommended since reference data can be updated multiple times per day.

A plain ISO-8601 date (YYYY-MM-DD) is also accepted for backwards compatibility but is deprecated, as it only resolves to the start of that day (00:00:00 UTC).

Response

Partial reference data

​
data
object[]
required

List of response data objects, often capped to 1000.

​
total
integer
required

Total number of results in the database that match the query filters.