NOTE: This is a BETA version. It is currently only made available to select partners.
The Unsettled Amounts Resource provides endpoints to monitor future cash flow, by providing a detailed view of the amounts owed by (or to) the requested entity. Positive amounts indicate amounts to be paid to the requesting entity, negative amounts indicate amounts to be paid by the entity.
It is useful to be familiar with the Owner Hierarchy, before using this resource, as this resource's endpoints include all the aggregate totals due for all children clients and accounts.
The structure, and granularity of each endpoint's response varies, to support various use cases.
Endpoints
| Endpoint Name | Path | Returned Schema |
|---|---|---|
Currency Breakdown: Owed by Currency and Amount Type | /hist/v1/unsettledamounts |
|
Currency Breakdown: Owed by Instrument | /hist/v1/unsettledamounts/instruments |
|
Exchange Breakdown: Owed by Exchange and Currency | /hist/v1/unsettledamounts/exchanges |
|
Exchange Breakdown: Owed by Currency and Amount Type | /hist/v1/unsettledamounts/exchanges/{ExchangeId} |
|
Structures
With the various granularity option, it is worthwhile to understand the common underlying structures, and which each endpoint can access.
| Schema | Description | Available within the response structures of the endpoint(s) |
|---|---|---|
CurrencyRoot | Aggregates in the requesting entity's currency, providing an array of CashFlow to show date specific amounts due. Has a child array, Currencies, consisting of an array of CurrencyBreakdown objects. | /unsettledamounts |
| ExchangeRoot | Aggregates in the requesting entity's currency, providing an array of CashFlow to show date specific amounts due. Has a child array, Exchanges, consisting of an array of ExchangeBreakdown objects. | /unsettledamounts/exchanges |
| ExchangeBreakdown | Contains the requesting entity's currency, providing an ExchangeId, Total, and array of CashFlow to show date specific amounts due to the specific Exchange. It also has a child array, Currencies, consisting of an array of CurrencyBreakdown objects. | /unsettledamounts/exchanges /unsettledamounts/exchanges/{ExchangeId} |
| CurrencyBreakdown | Contains the owed currency, a Total aggregate in that currency, and an array of CashFlow to show date specific amounts due for this currency. Can have a child array, AmountTypesBreakdown in select endpoints. | /unsettledamounts /unsettledamounts/exchanges /unsettledamounts/exchanges/{ExchangeId} |
| AmountTypeBreakdown | AmountType objects, containing an Amount Type, a Total aggregate in the owed currency, and an array of CashFlow to show date specific amounts due for this amount type. | /unsettledamounts /unsettledamounts/exchanges/{ExchangeId} |
| InstrumentBreakdown | Instrument object with instrument details, a Total aggregate in the owed currency and an array of CashFlow to show date specific amounts due for this instrument. | /unsettledamounts/instruments |
Diagram showing the above schemas, and their relation to Unsettled Amounts Endpoints
| Noteworthy Attributes | Description |
|---|---|
| CashFlow | A simple object containing an Amount and ValueDate attribute. The amount's currency is inherited from the nearest parent currency. |
| AmountTypeSource | An enumerator denoting the source of each amount type, also usable in some endpoints as a request filter(as an array of values). Possible values are:
|
Scope | A request query parameter, used to access either currency or amount type granularity levels from the /unsettledamounts endpoint. Possible values are:
|
Example Scenario and Response
As a White Label Client (WLC) or Introducing Broker (IB) consumer of this endpoint, I have underlying clients for whom I have settlement responsibility. I want to know the value dated amounts that we owe, or are owed to us, with the finest available precision, so that I can acquire the owed amounts in their respective currency in good time.
Request Currency Breakdown by Exchange
Using my WLC Client Key, make a request to see which exchanges money is owed to, and in what currencies:
GET /hist/v1/unsettledamounts/exchanges?ClientKey={ClientKey}
We receive the response:
200 OK
{
"Total": -3.18174235,
"Currency": "DKK",
"CashFlows": [
{
"Amount": -0.28,
"ValueDate": "2022-05-31"
},
{
"Amount": -2.90174235,
"ValueDate": "2022-06-01"
}
],
"Exchanges": [
{
"Currency": "DKK",
"ExchangeId": "NoExchange",
"Total": -2.90174235,
"CashFlows": [
{
"Amount": -2.90174235,
"ValueDate": "2022-06-01"
}
],
"Currencies": [
{
"CashFlows": [
{
"Amount": -0.39,
"ValueDate": "2022-06-01"
}
],
"Currency": "EUR",
"Total": -0.39
}
]
},
{
"Currency": "DKK",
"ExchangeId": "NYSE",
"Total": -0.28,
"CashFlows": [
{
"Amount": -0.28,
"ValueDate": "2022-05-31"
}
],
"Currencies": [
{
"CashFlows": [
{
"Amount": -0.28,
"ValueDate": "2022-05-31"
}
],
"Currency": "DKK",
"Total": -0.28
}
],
}
]
}
Access details on exchange
If you want specific information for the ExchangeId NYSE, you can query the Reference Data Service Group. Note that the "NoExchange" value cannot be looked up, and is provided in order to show amounts that are not related to an exchange.
GET /ref/v1/exchanges/{ExchangeId}
We recieve the response:
200 OK
{
"AllDay": false,
"CountryCode": "US",
"Currency": "USD",
"ExchangeId": "NYSE",
"ExchangeSessions": [
{
"EndTime": "2022-05-03T11:00:00.000000Z",
"StartTime": "2022-05-02T20:00:00.000000Z",
"State": "Closed"
},
{
"EndTime": "2022-05-03T13:30:00.000000Z",
"StartTime": "2022-05-03T11:00:00.000000Z",
"State": "PreTrading"
},
{
"EndTime": "2022-05-03T20:00:00.000000Z",
"StartTime": "2022-05-03T13:30:00.000000Z",
"State": "AutomatedTrading"
},
{
"EndTime": "2022-05-04T11:00:00.000000Z",
"StartTime": "2022-05-03T20:00:00.000000Z",
"State": "Closed"
},
{
"EndTime": "2022-05-04T13:30:00.000000Z",
"StartTime": "2022-05-04T11:00:00.000000Z",
"State": "PreTrading"
},
{
"EndTime": "2022-05-04T20:00:00.000000Z",
"StartTime": "2022-05-04T13:30:00.000000Z",
"State": "AutomatedTrading"
},
{
"EndTime": "2022-05-05T11:00:00.000000Z",
"StartTime": "2022-05-04T20:00:00.000000Z",
"State": "Closed"
}
],
"Mic": "XNYS",
"Name": "New York Stock Exchange",
"PriceSourceName": "NYSE",
"TimeZone": 3,
"TimeZoneAbbreviation": "EDT",
"TimeZoneOffset": "-04:00:00"
}
Request Amount Type owed Breakdown for an Exchange
To access a more detailed breakdown of the amounts owed to a specific exchange, I can specify the provided ExchangeId in the path, and make another request:
GET /hist/v1/unsettledamounts/exchanges/{ExchangeId}?ClientKey={ClientKey}
GET https://gateway.saxobank.com/openapi/unsettledamounts/exchanges/NYSE
GET https://gateway.saxobank.com/openapi/unsettledamounts/exchanges/NoExchange
Making this request for both Exchanges, we receive the response:
200 OK
{
"Currency": "DKK",
"ExchangeId": "NYSE",
"Total": -0.28,
"CashFlows": [
{
"Amount": -0.28,
"ValueDate": "2022-05-31"
}
],
"Currencies": [
{
"Currency": "DKK",
"Total": -0.28,
"AmountTypes": [
{
"AmountType": "Unrealized CFD Finance",
"AmountTypeId": "65",
"AmountTypeSource": "Financing",
"CashFlows": [
{
"Amount": -0.28,
"ValueDate": "2022-05-31"
}
],
"Total": -0.28
}
],
"CashFlows": [
{
"Amount": -0.28,
"ValueDate": "2022-05-31"
}
]
}
]
}
200 OK
{
"Currency": "DKK",
"ExchangeId": "NoExchange",
"Total": -2.90174235,
"CashFlows": [
{
"Amount": -2.90174235,
"ValueDate": "2022-06-01"
}
],
"Currencies": [
{
"Currency": "EUR",
"Total": -0.39,
"AmountTypes": [
{
"AmountType": "Unr. Interest",
"AmountTypeId": "42",
"AmountTypeSource": "Financing",
"CashFlows": [
{
"Amount": -0.39,
"ValueDate": "2022-06-01"
}
],
"Total": -0.39
}
],
"CashFlows": [
{
"Amount": -0.39,
"ValueDate": "2022-06-01"
}
]
}
]
}
The additional endpoints behave similarly–but provide access to different granularity data, sometimes requiring additional query parameters. See the reference docs for more details.