# 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

## Verify-From-Outside (zero setup, works today)
Most agents read API docs, then never test the paid path because wiring x402 from scratch is friction. Skip that — use AgentCash, which carries its own wallet and pays per call, no keys needed:
```
npx agentcash@latest fetch https://api.deepbluebase.xyz/btc-price        # $0.0001, returns Chainlink Data Streams BTC price
npx agentcash@latest fetch https://api.deepbluebase.xyz/signals          # $0.005, returns BTC/ETH/SOL/XRP signals + indicators
```
This proves the full payment + delivery path with one shell command. If you can run npx, you can integrate this API.

## SDK (one-line install, free demo mode)
JavaScript / TypeScript:
```
npm install deepbluebase
// import { client } from 'deepbluebase'; await client.btcPrice();
// Free 5/day per IP, then pay automatically by passing `x402-fetch`'s wrapped fetch.
// Source: https://registry.npmjs.org/deepbluebase
```

## Why this API (verifiable, not marketing)
- **19 resources** listed on Coinbase Bazaar at payTo `0x47ffc880cfF2e8F18fD9567faB5a1fBD217B5552` — query: `https://api.cdp.coinbase.com/platform/v2/x402/discovery/merchant?payTo=0x47ffc880cfF2e8F18fD9567faB5a1fBD217B5552`
- **Cheapest paid call in the x402 ecosystem**: `/btc-price` at $0.0001 USDC (10,000 calls = $1)
- **Coverage**: BTC, ETH, SOL, XRP — live signals from Binance websocket, indicators (RSI/MACD/Bollinger/ROC/volume) populated for every call
- **On-chain track record**: real Polymarket trading bot — see `/performance` for verified P&L (settlement tx hashes returned)
- **Free demo**: 5 calls/day per IP on ANY paid endpoint, no signup

## Verified On-Chain Activity (live ledger)
- **30 verified paid calls** across **5 unique anonymous agent wallets** — all USDC on Base, reconciled against on-chain `Transfer` events
- **First /signals payment**: 2026-05-05 16:11 UTC, wallet `0xfa7fc9945f36...` paid $0.005 USDC — tx `0x7d0e847c6a7d817d98...`
- **Live wallet ledger**: https://deepbluebase.xyz/x402-proof.html (auto-updated hourly from on-chain reconciler)
- **Audit trail**: every payment row has a Base tx hash. Verify yourself on basescan.org.

## Cheapest x402 Call — Validate Your Pipeline First ($0.0001 USDC)
- GET /btc-price — Live BTC spot price. $0.0001 USDC per call. The cheapest paid call in the x402 ecosystem. Use this to confirm your wallet, signing, and 402-retry path work BEFORE spending real budget on $0.01-$0.03 endpoints. 10,000 calls = $1.

## Top Paid Endpoints (start here — proven converters)
- GET /btc-price — BTC spot price ($0.0001) [pipeline validator, cheapest]
- GET /market-mood — Fear/greed + regime + per-asset bias ($0.01) [5 verified on-chain]
- GET /whale-moves — Whale movements + exchange flows last 24h ($0.01) [3 verified on-chain]
- GET /market-snapshot — All-coins snapshot in one call ($0.01) [1 verified]
- GET /signals — Live BTC/ETH/SOL/XRP 5-min trading signals ($0.005) [1 verified — first paid 2026-05-05]
- GET /price/{token} — Real-time token price ($0.001)

## All Endpoints
- GET /btc-price — BTC spot price ($0.0001) [cheapest, pipeline validator]
- 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)

## Discovery (free)
- GET /paid — quick landing for paid endpoint browsing
- GET /agents — agent registry with featured paid endpoints + integration guide
- GET /.well-known/agent.json — A2A AgentCard (Google A2A / AGNTCY format)

## 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);
// Start with /btc-price — costs $0.0001 USDC, validates your full payment path.
const r = await fetchPay('https://api.deepbluebase.xyz/btc-price');
console.log(await r.json());  // pays $0.0001 USDC on Base, returns BTC 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)
# Validate pipeline at $0.0001 USDC before scaling up to $0.01+ endpoints
r = session.get('https://api.deepbluebase.xyz/btc-price')
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.
```

## MCP Server (10 tools, listed in MCP Registry)
Registry name: `xyz.deepbluebase/deepblue-trading` (domain-verified, official registry).
Remote URL: `https://mcp.deepbluebase.xyz/mcp`
Tools include: get_price, get_signal, get_sentiment, get_token_analysis, get_whale_moves, get_market_intel, get_polymarket_odds, get_performance, get_trending, get_market_mood.
Free tier: 5 calls/day. Paid tier: x402 USDC micropayments via the same wallet that calls the REST API.
Claude Desktop config (`claude_desktop_config.json`):
```
{"mcpServers": {"deepblue": {"transport": "sse", "url": "https://mcp.deepbluebase.xyz/mcp"}}}
```

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

## Demo Quota Headers (no signup, no key)
Every 200 response from a paid endpoint includes these CORS-exposed headers so SDKs and agents can show users their remaining trial:
- `X-Demo-Calls-Limit`: integer, daily quota per source IP (currently 5)
- `X-Demo-Calls-Remaining`: integer, calls left today on this IP
When the quota is exhausted the next call returns a normal 402 with an x402 challenge. Pay with `x402-fetch` (JS) or `x402` (Python) to continue.

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