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.

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

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

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