Metadata-Version: 2.4
Name: zaref
Version: 0.1.0
Summary: South African reference data for Python: verified, cited, pay-per-call. No API key.
Project-URL: Homepage, https://zaref.dev
Project-URL: Documentation, https://zaref.dev/docs
Project-URL: API, https://zaref.dev/openapi.json
Author: zaref
License-Expression: MIT
Keywords: api,reference-data,repo-rate,sarb,sars,south-africa,tax,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Requires-Dist: requests>=2.28
Provides-Extra: pay
Requires-Dist: eth-account>=0.11; extra == 'pay'
Requires-Dist: x402[evm]>=2.16; extra == 'pay'
Description-Content-Type: text/markdown

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

```bash
pip install zaref
```

## Try it with no wallet

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

```python
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](https://x402.org) with a Base wallet funded with USDC. No account, no key: payment is the authentication.

```bash
pip install "zaref[pay]"
```

```python
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:

  ```python
  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.
