Quickstart

1. Free, right now

Nothing below needs a key, a wallet or a header. Start here to see what exists:

# Every country and series this service holds
curl https://latamref.dev/catalog

# A full public-holiday calendar, cited to its official source
curl https://latamref.dev/public/ar/holidays

# What changed recently, and how recently each value was re-verified
curl https://latamref.dev/v1/changes

Public holidays are free for every country, permanently. So are /catalog, /v1/changes, /settlement-conventions, /openapi.json and /llms.txt.

One country is completely free — evaluate the paid surface on it

Every BR series on latamref is free: current value, history, ?as_at=, full citations. It is the same surface every paid country sits behind, so you can exercise it end to end — and check our citations against the official sources — before paying a cent:

curl https://latamref.dev/v1/br/policy-rate
curl https://latamref.dev/v1/br/vat/history
curl 'https://latamref.dev/v1/br/corporate-tax?as_at=2024-06-30'

2. A paid call, and what it costs

Paid endpoints answer 402 Payment Required until they are paid. The 402 is not an error — it is the price quote, and it is machine-readable:

curl -i https://latamref.dev/v1/br/policy-rate

HTTP/1.1 402 Payment Required
payment-required: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQYXltZW50...

That header is base64-encoded JSON. Decode it to see the price, the asset, the chain and the address to pay:

curl -sD- -o /dev/null https://latamref.dev/v1/br/policy-rate \
  | grep -i '^payment-required:' | cut -d' ' -f2- | base64 -d | jq .

The challenge is also mirrored into the response body, so a client that cannot read headers is not locked out. Amounts are in the asset's base units — USDC has 6 decimals, so 1000 means $0.001.

3. Two ways to pay

Option A — x402, for agents with a wallet

Pay per call in USDC on Base. No account exists to create. A client library does the 402 → sign → retry loop for you:

npm install @x402/fetch

import { wrapFetchWithPayment } from "@x402/fetch";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const wallet  = createWalletClient({ account, chain: base, transport: http() });
const fetchWithPay = wrapFetchWithPayment(fetch, wallet);

const res  = await fetchWithPay("https://latamref.dev/v1/br/policy-rate");
const data = await res.json();
console.log(data.value, data.source.url);   // the number, and where it came from

On success the settlement receipt comes back in the PAYMENT-RESPONSE header. You sign a payment authorisation, not a blank cheque: the amount is fixed by the challenge.

Option B — an API key, for people and businesses

Buy prepaid credit by card on the pricing page and send the key as a header. No wallet, no crypto, and you get an invoice:

curl -H 'X-API-Key: YOUR_KEY' https://latamref.dev/v1/br/policy-rate

import requests

r = requests.get(
    "https://latamref.dev/v1/br/policy-rate",
    headers={"X-API-Key": "YOUR_KEY"},
    timeout=15,
)
r.raise_for_status()
d = r.json()
print(d["value"], d["unit"], "as at", d["effective_from"])
print("source:", d["source"]["url"])

Credit does not expire and there is no subscription. Calls that fail because of our error are not deducted. One key works on all seven regional services — credit bought on afriref.dev serves euroref, asiaref, latamref, usaref, mearef and ausref too: same key, same balance.

4. What comes back

Every paid value carries the evidence with it. The citation is the product — a number without one is what we are trying to replace:

{
  "country": "BR",
  "series": "policy-rate",
  "value": 15.75,
  "unit": "percent",
  "effective_from": "2026-07-14",   // when this value took legal effect
  "last_confirmed": "2026-07-24",   // when we last re-read the official source
  "source": {
    "name": "...",                  // the instrument, named
    "url":  "https://..."           // the document itself
  },
  "confidence": "primary",          // how the value was obtained
  "stale": false                    // past its expected update cycle?
}

5. Point-in-time reads

Add ?as_at=YYYY-MM-DD to get the value that was in force on a date, rather than today's:

curl 'https://latamref.dev/v1/br/policy-rate?as_at=2025-06-30'

If we hold no value in force on that date, you get a free 422 explaining what we do hold — not the nearest value, and not a guess.

6. Refusals — read this before treating one as a bug

The service refuses questions it cannot answer honestly, and refusals are always free: they are validated before the payment gate, so you are never charged for a question we know we cannot answer well.

The 422 reasons you are most likely to meet:

A refusal names the specific blocking reason and tells you what you can do instead. Treat it as data, not as failure.

7. Alerts — we watch the official sources so you don't have to

Reference values fail silently. A number that stood for years moves in one budget speech, and every hard-coded copy of the old value becomes wrong overnight — nothing crashes, nothing warns. It just starts being wrong.

A worked example from our own accuracy record: South Africa's compulsory VAT registration threshold was R1 million for roughly seventeen years — long enough to be baked into onboarding checks, software defaults and training material. On 1 April 2026 it became R2.3 million. A system with an alert learned within a day; a system with a lookup API didn't know to ask.

We fetch and hash every cited source daily, so we know when a value changes, not just what it is:

# HMAC-signed webhook the moment a series you watch changes
curl -X POST https://latamref.dev/alerts \
  -H 'content-type: application/json' \
  -d '{"url": "https://your-app.example/hooks/refdata",
       "series": ["za/vat-registration-threshold", "ng/policy-rate", "ke/*"]}'

1–20 patterns per subscription, wildcards per country (ke/*). Payloads are signed with HMAC-SHA256 in the x-afriref-signature header; the signing secret is returned once at registration. Registering is free, and so are your first 3 deliveries — after that each delivery deducts one call from your API key (pass api_key at registration). Prefer polling? The change feed is free: /v1/changes.

8. Rate limits

Free, unauthenticated discovery routes are throttled per IP; paid data routes are not throttled at all. Current limits and what they cover are published on /status.

9. If you are an agent, not a person

Something wrong?

If a value disagrees with its official source, send us the instrument — corrections with a primary source are acted on and credited on the accuracy record. api@3l-groupconsulting.co.za