SettleDate API docs
Base URL https://www.elcodev.com/apps/settledate. Every endpoint is a GET that returns JSON. Dates are YYYY-MM-DD; instants are ISO-8601 UTC.
# No key needed for free calendars (60 calls/hour per IP)
curl "https://www.elcodev.com/apps/settledate/v1/calendars/XNYS/is-trading-day?date=2026-11-26"
import requests
print(requests.get("https://www.elcodev.com/apps/settledate/v1/markets/XLON/status").json())
console.log(await (await fetch("https://www.elcodev.com/apps/settledate/v1/calendars/US/holidays?year=2027")).json());
Keys and limits
Send your key in the X-API-Key header (or Authorization: Bearer sd_…). Get a free key on the home page. Keyed responses carry X-Usage-Limit and X-Usage-Remaining; keyless responses carry X-RateLimit-Limit and X-RateLimit-Remaining.
| Access | Limit | Calendars |
|---|---|---|
| No key | 60 calls/hour per IP | Free set |
| Free key | 5,000 calls/month | Free set |
| Starter / Growth / Business | 100,000 / 1,000,000 / 5,000,000 calls/month | All |
The free set is every country calendar plus XNYS, XNAS, XLON, XETR, XTKS, us-fed, eu-target2, gb-bacs-chaps. Listing endpoints (/v1/calendars, /v1/settlement-cycles, /v1/changes, /v1/usage) are not counted. Failed requests are not counted.
Calendar ids
Exchanges use ISO 10383 MICs: BVMF XAMS XASX XBOM XBRU XCSE XDUB XETR XHEL XHKG XJSE XKRX XLIS XLON XMAD XMEX XMIL XNAS XNYS XNZE XOSL XPAR XSES XSHG XSTO XSWX XTKS XTSE XWBO. Aliases such as NYSE, LSE, XETRA, JPX, HKEX also work.
Payment rails: eu-target2 (Eurosystem T2 / TARGET2 (EUR)), gb-bacs-chaps (UK BACS / CHAPS (England and Wales bank holidays)), us-fed (US Federal Reserve (Fedwire / FedACH)).
Countries use ISO 3166 codes (AE AR AT AU BE BR CA CH CL CN CO CZ …) and some subdivisions: GB-ENG, GB-SCT, GB-NIR, GB-WLS, US-NY, CA-ON, CA-QC, AU-NSW, AU-VIC.
Joint calendars: join up to 8 ids with commas (XNYS,XLON). A day is open only if every calendar is open, and closed responses say which calendar closed it.
Endpoints
GET /v1/calendars
List every calendar with time zone, data range and verification level.
| Parameter | Description |
|---|---|
kind | Optional: exchange, rail or country |
curl -H "X-API-Key: $SETTLEDATE_KEY" \
"https://www.elcodev.com/apps/settledate/v1/calendars?kind=exchange"
import os, requests
r = requests.get(
"https://www.elcodev.com/apps/settledate/v1/calendars",
params={"kind":"exchange"},
headers={"X-API-Key": os.environ["SETTLEDATE_KEY"]},
timeout=10,
)
r.raise_for_status()
print(r.json())
const res = await fetch("https://www.elcodev.com/apps/settledate/v1/calendars?kind=exchange", {
headers: { "X-API-Key": process.env.SETTLEDATE_KEY },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
Example response
{
"calendars": [
{
"id": "BVMF",
"kind": "exchange",
"name": "B3 (Brasil Bolsa Balcao)",
"country": "BR",
"currency": "BRL",
"timezone": "America/Sao_Paulo",
"data_through": "2030-12-31",
"verification": {
"level": "library-derived",
"checked_against_official": []
}
},
{
"id": "XAMS",
"kind": "exchange",
"name": "Euronext Amsterdam",
"country": "NL",
"currency": "EUR",
"timezone": "Europe/Amsterdam",
"data_through": "2030-12-31",
"verification": {
"level": "library-derived",
"checked_against_official": []
}
}
],
"…": "more"
}GET /v1/calendars/{id}/is-trading-day
Whether a date is a trading (business) day, and why not. Alias: is-business-day.
| Parameter | Description |
|---|---|
date | Date to check |
curl -H "X-API-Key: $SETTLEDATE_KEY" \
"https://www.elcodev.com/apps/settledate/v1/calendars/XNYS/is-trading-day?date=2026-12-25"
import os, requests
r = requests.get(
"https://www.elcodev.com/apps/settledate/v1/calendars/XNYS/is-trading-day",
params={"date":"2026-12-25"},
headers={"X-API-Key": os.environ["SETTLEDATE_KEY"]},
timeout=10,
)
r.raise_for_status()
print(r.json())
const res = await fetch("https://www.elcodev.com/apps/settledate/v1/calendars/XNYS/is-trading-day?date=2026-12-25", {
headers: { "X-API-Key": process.env.SETTLEDATE_KEY },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
Example response
{
"calendar": "XNYS",
"date": "2026-12-25",
"weekday": "Fri",
"is_business_day": false,
"closed_reasons": [
{
"calendar": "XNYS",
"type": "holiday",
"name": "Christmas"
}
]
}GET /v1/calendars/{id}/next-trading-day
The next trading day after date. Alias: next-business-day.
| Parameter | Description |
|---|---|
date | Start date |
inclusive | true returns date itself if it is open |
curl -H "X-API-Key: $SETTLEDATE_KEY" \
"https://www.elcodev.com/apps/settledate/v1/calendars/XNYS/next-trading-day?date=2026-12-24"
import os, requests
r = requests.get(
"https://www.elcodev.com/apps/settledate/v1/calendars/XNYS/next-trading-day",
params={"date":"2026-12-24"},
headers={"X-API-Key": os.environ["SETTLEDATE_KEY"]},
timeout=10,
)
r.raise_for_status()
print(r.json())
const res = await fetch("https://www.elcodev.com/apps/settledate/v1/calendars/XNYS/next-trading-day?date=2026-12-24", {
headers: { "X-API-Key": process.env.SETTLEDATE_KEY },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
Example response
{
"calendar": "XNYS",
"date": "2026-12-24",
"next_business_day": "2026-12-28",
"inclusive": false
}GET /v1/calendars/{id}/previous-trading-day
The trading day before date. Alias: previous-business-day.
| Parameter | Description |
|---|---|
date | Start date |
inclusive | true returns date itself if it is open |
curl -H "X-API-Key: $SETTLEDATE_KEY" \
"https://www.elcodev.com/apps/settledate/v1/calendars/XLON/previous-trading-day?date=2026-12-28"
import os, requests
r = requests.get(
"https://www.elcodev.com/apps/settledate/v1/calendars/XLON/previous-trading-day",
params={"date":"2026-12-28"},
headers={"X-API-Key": os.environ["SETTLEDATE_KEY"]},
timeout=10,
)
r.raise_for_status()
print(r.json())
const res = await fetch("https://www.elcodev.com/apps/settledate/v1/calendars/XLON/previous-trading-day?date=2026-12-28", {
headers: { "X-API-Key": process.env.SETTLEDATE_KEY },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
Example response
{
"calendar": "XLON",
"date": "2026-12-28",
"previous_business_day": "2026-12-24",
"inclusive": false
}GET /v1/calendars/{id}/add-trading-days
Move a date by N trading days; negative N goes back. Alias: add-business-days.
| Parameter | Description |
|---|---|
date | Start date |
n | Integer between -2000 and 2000 |
curl -H "X-API-Key: $SETTLEDATE_KEY" \
"https://www.elcodev.com/apps/settledate/v1/calendars/XETR/add-trading-days?date=2026-04-02&n=2"
import os, requests
r = requests.get(
"https://www.elcodev.com/apps/settledate/v1/calendars/XETR/add-trading-days",
params={"date":"2026-04-02","n":"2"},
headers={"X-API-Key": os.environ["SETTLEDATE_KEY"]},
timeout=10,
)
r.raise_for_status()
print(r.json())
const res = await fetch("https://www.elcodev.com/apps/settledate/v1/calendars/XETR/add-trading-days?date=2026-04-02&n=2", {
headers: { "X-API-Key": process.env.SETTLEDATE_KEY },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
Example response
{
"calendar": "XETR",
"date": "2026-04-02",
"n": 2,
"result": "2026-04-08"
}GET /v1/calendars/{id}/trading-days-between
Count trading days from from (inclusive) to to (exclusive). Negative when to is earlier. Alias: business-days-between.
| Parameter | Description |
|---|---|
from | Start date, inclusive |
to | End date, exclusive |
inclusive_end | true counts to as well |
curl -H "X-API-Key: $SETTLEDATE_KEY" \
"https://www.elcodev.com/apps/settledate/v1/calendars/XNYS,us-fed/trading-days-between?from=2026-10-01&to=2026-11-01"
import os, requests
r = requests.get(
"https://www.elcodev.com/apps/settledate/v1/calendars/XNYS,us-fed/trading-days-between",
params={"from":"2026-10-01","to":"2026-11-01"},
headers={"X-API-Key": os.environ["SETTLEDATE_KEY"]},
timeout=10,
)
r.raise_for_status()
print(r.json())
const res = await fetch("https://www.elcodev.com/apps/settledate/v1/calendars/XNYS,us-fed/trading-days-between?from=2026-10-01&to=2026-11-01", {
headers: { "X-API-Key": process.env.SETTLEDATE_KEY },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
Example response
{
"calendars": [
"XNYS",
"us-fed"
],
"…": "more"
}GET /v1/calendars/{id}/holidays
Holidays in a year. Exchange calendars also list early closes and late opens with local times.
| Parameter | Description |
|---|---|
year | 4-digit year |
curl -H "X-API-Key: $SETTLEDATE_KEY" \
"https://www.elcodev.com/apps/settledate/v1/calendars/XNYS/holidays?year=2026"
import os, requests
r = requests.get(
"https://www.elcodev.com/apps/settledate/v1/calendars/XNYS/holidays",
params={"year":"2026"},
headers={"X-API-Key": os.environ["SETTLEDATE_KEY"]},
timeout=10,
)
r.raise_for_status()
print(r.json())
const res = await fetch("https://www.elcodev.com/apps/settledate/v1/calendars/XNYS/holidays?year=2026", {
headers: { "X-API-Key": process.env.SETTLEDATE_KEY },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
Example response
{
"calendar": "XNYS",
"year": 2026,
"holidays": [
{
"date": "2026-01-01",
"name": "New Year's Day",
"weekday": "Thu"
},
{
"date": "2026-01-19",
"name": "Dr. Martin Luther King Jr. Day",
"weekday": "Mon"
},
{
"date": "2026-02-16",
"name": "President's Day",
"weekday": "Mon"
},
{
"…": "more"
}
],
"early_closes": [
{
"date": "2026-11-27",
"close_local": "13:00",
"weekday": "Fri"
},
{
"date": "2026-12-24",
"close_local": "13:00",
"weekday": "Thu"
}
],
"late_opens": []
}GET /v1/markets/{mic}/session
Session on a date: open/close (and lunch break) in local time and UTC, and the session type: regular, early_close, late_open or special.
| Parameter | Description |
|---|---|
date | Date |
curl -H "X-API-Key: $SETTLEDATE_KEY" \
"https://www.elcodev.com/apps/settledate/v1/markets/XNYS/session?date=2026-11-27"
import os, requests
r = requests.get(
"https://www.elcodev.com/apps/settledate/v1/markets/XNYS/session",
params={"date":"2026-11-27"},
headers={"X-API-Key": os.environ["SETTLEDATE_KEY"]},
timeout=10,
)
r.raise_for_status()
print(r.json())
const res = await fetch("https://www.elcodev.com/apps/settledate/v1/markets/XNYS/session?date=2026-11-27", {
headers: { "X-API-Key": process.env.SETTLEDATE_KEY },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
Example response
{
"market": "XNYS",
"date": "2026-11-27",
"open": true,
"session_type": "early_close",
"timezone": "America/New_York",
"local": {
"open": "09:30",
"close": "13:00"
},
"utc": {
"open": "2026-11-27T14:30:00Z",
"close": "2026-11-27T18:00:00Z"
},
"regular_close_local": "16:00",
"utc_offset": "-05:00"
}GET /v1/markets/{mic}/sessions
Every session in a range, up to 400 days.
| Parameter | Description |
|---|---|
from | Start date |
to | End date, inclusive |
curl -H "X-API-Key: $SETTLEDATE_KEY" \
"https://www.elcodev.com/apps/settledate/v1/markets/XTKS/sessions?from=2026-03-02&to=2026-03-06"
import os, requests
r = requests.get(
"https://www.elcodev.com/apps/settledate/v1/markets/XTKS/sessions",
params={"from":"2026-03-02","to":"2026-03-06"},
headers={"X-API-Key": os.environ["SETTLEDATE_KEY"]},
timeout=10,
)
r.raise_for_status()
print(r.json())
const res = await fetch("https://www.elcodev.com/apps/settledate/v1/markets/XTKS/sessions?from=2026-03-02&to=2026-03-06", {
headers: { "X-API-Key": process.env.SETTLEDATE_KEY },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
Example response
{
"market": "XTKS",
"from": "2026-03-02",
"to": "2026-03-06",
"sessions": [
{
"market": "XTKS",
"date": "2026-03-02",
"open": true,
"session_type": "regular",
"timezone": "Asia/Tokyo",
"local": {
"open": "09:00",
"close": "15:30",
"break_start": "11:30",
"break_end": "12:30"
},
"utc": {
"open": "2026-03-02T00:00:00Z",
"close": "2026-03-02T06:30:00Z",
"break_start": "2026-03-02T02:30:00Z",
"break_end": "2026-03-02T03:30:00Z"
},
"utc_offset": "+09:00"
},
{
"…": "more"
}
]
}GET /v1/markets/{mic}/status
Open, closed or lunch break at an instant, with next open and close.
| Parameter | Description |
|---|---|
at | Optional ISO-8601 instant; defaults to now |
curl -H "X-API-Key: $SETTLEDATE_KEY" \
"https://www.elcodev.com/apps/settledate/v1/markets/XHKG/status?at=2026-10-26T04:30:00Z"
import os, requests
r = requests.get(
"https://www.elcodev.com/apps/settledate/v1/markets/XHKG/status",
params={"at":"2026-10-26T04:30:00Z"},
headers={"X-API-Key": os.environ["SETTLEDATE_KEY"]},
timeout=10,
)
r.raise_for_status()
print(r.json())
const res = await fetch("https://www.elcodev.com/apps/settledate/v1/markets/XHKG/status?at=2026-10-26T04:30:00Z", {
headers: { "X-API-Key": process.env.SETTLEDATE_KEY },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
Example response
{
"market": "XHKG",
"at": "2026-10-26T04:30:00Z",
"local_date": "2026-10-26",
"local_time": "12:30",
"timezone": "Asia/Hong_Kong",
"status": "break",
"is_open": false,
"session": {
"market": "XHKG",
"date": "2026-10-26",
"open": true,
"session_type": "regular",
"timezone": "Asia/Hong_Kong",
"local": {
"open": "09:30",
"close": "16:00",
"break_start": "12:00",
"break_end": "13:00"
},
"utc": {
"open": "2026-10-26T01:30:00Z",
"close": "2026-10-26T08:00:00Z",
"break_start": "2026-10-26T04:00:00Z",
"break_end": "2026-10-26T05:00:00Z"
},
"utc_offset": "+08:00"
},
"next_open": "2026-10-26T05:00:00Z",
"next_close": "2026-10-26T08:00:00Z"
}GET /v1/settlement-date
Settlement date for a trade. The cycle comes from the market's rule for that trade date unless you pass one. Days are counted on the market calendar joined with the settlement-currency calendar (USD → us-fed, EUR → eu-target2, GBP → gb-bacs-chaps).
| Parameter | Description |
|---|---|
market | Exchange MIC |
trade_date | Trade date (must be a trading day) |
cycle | Optional override, e.g. T+1 |
calendars | Optional extra calendars to join, comma-separated |
currency_calendar | Optional override of the cash-leg calendar, or none |
curl -H "X-API-Key: $SETTLEDATE_KEY" \
"https://www.elcodev.com/apps/settledate/v1/settlement-date?market=XETR&trade_date=2027-10-08"
import os, requests
r = requests.get(
"https://www.elcodev.com/apps/settledate/v1/settlement-date",
params={"market":"XETR","trade_date":"2027-10-08"},
headers={"X-API-Key": os.environ["SETTLEDATE_KEY"]},
timeout=10,
)
r.raise_for_status()
print(r.json())
const res = await fetch("https://www.elcodev.com/apps/settledate/v1/settlement-date?market=XETR&trade_date=2027-10-08", {
headers: { "X-API-Key": process.env.SETTLEDATE_KEY },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
Example response
{
"market": "XETR",
"trade_date": "2027-10-08",
"settlement_date": "2027-10-12",
"cycle": "T+2",
"basis": "market_rule",
"status": "in_effect",
"effective_from": "2014-10-06",
"rule": "CSDR Art. 5(2) (T+2)",
"source": "https://eur-lex.europa.eu/eli/reg/2014/909/oj",
"calendars_used": [
"XETR",
"eu-target2"
],
"skipped_days": [],
"upcoming_change": {
"cycle": "T+1",
"effective_from": "2027-10-11",
"status": "confirmed",
"rule": "Regulation (EU) 2025/2075 amending CSDR Art. 5(2): T+1 applies from 11 Oct 2027",
"source": "https://eur-lex.europa.eu/eli/reg/2025/2075/oj"
}
}GET /v1/settlement-cycles
Settlement cycle rules by market with status and source.
| Parameter | Description |
|---|---|
market | Optional MIC |
curl -H "X-API-Key: $SETTLEDATE_KEY" \
"https://www.elcodev.com/apps/settledate/v1/settlement-cycles?market=XLON"
import os, requests
r = requests.get(
"https://www.elcodev.com/apps/settledate/v1/settlement-cycles",
params={"market":"XLON"},
headers={"X-API-Key": os.environ["SETTLEDATE_KEY"]},
timeout=10,
)
r.raise_for_status()
print(r.json())
const res = await fetch("https://www.elcodev.com/apps/settledate/v1/settlement-cycles?market=XLON", {
headers: { "X-API-Key": process.env.SETTLEDATE_KEY },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
Example response
{
"settlement_cycles": {
"XLON": [
{
"from": "2014-10-06",
"days": 2,
"status": "in_effect",
"label": "UK CSDR Art. 5(2) (T+2)",
"source": "https://www.legislation.gov.uk/eur/2014/909/article/5"
},
{
"from": "2027-10-11",
"days": 1,
"status": "announced_not_final",
"label": "HM Treasury: UK T+1 from 11 Oct 2027; draft Central Securities Depositories (Amendment) (Intended Settlement Date) Regulations 2026 published Nov 2025, not yet made (checked 2026-10-24)",
"source": "https://www.gov.uk/government/publications/accelerated-settlement-t1"
}
]
},
"note": "status: in_effect | confirmed (in law, future) | announced_not_final (announced or recommended; legal instrument not final)."
}GET /v1/usage
Your plan and calls used this month. Requires a key.
curl -H "X-API-Key: $SETTLEDATE_KEY" \
"https://www.elcodev.com/apps/settledate/v1/usage"
import os, requests
r = requests.get(
"https://www.elcodev.com/apps/settledate/v1/usage",
params={},
headers={"X-API-Key": os.environ["SETTLEDATE_KEY"]},
timeout=10,
)
r.raise_for_status()
print(r.json())
const res = await fetch("https://www.elcodev.com/apps/settledate/v1/usage", {
headers: { "X-API-Key": process.env.SETTLEDATE_KEY },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
Example response
{
"plan": "free",
"month": "202610",
"calls_used": 42,
"monthly_limit": 5000,
"note": "Counts can lag by a few minutes."
}GET /v1/changes
The corrections log: every hand override applied on top of the library data, with its official source.
Settlement rules
Status values: in effect the rule applies today; confirmed in law a future change written into law or regulation; announced, not final a future change announced or recommended whose legal instrument isn't final. Responses for trades before a pending change include upcoming_change.
Settlement dates are reference calculations for standard cash-equity trades. Your CSD, custodian or counterparty may apply different conventions (e.g. securities financing, primary market, cross-border links).
Errors
Errors are JSON: {"error": {"code": "…", "message": "…"}}.
| HTTP | code | Meaning |
|---|---|---|
| 400 | bad_date, missing_param, bad_n, bad_cycle… | Fix the request |
| 401 | invalid_key | Unknown or revoked key |
| 402 | plan_required | That calendar needs a paid plan |
| 404 | unknown_calendar, unknown_endpoint | See /v1/calendars |
| 422 | out_of_range, not_a_trading_day | Outside 2020–2030 (or the calendar's data range), or trade date on a closed day (response includes next_trading_day) |
| 429 | quota_exceeded, rate_limited | Monthly quota or keyless hourly limit reached |
OpenAPI, llms.txt and AI agents
Machine-readable spec: https://www.elcodev.com/apps/settledate/openapi.json (OpenAPI 3.1). Plain-text summary for LLMs: https://www.elcodev.com/apps/settledate/llms.txt. Agents can call the keyless endpoints directly for the free calendars.