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:    [email protected]
  ? 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