Memoless Swaps (Bitcoin and Limited Memo Chains)

For chains with limited memo space (like Bitcoin's 80-byte OP_RETURN), THORChain supports memoless transactions using reference memos. This guide provides a quick start for implementing memoless swaps.

Overview

Memoless swaps allow you to:

• Register a swap memo once, use multiple times
• Encode reference numbers in transaction amounts
• Avoid memo length restrictions on UTXO and other memo-limited chains

Memoless Swap Checklist

Phase 1: Register Reference Memo

1. Send Registration Transaction: Send RUNE to inbound address with memo:

   REFERENCE:BTC.BTC:=:ETH.ETH:0x86d526d6624AbC0178cF7296cD538Ecc080A95F1
   

   See REFERENCE memo format for details.

2. Wait for Confirmation: Monitor the registration transaction hash

3. Get Reference Number: Call GET /thorchain/memo/{registration_hash} once block is final

   {
     "reference": "20002",
     "asset": "BTC.BTC",
     "memo": "=:ETH.ETH:0x86d526d6624AbC0178cF7296cD538Ecc080A95F1",
     "height": "12345678"
   }
   

Phase 2: Execute Memoless Swap

1. Validate Reference: Call GET /thorchain/memo/BTC.BTC/20002 before broadcasting

   • Ensure response is valid and not expired
   • Check usage count within limits
   • Verify reference lifecycle state

2. Encode Amount:

   Desired amount: 0.05 BTC = 5,000,000 sats
   Reference: 20002
   Final amount: 5,020,002 sats
   

   See Encoding Algorithm for detailed steps.

3. Send Bitcoin Transaction:

   • Amount: 5,020,002 sats
   • To: BTC inbound address from /thorchain/inbound_addresses
   • Memo: Empty (reference encoded in amount) or R:20002 (explicit reference)

   See Sending Transactions - UTXO Chains for transaction structure.

4. Monitor Results: Reference will be marked as used and require re-registration for future swaps

   Check usage via GET /thorchain/memo/BTC.BTC/20002

Memoless Error Conditions

Memoless Transaction Errors

Reference Not Found Error

{ "error": "reference memo not found for asset BTC.BTC reference 20002" }

Resolution: Re-register the reference memo or verify reference number

Reference Expired Error

{ "error": "reference memo expired for asset BTC.BTC reference 20002" }

Resolution: Register a new reference memo with same parameters. References expire after MemolessTxnTTL blocks (default: 3600 blocks ≈ 6 hours).

Usage Limit Exceeded Error

{ "error": "reference memo usage limit exceeded for reference 20002" }

Resolution: Register a new reference memo for additional uses. Default limit is MemolessTxnMaxUse = 1 use per reference.

Same Height Usage Error

{ "error": "transaction observed before reference memo creation" }

Resolution: Wait for next block after registration before using reference. Transactions must be observed after the reference registration height.

Memoless Halted Error

{ "error": "memoless transactions are currently halted" }

Resolution: Check THORChain status - emergency halt is active. Monitor HaltMemoless mimir and wait for unhalt before attempting memoless transactions.

Pre-Flight Validation API

Always validate before broadcasting:

# Check if reference exists and is valid
GET /thorchain/memo/{asset}/{reference}

# Preview reference extraction from amount
GET /thorchain/memo/check/{asset}/{amount}

Best practice

• Use RBF/fee-bump to accelerate confirmation if mempool congestion increases.
• If confirmation before TTL looks unlikely, RBF-cancel (double-spend to self) and re-register a fresh reference, then resend.
• Don’t broadcast close to expiry; choose a feerate that targets confirmation well within the TTL (with buffer).

See API Endpoints for full documentation.

Related Documentation

• Memos - Reference Memo Technical Details
• Reference Memo Lifecycle States
• Amount Encoding Algorithm
• Sending Transactions - UTXO Chains
• Memoless Transaction Mimirs
• Network Halts - Memoless