{"openapi":"3.1.0","info":{"title":"afriref - Pan-African government reference data","version":"1.0.0","description":"Authoritative Pan-African government reference values as clean JSON: central-bank policy rates, VAT rates, national minimum wages and public holidays for Côte d'Ivoire (ci), Egypt (eg), Ethiopia (et), Ghana (gh), Kenya (ke), Morocco (ma), Nigeria (ng), Rwanda (rw), Senegal (sn), Tanzania (tz), Uganda (ug). 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/ci/policy-rate. Countries: ci, eg, et, gh, ke, ma, ng, rw, sn, tz, ug. Series: policy-rate, vat, minimum-wage, public-holidays, cpi, corporate-tax, income-tax. 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. Payment is x402 (USDC on Base) per call; no signup or API keys needed.","contact":{"email":"api@3l-groupconsulting.co.za"}},"servers":[{"url":"https://afriref.dev"}],"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":["ci","eg","et","gh","ke","ma","ng","rw","sn","tz","ug"]}}],"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","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.005000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string","enum":["ci","eg","et","gh","ke","ma","ng","rw","sn","tz","ug"]},"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"]},"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","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.005000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string","enum":["ci","eg","et","gh","ke","ma","ng","rw","sn","tz","ug"]}},{"name":"series","in":"path","required":true,"schema":{"type":"string","enum":["policy-rate","vat","minimum-wage","public-holidays","cpi","corporate-tax","income-tax"]}},{"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":"getChanges","summary":"Series whose current value changed since a given date","tags":["Reference data"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"since","in":"query","required":true,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Changed series"},"400":{"description":"Missing or invalid since parameter"},"402":{"description":"Payment Required"}}}},"/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":["ci","eg","et","gh","ke","ma","ng","rw","sn","tz","ug"]},"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":["ci","eg","et","gh","ke","ma","ng","rw","sn","tz","ug"]},"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":["ci","eg","et","gh","ke","ma","ng","rw","sn","tz","ug"]},"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/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":["ci","eg","et","gh","ke","ma","ng","rw","sn","tz","ug"]},"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/answers/payroll":{"post":{"operationId":"answerPayroll","summary":"Gross-to-net payroll: PAYE + statutory deductions → net take-home (Nigeria, Kenya)","tags":["Answers"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.100000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","enum":["ke","ng"]},"gross":{"type":"number","description":"Gross pay in local currency"},"period":{"type":"string","enum":["month","year"],"description":"default month"},"basic":{"type":"number","description":"Nigeria: basic pay (exact pension/NHF base; else 40/30/10 assumed & disclosed)"},"housing":{"type":"number"},"transport":{"type":"number"},"annual_rent":{"type":"number","description":"Nigeria: unlocks rent relief (cap ₦500,000)"},"sector":{"type":"string","enum":["public","private"]},"nhis_premium":{"type":"number"},"pensionable_pay":{"type":"number","description":"Kenya: NSSF tier base"},"insurance_premium":{"type":"number","description":"Kenya: 15% insurance relief"}},"required":["country","gross"]}}}},"responses":{"200":{"description":"Net pay, PAYE, statutory deductions, taxable income, per-bracket workings, disclosed assumptions, and bracket + contribution-law citations"},"400":{"description":"Invalid body (free)"},"402":{"description":"Payment Required"},"404":{"description":"Unknown country"},"422":{"description":"Payroll not yet supported for this country (free)"}}}},"/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"}}}}}}