Six MCP tools, one trade: walking an AI agent from RFQ to refund

ids force each maker to quote their true price based on their internal models, ensuring market efficiency. 2. Atomic HTLC: Settlement uses a hashlock and timelock. The taker locks funds against a hash; the maker locks the mirror leg against the same hash. The claim of one leg reveals the preimage, which is required to claim the other. This ensures that either both legs settle or neither does. 3. Deterministic Refund: The timelock acts as a safety valve. If the settlement window expires without a claim, funds refund automatically. This is the critical enabler of autonomy. 4. Forward Extension: The HTLC primitive supports deferred settlement. Agents can agree on a price today and set a timelock for T+N hours. No margin or clearinghouse is required because the assets are locked upfront. If one party no-shows, the other receives a refund.

Implementation Example

The following TypeScript example demonstrates an AtomicTradeOrchestrator that utilizes MCP tools to manage the trade lifecycle. This implementation abstracts the tool calls into a structured workflow, emphasizing error handling and refund monitoring.

import { McpClient } from 'hashlock-tech/mcp';

interface TradeIntent {
  pair: string;
  amount: bigint;
  direction: 'BUY' | 'SELL';
  expiry: number; // Unix timestamp
  hashLock: string;
  timelock: number; // Seconds
}

interface QuoteResponse {
  makerId: string;
  price: bigint;
  signature: string;
}

export class AtomicTradeOrchestrator {
  private client: McpClient;

  constructor(config: { endpoint: string; apiKey: string }) {
    this.client = new McpClient(config);
  }

  // Phase 1: Sealed-Bid Discovery
  async initiateTrade(intent: TradeIntent): Promise<QuoteResponse | null> {
    // Broadcast sealed RFQ. Makers cannot see competing bids.
    const rfqId = await this.client.submitSealedRfq({
      pair: intent.pair,
      size: intent.amount.toString(),
      direction: intent.direction,
      expiry: intent.expiry,
      hash: intent.hashLock
    });

    // Poll for responses until expiry
    const quotes = await this.client.pollQuotes(rfqId, intent.expiry);
    
    // Select best quote (e.g., lowest price for BUY)
    const bestQuote = this.selectBestQuote(quotes, intent.direction);
    if (!bestQuote) return null;

    return bestQuote;
  }

  // Phase 2: Atomic Settlement
  async executeSettlement(intent: TradeIntent, quote: QuoteResponse): Promise<boolean> {
    // Taker locks assets in HTLC
    const takerLockTx = await this.client.initiateAtomicLock({
      asset: intent.pair.split('/')[0],
      amount: intent.amount.toString(),
      hash: intent.hashLock,
      timelock: intent.timelock,
      recipient: quote.makerId
    });

    // Maker locks mirror leg (handled by maker agent, but taker monitors)
    const makerLockStatus = await this.client.verifyMirrorLock({
      hash: intent.hashLock,
      expectedAmount: quote.price.toString()
    });

    if (!makerLockStatus.confirmed) {
      throw new Error('Mirror lock not found; initiating refund.');
    }

    // Taker claims maker's leg, revealing preimage
    const claimTx = await this.client.claimLockedAssets({
      lockId: makerLockStatus.lockId,
      preimage: this.derivePreimage(intent.hashLock) // Preimage must be kept secret until claim
    });

    // Maker will use revealed preimage to claim taker's leg automatically
    return claimTx.success;
  }

  // Phase 3: Unwind / Refund
  async monitorAndRefund(intent: TradeIntent): Promise<void> {
    // Critical: Monitor timelock to ensure refund if counterparty fails
    const currentBlock = await this.client.getBlockTimestamp();
    const deadline = intent.expiry + intent.timelock;

    if (currentBlock >= deadline) {
      // Execute refund if not settled
      const refundResult = await this.client.executeRefund({
        lockId: intent.hashLock,
        reason: 'TIMELock_EXPIRED'
      });

      if (!refundResult.success) {
        console.error('Refund failed; manual intervention required.');
      }
    }
  }

  private selectBestQuote(quotes: QuoteResponse[], direction: 'BUY' | 'SELL'): QuoteResponse | null {
    if (quotes.length === 0) return null;
    return quotes.reduce((best, current) => 
      direction === 'BUY' 
        ? (current.price < best.price ? current : best)
        : (current.price > best.price ? current : best)
    );
  }

  private derivePreimage(hash: string): string {
    // In production, preimage is generated and stored securely
    // This is a placeholder for the secret derivation logic
    return 'SECRET_PREIMAGE_HEX';
  }
}

Rationale

• Sealed RFQ Submission: The submitSealedRfq call ensures that the RFQ is broadcast without revealing other bids. This prevents maker agents from gaming the auction.
• Mirror Lock Verification: Before claiming, the taker verifies the maker has locked the corresponding assets. This prevents the taker from claiming without the maker being committed.
• Refund Monitoring: The monitorAndRefund method is essential. Autonomous agents must actively watch for timelock expiry to trigger refunds. Relying on the contract alone is insufficient if the agent needs to manage state or gas costs.
• Preimage Secrecy: The preimage must be derived and stored securely. Revealing it prematurely allows the counterparty to claim assets without fulfilling their obligation.

Pitfall Guide

1. Non-Sealed Bid Auctions

   • Explanation: Allowing makers to see competing quotes leads to price shading. Maker agents will adjust bids based on observed competition, resulting in suboptimal pricing and reduced liquidity.
   • Fix: Enforce sealed-bid RFQ structures where responses are submitted without visibility into other bids.

2. Preimage Leakage

   • Explanation: If the preimage is transmitted off-chain or logged before the on-chain claim, the counterparty can front-run the transaction and claim assets without locking their own.
   • Fix: Keep the preimage in secure memory. Reveal it only via the atomic claim transaction. Never log or transmit the preimage in plaintext.

3. Ignoring Refund Mechanisms

   • Explanation: Failing to monitor timelocks results in stuck funds if the counterparty crashes or the network congests. This breaks autonomy and requires manual recovery.
   • Fix: Implement a dedicated refund monitor that triggers executeRefund when the timelock expires. Treat refund execution as a critical path.

4. Timelock Hierarchy Violation

   • Explanation: If the maker's timelock is shorter than the taker's, the maker can claim and refund before the taker can claim, leaving the taker with no assets and no refund.
   • Fix: Ensure the maker's timelock is strictly longer than the taker's timelock. Validate this constraint before locking assets.

5. Hash Mismatch

   • Explanation: The maker uses a different hash than the taker, preventing the preimage from unlocking both legs. This breaks atomicity.
   • Fix: Validate that the maker's lock uses the exact same hash as the taker's RFQ. Reject any mismatched locks immediately.

6. Gas Volatility During Refund

   • Explanation: High gas prices can prevent refund transactions from being mined, causing funds to remain locked even after the timelock expires.
   • Fix: Use gas estimation with a buffer. Consider meta-transactions or layer-2 solutions if gas volatility is a concern. Monitor gas markets and retry with adjusted fees.

7. Cross-Chain Synchronization Lag

   • Explanation: In cross-chain swaps, one chain may confirm the lock while the other lags. Agents may timeout waiting for confirmation, missing the settlement window.
   • Fix: Implement adaptive polling intervals. Use block confirmations rather than transaction receipts for finality. Allow for network-specific latency in timelock calculations.

Production Bundle

Action Checklist

• Implement Sealed-Bid Validation: Ensure RFQ tools enforce sealed submissions and prevent quote visibility.
• Configure Refund Monitors: Deploy background processes to monitor timelocks and trigger refunds automatically.
• Validate Timelock Hierarchy: Enforce maker timelock > taker timelock in all settlement logic.
• Secure Preimage Management: Store preimages in secure memory; prevent leakage via logs or off-chain transmission.
• Test Cross-Chain Scenarios: Validate settlement flows on Ethereum mainnet, Sui, and Bitcoin signet to ensure compatibility.
• Monitor Gas Markets: Implement dynamic gas estimation to ensure refund and claim transactions are mined promptly.
• Audit Contract Interactions: Verify that MCP tools interact with deployed contracts correctly and handle reverts gracefully.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Spot Swap	HTLC Atomic Swap	Immediate settlement with zero counterparty risk.	Low (Gas fees only)
Forward Contract	HTLC with Extended Timelock	Binds price today, settles later without margin.	Medium (Lock-up capital)
Unidirectional Payment	Payment Rail (x402/AP2)	Optimized for speed and low cost; no settlement needed.	Low (Rail fees)
High-Value Trade	HTLC with Refund Monitor	Deterministic refund ensures capital safety.	Medium (Monitoring overhead)

Configuration Template

# mcp-settlement-config.yaml
mcp:
  endpoint: "https://api.hashlock.markets/v1"
  api_key: "${MCP_API_KEY}"
  
chains:
  ethereum:
    rpc_url: "${ETH_RPC_URL}"
    contract_address: "0x..."
    timelock_buffer: 300 # seconds
  sui:
    rpc_url: "${SUI_RPC_URL}"
    contract_address: "0x..."
    timelock_buffer: 120

security:
  preimage_storage: "secure_memory"
  log_level: "warn" # Prevent preimage leakage
  refund_monitor:
    enabled: true
    interval: 60 # seconds
    max_retries: 5

Quick Start Guide

1. Install MCP Package: Add hashlock-tech/mcp to your project dependencies.

   npm install hashlock-tech/mcp
   

2. Configure Environment: Set up RPC URLs, API keys, and contract addresses in your environment variables.
3. Initialize Orchestrator: Instantiate the AtomicTradeOrchestrator with your configuration.

   const orchestrator = new AtomicTradeOrchestrator({
     endpoint: process.env.MCP_ENDPOINT,
     apiKey: process.env.MCP_API_KEY
   });
   

4. Run Trade Flow: Execute the trade lifecycle by calling initiateTrade, executeSettlement, and monitorAndRefund.

   const intent = { pair: 'ETH/USDC', amount: 1000n, direction: 'BUY', expiry: Date.now() + 3600, hashLock: '...', timelock: 1800 };
   const quote = await orchestrator.initiateTrade(intent);
   if (quote) {
     await orchestrator.executeSettlement(intent, quote);
   }
   orchestrator.monitorAndRefund(intent);
   

5. Verify On-Chain: Check transaction hashes on Etherscan or the relevant block explorer to confirm settlement or refund.

The hashlock-tech/mcp package enables end-to-end autonomous settlement on Ethereum mainnet today. Sui contracts are deployed and CLI-tested, with gateway wiring in progress. Bitcoin signet validation is complete, with mainnet pending. For formal treatment of the protocol design, refer to the SSRN paper documentation. This architecture provides the settlement primitive necessary for agents to trade safely, ensuring that every trade resolves atomically or refunds deterministically.