--- title: "Settlement/value date: T+n business days across intersected national statutory calendars, with the cited market cycle" method: POST path: "/v1/answers/settlement-date" tags: ["Answers"] --- # Settlement/value date: T+n business days across intersected national statutory calendars, with the cited market cycle `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` 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). ## Headers - `X-Free-Trial` '1' ## Request body - object - `trade_date` string, date, required: Trade/reference date. Day 0: never counted toward n, never rolled forward. - `calendars` string[], 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_days` integer: 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. - `market` string: 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. - `receipt` boolean: 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 `200` 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}). - object: The settlement-date computation with its full evidence trail. Nothing here is asserted without a stated basis: the convention says whether it was cited from an instrument or supplied by the caller, and every skipped day names the calendar and reason that skipped it. - `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_basis` object: Inputs and rule ids behind both labels - `settlement_date` string, date, required - `settlement_weekday` string - `question` object, required: The question as understood: trade date and weekday, business-day count applied, calendars intersected, market/instrument when supplied - `convention_applied` object, 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. - `trail` object[]: 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) - `calendars` object[]: 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 - `caveats` string[]: Always worth reading: the specific limits of this answer - `receipt` AnswerReceipt: Signed record of one paid answer computation. Present only on HTTP 200 when the request body set receipt:true. kind is answer_receipt. This object is not a series certified extract: GET /v1/certified/{country}/{series} returns a different artifact (value, citation, archived-source fingerprint, verification chain) at its own price. An answer receipt is included in the answer's existing price — no extra charge. It is not legal advice. It only covers the computation over the cited series as of each series' last_confirmed. Signing: build the object without signature, set receipt_id from the sha256 of that canonical JSON (first 24 hex chars, same pattern as extract_id), re-canonicalize including receipt_id, then sign. Verify with the free key at /certified/public-key — the same key and the same canonicalization rule as series certified extracts, not a second key. - `kind` 'answer_receipt', required - `receipt_id` string, required: First 24 hex characters of sha256 over the canonical JSON of this object before signature is attached. Same pattern as certified extract_id. The signature covers the object including receipt_id. - `answer` string, required: Route or tool name of the paid answer, e.g. vat, wage-check, working-days, settlement-date, income-tax, statutory-interest, payroll, employment-cost. - `request` object, required: Sanitized inputs echoed from the request. Properties are route-specific. - `result` object, required: Compact summary of the answer status and workings already returned on this 200. Properties are route-specific. - `cited_series` object[], required: Series the computation cited. Empty only when the answer cited none. - `country` string, required - `series_id` string, required - `value` union, required: Cited series value as held. Number, string, or null. - number - string - `last_confirmed` string, date, nullable, required: ISO date the cited series was last confirmed, or null. - `source_url` string, nullable, required - `source_sha256` string, nullable, required: Hex fingerprint from provenance when available, otherwise null. - `issued_at` string, date-time, required: ISO8601 timestamp when the receipt was issued. - `limitations` string[], required: Always populated. States that this receipt is not a series certified extract and is not legal advice, and that it only covers the computation over the cited series as of each series' last_confirmed. - `signature` object, required: Ed25519 signature over the canonical JSON of this receipt with the signature field omitted. Same key_id and same canonicalization rule as series certified extracts, published at /certified/public-key. Not a second production key. - `alg` 'Ed25519', required - `key_id` string, required: Same key_id as GET /certified/public-key and as series certified extracts. - `public_key` string, required: Absolute URL of GET /certified/public-key. - `signed_payload` string, required: canonical JSON of answer_receipt: keys sorted recursively, no whitespace (see /certified/public-key) - `value` string, required: Base64 Ed25519 signature. ## Other responses - `400`: Invalid body, or no convention supplied (free). No receipt. - `402`: Payment Required. No receipt object is returned on 402. - `404`: Unknown calendar (free). No receipt. - `422`: Refused free: calendar coverage exhausted, no cited cycle for this market+instrument, cycle not in force on the trade date, T+0 on a non-business day, or ambiguous calendar. No receipt. - `501`: FX spot value dates are not computed — the USD-holiday test admits more than one documented reading (free) --- [API](https://skmtc.dev/afriref/apis/afriref-pan-african-government-reference-data.md) · [All operations](https://skmtc.dev/afriref/apis/afriref-pan-african-government-reference-data/llms.txt) · [OpenAPI document](https://skmtc.dev/afriref/apis/afriref-pan-african-government-reference-data/revisions/d78528e9f644?raw)