# ChainRay v2.5.3 — Complete API Reference (93 Paid + 8 Free Endpoints)

> 46-chain on-chain analytics & agent infrastructure.
> Pay-per-request with USDC via x402 protocol. No API keys. No subscriptions.
> Chain Proof v3 on every response (dataHash + analysisHash for verifiable AI).

## Free Endpoints (no payment required)

- GET /                — API overview, version, chain list, features
- GET /health          — System health: cache, memory, uptime, facilitator status
- GET /chains          — All 46 supported chains with metadata
- GET /llms.txt        — Concise AI discovery document (English)
- GET /llms-full.txt   — Complete endpoint reference (this file)
- GET /llms-ja.txt     — AI発見ドキュメント（日本語）
- GET /.well-known/privacy.json — Privacy policy (no-log, no-track, no-KYC)
- GET /mcp             — MCP protocol info + tool count
- SSE /mcp/sse         — MCP streaming session (79 tools for AI agents)

────────────────────────────────────────────────

## 🟢 Basic — $0.01 × 14 endpoints

| Endpoint | Params | Description |
|----------|--------|-------------|
| /price/:token | ?chain= | Token price (ETH/native or 0x address) via Uniswap V3 on-chain |
| /gas-tracker | ?chain= | Real-time gas prices (baseFee, fast, standard, slow, trend) |
| /gas-history | ?chain=&blocks=20 | Gas price history over N blocks |
| /whale-alerts | ?chain=&minAmount=50000 | Large transfers (native + USDC) |
| /nft/:contract | ?chain= | NFT collection metadata (name, supply, type) |
| /contract-events/:address | ?chain=&blocks= | Recent contract event logs |
| /governance/:address | ?chain= | Governance token analysis |
| /ens-resolve/:nameOrAddress | -- | ENS name ↔ address resolution (Ethereum) |
| /address-labels/:address | -- | Address Intelligence labels (whale/smart_money) |
| /token-supply/:address | ?chain= | ERC20 total supply, decimals, name |
| /block-info/:number | ?chain= | Block details (timestamp, txCount, gasUsed) |
| /contract-verify/:address | ?chain= | Contract bytecode verification |
| /oracle/price-feed/:token | ?chain= | Verified price oracle with Chain Proof |
| /agent-card/:agentId | -- | Look up a specific A2A agent card |

────────────────────────────────────────────────

## 🟡 Standard-Lite — $0.02 × 11 endpoints

| Endpoint | Params | Description |
|----------|--------|-------------|
| /gas-predict | ?chain= | Gas price prediction (next-block ML model) |
| /trending-tokens | ?chain= | Hot tokens by volume/holder growth |
| /recent-interactions/:address | ?chain= | Recent contract interactions for a wallet |
| /token-holders/:address | ?chain= | Top holders of an ERC20 token |
| /bridge-monitor | ?chain= | Cross-chain bridge activity |
| /nft-floor/:contract | ?chain= | NFT floor price estimation |
| /gas-optimization | ?chain= | Gas optimization recommendations |
| /stablecoin-supply | ?chain= | Stablecoin supply tracking |
| /oracle/gas-avg | ?chains= | Multi-chain gas average aggregation |
| /agent-card/discover | ?cap=&chain= | Discover A2A agents by capability |
| /solver-feed | ?from=&to=&amount= | ERC-7683 intent solver profitability feed |

────────────────────────────────────────────────

## 🔵 Standard — $0.03 × 15 endpoints

| Endpoint | Params | Description |
|----------|--------|-------------|
| /token-risk/:address | ?chain= | ERC20 token safety scoring (ownership, mint, proxy) |
| /defi-yields | ?chain= | Aave V3 lending rates (on-chain reads) |
| /defi-compare | ?chain= | Aave V3 market comparison |
| /stablecoin-monitor | ?chain= | Stablecoin stability analysis |
| /protocol-tvl | ?chain= | Protocol TVL (Aave + Compound on-chain) |
| /yield-farming | ?chain= | Yield farming opportunities |
| /flashloan-monitor | ?chain= | Flash loan detection |
| /liquidation-alerts | ?chain= | DeFi liquidation tracking |
| /token-approval/:address | ?chain= | Token approval risk scanner |
| /multi-sig/:address | ?chain= | Multi-sig wallet analysis |
| /tx-decode/:hash | ?chain= | Transaction decoding |
| /nft-holders/:contract | ?chain= | NFT holder distribution |
| /dex-trades/:pool | ?chain= | DEX trade history |
| /oracle/chain-status | -- | Multi-chain health & block freshness |
| /sentiment/:token | ?chain= | 5-signal on-chain sentiment oracle |

────────────────────────────────────────────────

## 🟣 Premium — $0.05 × 23 endpoints

| Endpoint | Params | Description |
|----------|--------|-------------|
| /wallet-profile/:address | ?chain= | Comprehensive wallet analysis |
| /contract-scan/:address | ?chain= | Smart contract security scan |
| /mev-detect/:hash | ?chain= | MEV detection on executed transactions |
| /token-screener | ?chain= | Multi-factor token screening |
| /liquidity-depth/:pool | ?chain= | DEX liquidity depth analysis |
| /smart-money | ?chain= | Smart money tracking |
| /portfolio-analyze/:address | ?chain= | Portfolio analysis & diversification score |
| /market-overview | -- | Cross-chain market snapshot (gas + price + TVL) |
| /chain-compare | ?chains= | Side-by-side chain comparison |
| /credit-score/:address | ?chain= | On-chain credit scoring |
| /risk-dashboard/:address | ?chain= | Risk analysis dashboard |
| /bridge-flow | ?chain= | Cross-chain bridge flow analysis |
| /protocol-health | ?chain= | DeFi protocol health metrics |
| /cross-chain/:address | -- | Cross-chain activity aggregation |
| /sandwich-scanner/:hash | ?chain= | Sandwich attack detection |
| /token-unlock/:address | ?chain= | Token unlock schedule |
| /yield-aggregator | ?chain= | Multi-protocol yield aggregation |
| /chain-health | -- | Chain infrastructure health |
| /defi-opportunity | ?chain= | DeFi opportunity finder |
| /whale-tracker | ?chain= | Whale activity tracker |
| /agent-reputation/:address | ?chain=&format=erc8004 | 10-factor KYA trust score |
| /mev-shield | ?action=&tokenIn=&amount= | Pre-trade MEV risk analysis |
| POST /agent-card/register | body: {agentId, name, ...} | Register A2A agent card |

────────────────────────────────────────────────

## 🔷 CaaS v1 — $0.08 × 1 endpoint

| Endpoint | Params | Description |
|----------|--------|-------------|
| /context-brief | ?intent=swap|bridge|invest | Multi-signal context brief for AI agents |

## 💠 CaaS v2 — $0.12 × 1 endpoint

| Endpoint | Params | Description |
|----------|--------|-------------|
| POST /context-brief/workflow | body: {agents, intent, chains} | Multi-agent workflow orchestration brief |

## 💎 Ultra — $0.10 × 1 endpoint

| Endpoint | Params | Description |
|----------|--------|-------------|
| /address-report/:address | ?chain= | Comprehensive address analysis report |

## 🔶 Batch — $0.003 per sub-query

| Endpoint | Params | Description |
|----------|--------|-------------|
| POST /batch | body: {queries: [{path, params}]} | Up to 10 queries in one call (bulk discount) |

────────────────────────────────────────────────

## Chain Support (46 chains)

### EVM (35): base, ethereum, arbitrum, optimism, polygon, bsc, avalanche, zksync, linea, scroll, blast, mantle, gnosis, polygon-zkevm, mode, sei, celo, manta, taiko, fantom, cronos, opbnb, zora, worldchain, metis, fraxtal, kava, zetachain, filecoin, core-dao, aurora, moonbeam, klaytn, bob, canto

### Non-EVM (11): solana, sui, aptos, ton, xrp, tron, doge, cardano, near, cosmos, bitcoin

## Technical Features
- Chain Proof v3: dataHash (SHA-256 of payload) + analysisHash (methodology fingerprint)
- Address Intelligence: Auto-learning whale/smart money database (10k LRU)
- Singleflight cache: Prevents thundering herd, 3-120s TTL per endpoint
- MCP SSE: 79 tools for Claude/Cursor/AI agents
- A2A: Google Agent-to-Agent protocol compatible
- ERC-8004: Agent identity standard for trust scoring
- ERC-7683: Intent solver standard for cross-chain execution
- Multi-Facilitator: Automatic failover for payment settlement
- Privacy: No user data stored, no IP logging, no KYC

## Discovery Files
- /llms.txt — Concise version (English)
- /llms-full.txt — This file (complete reference)
- /llms-ja.txt — 日本語版
- /openapi.json — OpenAPI 3.0 spec
- /.well-known/x402.json — x402 resource discovery
- /.well-known/privacy.json — Privacy policy
- /mcp — MCP info

## Contact
- Email: chainraydev@proton.me