介绍
# CornerStone MCP x402 Skill (for Agents)
此技能为您（代理）提供了一组工具，用于：创建和管理 Aptos 与 EVM 钱包、检查余额，以及调用 x402 付费 MCP 工具（股票预测、回测、银行关联、代理/借款人评分）。**支付是自动的** —— 当付费工具返回 402 时，该技能会自动签名、验证、结算并重试，过程透明。您只需调用工具，结果会自动返回。
---
## 快速入门工作流
首次使用时请按以下顺序操作，之后可直接跳转到所需工具：
1. **检查钱包** → 调用 `get_wallet_addresses`（无需参数）。 2. **如果为空** → 调用 `create_aptos_wallet`，然后调用 `create_evm_wallet`。 3. **充值** → 调用 `credit_aptos_wallet`（Aptos 水龙头）和 `fund_evm_wallet`（EVM 水龙头说明）。 4. **告知用户** 在 `https://arnstein.ch/flow.html` 将返回的地址加入白名单。 5. **检查余额** → 调用 `balance_aptos`（进行预测/回测必须持有 USDC）和/或 `balance_evm`（关联银行账户必须持有 ETH）。 6. **使用付费工具** → `run_prediction`、`run_backtest`、`link_bank_account` 或评分工具。
> **重要提示：** 如果地址未充值且未加入白名单，付费工具将因钱包/白名单错误而失败。请务必先验证钱包和余额。
---
## 工具参考
### 钱包管理工具（本地）
#### `get_wallet_addresses` - **参数：** 无 - **返回：** `{ aptos: [{ address, network }], evm: [{ address, network }] }` — 可能为空数组。 - **何时使用：** 在执行任何钱包或付费工具操作之前始终先调用。用于确定已存在的内容。 - **决策：** 如果两个数组均为空 → 创建钱包。如果仅有一个为空 → 创建缺失的那个。如果两者均有条目 → 继续检查余额或使用付费工具。
#### `create_aptos_wallet` - **参数：** `{ force?: boolean, network?: "testnet" | "mainnet" }` — 默认值：force=false, network=testnet。 - **返回：** `{ success, address, network, message }`，或者在钱包已存在且 force=false 时返回 `{ success: false, message, addresses }`。 - **何时使用：** 当 `get_wallet_addresses` 返回空的 `aptos` 数组，或用户请求创建新钱包时。 - **错误处理：** 如果 `success: false` 且钱包已存在，可以使用现有钱包，或者使用 `force: true` 重试以添加另一个钱包。
#### `create_evm_wallet` - **参数：** `{ force?: boolean, network?: "testnet" | "mainnet" }` — 默认值：force=false, network=testnet。 - **返回：** `{ success, address, network, message }` 或 `{ success: false, message, addresses }`。 - **模式与** `create_aptos_wallet` **相同**。
#### `credit_aptos_wallet` - **参数：** `{ amount_octas?: number }` — 默认 100,000,000（= 1 APT）。 - **在 devnet 上的返回：** `{ success: true, address }`（通过程序化水龙头充值）。 - **在 testnet 上的返回：** `{ success: true, address, faucet_url }`（仅提供说明；无程序化水龙头）。 - **前提条件：** Aptos 钱包必须存在（需先执行 `create_aptos_wallet`）。 - **注意：** 充值的 APT 用于支付 Gas 费；工具使用 USDC 支付（约 6 美分）。用户可能需要单独获取测试网 USDC。
#### `fund_evm_wallet` - **参数：** 无 - **返回：** `{ success: true, address, faucet_url, message }`（手动充值说明）。 - **前提条件：** EVM 钱包必须存在（需先执行 `create_evm_wallet`）。 - **注意：** 返回 Base Sepolia 水龙头 URL。用户必须手动充值；没有程序化水龙头。
### 余额工具（本地）
#### `balance_aptos` - **参数：** 无 - **返回：** `{ address, balances: { usdc, apt } }` 或 `{ error }`。 - **何时使用：** 在调用 `run_prediction`、`run_backtest` 或评分工具之前，以确认 USDC 余额充足。
#### `balance_evm` - **参数：** `{ chain?: string }` — 默认 "base"。支持：`base`、`baseSepolia`、`ethereum`、`polygon`、`arbitrum`、`optimism`。 - **返回：** `{ address, chain, balance, symbol }` 或 `{ error }`。 - **何时使用：** 在调用 `link_bank_account` 之前，以确认 Base Sepolia 上的 ETH 余额充足。 - **注意：** 对于测试网工具，请使用 `chain: "baseSepolia"`。
### 付费 MCP 工具（x402 — 支付自动处理）
> 所有付费工具均接受 Aptos 和 EVM 支付。该技能会选择最佳选项或遵循 `PREFERRED_PAYMENT_ORDER`。您不会看到 402 错误 —— 只需调用工具，即可获取结果或错误信息。
#### `run_prediction` - **参数：** `{ symbol: string, horizon?: number }` — symbol 为股票代码（例如 "AAPL"），horizon 为天数（默认 30）。 - **返回：** 预测结果对象（预测数据、置信区间等）或 `{ error }`。 - **费用：** 约 6 美分 USDC（Aptos 或 EVM）。 - **前提条件：** 已充值且已加入白名单的 Aptos 或 EVM 钱包。 - **调用示例：** `run_prediction({ symbol: "AAPL", horizon: 30 })`
#### `run_backtest` - **参数：** `{ symbol: string, startDate?: string, endDate?: string, strategy?: string }` — 日期格式为 "YYYY-MM-DD"，strategy 默认为 "chronos"。 - **返回：** 回测结果（收益率、回撤、夏普比率等）或 `{ error }`。 - **费用：** 约 6 美分 USDC。 - **调用示例：** `run_backtest({ symbol: "TSLA", startDate: "2024-01-01", endDate: "2024-12-31", strategy: "chronos" })`
#### `link_bank_account` - **参数：** 无 - **返回：** `{ link_token }` 或用于 Plaid 银行关联的账户 ID，或 `{ error }`。 - **费用：** 约 5 美分（EVM/Base）。 - **前提条件：** 已充值且已加入白名单的 EVM 钱包（测试网需使用 Base Sepolia）。
#### `get_agent_reputation_score` - **参数：** `{ agent_address?: string, payer_wallet?: string }` — 两者均为可选；如果省略则使用配置的钱包。 - **返回：** `{ reputation_score: number }`（例如 100），如果未在白名单中则返回 403，或 `{ error }`。 - **费用：** 通过 x402 支付约 6 美分，或使用出借人积分免费支付（传递 `payer_wallet`）。
#### `get_borrower_score` - **参数：** `{ agent_address?: string, payer_wallet?: string }` — 模式相同。 - **返回：** `{ score: number }`（基准为 100；关联银行后分数更高）或 `{ error }`。 - **费用：** 通过 x402 支付约 6 美分，或使用出借人积分免费支付。
#### `get_agent_reputation_score_by_email` - **参数：** `{ email: string, payer_wallet?: string }` — 将电子邮件解析为白名单代理。 - **返回：** `{ reputation_score: number }` 或 `{ error }`。 - **前提条件：** 服务器上必须设置 `SCORE_BY_EMAIL_ENABLED`。费用较高。
#### `get_borrower_score_by_email` - **参数：** `{ email: string, payer_wallet?: string }` — 模式相同。 - **返回：** `{ score: number }` 或 `{ error }`。 - **前提条件：** 服务器上必须设置 `SCORE_BY_EMAIL_ENABLED`。费用较高。
---
## 常见任务的决策树
### "为 X 运行预测" ``` get_wallet_addresses → aptos empty? → create_aptos_wallet → credit_aptos_wallet → tell user to whitelist → aptos exists? → balance_aptos → has USDC? → run_prediction({ symbol: "X", horizon: 30 }) → no USDC? → tell user to fund USDC, provide address ```
### "关联银行账户" ``` get_wallet_addresses → evm empty? → create_evm_wallet → fund_evm_wallet → tell user to whitelist → evm exists? → balance_evm({ chain: "baseSepolia" }) → has ETH? → link_bank_account → no ETH? → fund_evm_wallet (returns faucet URL) ```
### "获取我的评分" ``` get_wallet_addresses → has aptos or evm? → get_agent_reputation_score + get_borrower_score → neither? → create wallets first, whitelist, then query ```
---
## 错误处理
| 错误模式 | 含义 | 操作方法 | |--------------|---------|------------| | `"No Aptos wallet"` | 钱包文件丢失 | 调用 `create_aptos_wallet` | | `"No EVM wallet"` | 钱包文件丢失 | 调用 `create_evm_wallet` | | `"already exist. Use force: true"` | 钱包已存在，未覆盖 | 使用现有钱包，或传递 `force: true` 添加另一个 | | `"Payment verification failed"` | 资金不足或资产错误 | 检查余额；告知用户为钱包充值 | | `"No Aptos wallet configured"` / `"No EVM wallet configured"` | 付费工具需要不存在的钱包 | 创建缺失的钱包类型 | | `"Unsupported chain"` | `balance_evm` 的链名称无效 | 使用以下之一：base, baseSepolia, ethereum, polygon, arbitrum, optimism | | `"timed out after 300s"` | MCP 调用耗时过长 | 重试一次；服务器可能负载过高 | | `"403"` 或 `"not allowlisted"` | 钱包未加入白名单 | 告知用户在 https://arnstein.ch/flow.html 将地址加入白名单 |
---
## 设置（面向安装此技能的人类用户）
1. **安装：** 在仓库根目录下运行 `npm install`。将 `.env.example` 复制为 `.env`。 2. **配置：** 设置钱包路径（`APTOS_WALLET_PATH`、`EVM_WALLET_PATH` 或 `EVM_PRIVATE_KEY`）。 3. **钱包：** 通过工具（`create_aptos_wallet`、`create_evm_wallet`）或 CLI（`node src/setup-aptos.js`、`node src/setup.js`）创建。在 https://arnstein.ch/flow.html 为所有地址充值并加入白名单。
---
## CLI 命令（在仓库根目录下）
| 任务 | 命令 | |------|--------| | 生成 Aptos 钱包 | `npm run setup:aptos` | | 生成 EVM 钱包 | `npm run setup` | | 显示白名单地址 | `npm run addresses` | | 为 Aptos 充值（devnet） | `npm run credit:aptos`（设置 `APTOS_FAUCET_NETWORK=devnet`）| | EVM 余额 | `npm run balance -- <chain>` | | 转账 ETH/代币 | `npm run transfer -- <chain> <to> <amount> [tokenAddress]` | | 交换代币（Odos） | `npm run swap -- <chain> <fromToken> <toToken> <amount>` | | 运行技能演示 | `npx cornerstone-agent "Run a 30-day prediction for AAPL"` | | 验证 Aptos 钱包 | `npm run attest:aptos` | | 验证 EVM 钱包 | `npm run attest:evm` |
---
**来源：** [FinTechTonic/autonomous-agent](https://github.com/FinTechTonic/autonomous-agent)