# Get Year End Fx Rate > Find and cite a Treasury/Fiscal Data or verified manual year-end USD FX rate with FBAR-style proof. Use for FBAR/foreign account year-end conversion, not yearly-average tax workflows. - Skill: `zztimur/get-year-end-fx-rate` (Agent Skill, multi-file: 16 files) - Install (CLI): `npx skillmds@latest add zztimur/get-year-end-fx-rate` - Raw SKILL.md: https://api.skillmd.com/api/skills/zztimur/get-year-end-fx-rate/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: zztimur (https://skillmd.com/u/zztimur) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/zztimur/get-year-end-fx-rate --- # Get Year-End FX Rate Find one year-end USD exchange rate, cite the source, and retain a proof workpaper. Return support documentation for FBAR-style conversion, not legal advice and not an official determination. ## Required Workflow Read `references/source-policy.md` before answering. It defines source priority, FBAR framing, proof requirements, rate direction, and refusal rules. Collect or infer: - Currency, preferably ISO 4217 code such as `COP`, `CAD`, or `EUR`. - Calendar year. - Output root, defaulting to `work/fbar-fx-rate-proof/`. Ask for clarification when the currency is ambiguous, for example `peso`, `dollar`, `pound`, or `ruble` without country/ISO code. Do not answer or create a workpaper for a year-end date that has not occurred yet. The CLI enforces this for both `lookup` and `manual`; `--retrieved`, `--proof-file`, and `--year-end-confirmed` are not override switches. ## Source Search Follow the source priority in `references/source-policy.md`: the Treasury Reporting Rates of Exchange dataset on Fiscal Data for the `YYYY-12-31` record date first, then another verifiable year-end government, central-bank, or bank source, then a user/preparer-supplied year-end rate. Never calculate averages and never reuse a yearly-average rate from `get-yearly-fx-rate`. If no verifiable year-end source is found, stop and ask the user or preparer for a custom year-end rate/source. Use `scripts/get_year_end_fx_rate.py` for deterministic Treasury lookup and workpaper generation. Before running either workflow, make sure the requested `YYYY-12-31` date has passed. If it has not, stop and tell the user the year-end rate cannot exist yet. Treasury/Fiscal Data lookup: ```bash python3 -B "/scripts/get_year_end_fx_rate.py" lookup \ --currency COP \ --year 2025 \ --output-root work/fbar-fx-rate-proof ``` Manual fallback after the agent has found or received a verifiable year-end source: ```bash python3 -B "/scripts/get_year_end_fx_rate.py" manual \ --currency COP \ --year 2025 \ --rate 3900.00 \ --rate-direction foreign-per-usd \ --source-title "Published year-end source title" \ --source-url "https://example.gov/rates/2025-year-end" \ --source-note "Source labels this as the 2025-12-31 or year-end rate; retrieved YYYY-MM-DD" \ --year-end-confirmed \ --proof-file "/path/to/source-screenshot-or-saved-page.pdf" \ --output-root work/fbar-fx-rate-proof ``` Use `foreign-per-usd` when the rate means one U.S. dollar equals the foreign-currency amount. Use `usd-per-foreign` only when the source means one unit of foreign currency equals the U.S. dollar amount. For manual workpapers, do not run the script until the source clearly supports a year-end rate. A saved local proof file is strongly preferred; the script accepts `--proof-file` only when it points to an existing regular file, then copies/hashes it. A folder, broken link, or missing path is not proof and stops before a packet is created. If no proof file is available, the workpaper records that limitation. `--source-note` is required and must explain why the source supports year-end use. `--source-url` must be a nonempty absolute `http://` or `https://` URL, and `--retrieved` cannot be later than today. Pass either `--proof-file` or a specific `--no-proof-file-reason` of at least 16 trimmed characters; never omit both and never pass both. When no proof file is available, the script records the reason and prints one `Caveat:` line in its final output. ## Treasury Map Maintenance The helper uses a Treasury row-to-ISO map because Fiscal Data rows use country/currency labels, not ISO codes. The package carries a frozen `tests/fixtures/treasury-2025-12-31.json` response so map validation remains deterministic. When `map-check --strict` reports an unexplained row, update `TREASURY_ROWS_BY_CODE`, an alternate row mapping, or the explicit exception registry; do not treat an unmapped code as Treasury unavailability. ```bash python3 -B "/scripts/get_year_end_fx_rate.py" map-check \ --year 2025 \ --currency AED \ --strict ``` Use `fetch-plan` before handing an API failure to another runtime. It prints the exact query URL and the deterministic offline replay command without making a network call: ```bash python3 -B "/scripts/get_year_end_fx_rate.py" fetch-plan \ --mode lookup --currency COP --year 2025 ``` If `lookup` or `map-check` exits 5, retain its `fetch_failure_class` (`tls-certificate-verification`, `dns-unavailable`, `timeout`, `http-error`, or `network-unavailable`), fetch the exact query URL with an available web tool, save the **raw JSON response** locally, then rerun with `--api-file `. TLS verification remains strict; use the runtime trust store or an existing `SSL_CERT_FILE`/`REQUESTS_CA_BUNDLE`, never an insecure bypass. Do not substitute a search snippet, screenshot, or manually copied rate. ## Proof Packet Create a retained workpaper folder for every answered rate: ```text work/fbar-fx-rate-proof/--/ ``` The folder must include: - `workpaper.json`, structured metadata for reuse by FBAR checking workflows. - `workpaper.md`, a small human-readable source note. - `workpaper.pdf`, a printable proof note with rate, source, caveats, and saved proof/hash details. - For Treasury lookups, a saved Fiscal Data API JSON response. - For manual sources, a saved screenshot/PDF/HTML/source artifact when one is available. Do not fill the printable PDF with links to the workpaper's own PDF/MD/JSON files. Those artifact links belong in the final chat output. Inside the PDF, list only saved source proof filenames or packet-relative paths and hashes. ## Final Answer Keep the user-facing answer concise and use this shape: ```markdown Rate: 1 USD = year-end () Reciprocal: 1 = USD Source: , , retrieved Proof: [workpaper.pdf]() Artifacts: [workpaper.pdf](), [workpaper.md](), [workpaper.json](), [source-proof-1.ext]() ``` Use Markdown links for every retained local artifact so the chat UI can expose them as clickable/downloadable files. Wrap link targets in angle brackets because workspace paths may contain spaces. Do not wrap proof paths in backticks. A Markdown link to a local absolute path is only clickable/downloadable when the chat client has direct filesystem access to this machine, true for a local desktop session but not for a hosted/remote session (for example, Claude Code on the web) where the user's browser cannot reach this container's filesystem. When running in such a session, also deliver each retained artifact using the host's file-delivery capability (for example, Claude Code's `SendUserFile` tool) in addition to the links above. Add one short caveat only when needed, such as `Treasury/Fiscal Data did not list this currency/year, so this uses a manual year-end source.` The script already emits the caveat when a manual source has no saved proof file. Do not call the rate official tax advice. ## Runtime And Validation The script uses only Python standard-library modules. Run it with `python3 -B` so an installed or read-only skill tree is never mutated by bytecode caches. `scripts/get_year_end_fx_rate.py` imports `scripts/_workpaper.py`, a generated, byte-identical vendored copy of the shared proof-packet engine (the same copy `get-yearly-fx-rate` carries, so both proof packets look the same). This installed skill runs standalone and never imports `workpaper-kit` at runtime. Do not hand-edit `scripts/_workpaper.py`. To change shared proof-packet behavior in the source repository, edit `workpaper-kit/workpaper.py` and let the pre-commit hook or `workpaper-kit/sync.sh` regenerate both FX skills; the canonical kit is not included in standalone installs. After changing this skill, run: ```bash python3 -B "/scripts/get_year_end_fx_rate.py" self-test python3 -B "/tests/run_regressions.py" python3 -S skill-forge/scripts/inspect_skill_package.py "" --json --strict ``` If the Anthropic skill-creator `quick_validate.py` is installed, run it against `` too. If Claude tooling is available, also run: ```bash claude plugin validate --strict "" ``` ## Package Compatibility This is a single multi-agent package. The root `SKILL.md`, `references/`, and `scripts/` are the source of truth. `agents/openai.yaml` is OpenAI/Codex discovery metadata only. `.claude-plugin/plugin.json` and `commands/get-year-end-fx-rate.md` are Claude adapters only; do not duplicate workflow or source policy in adapter files.