earnrate

earnrate

我想要一张幽灵卡：一张始终能从我的卡中选出回报最高的卡。银行卡组织不允许这种卡存在，所以我打造了一个次优方案。

earnrate 是面向个人和 AI Agent 的最佳卡片决策层。 告诉它商户名称，它就会告诉你钱包里哪张卡在该商户消费回报最高，以及原因。它会保留状态（了解你的消费上限和已选类别），会考虑估值，并会透明地说明其假设。它绝不会接触卡号。

• 在你的机器上运行。无需账户、无遥测、无联盟链接。请参阅隐私页面。
• 目前仅支持美国卡和美国商户。

状态： 项目尚处早期，但已可使用：包括引擎、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 设为对应路径。

你的钱包

钱包是一个 YAML 文件，按 ID 列出你的卡片；每个 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 Agent 的消费或通过 --apply 导入账单后，消费上限会逐渐填满，并在每个周期重置。

earnrate 尚不了解的商户

earnrate 内置了一份精心整理的商户列表。对于其他商户，它会退回到各卡的基础回报率，并明确说明这一点。传入 --llm（或将 EARNRATE_LLM=on）即可让 Claude 猜测类别：

• 它会使用你自己的 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 Agent 的消费或通过 --apply 导入账单后，消费额会递增；退款则会递减。达成奖励或截止日期已过后，该卡会恢复正常排名。如果有两项未达成的奖励，则优先处理每日所需消费额更高的一项。

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。请下载 CSV，而不是 PDF 账单：Chase 的 PDF 会在付款凭条中显示完整卡号，而 earnrate 从不处理卡号。

• 除非传入 --apply，否则这只是一次模拟；传入该参数后，会将当期的额度使用情况记入你的钱包。退款会减少额度使用量。
• 只读取日期、描述、金额、类别，以及 Chase 账单中的交易类型列。账单本身不会被存储：--apply 会将额度总额以及每笔已记录消费的哈希值写入 ~/.earnrate/imported.json，因此重复导入同一文件不会重复计入。
• 对于 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 卡、Nordstrom Visa
• 其他： U.S. Bank Cash+、Bilt Obsidian、SoFi Unlimited 2%

商店卡（Target、Kohl's、Nordstrom）只会在对应商店中被推荐。航空和酒店卡只计算卡片本身提供的奖励，不计算会员无论采用何种支付方式都能获得的计划积分；行李、免费住宿、贵宾室等福利也不计入。

目前格式尚无法表达的内容（例如 Bilt 的房租奖励、Citi Nights）会在相应卡片的文件中列为 todo:，而不是凭空推测。

发现奖励比例有误，或希望添加某张卡？请附上发卡机构官网页面的链接提交问题。

在 AI Agent 中使用（MCP）

earnrate mcp 会通过 stdio 将 earnrate 作为本地 MCP 服务运行，并提供五个工具：

• 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 的猜测。
• 引擎是纯函数且具有确定性。 给定一笔消费、一个日期和一个钱包，它会根据网络受理情况、日期范围、已用额度（消费跨越额度上限时会拆分计算）、季度类别选择和激活状态检查每条规则，然后根据你设定的每点价值计算积分价值，包括积分合并计算（如果你同时持有 Sapphire 和 Freedom Unlimited，Freedom Unlimited 的积分就按 Sapphire 积分的价值计算）。回答中还会显示并列结果、亚军胜出的积分估值，以及过期数据。
• 修改钱包时会保留文件内容。 记录消费时只会重写发生变化的数字，因此 YAML 中的注释和格式都能保留。
• 漂移检测。 每周运行一次 GitHub Action，在无头浏览器中打开各发卡机构的页面，检查每段引文是否仍然存在，并在条款变更时创建 issue。它只存储发卡机构文本的哈希值。
• 端到端测试。 测试包括根据发卡机构条款编写的黄金用例、CLI 快照测试、通过真实 stdio 完成的 MCP 往返测试、打包并安装 npm 包的安装测试，以及检查已提交文件中不含卡号。CI 会在每次推送时运行所有测试。

代码使用 TypeScript 编写，由 Node 24 直接运行（src/）；引擎位于 src/engine/，商户解析位于 src/merchants/，CLI 和 MCP 服务则是在它们之上的轻量封装。

保持卡片数据最新

data/cards/ 中的每条规则都附有一段来自发卡机构自有页面的简短引文。在此仓库的克隆版本中，yarn check-sources 会在无头浏览器中打开各发卡机构页面，并报告：

• 页面上已找不到对应引文的规则，通常意味着规则已变更
• 自上次基线以来新增或消失的返利条目，例如新增福利

GitHub Action 每周一运行该检查；如果发现变更，就会创建名为“Card source changes”的 issue。更新卡片文件后，运行 yarn check-sources --update 记录新的基线。部分发卡机构会阻止共享服务器上的无头浏览器访问；这些页面会标记为“couldn't check”，在本地运行命令即可检查。首次运行需要执行 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 不提供财务建议。发卡机构可能会更改条款，每个答案都会注明所依据的规则，因此大额消费前请查看卡片发卡机构的页面（文件中有链接）。