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

bash

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

Required env vars:

VarPurposeBASE_RPC_URLBase chain RPC endpoint (Alchemy, Infura, dRPC, etc.)SPANDEX_PRIVATE_KEYWallet private key (hex). OR use SPANDEX_KEY_PATH for file-based key

Optional env vars:

VarDefaultPurposeSPANDEX_KEY_PATH—Path to file containing private key (alternative to raw key)SPANDEX_APP_ID``spandex-trader-skillApp identifier for provider APIsSPANDEX_STRATEGY``bestPriceDefault quote strategySPANDEX_PRIORITY_GWEI``0.03Priority fee floor (gwei) for Base sequencerSPANDEX_SKIP_LOCK—Set 1 to disable anti-double-execution lockSPANDEX_DEBUG—Enable debug logging

Commands#

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

bash

# 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 <bps>.

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#

ProviderStandard ERC-20Clanker V4Flaunch DERC20KyberSwap✅✅✅LI.FI✅✅✅Fabric✅⚠️⚠️Odos✅❌❌Velora✅❌❌Relay✅⚠️⚠️

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