Derivatives in Addepar represent financial instruments whose value is derived from an underlying asset, index, or rate. The Derivatives API provides two sub-resources: underlying assets (the entities a derivative tracks) and yield curves (interest rate term structures used for pricing).


Base route	/v1/derivatives
Endpoints	Underlying Assets GET /v1/derivatives/underlying_assets, /v1/derivatives/underlying_assets/:derivative-id POST /v1/derivatives/underlying_assets PATCH /v1/derivatives/underlying_assets, /v1/derivatives/underlying_assets/:derivative-id DELETE /v1/derivatives/underlying_assets, /v1/derivatives/underlying_assets/:derivative-id Yield Curves GET /v1/derivatives/yield_curves, /v1/derivatives/yield_curves/:derivative-id POST /v1/derivatives/yield_curves PATCH /v1/derivatives/yield_curves, /v1/derivatives/yield_curves/:derivative-id DELETE /v1/derivatives/yield_curves, /v1/derivatives/yield_curves/:derivative-id, /v1/derivatives/yield_curves/:derivative-id/rates
Produces	JSON
Pagination	Cursor-based
Application permissions required	"API Access: Create, edit, and delete"
OAuth scopes	GET `PORTFOLIO` POST, PATCH, and DELETE `PORTFOLIO`

Access requirements

All requests require a valid API key or OAuth token with appropriate scopes. Application-level permissions must include "API Access: Create, edit, and delete" for write operations.

Underlying assets

An underlying asset represents the security, index, commodity, or currency pair that a derivative tracks.

Attribute	Description
`id`	Unique identifier for the underlying asset. Integer. Example: `42`
`assetName`	Display name of the asset. String. Example: `"S&P 500"`
`assetType`	Category of the underlying. Enum: `SECURITY`, `INDEX`, `COMMODITY`, `CURRENCY_PAIR`. Example: `"INDEX"`
`underlyingType`	How the asset value is expressed. Enum: `PRICE`, `INDEX`, `EXCHANGE_RATE`. Example: `"PRICE"`
`baseCurrency`	ISO 4217 currency code for the asset. String. Example: `"USD"`
`quoteCurrency`	Quote currency for exchange rate assets. String. Example: `"EUR"`
`financialGraphNodeId`	Addepar entity ID of the linked security. Integer. Example: `1001`
`benchmarkId`	Benchmark entity ID (for index-type assets). Integer. Example: `500`
`metricValues`	Key-value pairs of metric data for the asset. Object. Example: `{"spot_price": 4500.0}`

List underlying assets

Returns all underlying assets, optionally filtered by date range for metric values.

GET /v1/derivatives/underlying_assets

Parameter	Description
`metric_date_from`	Start date for metric values (optional). Format: `YYYY-MM-DD`.
`metric_date_to`	End date for metric values (optional). Format: `YYYY-MM-DD`.
`page[limit]`	Maximum items per page (optional).
`page[cursor]`	Cursor for pagination (optional).

Authentication

This endpoint requires a valid API key or OAuth token. Include your credentials via the Authorization header. For details, see Authentication.

GET https://{firm}.addepar.com/api/v1/derivatives/underlying_assets?metric_date_from=2024-01-01&metric_date_to=2024-12-31

{
    "data": [
        {
            "id": 42,
            "assetName": "S&P 500",
            "assetType": "INDEX",
            "underlyingType": "INDEX",
            "baseCurrency": "USD",
            "quoteCurrency": null,
            "financialGraphNodeId": 1001,
            "benchmarkId": 500,
            "metricValues": {
                "spot_price": 4500.0
            }
        }
    ]
}

Response codes

200 OK -- Success
401 Unauthorized -- Invalid or missing credentials

Get a single underlying asset

Returns a specific underlying asset by ID.

GET /v1/derivatives/underlying_assets/:derivative-id

Parameter	Description
`derivative-id`	ID of the underlying asset (required). Path parameter.
`metric_date_from`	Start date for metric values (optional).
`metric_date_to`	End date for metric values (optional).

GET https://{firm}.addepar.com/api/v1/derivatives/underlying_assets/42

{
    "data": {
        "id": 42,
        "assetName": "S&P 500",
        "assetType": "INDEX",
        "underlyingType": "INDEX",
        "baseCurrency": "USD",
        "quoteCurrency": null,
        "financialGraphNodeId": 1001,
        "benchmarkId": 500,
        "metricValues": {}
    }
}

Response codes

200 OK -- Success
401 Unauthorized -- Invalid or missing credentials
404 Not Found -- Underlying asset does not exist

Create an underlying asset

Creates a new underlying asset record.

POST /v1/derivatives/underlying_assets

POST https://{firm}.addepar.com/api/v1/derivatives/underlying_assets
Content-Type: application/vnd.api+json

{
    "data": {
        "assetName": "Brent Crude Oil",
        "assetType": "COMMODITY",
        "underlyingType": "PRICE",
        "baseCurrency": "USD"
    }
}

{
    "data": {
        "id": 43,
        "assetName": "Brent Crude Oil",
        "assetType": "COMMODITY",
        "underlyingType": "PRICE",
        "baseCurrency": "USD",
        "quoteCurrency": null,
        "financialGraphNodeId": null,
        "benchmarkId": null,
        "metricValues": {}
    }
}

Response codes

201 Created -- Successfully created
400 Bad Request -- Invalid request body
401 Unauthorized -- Invalid or missing credentials

Update underlying assets

Updates one or more underlying assets. Supports both bulk (collection endpoint) and single-resource updates.

PATCH /v1/derivatives/underlying_assets

Updates multiple underlying assets in a single request.

PATCH https://{firm}.addepar.com/api/v1/derivatives/underlying_assets
Content-Type: application/vnd.api+json

{
    "data": {
        "items": [
            {
                "id": 42,
                "assetName": "S&P 500 Index (Updated)"
            }
        ]
    }
}

Response codes

200 OK -- Successfully updated
401 Unauthorized -- Invalid or missing credentials

PATCH /v1/derivatives/underlying_assets/:derivative-id

Updates a single underlying asset.

PATCH https://{firm}.addepar.com/api/v1/derivatives/underlying_assets/42
Content-Type: application/vnd.api+json

{
    "data": {
        "assetName": "S&P 500 Index (Updated)",
        "baseCurrency": "USD"
    }
}

Response codes

200 OK -- Successfully updated
401 Unauthorized -- Invalid or missing credentials
409 Conflict -- Concurrent modification conflict

Delete underlying assets

Deletes one or more underlying assets. Supports both bulk and single-resource deletion.

DELETE /v1/derivatives/underlying_assets

Deletes multiple underlying assets by ID.

DELETE https://{firm}.addepar.com/api/v1/derivatives/underlying_assets
Content-Type: application/vnd.api+json

{
    "data": [
        {"type": "derivatives", "id": "42"},
        {"type": "derivatives", "id": "43"}
    ]
}

Response codes

204 No Content -- Successfully deleted
400 Bad Request -- Invalid request body
401 Unauthorized -- Invalid or missing credentials
409 Conflict -- Asset is referenced by active derivatives

DELETE /v1/derivatives/underlying_assets/:derivative-id

Deletes a single underlying asset.

DELETE https://{firm}.addepar.com/api/v1/derivatives/underlying_assets/42

Response codes

204 No Content -- Successfully deleted
400 Bad Request -- Invalid request
401 Unauthorized -- Invalid or missing credentials
404 Not Found -- Underlying asset does not exist

Yield curves

A yield curve defines an interest rate term structure used for pricing fixed-income derivatives. Each curve has a set of rates at different tenors and dates.

Attribute	Description
`id`	Unique identifier for the yield curve. Integer. Example: `10`
`name`	Display name. String. Example: `"USD LIBOR 3M"`
`currency`	ISO 4217 currency code. String. Example: `"USD"`
`rateType`	Type of interest rate. String. Example: `"SPOT"`
`compoundingFrequency`	How often interest compounds. String. Example: `"CONTINUOUS"`
`dayCountConvention`	Day count basis for rate calculations. String. Example: `"ACT_365"`
`interpolationMethod`	Method for estimating rates between tenors. String. Example: `"LINEAR"`
`extrapolationStrategy`	How to handle rates beyond the curve. String. Example: `"FLAT"`
`isDefault`	Whether this is the default curve for its currency. Boolean. Example: `true`
`rates`	Array of rate observations (see below). Array.

Rate object attributes:

Attribute	Description
`as_of_date`	Observation date. String (`YYYY-MM-DD`). Example: `"2024-06-15"`
`tenor`	Time to maturity in years. Number. Example: `0.25`
`rate`	Annualized interest rate (decimal). Number. Example: `0.0525`

List yield curves

Returns all yield curves.

GET /v1/derivatives/yield_curves

Parameter	Description
`page[limit]`	Maximum items per page (optional).
`page[cursor]`	Cursor for pagination (optional).

GET https://{firm}.addepar.com/api/v1/derivatives/yield_curves

{
    "data": [
        {
            "id": 10,
            "name": "USD LIBOR 3M",
            "currency": "USD",
            "rateType": "SPOT",
            "compoundingFrequency": "CONTINUOUS",
            "dayCountConvention": "ACT_365",
            "interpolationMethod": "LINEAR",
            "extrapolationStrategy": "FLAT",
            "isDefault": true,
            "rates": [
                {
                    "as_of_date": "2024-06-15",
                    "tenor": 0.25,
                    "rate": 0.0525
                },
                {
                    "as_of_date": "2024-06-15",
                    "tenor": 1.0,
                    "rate": 0.0540
                }
            ]
        }
    ]
}

Response codes

200 OK -- Success
401 Unauthorized -- Invalid or missing credentials

Get a single yield curve

Returns a specific yield curve by ID.

GET /v1/derivatives/yield_curves/:derivative-id

GET https://{firm}.addepar.com/api/v1/derivatives/yield_curves/10

{
    "data": {
        "id": 10,
        "name": "USD LIBOR 3M",
        "currency": "USD",
        "rateType": "SPOT",
        "compoundingFrequency": "CONTINUOUS",
        "dayCountConvention": "ACT_365",
        "interpolationMethod": "LINEAR",
        "extrapolationStrategy": "FLAT",
        "isDefault": true,
        "rates": []
    }
}

Response codes

200 OK -- Success
401 Unauthorized -- Invalid or missing credentials
404 Not Found -- Yield curve does not exist

Create a yield curve

Creates a new yield curve with optional initial rates.

POST /v1/derivatives/yield_curves

POST https://{firm}.addepar.com/api/v1/derivatives/yield_curves
Content-Type: application/vnd.api+json

{
    "data": {
        "name": "EUR Swap Curve",
        "currency": "EUR",
        "rateType": "SPOT",
        "compoundingFrequency": "SEMI_ANNUAL",
        "dayCountConvention": "ACT_360",
        "interpolationMethod": "CUBIC_SPLINE",
        "extrapolationStrategy": "FLAT",
        "isDefault": false,
        "rates": [
            {"as_of_date": "2024-06-15", "tenor": 0.5, "rate": 0.035},
            {"as_of_date": "2024-06-15", "tenor": 1.0, "rate": 0.038}
        ]
    }
}

{
    "data": {
        "id": 11,
        "name": "EUR Swap Curve",
        "currency": "EUR",
        "rateType": "SPOT",
        "compoundingFrequency": "SEMI_ANNUAL",
        "dayCountConvention": "ACT_360",
        "interpolationMethod": "CUBIC_SPLINE",
        "extrapolationStrategy": "FLAT",
        "isDefault": false,
        "rates": [
            {"as_of_date": "2024-06-15", "tenor": 0.5, "rate": 0.035},
            {"as_of_date": "2024-06-15", "tenor": 1.0, "rate": 0.038}
        ]
    }
}

Response codes

201 Created -- Successfully created
400 Bad Request -- Invalid request body
401 Unauthorized -- Invalid or missing credentials

Update yield curves

Updates one or more yield curves. Supports bulk and single-resource updates.

PATCH /v1/derivatives/yield_curves

PATCH https://{firm}.addepar.com/api/v1/derivatives/yield_curves
Content-Type: application/vnd.api+json

{
    "data": {
        "items": [
            {
                "id": 10,
                "name": "USD SOFR 3M"
            }
        ]
    }
}

Response codes

200 OK -- Successfully updated
401 Unauthorized -- Invalid or missing credentials

PATCH /v1/derivatives/yield_curves/:derivative-id

PATCH https://{firm}.addepar.com/api/v1/derivatives/yield_curves/10
Content-Type: application/vnd.api+json

{
    "data": {
        "name": "USD SOFR 3M",
        "interpolationMethod": "CUBIC_SPLINE"
    }
}

Response codes

200 OK -- Successfully updated
401 Unauthorized -- Invalid or missing credentials
409 Conflict -- Concurrent modification conflict

Delete yield curves

Deletes one or more yield curves.

DELETE /v1/derivatives/yield_curves

DELETE https://{firm}.addepar.com/api/v1/derivatives/yield_curves
Content-Type: application/vnd.api+json

{
    "data": [
        {"type": "derivatives", "id": "11"}
    ]
}

Response codes

204 No Content -- Successfully deleted
400 Bad Request -- Invalid request body
401 Unauthorized -- Invalid or missing credentials
409 Conflict -- Yield curve is referenced by active derivatives

DELETE /v1/derivatives/yield_curves/:derivative-id

DELETE https://{firm}.addepar.com/api/v1/derivatives/yield_curves/10

Response codes

204 No Content -- Successfully deleted
400 Bad Request -- Invalid request
401 Unauthorized -- Invalid or missing credentials
404 Not Found -- Yield curve does not exist

Delete yield curve rates

Deletes rates for a specific yield curve on a given date.

DELETE /v1/derivatives/yield_curves/:derivative-id/rates

Parameter	Description
`derivative-id`	ID of the yield curve (required). Path parameter.
`as_of_date`	Date of the rates to delete (required). Query parameter. Format: `YYYY-MM-DD`.

DELETE https://{firm}.addepar.com/api/v1/derivatives/yield_curves/10/rates?as_of_date=2024-06-15

Response codes

204 No Content -- Successfully deleted
400 Bad Request -- Missing as_of_date parameter
401 Unauthorized -- Invalid or missing credentials
404 Not Found -- Yield curve does not exist

Related resources

Underlying Assets | Derivatives Migration