# zaref — South African reference data API

Clean, current, cited JSON for SA reference values that otherwise live in government PDFs.
Every value carries source_url, effective_date, last_confirmed and next_expected_update.
A series past its expected update self-declares stale:true rather than pretending.
Independent data service. Not affiliated with, or endorsed by, any South African government entity. Every value carries the official source URL and its effective date; verify against the source for legal or financial use.

Catalog (free): https://zaref.dev/catalog
OpenAPI 3.1: https://zaref.dev/openapi.json
MCP server (Streamable HTTP): https://zaref.dev/mcp — tools: list_series, get_public_holidays, get_series_info

## Series
- https://zaref.dev/v1/fuel-prices — Current SA retail/wholesale fuel prices: petrol 93/95 (inland & coastal), diesel 50ppm, illuminating paraffin. Rand per litre.
- https://zaref.dev/v1/repo-prime — SARB repo rate and prime lending rate, with last MPC change date.
- https://zaref.dev/v1/cpi — Latest Stats SA headline consumer inflation, year-on-year %, with reference month.
- https://zaref.dev/v1/income-tax — Personal income tax brackets, rebates and thresholds for the current SA tax year.
- https://zaref.dev/v1/vat — VAT rate currently in force in South Africa.
- https://zaref.dev/v1/uif-oid — UIF contribution remuneration ceiling and OID (COIDA) earnings threshold.
- https://zaref.dev/v1/minimum-wage — National minimum wage per hour, incl. special categories, with effective date.
- https://zaref.dev/v1/public-holidays — Official SA public holidays for the current calendar year, incl. proclaimed one-offs and Sunday observances.
- https://zaref.dev/v1/school-terms — DBE public school term dates.
- https://zaref.dev/v1/sassa-grants — All SASSA social grant amounts incl. SRD, with effective date.
- https://zaref.dev/v1/travel-rates — SARS prescribed per-km reimbursement rate and subsistence allowances for the current tax year.
- https://zaref.dev/v1/tax-rates-other — Corporate tax, dividends WHT, CGT inclusion, transfer duty brackets, retirement caps, medical tax credits, interest exemptions, estate/donations tax.
- https://zaref.dev/v1/unemployment — Latest Stats SA QLFS official and expanded unemployment rates, with reference quarter.
- https://zaref.dev/v1/gdp — Latest Stats SA GDP growth (QoQ and YoY), with reference quarter.
- https://zaref.dev/v1/ppi — Latest Stats SA producer inflation YoY, with reference month.
- https://zaref.dev/v1/toll-fees — Mainline toll plaza tariffs (vehicle classes 1-4) for the major national routes, current adjustment.
- https://zaref.dev/v1/electricity-tariffs — NERSA-approved Eskom tariff increases and key residential rates for the current year.
- https://zaref.dev/v1/municipal-tariffs — Residential electricity/water/refuse/rates headline tariffs for the 5 big metros, current municipal year.
- https://zaref.dev/v1/learnership-allowances — Minimum weekly learnership allowances per NQF level, per the current NMW gazette.
- https://zaref.dev/v1/sectoral-wages — Minimum wages for sectors with their own determinations (contract cleaning, private security, etc.) beside the NMW.
- https://zaref.dev/v1/sars-interest-rates — Official rate of interest (fringe benefits, s7C loans), SARS interest on outstanding taxes and refunds, and the prescribed rate of interest for legal and judgment debts.
- https://zaref.dev/v1/retirement-limits — Retirement contribution deduction cap, tax-free savings limits, retirement and withdrawal lump-sum tax tables, living-annuity thresholds.
- https://zaref.dev/v1/nca-max-rates — Maximum lawful interest rates per credit type under NCA Regulation 42 Table A, computed at the current repo rate, plus the in duplum rule and service fee cap.
- https://zaref.dev/v1/bcea-thresholds — The BCEA earnings threshold, which working-time protections fall away above it, the earnings definition and related LRA/EEA effects.
- https://zaref.dev/v1/tax-calendar — SARS filing-season windows, provisional tax deadlines, employer reconciliation windows and recurring monthly deadlines.
- https://zaref.dev/v1/exchange-control — Single discretionary allowance (R2m from April 2026), foreign investment allowance, minors' travel and cash export limits, with the TCS PIN rules.
- https://zaref.dev/v1/deeds-fees — Deeds Office transfer and bond registration fee tiers, lodgement and ancillary fees, per the current gazetted schedule.
- https://zaref.dev/v1/fuel-levies — General fuel levy, RAF levy and carbon fuel levy per litre for petrol and diesel, plus the carbon tax rate, including temporary relief episodes.
- https://zaref.dev/v1/zaronia — SARB's ZARONIA risk-free overnight benchmark, the designated JIBAR successor (JIBAR ceases 2026-12-31), with the transition timeline and daily-rate history for compounded interest calculations.
- https://zaref.dev/v1/wear-and-tear-periods — SARS BGR7 schedule of straight-line depreciation write-off periods (in years) for over 140 asset classes, plus the R7,000 small-item write-off threshold.
- https://zaref.dev/v1/fx-rates — SARB indicative daily ZAR exchange rates against USD, GBP, EUR and JPY, plus the nominal effective exchange rate (trade-weighted) index.
- https://zaref.dev/v1/bond-yields — SARB closing yields on the R2030 and R209 South African government benchmark bonds, key reference points for the domestic yield curve.
- https://zaref.dev/v1/sovereign-credit-rating — South Africa's current credit rating and outlook from Moody's, S&P Global and Fitch, with each agency's most recent rating action date.

## Calculators (computed from the verified tables, $0.01 per call; /calc/vat is free)
- https://zaref.dev/calc/income-tax?annual=750000&age=40 — SA personal income tax for the current tax year: annual and monthly tax, effective rate, age rebates applied.
- https://zaref.dev/calc/net-salary?monthly=50000&age=35 — Net take-home from a gross monthly salary: PAYE plus employee UIF at the current tables.
- https://zaref.dev/calc/transfer-duty?price=2500000 — Property transfer duty from the current SARS brackets.
- https://zaref.dev/calc/fuel-cost?km=568&l_per_100km=7.5&fuel=petrol_95&region=inland — Fuel cost for a trip at current official SA fuel prices.
- https://zaref.dev/calc/toll-route?route=N3&vehicle_class=1 — Total mainline toll cost for a full run of a national route at current gazetted tariffs.
- https://zaref.dev/calc/vat?amount=1000&direction=add — Add or strip VAT at the current SA rate (direction=add | remove | strip; unrecognised values are rejected). Free.
- https://zaref.dev/calc/cgt?gain=500000&type=individual&taxable_income=800000 — Capital gains tax for individuals (marginal method), companies and trusts.
- https://zaref.dev/calc/estate-duty?estate=10000000 — Estate duty after the section 4A abatement, tiered at R30m.
- https://zaref.dev/calc/learnership?nqf=4&credits=200 — Minimum weekly learnership allowance by NQF level and credits.
- https://zaref.dev/calc/lump-sum-tax?amount=1200000&type=retirement — Tax on a retirement fund lump sum or withdrawal using the cumulative SARS method (prior lump sums aggregate).
- https://zaref.dev/calc/nca-max-rate?type=unsecured — Maximum lawful interest rate for a credit agreement under NCA Regulation 42 Table A, at the current or a given repo rate.
- https://zaref.dev/calc/property-costs?price=2500000&bond=2000000 — Total statutory costs of buying a property: transfer duty plus Deeds Office transfer, bond and lodgement fees.
- https://zaref.dev/calc/two-pot-withdrawal?amount=50000&annual_income=600000 — Tax on a two-pot retirement savings-component withdrawal at the member's marginal rate.
- https://zaref.dev/calc/travel-allowance?monthly_allowance=8000&annual_income=720000 — PAYE inclusion and monthly tax impact of a fixed travel allowance under the 80/20 rule.
- https://zaref.dev/calc/company-car?vehicle_value=450000&maintenance_plan=true&annual_income=720000 — Company car fringe benefit: monthly taxable value (3.5%/3.25%) and PAYE impact.
- https://zaref.dev/calc/bond-repayment?amount=1500000&years=20 — Monthly bond repayment and total interest, at the live prime rate by default.
- https://zaref.dev/calc/zaronia-interest?principal=1000000&start=2026-07-10&end=2026-07-14 — Compound-in-arrears interest on a principal over a date range, using zaref's accumulating daily ZARONIA history (ACT/365). Coverage limited to dates zaref has tracked.
- https://zaref.dev/calc/uif?monthly_salary=25000 — Monthly UIF contribution (employee 1% + employer 1%) at the current earnings ceiling.
- https://zaref.dev/calc/donations-tax?amount=500000 — Donations tax owed on a donation, after the annual natural-person exemption.
- https://zaref.dev/calc/local-interest?amount=40000&age=40 — Taxable local interest after the age-based annual exemption.
- https://zaref.dev/calc/medical-tax-credit?members=1&dependants=2&out_of_pocket_annual=15000&taxable_income=500000 — Medical scheme fees tax credit plus the additional medical expenses tax credit from qualifying out-of-pocket costs.
- https://zaref.dev/calc/provisional-tax?annual_taxable_income=900000&employees_tax_paid=180000 — Estimated first and second provisional tax payments (50/50 split) net of employees' tax already withheld, with the current filing deadlines.
- https://zaref.dev/calc/net-to-gross?net_monthly=40000&age=35 — Gross monthly salary required to net a target take-home amount, at the current tax tables.
- https://zaref.dev/calc/home-office-expense?office_area_m2=12&home_area_m2=180&annual_home_costs=240000 — Deductible home office expense by area apportionment (s23(b)/(m)).
- https://zaref.dev/calc/sbc-tax?annual_taxable_income=600000 — Small Business Corporation income tax at the progressive SBC rates (eligibility conditions apply).
- https://zaref.dev/calc/wear-and-tear?asset=Passenger%20cars&cost=350000 — Annual and monthly straight-line wear-and-tear allowance for an asset, using the SARS BGR7 write-off period schedule.
- https://zaref.dev/calc/crypto-tax?capital_gain=150000&revenue_gain=50000&other_taxable_income=600000&age=35 — Estimated SA tax on crypto asset gains: revenue-nature profits taxed at the marginal rate, capital-nature gains via CGT with the annual exclusion and 40% inclusion. Handles staking/mining/airdrop receipts and FIFO batch matching of a raw buy/sell transaction list.
- https://zaref.dev/calc/crypto-classify?holding_period_months=30&trades_per_month=1&intention=hold_long_term — Indicative capital-vs-revenue classification of crypto gains by weighing the classic SA case-law factors: intention, holding period and trading frequency.
- https://zaref.dev/calc/bond-price?face_value=1000000&coupon_percent=8&years_to_maturity=4 — Clean price of a fixed-rate bond from face value, coupon and years to maturity, at a given yield (defaults to the live R2030 benchmark yield).

## Live feeds ($0.005 per call)
- https://zaref.dev/v1/tenders?province=Gauteng&closing_within_days=14 — Live South African government tender feed from National Treasury's eTenders OCDS API: filter by province, procurement category, buyer, keyword and closing window. Returns compact tender records with closing dates, briefing sessions, documents and contacts.
- https://zaref.dev/v1/crypto-prices?pairs=BTCZAR,ETHZAR — Live ZAR crypto prices from VALR's public market data: last traded, bid/ask, 24-hour high/low/volume and daily change for BTC, ETH and every other ZAR pair on the exchange.

## History
- https://zaref.dev/v1/{series}/history — dated history points per series ($0.01 per call), accumulating from 2026-07 with backfill for key series.

## Freshness diff
- https://zaref.dev/v1/changes?since=YYYY-MM-DD — which series changed or were reconfirmed since a date ($0.005). The cheap cache check.

## Machine manifests
- https://zaref.dev/.well-known/x402.json — x402 service manifest (endpoints, prices, network, facilitator)
- https://zaref.dev/.well-known/agent.json — agent card (skills, protocols, pricing)

Pricing: $0.005 USDC per series call, $0.01 per history or calculator call, $0.025 for /v1/all, paid per request via the x402 protocol on Base.
The catalog and /v1/public-holidays are free. A 402 response carries the payment requirements; x402-capable clients pay and retry automatically.