Hashlock MCP README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Hashlock MCP listing page.
@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.
⚠️ Testnets only for now (Ethereum Sepolia · TRON Nile · Bitcoin signet). Mainnet comes after the security-hardening gate — do not send real funds.
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:
- Browse the asset registry and the public RFQ board
- Post a public RFQ or a private fixed-price order (shareable link)
- Respond to requests with a price; negotiate (counter / accept / decline) in the deal thread
- Agree — both parties accept → an HTLC swap is created
- 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://dev.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):
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) mints the session; each key also signs settlement on its chain.
| Env var | Chain | Login |
|---|---|---|
HASHLOCK_EVM_KEY | EVM | SIWE personal_sign |
HASHLOCK_TRON_KEY | TRON | signMessageV2 |
HASHLOCK_BTC_KEY | Bitcoin | BIP-322 |
HASHLOCK_TOKEN | — | a ready JWT (alternative to a key) |
With none set, read-only tools (list_assets, list_open_rfqs, get_rfq) still work. Use dedicated testnet keys.
Other env: HASHLOCK_API_URL (default https://dev.hashlock.markets/api), HASHLOCK_APP_URL (share links; default derived), HASHLOCK_EVM_RPC (default a public Sepolia RPC), HASHLOCK_TRON_HOST (default Nile), 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:
The grant then appears under Developers as an ordinary API key
and 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_….
How the OAuth flow works
Standard OAuth 2.1, so any compliant MCP client drives it unattended:
| Step | Endpoint |
|---|---|
| Unauthorized call names its metadata | 401 + WWW-Authenticate: … resource_metadata=… (RFC 9728) |
| Client reads the resource + server metadata | /.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server (RFC 8414) |
| Client registers itself | POST /oauth/register (RFC 7591) |
| You sign in and approve, in the browser | /oauth/authorize |
| Client redeems the code for a key | POST /oauth/token — PKCE S256 required (RFC 7636) |
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.
Testnets only until the hardening gate.
Run the hosted service yourself:
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 (16)
| Tool | What it does |
|---|---|
list_assets | Asset registry (SYMBOL@chain refs, decimals) |
list_open_rfqs | Public RFQ board, filterable |
get_rfq | One RFQ / private order |
create_rfq | Post a public RFQ or private fixed-price order |
cancel_rfq | Cancel your own request |
respond_to_rfq | Respond with a price → opens a deal thread |
negotiate | message / propose / accept_proposal / accept / reject |
my_rfqs, my_deals | Your requests and deal threads |
deal_status | Thread + negotiation history + HTLC swap state |
set_settlement_address | Your receive/refund address per chain |
get_deal_secret | The locally-stored swap preimage (gated on both legs funded) |
reveal_claim | Report an out-of-band claim (secret + tx) so the other leg settles |
whoami | The account you're authenticated as |
fund_leg | Autonomous: fund your side of a swap on-chain with the agent's own key (EVM/TRON/BTC) |
claim_leg | Autonomous: claim your receive leg with the preimage (reveals the secret on-chain) |
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 dedicated testnet keys.
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
Node ≥ 20. MIT.