内容
# @usenami/signer-mcp
> 为任何支持 MCP 的 AI 代理签署 CEX 订单 — 密钥从未离开过 AWS Nitro Enclave。
`signer-mcp` 是 [Usenami Signer](https://usenami.io/signer) 的公开接口。它为 Claude Desktop、Cursor、ElizaOS 和其他任何支持 MCP 的客户端提供了一个五种工具的界面，用于交易真实的 CEX/DEX 永续合约账户（Binance、OKX、Asterdex、KuCoin、Bybit、Hyperliquid），而无需将私钥加载到代理进程中 — 或您的进程中。
状态：**v0（alpha）**。测试网上的交易场所列表、证明、账户读取和订单放置/取消。
## 为什么存在
目前，每个与 CEX 交互的代理框架都会将 API 密钥加载到代理进程中。这会将密钥放在磁盘上、环境变量中、npm 包中、提示工程化工具调用中和 shell 历史记录中。一个提示注入、一个供应链泄露、一个意外的日志记录或一个好奇的同事 — 密钥就会泄露。
Signer 采取相反的方法。签名密钥在由 AWS 自身证明的 AWS Nitro Enclave **内部**生成。Enclave 的测量值（`PCR0`）发布在 `https://usenami.io/signer/attestations` 上。您在此处安装的 MCP 服务器可以请求 Enclave 签署特定的订单 — 受明确的策略（每资产上限、每周期上限、允许的交易场所）约束 — 但它无法读取密钥。代理、您的笔记本电脑、您的 IaC 或我们的工程师都无法读取密钥。
如果代理被泄露，它所能做的最坏的事情就是在您的策略窗口内放置订单。密钥本身保持证明。
## 快速入门（Claude Desktop）
1. **获取令牌。** 在 [usenami.io/signer](https://usenami.io/signer) 上登录并创建一个 API 令牌。该令牌绑定到一个单独的策略 — 在生成令牌之前设置每个交易场所的上限。
2. **编辑 `claude_desktop_config.json`。** 路径在 macOS 上为 `~/Library/Application Support/Claude/claude_desktop_config.json`。
```json
{
"mcpServers": {
"signer": {
"command": "npx",
"args": ["-y", "@usenami/signer-mcp"],
"env": {
"SIGNER_GATEWAY_URL": "https://signer.usenami.io",
"SIGNER_API_TOKEN": "sk_live_..."
}
}
}
}
```
3. **重启 Claude Desktop** 并查找 🔌 插件图标。您应该在 `signer` 下看到列出的五种工具。
4. **首先尝试只读工具。** 询问 Claude：
> “列出通过 Signer 可用的交易场所，然后返回当前的证明文档。”
没有资金风险 — 这些工具不会签署任何内容。
5. **一旦您信任证明，请下达一个小的测试订单：**
> “获取我的 Binance 账户，然后如果我有至少 $20 的可用保证金，请购买 0.001 BTC 的市场订单。”
如果出现任何问题，代理可以立即调用 `cancel_order`。
## 快速入门（ElizaOS）
ElizaOS 代理通过通用 MCP 插件
[`@elizaos/plugin-mcp`](https://github.com/elizaos-plugins/plugin-mcp) 访问 Signer — 不需要
Signer 特有的插件（可能会有原生的 `@usenami/eliza-plugin-signer`）。添加插件并通过 **stdio** 指向包：
```bash
npm install @elizaos/plugin-mcp
```
然后在您的角色/代理配置中：
```json
{
"plugins": ["@elizaos/plugin-mcp"],
"settings": {
"mcp": {
"servers": {
"signer": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@usenami/signer-mcp"],
"env": {
"SIGNER_GATEWAY_URL": "https://signer.usenami.io",
"SIGNER_API_TOKEN": "sk_live_..."
}
}
}
}
}
}
```
代理现在公开了相同的五种工具（`list_venues`、`get_attestation`、`get_account`、`place_order`、`cancel_order`）。相同的信任模型：签名密钥
从未进入 Eliza 进程 — 启动代理以使用只读工具
（`list_venues` / `get_attestation`）并在允许其下订单之前验证证明。
## 配置
通过 `claude_desktop_config.json`（或客户端的等效项）的 `env` 块传递环境变量：
| 变量 | 必需 | 默认值 | 备注 |
|---|---|---|---|
| `SIGNER_GATEWAY_URL` | 否 | `https://signer.usenami.io` | 自托管或临时部署的覆盖。 |
| `SIGNER_API_TOKEN` | 是（对于付费工具） | — | 由 usenami.io/signer 发出的 Bearer 令牌。`list_venues` 无需令牌；其他所有操作都需要。 |
| `SIGNER_FETCH_TIMEOUT_MS` | 否 | `30000` | 每个请求的获取超时时间，单位为毫秒。对于 CI/烟雾测试，值应较低；对于慢速链接，值应较高。必须是正整数。 |
MCP 服务器本身不存储任何磁盘内容。令牌在启动时从环境中读取，并在进程生命周期内保存在内存中 — 杀死代理，令牌就会消失。
## 工具参考
### `list_venues`
返回此 Signer 可以签署的静态交易场所清单。**只读**，不与网关联系，无需令牌。先调用此工具以发现支持哪些交易场所。
```json
{
"venues": [
{
"venue": "binance",
"asset_class": "perp",
"auth_scheme": "hmac_sha256",
"notes": "..."
}
],
"count": 6
}
```
#### 支持的交易场所
| `venue` id | 资产类别 | 认证方案 | 符号示例 | 备注 |
|---------------------|-----------|---------------|-----------|-------|
| `binance` | perp | hmac_sha256 | `BTCUSDT` | Binance USD-M 期货 |
| `okx` | perp | hmac_sha256 | `BTC-USDT-SWAP` | OKX 永续合约 |
| `asterdex` | perp | eip712 (bsc) | `BTC-USD` | Asterdex 链上永续合约（BSC） |
| `kucoin` | perp | hmac_sha256 | `XBTUSDTM` | KuCoin 期货（HMAC + 加密密码短语）；合约数量 |
| `bybit` | perp | hmac_sha256 | `BTCUSDT` | Bybit V5 线性合约（`category=linear`） |
| `hyperliquid_main` | perp | eip712 (hyperliquid) | `BTC` | Hyperliquid L1 永续合约；账户读取是公共的 `clearinghouseState` |
代理配置块对于每个交易场所都是相同的 — 将 `SIGNER_GATEWAY_URL` 指向您的 Signer 并设置 `SIGNER_API_TOKEN`。给定令牌可以交易的场所绑定到服务器端该令牌的策略；`list_venues` 报告网关可以签署的完整集合，而不是您的令牌允许列表。
### `get_attestation`
返回当前运行的 enclave 的 Nitro 证明文档。此处的 PCR0 测量值是 AWS 在启动 enclave 时签署的；您可以验证它与发布的构建版本是否匹配，方法是哈希相应的 EIF 并进行比较。
```json
{
"pcr0": "...sha384 hex...",
"pcr1": "...",
"pcr2": "...",
"signature": "...AWS-issued...",
"issued_at": "2026-05-31T18:00:00Z"
}
```
只读。
### `get_account`
返回某个交易场所的权益、可用保证金和未平仓合约。
```json
{
"venue": "binance",
"equity_usd": 145.32,
"free_margin_usd": 92.10,
"positions": [
{ "symbol": "BTCUSDT", "qty": 0.002, "entry_price": 67120.5 }
],
"updated_at": "2026-05-31T18:01:11Z"
}
```
只读。需要 `SIGNER_API_TOKEN`。
### `place_order`
下达一个市场订单或限价订单。Enclave 在检查策略上限后签署有效载荷。
参数：
- `venue` — `binance` | `okx` | `asterdex` | `kucoin` | `bybit` | `hyperliquid_main` 之一
- `symbol` — 规范的（`BTC`、`BTCUSDT`、`BTC/USDT`）**或** 交易场所原生的（`BTC-USDT-SWAP`、`XBTUSDTM`、...）。客户端将其转换为交易场所的原生格式并回显。
- `side` — `buy` | `sell`
- `qty` — **始终为基准资产数量**（例如 0.001 for 0.001 BTC）。不是 USD-标称的，不是交易场所合约。合约计价的交易场所（okx：1 合约 = 0.01 BTC on `BTC-USDT-SWAP`）会自动转换；交易场所合约网格之外的大小会被拒绝，不会被静默舍入。
- `type` — `market` | `limit`
- `price` — 如果 `type=limit` 则需要，如果 `type=market` 则忽略
- `policy_id` — 可选覆盖；默认为绑定到您的令牌的策略
结果包括一个 `translation` 回声 — 检查 `translation.sent` 以查看发送到交易所的确切交易场所原生符号 + 数量：
```json
{
"requested": { "symbol": "BTC", "qty": 0.01, "unit": "base_asset" },
"sent": { "symbol": "BTC-USDT-SWAP", "qty": "1", "unit": "contracts", "ctVal": "0.01" }
}
```
```json
{
"venue": "binance",
"order_id": "...",
"status": "FILLED",
"filled_qty": 0.001,
"avg_fill_price": 67128.9,
"policy_id": "default",
"attested_at": "..."
}
```
**破坏性**。需要 `SIGNER_API_TOKEN`。v0 将 Binance/OKX 路由到测试网，直到试点完成。
### `cancel_order`
通过其交易场所订单 ID 取消未完成的订单。幂等 — 取消已完成或不存在的订单会返回 `ok: false` 和交易场所原因，而不是出错。
参数：
- `venue` — 与 `place_order` 相同的枚举
- `order_id` — `place_order` 返回的交易场所 ID
需要 `SIGNER_API_TOKEN`。
## 验证证明
可信的 Signer 是其 enclave 测量值与您可以审计的构建版本匹配的 Signer。工作流程：
1. 调用 `get_attestation` 并复制返回的 `pcr0`。
2. 访问 [usenami.io/signer/attestations](https://usenami.io/signer/attestations)。
3. 将 PCR0 与当前生产版本的已发布构建版本进行交叉验证。
4. 可选地，从源代码重建 EIF（同一页面上有说明）并验证 SHA384 哈希。
如果发布的 PCR0 与 `get_attestation` 返回的结果不匹配，**不要交易**。打开一个问题。
## v0 有意不具备的功能
v0 故意保持界面紧密：
- 无多租户：每个交易场所每个令牌一个账户。
- 无 UPL 编辑 UI：策略在 usenami.io/signer 上设置。
- 无 WebSocket / 流式传输工具 — 仅 REST。
- 无跨交易场所路由（`place_order` 获取一个交易场所）。
- 无杠杆配置（`set_leverage`）— 使用账户默认值。
- 无提现 / 转账（最接近的是 `cancel_order`）。
- 无 TWAP / 冰山 — 仅一次性订单。
- 仅 stdio 传输 — 无 SSE 或远程 HTTP。
如果您需要上述任何功能，请提出一个问题来描述用例。v0 故意保持界面紧密。
## 开发
```bash
# 安装依赖
npm install
# 类型检查 + 构建
npm run build
# 从源码运行到预发布环境
SIGNER_GATEWAY_URL=https://staging.signer.usenami.io \
SIGNER_API_TOKEN=sk_test_... \
npm run dev
```
传输方式为 stdio；您需要一个支持 MCP 的客户端来实际使用这些工具。Anthropic 的 [`mcp-inspector`](https://github.com/modelcontextprotocol/inspector) 是在本地进行测试的最快方法。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
