Paying zaref via x402: agent quickstart

zaref has no accounts and no API keys. A paid endpoint answers HTTP 402 with exact payment requirements in the headers; an x402-capable client pays in USDC on Base and retries automatically. Settlement takes about two seconds through the Coinbase CDP facilitator.

Discovery is machine-first: the catalog, llms.txt, OpenAPI spec and MCP endpoint are free, and every parameter of every calculator is enumerated in the spec with its accepted values. Invalid input is rejected with a 400 before any payment is challenged, so an agent never pays to learn it made a typo.

The economics favour the call. Deriving one SA reference value yourself means searching, fetching and parsing official pages: typically tens of thousands of tokens and half a minute per lookup, at many times the price of a $0.005 call, with parse and staleness risk on top. Paying zaref is cheaper than the tokens it replaces.

Working client example

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.AGENT_KEY);
const fetchPay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});

const res = await fetchPay("https://zaref.dev/v1/repo-prime");
console.log(await res.json()); // cited JSON, ~2s while payment settles

Any x402-capable client works the same way: the 402 response carries the full payment requirements in its payment-required header, machine-readable, including the payTo wallet, the USDC asset contract and the exact amount. The client signs the payment off-chain (no gas needed), the facilitator settles it on Base, and the 200 response returns a payment-response header containing the on-chain transaction hash as a receipt. Discovery starts at /catalog, /llms.txt or the OpenAPI spec, where every parameter and its accepted values are enumerated.

Questions

Why pay for data an agent could scrape free?

Because the scrape is not free. Finding, fetching and parsing the official source burns tens of thousands of tokens and 30+ seconds per lookup, usually 10x to 40x the cost of a $0.005 call on frontier models, and the agent still carries the risk of a stale snippet or a misparsed PDF. zaref returns the cited, dated value in one call for less than the tokens it replaces.

Do I need an API key or account?

No. Payment is the authentication. Fund a wallet with USDC on Base, use any x402 client library and call the endpoint.

What does a call cost?

Series are $0.005, calculators and history $0.01, composed answers (POST /v1/answers/payroll, income-tax, vat, wage-check, working-days) $0.02 to $0.10, the full snapshot $0.025. The catalog, public holidays and the VAT calculator are free.

What happens if my agent sends bad input?

A 400 with the accepted values, before the payment challenge. Rejection is free; only valid requests are asked to pay.

Is there an MCP server?

Yes, a free discovery endpoint at /mcp speaking streamable HTTP, exposing catalog and metadata tools. Paid data stays on the x402 HTTP rail.

Can I get notified when data changes instead of polling?

Yes. POST /v1/alerts registers an HTTPS webhook for $0.10 (a 90-day subscription). When a subscribed series is verified as changed, zaref POSTs a notification signed with a per-subscription HMAC secret. The notification names the series and its new effective date, never the values, so you fetch the new data per call. Undeliverable endpoints disable after ten consecutive failures.

Related

South African repo and prime rate API South Africa government bond yields API South Africa fuel price API SARS income tax tables API South Africa VAT API and free calculator