zaref Python SDK

pip install zaref gives you the South African reference data API as a small, typed Python client. The catalog, public holidays and the VAT calculator work with no wallet and no crypto dependencies, so the first call succeeds in seconds.

Paid endpoints (repo rate, fuel prices, tax tables and the rest) need pip install "zaref[pay]" and a Base wallet funded with USDC. Payment happens automatically over the x402 protocol, about two seconds per call. A missing wallet raises a clear error naming the price; invalid input is rejected for free before any payment.

Quickstart

pip install zaref

from zaref import Zaref
z = Zaref()

z.public_holidays()          # free, no wallet
z.vat(amount=1000)           # free VAT calculator
z.list_series()              # everything available

# paid endpoints: pip install "zaref[pay]", fund a Base wallet
z = Zaref(private_key="0x...")    # or set ZAREF_PRIVATE_KEY
z.repo_rate()                # 7.0
z.income_tax(annual=480000)  # composed from the SARS tables
z.batch(["repo-prime", "vat", "cpi", "fuel-prices"])  # four series, one payment

How agents pay

No account, no API key. Paid endpoints reply HTTP 402 with exact payment requirements; an x402 client pays USDC on Base (about two seconds to settle) and retries automatically. Invalid input is rejected free with a 400 before any payment is challenged. See the x402 quickstart.

Questions

How do I install the zaref Python client?

pip install zaref. That gives the free surface (catalog, public holidays, VAT calculator) with no wallet and no crypto dependencies. For paid endpoints, pip install "zaref[pay]" and configure a Base wallet.

Does the Python SDK need an API key?

No. There are no accounts or keys. Free endpoints just work; paid endpoints authenticate by payment over x402 using a Base wallet funded with USDC.

What happens if I call a paid endpoint without a wallet?

The client raises PaymentRequired naming the endpoint and its price, not a stack trace. Invalid input raises InvalidRequest carrying the server's accepted values, and costs nothing.

Related

South African repo and prime rate API South Africa fuel price API SARS income tax tables API South Africa VAT API and free calculator South African public holidays API