@x402-api/elizaos-plugin

@x402-api/elizaos-plugin

ElizaOS plugin for pay-per-call DeFi intelligence — powered by x402 micropayments (USDC on Base)

Give your ElizaOS agent real-time access to 8 DeFi data endpoints for as little as $0.001 per query. No API keys, no subscriptions — just pay per call in USDC.

Endpoints

Action	Endpoint	Cost
GET_CRYPTO_PRICES	/api/price-feed	$0.001
GET_GAS_PRICES	/api/gas-tracker	$0.001
GET_DEX_QUOTES	/api/dex-quotes	$0.002
SCAN_TOKEN	/api/token-scanner	$0.003
TRACK_WHALES	/api/whale-tracker	$0.005
SCAN_YIELDS	/api/yield-scanner	$0.005
GET_FUNDING_RATES	/api/funding-rates	$0.008
PROFILE_WALLET	/api/wallet-profiler	$0.008

API Base URL: https://x402-api.fly.dev

Installation

npm install @x402-api/elizaos-plugin
# or
bun add @x402-api/elizaos-plugin

For automatic payments (required for production)

npm install x402-fetch viem

Quick Start

1. Add to your character file

// src/character.ts
import { x402DeFiPlugin } from '@x402-api/elizaos-plugin';

export const character: Character = {
  name: 'DeFi Agent',
  plugins: [
    '@elizaos/plugin-bootstrap',
    '@elizaos/plugin-sql',
    x402DeFiPlugin,  // ← add this
  ],
};

2. Configure your wallet

The plugin needs a wallet with USDC on Base to pay for API calls.

# .env
X402_WALLET_PRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE

⚠️ Security: Never commit your private key. Use .env files and add them to .gitignore.

3. Fund your wallet

Your wallet needs USDC on Base. Get some from:

• Coinbase → withdraw USDC to Base
• Uniswap on Base → swap ETH for USDC
• bridge.base.org → bridge from Ethereum

Costs are tiny — $1 of USDC covers 125–1000 queries depending on the endpoint.

Configuration

Environment Variables

Variable	Description	Default
X402_WALLET_PRIVATE_KEY	Your wallet's private key (hex)	—
X402_WALLET_ADDRESS	Your wallet address (for logging)	—
X402_API_BASE_URL	API base URL override	https://x402-api.fly.dev

Programmatic Config

import { createX402Plugin } from '@x402-api/elizaos-plugin';

const plugin = createX402Plugin({
  walletPrivateKey: process.env.MY_KEY,
  baseUrl: 'https://x402-api.fly.dev',  // or your own instance
  timeoutMs: 15000,
});

export const character: Character = {
  plugins: [plugin],
};

What Each Action Does

💰 GET_CRYPTO_PRICES

Fetches live prices for BTC, ETH, SOL + top 5 gainers/losers by 24h change. Data from CoinGecko.

Triggers when you say:

• "What are the current crypto prices?"
• "How is the market doing?"
• "Price feed"

⛽ GET_GAS_PRICES

Current gas prices across Ethereum, Base, Polygon, and Arbitrum. Returns slow/normal/fast tiers with USD cost estimates for transfers, swaps, and NFT mints.

Triggers when you say:

• "What are the gas fees right now?"
• "How much does an ETH swap cost?"
• "Check gas prices on Arbitrum"

🔄 GET_DEX_QUOTES

Compare swap quotes across Uniswap V3, SushiSwap, and 1inch for any token pair. Shows price impact, fees, gas costs, and best route.

Triggers when you say:

• "What's the best rate to swap 1 ETH for USDC?"
• "Compare DEX quotes for BTC/USDC on Base"
• "How much USDT do I get for 500 USDC?"

Params extracted from message: from/to tokens, amount, chain

🔍 SCAN_TOKEN

Security scan for any ERC-20 token. Checks: contract verification, proxy/upgradeable, mint function, liquidity lock, honeypot detection, buy/sell tax, holder count, risk score.

Triggers when you say:

• "Is PEPE safe? Check for rug"
• "Scan this token: 0x6982..."
• "Is this a honeypot?"

Params: token symbol or address, chain

🐋 TRACK_WHALES

Top holder distribution analysis. Returns concentration metrics (Gini coefficient, Herfindahl index), distribution buckets, top 20 holders with labels, and recent large transfers.

Triggers when you say:

• "Are whales accumulating ETH?"
• "Show whale activity for PEPE"
• "Who are the top holders of SOL?"

🌾 SCAN_YIELDS

Find the best DeFi yield opportunities across 10+ protocols: Aave, Compound, Morpho, Lido, Rocket Pool, Pendle, Ethena, Maker DSR, Convex, Yearn, Aerodrome, and more. Filter by chain, asset, TVL, and risk tier.

Triggers when you say:

• "What are the best DeFi yields right now?"
• "Find safe USDC yields on Base"
• "Best ETH staking rates?"

📊 GET_FUNDING_RATES

Perpetual futures funding rates across Hyperliquid, dYdX v4, Aevo, GMX, Drift, and Vertex. Automatically identifies arbitrage opportunities (long on lowest-rate venue, short on highest).

Triggers when you say:

• "What are the current perp funding rates?"
• "Is there a funding rate arb for ETH?"
• "Compare funding rates across venues"

👛 PROFILE_WALLET

Full wallet analysis: portfolio breakdown, DeFi positions, activity metrics, risk classification. Supports ENS and known wallet labels.

Triggers when you say:

• "Analyze wallet 0xd8dA..."
• "What's in vitalik's wallet?"
• "Profile this address: 0x..."

How x402 Payments Work

The x402 protocol is a standard for HTTP micropayments:

1. Agent → GET /api/price-feed
2. Server → 402 Payment Required + payment details
3. x402-fetch → sign & broadcast USDC transfer on Base
4. Agent → GET /api/price-feed + X-PAYMENT header
5. Server → validate payment → 200 OK + data

This happens automatically when you install x402-fetch and provide a wallet key. From your agent's perspective, it's just a normal API call.

Without x402-fetch

If x402-fetch is not installed, the plugin will:

• Make the request
• Receive a 402 response
• Throw a helpful error explaining how to configure payment

This is useful for testing the plugin structure without spending USDC.

TypeScript Types

All API response types are exported:

import type {
  PriceFeedResponse,
  GasTrackerResponse,
  DexQuotesData,
  TokenScanData,
  WhaleTrackerData,
  YieldPool,
  ArbOpportunity,
  WalletProfileData,
} from '@x402-api/elizaos-plugin';

Advanced: Custom Action Composition

Use only the actions you need:

import {
  createPriceFeedAction,
  createTokenScannerAction,
  type X402ClientConfig,
} from '@x402-api/elizaos-plugin';
import type { Plugin } from '@elizaos/core';

const config: X402ClientConfig = {
  baseUrl: 'https://x402-api.fly.dev',
  walletPrivateKey: process.env.X402_WALLET_PRIVATE_KEY,
};

const myPlugin: Plugin = {
  name: 'my-defi-plugin',
  description: 'Selected DeFi actions',
  actions: [
    createPriceFeedAction(config),
    createTokenScannerAction(config),
  ],
};

Running Your Own API Instance

The API server is open source. Deploy your own:

git clone https://github.com/sugi/x402-api-server
cd x402-api-server
fly deploy

Then point the plugin at your instance:

X402_API_BASE_URL=https://your-api.fly.dev

Development & Testing

# Install deps
npm install

# Build TypeScript
npm run build

# Watch mode
npm run dev

Testing without real payments

Set a dummy private key to test plugin loading (calls will fail at payment step):

X402_WALLET_PRIVATE_KEY=0x0000000000000000000000000000000000000000000000000000000000000001

Or mock x402-fetch in your tests.

Publishing to npm

npm run build
npm publish --access public

Or with Bun:

bun run build
bun publish

Compatibility

ElizaOS Version	Plugin Version	Notes
>=1.0.0	1.x	Full support
0.x	Not supported	Use the raw API client instead

License

MIT © Sugi

Links

• API Server: https://x402-api.fly.dev
• x402 Protocol: https://x402.org
• ElizaOS Docs: https://docs.elizaos.ai
• Source Code: https://github.com/sugi/x402-api-server