EZ-Path Examples

May 19, 2026 · View on GitHub

Production-ready code examples for integrating EZ-Path best-execution DEX routing into agents, SDKs, and scripts.

All examples:

  • ✅ Run standalone (no dependencies on ElizaOS or other frameworks)
  • ✅ Use real Base mainnet endpoint
  • ✅ Include x402 v2 payment flow
  • ✅ Handle error cases properly
  • ✅ Copy-paste ready

📁 Repository Structure

ezpath-examples/
├── README.md                          (this file)
├── package.json                       (Node.js dependencies)
├── .env.example                       (configuration template)
│
├── javascript/
│   ├── 01-vanilla-fetch.js           (raw fetch, no dependencies)
│   ├── 02-viem-client.js             (with viem SDK)
│   ├── 03-agentkit-integration.js    (Coinbase AgentKit)
│   └── utils.js                       (shared helpers)
│
├── typescript/
│   ├── 01-basic-quote.ts             (simple quote request)
│   ├── 02-concurrent-quotes.ts       (parallel tier comparison)
│   └── types.ts                       (TypeScript interfaces)
│
├── python/
│   ├── 01_basic_quote.py             (requests library)
│   ├── 02_async_quotes.py            (asyncio + aiohttp)
│   └── utils.py                       (helpers)
│
├── bash/
│   ├── 01-probe-endpoint.sh          (no payment)
│   ├── 02-get-quote.sh               (with payment)
│   └── functions.sh                   (reusable functions)
│
└── agentkit/
    ├── swap-action.ts                (AgentKit action template)
    └── integration-guide.md           (setup instructions)

🚀 Quick Start

Setup

# Clone this repo
git clone https://github.com/infiniteezverse/ezpath-examples.git
cd ezpath-examples

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Add your Base wallet private key
# EZPATH_WALLET_PRIVATE_KEY=0x...

Run Your First Example

JavaScript (no dependencies):

node javascript/01-vanilla-fetch.js

TypeScript:

npx ts-node typescript/01-basic-quote.ts

Python:

pip install requests
python python/01_basic_quote.py

Bash:

bash bash/01-probe-endpoint.sh

💡 Examples

Swap in 3 Lines

JavaScript:

const client = new EZPathClient(privateKey);
const quote = await client.getQuote({sellToken: USDC, buyToken: WETH, sellAmount: "100000000", tier: "basic"});
console.log(`Best price: ${quote.buyAmount} ${quote.routingEngine}`);

Python:

client = EZPathClient(private_key)
quote = client.get_quote(usdc, weth, "100000000", tier="basic")
print(f"Best price: {quote['buyAmount']} {quote['routingEngine']}")

Compare All Tiers

# Run 3 quotes (basic, resilient, institutional) in parallel
# See which tier gives the best edge
npx ts-node typescript/02-concurrent-quotes.ts

Coinbase AgentKit Integration

// See agentkit/swap-action.ts for full AgentKit action
import { ezpathSwapAction } from './agentkit/swap-action.ts';

// Register with AgentKit
agent.registerAction(ezpathSwapAction);

// Agent now responds to: "swap 100 USDC for WETH"

🔒 Security Notes

All examples include:

  • ✅ Hardcoded production toll address validation
  • ✅ EIP-712 signature verification
  • ✅ Nonce deduplication checks
  • ✅ Error handling for payment failures

Never:

  • Commit private keys to git
  • Share EZPATH_WALLET_PRIVATE_KEY in logs
  • Use this for production without testing on testnet first

📚 Detailed Guides

🆘 Common Issues

Q: Got "Invalid time value" error?
A: Your system clock may be out of sync. EIP-712 signatures are time-bound (15s window). Sync your clock: ntpdate -s time.nist.gov

Q: Quote request returned 402?
A: No X-Payment header provided. See examples for proper EIP-712 signing + header construction.

Q: "Nonce already used" error?
A: Each quote must use a unique nonce. Regenerate: crypto.getRandomValues(new Uint8Array(32))

Q: Different prices across tiers?
A: Expected! Different venues return different prices. Institutional tier races all 10 venues and picks the best.

Built for agents. Secured by design. Powered by x402.