einstein

Original source / Raw SKILL.md

---
name: einstein
description: >
  Blockchain analytics and DeFi intelligence via Einstein's x402 micropayment services.
  Use when user wants on-chain market analysis, token research, whale tracking, smart money
  tracking, rug pull scanning, launchpad monitoring (Pump.fun, Zora, Virtuals), portfolio
  analysis, MEV detection, cross-chain arbitrage, or Polymarket data. Supports Base, Ethereum,
  BSC, Arbitrum, Polygon, Optimism, zkSync, Solana. Costs $0.25-$1.15 USDC per query via
  x402 protocol on Base.
metadata:
  author: project-einstein
  version: "1.1.0"
  disable-model-invocation: true
  clawdbot:
    emoji: "🧠"
    homepage: "https://emc2ai.io"
    requires:
      bins: ["node", "curl"]
      env: ["EINSTEIN_X402_PRIVATE_KEY"]
---

# Einstein — Blockchain Analytics via x402

Einstein provides 27 blockchain analytics services accessible via x402 micropayments (USDC on Base). Each query costs $0.25–$1.15 depending on complexity.

## Quick Start

```bash
# 1. Install dependencies (manual step — the setup wizard will NOT run npm for you)
cd packages/project-einstein/openclaw-skill/einstein && npm install

# 2. Set your private key via environment variable (recommended)
export EINSTEIN_X402_PRIVATE_KEY=0x_your_private_key_here

# 3. Or run the interactive setup wizard
node scripts/einstein-setup.mjs

# 4. List all services (free)
node scripts/einstein.mjs services

# 5. Run a query (will prompt for payment confirmation)
node scripts/einstein.mjs top-movers --chain base --limit 10
```

**Requirements:**
- Node.js 18+
- Dependencies installed via `npm install` (not auto-installed)
- A **dedicated** wallet private key with USDC on Base network (do NOT use your main wallet)
- Set `EINSTEIN_X402_PRIVATE_KEY` environment variable (preferred) or run setup with `--save-config`

## Service Categories

| Tier | Price (Raw) | Price (+AI) | Services |
|------|-------------|-------------|----------|
| Basic | $0.25 | $0.40 | Latest tokens, token chart |
| Standard | $0.40 | $0.55 | Top movers, top tokens, OHLCV, Virtuals, wallet holdings, holder concentration |
| Platform | $0.60 | $0.75 | Zora launches/volume, Pump.fun launches/volume/graduation, BSC alpha, liquidity shifts |
| Advanced | $0.85 | $1.00 | Whale intel, smart money, top traders, DEX capital, token sniping, Polymarket events |
| Comprehensive | $1.00 | $1.15 | Investment report, NFT analytics, MEV detection, arbitrage scanner, rug pull scanner, Polymarket compare |

**Raw** = structured data only. **+AI** = includes AI-generated analysis and insights (default).

## Free Services

These commands are free and do not require x402 payment or a wallet key.

### Epstein Files Search

Search 44,886+ DOJ-released Jeffrey Epstein documents (Jan 2026 release) via the DugganUSA public index.

```bash
# Search by name
node scripts/einstein.mjs epstein-search --query "Ghislaine Maxwell" --limit 10

# Search by topic
node scripts/einstein.mjs epstein-search --query "flight logs" --limit 20

# Search by location
node scripts/einstein.mjs epstein-search --query "Little St James"
```

| Flag | Description | Default |
|------|-------------|---------|
| `--query <terms>` | Search query (required) | — |
| `--limit <N>` | Number of results (1-500) | `10` |

## Usage Examples

### Market Analysis

```bash
# Top movers on Base in the last 24 hours
node scripts/einstein.mjs top-movers --chain base --timeperiod 1d --limit 10

# Top tokens by market cap on Ethereum
node scripts/einstein.mjs top-tokens --chain ethereum --limit 20

# Latest deployed tokens with liquidity
node scripts/einstein.mjs latest-tokens --chain base --limit 15
```

### Whale & Smart Money Intelligence

```bash
# Track whale accumulation on Ethereum
node scripts/einstein.mjs whale-intel --chain ethereum --limit 10 --timeperiod 7d

# Smart money leaderboard on Base
node scripts/einstein.mjs smart-money --chain base --limit 20 --timeperiod 7d

# Capital-intensive DEX traders
node scripts/einstein.mjs dex-capital --chain base --limit 10 --timeperiod 3d
```

### Security & Risk Analysis

```bash
# Scan a token for rug pull risk
node scripts/einstein.mjs rug-scan --chain ethereum --token 0x1234...abcd

# Detect MEV/sandwich attacks
node scripts/einstein.mjs mev-detect --chain ethereum --limit 10 --timeperiod 1d

# Identify early snipers on a token
node scripts/einstein.mjs token-snipe --chain base --token 0x1234...abcd --limit 20
```

### Launchpad Monitoring

```bash
# Latest Pump.fun launches on Solana
node scripts/einstein.mjs pump-launches --limit 15 --timeperiod 1d

# Pump.fun tokens about to graduate
node scripts/einstein.mjs pump-grads --limit 10

# Zora launches on Base
node scripts/einstein.mjs zora-launches --limit 10 --timeperiod 3d

# Virtuals Protocol agent tokens
node scripts/einstein.mjs virtuals --limit 10 --timeperiod 7d
```

### Portfolio & Token Analysis

```bash
# Check wallet holdings
node scripts/einstein.mjs wallet --chain ethereum --wallet 0xd8dA...

# Token holder concentration
node scripts/einstein.mjs holders --chain base --token 0x1234... --limit 50

# Token price chart
node scripts/einstein.mjs chart --chain base --token 0x1234... --timeperiod 7d

# OHLCV data for technical analysis
node scripts/einstein.mjs ohlcv --chain base --token 0x1234... --timeperiod 30d
```

### Advanced Reports

```bash
# Multi-chain investment report
node scripts/einstein.mjs investment-report --chains base,ethereum,bsc --limit 10 --timeperiod 7d

# Cross-chain arbitrage opportunities
node scripts/einstein.mjs arbitrage --chain ethereum --limit 10 --timeperiod 1d

# NFT collection analytics
node scripts/einstein.mjs nft-analytics --chain ethereum --limit 10 --timeperiod 7d
```

### Prediction Markets

```bash
# Polymarket events (Polygon)
node scripts/einstein.mjs polymarket --limit 10 --timeperiod 7d

# Compare Polymarket API vs chain data
node scripts/einstein.mjs polymarket-compare --limit 10
```

## How Payment Works

Einstein uses the **x402 protocol** — an HTTP-native micropayment standard. Payment is automatic:

1. Your request hits Einstein's endpoint
2. Server responds with HTTP 402 + payment challenge
3. The skill signs a USDC TransferWithAuthorization (EIP-3009) using your private key
4. Request is re-sent with the payment signature
5. Coinbase CDP facilitator settles the USDC transfer on Base
6. You receive the analytics data

**No accounts, no API keys, no subscriptions.** Just USDC on Base and a private key.

## Options Reference

### `einstein.mjs` (query CLI)

| Flag | Description | Default |
|------|-------------|---------|
| `--chain <chain>` | Blockchain network | `base` |
| `--limit <N>` | Number of results (1-500) | `10` |
| `--timeperiod <period>` | Time window: 1d, 3d, 7d, 30d | `7d` |
| `--token <address>` | Token contract address | — |
| `--wallet <address>` | Wallet address | — |
| `--chains <c1,c2>` | Comma-separated chains | — |
| `--raw` | Data-only response (cheaper) | `false` |
| `--yes` / `-y` | Skip payment confirmation prompt | `false` |

To skip the confirmation prompt globally, set `EINSTEIN_AUTO_CONFIRM=true` or add `"autoConfirm": true` to config.json.

### `einstein-setup.mjs` (setup wizard)

| Flag | Description | Default |
|------|-------------|---------|
| `--key <privateKey>` | Private key (skips interactive prompt) | — |
| `--url <baseUrl>` | Base URL for Einstein API | `https://emc2ai.io` |
| `--chain <chain>` | Default blockchain network | `base` |
| `--save-config` | Write config.json to disk (otherwise prints env var exports) | `false` |

**Supported chains:** base, ethereum, bsc, solana, arbitrum, polygon, optimism, zksync

## Security Best Practices

**Use a dedicated wallet.** Create a separate wallet funded with a small amount of USDC for this skill. Do NOT use your primary wallet or any wallet holding significant funds.

**Prefer environment variables over config.json.** Environment variables (`EINSTEIN_X402_PRIVATE_KEY`) are not persisted to disk and are harder to accidentally commit to git. If you must use config.json (`--save-config`), restrict file permissions:

```bash
chmod 600 config.json
```

**What gets signed.** Each paid query signs an EIP-3009 `TransferWithAuthorization` message that authorizes a USDC transfer of the exact query price (shown before confirmation) from your wallet to the Einstein service address. The signature is single-use (unique nonce) and time-limited. No blanket approvals are granted.

**Payment confirmation.** By default, the CLI prompts before every paid query showing the exact cost. To skip the prompt for scripted/automated use, pass `--yes` / `-y` per-command or set `EINSTEIN_AUTO_CONFIRM=true` globally.

**No auto-installed packages.** The setup wizard does NOT run `npm install` automatically. You must install dependencies yourself so you can audit what is being installed.

**No home directory scanning.** Configuration is loaded only from environment variables and the skill-local `config.json`. No paths outside the skill directory are read.

## Troubleshooting

**"No private key configured"**
Set `EINSTEIN_X402_PRIVATE_KEY` environment variable or run `node scripts/einstein-setup.mjs --save-config`.

**"Payment rejected" / "Insufficient balance"**
Your wallet needs USDC on Base. Bridge via https://bridge.base.org. Use a dedicated wallet with a small balance.

**"Cannot reach emc2ai.io"**
Check internet connection. The service may have temporary downtime.

**"Unknown service"**
Run `node scripts/einstein.mjs services` to see all available commands.

**"Dependencies not installed"**
Run `npm install` in the skill directory: `cd packages/project-einstein/openclaw-skill/einstein && npm install`

## References

- `references/services-catalog.md` — Full service catalog with parameters
- `references/payment-guide.md` — Detailed x402 payment protocol guide
- `references/examples.md` — Extended usage examples by category


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/services-catalog.md

```markdown
# Einstein x402 Services Catalog

Complete reference for all 27 Bitquery analytics endpoints available via x402 micropayments.

## Pricing Structure

Every endpoint has two variants:
- **Default (analyzed):** Includes AI-generated insights and analysis
- **Raw (`/raw` suffix):** Structured data only, saves $0.15 per query

**Payment:** USDC on Base network (chain ID 8453) via EIP-3009 TransferWithAuthorization.

---

## Tier 1: Basic Queries

### Latest Tokens
- **Command:** `latest-tokens`
- **Endpoint:** `/x402/bitquery/latest-pairs`
- **Price:** $0.25 raw / $0.40 analyzed
- **Parameters:** `chain` (required), `limit` (required)
- **Chains:** base, ethereum, bsc, arbitrum, polygon, optimism
- **Default chain:** base
- **Description:** Latest deployed tokens on-chain with liquidity pool data. Shows new token launches with initial liquidity and trading activity.

### Token Chart
- **Command:** `chart`
- **Endpoint:** `/x402/bitquery/tokenchart`
- **Price:** $0.25 raw / $0.40 analyzed
- **Parameters:** `chain` (required), `tokenAddress` (required), `timeperiod` (required)
- **Chains:** base, ethereum, bsc, arbitrum, polygon, optimism, zksync
- **Default chain:** base
- **Description:** Token price history and chart data for technical analysis. Returns time-series price points.

---

## Tier 2: Standard Analysis

### OHLCV
- **Command:** `ohlcv`
- **Endpoint:** `/x402/bitquery/ohlcv`
- **Price:** $0.40 raw / $0.55 analyzed
- **Parameters:** `chain` (required), `tokenAddress` (required), `timeperiod` (required)
- **Chains:** base, ethereum, bsc, arbitrum, polygon, optimism
- **Default chain:** base
- **Description:** Open, High, Low, Close, Volume candlestick data for advanced technical analysis. Returns full OHLC bars with volume metrics.

### Top Tokens
- **Command:** `top-tokens`
- **Endpoint:** `/x402/bitquery/top-tokens`
- **Price:** $0.40 raw / $0.55 analyzed
- **Parameters:** `chain` (required), `limit` (required)
- **Chains:** base, ethereum, bsc, arbitrum, polygon, optimism, zksync
- **Default chain:** base
- **Description:** Top tokens ranked by market cap with price, volume, and supply metrics.

### Top Movers
- **Command:** `top-movers`
- **Endpoint:** `/x402/bitquery/topvolume`
- **Price:** $0.40 raw / $0.55 analyzed
- **Parameters:** `chain` (required), `limit` (required), `timeperiod` (required)
- **Chains:** base, ethereum, bsc, arbitrum, polygon, optimism, zksync, solana
- **Default chain:** base
- **Description:** Top gainers/losers analysis with volume, price change percentage, and market insights.

### Virtuals Protocol
- **Command:** `virtuals`
- **Endpoint:** `/x402/bitquery/virtual-pools`
- **Price:** $0.40 raw / $0.55 analyzed
- **Parameters:** `limit` (required), `timeperiod` (required)
- **Chains:** base (only)
- **Default chain:** base
- **Description:** Virtuals Protocol agent tokens and bonding curves on Base.

### Wallet Holdings
- **Command:** `wallet`
- **Endpoint:** `/x402/bitquery/wallet-holdings`
- **Price:** $0.40 raw / $0.55 analyzed
- **Parameters:** `chain` (required), `walletAddress` (required)
- **Chains:** ethereum, base, bsc, arbitrum, polygon
- **Default chain:** ethereum
- **Description:** Complete wallet portfolio breakdown showing all token holdings and USD values.

### Holder Concentration
- **Command:** `holders`
- **Endpoint:** `/x402/bitquery/holderconcentration`
- **Price:** $0.40 raw / $0.55 analyzed
- **Parameters:** `chain` (required), `tokenAddress` (required), `limit` (required)
- **Chains:** ethereum, base, bsc, arbitrum, polygon
- **Default chain:** base
- **Description:** Token holder distribution analysis with concentration risk metrics.

---

## Tier 3: Platform Monitoring

### Zora Launches
- **Command:** `zora-launches`
- **Endpoint:** `/x402/bitquery/zora-launches`
- **Price:** $0.60 raw / $0.75 analyzed
- **Parameters:** `limit` (required), `timeperiod` (required)
- **Chains:** base (only)
- **Default chain:** base
- **Description:** Latest Zora Launchpad token deployments with deployer intel.

### Zora Volume
- **Command:** `zora-volume`
- **Endpoint:** `/x402/bitquery/zora-volume`
- **Price:** $0.60 raw / $0.75 analyzed
- **Parameters:** `limit` (required), `timeperiod` (required)
- **Chains:** base (only)
- **Default chain:** base
- **Description:** Top Zora Launchpad tokens by trading volume.

### Pump.fun Launches
- **Command:** `pump-launches`
- **Endpoint:** `/x402/bitquery/pumpfun-launches`
- **Price:** $0.60 raw / $0.75 analyzed
- **Parameters:** `limit` (required), `timeperiod` (required)
- **Chains:** solana (only)
- **Default chain:** solana
- **Description:** Fresh Pump.fun token launches with bonding curve progress.

### Pump.fun Volume
- **Command:** `pump-volume`
- **Endpoint:** `/x402/bitquery/pumpfun-volume`
- **Price:** $0.60 raw / $0.75 analyzed
- **Parameters:** `limit` (required), `timeperiod` (required)
- **Chains:** solana (only)
- **Default chain:** solana
- **Description:** Top Pump.fun tokens by volume with buyer/seller flow.

### Pump.fun Graduation
- **Command:** `pump-grads`
- **Endpoint:** `/x402/bitquery/pumpfun-graduation`
- **Price:** $0.60 raw / $0.75 analyzed
- **Parameters:** `limit` (required)
- **Chains:** solana (only)
- **Default chain:** solana
- **Description:** Pump.fun tokens approaching Raydium graduation threshold.

### BSC Alpha
- **Command:** `alpha`
- **Endpoint:** `/x402/bitquery/bscalpha`
- **Price:** $0.60 raw / $0.75 analyzed
- **Parameters:** `chain` (required), `limit` (required), `timeperiod` (required)
- **Chains:** bsc (only)
- **Default chain:** bsc
- **Description:** Aggregated alpha signals for early opportunities on BSC.

### Liquidity Shifts
- **Command:** `liquidity`
- **Endpoint:** `/x402/bitquery/liquidityshifts`
- **Price:** $0.60 raw / $0.75 analyzed
- **Parameters:** `chain` (required), `limit` (required), `timeperiod` (required)
- **Chains:** ethereum, base, bsc, arbitrum, polygon, optimism, zksync
- **Default chain:** ethereum
- **Description:** High-velocity DEX liquidity changes detecting significant market moves.

---

## Tier 4: Advanced Intelligence

### Whale Intel
- **Command:** `whale-intel`
- **Endpoint:** `/x402/bitquery/whaleintel`
- **Price:** $0.85 raw / $1.00 analyzed
- **Parameters:** `chain` (required), `limit` (required), `timeperiod` (required)
- **Chains:** ethereum, base, bsc, arbitrum, polygon
- **Default chain:** base
- **Description:** Token-centric whale accumulation view with net capital flows and top holders.

### Top Traders
- **Command:** `top-traders`
- **Endpoint:** `/x402/bitquery/toptraders`
- **Price:** $0.85 raw / $1.00 analyzed
- **Parameters:** `chain` (required), `limit` (required), `timeperiod` (required)
- **Chains:** bsc (only)
- **Default chain:** bsc
- **Description:** Top meme/bonding-curve traders on Four.meme platform.

### DEX Capital
- **Command:** `dex-capital`
- **Endpoint:** `/x402/bitquery/dexcapital`
- **Price:** $0.85 raw / $1.00 analyzed
- **Parameters:** `chain` (required), `limit` (required), `timeperiod` (required)
- **Chains:** bsc, base, ethereum, arbitrum, polygon, optimism, zksync
- **Default chain:** base
- **Description:** Capital-intensive traders across DEXes showing big money flows.

### Smart Money
- **Command:** `smart-money`
- **Endpoint:** `/x402/bitquery/smartmoney`
- **Price:** $0.85 raw / $1.00 analyzed
- **Parameters:** `chain` (required), `limit` (required), `timeperiod` (required)
- **Chains:** ethereum, base, bsc, arbitrum, polygon
- **Default chain:** base
- **Description:** Leaderboard of top trader wallets with buy/sell flow analysis and accumulation patterns.

### Token Sniping
- **Command:** `token-snipe`
- **Endpoint:** `/x402/bitquery/tokensniping`
- **Price:** $0.85 raw / $1.00 analyzed
- **Parameters:** `chain` (required), `tokenAddress` (required), `limit` (required)
- **Chains:** ethereum, base, bsc, arbitrum, polygon
- **Default chain:** base
- **Description:** Early token buyers analysis with bot detection and sniper identification.

### Polymarket Events
- **Command:** `polymarket`
- **Endpoint:** `/x402/bitquery/polymarket-events`
- **Price:** $0.85 raw / $1.00 analyzed
- **Parameters:** `limit` (required), `timeperiod` (required)
- **Chains:** polygon (only)
- **Default chain:** polygon
- **Description:** Real-time Polymarket contract events and position changes.

---

## Tier 5: Comprehensive Reports

### Polymarket Chain Compare
- **Command:** `polymarket-compare`
- **Endpoint:** `/x402/bitquery/polymarket-chain-compare`
- **Price:** $1.00 raw / $1.15 analyzed
- **Parameters:** `limit` (required)
- **Chains:** polygon (only)
- **Default chain:** polygon
- **Description:** Compare Polymarket API vs Polygon blockchain events for latency arbitrage, whale signals, settlement predictions.

### Investment Report
- **Command:** `investment-report`
- **Endpoint:** `/x402/bitquery/investment-report`
- **Price:** $1.00 raw / $1.15 analyzed
- **Parameters:** `chains` (required, comma-separated), `limit` (required), `timeperiod` (required)
- **Chains:** base, ethereum, bsc, solana, arbitrum, polygon, optimism, zksync
- **Default chain:** base
- **Description:** Multi-chain investment report with bonding curves, liquidity, and whale intel.

### NFT Analytics
- **Command:** `nft-analytics`
- **Endpoint:** `/x402/bitquery/nftanalytics`
- **Price:** $1.00 raw / $1.15 analyzed
- **Parameters:** `chain` (required), `limit` (required), `timeperiod` (required)
- **Chains:** ethereum, base, bsc, arbitrum, polygon, optimism
- **Default chain:** ethereum
- **Description:** NFT collection analysis: mints, whales, floor prices, wash trading detection.

### MEV Detection
- **Command:** `mev-detect`
- **Endpoint:** `/x402/bitquery/mevdetection`
- **Price:** $1.00 raw / $1.15 analyzed
- **Parameters:** `chain` (required), `limit` (required), `timeperiod` (required)
- **Chains:** ethereum, base, bsc, arbitrum, polygon
- **Default chain:** ethereum
- **Description:** Detect MEV activity: sandwich attacks, front-running, toxic flow analysis.

### Arbitrage Scanner
- **Command:** `arbitrage`
- **Endpoint:** `/x402/bitquery/arbitragescanner`
- **Price:** $1.00 raw / $1.15 analyzed
- **Parameters:** `chain` (required), `limit` (required), `timeperiod` (required)
- **Chains:** ethereum, base, bsc, arbitrum, polygon, optimism
- **Default chain:** ethereum
- **Description:** Cross-chain price discrepancies and profitable arbitrage routes.

### Rug Pull Scanner
- **Command:** `rug-scan`
- **Endpoint:** `/x402/bitquery/rug-pull-scanner`
- **Price:** $1.00 raw / $1.15 analyzed
- **Parameters:** `chain` (required), `tokenAddress` (required)
- **Chains:** ethereum, base, bsc, arbitrum, polygon
- **Default chain:** base
- **Description:** Token security analysis: holder concentration, liquidity locks, risk scoring.

---

## Parameter Reference

| Parameter | Type | Constraints | Description |
|-----------|------|-------------|-------------|
| `chain` | string | See supported chains per endpoint | Blockchain network to query |
| `chains` | string[] | Comma-separated | Multiple chains (investment-report only) |
| `limit` | integer | 1-500 | Number of results to return |
| `timeperiod` | string | 1d, 3d, 7d, 30d (max) | Time window for data |
| `tokenAddress` | string | 0x-prefixed hex (EVM) | Token contract address |
| `walletAddress` | string | 0x-prefixed hex (EVM) | Wallet address |

**Time period note:** Periods longer than 30d (e.g., 3m, 1y) are automatically clamped to 30d by the server.

## Response Format

All endpoints return JSON. The analyzed variant includes an `analysis` field with AI-generated insights. The raw variant returns only the structured data fields.

```

### references/payment-guide.md

```markdown
# Einstein x402 Payment Guide

How x402 micropayments work for Einstein analytics services.

## What is x402?

x402 is an HTTP-native payment protocol that uses the HTTP 402 ("Payment Required") status code. It enables machine-to-machine micropayments without accounts, API keys, or subscriptions.

**Think of it as:** HTTP authentication, but with money instead of credentials.

## How It Works

### The 3-Step Flow

```
1. REQUEST → Server responds 402 + payment challenge
2. SIGN    → Client signs USDC transfer authorization
3. PAY+GET → Client re-sends request with payment → gets data
```

### Step 1: Fetch Payment Challenge

When you hit an Einstein endpoint without payment:

```http
POST /x402/bitquery/topvolume HTTP/1.1
Content-Type: application/json

{"chain": "base", "limit": 10, "timeperiod": "7d"}
```

Server responds:

```http
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64-encoded challenge>
```

The decoded challenge contains:

```json
{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "USDC",
    "payTo": "0x<einstein-wallet>",
    "amount": "0.55",
    "decimals": 6,
    "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "extra": {
      "name": "USD Coin",
      "version": "2"
    },
    "maxTimeoutSeconds": 300
  }]
}
```

### Step 2: Sign Payment

The client signs an EIP-712 `TransferWithAuthorization` (EIP-3009) message:

```
Domain:
  name: "USD Coin"
  version: "2"
  chainId: 8453
  verifyingContract: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

Message (TransferWithAuthorization):
  from: <your wallet address>
  to: <einstein wallet address>
  value: 550000 (0.55 USDC × 10^6)
  validAfter: <now - 60 seconds>
  validBefore: <now + timeout>
  nonce: <random 32 bytes>
```

This signature authorizes USDC to transfer **without a separate approval transaction**. The USDC contract on Base natively supports EIP-3009, so the transfer is gasless for the payer.

### Step 3: Execute with Payment

The signed payload is base64-encoded and sent as a header:

```http
POST /x402/bitquery/topvolume HTTP/1.1
Content-Type: application/json
X-PAYMENT: <base64-encoded payment payload>

{"chain": "base", "limit": 10, "timeperiod": "7d"}
```

> **Note:** This skill uses the `X-PAYMENT` header (V1) which reliably passes through CDN/proxy infrastructure. The V2 `PAYMENT-SIGNATURE` header is also supported by the server but may be stripped by some reverse proxies.

Server verifies the signature via the Coinbase CDP facilitator, settles the USDC transfer, and returns the data:

```http
HTTP/1.1 200 OK
PAYMENT-RESPONSE: <base64-encoded receipt>

{...analytics data...}
```

## Cost Structure

| Tier | Raw Data | With AI Analysis |
|------|----------|------------------|
| Basic | $0.25 | $0.40 |
| Standard | $0.40 | $0.55 |
| Platform | $0.60 | $0.75 |
| Advanced | $0.85 | $1.00 |
| Comprehensive | $1.00 | $1.15 |

**AI analysis premium:** +$0.15 per query. Includes AI-generated insights, risk assessments, and actionable recommendations alongside the raw data.

## Funding Your Wallet

### Get USDC on Base

1. **Bridge from Ethereum:** https://bridge.base.org
2. **Buy directly:** Use Coinbase, then send USDC to Base
3. **DEX swap:** Swap ETH for USDC on Base via Uniswap or Aerodrome

### How Much to Fund

- Light usage (5-10 queries/day): $5-10 USDC
- Moderate usage (20-50 queries/day): $20-50 USDC
- Heavy usage (100+ queries/day): $50-100 USDC

### Check Balance

```bash
# Via the setup script
node scripts/einstein-setup.mjs

# Or directly via cast (if installed)
cast call 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  "balanceOf(address)(uint256)" <your-wallet-address> \
  --rpc-url https://mainnet.base.org
```

## Security Considerations

### Private Key Safety

- **Never share your private key**
- Use a **dedicated wallet** with only the USDC needed for queries
- The skill stores the key in `config.json` — ensure this file is gitignored
- Alternatively, use the `EINSTEIN_X402_PRIVATE_KEY` environment variable

### What the Signature Authorizes

Each EIP-3009 signature authorizes a **single, exact transfer**:
- Fixed amount (e.g., exactly $0.55 USDC)
- Fixed recipient (Einstein's wallet)
- Time-bounded (expires after the timeout period)
- Single-use nonce (cannot be replayed)

The signature **cannot** be used to:
- Transfer more than the stated amount
- Transfer to a different address
- Execute multiple times
- Approve unlimited spending

### Facilitator

Payment verification and settlement is handled by the **Coinbase CDP facilitator** (`https://api.cdp.coinbase.com/platform/v2/x402`). This is Coinbase's official x402 infrastructure.

## Payment Headers Reference

| Header | Direction | Protocol | Purpose |
|--------|-----------|----------|---------|
| `PAYMENT-REQUIRED` | Response (402) | v2 | Payment challenge |
| `PAYMENT-SIGNATURE` | Request | v2 | Signed payment |
| `PAYMENT-RESPONSE` | Response (200) | v2 | Payment receipt |
| `X-PAYMENT` | Request | v1 (legacy) | Signed payment |
| `X-PAYMENT-RESPONSE` | Response (200) | v1 (legacy) | Payment receipt |

The Einstein skill sends the `X-PAYMENT` header (V1) for reliable delivery through CDN/proxy layers.

## Network Details

| Property | Value |
|----------|-------|
| Payment Network | Base (chain ID 8453) |
| Network ID (CAIP-2) | `eip155:8453` |
| Token | USDC |
| Token Address | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
| Token Decimals | 6 |
| EIP-712 Domain Name | `USD Coin` |
| EIP-712 Domain Version | `2` |
| Facilitator | `https://api.cdp.coinbase.com/platform/v2/x402` |
| Signature Scheme | EIP-3009 TransferWithAuthorization |

## Troubleshooting

### "Payment rejected"
- Check USDC balance on Base
- Ensure private key is correct (64 hex chars + 0x prefix = 66 chars)
- The payment challenge may have expired — retry the request

### "Facilitator error"
- Coinbase CDP facilitator may be temporarily down
- Retry after a few seconds

### "Signature verification failed"
- The private key may not match the wallet with USDC
- Check that you're on Base mainnet, not testnet

### "Nonce already used"
- Retry the request — a new nonce will be generated automatically

```

### references/examples.md

```markdown
# Einstein x402 — Usage Examples

Detailed examples organized by use case. All examples assume the skill is set up with a funded wallet.

## Market Analysis

### "What are the top movers on Base today?"

```bash
node scripts/einstein.mjs top-movers --chain base --timeperiod 1d --limit 10
```

Cost: $0.55 USDC (analyzed) or $0.40 (raw with `--raw`)

### "Show me the top tokens on Ethereum by market cap"

```bash
node scripts/einstein.mjs top-tokens --chain ethereum --limit 20
```

### "What tokens were just deployed on Base?"

```bash
node scripts/einstein.mjs latest-tokens --chain base --limit 15
```

### "Check the biggest volume movers on Solana this week"

```bash
node scripts/einstein.mjs top-movers --chain solana --timeperiod 7d --limit 10
```

---

## Whale & Smart Money Tracking

### "Track whale accumulation on Ethereum"

```bash
node scripts/einstein.mjs whale-intel --chain ethereum --limit 10 --timeperiod 7d
```

Cost: $1.00 USDC (analyzed) or $0.85 (raw)

### "Show me the smart money leaderboard on Base"

```bash
node scripts/einstein.mjs smart-money --chain base --limit 20 --timeperiod 7d
```

### "Who are the biggest DEX traders on Arbitrum?"

```bash
node scripts/einstein.mjs dex-capital --chain arbitrum --limit 10 --timeperiod 3d
```

### "Find top meme traders on BSC"

```bash
node scripts/einstein.mjs top-traders --chain bsc --limit 15 --timeperiod 7d
```

---

## Token Security & Risk

### "Is this token a rug pull?"

```bash
node scripts/einstein.mjs rug-scan --chain ethereum --token 0x1234567890abcdef1234567890abcdef12345678
```

Cost: $1.15 USDC (analyzed) or $1.00 (raw)

Returns: Holder concentration, liquidity locks, deployer history, risk score.

### "Check for MEV attacks on Ethereum"

```bash
node scripts/einstein.mjs mev-detect --chain ethereum --limit 10 --timeperiod 1d
```

### "Who sniped this token at launch?"

```bash
node scripts/einstein.mjs token-snipe --chain base --token 0xabcdef... --limit 20
```

### "Check holder concentration for a token"

```bash
node scripts/einstein.mjs holders --chain base --token 0xabcdef... --limit 50
```

---

## Launchpad Monitoring

### "What's launching on Pump.fun?"

```bash
node scripts/einstein.mjs pump-launches --limit 15 --timeperiod 1d
```

Cost: $0.75 USDC (analyzed) or $0.60 (raw)

### "Which Pump.fun tokens are about to graduate to Raydium?"

```bash
node scripts/einstein.mjs pump-grads --limit 10
```

### "Show me Pump.fun tokens with the most volume"

```bash
node scripts/einstein.mjs pump-volume --limit 10 --timeperiod 1d
```

### "What's new on Zora Launchpad?"

```bash
node scripts/einstein.mjs zora-launches --limit 10 --timeperiod 3d
```

### "Top Zora tokens by volume"

```bash
node scripts/einstein.mjs zora-volume --limit 10 --timeperiod 7d
```

### "Show me Virtuals Protocol agent tokens"

```bash
node scripts/einstein.mjs virtuals --limit 10 --timeperiod 7d
```

---

## Portfolio & Wallet Analysis

### "What does this wallet hold?"

```bash
node scripts/einstein.mjs wallet --chain ethereum --wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
```

Cost: $0.55 USDC (analyzed) or $0.40 (raw)

### "Show me OHLCV data for a token"

```bash
node scripts/einstein.mjs ohlcv --chain base --token 0xabcdef... --timeperiod 30d
```

### "Get price chart for a token"

```bash
node scripts/einstein.mjs chart --chain base --token 0xabcdef... --timeperiod 7d
```

---

## DeFi Intelligence

### "Find arbitrage opportunities"

```bash
node scripts/einstein.mjs arbitrage --chain ethereum --limit 10 --timeperiod 1d
```

Cost: $1.15 USDC (analyzed) or $1.00 (raw)

### "Check liquidity movements"

```bash
node scripts/einstein.mjs liquidity --chain ethereum --limit 10 --timeperiod 3d
```

### "BSC alpha signals"

```bash
node scripts/einstein.mjs alpha --chain bsc --limit 10 --timeperiod 1d
```

---

## Investment Reports

### "Give me a multi-chain investment overview"

```bash
node scripts/einstein.mjs investment-report --chains base,ethereum,bsc --limit 10 --timeperiod 7d
```

Cost: $1.15 USDC (analyzed) or $1.00 (raw)

This is the most comprehensive endpoint — combines bonding curve analysis, liquidity metrics, whale intel, and market signals across multiple chains.

---

## NFT Analytics

### "Analyze NFT collections on Ethereum"

```bash
node scripts/einstein.mjs nft-analytics --chain ethereum --limit 10 --timeperiod 7d
```

Cost: $1.15 USDC (analyzed) or $1.00 (raw)

Returns: Mint activity, whale collectors, floor prices, wash trading detection.

---

## Prediction Markets

### "What's happening on Polymarket?"

```bash
node scripts/einstein.mjs polymarket --limit 10 --timeperiod 7d
```

Cost: $1.00 USDC (analyzed) or $0.85 (raw)

### "Compare Polymarket API vs on-chain data"

```bash
node scripts/einstein.mjs polymarket-compare --limit 10
```

Cost: $1.15 USDC (analyzed) or $1.00 (raw)

Useful for detecting latency between API prices and actual blockchain settlements.

---

## Getting Data-Only (Raw) Responses

Add `--raw` to any command to skip AI analysis and save $0.15:

```bash
# Analyzed (default): $0.55
node scripts/einstein.mjs top-movers --chain base --limit 10

# Raw data only: $0.40
node scripts/einstein.mjs top-movers --chain base --limit 10 --raw
```

Raw responses return structured JSON without the `analysis` field. Useful when your agent will process the data with its own logic.

---

## Batch Queries

Run multiple queries sequentially:

```bash
# Morning market scan
node scripts/einstein.mjs top-movers --chain base --timeperiod 1d --limit 10 && \
node scripts/einstein.mjs whale-intel --chain base --timeperiod 1d --limit 5 && \
node scripts/einstein.mjs pump-grads --limit 5
```

Total cost: ~$0.55 + $1.00 + $0.75 = $2.30 USDC

---

## Output Handling

All data goes to **stdout** as JSON. Diagnostic messages go to **stderr**.

```bash
# Save to file
node scripts/einstein.mjs top-movers --chain base > movers.json 2>/dev/null

# Pipe to jq
node scripts/einstein.mjs top-movers --chain base 2>/dev/null | jq '.tokens[0]'

# Parse in another script
MOVERS=$(node scripts/einstein.mjs top-movers --chain base --raw 2>/dev/null)
echo "$MOVERS" | jq -r '.tokens[].symbol'
```

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "chuxo",
  "slug": "einstein",
  "displayName": "Einstein x402 Blockchain Analytics",
  "latest": {
    "version": "1.1.0",
    "publishedAt": 1770844090451,
    "commit": "https://github.com/openclaw/skills/commit/ab03442fed14b3c6d4b8b2a951481fd1cd0a254d"
  },
  "history": [
    {
      "version": "1.0.0",
      "publishedAt": 1770120856216,
      "commit": "https://github.com/clawdbot/skills/commit/57f0f4d096418a34f39d94abc5e15c762e9a42c8"
    }
  ]
}

```