# Echo Sentiment API

Real-time XLM (Stellar) market intelligence, pay-per-call via x402 (HTTP 402, USDC on Base mainnet). No API keys, no subscriptions — the payment is the authentication.

## Endpoints

- /v1/sample — FREE (10/hour/IP) — reduced sentiment snapshot: score, source, live price. Taste before you pay.
- /v1/sentiment — $0.005 — composite XLM market sentiment in [-1, 1] (Crypto Fear & Greed + SDEX order-flow imbalance + 24h momentum), live price, spread.
- /v1/quote — $0.005 — XLM price, best bid/ask, spread, book depth.
- /v1/arb-opportunities — $0.005 — live CEX<->SDEX arbitrage scan (Kraken, Upbit, SDEX), net % after fees.
- /v1/multi-asset — $0.005 — strategy backtest screen (SMA crossover, RSI mean-reversion, Buy&Hold) across 8 major assets; params: tickers (comma-separated), period (e.g. 3mo, 1y).
- /v1/sentiment-report — $0.05 — premium full report: verdict (bullish/bearish/neutral), confidence, raw FNG index + label, order-flow imbalance, book depth, 24h momentum %, arb context.
- /v1/bundle — $0.05 — prepaid bundle: 10 credits (10 basic calls or 1 premium report). Send header X-Bundle-Token: <token> on any paid endpoint to spend credits instead of paying per call.
- /v1/sentiment-history — $0.10 — hourly sentiment series (default 24h, ?hours= up to 168) — FNG + momentum reconstructed, live order-flow in 'current', trend direction.
- /v1/fng — $0.01 — cheap decision tick: Fear & Greed index (0-100), label, mapped sentiment.
- /v1/xlm-network — $0.01 — Stellar on-chain pulse: latest ledger (sequence, tx/op counts), XLM supply, base fee/reserve, and XLM/USDC SDEX trade stats for the latest hourly bucket (count, volumes, VWAP, OHLC).
- /v1/attested-quote — $0.005 — oracle-grade quote: price for a ticker (default xlm; btc/eth/sol/xrp/ada/link/… supported) + Ed25519 signature so agents can independently verify the data. See Attestations below.
- /v1/breadth — $0.01 — market regime: top-50 breadth % (share of top-50 up in 24h), average 24h change, BTC/ETH dominance, rules-based risk-on/off/mixed verdict, XLM rank by market cap + relative strength vs BTC and ETH (pp). Interpreted signal, not raw tables.
- /v1/btc-quote — $0.005 — BTC/USD spot price + 24h change (CoinGecko, keyless). Single-asset quote family alongside /v1/quote (XLM).
- /v1/global-market — $0.01 — crypto macro intel: total market cap, 24h volume, BTC/ETH dominance, market-cap change %. Poll for regime context before acting on single-asset endpoints.
- /v1/screen — $0.01 — parameterized strategy screen across a caller-chosen ticker set (params: tickers comma-separated, period e.g. 3mo/1y); SMA crossover, RSI mean-reversion, Bollinger, vs Buy&Hold backtests.

## Discovery

- /robots.txt — AI content-signals policy (search/ai-input granted, ai-train denied)
- /openapi.json — OpenAPI spec with per-path x-payment-info (price + offers embedded, machine-readable)
- /.well-known/x402 — machine-readable manifest (name, payTo, price, endpoints)
- /.well-known/mcp/server-card.json — MCP server card (transport endpoint)
- /.well-known/agent.json — A2A agent card
- /.well-known/agent-skills/index.json — agent skills discovery index
- /.well-known/api-catalog — RFC 9727 API catalog (linkset)

## Payment flow (x402 v2)

1. GET any paid endpoint -> HTTP 402 + PAYMENT-REQUIRED header (base64 JSON with accepts[]).
2. Sign an EIP-3009 permit for the accepted amount (5000 or 50000 microUSDC) to 0x583FfEE3f6E0E8cAB3531fBd5C4e291784D3b6cD.
3. Retry with PAYMENT-SIGNATURE header -> HTTP 200 + data.

Network: eip155:8453 (Base) + solana mainnet. Asset: USDC. Facilitator: self-hosted (no third party).

## Receipts (provenance)

Every paid 200 response carries receipt headers (payment-response settlement proof, x-receipt-hash, x-receipt-payer).

## Integrate (call us from YOUR agent — 3 lines)

```python
from x402 import x402ClientSync
from x402.http.x402_http_client import x402HTTPClientSync
from x402.mechanisms.evm.exact import ExactEvmScheme
from x402.mechanisms.evm.signers import EthAccountSigner
client = x402HTTPClientSync(x402ClientSync().register("eip155:8453", ExactEvmScheme(signer=EthAccountSigner(agent_wallet))))
r = client.get("https://api.6766587364.lol/v1/sentiment")  # auto-pays 0.005 USDC, returns 200 + data
```

No API key, no signup. Your agent pays per call in USDC; revenue settles on Base mainnet.