Answers

Settlement/value date: T+n business days across intersected national statutory calendars, with the cited market cycle

Date n business days after a trade date across the given national statutory calendars (not CSD/venue), with a per-day trail and cited convention. Unsupported cases are refused free before payment. Cycles: GET /settlement-conventions (free).

post/v1/answers/settlement-date

Request

  • Base URL: https://afriref.dev
  • URL: https://afriref.dev/v1/answers/settlement-date
  • Auth: one of:
    • API key in header PAYMENT-SIGNATURE
    • API key in header X-PAYMENT
    • API key in header X-API-Key

Headers

X-Free-Trial'1'

Opt in to the free trial (3 calls/day/IP).

Request body

trade_datestring date required

Trade/reference date. Day 0: never counted toward n, never rolled forward.

calendarsstring[] required

Calendar ids to intersect: ISO 3166-1 alpha-2 country codes plus 'eu.t2' for the euro cash leg (TARGET2). The settlement date must be a business day on every calendar named. Bare 'eu' is refused as ambiguous.

business_daysinteger

The offset you are trading under. Supply this, or market + instrument_class to have a cited cycle applied. If both are given and they differ, yours is used and the cited cycle is shown beside it.

marketstring

ISO 3166-1 alpha-2 country of the market whose settlement cycle applies (with instrument_class)

instrument_class'cash_equity' | 'etf' | 'corporate_bond' | 'government_bond' | 'tbill' | 'repo' | 'primary_issuance' | 'other'

Instrument class. A government bond never inherits an equity cycle.

receiptboolean

Optional. Default false. When true, a paid HTTP 200 embeds an Ed25519-signed receipt (kind answer_receipt) the caller can file and later verify at /certified/public-key. Included in this answer's existing price — no extra charge. The field is omitted on unpaid 402 and on free 4xx refusals. This is not a series certified extract: GET /v1/certified/{country}/{series} is a different artifact, with its own price.

Response

Settlement date, per-day trail, convention applied with citations, each calendar's basis/coverage/source, caveats. Optional property receipt (schema AnswerReceipt, kind answer_receipt) is present only when the request set receipt:true and this response is a paid HTTP 200. Unpaid 402 and free 4xx refusals do not include receipt. Not a series certified extract (GET /v1/certified/{country}/{series}).

status'ok' required
confidence_label'high' | 'medium' | 'low'

Derived from source type, verification age, stale. Rules: /label-rules

coverage_label'ready' | 'partial' | 'gap'

ready=complete, partial=limited, gap=no number. Rules: /label-rules

label_basisobject

Inputs and rule ids behind both labels

settlement_datestring date required
settlement_weekdaystring
questionobject required

The question as understood: trade date and weekday, business-day count applied, calendars intersected, market/instrument when supplied

convention_appliedobject required

The T+n actually used and where it came from: 'cited_convention' (with the instrument, authority and whether it is compelled by law) or 'caller_supplied'. When both were given and differ, the cited cycle is shown beside the caller's.

trailobject[]

Per-day walk from trade date to settlement: each candidate day, whether it counted, and - when skipped - which calendar blocked it and why (weekend rule or a named public holiday)

calendarsobject[]

Each calendar's basis (national statutory - NOT a CSD or venue calendar), weekend rule, covered period and official source, plus any known divergence worth flagging

caveatsstring[]

Always worth reading: the specific limits of this answer

Example response

{
  "receipt": {
    "kind": "answer_receipt",
    "receipt_id": "0123456789abcdef01234567",
    "answer": "vat",
    "request": {
      "country": "za",
      "amount": 100,
      "mode": "add",
      "receipt": true
    },
    "result": {
      "status": "ok"
    },
    "cited_series": [
      {
        "country": "za",
        "series_id": "vat",
        "value": null,
        "last_confirmed": "2026-04-01",
        "source_url": null,
        "source_sha256": null
      }
    ],
    "issued_at": "2026-09-25T15:45:00.000Z",
    "limitations": [
      "This receipt is not a series certified extract (GET /v1/certified/{country}/{series}).",
      "This receipt is not legal advice. It only covers the computation over the cited series as of each series' last_confirmed."
    ],
    "signature": {
      "alg": "Ed25519",
      "key_id": "<same key_id as /certified/public-key>",
      "public_key": "https://example.invalid/certified/public-key",
      "signed_payload": "canonical JSON of answer_receipt: keys sorted recursively, no whitespace (see /certified/public-key)",
      "value": "<base64>"
    }
  }
}

Changes

No recorded changes to this operation across all 3 revisions of this API.