x402-agent

Solana AI Agentic Protocol Engine — Complete Birdeye V3 API client, multi-provider AI, on-chain analytics, and interactive CLI with 65+ commands.

Install

# As a library
npm install x402-agent

# As a global CLI
npm install -g x402-agent

Quick Start

As a Library

const x402 = require('x402-agent');

// Birdeye V3 — Token Intelligence
const intel = await x402.birdeye.getTokenIntelligence('So11111111111111111111111111111111111111112');
// Returns: { metadata, marketData, tradeData, security, timestamp }

// Single token price
const price = await x402.birdeye.getPrice('6H8uyJYrPVcra6Fi7iWh29DXSm8KctzhHRyXmPwKpump');

// Market data for multiple tokens
const markets = await x402.birdeye.getTokenMarketDataMultiple([
  'So11111111111111111111111111111111111111112',
  'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
]);

// Whale detection
const whales = await x402.birdeye.getWhaleTradesV3('So11...', 50000);

// Wallet analysis
const profile = await x402.birdeye.getTraderProfile('Bnf1jud...');

// Enhanced: ASCII chart
const chart = await x402.enhanced.getOHLCVWithChart('So11...', '1h');
console.log(chart.chart);  // Prints colored ASCII price chart

// Enhanced: Market sentiment (0-100 fear/greed)
const sentiment = await x402.enhanced.getMarketSentiment('So11...');
console.log(sentiment.emoji, sentiment.sentiment, sentiment.score);

As a CLI

# Interactive REPL with boot animation
x402

# Skip animation
x402 --no-animation

# Run a single command
x402 price So11111111111111111111111111111111111111112
x402 intel So11111111111111111111111111111111111111112
x402 trending
x402 whales So11... 50000
x402 trader-profile Bnf1jud...

# Start HTTP API server
x402 --server --port=3000

Environment Variables

Create a .env file in your project root:

# Required for Birdeye API
BIRDEYE_API_KEY=your_birdeye_api_key

# Solana RPC
HELIUS_RPC_URL=https://mainnet.helius-rpc.com/?api-key=xxx

# AI Providers (optional — needed for AI commands)
GOOGLE_API_KEY=your_google_key
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
XAI_API_KEY=your_xai_key

Birdeye V3 API — Complete Coverage

All 53 Birdeye API methods are available via x402.birdeye:

Stats

| Method | Description | |--------|-------------| | getTokenOverview(address, opts) | Token overview with custom timeframes | | getTokenMetadataSingle(address) | Token metadata (name, symbol, decimals, logo) | | getTokenMetadataMultiple(addresses) | Metadata for up to 50 tokens | | getTokenMarketDataSingle(address) | Price, liquidity, supply, mcap, FDV, holders | | getTokenMarketDataMultiple(addresses) | Market data for up to 20 tokens | | getTokenTradeDataSingle(address, opts) | Buy/sell/volume/wallet data across timeframes | | getTokenTradeDataMultiple(addresses) | Trade data for up to 20 tokens | | getTokenLiquiditySingle(address) | Exit liquidity (real liquidity check) | | getTokenLiquidityMultiple(addresses) | Exit liquidity for up to 50 tokens | | getPairOverviewSingle(address) | Pair stats (base/quote, liquidity, volume) | | getPairOverviewMultiple(addresses) | Pair stats for up to 20 pairs | | getPriceStatsSingle(address, opts) | Price stats (high/low, % change) by timeframe | | getPriceStatsMultiple(addresses, opts) | Price stats for up to 20 tokens (POST) |

Token & Market Lists

| Method | Description | |--------|-------------| | getTokenList(opts) | List tokens with full filtering (max 100) | | getTokenListScroll(opts) | Scroll pagination (up to 5,000 per batch) | | getTokenNewListing(opts) | Recently listed tokens | | getTokenMarketList(address) | All markets/pairs for a token | | getTokenTrending(opts) | Trending tokens |

Transactions

| Method | Description | |--------|-------------| | getTradesTokenV3(address, opts) | Token trades with V3 filters | | getTradesAllV3(opts) | All trades across all tokens | | getTradesRecentV3(opts) | Most recent trades | | getTradesToken(address, opts) | Token trades (legacy V1) | | getTradesPair(address, opts) | Pair trades | | getTradesTokenSeekByTime(address, opts) | Token trades by time range | | getTradesPairSeekByTime(address, opts) | Pair trades by time range | | getTraderTradesSeekByTime(address, opts) | Trader/wallet trades by time | | getTradesTokenByVolume(address, type, opts) | Trades filtered by USD volume | | getTokenMintBurn(address, opts) | Mint and burn transactions |

Wallet, Networth & PnL

| Method | Description | |--------|-------------| | getWalletPortfolio(wallet) | All token balances in a wallet | | getWalletTokenBalance(wallet, token) | Specific token balance | | getWalletNetWorth(wallet) | Total net worth in USD | | getWalletPnL(wallet) | Profit and loss data |

Holder, Security & Search

| Method | Description | |--------|-------------| | getTokenHolders(address, opts) | Top token holders | | getTokenSecurity(address) | Security audit (ownership, freeze) | | searchTokens(keyword, opts) | Search tokens by keyword | | getTokenCreationInfo(address) | Deployer, creation time | | getMemeTokenDetail(address) | Meme token details | | getNetworkList() | All supported networks |

Price & OHLCV

| Method | Description | |--------|-------------| | getPrice(address) | Single token price | | getMultiplePrices(addresses) | Multiple token prices | | getPriceVolumeSingle(address) | Price + volume | | getPriceVolumeMulti(addresses) | Price + volume (multi) | | getHistoricalPrice(address, opts) | Historical price data | | getOHLCV(address, type, from, to) | OHLCV candlestick data | | getOHLCVPair(address, type, from, to) | OHLCV for a pair | | getOHLCVBaseQuote(base, quote, type, from, to) | OHLCV for base/quote | | getOHLCVV3(address, type, from, to) | V3 OHLCV |

Composite / Intelligence

| Method | Description | |--------|-------------| | getTokenIntelligence(address) | Full intel (metadata + market + trade + security) | | getX402Intelligence() | X402 token intelligence | | getWhaleTradesV3(address, minUsd) | Large volume trades | | getTopTokens(sortBy, limit) | Top tokens by metric | | getRecentlyListed(limit) | Recently listed tokens | | getTraderProfile(wallet) | Complete trader profile |

CLI Commands (65+)

Run x402 help to see all commands, organized by category:

| Category | Commands | |----------|----------| | AI & Chat | ask, chat, think, code | | Image Gen | image, banana, sticker, logo, weather, article | | Token Stats | price, overview, metadata, meta-multi, market, market-multi, tradedata, tradedata-multi, liquidity, liquidity-multi, pair, pair-multi, pricestats, pricestats-multi | | Token Lists | token-list, top-volume, top-gainers, new-listings, token-markets, trending | | Transactions | trades, trades-all, trades-pair, trader-txs, whales, mint-burn | | Charts & Sentiment | ohlcv, sentiment, whale-alerts | | Intelligence | intel, compare, analytics, x402-intel | | Security & Search | holders, security, search, creation, meme, networks | | Wallet & PnL | wallet, networth, pnl, wallet-balance, trader-profile | | Solana | balance, tokens, portfolio, supply, trade | | Agents | council, invest | | System | status, config, env, server |

Architecture

x402-agent/
├── lib/index.js              ← Programmatic API entry point
├── bin/x402                   ← CLI with boot animation
├── src/
│   ├── services/
│   │   ├── birdeye/
│   │   │   ├── v3.js          ← Core V3 client (53 methods)
│   │   │   └── index.js       ← Unified gateway + X402 analytics
│   │   ├── birdeye-enhanced.js ← Charts, sentiment, whales
│   │   ├── solana/            ← Solana RPC
│   │   ├── jupiter/           ← DEX aggregator
│   │   ├── portfolio.js       ← Wallet analytics
│   │   └── ...
│   ├── providers/             ← AI: Gemini, OpenAI, Claude, Grok
│   ├── agents/                ← Agent council, A2A protocol
│   ├── cli/
│   │   ├── commands/index.js  ← 65 CLI commands
│   │   └── index.js           ← Interactive REPL engine
│   └── config/index.js        ← Environment-based config
└── package.json

License

MIT © X402 Team