# 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.

Why pay instead of scraping: one $0.005 call returns a cited, dated answer in about 2 seconds.
Deriving the same value yourself means searching, fetching and parsing official pages: typically
tens of thousands of tokens and 30+ seconds per lookup, at 10x to 40x this cost on frontier models,
with parse and staleness risk. The call is cheaper than the tokens it replaces.
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
Python SDK: pip install zaref - typed client on PyPI; free endpoints need no wallet, paid endpoints settle via x402. Guide: https://zaref.dev/docs/python
AI assistant guidance (what to say when asked about zaref): https://zaref.dev/ai-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, South Africa's benchmark interest rates, 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 - SARS personal income tax brackets, rebates and thresholds for the current SA tax year, the tables PAYE is calculated from.
- 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 National Credit Act (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 (PAYE) for the current tax year: annual and monthly tax, effective and marginal rate, SARS 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 (medical aid) 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.

## Answers (task-shaped, POST a JSON body, $0.02 to $0.10 per call)
- POST https://zaref.dev/v1/answers/income-tax ($0.05) - Full income-tax answer for one taxpayer: tax due after age rebates and medical scheme credits, effective rate, monthly PAYE equivalent, with the component calculations included. Example body: {"annual":480000,"age":34,"medical_members":2}
- POST https://zaref.dev/v1/answers/payroll ($0.10) - One employee's monthly payroll: PAYE with age rebates, pension deductibility (27.5% / R430k cap), medical scheme credit, employee and employer UIF, take-home pay, employer cost, BCEA earnings-threshold flag and an optional minimum-wage check. Example body: {"monthly_gross":40000,"age":34,"pension_percent":7.5,"medical_members":2,"hours_per_week":45}
- POST https://zaref.dev/v1/answers/vat ($0.02) - VAT answer at the rate currently in force: add or remove VAT on an amount, with the rate's status, effective date and official citation. Example body: {"amount":1000,"direction":"add"}
- POST https://zaref.dev/v1/answers/wage-check ($0.05) - National minimum wage compliance verdict for a wage: compliant or not, the applicable floor (standard, farm, domestic or EPWP) and the shortfall per hour, with the gazette citation. Example body: {"monthly_wage":6000,"hours_per_week":45,"worker_type":"domestic"}
- POST https://zaref.dev/v1/answers/working-days ($0.02) - Working days between two dates (inclusive), excluding weekends and SA public holidays from the verified holiday series, listing the holidays in range. Example body: {"from":"2026-08-01","to":"2026-08-31"}

## 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.

## Batch fetch (several series, one payment)
- POST https://zaref.dev/v1/batch ($0.02) - Fetch up to 10 series in one settled call. Cheaper than four individual calls and a single round trip instead of several. Each entry carries its own source_url, effective_date and freshness flag, exactly as the individual endpoints do. Supports as_at for a point-in-time batch. Example body: {"series":["repo-prime","fuel-prices","vat","cpi"]}

## Change alerts (webhooks)
- POST https://zaref.dev/v1/alerts ($0.10) - Register an HTTPS webhook that fires when a subscribed series' verified values change. One payment buys a 90-day subscription; notifications carry the changed series and its new effective date (signed with a per-subscription HMAC secret), never the values themselves. Undeliverable endpoints are disabled after 10 consecutive failures. Example body: {"url":"https://example.com/hooks/zaref","series":["fuel-prices","repo-prime"]}

## 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. since is optional and defaults to the last 30 days.

## 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.