Trading Pipeline

Overview

Merlin's trading engine builds unsigned Uniswap V3 swap transactions. The backend is non-custodial — it returns unsigned calldata for the frontend to sign and submit.

6-Step Pipeline

1. QUOTE     — Uniswap V3 QuoterV2 on-chain quote (exactInputSingle)
2. SIMULATE  — eth_call dry-run of the swap
3. POLICY    — 8 guardrail safety checks
4. EXECUTE   — Frontend signs with private key, broadcasts tx
5. CONFIRM   — Wait for on-chain receipt, verify success
6. PERSIST   — Save trade record to Firestore

Standard Trade Flow (ETH gas)

POST /api/v1/trade/quote
  -> Resolve asset -> check guardrails -> Uniswap V3 quote
  -> Build unsigned swap tx (approve + exactInputSingle)
  -> Store quote (5-min TTL) -> Return to frontend

Frontend:
  -> User confirms -> sign tx -> broadcast -> poll receipt
  -> POST /api/v1/trade/confirm {quote_id, tx_hash}

Gasless Trade Flow (USDC gas via EIP-7702)

POST /api/v1/trade/quote-gasless
  -> Same quote + guardrails
  -> Build batch calls [approve, swap]
  -> Encode executeBySender() for AmbireAccount7702
  -> Assemble PackedUserOperation (ERC-4337 v0.7)
  -> Fetch paymaster signature from Ambire relay
  -> Return unsigned UserOp

Frontend:
  -> Sign EIP-7702 authorization (first time only)
  -> Sign UserOp hash
  -> Submit eth_sendUserOperation to bundler

Guardrail Checks (8 mandatory)

1. Side validation — must be "buy" or "sell"
2. Asset validation — must be known xStock or supported crypto
3. Amount validation — min $1, max $10,000
4. US person block — xStocks blocked for US persons
5. Sanctioned country block — 10 blocked countries
6. Daily limit — max $50,000 daily notional
7. Duplicate detection — no identical trade within 60 seconds
8. Rate limit — max 10 trades per minute

Contract Addresses (Ethereum Mainnet)

Key Files