Underlying Assets
This route provides access to V1 Underlying Assets.
Get underlying asset by ID
GET /v1/derivatives/underlying_assets/:id retrieves an underlying asset by ID.
Query parameters
metric_date_from: Start date, inclusive, for returning the asset's spot values.
Optional, if omitted then no spot values are returned.metric_date_to: End date, inclusive, for returning the asset's spot values.
Optional, if omitted then no spot values are returned.
Use ISO 8601 extended format for the metric dates.
To include a month's spot values with entity 1234,
/v1/derivatives/underlying_assets/1234?metric_date_from=2025-01-01&metric_date_to=2025-01-31
Responses
200 OK: success
{
"data" : {
"id" : "1234",
"type" : "derivatives_underlying_assets",
"attributes" : {
"entity_name" : "corporate bond",
"entity_type" : "SECURITY",
"underlying_type": "PRICE",
"base_currency" : "USD",
"metric_values": {
"2025-01-01": 4.0,
"2025-01-02": 5.0,
"2025-01-03": 6.0
}
},
"links" : {
"self" : "/v1/derivatives_underlying_assets/1234"
}
}
}
403 Forbidden: not permitted to make the request404 Not Found: an entity with the given ID is not available to the requester
Get all underlying assets
GET /v1/derivatives/underlying_assets retrieves a page of underlying assets.
Query parameters
page[after]: How many entities to skip before starting to return assets.
Optional, defaults to 0.page[limit]: How many assets to return, at most.
Optional, defaults to the server-side maximum.metric_date_from: Start date, inclusive, for returning the entities' spot values.
Optional, if omitted then no spot values are returned.metric_date_to: End date, inclusive, for returning the entities' spot values.
Optional, if omitted then no spot values are returned.
Use ISO 8601 extended format for the metric dates.
For example, for a later page of entities (without spot values), use parameters like,
/v1/derivatives/underlying_assets?page[after]=60&page[limit]=20
To include a month's spot values with each of the first page of entities,
/v1/derivatives/underlying_assets?metric_date_from=2025-01-01&metric_date_to=2025-01-31
Note that a high page limit with a large window for spot values may result in a large response.
Responses
200 OK: success
{
"data": [
{
"id": "1234",
"type": "derivatives_underlying_assets",
"attributes": {
"entity_name": "some stock",
"entity_type": "SECURITY",
"underlying_type": "PRICE",
"base_currency": "USD",
"metric_values": {
"2025-01-01": 4.0,
"2025-01-02": 5.0,
"2025-01-03": 6.0
}
},
"links": {
"self": "/v1/derivatives_underlying_assets/1234"
}
},
{
"id": "1235",
"type": "derivatives_underlying_assets",
"attributes": {
"entity_name": "some other stock",
"entity_type": "SECURITY",
"underlying_type": "PRICE",
"base_currency": "USD",
"metric_values": {
"2025-01-01": 2.3,
"2025-01-02": 2.4,
"2025-01-03": 2.5
}
},
"links": {
"self": "/v1/derivatives_underlying_assets/1235"
}
}
]
}
403 Forbidden: not permitted to make the request
Create underlying assets
POST /v1/derivatives/underlying_assets creates one or many underlying assets.
Do not provide an id because that field will be assigned by the server.
Requests
Single entity:
{
"data": {
"type": "derivatives_underlying_assets",
"attributes": {
"entity_name": "my underlying stock",
"entity_type": "SECURITY",
"underlying_type": "PRICE",
"base_currency": "USD",
"financial_graph_node_id": 789,
"metric_values": {
"2025-01-01": 4.0,
"2025-01-02": 5.0,
"2025-01-03": 6.0
}
}
}
}
Multiple entities:
{
"data": [
{
"type": "derivatives_underlying_assets",
"attributes": {
"entity_name": "some stock",
"entity_type": "SECURITY",
"underlying_type": "PRICE",
"base_currency": "GBP",
"metric_values": {
"2025-01-01": 4.0,
"2025-01-02": 5.0,
"2025-01-03": 6.0
}
}
},
{
"type": "derivatives_underlying_assets",
"attributes": {
"entity_name": "some other stock",
"entity_type": "SECURITY",
"underlying_type": "PRICE",
"base_currency": "GBP",
"metric_values": {
"2025-01-01": 2.3,
"2025-01-02": 2.4,
"2025-01-03": 2.5
}
}
}
]
}
Responses
201 Created: success
Single entity:
{
"data" : {
"id" : "1234",
"type": "derivatives_underlying_assets",
"attributes": {
"entity_name": "my underlying stock",
"entity_type": "SECURITY",
"underlying_type": "PRICE",
"base_currency": "USD",
"financial_graph_node_id": 789,
"metric_values": {
"2025-01-01": 4.0,
"2025-01-02": 5.0,
"2025-01-03": 6.0
}
},
"links" : {
"self" : "/v1/derivatives_underlying_assets/1234"
}
}
}
Multiple entities:
{
"data": [
{
"id": "1234",
"type": "derivatives_underlying_assets",
"attributes": {
"entity_name": "some stock",
"entity_type": "SECURITY",
"underlying_type": "PRICE",
"base_currency": "GBP",
"metric_values": {
"2025-01-01": 4.0,
"2025-01-02": 5.0,
"2025-01-03": 6.0
}
},
"links": {
"self": "/v1/derivatives_underlying_assets/1234"
}
},
{
"id": "1235",
"type": "derivatives_underlying_assets",
"attributes": {
"entity_name": "some other stock",
"entity_type": "SECURITY",
"underlying_type": "PRICE",
"base_currency": "GBP",
"metric_values": {
"2025-01-01": 2.3,
"2025-01-02": 2.4,
"2025-01-03": 2.5
}
},
"links": {
"self": "/v1/derivatives_underlying_assets/1235"
}
}
]
}
400 Bad Request: invalid payload403 Forbidden: not permitted to make the request
Patching underlying assets
When patches are presented for underlying assets, required attributes may be omitted:
they are filled in with their previous values.
metric_values is a special case of an optional attribute because of its object value.
If the attribute is wholly omitted then the entity's spot values are unchanged.
If included then the patch applies to the inclusive interval
from the earliest given date to the latest:
- Spot values outside the interval remain unchanged.
- Spot values patched as
nullinstead of as a number are deleted. - Spot values within the interval are provided in the response to confirm the result of the patch.
Patch underlying asset by ID
PATCH /v1/derivatives/underlying_assets/:id modifies an underlying asset.
Requests
{
"data": {
"id": "1234",
"type": "derivatives_underlying_assets",
"attributes": {
"entity_name": "my stock",
"entity_type": "SECURITY",
"base_currency": "USD",
"metric_values": {
"2025-01-01": 7.0,
"2025-01-02": null,
"2025-01-04": 8.0
}
}
}
}
Responses
200 OK: success
{
"data": {
"id": "1234",
"type": "derivatives_underlying_assets",
"attributes": {
"entity_name": "my stock",
"entity_type": "SECURITY",
"underlying_type": "PRICE",
"base_currency": "USD",
"metric_values": {
"2025-01-01": 7.0,
"2025-01-03": 6.0,
"2025-01-04": 8.0
}
},
"links": {
"self": "/v1/derivatives_underlying_assets/1234"
}
}
}
400 Bad Request: invalid payload403 Forbidden: not permitted to make the request404 Not Found: an entity with the given ID is not available to the requester409 Conflict: ID in path does not match ID in payload
Patch underlying assets
PATCH /v1/derivatives/underlying_assets modifies one or many underlying assets.
Requests
Single entity:
{
"data": {
"id": "1234",
"type": "derivatives_underlying_assets",
"attributes": {
"entity_name": "my stock",
"entity_type": "SECURITY",
"base_currency": "USD",
"metric_values": {
"2025-01-01": 7.0,
"2025-01-02": null,
"2025-01-04": 8.0
}
}
}
}
Multiple entities:
{
"data": [
{
"id": "1234",
"type": "derivatives_underlying_assets",
"attributes": {
"entity_name": "stock patched",
"entity_type": "SECURITY",
"base_currency": "USD"
}
},
{
"id": "1235",
"type": "derivatives_underlying_assets",
"attributes": {
"entity_name": "bond patched",
"entity_type": "SECURITY",
"base_currency": "GBP"
}
}
]
}
Responses
200 OK: success
Single entity:
{
"data": [
{
"id": "1234",
"type": "derivatives_underlying_assets",
"attributes": {
"entity_name": "my stock",
"entity_type": "SECURITY",
"underlying_type": "PRICE",
"base_currency": "USD",
"metric_values": {
"2025-01-01": 7.0,
"2025-01-03": 6.0,
"2025-01-04": 8.0
}
},
"links": {
"self": "/v1/derivatives_underlying_assets/1234"
}
}
]
}
Multiple entities:
{
"data": [
{
"id": "1234",
"type": "derivatives_underlying_assets",
"attributes": {
"entity_name": "stock patched",
"entity_type": "SECURITY",
"underlying_type": "PRICE",
"base_currency": "USD"
},
"links": {
"self": "/v1/derivatives_underlying_assets/1234"
}
},
{
"id": "1235",
"type": "derivatives_underlying_assets",
"attributes": {
"entity_name": "bond patched",
"entity_type": "SECURITY",
"underlying_type": "PRICE",
"base_currency": "GBP"
},
"links": {
"self": "/v1/derivatives_underlying_assets/1235"
}
}
]
}
400 Bad Request: invalid payload403 Forbidden: not permitted to make the request404 Not Found: an entity with the given ID is not available to the requester
Delete underlying asset by ID
DELETE /v1/derivatives/underlying_assets/:id deletes an underlying asset by ID.
Responses
204 No Content: success403 Forbidden: not permitted to make the request404 Not Found: an entity with the given ID is not available to the requester
Delete underlying assets
DELETE /v1/derivatives/underlying_assets deletes multiple underlying assets by ID,
ignoring any that are not available to the requester
Requests
{
"data": [
{
"type": "derivatives_underlying_assets",
"id": "1234"
},
{
"type": "derivatives_underlying_assets",
"id": "1235"
}
]
}
Responses
204 No Content: success400 Bad Request: invalid payload403 Forbidden: not permitted to make the request
Updated 5 days ago