{"openapi":"3.1.0","info":{"title":"euroref - European government reference data","version":"1.0.0","description":"Authoritative European government reference values as clean JSON: central-bank policy rates, VAT rates, national minimum wages and public holidays for Austria (at), Belgium (be), Bulgaria (bg), Switzerland (ch), Czechia (cz), Germany (de), Denmark (dk), Spain (es), Euro Area (eu), Finland (fi), France (fr), United Kingdom (gb), Greece (gr), Hungary (hu), Ireland (ie), Iceland (is), Italy (it), Netherlands (nl), Norway (no), Poland (pl), Portugal (pt), Romania (ro), Serbia (rs), Sweden (se), Türkiye (tr), Ukraine (ua). Free tier: public holidays for every country, plus catalog and change feed. Paid access per-call via x402 (USDC) or prepaid card packs from $10 - no signup needed for x402, no subscription ever. Every value carries a citation to its official primary source (government gazette or central-bank statement), an effective date, a last-confirmed date and a staleness flag.","x-guidance":"GET /v1/{country}/{series} returns the current value of a reference series — e.g. GET /v1/at/policy-rate. Countries: at, be, bg, ch, cz, de, dk, es, eu, fi, fr, gb, gr, hu, ie, is, it, nl, no, pl, pt, ro, rs, se, tr, ua. Series: policy-rate, vat, minimum-wage, public-holidays, cpi, corporate-tax, income-tax, fx-reference. Append /history for past values. GET /v1/all returns every series for every country in one call. GET /catalog (free) lists all available series with freshness metadata, each with the official source it is cited to. If you are an x402/API seller making a cross-border digital sale, POST /v1/vat/determine tells you which jurisdiction's VAT applies, who accounts for it, and the registration trigger — cited to the statute (EU, UK, South Africa), and it handles the wallet-only unidentified-buyer case. Payment is x402 (USDC on Base) per call; no signup or API keys needed.","contact":{"name":"afriref API support","email":"api@3l-groupconsulting.co.za","url":"https://euroref.dev/pricing"},"termsOfService":"https://euroref.dev/terms"},"servers":[{"url":"https://euroref.dev"}],"x-example-urls":["https://euroref.dev/catalog","https://euroref.dev/public/at/holidays","https://euroref.dev/v1/at/policy-rate","https://euroref.dev/v1/at/policy-rate/history","https://euroref.dev/v1/all"],"paths":{"/catalog":{"get":{"operationId":"getCatalog","summary":"Catalog of all countries and series with freshness metadata (free)","tags":["Free"],"security":[],"responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/public/{country}/holidays":{"get":{"operationId":"getPublicHolidays","summary":"Public holiday calendar for a country (free)","tags":["Free"],"security":[],"parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string","enum":["at","be","bg","ch","cz","de","dk","es","eu","fi","fr","gb","gr","hu","ie","is","it","nl","no","pl","pt","ro","rs","se","tr","ua"],"example":"at"},"example":"at"}],"responses":{"200":{"description":"Holiday calendar","content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"series":{"type":"string"},"value":{"description":"Number for rates/wages; array of {date,name} for holiday calendars"},"unit":{"type":"string"},"effective_from":{"type":["string","null"],"format":"date"},"last_confirmed":{"type":"string","format":"date","description":"When this value was last verified against the official source"},"source":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["name","url"]},"stale":{"type":"boolean","description":"True when past the expected update cycle — treat with caution"},"notes":{"type":"string"},"effective_rate":{"type":"number","description":"Optional. Combined effective rate where statutory levies stack on top of the standard rate (e.g. Ghana VAT 15% + NHIL 2.5% + GETFund 2.5% = 20%). Present only where it differs from value."},"components":{"type":"array","description":"Optional. Breakdown of a composite rate into its named statutory components (present only where applicable, e.g. Ghana VAT).","items":{"type":"object","properties":{"name":{"type":"string"},"rate":{"type":"number"}},"required":["name","rate"]}}},"required":["country","series","value","effective_from","last_confirmed","source","stale"]}}}},"404":{"description":"Unknown country"}}}},"/v1/{country}/{series}":{"get":{"operationId":"getSeries","summary":"Current value of a reference series, with official source citation","tags":["Reference data"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string","enum":["at","be","bg","ch","cz","de","dk","es","eu","fi","fr","gb","gr","hu","ie","is","it","nl","no","pl","pt","ro","rs","se","tr","ua"],"example":"at"},"example":"at","description":"Country code"},{"name":"series","in":"path","required":true,"schema":{"type":"string","enum":["policy-rate","vat","minimum-wage","public-holidays","cpi","corporate-tax","income-tax","fx-reference"],"example":"policy-rate"},"example":"policy-rate","description":"Series id"}],"responses":{"200":{"description":"Current value","content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"series":{"type":"string"},"value":{"description":"Number for rates/wages; array of {date,name} for holiday calendars"},"unit":{"type":"string"},"effective_from":{"type":["string","null"],"format":"date"},"last_confirmed":{"type":"string","format":"date","description":"When this value was last verified against the official source"},"source":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["name","url"]},"stale":{"type":"boolean","description":"True when past the expected update cycle — treat with caution"},"notes":{"type":"string"},"effective_rate":{"type":"number","description":"Optional. Combined effective rate where statutory levies stack on top of the standard rate (e.g. Ghana VAT 15% + NHIL 2.5% + GETFund 2.5% = 20%). Present only where it differs from value."},"components":{"type":"array","description":"Optional. Breakdown of a composite rate into its named statutory components (present only where applicable, e.g. Ghana VAT).","items":{"type":"object","properties":{"name":{"type":"string"},"rate":{"type":"number"}},"required":["name","rate"]}}},"required":["country","series","value","effective_from","last_confirmed","source","stale"]}}}},"402":{"description":"Payment Required"},"404":{"description":"Unknown country or series"}}}},"/v1/{country}/{series}/history":{"get":{"operationId":"getSeriesHistory","summary":"Historical values of a series, filterable by date range","tags":["Reference data"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string","enum":["at","be","bg","ch","cz","de","dk","es","eu","fi","fr","gb","gr","hu","ie","is","it","nl","no","pl","pt","ro","rs","se","tr","ua"],"example":"at"},"example":"at"},{"name":"series","in":"path","required":true,"schema":{"type":"string","enum":["policy-rate","vat","minimum-wage","public-holidays","cpi","corporate-tax","income-tax","fx-reference"],"example":"policy-rate"},"example":"policy-rate"},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Historical entries"},"402":{"description":"Payment Required"},"404":{"description":"Unknown country or series"}}}},"/v1/all":{"get":{"operationId":"getAllSeries","summary":"Snapshot of every series for every country","tags":["Reference data"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Full snapshot"},"402":{"description":"Payment Required"}}}},"/v1/changes":{"get":{"operationId":"changes","summary":"FREE: what changed, and how recently every series was re-verified against its official source","description":"Unmetered and unpriced. Returns every series whose current value took effect on or after `since` (optional; defaults to the last 30 days), newest first, each with the date we last re-confirmed it and whether it is past its verification window. Also returns a freshness summary for the whole served dataset: how many series were re-verified within 1, 7, 30 and 90 days, how many are past their window, and which single series has gone longest without a check. Published free deliberately — freshness is checkable or it is marketing.","tags":["Discovery"],"parameters":[{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Only return series whose current value took effect on or after this date. Defaults to 30 days ago."}],"responses":{"200":{"description":"Changed series (newest first) plus a dataset-wide freshness summary"},"400":{"description":"since was not a real calendar date"}}}},"/v1/answers/wage-check":{"post":{"operationId":"answerWageCheck","summary":"Minimum-wage compliance verdict: is this salary at/above the statutory floor?","tags":["Answers"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","enum":["at","be","bg","ch","cz","de","dk","es","eu","fi","fr","gb","gr","hu","ie","is","it","nl","no","pl","pt","ro","rs","se","tr","ua"]},"amount":{"type":"number","description":"Wage in the country's own currency"},"period":{"type":"string","enum":["month","day","hour","week"],"description":"Must match the statutory floor's period — cross-period conversion is never guessed"}},"required":["country","amount","period"]}}}},"responses":{"200":{"description":"Verdict (above/at/below), margin, statutory floor, instrument citation. Honest statuses for countries with no enforceable floor or period mismatch."},"400":{"description":"Invalid body (free — validated before payment)"},"402":{"description":"Payment Required"},"404":{"description":"Unknown country"}}}},"/v1/answers/vat":{"post":{"operationId":"answerVat","summary":"VAT breakdown: net/tax/gross for an amount, incl. statutory levy components","tags":["Answers"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","enum":["at","be","bg","ch","cz","de","dk","es","eu","fi","fr","gb","gr","hu","ie","is","it","nl","no","pl","pt","ro","rs","se","tr","ua"]},"amount":{"type":"number"},"mode":{"type":"string","enum":["add","extract"],"description":"add = amount is net; extract = amount is gross (default add)"}},"required":["country","amount"]}}}},"responses":{"200":{"description":"Breakdown with rate applied, components where composite (e.g. Ghana), and instrument citation"},"400":{"description":"Invalid body (free)"},"402":{"description":"Payment Required"},"404":{"description":"Unknown country"},"422":{"description":"No single statutory VAT rate exists (e.g. Brazil transition) — free, with explanation"}}}},"/v1/answers/working-days":{"post":{"operationId":"answerWorkingDays","summary":"Working days in a date range: weekends and public holidays applied, next working day","tags":["Answers"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","enum":["at","be","bg","ch","cz","de","dk","es","eu","fi","fr","gb","gr","hu","ie","is","it","nl","no","pl","pt","ro","rs","se","tr","ua"]},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date","description":"Max 366 days after from"}},"required":["country","from","to"]}}}},"responses":{"200":{"description":"Counts, holidays hit, next working day, country weekend convention (Egypt Fri–Sat)"},"400":{"description":"Invalid body (free)"},"402":{"description":"Payment Required"},"404":{"description":"Unknown country"}}}},"/v1/answers/settlement-date":{"post":{"operationId":"answerSettlementDate","summary":"Settlement/value date: T+n business days across intersected national statutory calendars, with the cited market cycle","description":"Computes the date n business days after a trade date on the INTERSECTION of the calendars supplied, returning a per-day trail (every skipped day with the reason on each calendar), the convention applied and whether it was cited or caller-asserted, and each calendar's basis, weekend rule, coverage and official source. Calendars are NATIONAL STATUTORY holiday calendars, not CSD or trading-venue calendars — the response states each calendar's basis and any known divergence. Anything we cannot compute from a cited calendar under a stated convention is refused free before the payment gate: coverage exhaustion, an instrument class with no primary-sourced cycle, a trade date on which no cited cycle was in force, T+0 on a non-business day, and FX spot value dates. See GET /settlement-conventions (free) for every cycle we hold and what we deliberately refuse to cite.","tags":["Answers"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"trade_date":{"type":"string","format":"date","description":"Trade/reference date. Day 0: never counted toward n, never rolled forward."},"calendars":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":4,"description":"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":{"type":"integer","minimum":0,"maximum":30,"description":"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":{"type":"string","description":"ISO 3166-1 alpha-2 country of the market whose settlement cycle applies (with instrument_class)"},"instrument_class":{"type":"string","enum":["cash_equity","etf","corporate_bond","government_bond","tbill","repo","primary_issuance","other"],"description":"Instrument class. A government bond never inherits an equity cycle."}},"required":["trade_date","calendars"]}}}},"responses":{"200":{"description":"Settlement date, per-day trail, convention applied with citations, each calendar's basis/coverage/source, caveats"},"400":{"description":"Invalid body, or no convention supplied (free)"},"402":{"description":"Payment Required"},"404":{"description":"Unknown calendar (free)"},"422":{"description":"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"},"501":{"description":"FX spot value dates are not computed — the USD-holiday test admits more than one documented reading (free)"}}}},"/settlement-conventions":{"get":{"operationId":"settlementConventions","summary":"Free: every settlement cycle we hold, with its primary-source citation — and what we deliberately refuse to cite","tags":["Discovery"],"responses":{"200":{"description":"Cited cycles per market and instrument class, each with authority tier, in-force dates and citations, plus an explicit deliberately-absent list"}}}},"/v1/answers/income-tax":{"post":{"operationId":"answerIncomeTax","summary":"Statutory income tax on a taxable-income figure, with per-bracket workings","tags":["Answers"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","enum":["at","be","bg","ch","cz","de","dk","es","eu","fi","fr","gb","gr","hu","ie","is","it","nl","no","pl","pt","ro","rs","se","tr","ua"]},"taxable_income":{"type":"number","description":"Taxable income in local currency, in the schedule's own period basis. NOT gross pay — reliefs are applied first, and are not modelled here."}},"required":["country","taxable_income"]}}}},"responses":{"200":{"description":"Tax, effective + marginal rate, per-bracket breakdown, tax-unit scaling (UVT/UTA/UIT/BPC), instrument citation, and a scope_note that this is not net take-home pay"},"400":{"description":"Invalid body (free — validated before payment)"},"402":{"description":"Payment Required"},"404":{"description":"Unknown country"},"422":{"description":"Country's income-tax schedule is not in computable bracket form (free)"}}}},"/v1/vat/determine":{"post":{"operationId":"determineCrossBorderVat","summary":"Cross-border VAT treatment of a digital-services sale (EU, UK, South Africa) — the applied rule, cited to the statute","description":"Regulatory information with citations, for x402/API sellers: place of supply, who accounts for the VAT, rate basis, registration/threshold trigger and reporting mechanism for a seller-country → buyer-country digital-services sale. Unknown buyers (wallet-address only) are resolved under B2C-default rules and explicitly flagged; combinations outside the verified ruleset are refused FREE (422) before payment — never guessed, never charged.","tags":["x402 sellers"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.100000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"seller_country":{"type":"string","description":"ISO 3166-1 alpha-2 (EL accepted for Greece, UK for United Kingdom)"},"buyer_country":{"type":"string","description":"ISO 3166-1 alpha-2"},"buyer_type":{"type":"string","enum":["B2B","B2C","unknown"],"description":"Default unknown — treated as B2C and flagged in the response"}},"required":["seller_country","buyer_country"]}}}},"responses":{"200":{"description":"The applied rule (place of supply, who accounts, rate basis, registration trigger, reporting) with statutory citation, classification workings, destination-liability companion where applicable, e-services definition, ViDA forward-flag and disclaimer"},"400":{"description":"Invalid body (free — validated before payment)"},"402":{"description":"Payment Required"},"405":{"description":"Wrong method (free) — use POST"},"422":{"description":"Combination outside the verified ruleset (free, labeled — never guessed, never charged)"}}}},"/alerts":{"post":{"operationId":"registerAlert","summary":"Register a webhook fired when subscribed series change (HMAC-SHA256 signed)","tags":["Alerts"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.100000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Webhook endpoint to receive series.changed events"},"series":{"type":"array","items":{"type":"string"},"description":"Patterns like \"ng/policy-rate\", \"ke/*\", or \"*\"","minItems":1,"maxItems":20}},"required":["url","series"]}}}},"responses":{"201":{"description":"Subscription created; response includes the HMAC secret (shown once)"},"400":{"description":"Invalid body"},"402":{"description":"Payment Required"}}}}}}