zaref 0.1.0

South African reference data for Python: verified, cited, pay-per-call. No API key.

zaref

South African reference data for Python. Repo rate, fuel prices, tax tables, ZARONIA, FX, bond yields, wages, grants, plus calculators. Verified daily against the official sources, cited on every response, paid per call in USDC. No API key, no signup, no monthly plan.

pip install zaref

Try it with no wallet

The catalog, public holidays and the VAT calculator are free and need nothing set up:

from zaref import Zaref

z = Zaref()

z.public_holidays()          # every SA public holiday this year
z.vat(amount=1000)           # add VAT at the current rate
z.list_series()              # everything available

Paid endpoints

Everything else costs a fraction of a cent, paid automatically over the x402 protocol with a Base wallet funded with USDC. No account, no key: payment is the authentication.

pip install "zaref[pay]"

from zaref import Zaref

z = Zaref(private_key="0x...")     # or set ZAREF_PRIVATE_KEY

z.repo_rate()                      # 7.0
z.series("fuel-prices")            # cited JSON with source_url + effective_date
z.income_tax(annual=480000)        # composed from the current SARS tables
z.batch(["repo-prime", "vat", "cpi", "fuel-prices"])   # four series, one payment
z.changes(since="2026-07-01")      # what moved, before you re-fetch

Every paid call returns in about two seconds. A call costs less than the tokens an agent would burn finding and parsing the official source itself.

Honest by construction

• Every response carries source_url, effective_date, last_confirmed and a stale flag. A value we cannot verify is null with a note, never a guess.

• Invalid input is rejected for free, before any payment. A bad parameter raises InvalidRequest carrying the accepted values, and costs nothing:

  from zaref import Zaref, InvalidRequest
  try:
      Zaref(private_key="0x...").calc("cgt", gain=100000, type="bogus")
  except InvalidRequest as e:
      print(e.accepted_values)   # ['individual', 'company', 'trust']
  

• A paid call without a wallet raises PaymentRequired naming the endpoint and price, not a stack trace.

What's covered

33 verified series, 29 calculators, task-shaped answers (payroll, wage checks, working days), two live feeds (government tenders, crypto ZAR prices), history with point-in-time as_at, a batch endpoint and change-alert webhooks. Full list: z.catalog() or https://zaref.dev/docs.

Disclaimer

Independent data service, not affiliated with any South African government entity. Every value carries its official source; verify against the source for legal or financial use.