hashlock-mcp

Purpose

Hashlock MCP is the canonical Model Context Protocol (MCP) server for Hashlock Markets, providing non-custodial, cross-chain over-the-counter trading capabilities for AI agents (Claude, Cursor, Windsurf, or any MCP client) and institutional OTC trading desks. At its core, it fuses sealed RFQ, price negotiation, and HTLC atomic settlement into a single operation, serving as the atomic settlement layer in the agent economy.

Main Capabilities

Through this server, agents can complete the full OTC trading loop: browse the asset registry and public RFQ board; post public RFQs or private fixed-price orders (with shareable links); quote on requests and negotiate with counteroffers, acceptances, or rejections; create an HTLC swap once both parties accept; track settlement status (who has funded, time locks, transaction hashes), and manage receiving/refund addresses.

Signing for settlement (funding and claiming HTLCs) is always done by the user's own wallet; the server never holds keys or funds. The swap secret is generated on the local machine, and only its sha256 hash lock is sent out; when claiming is needed, it can be retrieved with get_deal_secret.

Usage

Two ways to run:

• Local (stdio): runs on the user's machine via the npm package, uses their own keys, and can optionally be configured with HASHLOCK_*_KEY for autonomous settlement (SIWE login + on-chain signing). Example configuration is as follows (mcpServers configuration for Claude Desktop / Cursor / Windsurf):

npx @hashlock-tech/mcp

Required environment variable: HASHLOCK_API_URL (API base URL, e.g. https://hashlock.markets/api , no default). Other optional variables: HASHLOCK_APP_URL (share links, derived automatically by default), HASHLOCK_EVM_RPC (defaults to the public Ethereum mainnet RPC; for other EVM chains use HASHLOCK_EVM_RPC_<CHAIN>, e.g. HASHLOCK_EVM_RPC_BASE), HASHLOCK_TRON_HOST (defaults to TronGrid mainnet), HASHLOCK_TRON_API_KEY (TronGrid API key; rate limiting occurs if missing), HASHLOCK_SECRETS_PATH (defaults to ~/.hashlock/mcp-secrets.json, permissions 0600).

Regarding authentication: the agent has its own keys, and the server completes login itself (nonce → signature → JWT, automatically refreshed on expiration). The first configured key (priority EVM → TRON → BTC → Solana) mints the session, and each key also signs settlements for its own chain. HASHLOCK_SOLANA_KEY is in base58 format (the 64-byte wallet export or the bare 32-byte seed). When no key is set, read-only tools (list_assets, list_open_rfqs, get_rfq) are still available. It is recommended to use a dedicated key containing only the funds intended for trading.

• Remote (hosted, Streamable HTTP): public URL https://hashlock.markets/mcp , any MCP client can add it via URL, one-click OAuth, no installation required. This is a multi-tenant, strictly non-custodial interface: browse, post RFQs, negotiate, and obtain unsigned funding/claiming/refund transactions to be signed by the user's own wallet (no autonomous environment key signing, and no server-side secret storage; users provide their own hash locks and keep the preimage). To connect, the client only needs to add the server URL; the client will discover that authorization is required, guide the user to log in to Hashlock and approve, and then obtain their own key. Approval requires a wallet signature; the login session alone grants no permissions. Authorization appears in Developers as an ordinary API key: it expires after 90 days, is notified via Telegram at creation time (if Telegram is linked), and can be revoked at any time. Clients that do not support OAuth can still send a self-created key as Authorization: Bearer hk_….

Agents without a browser: an agent holding a wallet key can mint an hk_ key itself—GET https://hashlock.markets/api/v1/keys/nonce , sign the "Hashlock Markets — create an API key." text along with the Address: and Nonce: lines (optionally Key name: and Scopes:), then POST /api/v1/keys with { rail, address, message, signature }. The key belongs to the account logged in with that wallet and is created on first use. A wallet-only account holds one key — signing again replaces it, which is also how a lost key is recovered; registering with email, Google, or Telegram via /developers allows up to 10 keys. See /api/v1/docs for details.

Using standard OAuth 2.1, any compliant MCP client can run unattended: the authorization code is single-use and expires in 60 seconds; redirect URIs are allowlisted, and loopback addresses are permitted per RFC 8252. The issued token is itself the API key, so authorization can be revoked in the same list as other keys.

On which chains assets can be "given": an order that gives an asset requires a wallet that the user has proven on that chain, and a key initially contains only the address used by its owner at login — whoami lists both. To add other addresses, call wallet_proof_message to get the exact text, sign it with that wallet (EVM personal_sign · TRON signMessageV2 · Solana signMessage · Bitcoin BIP-322), and pass it to prove_wallet. Proof only expands the tradable scope; it does not become the account's receiving address (the receiving address can only be set by a wallet session). remove_wallet_proof can withdraw it.

Run the hosted service yourself: environment variables HASHLOCK_V1_URL (developer API base address, default https://api.hashlock.markets/v1 ) and PORT (default 8080 ). Place the service behind a reverse proxy at the /mcp path; GET /health is the liveness probe.

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

When to use

• Autonomous AI agent OTC trading: after setting up keys for each chain involved, the agent can run unattended end to end: create_rfq / respond_to_rfq → negotiate (accept) → set_settlement_address (both chains) → fund_leg → claim_leg. Funding/claiming is signed locally with the agent key; the swap secret is generated and stored locally, and only the hashlock leaves the machine.
• Institutional OTC trading desk: sealed quotes and negotiation through a native MCP interface.
• Scenarios requiring cross-chain atomic settlement without relying on bridges or custodians.

Limitations and caveats

• It is recommended to use a dedicated key containing only the funds intended for trading.
• Solana is the only chain where transactions are not constructed by this package: the escrow address is the hash of the agreed terms, so the server is responsible for assembling each transaction, and the agent signs the received bytes. Before funding, set this agent's Solana address (returned by whoami as localSigners.addresses.solana) as the settlement address with set_settlement_address.
• The hosted remote service is multi-tenant and strictly non-custodial: no autonomous environment key signing, and no server-side secret storage.
• Authentication: authorization codes are single-use and expire in 60 seconds; API keys expire after 90 days.
• Release process: you must update both package.json (and packages[0].version in server.json) and the top-level version in server.json, otherwise the registry will reject duplicate versions; then tag to trigger the workflow.
• Runtime requirements: Node ≥ 20, MIT license.

How atomic settlement works

Both parties lock funds in an HTLC bound to the same sha256(secret) hashlock — Bitcoin uses a P2WSH script, EVM/TRON use a contract. The initiator first funds the long-timelock leg (nonSymmetric time locks, preventing either party from getting a free option). Claiming one leg reveals the secret on-chain, thereby unlocking the other leg. Either both legs settle, or both legs are refunded after their respective time locks. The recipient of each leg is fixed at the time of funding—revealing the secret cannot change the flow of funds.

(Documentation: docs.hashlock.markets — concepts, quick start, guides, and API reference. For agents: llms.txt index, llms-full.txt complete single file, any page plus .md converts to Markdown, documentation search MCP server located at https://docs.hashlock.markets/mcp 。）