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

--

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 party getting cheated and without parking the funds with a third party?

The answer the industry settled on, years before “intent-based DeFi” became 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 four MCP tools your AI agent can call directly across Ethereum, Bitcoin, and SUI.

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 block height (or timestamp) 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 release paths, mutually exclusive. Either the receiver wins by revealing the preimage, or the sender wins by waiting.

Why this enables atomic cross-chain swaps

Consider Alice wanting to trade ETH for BTC with Bob.

First, Alice generates a random secret s and computes H = sha256(s). She posts an HTLC on Ethereum locking her ETH, payable to Bob upon revealing s, with timelock T_ETH. Bob sees Alice’s HTLC, copies the same H, and posts a corresponding HTLC on Bitcoin locking his BTC, payable to Alice upon revealing s, with timelock T_BTC. Alice claims the BTC by revealing s on Bitcoin — a public on-chain action. Bob now reads s off the Bitcoin chain and uses it to claim the ETH on Ethereum.

Either both trades fill or both refund. There is no scenario in which one side gets the asset and the other doesn’t, provided one critical condition holds:

T_BTC — the receiver’s leg, claimed first — must expire BEFORE T_ETH, the sender’s leg.

If Bob’s BTC HTLC could expire after Alice’s ETH HTLC, Alice could wait until Bob’s leg refunds, then reveal s and claim the ETH leg too — taking both sides. The standard ordering — receiver-first leg expires first, sender-first leg expires later — closes that attack. This timing rule is the only non-obvious part of the protocol; everything else is hashing and signature checks.

How Hashlock Markets wraps this

Hashlock Markets is an intent-based trading protocol. Traders declare what they want; market makers respond with private sealed-bid quotes; the winning quote settles on-chain. The settlement leg is HTLC-atomic across Ethereum (EVM), Bitcoin (script HTLC), and SUI (Move HTLC).

The protocol exposes six MCP tools. Two are for the pricing side — create_rfq and respond_rfq — and four are for the HTLC settlement leg.

create_htlc funds the on-chain HTLC and records the lock tx hash. Both legs of a swap call this once.

withdraw_htlc claims the funds by revealing the 32-byte preimage. The reveal is public; the counterparty uses it to claim the other leg.

refund_htlc returns the funds to the original sender if the timelock has passed and no one withdrew. Sender-only, post-deadline.

get_htlc reads current state for both legs of a trade: contract addresses, lock amounts, timelocks, status.

The MCP layer means an AI agent — Claude Desktop, Cursor, GPT, anything that speaks the Model Context Protocol — can drive the full settlement flow with no smart-contract code on your side. The agent calls create_htlc, polls get_htlc, calls withdraw_htlc when the counterparty’s leg is funded, or calls refund_htlc if the deadline passes.

End-to-end example: an agent settles an ETH→BTC trade

Skipping the RFQ stage — assume the trader and market maker have already agreed on a price via create_rfq and respond_rfq.

The trader agent, wanting to sell ETH for BTC, calls create_htlc with side “sender”, chain “ethereum”, amount 2.0 ETH, hash H, and timelock T_ETH. It receives back a tx hash and contract address. It then polls get_htlc until both legs are funded, confirming the market maker has posted the BTC leg with the same H. It then calls withdraw_htlc on the BTC leg, revealing s — the preimage is now public on the Bitcoin chain.

The market maker agent, on the other side, polls get_htlc, sees the BTC leg has been withdrawn, reads s from on-chain, and calls withdraw_htlc on the Ethereum leg. The trade is settled. Both legs filled atomically.

If at any point the market maker never funds their leg, or either side disappears mid-flow, refund_htlc recovers the funds after the timelock expires. The trader’s leg carries the longer timelock per the rule above, so the safe path is always: claim what’s owed to you first, then refund anything still locked.

Why the design choice matters

Plenty of cross-chain venues skip HTLCs and use a wrapped-asset bridge or a custodial relayer. Both work for happy-path flows, and both add a trust assumption that has been the source of nine of the ten 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. The protocol either fills both sides or returns both sides. 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 three chains because SHA-256 is universal; the script that checks it differs (Solidity, Bitcoin Script, Move), but the cryptographic contract is identical.

Try it

Connect your MCP client to Hashlock Markets in one of two ways. The remote streamable-http transport is preferred: point your MCP config at https://hashlock.markets/mcp with a SIWE bearer token from hashlock.markets/sign/login. Local stdio also works: run the published package via npx -y @hashlock-tech/mcp with the same token in HASHLOCK_ACCESS_TOKEN.

Either way you get the six tools. Six tools, three chains, atomic settlement.

More: https://hashlock.markets