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 @fluidwalletbase/sor create my-swap-app

The CLI will interactively ask for:

1. Fluid API key (fw_sor_...) — get it at fluidnative.com → Developer Console → API Keys
2. Seed phrase (hidden input — never echoed, never written to disk) — your signing key is derived in-process (BIP-44 m/44'/60'/0'/0/0) and only the private key is saved to .env.local

# [1/5] Fluid API key setup
# ? Paste API key (fw_sor_...): fw_sor_

# [2/5] Derive signing key from seed phrase
# ? Seed phrase (hidden):  — input invisible
# ✓ Seed phrase received (12 words — input hidden)

# [3/5] Scaffolding my-swap-app…
# [4/5] Installing dependencies…
# [5/5] Deriving signing key and writing .env.local…
# ✓ API key written   fw_sor_48d688***
# ✓ Signing key derived   0x1ab42c... (seed phrase not stored)

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

After setup — run the demo agent

The CLI generates your FLUID_AGENT_KEY and exports it to ~/.zshrc. Once setup is complete:

# Copy environment template
cp .env.example .env
# (your FLUID_AGENT_KEY is already in the shell from the CLI)

# Run the SOR demo agent
node agent.js

The agent runs 4 steps automatically:

Step 1: Public SOR Quote    — no key needed, shows all ranked routes
Step 2: Authenticated Quote — uses your fk_... key (read scope)
Step 3: Balance Check       — verifies USDC balance before swapping
Step 4: Execute Swap        — live swap via Ganji SOR, prints BaseScan receipt

No funds? Steps 1 and 2 run without any balance. Fund your wallet with USDC on Base mainnet to run Step 4.

Keys

| Key | How you get it | Used for | |-----|---------------|----------| | FLUID_AGENT_KEY (fk_...) | Auto-generated by CLI → exported to ~/.zshrc | Authenticated quotes + swap execution | | None needed | Built-in, rate-limited | Public quotes via /api/sor/public-quote |

Scopes selected during CLI setup

| Scope | What it allows | |-------|---------------| | read | Price quotes, route discovery, gas estimates | | swap | Execute token swaps via the SOR contract 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