Memos

Memos tell Harbor where to route an inbound deposit and how that destination subnet should process it.

High-Level Memo Model

Memos are interpreted in two layers:

1. XNode routing layer
2. Destination subnet layer (for example, the Smart Order Router)

At a high level:

<subnet_prefix>:<subnet params, colon delimited>

subnet_prefix selects the destination subnet route. subnet params are passed to that subnet as its processing instructions.

Smart Order Router Memo Format

Canonical Format

=:<to_asset>:<to_address>:<quote_out>/<tolerance_bps>[:<affiliate_1>/<affiliate_2>/...[:<affiliate_bps_1>/<affiliate_bps_2>/...]]

Field Semantics and Valid Values

Field	Required	Controls	Valid values / constraints
=: prefix	Yes	Routes to exchange/SOR subnet	Must start with =: for SOR swap memos
to_asset	Yes	Desired output asset	Non-empty string; resolved by SOR market graph (short/alias forms may be accepted)
to_address	Yes	Recipient address on destination chain	Must parse as a valid chain address
quote_out	Yes	Expected net output amount	Positive integer amount (in 1e8). Should be "expectedAmountOut" value from quote endpoint
tolerance_bps	Yes	Slippage tolerance bound below quote_out	Integer basis points, 0 to 9999
affiliate_*	No	Affiliate shortcodes for fee allocation	Slash-delimited list of non-empty shortcodes
affiliate_bps_*	No	Affiliate fee bps per shortcode position	Integer basis points, 0 to 9999

Fuzzy Asset Matching

SOR accepts asset shortcodes in memo to_asset values.

Examples:

• b -> BTC.BTC
• e -> ETH.ETH

Always verify shortcode behavior by requesting a quote with your intended shortcode and confirming the response matches the exact asset you expect before submitting deposits.

Examples

Basic swap:

=:ETH.USDT:0x90f2b1ae50e6018230e90a33f98c7844a0ab635a:224730000000/50

Swaps with two affiliates:

=:b:bc1qy6a8nmnw75fks66rkyvwwa9fd62lnmrz3m87y4:342813/300:sk/t:5/50

In this example:

• b is the to_asset token as provided in memo (resolves to BTC.BTC)
• bc1... is to_address
• 342813/300 is quote_out/tolerance_bps
• sk/t are affiliate shortcodes
• 5/50 are their corresponding bps values

Integration Rules

• It's recommended to use the exact quote.memo from the quote request.

Chain-Specific Submission

Bitcoin and Other UTXO Chains

• Place memo in a dedicated OP_RETURN output.
• Keep OP_RETURN payload within 80 bytes.

Ethereum and EVM Chains

• Pass memo string unchanged to depositWithExpiry(..., memo, expiry).

Related

• Cross-chain Swaps
• Deposit Transactions
• Router Contract