spanDEX Trader

Trade on Base chain using spanDEX — the free, open-source meta-aggregator by @_nonlinear / Fabric.

Races 6 DEX aggregators (Fabric, KyberSwap, Odos, Velora, LI.FI, Relay) per swap, simulates on-chain, picks the winner, and executes with automatic fallback if the best-priced provider fails.

Setup

Prerequisites: Node.js 18+, npm

# Install dependencies (run once in skill directory)
cd <skill-dir>/scripts && npm init -y && npm i viem @spandex/core

Required env vars:

Optional env vars:

Commands

All output is JSON. TOKEN can be a contract address or alias (USDC, WETH, ETH, DAI, USDT).

# Compare prices across all 6 providers
node scripts/spandex_trade.mjs quote --sell USDC --buy 0xTOKEN --amount 50

# Execute swap (best price, automatic fallback)
node scripts/spandex_trade.mjs swap --sell USDC --buy 0xTOKEN --amount 50
node scripts/spandex_trade.mjs swap --sell USDC --buy 0xTOKEN --amount 50 --slippage 500 --dry-run

# KyberSwap limit orders (gasless EIP-712)
node scripts/spandex_trade.mjs limit --sell 0xTOKEN --buy USDC --sell-amount 1000000 --buy-amount 50 --expiry 7d
node scripts/spandex_trade.mjs orders --status active
node scripts/spandex_trade.mjs cancel-order --order-id 123

# Wallet
node scripts/spandex_trade.mjs balance
node scripts/spandex_trade.mjs balance --token 0xTOKEN
node scripts/spandex_trade.mjs providers

Slippage defaults

Auto-applied based on token pair:

• Major ↔ Major (USDC/WETH/ETH): 0.5% (50 bps)
• Major ↔ Microcap: 3% (300 bps)
• Microcap ↔ Microcap: 5% (500 bps)

Override with --slippage .

Execution flow

1. getQuotes() — fetch + simulate from all 6 providers in parallel
2. sortQuotesByPerformance() — rank by output amount (best first)
3. For each quote: buildCalls() → sendTransaction() with priority fee → if fail, try next provider
4. netOutputs() — extract actual output from TX receipt logs
5. Final balance verification

Key behaviors

• Anti-double-execution: 120s lockfile per token prevents accidental duplicate swaps
• Fallback routing: If best-price provider fails execution, automatically tries next
• V4/DERC20 compatible: Uses buildCalls() for proper Clanker V4 and Flaunch DERC20 settlement
• No API keys needed: All 6 providers work without registration

Token compatibility by provider

For detailed integration notes and architecture, see references/INTEGRATION.md.