earnrate

earnrate

いつでも自分のカードの中で最もお得なカードで支払ってくれる、ゴーストカードが欲しいと思っていました。カードネットワークでは認められていないため、次善の策を作りました。

earnrate は、人と AI エージェントのための最適カード決定レイヤーです。 加盟店を指定すると、財布の中で最も多くのポイントを獲得できるカードと、その理由を教えてくれます。状態を保持し（利用上限や選択したカテゴリーを把握します）、価値を考慮し、判断の前提を明示します。カード番号を参照することはありません。

• お使いのマシン上で動作します。アカウント、テレメトリー、アフィリエイトリンクはありません。プライバシーページをご覧ください。
• 現時点では、米国のカードと加盟店に対応しています。

ステータス： 初期段階ですが、エンジン、CLI、オプションの Claude 加盟店検索、MCP サーバーが動作します。既存のカード選択用 MCP サーバーとの比較については、ベンチマークをご覧ください。

試してみる

Node 24 以降が必要です。

npm install -g earnrate
mkdir -p ~/.earnrate
curl -o ~/.earnrate/wallet.yaml https://raw.githubusercontent.com/cwasley/earnrate/main/wallet.example.yaml
earnrate whole foods 80

次に、~/.earnrate/wallet.yaml を編集して、自分のカードを一覧に追加します（ウォレットを参照）。

Whole Foods Market · $80

Use Blue Cash Preferred: 6% back, about $4.80. High confidence.

  1. Blue Cash Preferred  6%  $4.80
     6% cash back from its "us-supermarkets" rule. ...
  2. Prime Visa           5%  $4.00
     5% cash back from its "whole-foods" rule. Online or in-store.
  3. Amex Gold            4%  $3.20
     4x Amex Membership Rewards from its "us-supermarkets" rule. ...
     Valued at 1¢ per point: 4% back.
  + 6 more cards (--all lists them)

Amex Gold beats Blue Cash Preferred here if Amex Membership Rewards (MR) points are worth 1.5¢ or more (you value them at 1¢).

Assumes Whole Foods Market codes as supermarkets (MCC 5411).

オプション：--online または --in-store、--valuation flat|points-heavy、--all、--json、--date、--country。詳しくは earnrate --help を実行してください。ウォレットを別の場所に保存するには、EARNRATE_WALLET にそのパスを設定します。

ウォレット

ウォレットは、各カードの ID を列挙した YAML ファイルです。ID は data/cards/ にある各カードのファイル名です。必須なのはカードだけです。

valuations:
  UR: 1.5 # cents per point; leave out to use earnrate's defaults
memberships: [amazon-prime] # unlocks Prime Visa's 5%
cards:
  - id: chase-sapphire-preferred
  - id: chase-prime-visa
  - id: chase-freedom-flex
    activated: [q4-2026-grocery] # rotating 5% categories you've activated
  - id: usbank-cash-plus
    chosen: # categories you picked for the quarter
      period: 2026-Q4
      picks:
        five-percent: [tv-internet-streaming, movie-theaters]
        two-percent: [gas-ev-charging]

activated に指定するルール ID、chosen の選択肢スロット、ボーナスを有効にする会員 ID（BofA Rewards の会員ランクを示す bofa-rewards-premier など）は、各カードのファイルに記載されています。通貨とそのデフォルト値は data/currencies.yaml にあります。AI エージェントから購入を記録するか、--apply で明細を取り込むと利用上限が加算され、各期間の開始時にリセットされます。

earnrate が把握していない加盟店

earnrate には、厳選した加盟店リストが含まれています。それ以外の加盟店については、各カードの基本還元率を使い、その旨を伝えます。代わりに Claude にカテゴリーを推測させるには、--llm を渡すか、EARNRATE_LLM=on を設定します。

• ご自身の ANTHROPIC_API_KEY を使い、入力した加盟店名のテキストだけを送信します。金額、カード、ウォレットの内容がマシンの外に送られることはありません。
• 回答は ~/.earnrate/merchant-cache.json に保存されるため、加盟店を検索するのは一度だけです。
• 回答には Claude の推測であることが明記され、推論が示されます。また、信頼度が中程度を超えることはありません。
• 厳選された加盟店の情報が Claude に送られることはありません。

ウェルカムボーナス

カードの入会ボーナスを獲得しようとしている場合は、ウォレットの該当カードに追加します。

- id: chase-sapphire-preferred
  bonus: { opened: 2026-10-01, spend: 5000, by: 2026-12-31, points: 75000 }

ボーナスが有効な間は、そのカードが利用できるすべての加盟店で優先されます。回答には、必要な残りの利用額、期限に間に合わせるための週ごとの利用ペース、ポイント評価に基づくボーナスの価値、最も還元率の高いカードと比べて利用することで失う価値が示されます。AI エージェントから購入を記録するか、--apply で明細を取り込むと利用額が加算され、返金があると減算されます。条件を達成するか期限が過ぎると、カードは通常のランキングに戻ります。有効なボーナスが2つある場合は、1日あたりに必要な利用額が多い方が優先されます。

spend、by、報酬（points、現金還元の場合は dollars）は、earnrate にカードの公表オファーが登録されていれば、その値がデフォルトになります。実際のオファーが異なる場合は、これらを設定してください。

次にどのカードを作る？

earnrate offers --cash

まだ持っていないカードの入会オファーを、初年度の価値（自分のポイント評価額で換算したボーナスから初年度の年会費を差し引いた額）で順位付けします。--points、--no-fee、--business で絞り込めます。各オファーは発行会社のページに掲載されている一般向けのもので、獲得ルールと同様に毎週確認され、発行会社の適用条件は注記に記載されています。オファーは申込者や申込方法によって異なる場合があり、対象は earnrate が把握しているカードに限られます。アフィリエイトリンクや申込リンクはありません。

利用明細をインポートする

カードの利用履歴をダウンロードして、earnrate のおすすめカードで購入した場合にどれだけ獲得できたかを確認します。

earnrate import activity.csv --card amex-gold
earnrate import gold.csv:amex-gold sapphire.csv:chase-sapphire-preferred

各購入について、各カードで獲得した額とウォレット内の最適なカードで獲得できた額を合計し、別のカードなら最も多く獲得できた加盟店を一覧表示します。また、発行会社の加盟店分類コードが earnrate の想定と異なる加盟店にはフラグを付けます。カード名を指定して利用明細を複数指定すると、まとめてレポートを作成できます。Amex と Chase の利用履歴 CSV を読み込みます。PDF の利用明細ではなく CSV をダウンロードしてください。Chase の PDF には支払い用クーポンにカード番号全体が印字されますが、earnrate がカード番号を扱うことはありません。

• --apply を指定しない限り、これはドライランです。指定すると、ウォレットに当期の上限利用額が記録されます。返金分は差し引かれます。
• 読み取るのは日付、説明、金額、カテゴリ、および（Chase の場合）取引種別の各列だけです。利用明細そのものは保存されません。--apply を指定すると、上限利用額の合計と、記録した各購入のハッシュが ~/.earnrate/imported.json に書き込まれるため、同じファイルを2回インポートしても重複して計上されません。
• earnrate が把握していない加盟店の場合は、利用明細のカテゴリを使って行にフラグを付けます。ほかの発行会社では異なるカテゴリに分類される場合があるためです。
• --valuation points-heavy を指定すると、ポイントをウォレットでの評価額ではなく移行レートで評価します。その結果、最適なカードが変わる場合があります。

対応カード

57枚のカードを、それぞれ発行会社の規約に基づいてモデル化し、規約と照合して毎週確認しています。

• American Express： Gold、Platinum、Blue Cash Preferred、Blue Cash Everyday、Blue Business Plus
• Chase： Sapphire Preferred、Sapphire Reserve、Freedom Unlimited、Freedom Flex、Ink Business Cash、Ink Business Preferred、Prime Visa
• Chase の航空会社・ホテル系カード： United Gateway、Explorer、Quest、Club、Business、Club Business；Southwest Plus、Premier、Priority、Premier Business、Performance Business；Aeroplan；IHG One Rewards、Premier、Premier Select、Business
• Citi： Strata Elite、Strata Premier、Double Cash、Custom Cash、My Best Buy Visa、Costco Anywhere Visa（個人用・ビジネス用）；AAdvantage MileUp、Platinum Select、Globe、Executive、Business
• Capital One： Venture X、Venture、Savor、Kohl's Card、Kohl's Rewards Visa
• Wells Fargo： Active Cash、Autograph
• Bank of America： Atmos Rewards Ascent、Summit、Business；Customized Cash Rewards
• TD Bank： Target Circle Card、Nordstrom card、Nordstrom Visa
• その他： U.S. Bank Cash+、Bilt Obsidian、SoFi Unlimited 2%

店舗専用カード（Target、Kohl's、Nordstrom）は、それぞれの店舗でのみ候補に表示されます。航空会社・ホテル系カードで計上されるのはカード自体で獲得できるものだけで、会員がどのような支払い方法を使ってもプログラムから付与されるポイントは対象外です。また、特典（手荷物、無料宿泊、ラウンジ）も計上されません。

形式上まだ表現できない項目（Bilt の家賃での獲得、Citi Nights など）は推測せず、そのカードのファイルに todo: として記載しています。

還元率の誤りを見つけた場合や、カードの追加を希望する場合は、発行会社の公式ページへのリンクを添えてイシューを作成してください。

AI エージェントから使う（MCP）

earnrate mcp は、stdio 経由で earnrate をローカル MCP サーバーとして実行し、5 つのツールを提供します。

• best_card_for_purchase：どのカードを使うべきかを理由とともに提示します
• resolve_merchant：加盟店がどのように特定されたかを説明します
• list_wallet：カード、今期の残り上限額、選択したカテゴリー、ウェルカムボーナスの進捗を表示します
• compare_welcome_offers：保有していないカードで利用できる、最もお得な公開入会オファーを比較します
• record_purchase：ウォレットファイル内の購入額を利用上限と進行中のウェルカムボーナスに反映し、コメントも保持します

earnrate が認識していない加盟店の場合、呼び出し元のモデルは category（例：grocery.supermarket）を渡せます。これは不明な加盟店にのみ使われ、回答内に明記されます。コマンドラインでは同じ値を --category として指定します。

Claude Code に追加するには、次のようにします。

claude mcp add --scope user earnrate -- npx -y earnrate mcp

ほかの MCP クライアントでも、設定に同じコマンドを指定します。

{
  "mcpServers": {
    "earnrate": { "command": "npx", "args": ["-y", "earnrate", "mcp"] }
  }
}

コマンドラインと同じウォレット（~/.earnrate/wallet.yaml、またはサーバーの env に設定された EARNRATE_WALLET）を読み込みます。

仕組み

merchant text
  → resolve    category, channel, and the assumption behind them
  → evaluate   every rule on every card: network, dates, caps, picks, activations
  → value      your cents per point, with pooling
  → rank       winner, runner-ups, flip points, warnings, confidence

• カードの利用条件はコードではなくデータです。 各カードはルール（カテゴリー、還元率、上限、チャネル、日付、利用開始手続き、必要な会員資格）を記述した YAML ファイルで、Zod によって検証されます。すべてのルールには発行会社のページからの短い引用が含まれ、引用がない場合はテストが失敗します。エンジンにカード固有の分岐はありません。
• 加盟店は、カテゴリーとその根拠となる推定内容に紐づけられます。 「Whole Foods はスーパーマーケット（MCC 5411）として処理されます」と回答に明記されます。スタジアムやホテル内のレストランなど、複数の方法で処理される可能性がある店舗は、中程度の信頼度で、別の可能性も明示して返されます。不明な加盟店には基本還元率が適用されます。または、オプトインした場合はキャッシュされ、推定であることが明記された Claude の推測が使われます。
• エンジンは純粋かつ決定論的です。 購入内容、日付、ウォレットが与えられると、ネットワークでの利用可否、期間、すでに使った上限額（購入によって上限をまたぐ場合は分割）、四半期ごとの選択と利用開始状況について、すべてのルールを確認します。その後、ポイントを 1 ポイントあたりの価値で評価します。ポイントの合算も考慮されます（Freedom Unlimited のポイントは、Sapphire も保有している場合、Sapphire のポイント相当の価値になります）。同点の場合や、次点のカードが勝つ評価額、データの古さも回答に表示されます。
• ウォレットを編集しても、ファイルの内容は保たれます。 購入の記録では、変更された数値だけを書き換えるため、YAML 内のコメントや書式が維持されます。
• 変更の検出。 毎週、GitHub Action がヘッドレスブラウザーで各発行会社のページを開き、引用がすべて残っているかを確認します。利用条件に変更があった場合はイシューを作成します。保存するのは発行会社のテキストのハッシュだけです。
• エンドツーエンドでテスト済みです。 発行会社の利用条件に基づいて作成されたゴールデンケース、CLI のスナップショットテスト、実際の stdio を使った MCP の一連のやり取り、npm パッケージをパックしてインストールするインストールテスト、コミットされたファイルにカード番号が含まれていないことの確認を行います。CI ではプッシュのたびにこれらすべてを実行します。

コードは Node 24 で直接実行される TypeScript（src/）で、エンジンは src/engine/、加盟店の解決処理は src/merchants/ にあります。CLI と MCP サーバーは、その上に構築された薄いレイヤーです。

カードデータを最新に保つ

data/cards/ のすべてのルールには、発行会社のページからの短い引用が含まれています。このリポジトリをクローンして yarn check-sources を実行すると、ヘッドレスブラウザーで各発行会社のページを開き、次の内容を報告します。

• 引用がページからなくなったルール。通常はルールが変更されたことを示します
• 前回の基準時点から追加または削除された還元項目（新しい特典など）

GitHub Action が毎週月曜日にこれを実行し、変更があった場合は「Card source changes」というイシューを作成します。カードファイルを更新した後は、yarn check-sources --update を実行して新しい基準を記録してください。発行会社によっては共有サーバー上のヘッドレスブラウザーをブロックするため、そのようなページは「確認できませんでした」と表示されます。コマンドをローカルで実行すれば、これらのページも確認できます。初回の実行時には yarn playwright install chromium が必要です。

earnrate の開発

git clone https://github.com/cwasley/earnrate.git && cd earnrate
yarn install
yarn earnrate whole foods 80   # runs src/ directly, no build
yarn validate                  # typecheck, lint, format check and tests

プルリクエストを作成する前に、CONTRIBUTING.md をご確認ください。

ライセンス

• コード（data/以外のすべて）はMITです。
• データ（data/内のカードのルール、加盟店、カテゴリ、通貨）はCC BY-NC 4.0です。個人利用および非商用利用は、クレジット表記を条件に無料で利用できます。
• データの商用利用にはライセンスが必要です。 独自のAPIやMCP サーバーを通じて提供する場合や、有料製品で使用する場合も含まれます。[email protected]までお問い合わせください。

法的助言ではありません。誠意に基づいて構成しています。

earnrateは金融に関する助言を行うものではありません。発行会社は規約を変更することがあり、回答には使用したルールが必ず記載されます。高額な買い物をする前に、カード発行会社のページ（各ファイルにリンクがあります）をご確認ください。