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

#mcp #ai #cryptocurrency #blockchain

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 four MCP tools your AI agent can call directly across Ethereum, Bitcoin, and SUI.

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 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 s, or the sender wins by waiting.

2. Why this enables atomic cross-chain swaps

Consider Alice wanting to trade ETH for BTC with Bob.

Alice generates a random secret s and computes H = sha256(s).
Alice 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. The reveal is 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 just hashing and signature checks.

3. 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, respond_rfq), and four are for the HTLC settlement leg:

Tool	Who calls it	What it does
`create_htlc`	Both legs	Funds the on-chain HTLC and records the lock tx hash. Called once per leg of the swap.
`withdraw_htlc`	Receiver	Claims the funds by revealing the 32-byte preimage. The reveal is public; the counterparty uses it to claim the other leg.
`refund_htlc`	Sender, post-deadline	Returns the funds to the original sender if the timelock has passed and no one withdrew.
`get_htlc`	Either side	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.

4. 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):

[Trader agent — wants to sell ETH for BTC]

1. create_htlc { tradeId, side: "sender", chain: "ethereum",
                 amount: "2.0", token: "ETH",
                 hash: H, timelock: T_ETH }
   → returns tx hash, contract address

2. get_htlc { tradeId }
   → polls until both legs are funded
   → confirms MM has posted the BTC leg with the same H

3. withdraw_htlc { tradeId, leg: "btc", preimage: s }
   → claims BTC by revealing s
   → s is now public on the Bitcoin chain

[MM agent — was selling BTC for ETH]

4. get_htlc { tradeId }
   → sees the BTC leg has been withdrawn, reads s from on-chain

5. withdraw_htlc { tradeId, leg: "ethereum", preimage: s }
   → claims ETH

[Settled. Both legs filled atomically.]

If at any point the MM never funds their leg, or either side disappears mid-flow, refund_htlc recovers the funds after the timelock expires. The trader's leg is set with 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.

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 for happy-path flows, 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.