Skip to main content

Memos

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

<route_prefix>:<route params, colon delimited>

Memo Families​

Harbor currently recognizes these top-level memo families:

Memo prefixPurpose
emptyCredit a trading sub-account owned by the depositor, when no deposit channel claims the tx.
d:Credit a trading sub-account owned by an explicit signer: d:<CHAIN>:<L1_ADDRESS>. Supported signer chains are ETH and BTC.
o:Deposit-driven order-book limit order: o:<ToAsset>:<ToAddress[/RefundAddress]>:<Price>/<TtlSeconds>[:<aff...>[:<affBps...>]].
=:Swap / gas-account memo family. The exact memo =: credits the gas account; =:<to_asset>:... creates a swap.

Swap Memos​

Canonical Format​

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

Fields​

FieldRequiredControlsValid values / constraints
=: prefixYesRoutes to exchange / order routerMust start with =: for order router swap memos
to_assetYesDesired output assetNon-empty string; resolved by the order router market graph (short/alias forms may be accepted)
to_addressYesRecipient address on destination chainMust parse as a valid chain address
refund_addressNoOverride the default refund recipient on the source chainAppended to to_address with /. Must parse as a valid source-chain address. If omitted, refunds go to the source-chain from address
quote_outYesExpected net output amountPositive integer amount (in 1e8). Should be "expectedAmountOut" value from quote endpoint
tolerance_bpsYesSlippage tolerance bound below quote_outInteger basis points, 0 to 9999
affiliate_*NoAffiliate shortcodes for fee allocationSlash-delimited list of non-empty shortcodes
affiliate_bps_*NoAffiliate fee bps per shortcode positionInteger basis points, 0 to 9999

Asset Shortcodes​

The order router accepts asset shortcodes in to_asset, for example b for BTC.BTC and e for ETH.ETH. Verify shortcode behavior with a quote before submitting deposits.

Examples​

Basic swap (BTC → ETH.USDT):

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

With a custom refund address (ETH.USDT → BTC, refund to a specific Ethereum address):

=:BTC.BTC:bc1qy6a8nmnw75fks66rkyvwwa9fd62lnmrz3m87y4/0xb38e8c17e38363af6ebdcb3dae12e0243582891d:342813/300

Swap with two affiliates:

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

Trading Deposit Memos​

d: Trading Credit​

d:<CHAIN>:<L1_ADDRESS>

Credits the deposit to the trading account controlled by <CHAIN>/<L1_ADDRESS>, regardless of the sender. Use this for smart-contract wallets and routers that can deposit but cannot sign Harbor trading envelopes directly. Supported signer chains are ETH and BTC.

o: Deposit-Driven Limit Order​

o:<ToAsset>:<ToAddress[/RefundAddress]>:<Price>/<TtlSeconds>[:<affiliate_1>/<affiliate_2>/...[:<affiliate_bps_1>/<affiliate_bps_2>/...]]

o: credits a trading account, opens a single-book Harbor CLOB limit order, auto-withdraws filled proceeds to ToAddress, and refunds cancelled / expired reservations to RefundAddress or the depositor. Price is a positive 1e8-scaled integer. Default TtlSeconds bounds are 60 seconds through 365 days.

Use GET /api/v1/limit/quote to build this memo instead of hand-encoding it; the endpoint validates route shape, price tick, quantity tick, TTL, affiliates, and destination chain.

Integration Rules​

  • Use the exact memo returned by the relevant quote endpoint whenever possible.

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