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"

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.

AccessLimitCalendars
No key60 calls/hour per IPFree set
Free key5,000 calls/monthFree set
Starter / Growth / Business100,000 / 1,000,000 / 5,000,000 calls/monthAll

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.

ParameterDescription
kindOptional: exchange, rail or country
curl -H "X-API-Key: $SETTLEDATE_KEY" \
  "https://www.elcodev.com/apps/settledate/v1/calendars?kind=exchange"
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.

ParameterDescription
dateDate 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"
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.

ParameterDescription
dateStart date
inclusivetrue 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"
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.

ParameterDescription
dateStart date
inclusivetrue 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"
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.

ParameterDescription
dateStart date
nInteger 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"
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.

ParameterDescription
fromStart date, inclusive
toEnd date, exclusive
inclusive_endtrue 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"
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.

ParameterDescription
year4-digit year
curl -H "X-API-Key: $SETTLEDATE_KEY" \
  "https://www.elcodev.com/apps/settledate/v1/calendars/XNYS/holidays?year=2026"
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.

ParameterDescription
dateDate
curl -H "X-API-Key: $SETTLEDATE_KEY" \
  "https://www.elcodev.com/apps/settledate/v1/markets/XNYS/session?date=2026-11-27"
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.

ParameterDescription
fromStart date
toEnd 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"
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.

ParameterDescription
atOptional 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"
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).

ParameterDescription
marketExchange MIC
trade_dateTrade date (must be a trading day)
cycleOptional override, e.g. T+1
calendarsOptional extra calendars to join, comma-separated
currency_calendarOptional 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"
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.

ParameterDescription
marketOptional MIC
curl -H "X-API-Key: $SETTLEDATE_KEY" \
  "https://www.elcodev.com/apps/settledate/v1/settlement-cycles?market=XLON"
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"
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.

MarketsCycleFrom trade dateStatusRule
XNYS XNAST+22017-09-05in effectSEC Rule 15c6-1 (T+2, 2017)
XNYS XNAST+12024-05-28in effectSEC Rule 15c6-1 amendments (T+1)
XTSET+22017-09-05in effectCSA NI 24-101 (T+2)
XTSET+12024-05-27in effectCSA NI 24-101 amendments (T+1)
XMEXT+22017-09-05in effectIndeval (T+2)
XMEXT+12024-05-27in effectMexican market move to T+1 (aligned with US/Canada)
XPAR XAMS XBRU XLIS XMIL XDUB XETR XMAD XHEL XWBO XSTO XCSET+12027-10-11confirmed in lawRegulation (EU) 2025/2075 amending CSDR Art. 5(2): T+1 applies from 11 Oct 2027
XOSLT+12027-10-11announced, not finalEU T+1 (Reg. 2025/2075) expected to apply in Norway via EEA incorporation; Norwegian implementation not yet final
XLONT+12027-10-11announced, not finalHM 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)
XSWXT+12027-10-11announced, not finalswissSPTC recommendation (acknowledged by SIF) for T+1 from 11 Oct 2027; SIX rule-book change pending
BVMFT+2—in effectB3 equities T+2
XJSET+3—in effectJSE equities T+3
XTKST+2—in effectJPX cash equities T+2 (since 16 Jul 2019)
XHKGT+2—in effectHKEX CCASS T+2
XSHGT+1—in effectSSE A-shares: securities T+0, cash T+1 (modelled as T+1)
XKRXT+2—in effectKRX equities T+2
XSEST+2—in effectSGX equities T+2
XBOMT+1—in effectSEBI T+1 rolling settlement (fully phased in 27 Jan 2023)
XASXT+2—in effectASX CHESS T+2
XNZET+2—in effectNZX T+2

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": "…"}}.

HTTPcodeMeaning
400bad_date, missing_param, bad_n, bad_cycle…Fix the request
401invalid_keyUnknown or revoked key
402plan_requiredThat calendar needs a paid plan
404unknown_calendar, unknown_endpointSee /v1/calendars
422out_of_range, not_a_trading_dayOutside 2020–2030 (or the calendar's data range), or trade date on a closed day (response includes next_trading_day)
429quota_exceeded, rate_limitedMonthly 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.