dev.afriref/reference-data

Tools

• add_business_days

  FREE, unmetered. The date n business days after (or, for negative n, before) a start date. The start date is day 0 and never counted; n = 0 returns the date itself if it is a business day, otherwise the next one. Lists every non-business day skipped and why. Uses the country's national public-holiday calendar and its statutory weekend rule (Gulf Friday+Saturday, Israel Saturday-only, India 2nd/4th Saturdays, Nepal's 2026 change, China's multi-day breaks and make-up working days). A date in a year whose holidays we do not hold is refused with error year_not_held and the years_held list; it is never computed from weekends alone. A statutory holiday whose date is not yet fixed is refused as holiday_date_pending. Regional (sub-national) holidays are not applied.

  shallow
• business_days_between

  FREE, unmetered. Business days between two dates. business_days counts (from, to] and is negative when to is before from, so add_business_days(from, business_days) lands on to whenever to is a business day; business_days_inclusive counts both ends. Also returns weekend days and the public holidays in range. Uses the country's national public-holiday calendar and its statutory weekend rule (Gulf Friday+Saturday, Israel Saturday-only, India 2nd/4th Saturdays, Nepal's 2026 change, China's multi-day breaks and make-up working days). A date in a year whose holidays we do not hold is refused with error year_not_held and the years_held list; it is never computed from weekends alone. A statutory holiday whose date is not yet fixed is refused as holiday_date_pending. Regional (sub-national) holidays are not applied.

  shallow
• charge_sale

  PAID ($0.50). Charge this sale: should this invoice carry VAT, which country's and how much - place of supply under the EU, UK and South Africa rules, net/VAT/gross, registration threshold, rule cited. Omit buyer_country for single-country rate maths. Anything we cannot answer in full is refused free (coverage_gap, no_charge). Shares the 3 free calls per IP per day with the answer tools. Pass api_key if you have one (card checkout at /pricing); otherwise the result is the x402 payment requirement. Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.10 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.

  shallow
• charge_sale_certified

  PAID ($0.75). The charge_sale dossier plus an Ed25519-signed certified extract of the governing VAT rate, for a filing. Refused free when the governing source cannot be certified right now. Anything we cannot answer in full is refused free (coverage_gap, no_charge). Shares the 3 free calls per IP per day with the answer tools. Pass api_key if you have one (card checkout at /pricing); otherwise the result is the x402 payment requirement. Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.10 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.

  shallow
• check_minimum_wage

  PAID ($0.02). Compliance verdict: is a salary at, above or below the country's statutory minimum wage? Returns verdict, margin, the statutory floor and the legal instrument it rests on. Honest statuses when no enforceable floor exists or the period doesn't match the floor's period (cross-period conversion is never guessed). Pass api_key if you have one (instant card checkout at /pricing); otherwise the response explains how to pay via x402. The evaluation country is free to try (see list_series). Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.10 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.

  shallow
• compare_series

  PAID ($0.02). One series (e.g. vat, policy-rate, minimum-wage, corporate-tax) across up to 10 countries of this brand in one call; each row carries its own source, dates and labels, and countries without the series are listed under missing. Malformed requests are refused free. Pass api_key if you have one; otherwise the response explains how to pay via x402. After a 200, bind get_changes (free poll) or register_alert (HMAC push; Register: $0 · Delivery after trial: $0.05) on this series so a later gazette does not silently retire the value.

  shallow
• compute_income_tax

  PAID ($0.02). Statutory income tax on a TAXABLE-income figure using the country's verified marginal bracket schedule, with full per-bracket workings, effective rate and marginal rate. You pass the amount in local currency. IMPORTANT: this is tax on taxable income, NOT net take-home pay — reliefs/allowances and social-security contributions are the caller's concern and are not applied (see the response scope_note). Pass api_key if you have one (instant card checkout at /pricing); otherwise the response explains how to pay via x402. The evaluation country is free to try (see list_series). Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.10 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.

  shallow
• compute_payroll

  PAID ($0.05). Gross-to-net take-home pay for Nigeria or Kenya: applies PAYE (on the verified brackets) plus the statutory employee deductions (Nigeria: pension/NHF/NHIS; Kenya: NSSF/SHIF/Affordable Housing Levy) and reliefs, returning net pay with full workings, per-contribution citations and DISCLOSED assumptions. Nigeria's pension base needs pay composition — pass basic/housing/transport for an exact figure, or a market-convention 40/30/10 split is assumed and disclosed. Pass api_key if you have one (instant card checkout at /pricing); otherwise the response explains how to pay via x402. The evaluation country is free to try (see list_series). Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.10 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.

  shallow
• compute_statutory_interest

  PAID ($0.02). Simple statutory interest on a principal at the cited statutory-interest series rate: Actual/365 simple, principal × (rate/100) × (days/365). Pass days, or from and to as YYYY-MM-DD (from inclusive, to exclusive). If both are sent and disagree, the call is refused free. A series with no numeric rate after materialization (mechanism-only) is refused free — a non-answer is not sold. Not legal advice. Jurisdiction-specific compounding and day-count statutes are not applied. Pass api_key if you have one (instant card checkout at /pricing); otherwise the response explains how to pay via x402. Every GH series is free to try. Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.10 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.

  shallow
• compute_vat

  PAID ($0.01). VAT breakdown for an amount: net, tax and gross using the country's current statutory rate, including per-levy components where the rate is composite (e.g. Ghana VAT + NHIL + GETFund). mode=add treats the amount as net; mode=extract backs VAT out of a gross amount. Pass api_key if you have one (instant card checkout at /pricing); otherwise the response explains how to pay via x402. The evaluation country is free to try (see list_series). Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.10 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.

  shallow
• cost_hire

  PAID ($0.50). Cost this hire: one cited dossier for a salary - wage-floor verdict, employer and employee contributions (or PAYE net pay for NG/KE), employer cost, optional income tax on taxable_income and first working day on or after start_date. Countries here: KE, NG. Anything we cannot answer in full is refused free (coverage_gap, no_charge). Shares the 3 free calls per IP per day with the answer tools. Pass api_key if you have one (card checkout at /pricing); otherwise the result is the x402 payment requirement. Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.10 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.

  shallow
• count_working_days

  PAID ($0.002). Working days in a date range for a country: weekends (Egypt's Fri–Sat handled) and statutory public holidays applied, with the holidays hit by name and the next working day after the range. Range max 366 days. Pass api_key if you have one (instant card checkout at /pricing); otherwise the response explains how to pay via x402. The evaluation country is free to try (see list_series). Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.10 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.

  shallow
• evidence_pack

  PAID ($0.25). Country evidence pack: the full cited country brief plus up to 3 Ed25519-signed certified extracts (default the first certifiable of vat, policy-rate, minimum-wage). Named series must all be certifiable. Anything we cannot answer in full is refused free (coverage_gap, no_charge). Shares the 3 free calls per IP per day with the answer tools. Pass api_key if you have one (card checkout at /pricing); otherwise the result is the x402 payment requirement. Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.10 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.

  shallow
• get_calendar

  FREE, unmetered. GET /v1/calendar for this brand's continent. Optional country (ISO 3166-1 alpha-2) and series. Derives reverify_by from last_confirmed + update_cycle_days (the same window that sets stale) and, only when current.effective_to is a non-empty string, next_effective_known with basis effective_to. status unknown omits that date. Never parses notes. Does not invent MPC, budget, or wage-review dates. next_effective_known is the recorded end of the current value, not a promised gazette event. A 402 is a gate bug — do not pay. Past changes stay on get_changes.

  shallow
• get_changes

  FREE unmetered change + freshness feed. After any paid series or answer call, call this before you assume the cached value is still the law. Returns every series whose current value took effect on or after `since` (default last 30 days), newest first, each with last_confirmed and stale, PLUS a dataset-wide freshness summary: how many of the served series were re-verified within 1/7/30/90 days, how many are past their window, and which single series has gone longest without a check. Freshness is checkable or it is marketing. Args: since? (YYYY-MM-DD). Do not re-pay get_series to discover a diff. For a push bind, use register_alert (Register: $0 · Delivery after trial: $0.05). For a filing freeze of the current value, GET /v1/certified/{country}/{series} ($0.10).

  shallow
• get_country_brief

  PAID ($0.01). Country brief: every reference series we hold for one country (policy rate, VAT/GST, CPI, taxes, minimum wage, holidays...) in one call, each with value, unit, effective and last-confirmed dates, official source and confidence label. Cheaper than buying the series one by one. Pass api_key if you have one (card checkout at /pricing); otherwise the response explains how to pay via x402. After a 200, bind get_changes (free poll) or register_alert (HMAC push; Register: $0 · Delivery after trial: $0.05) on this series so a later gazette does not silently retire the value.

  shallow
• get_filing_deadlines

  PAID ($0.003, same as any series). Recurring statutory tax deadlines for a country — VAT/GST returns and payments, PAYE/payroll withholding remittances, corporate income tax returns and provisional/instalment payments — as RULES, each cited to the official source with the verbatim phrase that states it, plus the actual DUE DATES in a window, rolled for the country's weekend and national public holidays (every skipped day is listed). Where a rule's source does not say which way a weekend deadline moves, the date is flagged roll_unverified rather than guessed. Countries or taxes we could not verify are returned as a free coverage_gap with reasons, never invented. Pass year_end (MM-DD) to re-anchor corporate-tax rules on the company's own accounting year end. The HTML page /{country}/filing-deadlines shows the rules free. Every GH series is free to try. After a 200, bind get_changes (free poll) or register_alert (HMAC push; Register: $0 · Delivery after trial: $0.05) on this series so a later gazette does not silently retire the value.

  shallow
• get_key_balance

  FREE. Remaining allowance for an API key (free, card or metered): plan, quota, used, remaining, reset date and what the key covers. Never metered. Pass api_key, or send the key as the X-API-Key header on /mcp.

  shallow
• get_public_holidays

  FREE. Official public-holiday calendar for a supported country, including gazetted movable holidays, with the official government source cited. Some countries also carry sub-national calendars (e.g. the German Laender): the `subdivisions` field lists them, and passing `subdivision` (ISO 3166-2, e.g. 'DE-BY') returns the national calendar merged with that region's statutory days.

  shallow
• get_public_holidays_worldwide

  FREE with any API key, including the free key by email (https://afriref.dev/free-key). Same as get_public_holidays, but for every country across all seven brands, not only Pan-African. Unmetered: never counts against the key's allowance. Pass api_key, or send the key as the X-API-Key header on /mcp.

  shallow
• get_series

  PAID ($0.003). Current value of a reference series — e.g. series=policy-rate, vat, minimum-wage. Every value carries its official source citation, effective date, last-confirmed date and staleness flag. Pass api_key if you have one (instant card checkout at /pricing); otherwise the response explains how to pay via x402. Every GH series is free to try. After a 200, bind get_changes (free poll) or register_alert (HMAC push; Register: $0 · Delivery after trial: $0.05) on this series so a later gazette does not silently retire the value.

  shallow
• get_series_history

  PAID ($0.003). Historical values of a reference series with effective date ranges, optionally filtered by from/to (YYYY-MM-DD). Pass api_key if you have one (instant card checkout at /pricing); otherwise the response explains how to pay via x402. Every GH series is free to try. After a 200, bind get_changes (free poll) or register_alert (HMAC push; Register: $0 · Delivery after trial: $0.05) on this series so a later gazette does not silently retire the value.

  shallow
• get_snapshot

  PAID ($0.02). Snapshot of every series for every country in one call. Pass api_key if you have one (instant card checkout at /pricing); otherwise the response explains how to pay via x402. Every GH series is free to try. After a 200, bind get_changes (free poll) or register_alert (HMAC push; Register: $0 · Delivery after trial: $0.05) on this series so a later gazette does not silently retire the value.

  shallow
• hire_compare

  PAID ($0.75 for 2 countries, $1.00 for 3-5). Employer cost, employer and employee contributions, on-cost percent and wage-floor verdict side by side and ranked, every figure cited. Countries (any brand): AE, AU, CA, DE, ES, GB, IT, MX, PL, US. Gross is in each country's own currency; currencies are not converted. Anything we cannot answer in full is refused free (coverage_gap, no_charge). Shares the 3 free calls per IP per day with the answer tools. Pass api_key if you have one (card checkout at /pricing); otherwise the result is the x402 payment requirement. Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.10 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.

  shallow
• invoice_payable

  PAID ($0.40). Is this invoice overdue, by how many days, and how much statutory late-payment interest is owed (Actual/365 simple, rate and workings cited). Late-payment regime: none here; statutory interest only: BF, BJ, BW, CI, CM, DZ, EG, ET, MA, ML, MU, MZ, NA, NE, SN, TG, TN, ZA. Send due_date, or invoice_date with terms_days. Anything we cannot answer in full is refused free (coverage_gap, no_charge). Shares the 3 free calls per IP per day with the answer tools. Pass api_key if you have one (card checkout at /pricing); otherwise the result is the x402 payment requirement. Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.10 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.

  shallow
• is_business_day

  FREE, unmetered. Is this date a business day in this country? Returns is_business_day, the reason (weekend, public_holiday, makeup_workday…), the holiday names, and the next and previous business day. Uses the country's national public-holiday calendar and its statutory weekend rule (Gulf Friday+Saturday, Israel Saturday-only, India 2nd/4th Saturdays, Nepal's 2026 change, China's multi-day breaks and make-up working days). A date in a year whose holidays we do not hold is refused with error year_not_held and the years_held list; it is never computed from weekends alone. A statutory holiday whose date is not yet fixed is refused as holiday_date_pending. Regional (sub-national) holidays are not applied.

  shallow
• list_series

  FREE. Catalog of all afriref reference-data series: supported countries, series ids, descriptions, freshness metadata and per-series URLs. Call this first to discover what data exists. Paid answer tools accept receipt=true (included in the answer price, no extra USDC) and, on a paid success, return an Ed25519 answer receipt (kind answer_receipt). That receipt is not a series certified extract and is not legal advice. Series certified extracts are GET /v1/certified/{country}/{series} at $0.10 and are not an MCP tool. Verify a receipt with verify_answer_receipt (free, public key only) against /certified/public-key. get_changes is free. get_calendar is free. register_alert registration is free.

  shallow
• next_filings

  PAID ($0.35). Upcoming VAT, PAYE and corporate-tax due dates in a window (default the next 90 days), rolled for weekends and national public holidays, each rule cited. Countries with verified rules here: EG, GH, KE, MU, NG, RW, SN, TN, TZ, UG, ZA. Anything we cannot answer in full is refused free (coverage_gap, no_charge). Shares the 3 free calls per IP per day with the answer tools. Pass api_key if you have one (card checkout at /pricing); otherwise the result is the x402 payment requirement. Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.10 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.

  shallow
• register_alert

  Bind a webhook so the next gazette does not silently stale a value you already paid for. REGISTERING IS FREE. Register: $0 · Delivery after trial: $0.05. First 3 deliveries are free; later deliveries are $0.05 and refunded if the webhook fails to send. HMAC-SHA256 signed. Two watch types on the same call: • series: ["za/vat-registration-threshold", "ke/*", "*"] → series.changed when the served value or its effective date moves. On usaref those watches are statutory (minimum-wage, income-tax, statutory-interest, sales-tax, public-holidays), not a FRED-macro subscription. • sources: ["<exact official source.url>"] → source.changed when the document BYTES change (old/new sha256 + citing series). Bytes ≠ value. Value changes arrive as series.changed. Unknown URLs refuse free (source_not_fingerprinted). Max 20 series + 20 sources. Required: url. Optional: api_key stored on the subscription to fund deliveries after the trial. This call does not meter that key. Prefer this over polling get_changes if you are a long-running agent. This is retention, not a new data product.

  shallow
• settlement_date

  PAID ($0.02). Settlement/value date: the date n business days after a trade date, computed on the INTERSECTION of the calendars you name, with a per-day trail showing every skipped day and why, on which calendar. Supply business_days for a cycle you are trading under, or market + instrument_class to have a settlement cycle applied that we cite to its primary source (e.g. US equities T+1 under 17 CFR 240.15c6-1(a); UK gilts T+1 by DMO convention, which is NOT the T+2 equity cycle; Japan equities T+2 but JGBs T+1). Calendars are NATIONAL statutory holiday calendars with researched statutory weekend rules (Israel Saturday-only, Gulf Friday+Saturday, India Sundays plus the 2nd and 4th Saturday), NOT CSD or exchange calendars — each response states the basis and any known divergence. Use 'eu.t2' for the euro cash leg. We refuse FREE rather than guess: beyond published calendar coverage, no cited cycle for the instrument (government bonds never inherit an equity cycle), a cycle not in force on the trade date, or FX spot value dates. Free companion: GET /settlement-conventions. Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.10 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.

  shallow
• validate_tax_id

  PAID ($0.003). Offline format and check-digit validation of a business tax ID or VAT number for one country of this brand: valid/invalid, normalised form, id type, check level (checksum only where the authority publishes the algorithm) and why it failed, with official sources. Does not confirm registration; follow official_lookup for that. Countries without a sourced rule answer free with status 'unknown'. Pass api_key if you have one; otherwise the response explains how to pay via x402. After a 200, bind get_changes (free poll) or register_alert (HMAC push; Register: $0 · Delivery after trial: $0.05) on this series so a later gazette does not silently retire the value.

  shallow
• verify_answer_receipt

  FREE. Verify an answer receipt (kind answer_receipt) with the Ed25519 public key only. Pass the receipt object or its canonical JSON, signature_value when the signature is not inside the receipt, and public_key_pem to verify offline. If public_key_pem is omitted, the tool may GET signature.public_key (/certified/public-key) and read public_key_pem. Never send a private key. A valid signature shows this service issued that exact receipt. It does not turn the receipt into a series certified extract (GET /v1/certified/{country}/{series} at $0.10, not an MCP tool) and it is not legal advice. Same key and canonical-JSON rule as /certified/public-key.

  shallow

Embed this server’s score

Tool count and median score across every tool in this server’s corpus — honest in a way a single cherry-picked tool’s badge wouldn’t be.

[![Vouch score](https://vouch.tools/api/servers/befb60f9-c2b9-49b3-926d-d1d4a8200867/badge.svg)](https://vouch.tools/servers/befb60f9-c2b9-49b3-926d-d1d4a8200867)