HashLock OTC

@hashlock-tech/mcp

Hashlock Markets — 以 MCP 工具形式提供的 Agent 经济结算层。非托管跨链场外交易：密封 RFQ + 价格协商 + HTLC 原子结算——两边要么都完成结算，要么都退款；无需跨链桥、托管方或承担交易对手风险。BTC ↔ EVM / TRON / Solana。

已在主网运行：Bitcoin、Ethereum、Base、Robinhood Chain、TRON、Solana。请使用专用密钥，且仅存入你打算交易的资金。

📖 文档：docs.hashlock.markets — 概念、快速入门、指南和 API 参考。面向 Agent：llms.txt（索引）、llms-full.txt（全部内容汇总于一个文件），在任意页面 URL 后添加 .md 即可获取 Markdown 版本；还可使用文档搜索 MCP 服务：https://docs.hashlock.markets/mcp。

这是什么？

Hashlock Markets 的规范 Model Context Protocol 服务。它为 AI Agent（Claude、Cursor、Windsurf，以及任何 MCP 客户端）提供完整的场外交易流程：

1. 浏览资产注册表和公开 RFQ 看板
2. 发布公开 RFQ 或私人固定价格订单（可分享链接）
3. 回复请求并报价；在交易讨论串中协商（还价 / 接受 / 拒绝）
4. 达成一致——接受对方报价 → 创建 HTLC 兑换（你自己的报价或还价本身即视为接受）
5. 跟踪结算——查看谁已注资、时间锁和交易哈希，并管理收款 / 退款地址

结算签名（为 HTLC 注资和领取）由你自己的钱包完成——服务端不会持有密钥或资金。兑换密钥在你的设备本地生成，仅发送其 sha256 哈希锁；到领取时，使用 get_deal_secret 获取密钥。

两种运行方式

• 本地（stdio）——使用下方的 npm 包。在你的设备上运行，使用你自己的密钥；可以 自主完成结算（SIWE 登录 + 使用 HASHLOCK_*_KEY 进行链上签名）。你完全信任自己。
• 远程（托管，Streamable HTTP）——公共 URL（https://hashlock.markets/mcp），可从 Claude / ChatGPT / 任何 MCP 客户端添加；一键 OAuth，无需安装。支持多租户，因此严格遵循 非托管原则：结算返回未签名的交易，由你使用自己的钱包签名；服务端绝不持有密钥或兑换原像。参见下方的远程（托管）。

安装

HASHLOCK_API_URL=https://hashlock.markets/api npx -y @hashlock-tech/mcp

最简配置（只读——浏览资产和 RFQ 看板，无需密钥）：

{
  "mcpServers": {
    "hashlock": {
      "command": "npx",
      "args": ["-y", "@hashlock-tech/mcp"],
      "env": { "HASHLOCK_API_URL": "https://hashlock.markets/api" }
    }
  }
}

如需交易，请添加 Agent 自己的密钥（通过 npx 运行本地 stdio，配置 Claude Desktop / Cursor / Windsurf 的 mcpServers）：

{
  "mcpServers": {
    "hashlock": {
      "command": "npx",
      "args": ["-y", "@hashlock-tech/mcp"],
      "env": {
        "HASHLOCK_API_URL": "https://hashlock.markets/api",
        "HASHLOCK_EVM_KEY": "0x<agent EVM key>",
        "HASHLOCK_TRON_KEY": "<agent TRON key, 64-hex (optional)>",
        "HASHLOCK_BTC_KEY": "<agent BTC WIF (optional)>",
        "HASHLOCK_SOLANA_KEY": "<agent Solana key, base58 (optional)>"
      }
    }
  }
}

身份验证 — 每条链独立处理

Agent 持有自己的密钥；服务端自行完成登录（nonce → 签名 → JWT，过期时刷新）。 第一个已配置的密钥（EVM → TRON → BTC → Solana）用于创建会话；每个密钥也会在其所属链上签署结算。

环境变量	链	登录方式
HASHLOCK_EVM_KEY	EVM	SIWE personal_sign
HASHLOCK_TRON_KEY	TRON	signMessageV2
HASHLOCK_BTC_KEY	Bitcoin	BIP-322
HASHLOCK_SOLANA_KEY	Solana	ed25519 signMessage
HASHLOCK_TOKEN	—	现成的 JWT（可替代密钥）

HASHLOCK_SOLANA_KEY 使用 base58 编码——钱包提供的 64 字节导出值，或仅含 32 字节的种子。如果它是唯一设置的密钥，就会用于创建会话；否则会按上述顺序排在其他密钥之后。无论哪种情况，Agent 都会在首次发帖、报价、接受订单或调用 whoami 时证明其拥有该钱包（向 /me/link-solana 发送带 nonce 的签名消息），因为 give 端为 Solana 的订单若未提供此证明就会被拒绝——而且只有这样，Agent 才会出现在面向该钱包的私有订单的信息流中。如果账户已关联其他 Solana 钱包，则保留现有的关联；其他操作不受阻止，whoami.solanaLink 会说明这一点。Solana 也是唯一一种本软件包不会构建交易的链：托管合约的 ADDRESS 是约定条款的哈希，因此由服务端构建每笔交易，Agent 则对收到的字节签名。在注资前，通过 set_settlement_address 将 Agent 的 Solana 地址设为结算地址——whoami 会在 localSigners.addresses.solana 中返回该地址。

如果未设置任何密钥，仍可使用只读工具（list_assets、list_open_rfqs、get_rfq）。请使用仅持有计划交易资金的专用密钥。

必需：HASHLOCK_API_URL — API 基础 URL，例如 https://hashlock.markets/api；没有默认值。其他环境变量：HASHLOCK_APP_URL（分享链接；默认值自动推导）、HASHLOCK_EVM_RPC（默认使用一个公共 Ethereum 主网 RPC；其他 EVM 链使用 HASHLOCK_EVM_RPC_<CHAIN>，例如 HASHLOCK_EVM_RPC_BASE）、HASHLOCK_TRON_HOST（默认使用 TronGrid 主网）、HASHLOCK_TRON_API_KEY（TronGrid API 密钥——不提供时 TronGrid 会限制请求）、HASHLOCK_SECRETS_PATH（默认值为 ~/.hashlock/mcp-secrets.json，权限模式为 0600）。

远程（托管）

同一服务也以 通过 Streamable HTTP 传输的远程 MCP 形式运行，任何人都能通过 URL 连接，无需 安装。这是一个多租户、非托管的入口：浏览、发布 RFQ、协商，并获取由你使用自己的钱包签署的未签名 资金划转／领取／退款交易（这里不会通过环境变量中的密钥自主签名，也不会在服务端存储机密——你需要提供自己的 hashlock，并自行保管原像）。

**从客户端连接：**添加服务 URL。仅此而已——客户端会发现需要授权，将你引导至 Hashlock 登录并批准，然后获取自己的密钥：

URL: https://hashlock.markets/mcp

批准操作需要使用你的钱包签名——仅登录会话不会授予任何权限。授权随后会显示在 开发者 下，作为普通 API 密钥：有效期为 90 天；每当创建密钥时，系统都会通过 Telegram 通知你（如果已关联）；你也可以随时在此撤销密钥。不支持 OAuth 的客户端仍可发送自行创建的密钥，格式为 Authorization: Bearer hk_…。

**无浏览器的 Agent：**持有钱包密钥的 Agent 可以自行铸造 hk_ 密钥——调用 GET https://hashlock.markets/api/v1/keys/nonce，签署 Hashlock Markets — create an API key.，并附上 Address: 和 Nonce: 行（可选添加 Key name: 和 Scopes:），然后通过 POST /api/v1/keys 发送 { rail, address, message, signature }。密钥属于该钱包登录的账户，并在首次使用时创建。仅使用钱包的账户只有一个密钥——再次签名会替换原密钥，也可借此找回丢失的密钥；通过邮箱、Google 或 Telegram 在 /developers 注册后，可持有最多 10 个密钥。请参阅 /api/v1/docs。

OAuth 流程的工作方式

标准 OAuth 2.1，因此任何符合规范的 MCP 客户端都能自动完成此流程：

步骤	端点
未授权的调用会提供元数据地址	401 + WWW-Authenticate: … resource_metadata=…（RFC 9728）
客户端读取资源和服务元数据	/.well-known/oauth-protected-resource、/.well-known/oauth-authorization-server（RFC 8414）
客户端注册自身	POST /oauth/register（RFC 7591）
你在浏览器中登录并通过钱包签名批准	/oauth/authorize
客户端兑换授权码以获取密钥	POST /oauth/token — 必须使用 PKCE S256（RFC 7636）

授权码只能使用一次，有效期为 60 秒；重定向 URI 设有许可名单，并按 RFC 8252 允许环回地址。颁发的令牌就是 API 密钥，因此可在与其他所有密钥相同的列表中撤销授权。

**可提供资产的链。**订单中需要提供资产时，你必须使用已在相应链上验证过的钱包；密钥最初仅关联其所有者登录时使用的地址——whoami 会列出两者。若要添加其他钱包，请调用 wallet_proof_message 获取确切文本，使用该钱包签名（EVM personal_sign · TRON signMessageV2 · Solana signMessage · Bitcoin BIP-322），然后将签名传给 prove_wallet。钱包证明只会扩大你可交易的范围，不会产生其他影响：它不会成为账户的收款地址，收款地址只能通过钱包会话设置；调用 remove_wallet_proof 即可移除证明。

自行运行托管服务：

docker build -t hashlock-mcp-http .
docker run -p 8080:8080 -e HASHLOCK_V1_URL=https://api.hashlock.markets/v1 hashlock-mcp-http
# or, from source:
pnpm build && HASHLOCK_V1_URL=https://api.hashlock.markets/v1 PORT=8080 pnpm start:http

环境变量：HASHLOCK_V1_URL（开发者 API 基础 URL，默认值为 https://api.hashlock.markets/v1）· PORT（默认值为 8080）。将服务置于反向代理之后，并映射到 /mcp；GET /health 是存活探测端点。

工具（17）

工具	功能
list_assets	资产注册表（SYMBOL@chain 引用、小数位数）
list_open_rfqs	公开 RFQ 看板，可筛选
get_rfq	单个 RFQ / 私有订单
create_rfq	发布公开 RFQ 或私有固定价格订单
cancel_rfq	取消你自己的请求
respond_to_rfq	报价响应 → 开启交易线程
negotiate	message / propose / accept_proposal / accept / reject — 接受时会指定你读取的价格；如果价格已变动，则会被拒绝；你自己的报价或还价也算作你接受，因此你只能接受对方的价格；accept_proposal 会接受对方的还价，并一步达成交易
my_rfqs, my_deals	你的请求和交易线程
deal_status	线程 + 谈判历史 + HTLC 兑换状态
set_settlement_address	为每条链设置你的收款/退款地址
get_deal_secret	本地存储的兑换原像（仅当两条腿都已注资时可用）
reveal_claim	报告链下索赔（密钥 + 交易），以便结算另一条腿
whoami	你通过身份验证的账户
fund_leg	**自主执行：**使用 Agent 自己的密钥在链上为兑换的己方一腿注资（EVM/TRON/BTC/Solana）
claim_leg	**自主执行：**使用原像领取你收到的一腿（会在链上公开密钥）
refund_leg	**自主执行：**你的注资腿超过时间锁后，若无人领取即可取回

金额使用人类可读的十进制字符串（"0.5"）；价格是报价资产的总金额，而非单位价格。错误会返回结构化封装 { error: { code, is_retryable, recovery_hint } }，Agent 可据此分支处理。

完全自主的循环

为兑换涉及的每条链设置密钥后，Agent 可以在没有人工参与的情况下端到端运行： create_rfq/respond_to_rfq → negotiate（接受）→ set_settlement_address（两条链）→ fund_leg → claim_leg。注资/领取操作均使用 Agent 的密钥在本地签名；兑换密钥在本地生成并存储，只有其哈希锁会离开设备。请使用专用密钥，且只存入你打算交易的资金。

原子结算的工作原理

双方都将资金锁定在绑定到相同 sha256(secret) 哈希锁的 HTLC 中——BTC 使用 P2WSH 脚本，EVM/TRON 使用合约。发起方先为长时间锁的一腿注资（使用非对称时间锁，避免任何一方获得免费选择权）。领取其中一腿会在链上公开密钥，从而解锁另一腿。要么两腿都完成结算，要么都在时间锁到期后退款。每条腿的接收方在注资时即固定——公开密钥无法改变资金的去向。

开发

pnpm install
pnpm run build    # tsup → dist/
pnpm run lint     # tsc --noEmit
pnpm test         # vitest

发布时需要更新两个版本号，而且它们并不相同：package.json（以及必须与之匹配的 server.json 中的 packages[0].version）是 npm 包的版本，而 server.json 顶层的 version 则是 MCP Registry 中条目的版本。如果漏改后者，npm 仍会顺利发布，但 registry 会返回 cannot publish duplicate version。然后打标签：git tag v0.8.1 && git push origin v0.8.1 会运行两个工作流。

Node ≥ 20。MIT。