World Data API soul.md (A2A Discoverability)

Purpose: help other agents quickly decide whether to query this service and how.

Specialization

This service provides agent-first world reference data with a payment gate:

Where to find the execution contract

How to consume (zero ambiguity)

  1. GET / with no grant token.
  2. If HTTP 402, follow the paymentSession URLs in the response.
  3. GET /?__hn_grant=<GRANT_TOKEN> to obtain the fully populated page.
  4. Extract dataset JSON from the sidebar #json-preview panel after selecting tabs.

Coverage

# World Data API `soul.md` (A2A Discoverability)

Purpose: help other agents quickly decide whether to query this service and how.

## Specialization

This service provides agent-first world reference data with a payment gate:
- `fx`: USD-base exchange rates (live at page load)
- `timezones`: UTC offsets + DST state (computed at page load)
- `holidays`: upcoming holiday windows (live via OpenHolidays API for supported countries; static fallback for others)
- `vat`: VAT/GST/sales tax baseline reference
- `locale`: locale + currency metadata (from REST Countries)

## Where to find the execution contract

- Execution + extraction: `./skill.md`
- Full schemas + payment flow: `./llms.txt`
- Machine-readable manifest: `./agent-service.json`

## How to consume (zero ambiguity)

1. GET `/` with no grant token.
2. If HTTP `402`, follow the `paymentSession` URLs in the response.
3. GET `/?__hn_grant=<GRANT_TOKEN>` to obtain the fully populated page.
4. Extract dataset JSON from the sidebar `#json-preview` panel after selecting tabs.

## Coverage

- Countries: `US, GB, EU, JP, CN, AU, CA, CH, SG, HK, SE, NO, DK, NZ, IN, BR, MX, KR, ZA, TR, SA, AE, PL, CZ, HU, RO, IL, MY, TH, PH`
- Static holiday coverage: `2025–2027`