Skip to content

iwbinb/usdc-copilot

BranchesTags

Repository files navigation

USDC Copilot

AI-native portfolio agent for autonomous USDC treasuries. Built for the Agora Agents Hackathon (Canteen × Circle, 2026).

USDC Copilot is the cockpit autonomous agents need to operate USDC treasuries across multiple chains. It reads a unified balance via Circle Gateway, indexes every USDC Transfer event on Arc and three EVM testnets, scores each watched transfer with Claude Haiku 4.5, lets Claude Sonnet 4.6 propose typed rebalancing actions, and executes those actions through CCTP V2 in seconds.

The flagship feature is verified on-chain: 1 USDC moved Arc → Ethereum Sepolia end-to-end in ~10 seconds, with both the burn and the mint linked from the dashboard.

English

What it does

Pillar What it does
Unified balance Calls Circle Gateway /v1/balances to read USDC across Arc, Ethereum Sepolia, Base Sepolia, Arbitrum Sepolia — with RPC fallback so a treasury holding USDC directly in an EOA still shows real numbers.
Activity indexer Bun worker subscribed to USDC Transfer events on four chains, writing to Postgres. The dashboard's Activity feed reads from this.
Risk classifier Claude Haiku 4.5 scores every watched transfer 0–100 with a label (safe / suspicious / high_risk) and a one-sentence reason, via Anthropic tool-use.
Liquidity strategist Claude Sonnet 4.6 reads the portfolio + recent activity and emits 1–4 typed insights, each optionally bound to a cctp_transfer action.
One-click execution POST /api/execute signs the burn + mint via viem (PRIVATE_KEY) or Circle Developer-Controlled Wallets; polls Circle's Iris attestation service in between.
Production polish Modular 7-page Next.js dashboard, dark/light theme, full-address display with copy & explorer links, real metrics from the indexer.

Tech stack

apps/
  web/        Next.js 15 App Router · Tailwind · dark/light theme · SSR dashboard
  api/        Bun + Hono · Gateway + CCTP V2 + Wallets · Postgres
  indexer/    Bun worker · viem · scores transfers via Haiku 4.5
packages/
  shared/     chain configs, ABIs, types, CCTP V2 contract triple

Chains (testnet only — Gateway has no mainnet endpoint yet):

Chain Chain ID CCTP domain Native gas USDC
Arc Testnet 5042002 26 USDC 0x3600000000000000000000000000000000000000
Ethereum Sepolia 11155111 0 ETH 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238
Base Sepolia 84532 6 ETH 0x036CbD53842c5426634e7929541eC2318f3dCF7e
Arbitrum Sepolia 421614 3 ETH 0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d

Circle products integrated: Gateway, CCTP V2, Developer-Controlled Wallets, Arc, Paymaster (Arbitrum demo card), App Kit patterns.

Models: claude-sonnet-4-6 (liquidity strategist), claude-haiku-4-5-20251001 (risk classifier).

Quick start

# 1. install
bun install

# 2. configure
cp .env.example .env
#   ANTHROPIC_API_KEY=...
#   DATABASE_URL=postgres://...
#   PRIVATE_KEY=0x...      # raw-key execution path (preferred)
#   GATEWAY_API_BASE=https://gateway-api-testnet.circle.com  (default)
#   CCTP_ATTESTATION_API=https://iris-api-sandbox.circle.com (default)
#   INDEXER_WATCH_ADDRESSES=0x...,0x...
#   EXECUTE_TOKEN=...      # bearer required to call /api/execute in live mode

# 3. apply schema
bun run --cwd apps/api scripts/init-db.ts

# 4. dev servers (3 terminals)
bun run dev:api      # http://localhost:8787
bun run dev:indexer  # background worker
bun run dev:web      # http://localhost:3000

Verify the integrations

# Gateway unified balance for any EVM address
bun run spike:gateway 0x71C7656EC7ab88b098defB751B7401B5f6d8976F

# End-to-end CCTP V2 burn → attest → mint
PRIVATE_KEY=0x... bun run --cwd apps/api scripts/spike-cctp-raw.ts arc ethereum 1

Tests & code review

bun test            # 47 unit + 12 e2e, all passing
bun run typecheck   # all four workspaces

The CODE_REVIEW.md in docs/ walks through bug fixes, security posture, and architecture notes from the internal review pass.

Routes

Path What you see
/ Hero card with rotating gradient ring · 4 nav tiles · top AI suggestion · flagship CCTP execution
/balance Unified balance per chain + distribution bar + Signer card + Arc & Paymaster spotlight
/activity Live transfer feed with chain / direction / risk filters + right sidebar (risk rollup, per-chain stats)
/insights Claude-generated insights with one-click Execute + stage tracker
/chains Per-chain card with indexed transfers, USDC volume, contract address, explorer link
/executions Every real CCTP burn/mint the project has signed, linked to source/dest explorers
/about Product overview, Circle products used, repo layout

Verified on-chain evidence

1 USDC, Arc → Ethereum Sepolia, Fast Transfer (finality threshold 1000)

  • burn on Arc: Arcscan
  • Iris attestation: 262 bytes, returned by iris-api-sandbox.circle.com/v2/messages/26
  • mint on Ethereum Sepolia: Etherscan

Full evidence in EVIDENCE.md.

Project philosophy

This is not an Explorer with an AI sticker. The dashboard is the observation surface of an agent that:

  1. reads state from a real on-chain source (Gateway + RPC),
  2. ingests every event into Postgres so decisions are grounded in data,
  3. commits to a typed action via Anthropic tool-use, not free-form text,
  4. closes the loop with a real CCTP V2 transaction that mints on the destination chain,
  5. records the execution so the next decision can build on it.

That loop is the product. Everything else is plumbing.

License

MIT.

中文

USDC Copilot 是给自主 AI agents 用的 USDC 多链资金管家。它通过 Circle Gateway 读取 Arc + 3 条 EVM testnet 的统一余额,把每一笔 USDC Transfer 事件索引进 Postgres,用 Claude Haiku 4.5 给每笔被关注的转账打风险分,用 Claude Sonnet 4.6 给出结构化的再平衡建议,并通过 CCTP V2 在十秒内把建议落地到链上。

核心能力链上已被验证:1 USDC 从 Arc 跨到 Ethereum Sepolia,burn / 证明 / mint 全流程约 10 秒,所有 tx hash 在 dashboard 内可点开浏览器核对。

它做什么

模块 做什么
统一余额 调 Circle Gateway /v1/balances 拿 Arc / Ethereum Sepolia / Base Sepolia / Arbitrum Sepolia 的 USDC,RPC fallback 保证 EOA 直接持有的 USDC 也能正确显示。
活动索引器 Bun worker 订阅四条链上 USDC Transfer 事件,写入 Postgres,Activity 页直接读它。
风险分类器 Claude Haiku 4.5 通过 tool-use,对每笔关注的转账给出 0–100 风险分 + 标签(safe / suspicious / high_risk)+ 一句话理由。
流动性策略师 Claude Sonnet 4.6 读组合 + 近期活动,产出 1–4 条结构化 insight,可选附带一个 cctp_transfer action。
一键执行 POST /api/execute 通过 viem(PRIVATE_KEY)或 Circle Developer-Controlled Wallets 签名 burn + mint,中间轮询 Iris 取证明。
生产级打磨 模块化 7 页 Next.js dashboard,深色 / 浅色双主题,完整地址显示 + 复制按钮 + 区块浏览器跳转,指标全部来自真实 indexer。

技术栈

apps/
  web/        Next.js 15 App Router · Tailwind · 深浅主题 · SSR dashboard
  api/        Bun + Hono · Gateway + CCTP V2 + Wallets · Postgres
  indexer/    Bun worker · viem · 转账事件 + Haiku 4.5 评分
packages/
  shared/     链配置、ABI、类型、CCTP V2 合约三元组

链(目前 testnet only — Gateway 尚无 mainnet endpoint):Arc Testnet (5042002, 域 26) / Ethereum Sepolia / Base Sepolia / Arbitrum Sepolia。详细合约地址见上方英文版表格。

集成的 Circle 产品:Gateway、CCTP V2、Developer-Controlled Wallets、Arc、Paymaster(Arbitrum 演示卡)、App Kit 视觉模式。

模型:claude-sonnet-4-6(策略)、claude-haiku-4-5-20251001(风险)。

快速开始

# 1. 安装
bun install

# 2. 配置
cp .env.example .env
#   ANTHROPIC_API_KEY=...
#   DATABASE_URL=postgres://...
#   PRIVATE_KEY=0x...      # 优先使用的 raw-key 执行路径
#   GATEWAY_API_BASE=https://gateway-api-testnet.circle.com  (默认)
#   CCTP_ATTESTATION_API=https://iris-api-sandbox.circle.com (默认)
#   INDEXER_WATCH_ADDRESSES=0x...,0x...
#   EXECUTE_TOKEN=...      # live 模式调用 /api/execute 需带的 Bearer

# 3. 建表
bun run --cwd apps/api scripts/init-db.ts

# 4. 启服务(3 个终端)
bun run dev:api      # http://localhost:8787
bun run dev:indexer  # 后台 worker
bun run dev:web      # http://localhost:3000

验证集成

# 读任意 EVM 地址的 Gateway 统一余额
bun run spike:gateway 0x71C7656EC7ab88b098defB751B7401B5f6d8976F

# 完整 CCTP V2:burn → 取证 → mint
PRIVATE_KEY=0x... bun run --cwd apps/api scripts/spike-cctp-raw.ts arc ethereum 1

测试与代码评审

bun test            # 47 单元 + 12 e2e,全部通过
bun run typecheck   # 4 个 workspace 类型检查

docs/CODE_REVIEW.md 记录了内部评审过程发现的 bug、修复、安全审视和架构注解。

页面

路径 内容
/ 渐变光环 Hero · 4 个导航 tile · 顶部 AI 建议 · 旗舰 CCTP 执行高亮
/balance 各链余额 + 占比条形图 + Signer card + Arc & Paymaster 高亮
/activity 实时 transfer 流,可按链 / 方向 / 风险筛选,右侧栏聚合风险分类 + 各链分布
/insights Claude 生成的建议 + 一键 Execute + 阶段进度
/chains 每链卡片:transfers 数、USDC volume、合约地址、浏览器链接
/executions 项目签过的所有真实 CCTP burn/mint,链接到源/目标链浏览器
/about 产品概览、用到的 Circle 产品、仓库结构

链上证据(已验证)

1 USDC,Arc → Ethereum Sepolia,Fast Transfer

完整证据在 EVIDENCE.md。

设计哲学

这不是「加了 AI 贴纸的 Explorer」。Dashboard 是一个 agent 的观察面,而 agent 真正做的事是:

  1. 从真实链上来源读状态(Gateway + RPC)
  2. 把每个事件落库,让决策建立在数据上
  3. 通过 Anthropic tool-use 给出类型化的 action,不是自由文本
  4. 用一笔真实的 CCTP V2 交易在目标链 mint,把回路闭合
  5. 记录执行,作为下次决策的输入

这个回路就是产品本身,其余都是脚手架。

License

MIT。

About

AI-native portfolio agent for autonomous USDC treasuries. Circle Gateway + CCTP V2 + Claude agents. Agora Agents Hackathon 2026.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages