# usaref Government Reference Data History

> usaref Government Reference Data History is a paid API for AI agents from usaref.dev, paid per call via x402, $0.005/call, status unknown (last checked 2026-09-13).

Returns the historical time-series of a specific government reference data series (e.g. policy rate, VAT, minimum wage) for a given North American country

## Facts

- Endpoint: GET https://usaref.dev/v1/:country/:series/history
- Price: $0.005/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/usaref-government-reference-data-history-f05f690d
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_H4_fgozhx2JLUfTK_-Drk

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability usaref-government-reference-data-history-f05f690d
```

Example prompt: Can you pull the full policy-rate history for Mexico from usaref so I can see how their central bank rate has changed over time?

## When to prefer this

Use this endpoint when you need historical time-series data for a specific government reference metric (tax rates, wages, interest rates, CPI, holidays) for a North American or Central American country. Prefer this over the snapshot endpoint when you need the full history rather than just the current value. Best suited for compliance checks, economic analysis, or policy tracking tasks.

## Known failure modes

- Invalid country code returns 400 or 404 — only ca, cr, do, gt, hn, mx, pa, sv, us are supported
- Invalid series ID returns 400 or 404 — only policy-rate, vat, minimum-wage, public-holidays, cpi, corporate-tax, income-tax are valid
- stale:true in response indicates data is past its expected update cycle and may be outdated
- Payment failure (x402) if USDC payment is not correctly included
- Network timeout or 5xx if the upstream data source is unavailable

## How this service works

Government reference data series

## Output

A JSON object containing the country code, series identifier, current value, unit, effective_from date, last_confirmed date, source attribution (name and URL), a staleness flag, optional notes, and optional rate component breakdowns where applicable (e.g. stacked statutory levies).

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "pathParams": {
     "type": "object",
     "required": [
      "country",
      "series"
     ],
     "properties": {
      "series": {
       "enum": [
        "policy-rate",
        "vat",
        "vat-registration-threshold",
        "minimum-wage",
        "public-holidays",
        "cpi",
        "corporate-tax",
        "withholding-tax",
        "statutory-interest",
        "income-tax",
        "social-contributions",
        "fx-reference",
        "sales-tax"
       ],
       "type": "string",
       "description": "Reference series id"
      },
      "country": {
       "enum": [
        "bs",
        "ca",
        "cr",
        "do",
        "gt",
        "hn",
        "mx",
        "pa",
        "sv",
        "us"
       ],
       "type": "string",
       "description": "ISO country code"
      }
     }
    },
    "queryParams": {
     "type": "object",
     "properties": {},
     "additionalProperties": false
    }
   },
   "additionalProperties": false
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/usaref-government-reference-data-history-f05f690d/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from usaref.dev](https://www.zero.xyz/host/usaref.dev/llms.txt)