DEV Community

Baris Sozen
Baris Sozen

Posted on Edited on

Atomic cross-chain trades, explained: a hands-on walkthrough of HTLCs

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


Cross-chain trading has a hard problem at its core: how do you move value between two ledgers that don't speak to each other, without either side getting cheated and without parking the funds with a third party?

The answer the industry settled on, years before "intent-based DeFi" was a phrase, is the Hash Time-Locked Contract, an HTLC. It's the primitive underneath atomic swaps, the Lightning Network, most cross-chain bridges that don't trust an oracle, and the settlement leg of Hashlock Markets.

This post walks through the HTLC mechanism end-to-end, then shows how Hashlock Markets exposes it as a handful of MCP tools your AI agent can call directly across Bitcoin, Ethereum, TRON, Solana, Base and Robinhood Chain.

1. The two locks

An HTLC is a smart contract (or, on Bitcoin, a script) holding funds behind two conditions:

The hashlock. The contract knows a hash H = sha256(s). The funds release to the receiver if and only if the receiver presents the 32-byte preimage s. SHA-256 is a one-way function (knowing H tells you nothing about s), so only the party who originally generated s can reveal it.

The timelock. If nobody presents s before time T, the original sender can call refund and reclaim the funds. The receiver can no longer claim after T.

That's the whole primitive. Two mutually exclusive release paths: the receiver wins by revealing s, or the sender wins by waiting.

2. Why this enables atomic cross-chain swaps

Alice wants to trade BTC for ETH with Bob.

  1. Alice generates a random 32-byte secret s and computes H = sha256(s).
  2. Alice posts an HTLC on Bitcoin locking her BTC, payable to Bob upon revealing s, with timelock T_BTC.
  3. Bob sees Alice's HTLC, copies the same H, and posts a corresponding HTLC on Ethereum locking his ETH, payable to Alice upon revealing s, with timelock T_ETH.
  4. Alice claims the ETH by revealing s on Ethereum. The reveal is a public on-chain action.
  5. Bob now reads s off the Ethereum chain and uses it to claim the BTC on Bitcoin.

Either both legs fill or both refund. One side cannot get the asset while the other doesn't, provided one critical condition holds:

T_ETH (the leg Alice claims first) must expire BEFORE T_BTC (the leg Alice funded).

If Bob's ETH HTLC could expire after Alice's BTC HTLC, Alice could wait until her own leg refunds, then reveal s and claim the ETH leg too, taking both sides. The standard ordering, the leg claimed first expires first, the secret holder's leg expires later, closes that attack. This timing rule is the only non-obvious part; everything else is just hashing and signature checks.

Hashlock Markets bakes the rule in. The secret holder is the initiator and always funds the long leg. Safe timelocks are 24 hours on Bitcoin and 4 hours on every other chain, so in the example above the Bitcoin leg is long at 24 h and the Ethereum leg is short at 4 h.

3. How Hashlock Markets wraps this

Hashlock Markets is a sealed RFQ protocol: takers post what they want, makers answer with private quotes, both sides accept in a thread, and the agreed swap settles on-chain. The settlement leg is HTLC-atomic across Bitcoin (P2WSH script), the EVM chains (Ethereum, Base, Robinhood Chain), TRON and Solana, live on mainnet on all six.

The hosted MCP server exposes 24 tools. Pricing is create_rfq, quote_rfq and the negotiation tools; the HTLC settlement leg is driven by these:

Tool Who calls it What it does
build_fund Both legs Unsigned funding transaction for the leg you give. Called once per leg.
build_claim Receiver Unsigned claim that reveals the 32-byte preimage. The reveal is public; the counterparty uses it to claim the other leg.
build_refund Funder, post-deadline Unsigned refund once the timelock has passed and no one claimed.
broadcast_tx Either side Relays a transaction you signed.
swap_status Either side State of both legs: addresses, timelocks, tx hashes, status.

The hosted server is strictly non-custodial: it builds transactions, you sign them, and only the hashlock ever leaves the initiator's machine.

The MCP layer means an AI agent (Claude, ChatGPT, anything that speaks the Model Context Protocol) can drive the full settlement flow with no smart-contract code on your side: build_fund, poll swap_status, build_claim once the counterparty's leg is funded, or build_refund if the deadline passes.

4. End-to-end example: an agent settles a BTC-for-ETH trade

Skipping the RFQ stage (assume a price was agreed via create_rfq and quote_rfq, and the trader, as initiator, sent hashlock = sha256(s) with the accept; set_swap_address has been called for both legs):

[Trader agent, the initiator: sells BTC for ETH]

1. build_fund { swapId, leg: "b" }   // leg b is the taker's leg, here the Bitcoin leg
   -> unsigned funding tx for the long leg; sign, broadcast_tx

2. swap_status { swapId }
   -> polls until status is counterparty_funded
   -> confirms the MM has posted the ETH leg with the same hashlock

3. build_claim { swapId, leg: "a", secret: s }   // leg a is the maker's leg, here the Ethereum leg
   -> sign and broadcast_tx
   -> s is now public on Ethereum

[MM agent, the counterparty: sells ETH for BTC]

4. swap_status { swapId }
   -> sees initiator_claimed, reads s from the swap state

5. build_claim { swapId, leg: "b", secret: s }
   -> sign and broadcast_tx, claims BTC

[Settled. Both legs filled atomically.]
Enter fullscreen mode Exit fullscreen mode

On every chain except Bitcoin, step 5 is optional: once the secret is revealed, Hashlock's keeper claims that leg to its fixed recipient. A Bitcoin claim needs the receiver's own signature.

If the MM never funds their leg, or either side disappears mid-flow, build_refund recovers the funds after the timelock. The initiator's leg carries the longer timelock, so the safe path is always: claim what's owed to you first, then refund anything still locked.

5. Why the design choice matters

Plenty of cross-chain venues skip HTLCs and use a wrapped-asset bridge or a custodial relayer. Both work on the happy path, and both add a trust assumption that has been behind many of the largest exploits in the space.

HTLCs trade off a little latency (you pay for the timelock window) for a very specific guarantee: at no point does any party hold the other party's asset without an enforceable reason to release it. Both sides fill or both refund. There's no "stuck funds" state that requires governance intervention.

That property is what lets Hashlock Markets settle across heterogeneous chains, including Bitcoin, which has no smart contracts in the EVM sense, without trusting a custodian. The same hash works on all six chains because SHA-256 is universal (Bitcoin Script has OP_SHA256 but no keccak, so the EVM and TRON contracts use sha256 too); the code that checks it differs, but the cryptographic contract is identical.

6. Try it

Connect your MCP client to Hashlock Markets:

Hosted (preferred): add this URL to your MCP client. It sends you to Hashlock to approve with a wallet signature and receives its own API key over OAuth 2.1. Clients that do not speak OAuth send Authorization: Bearer hk_live_...; keys last 90 days.

https://hashlock.markets/mcp
Enter fullscreen mode Exit fullscreen mode

Local stdio: run the published package with your own chain keys. It signs and settles for you (fund_leg, claim_leg, refund_leg) and stores the secret locally.

{
  "mcpServers": {
    "hashlock": {
      "command": "npx",
      "args": ["-y", "@hashlock-tech/mcp"],
      "env": {
        "HASHLOCK_API_URL": "https://hashlock.markets/api",
        "HASHLOCK_EVM_KEY": "0x<agent EVM key>"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Either way you get the full tool set (24 hosted, 17 local), six chains, atomic settlement.

Docs: https://docs.hashlock.markets
More: https://hashlock.markets
GitHub: https://github.com/Hashlock-Tech/hashlock-mcp
npm: https://www.npmjs.com/package/@hashlock-tech/mcp

Top comments (0)