Wire Claude into Hashlock Markets in 10 minutes: a hands-on MCP tutorial

Update, October 2026. This post was first published in April 2026. It has been revised to match the product as it is live today: six mainnet chains (Bitcoin, Ethereum, TRON, Solana, Base, Robinhood Chain), API key authentication, and the current MCP tool set. Current reference: https://docs.hashlock.markets

---

Hashlock Markets is a non-custodial P2P cross-chain swap protocol built around two ideas that DeFi has talked about for years but rarely shipped together: sealed RFQ so quotes are private, and HTLC atomic settlement so cross-chain trades complete or refund as a unit, with no escrow in the middle. Sitting in front of both is a Model Context Protocol (MCP) server, which means any MCP-capable AI agent (Claude, ChatGPT, a custom runtime) can drive the entire trading lifecycle without a human at the console.

This post is the short, practical version: how to set that up, what each piece does, and the tool calls an agent makes in a normal trade.

Step 1: pick a transport

There are two ways to connect an agent to the Hashlock MCP server. They differ in who holds the keys.

Streamable HTTP (hosted). Point your agent at:

https://hashlock.markets/mcp

One URL, no install. This is the right choice for Claude, ChatGPT, custom orchestrators, and anything that can't spawn local processes. The hosted server is strictly non-custodial: it holds no keys, returns unsigned transactions for you to sign, and the initiator keeps the HTLC preimage. Amounts are base-unit integer strings, as in the REST API.

stdio (local). Your agent spawns the server as a child process with your own chain keys in the environment:

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

The package auto-installs from npm as @hashlock-tech/mcp; HASHLOCK_API_URL is required. This server can sign and settle autonomously with the keys you gave it, and stores the swap secret at ~/.hashlock/mcp-secrets.json. Amounts here are human decimal strings such as "0.5".

The hosted server exposes 24 tools and the local one 17; the names differ in places, so Step 3 shows both.

Step 2: authenticate with a wallet signature

Authentication is an API key, and an agent gets one by signing a message with its wallet. No passwords, no email, no browser required.

On the hosted transport the MCP client handles this: the client runs a standard OAuth 2.1 flow with PKCE, you approve with a signature from your wallet, and the client receives its own key. That key appears under hashlock.markets/developers and can be revoked there. Clients that do not speak OAuth send a key you minted yourself: Authorization: Bearer hk_live_....

An agent can also mint a key over REST with no human in the loop: GET /v1/keys/nonce returns a single-use nonce, the agent signs a short message naming Hashlock Markets, create an API key, its address, the scopes it wants and the nonce, and POST /v1/keys with { rail, address, message, signature } returns the key once. The rail is evm, tron, solana or bitcoin.

A few practical implications worth being explicit about:

• Keys expire. Every key works for 90 days and is shown once. A wallet-only account holds one live key, so a fresh signed mint replaces the old one; that is also how an agent recovers a leaked key.
• You can scope the wallet. Give the agent a dedicated trading wallet, funded with a per-day budget, rather than the keys to your main treasury. It then has a hard ceiling, and every action is auditable on chain.
• Payout addresses are protected. Over an API key, money can only go to the account's login wallet or one it has authorised, so a leaked key cannot redirect your funds.

Step 3: understand the tool set

The tools map cleanly onto the trading lifecycle.

RFQ (Request for Quote)

Hosted tool	Local tool	What it does
list_assets, list_open_rfqs, get_rfq	same names	Asset registry (SYMBOL@chain refs such as USDC@base) and the RFQ board.
create_rfq	create_rfq	Declare what you want: "I give X on this chain, I want Y on that chain."
quote_rfq	respond_to_rfq	Used by makers to answer with a price. Opens a private thread.
list_rfq_threads, get_thread	my_rfqs, my_deals	How a taker finds the quotes it received.
propose_price, accept_proposal, accept_terms	negotiate	Counter, take the other side's price, or accept the current terms.

create_rfq is the trader's entry point. Each maker answers in its own thread. No maker sees a competitor's price. That's the sealed part: no public price book, and the intent never hits a public mempool, so no front-running and no MEV tax on the fill.

Every accept names the price the caller read and is refused if the terms moved since. The initiator (the party who funds the long leg) sends hashlock = sha256(secret) with its accept; only the hash leaves the machine. The local server generates the 32-byte secret; on the hosted server you do.

HTLC (Hash Time-Locked Contract) settlement

Hosted tool	Local tool	What it does
set_swap_address	set_settlement_address	Payout address where you receive, refund address where you fund.
build_fund	fund_leg	Lock your side of the trade in an on-chain HTLC against the hashlock.
swap_status, list_swaps	deal_status	Read HTLC state (funded, claimed, refunded) across both legs.
build_claim	claim_leg	Claim the counterparty's locked funds by revealing the preimage.
build_refund	refund_leg	Reclaim your own funds after the timelock if nobody claimed.

The atomic settlement guarantee falls out of the HTLC math. Both legs lock funds against the same sha256 hashlock. The initiator claims the leg it receives on by presenting the secret, which puts it on chain. The counterparty (or Hashlock's keeper on their behalf, on every chain except Bitcoin) uses the same secret to claim the other leg. Either both legs complete, or both refund after their timeouts. There is no state where one side has been paid and the other hasn't.

The timelocks are asymmetric: the initiator funds the long leg, so the counterparty always has time to use the revealed secret before the initiator could refund. Bitcoin legs use 24 hours; Ethereum, Base, Robinhood Chain, TRON and Solana legs use 4 hours.

For an agent running unattended, the practical version of this is: failed steps are safe. A network error during a claim doesn't leave the trader exposed: it can retry, and if it never does, the timelock lets it refund. An agent built on this primitive can be aggressive about retries without putting capital at risk.

Step 4: a normal trade, end to end

Here's the sequence a local, autonomous agent makes to swap ETH on Ethereum for SOL on Solana:

1. create_rfq giving ETH@ethereum, wanting SOL@solana, with the amount and a ttlSeconds. The server returns an RFQ ID.
2. Wait for quotes. Makers answer with respond_to_rfq, each opening a thread. The agent reads them with my_deals, picks the best price (or applies whatever selection logic you've taught it), and calls negotiate with accept_proposal. Both chains have 4-hour timelocks, so on this tie the taker's leg is the long one: our agent is the initiator, and the secret is generated locally with only its hash sent.
3. set_settlement_address for each chain: the Ethereum refund address and the Solana payout address.
4. fund_leg on Ethereum. The initiator funds first.
5. The maker funds the Solana leg against the same hashlock.
6. deal_status to verify both legs are funded.
7. claim_leg on Solana, revealing the preimage. The keeper sees the secret hit the chain and claims the ETH for the maker.
8. deal_status again to confirm both legs are claimed. Trade is done.

If anything stalls (the maker disappears between steps 5 and 7, or a chain congests past the timeout) the agent calls refund_leg and recovers its locked ETH. No loss, no support ticket.

An agent that crashes mid-flow and restarts does not double-spend: it reads the existing state with deal_status (hosted: swap_status) and picks up where it left off. Errors come back as a structured envelope with code, is_retryable and recovery_hint, so the agent can branch on them.

Step 5: example agent prompt

Here's a minimal prompt that gives an agent enough context to operate Hashlock as a tool:

You have access to the Hashlock Markets MCP server. Your job is to swap [from-asset] for [to-asset] in the size the user requested. Use create_rfq to post the request, read the quotes you receive, and accept the best price. Then set your settlement addresses, fund your leg, verify both legs are funded, claim your receive leg, and refund if the counterparty doesn't complete within the timelock. Surface every step's output to the user.

For Claude specifically, that prompt plus the config from Step 1 is enough to start. The model already knows how to call MCP tools; you don't need a custom orchestration layer. The repo also ships an agent skill under skills/hashlock-markets for Claude Code and similar runtimes.

What you get

When the pieces are wired together, the agent's trading surface has properties that are hard to assemble out of public-orderbook DEXs:

• Private quoting. No information leakage while makers price the request.
• Atomic settlement. Both legs complete, or both refund. Nothing in between.
• No front-running, no MEV tax. Quotes never hit a public book or mempool; a public RFQ is visible to makers on the board, but every price stays inside a private thread.
• Cross-chain by default. Bitcoin, Ethereum, TRON, Solana, Base and Robinhood Chain are live on mainnet today.
• Safe to retry. Readable swap state plus HTLC refunds means a crash-restart loop doesn't lose money.

That set of guarantees is what makes the protocol usable by software, not just humans. An AI agent doesn't need to be careful the way a human trader does, because the failure modes are bounded by the protocol itself.

Where to go next

Three pages cover most of what you need:

• Protocol home and live UI: hashlock.markets
• Docs, including the MCP tool reference: docs.hashlock.markets
• Canonical repo, with examples and the agent skill: github.com/Hashlock-Tech/hashlock-mcp

The next decade of DeFi is going to be operated by software, not by humans clicking in browser tabs. The infrastructure for that has to be private, atomic, and cross-chain, and exposed to agents in a way they can actually use. That's the bet behind Hashlock Markets, and the MCP server is the part of it you can plug into your agent today.