comprabtc

Name: comprabtc
Author: csacanam

本地服务

github.com/csacanam金融数据011 周前更新

代码仓库

关于 comprabtc

CompraBTC 是面向 Celo 用户和 Agent 的非托管比特币定投服务。用户设定定期 USDT 购买计划，链上限额约束每次执行，所得 WBTC 直接进入用户钱包。

主要功能

01定期将 USDT 兑换为 WBTC
02链上支出与间隔限制
03链上取消计划
04购买后发送 Telegram 通知
05Agent API 与 keeper 执行

适用场景

01设置定期比特币储蓄计划
02让金库钱包定期购买 WBTC
03监控购买并取消计划
04通过 API 触发执行

MCP 相关

MCP 服务提供查询状态、创建、续订和取消计划，以及跟踪投资组合的工具；交易由金库自己的钱包签名。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "csacanam-comprabtc": {
      "command": "npx",
      "args": [
        "-y",
        "comprabtc-mcp"
      ],
      "env": {
        "COMPRABTC_WALLET_PRIVATE_KEY": "<COMPRABTC_WALLET_PRIVATE_KEY>",
        "COMPRABTC_MAX_PER_RUN_USDT": "<COMPRABTC_MAX_PER_RUN_USDT>"
      }
    }
  }
}

启动命令npx -y comprabtc-mcp

需要配置的环境变量

COMPRABTC_WALLET_PRIVATE_KEY密钥Treasury/agent wallet that owns the plan (holds USDT, signs setup txs, receives WBTC). Required only for create/renew/cancel; reads work without it.

COMPRABTC_MAX_PER_RUN_USDTSafety cap per installment in USDT (default 50, pool-depth guard).

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmcomprabtc-mcp0.1.1stdio

工具

收录的工具列表 · 更新于 3 周前

参数	类型	必填	说明
address	string	否	要检查的钱包（默认为已配置的资金库钱包）

详细介绍

CompraBTC

Celo 上的非托管式比特币定投 Agent。 只需设置一次计划——每小时／每天将 $X 换成 BTC——链上 Agent 就会为你购买比特币，并直接存入你自己的钱包。两次购买之间，资金始终留在你的钱包中。

在线应用： https://comprabtc.vercel.app（可在 MiniPay 和任何注入式钱包中使用）
Agent API： https://comprabtc-api.vercel.app（`GET /服务描述 ·GET /api/stats` 公开指标）
为 Celo Agentic Payments & DeFAI Hackathon 打造——排行榜

已部署合约（Celo 主网，链 ID 42220）

合约	地址
DCAExecutor（已验证）	`0xd03ffeBBCaaA8aA21053eEB0EeAde39EFC504189`
USDT（输入代币）	`0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e`
WBTC — 原生桥接代币（输出代币）	`0x8aC2901Dd8A1F17a1A4768A6bA4C3751e3995B2D`
Uniswap V3 SwapRouter02	`0x5615CDAb10dc425a742d643d949a7F474C01abc4`

兑换通过 USDT/WBTC 0.3% Uniswap V3 池进行路由。协议费用：每次执行收取 1% + $0.005 固定费用，并设有链上硬性上限（≤1%、≤$0.05 固定费用）；如果费用会吞掉整笔定投金额，交易就会回滚。

Agent 身份：Celo 主网上的 ERC-8004 #9665（8004scan）。每笔交易都带有 ERC-8021 归因标签。

工作原理

flowchart TB
    USER["👤 User wallet<br/>(MiniPay / MetaMask / Valora)"]
    FE["Frontend — Next.js PWA<br/>(Vercel)"]

    subgraph onchain["⛓️ Celo mainnet"]
        USDT["USDT (ERC-20)"]
        EXEC["DCAExecutor<br/>0xd03f…4189<br/>non-custodial, on-chain limits"]
        ROUTER["Uniswap V3 SwapRouter02<br/>USDT/WBTC 0.3% pool"]
        TREASURY["Treasury"]
    end

    subgraph backend["🤖 Agent backend — Vercel"]
        KEEPER["Keeper (Vercel Cron, 5 min)<br/>scans PlanCreated events,<br/>checks due plans"]
        API["Express API<br/>POST /api/execute<br/>(x402-gated, permissionless)"]
        DB[("Supabase<br/>plans · executions")]
        TG["Telegram bot<br/>purchase alerts + ops"]
    end

    FACIL["x402 facilitator<br/>api.x402.celo.org"]

    USER -- "① approve(budget) — once" --> USDT
    USER -- "② createPlan(amount, interval) — once" --> EXEC
    FE -.-> USER
    KEEPER -- "discovers plans<br/>(PlanCreated events)" --> EXEC
    KEEPER -- "③ pays 0.02 USDT via x402<br/>(EIP-3009 signature)" --> API
    API -- "verify + settle" --> FACIL
    API -- "④ execute(user, minOut)<br/>+ ERC-8021 attribution tags" --> EXEC
    EXEC -- "⑤ transferFrom<br/>(one installment)" --> USDT
    EXEC -- "fee 1% + $0.005" --> TREASURY
    EXEC -- "⑥ swap USDT→WBTC" --> ROUTER
    ROUTER -- "⑦ WBTC straight<br/>to the user's wallet" --> USER
    API -- "records execution" --> DB
    API -- "🔔 purchase alert" --> TG

用户授权 DCAExecutor 使用 USDT（上限 = 计划总预算），并创建一项设有链上限制的计划（每次执行金额、最短间隔）。取消只需点击一次（cancelPlan 或 approve(0)）。
keeper 从 PlanCreated 事件中发现计划，并在每个周期先通过 x402 微支付向执行 API 付款，再调用 execute()——因此，每次购买也都是一次 Agent 对 Agent 的支付。
链上限制意味着，即使 keeper 遭到入侵，也无法超额收费：它最多只能提取 amountPerRun，且必须等到 minInterval 到期后才能执行。
每次购买后，用户都会收到 Telegram 提醒（在应用的 Settings 中添加链接）。

仓库目录结构

目录	内容
`contracts/`	`DCAExecutor.sol`（Foundry）——21 项测试，包括主网分叉测试，以及部署脚本
`backend/`	Express API + keeper 循环（viem）+ x402 中间件 + Supabase + Telegram 机器人
`frontend/`	Next.js PWA（wagmi/viem）——MiniPay 自动连接、创建计划、BTC 投资组合
`docs/`	单位经济分析、文案审查
`PLAN.md`	完整的架构计划及逐项可行性验证

本地运行

前端（需要在 frontend/.env.local 中设置 NEXT_PUBLIC_EXECUTOR_ADDRESS、NEXT_PUBLIC_API_URL、NEXT_PUBLIC_ATTRIBUTION_CODE、NEXT_PUBLIC_TELEGRAM_BOT）：

cd frontend && pnpm install && pnpm dev   # http://localhost:3000

后端 + keeper（Node 22；所需环境变量见 backend/src/config.ts——执行器地址、keeper 密钥、Supabase 凭据、x402 API 密钥；数据库架构见 backend/supabase/schema.sql，迁移文件位于同一目录）：

cd backend && pnpm install && pnpm dev    # API on :8080, keeper ticks every 60s

本地运行时，keeper 会作为进程内循环运行（setInterval）。部署到 Vercel 后，整个 Express 应用是一个独立函数，keeper 则由 Vercel Cron 通过调用 GET /api/cron/keeper 驱动（由 CRON_SECRET 保护，调度配置位于 backend/vercel.json）——无服务器实例会被冻结并重复使用，因此在那里设置间隔定时器会导致重复且不按计划运行的周期任务。keeper 需要在周期之间记住的所有信息（提醒冷却时间、摘要频率、上次扫描的区块）都存放在 agent_keeper_state 中，而非内存中。

合约：

cd contracts && forge test                # unit + Celo mainnet fork tests
forge script script/Deploy.s.sol --rpc-url celo --broadcast --verify --interactives 1

面向 AI Agent

拥有自有资金钱包的 Agent 可以通过两笔交易设置 Bitcoin 储蓄计划；协助人类的 Agent 也可以（由 Web 应用处理签名）：

MCP 服务（treasury DCA）：claude mcp add comprabtc -- npx -y comprabtc-mcp — 提供用于检查状态、创建／续订／取消计划以及跟踪投资组合的工具，并使用 treasury 自有钱包签名。参见 mcp/README.md。
Agent 技能：npx skills add csacanam/comprabtc — 涵盖计划创建（viem）、监控、预算计算、取消计划，以及无需许可的 x402 执行触发器。
服务描述文件（机器可读的操作指南）：GET https://comprabtc-api.vercel.app/ · LLM 索引：comprabtc.vercel.app/llms.txt
Agent 身份：Celo 上的 ERC-8004 #9665 — metadata · 8004scan

透明度

运营方钱包（已声明）：

角色	地址
Keeper（执行计划）	`0x2F6a8283546d28506B312013F77aA38e60AF99B0`
Treasury / payTo（接收费用）	`0x6Bd5c303b2ed7E264C1Ce9D3592457292a1F1c43`

链上交易量来自真实用户资金。 每个计划都以用户自己的 approve 开始；Keeper 每次运行通过 transferFrom 提取一笔分期款，购买的 WBTC 会直接进入用户钱包并留存其中。不托管、不往返转账——这些交易量都是真实购买 BTC 的行为，具有实际经济意图。

x402 是内部计量机制，也向外部开放。 Keeper 每次运行都会支付 x402，因此 每笔 x402 付款都对应一次实际执行的购买，并非单独产生的微额交易。/api/execute 无需许可，并会根据链上事件自动注册计划，因此任何外部 Agent 或人类都可以调用它并结算自己的 x402；这不是一个封闭循环。

黑客松赛道

赛道 1 — 链上收入： 在 execute() 内收取协议费用，每笔交易都带有 ERC-8021 归属标记。
赛道 2 — x402 支付： Keeper 每次运行都会通过 Celo x402 facilitator 向 /api/execute 付款。该端点无需许可——任何 Agent 都可以付费触发一次执行。
赛道 4 — Aigora： Agent 已注册到 Aigora 市场（#395），并在 trionlabs/aigora-skills 提交了反馈 PR。