npm package: @mawdbotsonsolana/x402-agent
Description: Solana AI Agentic Protocol Engine — Complete Birdeye V3 API client (53 endpoints), multi-provider AI, on-chain analytics, and interactive CLI with 65+ commands
Author: X402 Team
Latest version: 2.0.0

# x402-agent

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

[![npm version](https://img.shields.io/npm/v/x402-agent.svg)](https://www.npmjs.com/package/x402-agent)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

---

## Install

```bash
# As a library
npm install x402-agent

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

## Quick Start

### As a Library

```js
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

```bash
# 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:

```env
# 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