# 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.

- **Type:** Skill
- **Install:** `agentstack add skill-zztimur-skills-to-pay-the-bills-get-year-end-fx-rate`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [zztimur](https://agentstack.voostack.com/s/zztimur)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [zztimur](https://github.com/zztimur)
- **Source:** https://github.com/zztimur/skills-to-pay-the-bills/tree/main/get-year-end-fx-rate

## Install

```sh
agentstack add skill-zztimur-skills-to-pay-the-bills-get-year-end-fx-rate
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 "/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 "/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 "/scripts/get_year_end_fx_rate.py" map-check \
  --year 2025 \
  --currency AED \
  --strict
```

If `lookup` or `map-check` exits 5, fetch the exact API query URL shown in the error with an available web tool, save the **raw JSON response** locally, then rerun the same command with `--api-file `. Do not substitute a search snippet, screenshot, or manually copied rate. The packet records whether its JSON came from a live API fetch or a supplied local file.

## 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. Use `python3` unless the active environment provides `python`.

`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 "/scripts/get_year_end_fx_rate.py" self-test
python3 "/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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [zztimur](https://github.com/zztimur)
- **Source:** [zztimur/skills-to-pay-the-bills](https://github.com/zztimur/skills-to-pay-the-bills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zztimur-skills-to-pay-the-bills-get-year-end-fx-rate
- Seller: https://agentstack.voostack.com/s/zztimur
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.