FinCal API - /settlement

Description

Calculates a T+N settlement date (e.g., T+2 or T+3) from a given base date, considering weekends and holidays specific to a financial calendar. This is fundamental for post-trade processing and accurate deal settlement.

🌐 Browser

Paste the URL directly into your browser to see the JSON output:

https://fincalapi.com/v1/settlement_date?date=2025-05-01&calendar=SIFMA-US&tplus=2

Endpoint

GET https://fincalapi.com/v1/settlement_date

Parameters

Name	Type	Required	Description
`date`	string	✅ Yes	Base date in `YYYY-MM-DD` format (e.g., `2025-05-01`).
`calendar`	string	✅ Yes	Holiday calendar name, e.g., `SIFMA-US`, `NYSE`, `NASDAQ`, `SIFMA-UK`, `SIFMA-JP`.
`tplus`	integer	✅ Yes	The 'N' in T+N (number of business days to add). Can be negative for T-N.
`format`	string	No (Default: `json`)	Response format: `json`, `text`, `plain`, `html`, `csv`.

Usage Examples

🐍 Python

Get the T+3 settlement date for a Japanese holiday using Python:

import requests
import json

base_url = "https://fincalapi.com/v1/settlement_date"
params = {
    "date": "2025-01-01",
    "calendar": "SIFMA-JP", # New Year's Day, a holiday in Japan
    "tplus": 3
}

response = requests.get(base_url, params=params)

if response.status_code == 200:
    settlement_info = response.json()
    print(json.dumps(settlement_info, indent=2))
    # Example output:
    # {
    #   "input_date": "2025-01-01",
    #   "calendar": "SIFMA-JP",
    #   "n_offset": 3,
    #   "settlement_date": "2025-01-08" # T+3 from Jan 1, considering holidays and weekends
    # }
else:
    print(f"Error: {response.status_code} - {response.text}")

💻 VBA Macro

Automate T+N settlement date calculations in VBA (sends API key via Authorization header):

Function GetSettlementDate(baseDate As String, calendarName As String, tPlusOffset As Integer) As String
    Dim http As Object
    Set http = CreateObject("MSXML2.XMLHTTP")
    Dim url As String
    url = "https://fincalapi.com/v1/settlement_date?date=" & baseDate & "&calendar=" & calendarName & "&tplus=" & tPlusOffset
    http.Open "GET", url, False
    http.setRequestHeader "Authorization", "Bearer fincal_live_YOUR_KEY_HERE"
    http.Send
    GetSettlementDate = http.responseText ' Returns JSON string
End Function

' Example: MsgBox GetSettlementDate("2025-07-03", "SIFMA-US", 2)

🧮 Excel Formula (WEBSERVICE)

Calculate the T+2 settlement date for a date in cell A2 using the SIFMA-US calendar. Pass your API key as the api_key query parameter:

=WEBSERVICE("https://fincalapi.com/v1/settlement_date?date="&TEXT(A2,"YYYY-MM-DD")&"&calendar=SIFMA-US&tplus=2&api_key=fincal_live_YOUR_KEY_HERE")

Security note: The api_key parameter works but your key will appear in server access logs and Excel's formula bar. For better security, use the VBA macro above or Power Query, which support the Authorization header instead.

🔌 Excel Power Query (recommended)

Excel 2016+ supports custom HTTP headers in Power Query, keeping your key out of the URL:

let
    ApiKey = "fincal_live_YOUR_KEY_HERE",
    Source = Web.Contents(
        "https://fincalapi.com/v1/settlement_date?date=2025-07-03&calendar=SIFMA-US&tplus=2",
        [Headers = [Authorization = "Bearer " & ApiKey]]
    ),
    Result = Json.Document(Source)
in
    Result

In Excel: Data → Get Data → From Other Sources → From Web → Advanced → add Authorization header.

📊 Google Sheets

Calculate T+2 settlement date. Pass your API key as a query parameter:

=IMPORTDATA("https://fincalapi.com/v1/settlement_date?date=2025-07-03&calendar=SIFMA-US&tplus=2&api_key=fincal_live_YOUR_KEY_HERE")

🖥️ cURL / Terminal

Calculate T+2 for a specific date and calendar:

curl -H "Authorization: Bearer fincal_live_YOUR_KEY_HERE" \
  "https://fincalapi.com/v1/settlement_date?date=2025-05-01&calendar=SIFMA-US&tplus=2"