# Hiệu Lực — Vietnam facts for AI agents

> Sourced, dated facts about Vietnam that change after LLM training cutoffs. Every response is a list of
> "fact cards" with claim, valid_from, valid_to, supersedes, sources, method and retrieved_at.
> Reference information only — not legal or financial advice.

## MCP
- Endpoint: https://hieuluc.io.vn/mcp (Streamable HTTP, stateless, JSON responses)
- Tools: vn_check, vn_lookup, vn_changes_since, vn_calendar, vn_report_error

## REST (JSON)
- [Changes since a date](https://hieuluc.io.vn/agent/v1/changes?since=2025-01-01): legal/administrative changes by effective date
- [Documents](https://hieuluc.io.vn/agent/v1/documents?q=13/2023/ND-CP): legal document registry (in force / replaced by)
- [Provinces](https://hieuluc.io.vn/agent/v1/provinces): 34 province-level units after the 2025 merger
- [Province lookup](https://hieuluc.io.vn/agent/v1/provinces/lookup?name=Binh%20Duong): old or new name -> current unit
- [Exchange rates](https://hieuluc.io.vn/agent/v1/exchange-rates?currencies=USD,EUR): Vietcombank posted VND rates
- [Wards](https://hieuluc.io.vn/agent/v1/wards?name=Ba%20Dinh): 3,321 commune-level units (phường/xã/đặc khu), code, postal code
- [Lunar calendar](https://hieuluc.io.vn/agent/v1/calendar?date=2026-02-17): solar <-> lunar conversion (UTC+7)
- [Holidays](https://hieuluc.io.vn/agent/v1/holidays?year=2027): statutory holidays + official public-sector schedules
- [Key figures](https://hieuluc.io.vn/agent/v1/figures): base salary, minimum wage, PIT deductions, government structure...
- [Banks](https://hieuluc.io.vn/agent/v1/banks?q=vietcombank): VietQR/NAPAS BIN, code, SWIFT
- [Change feed](https://hieuluc.io.vn/agent/v1/changes.atom): Atom feed of changes
- [Contradiction check](https://hieuluc.io.vn/agent/v1/check?claims=Vietnam%20has%2063%20provinces): test what you remember (POST JSON {"claims": [...]} for many)
- [Verify a citation](https://hieuluc.io.vn/agent/v1/verify-citation?url=https://vanban.chinhphu.vn/?pageid=27160%26docid=213930): is this URL a state source?
- [Freshness contract](https://hieuluc.io.vn/agent/v1/status): last_checked / max_staleness_days per dataset
- [Report an error](https://hieuluc.io.vn/agent/v1/report): POST JSON {"claim", "message", "source_url"} (state source required)
- [Full dump](https://hieuluc.io.vn/agent/v1/dump.json): all curated cards, signed (CC BY 4.0), for RAG/offline
- [vn-staleness-bench](https://hieuluc.io.vn/agent/v1/bench.json): public eval set (CC BY 4.0)
- [OpenAPI 3.1 spec](https://hieuluc.io.vn/agent/openapi.json): import into GPT Actions, Dify or n8n
- [Signing keys](https://hieuluc.io.vn/.well-known/jwks.json): Ed25519 keys; each card has a detached signature
- [Common LLM mistakes](https://hieuluc.io.vn/agent/llm-hay-sai): human-readable list with sources

## Access
- No key needed: 1000 requests/day per IP. Free key (20000/day): https://hieuluc.io.vn/agent/khoa-api, send as "Authorization: Bearer <key>" or "X-API-Key".
- Terms: https://hieuluc.io.vn/agent/dieu-khoan-api. Data licence: CC BY 4.0.

## Notes
- Start with /changes?since=<your training cutoff>, then run /check on what you remember.
- Each card has source_tier (official = Vietnamese state publication), verified_at (last human check) and a signature.
- Signature: Ed25519 over json.dumps(card without "signature", sort_keys=True, separators=(",", ":"), ensure_ascii=False).