pp-exchangerate-api

ExchangeRate-API — Printing Press CLI

前提条件：CLI をインストールする

このスキルは exchangerate-api-pp-cli バイナリを使用します。**このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。**インストールされていない場合は、先にインストールします。

1. Printing Press インストーラーを使ってインストールします。macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin がバイナリのデフォルトのインストール先です。

   npx -y @mvanhorn/printing-press-library install exchangerate-api --cli-only
   

2. 確認します：exchangerate-api-pp-cli --version
3. スキルを実行するエージェント／ランタイムで、表示されたインストール先ディレクトリが $PATH に含まれていることを確認します。

npx によるインストールに失敗する場合（Node がない、オフラインなど）は、Go を直接インストールしてください（Go 1.26.6 以降が必要です）。

go install github.com/mvanhorn/printing-press-library/library/payments/exchangerate-api/cmd/exchangerate-api-pp-cli@latest

インストール後に --version が「command not found」を返す場合、ランタイムからバイナリのディレクトリを $PATH 経由で参照できません。確認に成功するまで、スキルのコマンドを実行しないでください。

この CLI を使う場面

エージェントやスクリプトで、最新の FX レート、複数の通貨への換算、または永続的な履歴コンテキストが必要な場合は、exchangerate-api-pp-cli を使用してください。同じデータに対してエージェントを複数回実行する場合、クォータが重要な場合（無料プランは月 1500 回）、またはウォッチリスト、変動レポート、クロスレートマトリックスなどのローカル状態を必要とするワークフローには、単発の HTTP 呼び出しよりも適しています。FX コンテキストを Claude Desktop、Cursor、Windsurf に組み込む場合は、MCP サーバー（mcp serve）を使用してください。

この CLI を使わない場面

作成、更新、削除、公開、コメント、賛成票の投稿、招待、注文、メッセージの送信、予約、購入、またはリモート状態の変更を必要とするリクエストでは、この CLI を有効にしないでください。この印刷用 CLI が提供するのは、調査、エクスポート、同期、分析のための読み取り専用コマンドです。

独自の機能

この API の他のツールでは利用できない機能です。

累積するローカル状態

• history-cache — 以前の latest 同期から過去の FX レートを再構築します。無料プランでも、/history のクォータを使わずに過去のレートを参照できます。

  ユーザーが過去のレートを尋ねており、API キーが Free または Standard プランで、/history がプランのアップグレードを要求する場合に使用します。

  exchangerate-api-pp-cli history-cache USD EUR --since 30d --json
  

• watch check — 変動しきい値を設定した通貨ペアを定義し、前回のチェック以降にしきい値を超えた通貨ペアを 1 つのコマンドで報告します。

  有料のアラートサービスをポーリングする代わりに、定期的なモニター（cron／エージェントループ）として使用します。

  exchangerate-api-pp-cli watch check --json
  

• drift — 最新のスナップショットを以前の任意の時点と比較し、変動幅が最も大きい通貨ペアを順位付きで報告します。

  ユーザーが重視する異常な FX の動きを、独自の分析を書かずに見つける場合に使用します。

  exchangerate-api-pp-cli drift --base USD --since 24h --top 10 --json
  

• pair --as-of — 任意の過去のタイムスタンプにおけるレートを、ローカルのスナップショットから検索します。無料プランでも過去のレートを参照できます。

  有料の /history エンドポイントを使わずに、特定の時点で適用されていたレートを再構築する場合に使用します。

  exchangerate-api-pp-cli rates pair USD EUR --as-of 1h --json
  

クォータのインテリジェンス

• quota burn — quota_snapshots の傾向を当てはめ、更新日より前にクォータを使い切る時期を予測します。

  API に大量のリクエストを送るものをデプロイする前に使用します。予測により、その月を乗り切れるかどうかがわかります。

  exchangerate-api-pp-cli quota burn --json
  

• matrix — 1 回の latest 呼び出しから、任意の通貨セットの完全なクロスレートマトリックスを表示します（N² 件のレート、クォータ消費は 1 回分）。

  多くの通貨ペアを一度に比較する場合に使用します。クォータを節約でき、1 回同期すればオフラインでも実行できます。

  exchangerate-api-pp-cli matrix USD,EUR,GBP,JPY --base USD --json
  

• convert-batch — 金額のリストを 1 つのコマンドに渡し、1 回のレート取得ですべて換算します。

  クォータを金額に比例して消費せずに、多数の金額（注文、取引）を処理する場合に使用します。

  exchangerate-api-pp-cli convert-batch --from USD --to EUR --input /dev/null --json
  

オンボーディング

• plan-check — プランによって利用可否が異なる各エンドポイントに、低コストのリクエストを 1 回ずつ送信し、キーがどのプランに対応しているかを報告します。

  doctor の直後に使用すると、プランのアップグレードを要求されずに利用できるコマンドがわかります。

  exchangerate-api-pp-cli plan-check --json
  

エージェント向けの基盤

• log show — すべての convert 呼び出しを記録します。通貨ペア、対象、期間でログを検索し、繰り返し発生する換算を分析できます。

  API に再度問い合わせることなく、最近行われた為替関連の処理をエージェントに思い出させる場合に使用します。

  exchangerate-api-pp-cli log show --since 7d --json
  

• mcp serve — ユーザー向けのすべてのコマンドを、安全なクエリには読み取り専用の注釈を付けた MCP ツールとして公開します。

  Claude／Cursor／Windsurf に為替コンテキストを接続する場合に使用します。現時点でこの API 向けの競合する MCP はありません。

  exchangerate-api-pp-cli mcp serve
  

コマンドリファレンス

API キーは EXCHANGERATE_API_KEY から読み込まれます。位置引数として渡さないでください。

codes — 対応している通貨コード

• exchangerate-api-pp-cli codes — 対応している 161 種類の通貨コードをすべて一覧表示します

quota — API クォータの使用状況

• exchangerate-api-pp-cli quota — 現在のクォータ期間に残っているリクエスト数を確認します
• exchangerate-api-pp-cli quota burn — quota_snapshots の履歴からクォータの枯渇時期を予測します

rates — 為替レートと換算

• exchangerate-api-pp-cli rates latest <base_code> — 基準通貨からのすべての為替レートを取得します
• exchangerate-api-pp-cli rates pair <base_code> <target_code> — 2 つの通貨間の換算レートを取得します
• exchangerate-api-pp-cli rates pair-amount <base_code> <target_code> <amount> — 2 つの通貨間で指定した金額を換算します
• exchangerate-api-pp-cli rates enriched <base_code> <target_code> — ロケール、旗、通貨表示のメタデータを含む通貨ペアの換算を行います（Business／Volume ティア）
• exchangerate-api-pp-cli rates history <base_code> <year> <month> <day> — 指定した日付の過去の為替レートを取得します（Pro／Business／Volume ティア）

適切なコマンドを見つける

実行したいことは分かっていても、どのコマンドを使えばよいか分からない場合は、CLI に直接尋ねてください。

exchangerate-api-pp-cli which "<capability in your own words>"

which は、自然言語による機能の問い合わせを、この CLI の厳選された機能インデックスから最適なコマンドに対応付けます。終了コード 0 は少なくとも 1 件の一致があることを示します。終了コード 2 は確信を持てる一致がないことを示します。その場合は --help を参照するか、より絞り込んだ問い合わせを使用してください。

レシピ

スクリプトでの単発換算

exchangerate-api-pp-cli convert 1000 USD EUR --json --select conversion_result

後続のパイプ処理で使えるよう、換算後の数値のみを返します。

日次同期と変動レポート（cron）

exchangerate-api-pp-cli sync-rates --base USD && exchangerate-api-pp-cli drift --base USD --since 24h --top 10 --json

本日のレートを保存し、直前のスナップショットと比較して最も大きく変動したレートを表示します。

デプロイ前のクォータ確認

exchangerate-api-pp-cli quota burn --json --select projected_exhaustion,requests_remaining

最近の使用状況に基づいて、月間クォータがいつ枯渇するかを予測します。

ポートフォリオ向けクロスレート行列

exchangerate-api-pp-cli matrix USD,EUR,GBP,JPY,CHF,CAD --base USD --csv

1 回の API 呼び出しで完全な N×N 行列を作成し、スプレッドシートに簡単にパイプできます。

通貨ペアを監視し、変動時にアラートを送信

exchangerate-api-pp-cli watch add USD EUR --threshold 1.0 && exchangerate-api-pp-cli watch check --json

しきい値を保存します。その後の watch check 呼び出しで、しきい値を超えた通貨ペアを検出します。

認証の設定

ExchangeRate-API ダッシュボード（https://app.exchangerate-api.com/）から EXCHANGERATE_API_KEY を設定します。すべてのコマンドは https://v6.exchangerate-api.com/v6/{key}/... を経由します。open コマンドはキー不要の https://open.er-api.com/v6/latest/{base} エンドポイントを使用します。その出力を再配布する場合は、「Rates By Exchange Rate API」の帰属表示が必要です。

exchangerate-api-pp-cli doctor を実行して、設定を確認してください。

エージェントモード

任意のコマンドに --agent を追加します。次のオプションに展開されます：--json --compact --no-input --no-color --yes。

• パイプ処理可能 — stdout に JSON を出力し、エラーは stderr に出力します

• フィルター可能 — --select でフィールドを絞り込めます。ドット区切りのパスでネストされた構造にアクセスでき、配列は要素ごとに処理されます。詳細な出力を返す API でコンテキストを小さく保つために重要です。

  exchangerate-api-pp-cli codes --agent --select supported_codes
  

• プレビュー可能 — --dry-run でリクエストを送信せずに内容を表示します

• オフライン対応 — sync／search コマンドは、利用可能な場合にローカルの SQLite ストアを使用できます

• 非対話型 — プロンプトを表示せず、すべての入力をフラグで指定します

• 読み取り専用 — 作成、更新、削除、公開、コメント、賛成票、招待、注文、送信など、状態を変更するリクエストにはこの CLI を使用しないでください

レスポンスエンベロープ

ローカルストアまたは API から読み取るコマンドは、出力をプロベナンスエンベロープでラップします。

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

データには .results を、ライブデータかローカルデータかの判定には .meta.source を解析してください。人間が読みやすい N results (live) の概要が stderr に出力されるのは、stdout がターミナルであり、かつ機械形式のフラグ（--json、--csv、--compact、--quiet、--plain、--select）が設定されていない場合のみです。パイプやエージェントによる利用、および形式を明示した実行では、stdout に純粋な JSON が出力されます。

エージェントからのフィードバック

この CLI に気になる点があったら、あなた（またはエージェント）が記録してください。

exchangerate-api-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
exchangerate-api-pp-cli feedback --stdin < notes.txt
exchangerate-api-pp-cli feedback list --json --limit 10

エントリーはローカルの ~/.exchangerate-api-pp-cli/feedback.jsonl に保存されます。EXCHANGERATE_API_FEEDBACK_ENDPOINT が設定され、かつ --send が渡されているか EXCHANGERATE_API_FEEDBACK_AUTO_SEND=true が設定されていない限り、POST されることはありません。デフォルトの動作はローカルのみです。

バグ報告ではなく、意外に感じたことを書いてください。短く、具体的に、1 行で。積み重ねにつながるのはその部分です。

出力の配信

すべてのコマンドで --deliver <sink> を指定できます。出力は標準出力に加えて（または標準出力の代わりに）指定したシンクへ送られるため、エージェントはコマンド結果を手作業でパイプしなくても振り分けられます。サポートされているシンクは 3 種類です。

シンク	動作
stdout	デフォルト。stdout のみに書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（tmp + rename）
webhook:<url>	出力本文を URL に POST します（--compact の場合は application/json または application/x-ndjson）

不明なスキームは、サポート対象の一覧を示す構造化エラーとともに拒否されます。Webhook の失敗時はゼロ以外の値を返し、URL と HTTP ステータスを stderr に記録します。

名前付きプロファイル

プロファイルは、保存したフラグ値のセットで、呼び出しのたびに再利用できます。同じ設定で同じコマンドを毎回実行するスケジュール済みエージェントには、HeyGen の「Beacon」パターンのように活用できます。

exchangerate-api-pp-cli profile save briefing --json
exchangerate-api-pp-cli --profile briefing codes
exchangerate-api-pp-cli profile list --json
exchangerate-api-pp-cli profile show briefing
exchangerate-api-pp-cli profile delete briefing --yes

明示的なフラグは常にプロファイル値より優先され、プロファイル値はデフォルト値より優先されます。agent-context は available_profiles の下に利用可能なすべてのプロファイルを一覧表示するため、実行時に情報を調べるエージェントがプロファイルを見つけられます。

終了コード

コード	意味
0	成功
2	使用方法のエラー（引数が正しくありません）
3	リソースが見つかりません
4	認証が必要です
5	API エラー（上流の問題）
7	レート制限中（待ってから再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します。

1. 空、help、または --help → exchangerate-api-pp-cli --help の出力を表示します
2. install で始まる → mcp で終わる場合は MCP のインストール。それ以外の場合は、上記の「前提条件」を参照してください
3. その他 → 直接使用（CLI コマンドとして --agent を付けて実行します）

MCP サーバーのインストール

この CLI の公開ライブラリのエントリーまたはビルド済みリリースから MCP バイナリをインストールし、登録します。

claude mcp add exchangerate-api-pp-mcp -- exchangerate-api-pp-mcp

確認します：claude mcp list

直接使用

1. インストールされているか確認します：which exchangerate-api-pp-cli 見つからない場合は、インストールを提案します（このスキルの冒頭にある「前提条件」を参照してください）。
2. ユーザーのクエリに最適なコマンドを、上記の「独自の機能」と「コマンドリファレンス」から選びます。
3. --agent フラグを付けて実行します。

   exchangerate-api-pp-cli <command> [subcommand] [args] --agent
   

4. 曖昧な場合は、サブコマンドのヘルプを確認します：exchangerate-api-pp-cli <command> --help。