# x402 Meta Gateway — Full API Documentation

> AI-synthesized crypto trading intelligence for autonomous agents. 14 paid endpoints + MCP server. Pay per query with USDC micropayments on Base, Ethereum, or Solana via x402 protocol. Endpoints include Twitter/X data when available.

Base URL: https://x402.911fund.io

## How Payment Works

1. Send a GET request to any /alpha/* endpoint without payment
2. Receive HTTP 402 with payment requirements (amount, chain options, facilitator details)
3. Sign payment with your wallet (EIP-712 for EVM, signTransaction for Solana)
4. Retry the same request with `X-PAYMENT: <signed_payment>` header
5. Receive data

The `@x402/fetch` SDK automates steps 1-4 for EVM chains.

## MCP Server

Endpoint: POST https://x402.911fund.io/mcp
Transport: Streamable HTTP
Protocol: JSON-RPC 2.0
Headers: `Content-Type: application/json`, `Accept: application/json, text/event-stream`
Payment: `X-PAYMENT` header with signed payment for paid tools

Agent configuration:
```json
{
  "mcpServers": {
    "x402-alpha": {
      "url": "https://x402.911fund.io/mcp",
      "transport": "streamable-http"
    }
  }
}
```

MCP tools map 1:1 to REST endpoints. Same data, same pricing. Tool names use underscores: `alpha_token`, `alpha_trending`, `alpha_sentiment`, `alpha_search`, `alpha_deep`, `alpha_prediction`, `alpha_macro`, `alpha_news`, `alpha_stats` (free).

## Trust and Billing Semantics

- `400 invalid_params`: malformed or missing required input. No charge.
- `422 needs_clarification`: ambiguous or too-short input for reliable routing. No charge.
- `402 Payment Required`: valid request shape, payment challenge required before execution.
- `preview=true` (REST) / `preview: true` (MCP): no-charge estimate only.
- Payment authorizes a compute attempt, not guaranteed upstream availability.
- `/alpha/sentiment` requires Twitter and may return `503 upstream_failed` when Twitter is unavailable.
- Other endpoints may return `200` with `warnings:["twitter_unavailable"]` if X/Twitter data is missing.

## Query Quality Guidance

### Endpoint Query Playbook

| Endpoint | Strong query example | Weak query example |
|---|---|---|
| `/alpha/token` | `/alpha/token?symbol=SOL` or `/alpha/token?address=0x...` | `/alpha/token?symbol=x` |
| `/alpha/trending` | `/alpha/trending` or `/alpha/trending?category=defi` | `/alpha/trending?category=random` |
| `/alpha/sentiment` | `/alpha/sentiment?query=JUP unlock schedule impact` | `/alpha/sentiment?query=hi` |
| `/alpha/search` | `/alpha/search?query=Solana DEX fee switch timeline 2026` | `/alpha/search?query=ok` |
| `/alpha/deep` | `/alpha/deep?query=Base L2 sequencer decentralization roadmap 2026` | `/alpha/deep?query=coin` |
| `/alpha/prediction` | `/alpha/prediction?query=fed rate cut by June 2026&category=economics` | `/alpha/prediction?query=test` |
| `/alpha/macro` | `/alpha/macro?theme=inflation` | `/alpha/macro?theme=whatever` |
| `/alpha/news` | `/alpha/news?query=bitcoin ETF flows&category=coindesk` | `/alpha/news?query=hi` |


Use explicit prompts with asset + topic + context/time window:
- `/alpha/search?query=Jupiter+DEX+Solana+fee+switch+timeline+2026`
- `/alpha/deep?query=Base+L2+sequencer+decentralization+roadmap+2026`
- `/alpha/prediction?query=fed+rate+cut+by+June+2026&category=economics`

Avoid low-signal prompts such as `hi`, `test`, and single-word ambiguous terms.

## Endpoints

### GET /alpha/token — $0.03 USDC

AI-synthesized token intelligence (DexScreener + CoinGecko + Twitter + Grok).

Parameters:
- `symbol` (required*): Token symbol — SOL, ETH, WIF, PEPE, BTC
- `address` (required*): Contract address (alternative to symbol)
- `token` (required*): Alias for symbol or address
- `q` (required*): Alias for symbol
- `chain` (optional): Chain for lookup, default: base

*One of symbol, address, token, or q is required.

Response includes:
- `price`, `volume24h`, `marketCap`, `priceChange24h` from DexScreener + CoinGecko
- `twitter.tweets[]` with text, author, likes, views, retweets, bookmarks, followers, verified, bio
- `twitter.topByEngagement[]` sorted by total engagement
- `grokAnalysis` — AI synthesis with trading signals, sentiment score, key narratives

### GET /alpha/trending — $0.03 USDC

Trending tokens with Twitter analysis + AI narrative detection.

Parameters:
- `category` (optional): Filter by category
- `limit` (optional): Number of results

Response includes:
- Array of trending tokens with price action, volume spikes
- X/Twitter mentions and engagement data per token
- `grokAnalysis` — AI narrative detection (what themes are driving the market)

### GET /alpha/sentiment — $0.062 USDC

X (up to 99 tweets) + Reddit posts with full engagement metrics + Grok bull/bear scoring and an X-vs-Reddit corroboration check.

Parameters:
- `query` (required*): Search query — cashtag ($WIF), topic, or account
- `q` (required*): Alias for query
- `topic` (required*): Alias for query
- `token` (required*): Alias for query

*One of query, q, topic, or token is required.

Response includes:
- `tweets[]` — up to 99 tweets with text, author, likes, views, retweets, bookmarks, quotes, replies, followers, verified, bio, url
- `reddit.posts[]` — crypto-filtered Reddit posts with title, text, subreddit, author, upvotes, comments, upvoteRatio, url
- `topByEngagement[]` — tweets sorted by total engagement
- `engagement` — aggregate totals (totalLikes, totalViews, totalRetweets, verifiedAuthors, avgFollowers)
- `grokAnalysis` — AI bull/bear scoring with sentiment breakdown, key narratives, notable accounts

### GET /alpha/search — $0.03 USDC

Neural web search + Twitter + AI synthesis (Exa + Grok).

Parameters:
- `query` (required*): Research query — e.g., "Jupiter DEX Solana", "Ethereum ETF flows"
- `q` (required*): Alias for query

*One of query or q is required.

Response includes:
- `results[]` — web search results with title, url, snippet, relevance score
- `twitter` — related tweets with engagement data
- `grokAnalysis` — AI synthesis combining web + social sources

### GET /alpha/deep — $0.10 USDC

Deep multi-source research (Exa + Firecrawl + Claude + up to 99 tweets). Premium endpoint, up to 60 seconds.

Parameters:
- `query` (required*): Research question
- `topic` (required*): Alias for query
- `token` (required*): Alias for query
- `url` (required*): Specific URL to research

*One of query, topic, token, or url is required.

Response includes:
- `research` — deep analysis from Claude combining all sources
- `sources[]` — Exa search results + Firecrawl extracted content
- `twitter` — up to 99 tweets with full engagement metrics
- `grokAnalysis` — AI synthesis layer

### GET /alpha/prediction — $0.03 USDC

Prediction market intelligence (Polymarket + Kalshi + Twitter + Grok).

Parameters:
- `query` (required): Prediction query — "fed chair", "trump tariff", "bitcoin 150k", "recession", "election"
- `q` (optional): Alias for query
- `category` (optional): Filter — crypto, politics, economics, sports, other

Response includes:
- `markets[]` — matching prediction markets with current odds, volume, expiry, clickable URLs
- `grokAnalysis` — AI synthesis of what prediction markets signal

### GET /alpha/macro — $0.05 USDC

Macro economic pulse (FRED + prediction markets + Twitter + Grok).

Parameters:
- `theme` (optional): Macro theme — inflation, employment, rates, gdp, housing. Defaults to broad overview.

Response includes:
- `fred` — Federal Reserve Economic Data (GDP, CPI, unemployment, rates)
- `predictions` — related prediction market odds
- `grokAnalysis` — AI synthesis of macro outlook and crypto implications

### GET /alpha/news — $0.02 USDC

AI-filtered crypto news from CoinTelegraph, Decrypt, CoinDesk, Blockworks + X/Twitter with AI synthesis.

Parameters:
- `query` (optional): Search keyword — bitcoin, ETF, regulation, solana
- `category` (optional): Filter by source — coindesk, cointelegraph, decrypt, blockworks

Response includes:
- `articles[]` — news articles with title, source, url, summary, publishedAt
- `twitter` — related tweets
- `grokAnalysis` — AI synthesis of news themes and market implications

### GET /alpha/onchain — $0.05 USDC

On-chain activity intelligence — whale movements, large transfers, DEX volume anomalies, smart money tracking.

Parameters:
- `symbol` (required*): Token symbol — SOL, ETH, BTC
- `address` (required*): Contract address
- `token` (required*): Alias for symbol/address
- `chain` (optional): Chain filter — base, ethereum, solana. Default: all.
- `timeframe` (optional): Lookback window — 1h, 4h, 24h, 7d. Default: 24h.

*One of symbol, address, or token is required.

Response includes:
- `data.volume` — DEX volume data with 24h change percentage
- `data.whaleActivity[]` — large transfers with direction, amount, addresses, timestamp
- `data.liquidityChanges` — added/removed/net liquidity in USD
- `data.smartMoney` — accumulation signal with confidence score
- `twitter` — related on-chain discussion
- `grokAnalysis` — AI synthesis of on-chain activity patterns

### GET /alpha/compare — $0.05 USDC

Side-by-side token comparison across price action, volume, sentiment, and fundamentals.

Parameters:
- `tokens` (required): Comma-separated token symbols (2-5), e.g. SOL,ETH or WIF,PEPE,BONK
- `addresses` (optional): Comma-separated contract addresses (alternative)
- `metrics` (optional): Focus areas — price,volume,sentiment,holders,liquidity. Default: all.

Response includes:
- `data.tokens[]` — per-token objects with price, marketCap, volume24h, priceChange24h/7d, sentiment
- `data.comparison` — leader summaries (momentum_leader, volume_leader, sentiment_leader)
- `twitter` — social mentions per token
- `grokAnalysis` — AI comparative synthesis

### GET /alpha/narrative — $0.05 USDC

Detect and track active market narratives — AI tokens, RWA, L2 wars, memecoins, DePIN. What stories drive capital flows.

Parameters:
- `narrative` (optional): Specific narrative slug — ai, rwa, meme, l2, depin, defi, gaming. If omitted, returns top active narratives.
- `query` (optional): Free-text narrative query — "AI agent tokens", "real world assets"
- `q` (optional): Alias for query
- `limit` (optional): Number of narratives to return. Default: 5.

Response includes:
- `data.narratives[]` — narrative objects with name, slug, strength score, trend, top tokens, catalysts, volume, mindshare
- `data.rotations` — capital flow signals (flowing_in, flowing_out)
- `twitter` — narrative mentions
- `grokAnalysis` — AI narrative synthesis

### GET /alpha/calendar — $0.03 USDC

Upcoming crypto events — token unlocks, protocol upgrades, governance votes, mainnet launches, conferences.

Parameters:
- `symbol` (optional): Filter by token — SOL, ETH, ARB
- `query` (optional): Free-text event query — "Ethereum upgrade", "token unlock"
- `q` (optional): Alias for query
- `days` (optional): Look-ahead window — 7, 14, 30. Default: 14.
- `category` (optional): Event type — unlock, upgrade, governance, launch, conference, earnings

Response includes:
- `data.events[]` — event objects with title, type, date, token, impact level, details, source
- `data.impact_summary` — high impact event count and affected tokens
- `twitter` — event buzz
- `grokAnalysis` — AI event impact synthesis
- Note: Event data is AI-synthesized. Response includes `warnings:["ai_synthesized_events"]`.

### GET /alpha/risk — $0.062 USDC

Token safety assessment — contract audit status, rug pull signals, liquidity depth, holder concentration, honeypot detection, plus X and Reddit scam-report corroboration.

Parameters:
- `symbol` (required*): Token symbol
- `address` (required*): Contract address (preferred for accuracy)
- `token` (required*): Alias for symbol/address
- `chain` (optional): Chain for lookup. Default: auto-detect.

*One of symbol, address, or token is required.

Response includes:
- `data.riskScore` — overall risk score (0-100, lower is safer)
- `data.riskLevel` — low, medium, high, or critical
- `data.factors` — breakdown: audit (status + score), liquidity (depth + score), holders (concentration + score), contract (flags + score), social (scam mentions + score)
- `data.warnings[]` — specific risk warnings
- `twitter` — scam/security mentions on X
- `reddit` — crypto-filtered Reddit scam/security posts (subreddit, upvotes, comments)
- `grokAnalysis` — AI risk assessment narrative

### GET /alpha/portfolio — $0.05 USDC

Wallet portfolio analysis — token holdings, diversification score, risk exposure, correlation analysis, AI rebalancing suggestions.

Parameters:
- `wallet` (required*): Wallet address (EVM 0x... or Solana base58)
- `address` (required*): Alias for wallet
- `chain` (optional): Chain for lookup — base, ethereum, solana. Default: auto-detect from address format.

*One of wallet or address is required.

Response includes:
- `data.totalValue_usd` — total portfolio value
- `data.holdings[]` — per-token objects with symbol, balance, value_usd, percentage, 24h change
- `data.analysis` — diversification_score, risk_level, concentration metrics, correlation
- `grokAnalysis` — AI portfolio synthesis with rebalancing suggestions

## Free Endpoints

### GET /health
Returns `{ "status": "ok" }`

### GET /stats
Returns uptime, memory usage, request counts, per-endpoint analytics, rate limit info.

### GET /.well-known/x402.json
Machine-readable x402 payment discovery with all endpoint pricing and chain details.

## Payment Chains

| Chain | Signing Method | USDC Contract |
|---|---|---|
| Base | EIP-712 signTypedData | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
| Ethereum | EIP-712 signTypedData | 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 |
| Solana | signTransaction (SPL) | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v |

Receiver wallets:
- EVM: 0xd86F1F35d6B15fEBef2f4a4390b584D8a7deC0B6
- Solana: CtbPTTFMRfULUMz7DjPDRCKXVSBEcAEXeTUq4n7fSFuf

## TypeScript Quick Start (Base)

```typescript
import { createX402Fetch } from "@x402/fetch";
import { createWalletClient, http } from "viem";
import { base } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const walletClient = createWalletClient({ account, chain: base, transport: http() });
const x402Fetch = createX402Fetch(walletClient);

const res = await x402Fetch("https://x402.911fund.io/alpha/token?symbol=SOL");
const data = await res.json();
```

## Error Codes

| Status | Meaning |
|---|---|
| 402 | Payment required — follow x402 payment flow |
| 400 | Bad request — check required parameters |
| 429 | Rate limited (30 req/min) — wait and retry |
| 500 | Upstream service error — retry after brief delay |

## Links

- API: https://x402.911fund.io
- Docs: https://github.com/the911fund/x402-docs
- x402scan: https://www.x402scan.com/server/6b9891e8-6939-4c9c-842f-9658f99cb6f3
- x402 Protocol: https://x402.org
- @x402/fetch SDK: https://github.com/coinbase/x402

## Runtime Contract Updates (2026-02-18)

### Discovery additions (`/.well-known/x402.json`)

Each paid `resources[]` entry now includes:
- `resource` absolute URL
- `tags` and `serviceTags`
- `inputSchema` and `outputSchema`
- `examples`
- `accepts[]` with `scheme`, `network`, `asset`, `payTo`, `maxAmountRequired`

### Stats additions (`/stats`)

- `paymentConversion`:
  - `paidExecutions`
  - `paid5xxFailures`
  - `paid5xxRatePctOfPaid`
  - `paid5xxPerChallengePct`
- `latency` rolling quantiles (`p50_ms`, `p95_ms`, `p99_ms`, `max_ms`) overall and by endpoint

### Error envelope additions

REST API errors now include:
- top-level `request_id`
- `error.action` for actionable remediation guidance

Missing required input should resolve as:
- `422 needs_clarification`
- no charge (`meta.price_charged=false`)