Hashlock MCP Server

@hashlock-tech/mcp

Hashlock Markets — the settlement layer for the agent economy, as MCP tools. Non-custodial cross-chain OTC: sealed RFQ + price negotiation + HTLC atomic settlement — both legs settle or both refund; no bridge, no custodian, no counterparty risk. BTC ↔ EVM / TRON / Solana.

Live on mainnet: Bitcoin, Ethereum, Base, Robinhood Chain, TRON, Solana. Use a dedicated key with only the funds you intend to trade.

📖 Documentation: docs.hashlock.markets — concepts, quickstart, guides and the API reference. For agents: llms.txt (index), llms-full.txt (everything in one file), any page as Markdown by adding .md, and a docs-search MCP server at https://docs.hashlock.markets/mcp.

What is this?

The canonical Model Context Protocol server for Hashlock Markets. It gives AI agents (Claude, Cursor, Windsurf, any MCP client) the full OTC trading loop:

1. Browse the asset registry and the public RFQ board
2. Post a public RFQ or a private fixed-price order (shareable link)
3. Respond to requests with a price; negotiate (counter / accept / decline) in the deal thread
4. Agree — both parties accept → an HTLC swap is created
5. Track settlement — who funded, timelocks, tx hashes — and manage receive/refund addresses

Settlement signing (funding and claiming the HTLCs) stays with your own wallet — the server never holds keys or funds. The swap secret is generated locally on your machine and only its sha256 hashlock is sent; retrieve it with get_deal_secret when it's time to claim.

Two ways to run

• Local (stdio) — the npm package below. You run it on your machine with your own keys; it can settle autonomously (SIWE login + on-chain signing with HASHLOCK_*_KEY). Full trust in yourself.
• Remote (hosted, Streamable HTTP) — a public URL (https://hashlock.markets/mcp) anyone can add from Claude / ChatGPT / any MCP client; one-click OAuth, no install. Multi-tenant, so it is strictly non-custodial: settlement returns unsigned transactions you sign with your own wallet, and the server never holds keys or your swap preimage. See Remote (hosted) below.

Install

Local stdio via npx (Claude Desktop / Cursor / Windsurf mcpServers config):

{
  "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)>"
      }
    }
  }
}

Auth — autonomous, per chain

The agent owns its key(s); the server does the login itself (nonce → sign → JWT, refreshed on expiry). The first configured key (EVM → TRON → BTC → Solana) mints the session; each key also signs settlement on its chain.

HASHLOCK_SOLANA_KEY is base58 — the 64-byte export a wallet gives you, or a bare 32-byte seed. It mints the session when it is the only key set, and otherwise sits behind the others in the order above. Either way it proves ownership of the wallet (a signed, nonce-bearing message to /me/link-solana) the first time the agent posts, quotes, accepts or calls whoami, because an order whose give leg is Solana is refused without it — and because it is what puts the agent in the feed for a private order aimed at that wallet. If the account is already linked to a different Solana wallet, that link is left alone; nothing else is blocked, and whoami.solanaLink says so. Solana is also the one chain whose transactions this package does not build: the escrow's ADDRESS is a hash of the agreed terms, so the server composes each one and the agent signs the bytes it is handed. Set the agent's Solana address — whoami returns it as localSigners.addresses.solana — as its settlement address with set_settlement_address before funding.

With none set, read-only tools (list_assets, list_open_rfqs, get_rfq) still work. Use a dedicated key with only the funds you intend to trade.

Required: HASHLOCK_API_URL — the API base, e.g. https://hashlock.markets/api; there is no default. Other env: HASHLOCK_APP_URL (share links; default derived), HASHLOCK_EVM_RPC (default a public Ethereum mainnet RPC; another EVM chain takes HASHLOCK_EVM_RPC_<CHAIN>, e.g. HASHLOCK_EVM_RPC_BASE), HASHLOCK_TRON_HOST (default TronGrid mainnet), HASHLOCK_TRON_API_KEY (a TronGrid API key — TronGrid throttles requests without one), HASHLOCK_SECRETS_PATH (default ~/.hashlock/mcp-secrets.json, mode 0600).

Remote (hosted)

The same server also runs as a remote MCP over Streamable HTTP so anyone can connect by URL — no install. This is the multi-tenant, non-custodial surface: browse, RFQ, negotiate, and get unsigned fund/claim/refund transactions you sign with your own wallet (there is no autonomous key-in-env signing and no server-side secret storage here — you supply your own hashlock and keep your own preimage).

Connect from a client: add the server URL. Nothing else — the client discovers that it needs authorization, sends you to Hashlock to sign in and approve, and receives its own key:

URL: https://hashlock.markets/mcp

Approving takes a signature from your wallet — a signed-in session alone grants nothing. The grant then appears under Developers as an ordinary API key: it expires after 90 days, you are told in Telegram (when linked) whenever one is created, and it can be revoked there at any time. Clients that do not speak OAuth can still send a key they created themselves as Authorization: Bearer hk_….

Agents, with no browser: an agent that holds a wallet key mints its own hk_ key — GET https://hashlock.markets/api/v1/keys/nonce, sign Hashlock Markets — create an API key. plus Address: and Nonce: lines (optionally Key name: and Scopes:), and POST /api/v1/keys with { rail, address, message, signature }. The key belongs to the account that wallet signs in to, created on first use. A wallet-only account holds one key — signing again replaces it, which is also how a lost key is recovered; sign up at /developers with email, Google or Telegram to hold up to 10. See /api/v1/docs.

Standard OAuth 2.1, so any compliant MCP client drives it unattended:

Codes are single-use and expire in 60 seconds; redirect URIs are allowlisted, with loopback permitted per RFC 8252. The issued token IS the API key, so a grant is revocable from the same list as every other key.

Which chains you can give on. An order that GIVES an asset needs a wallet you proved on that chain, and a key starts with only the address its owner signed in with — whoami lists both. To add another, call wallet_proof_message for the exact text, sign it with that wallet (EVM personal_sign · TRON signMessageV2 · Solana signMessage · Bitcoin BIP-322) and pass it to prove_wallet. A proof widens what you can trade and nothing else: it never becomes the account's payout address, which only a wallet session can set, and remove_wallet_proof takes it back.

Run the hosted service yourself:

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

Env: HASHLOCK_V1_URL (developer-API base, default https://api.hashlock.markets/v1) · PORT (default 8080). Put it behind your reverse proxy at /mcp; GET /health is a liveness probe.

Tools (17)

Amounts are human decimal strings ("0.5"); prices are the total quote-asset amount, not per-unit. Errors return a structured envelope { error: { code, is_retryable, recovery_hint } } agents can branch on.

Fully autonomous loop

With a key set for each chain a swap touches, an agent can run end to end with no human: create_rfq/respond_to_rfq → negotiate (accept) → set_settlement_address (both chains) → fund_leg → claim_leg. Funding/claiming is signed locally with the agent's keys; the swap secret is generated + stored locally and only its hashlock leaves the machine. Use a dedicated key with only the funds you intend to trade.

How atomic settlement works

Both parties lock funds in HTLCs bound to the same sha256(secret) hashlock — BTC as a P2WSH script, EVM/TRON as contracts. The initiator funds the long-timelock leg first (asymmetric timelocks, so nobody gets a free option). Claiming one leg reveals the secret on-chain, which unlocks the other leg. Either both legs settle, or both refund after their timelocks. The recipient of each leg is fixed at funding time — revealing the secret cannot redirect funds.

Development

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

Releasing means bumping two version numbers, and they are not the same one: package.json (and server.json's packages[0].version, which must match it) is the npm package, while server.json's own top-level version numbers the entry in the MCP Registry. Leave the second behind and npm publishes happily while the registry answers cannot publish duplicate version. Then tag: git tag v0.8.1 && git push origin v0.8.1 runs both workflows.

Node ≥ 20. MIT.