# DeepBlue Trading API
> AI-powered crypto trading signals and DeFi research. Pay-per-call with USDC via x402.

## Base URL
https://api.deepbluebase.xyz

## Payment
Protocol: x402 v2 (HTTP 402). Currency: USDC. Networks: Solana mainnet, Base mainnet.
Send payment in 'payment-signature' header as base64-encoded x402 v2 payload.
Active facilitator: https://api.cdp.coinbase.com/platform/v2/x402
Supported facilitators: Coinbase CDP, x402endpoints.online, PayAI

## Endpoints
- GET /signals — Live BTC/ETH/SOL/XRP 5-min trading signals ($0.005)
- GET /performance — Verified Polymarket P&L and win rate ($0.01)
- GET /sentiment — Crypto sentiment composite ($0.01)
- GET /trending — Trending DeFi pools on Base ($0.005)
- GET /price/{token} — Real-time token price ($0.001)
- GET /token/{addr} — Token analysis & risk scoring ($0.01)
- GET /wallet/{addr} — Wallet portfolio scan ($0.01)
- GET /polymarket — Prediction market analytics ($0.01)
- GET /polymarket/markets — Market intelligence feed ($0.01)
- GET /polymarket/5min — 5-min epoch market discovery ($0.01)
- GET /market-snapshot — All-coins snapshot ($0.01)
- GET /market-intel — BTC macro + funding rates ($0.02)
- GET /market-mood — Fear/greed + regime + bias ($0.01)
- GET /whale-moves — Whale movements + exchange flows ($0.02)
- GET /sentiment/composite — Multi-source sentiment ($0.01)
- GET /btc/realtime-signal — Live directional signal ($0.005)
- GET /prediction-markets — Premium bundle ($0.03)
- GET /crypto-sentiment — Premium sentiment bundle ($0.03)
- GET /discover — Search x402 ecosystem ($0.002)

## Free Endpoints (no payment, test the data shape first)
- GET /health — API health + dependency checks
- GET /pricing — Pricing table
- GET /public/latest-signal — Last live 5-min signal (free preview)
- GET /public/recent-trades — Last 5 trades (free preview)
- GET /.well-known/x402 — Payment discovery
- GET /.well-known/openapi.json — OpenAPI 3.1 spec

## Path Parameter Examples (substitute literally — do NOT keep braces)
- /price/{token}  → /price/BTC  or  /price/ETH  or  /price/SOL  or  /price/XRP
- /token/{addr}   → /token/0x4200000000000000000000000000000000000006   (WETH on Base)
- /wallet/{addr}  → /wallet/0x47ffc880cfF2e8F18fD9567faB5a1fBD217B5552  (this bot's own wallet)

## Quickstart — pay nothing, then pay automatically

### Option A. Free demo budget (zero setup, zero wallet)
Every IP gets 5 free calls/day on ANY paid endpoint — no payment header needed. Use this to validate data shape before wiring x402.
```
# Works directly. First 5/day are free per IP, no auth, no wallet.
curl -s https://api.deepbluebase.xyz/price/BTC
curl -s https://api.deepbluebase.xyz/signals
curl -s https://api.deepbluebase.xyz/sentiment
```

### Option B. Free public preview endpoints (unlimited)
```
curl -s https://api.deepbluebase.xyz/public/latest-signal   # last 5-min signal (preview of /signals)
curl -s https://api.deepbluebase.xyz/public/recent-trades   # last 5 trades (preview of /performance)
```

### Option C. Pay automatically with an x402 SDK (after demo budget)
Do NOT try to hand-craft the X-Payment header — use one of the SDKs below. Pick by runtime.

**TypeScript / Node (Vercel, serverless, browser-side agents):**
```
// npm install x402-fetch viem
import { wrapFetchWithPayment } from 'x402-fetch';
import { privateKeyToAccount } from 'viem/accounts';
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const fetchPay = wrapFetchWithPayment(fetch, account);
const r = await fetchPay('https://api.deepbluebase.xyz/price/BTC');
console.log(await r.json());  // pays $0.001 USDC on Base, returns price JSON
```

**Python (sync, requests-based):**
```
# pip install 'x402[requests]' eth-account
import os
from eth_account import Account
from x402 import x402ClientSync
from x402.http.clients.requests import x402_requests
client = x402ClientSync()
client.register_scheme_default(Account.from_key(os.environ['PRIVATE_KEY']))
session = x402_requests(client)
r = session.get('https://api.deepbluebase.xyz/price/BTC')
print(r.json())
```

**AgentCash / MCP-aware agents (Claude Code, Cursor, MCP clients):**
```
// agentcash.fetch('https://api.deepbluebase.xyz/price/BTC')
// Wallet auto-pays the 402 challenge, retries, returns the body.
```

## Free Alternative Endpoints (paid → free fallback map)
Every paid endpoint either has a free public preview or falls under the 5/day demo budget. If you can't pay yet, hit these instead:
- /signals ($0.005)         → /public/latest-signal (free, unlimited)
- /performance ($0.01)      → /public/recent-trades (free, unlimited)
- /sentiment, /trending, /price/*, /token/*, /wallet/*, /polymarket/*, /market-* — first 5/day per IP free via demo budget

## OpenAPI Spec
https://api.deepbluebase.xyz/openapi.json