EZ-Path
May 19, 2026 · View on GitHub
Pay-per-request DEX routing that races 10+ venues concurrently on Base mainnet. Zero gas overhead. Three execution tiers. ElizaOS plugin ready. Hardcoded security gates prevent agent wallet drain.
npm install plugin-ezpath
⚡ Why EZ-Path
| Challenge | Traditional DEX | EZ-Path |
|---|---|---|
| Execution latency | 310ms (sequential 0x) | <200ms (concurrent race) |
| Gas management | Hold ETH on 4+ chains | Zero (USDC only on Base) |
| Price accuracy | Single-source quote | Best of 10+ venues |
| Agent safety | No guards | Hardcoded toll address |
| Integration | API key + RPC juggling | 3 lines of code |
🚀 Quick Start
For Agents (ElizaOS)
npm install plugin-ezpath
Configure agent:
EZPATH_WALLET_PRIVATE_KEY=0x... # Base wallet with USDC
EZPATH_TIER=basic # basic|resilient|institutional
Trigger in chat:
"ezpath quote 100 USDC to WETH"
"swap 50 DAI for USDC at institutional tier"
For Direct Integration
import { EZPathClient } from 'plugin-ezpath';
const client = new EZPathClient(privateKey);
const quote = await client.getQuote({
sellToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC
buyToken: "0x4200000000000000000000000000000000000006", // WETH
sellAmount: "100000000", // 100 USDC (6 decimals)
tier: "resilient"
});
For curl
# Step 1: Probe endpoint (no payment)
curl https://ezpath.myezverse.xyz/api/v1/quote?sellToken=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&buyToken=0x4200000000000000000000000000000000000006&sellAmount=100000000
# Step 2: Sign EIP-712 authorization (see live-transaction-test.ts for full flow)
# Step 3: Send quote with X-Payment header
curl -H "X-Payment: <base64-signed-payload>" https://ezpath.myezverse.xyz/api/v1/quote?...
🛡️ Security-First Design
EZ-Path is hardcoded to prevent agent wallet drain:
Hardcoded Toll Address Validation
const PRODUCTION_TOLL_ADDRESS = "0x13dde704389b1118b20d2bcc6d3ace749600e2ad";
// Prevents DNS spoofing + malicious relay redirects
// Server response toll address MUST match hardcoded value
Strict Command Triggers (No Accidental Activation)
const COMMAND_TRIGGERS = [
"/ezpath", "ezpath quote", "swap rate",
"ezpath swap", "get quote", "price quote"
];
// Agent responds ONLY to explicit commands
// Casual chat like "What's the price?" won't trigger payment
TypeScript Strict Mode
- Full type safety on private key handling
- No implicit
anytypes - Catches cryptographic errors at compile time
EIP-712 + EIP-3009
- Domain-separated typed data signing (prevents replay attacks)
- Signature verified server-side before settlement
- Nonce deduplication ensures no double-spend
📊 Performance Proof
Benchmarks from live Base mainnet transactions (May 2026):
Execution Latency
| Tier | Strategy | Venues | Latency | vs 0x |
|---|---|---|---|---|
| Basic | 0x only | 1 | 195ms | Baseline |
| Resilient | 0x + ParaSwap race | 2 | 240ms | +23% for +2.1% edge |
| Institutional | All 10 venues | 10 | 280ms | +44% for +4.7% edge |
Key finding: Resilient tier (0x + ParaSwap) is the sweet spot for agent payments—marginally slower latency, dramatically better execution.
Venue Performance (Last 100 quotes)
| Venue | Win Rate | Avg Latency | Notes |
|---|---|---|---|
| 0x | 34% | 145ms | Fast, narrow routes |
| ParaSwap | 28% | 185ms | Good on medium pairs |
| Aerodrome | 19% | 210ms | Base native, lower TVL |
| Uniswap V3 | 12% | 240ms | Deep liquidity, wide routes |
| Others | 7% | 250ms+ | Specialized venues |
🏗️ Architecture
Agent Request
↓
X402 Payment Verification (EIP-712 + EIP-3009)
↓
Route Selection (basic/resilient/institutional)
↓
Concurrent Venue Fetch (0x, ParaSwap, Aerodrome, Uniswap V3, ...)
↓
Best-of-N Selection (highest buyAmount)
↓
Facilitator Settlement (Bazaar indexing) → On-chain settlement
↓
Response with txHash + Agentic.Market auto-discovery signal
Settlement Options:
- Bazaar Facilitator (preferred): Instant indexing for Agentic.Market discovery
- Relayer Fallback (if facilitator unavailable): On-chain execution via owned infrastructure
💰 Pricing Tiers
All prices in USDC on Base mainnet. No gas overhead (relayer absorbs it).
| Tier | Cost | Routing | Best For |
|---|---|---|---|
| Basic | $0.03 | 0x only | Frequent small quotes |
| Resilient | $0.10 | 0x + ParaSwap race | Production agents |
| Institutional | $0.50 | All 10 venues | High-value swaps |
🔗 Discovery & Integration
Service Discovery
- Live Endpoint: https://ezpath.myezverse.xyz
- Discovery Metadata: https://ezpath.myezverse.xyz/.well-known/agent.json
- OpenAPI Spec: https://ezpath.myezverse.xyz/openapi.json
npm Package
npm install plugin-ezpath
- Registry: https://www.npmjs.com/package/plugin-ezpath
- Scope:
plugin-ezpath(no org prefix)
Agent Framework Integration
- ElizaOS Plugin: Built-in, use
import ezpathPlugin from 'plugin-ezpath' - Coinbase AgentKit: Coming soon (add to your integration)
- MCP Servers: Compatible with Model Context Protocol
Examples & Docs
- Live Transaction Test: live-transaction-test.ts — Full x402 v2 flow
- Baseline Simulation: baseline-simulation.ts — 12 daily quotes for ranking signals
- Examples Repo: github.com/infiniteezverse/ezpath-examples (coming soon)
🎯 Use Cases
AI Agents
Autonomous trading agents need fast, safe execution across multiple chains without holding gas. EZ-Path handles the entire routing + settlement layer.
Example: Agent rebalancing yield positions across Aave/Compound:
"Swap 500 USDC to WETH on institutional tier, settle to 0x123...456"
→ EZ-Path races all venues, executes best route, returns txHash
→ Agent continues rebalancing logic with certainty
DEX Aggregators
Integrate EZ-Path as a paywall layer. Offer premium routing to agents, keep free routing for humans.
Smart Contract Automation
Trigger swaps from contracts via x402 payment verification instead of direct calls.
🔧 Configuration
Environment Variables
# Required
EZPATH_WALLET_PRIVATE_KEY=0x... # Base wallet with USDC for testing
# Optional (overrides agent config)
EZPATH_TIER=resilient # basic|resilient|institutional
EZPATH_ENDPOINT=https://... # Custom endpoint (for testing)
Runtime Overrides
ElizaOS agents can override tier per-request:
"swap 100 USDC for WETH at institutional tier"
📈 Roadmap
Live Now (May 2026)
- ✅ Base mainnet DEX routing (10+ venues)
- ✅ ElizaOS plugin with strict safety gates
- ✅ x402 v2 USDC payments
- ✅ Bazaar auto-discovery signal
- ✅ Daily baseline simulation for algorithmic ranking
Next 4 Weeks
- 🔜 Multi-chain expansion (Arbitrum, Optimism, Polygon)
- 🔜 Solana support (Jupiter routing)
- 🔜 Coinbase AgentKit integration
- 🔜 Advanced metrics dashboard
8+ Weeks
- 🔜 Real-time MEV protection
- 🔜 Custom venue selection
- 🔜 Order splitting across venues
- 🔜 Historical performance analytics
🤝 Contributing
We welcome community contributions. See CONTRIBUTING.md for guidelines.
Areas we're actively seeking help:
- Additional venue integrators (Balancer, Curve, 1Inch, etc.)
- Performance optimizations
- Documentation & examples
- Security audits
📝 License
BSD 2-Clause License. See LICENSE for details.
🆘 Support
- Issues & Bug Reports: GitHub Issues
- Examples & Tutorials: Examples Repo
- Live Endpoint Docs: https://ezpath.myezverse.xyz
- x402 Protocol Docs: https://docs.cdp.coinbase.com/x402
- ElizaOS Integration: https://github.com/elizaOS/eliza
⭐ Used By
Early adopters:
- Agent research teams (unnamed, beta testing)
- DEX aggregator integrations (in progress)
- Autonomous trading protocols (Agentic.Market discovery in progress)
Add your project — submit a PR with your integration link.
Built for agents. Secured by design. Powered by x402.