fluid-sor

Smart Order Routing for autonomous agents on Base Mainnet — multi-venue, split-route, MEV-protected.

Contract: 0xF24daF8Fe15383fb438d48811E8c4b43749DafAE — Base Mainnet (Chain ID: 8453)
Paper: Ganji's DeFi SOR Protocol: Multi-Venue Smart Order Routing for Human and Agent-Native Crypto Swaps on Base
Authors: Abhijeeth Ganji (Maryville University), Priyanka Velpula (Ex-Wipro)

---

What's inside

File	What it does
agent.js	Demo SOR agent — public quote → authenticated quote → live swap with BaseScan receipt
.env.example	Environment variables template — copy to .env after CLI setup
contracts/	FluidSOR smart contract on Base Mainnet
packages/	@fluidwalletbase/wallet-endpoints — SDK for quotes and swaps
bin/	CLI scaffold for swap apps

---

Quick start

npx fluid-sor create my-swap-app

The CLI handles everything automatically — just provide your email and password:

── Step 1/7: Developer account
  ? Email address:    you@example.com
  ? Password:         ········
  ✓ Developer account created

── Step 2/7: Fluid API key (fw_sor_...) · auto-generated
  ══ SHOWN ONCE — save your API key NOW ══
  FLUID_API_KEY    fw_sor_a8f3c2d1...
  ═════════════════════════════════════════

── Step 3/7: FLDP EC key pair (P-256) · auto-generated
  ══ SHOWN ONCE — save your FLDP key NOW ══
  FLDP_KEY_NAME      fluid/devkeys/abc1/...
  FLDP_PRIVATE_KEY   { "privateKey": "-----BEGIN..." }
  ═════════════════════════════════════════

── Step 4/7: Wallet seed phrase (BIP-39, 12 words) · auto-generated
  ══ SHOWN ONCE — write down your seed phrase NOW ══
  witch collapse practice feed shame open despair ...
  ═════════════════════════════════════════

── Step 5/7: Scaffolding my-swap-app…
── Step 6/7: Installing dependencies…
── Step 7/7: Deriving signing key and writing .env.local…
  ✓ API key written         fw_sor_a8f3c2***
  ✓ Signing key derived     0x4f9a1b2c…  (seed phrase discarded)
  ✓ .env.local written      (git-ignored)

  my-swap-app
    npm run dev
    # → http://localhost:5173

Everything is auto-generated — API key, FLDP EC key pair, and BIP-39 seed phrase are each shown once and never stored. Only the derived private key (m/44'/60'/0'/0/0) is written to .env.local.

---

What gets written to .env.local

VITE_FLUID_API_KEY=fw_sor_...          # auto-generated, registered with Fluid
VITE_FLUID_PRIVATE_KEY=0x...           # derived from seed phrase (seed discarded)
VITE_FLUID_SOR_ADDRESS=0xF24daF8...    # pre-filled — FluidSOR contract on Base
VITE_FLDP_KEY_NAME=fluid/devkeys/...   # FLDP developer key name

---

Keys

Key	Generated by	Used for
fw_sor_... API key	CLI step 2 — auto	Authenticated SOR quotes + swap execution
FLDP EC key pair (P-256)	CLI step 3 — auto	Developer API signing
Seed phrase (BIP-39, 12 words)	CLI step 4 — auto, shown once	Derives wallet signing key
Private key (0x...)	Derived in-process, never shown	Signs on-chain swaps on Base

---

Endpoints

Endpoint	Auth	Description
GET /api/sor/public-quote	None	Ranked route quotes — 30 req/min, no key
POST /v1/agents/quote-swap	read scope	Authenticated quote with higher rate limits
POST /v1/agents/swap	swap scope	Execute swap via SOR on Base Mainnet
POST /v1/agents/estimate-gas	read scope	Gas estimate for a swap

Supported pairs: USDC/USDT · USDC/WETH · USDT/USDC · WETH/USDC

---

The SOR routing flow

agent calls  →  GET /api/sor/public-quote?tokenIn=USDC&tokenOut=USDT&amountIn=1000
                     ↓
Ganji SOR   →  GanjiRoute-BellmanFord scans 18+ venues
               |V|≈200, |E|≈1500, convergence <50ms
                     ↓
SOR returns →  ranked routes: Fluid AMM, Uniswap V3, Aerodrome, split routes
               { bestVenue: "Fluid AMM + Uniswap V3 (60/40)", bestAmountOut: "999.90" }
                     ↓
agent swaps →  POST /v1/agents/swap
               X-Agent-Key: fk_...   ← generated by CLI in step 4
               { fromToken: "USDC", toToken: "USDT", amount: "1000" }
                     ↓
SOR executes → on-chain via 0xF24daF8Fe15383fb438d48811E8c4b43749DafAE
               MEV-protected · Pauli Proof attached · VER score ≥ 0.998
               ↓
receipt     →  { txHash: "0x...", explorerUrl: "https://basescan.org/tx/0x..." }

---

Key metrics (from paper)

Metric	Value
Route discovery (warm cache)	47.5 ms
End-to-end latency	~280 ms
Price improvement	+2.4 bps vs single venue
REI score (stablecoin)	0.9994
REI score (volatile)	0.9982
VCS score	~0.85 (18+ venues, 4 chains)
BF convergence	<50 ms (|V|≈200, |E|≈1500)
Agent throughput	10²–10³ intents/min
MEV protection	88% detection, 95% prevention

---

Research dataset

265,000-row simulation dataset validating all paper metrics across 10 CSV files.

📊 kaggle.com/code/abhijeethganji9/ganji-s-defi-sor-protocol

---

Related

Repo / Package	Description
fluid-agent-demo	Full agent demo with FADP payment flow
@fluidwalletbase/wallet-endpoints	SDK — quotes, swaps, balance
@fluidwallet/fadp-cli	Setup CLI — keys, shell export, scaffold
fluidnative.com	MVP — live SOR on Base Mainnet

---

License

MIT — Fluid Wallet