OpenAPI

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 NamePathReturned Schema

Currency Breakdown: Owed by Currency and Amount Type

/hist/v1/unsettledamounts
  • CurrencyRoot
    • CurrencyBreakdown
      • AmountTypeBreakdown

Currency Breakdown: Owed by Instrument

/hist/v1/unsettledamounts/instruments
  • InstrumentBreakdown

Exchange Breakdown: Owed by Exchange and Currency

/hist/v1/unsettledamounts/exchanges

  • ExchangeRoot
    • ExchangeBreakdown
      • CurrencyBreakdown

Exchange Breakdown: Owed by Currency and Amount Type

/hist/v1/unsettledamounts/exchanges/{ExchangeId}
  • ExchangeBreakdown
    • CurrencyBreakdown
      • AmountTypeBreakdown

(info) See our sample code and live demo on GitHub!

Structures

With the various granularity option, it is worthwhile to understand the common underlying structures, and which each endpoint can access.


SchemaDescriptionAvailable 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
ExchangeRootAggregates 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
ExchangeBreakdownContains 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}

CurrencyBreakdownContains 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}

AmountTypeBreakdownAmountType 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}

InstrumentBreakdownInstrument 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 AttributesDescription
CashFlowA 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:

  • "TransactionsNotBooked": Describing intraday trades, before they are booked.
  • "Financing": Describes amounts that may accrue over time, such as subscriptions, fees, or cash withdrawals.
  • "CorporateAction": Describes amounts derived from the corporate actions that are known to occur in the future.

Scope

A request query parameter, used to access either currency or amount type granularity levels from the /unsettledamounts endpoint. Possible values are:

  • Currencies
  • AmountTypes

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:


Example Unsettled Amounts, by Exchange request
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.


Example Exchange Detail request
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:


Example Amount Types for Exchange 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.