API Documentation

Everything you need to wire your agent into SorenLux intelligence.

Contents

Base URL & Authentication

https://sorenlux.ai/api

No API keys. No OAuth. Paid endpoints use x402 — your agent pays USDC on Base per request. Free endpoints require nothing.

x402 Payment Flow

Paid endpoints return 402 Payment Required with a payment preview. Your agent pays, then replays the request with proof.

  1. Request — GET /api/intel/BTC
  2. Receive 402 — Response includes price, wallet, network, and a data preview
  3. Pay — Send USDC on Base to the specified wallet
  4. Replay — Resend the request with x-payment-verified: true header
  5. Receive data — Full analyst intelligence payload
Network: Base (Chain ID 8453)
Token: USDC
Wallet: 0x57536458E8E3636038e36D373fD001A0017B97c6

GET /api/health

GET /api/health Free 
{
  "status": "ok",
  "service": "SorenLux AI — Crypto Analyst Intelligence",
  "version": "0.1.0",
  "endpoints": {
    "free": ["/api/health", "/api/overview"],
    "paid": ["/api/intel/[ticker]", "/api/divergence"]
  },
  "pricing": {
    "intel": "$0.05 USDC per call",
    "divergence": "$0.03 USDC per call"
  },
  "payment": "x402 (USDC on Base)",
  "wallet": "0x57536458E8E3636038e36D373fD001A0017B97c6"
}

GET /api/overview

GET /api/overview Free 
{
  "tickers": [
    {
      "ticker": "BTC",
      "total_mentions": 292,
      "sentiment": {
        "bullish_pct": 42.5,
        "dominant": "bullish"
      },
      "conviction": {
        "high_conviction_pct": 55.1
      }
    },
    ...
  ],
  "crypto_tickers": [...],
  "total_crypto_tickers": 10
}

Returns all 534 tracked tickers with sentiment summaries. Use this to discover what's available before making paid calls.

GET /api/intel/:ticker

GET /api/intel/:ticker $0.05 USDC 
// 402 response (before payment):
{
  "error": "Payment required",
  "ticker": "BTC",
  "price": "0.05 USDC",
  "network": "Base (8453)",
  "wallet": "0x5753...97c6",
  "protocol": "x402",
  "preview": {
    "ticker": "BTC",
    "name": "Bitcoin",
    "total_mentions": 292,
    "dominant_sentiment": "bullish",
    "bullish_pct": 42.5
  }
}

// Full response (after payment):
{
  "ticker": "BTC",
  "name": "Bitcoin",
  "total_mentions": 292,
  "sentiment": {
    "bullish": 124, "bearish": 85, "neutral": 83,
    "bullish_pct": 42.5, "dominant": "bullish"
  },
  "conviction": {
    "high": 161, "medium": 97, "low": 34,
    "high_conviction_pct": 55.1
  },
  "channels": [
    { "channel": "into_the_cryptoverse", "mentions": 126 },
    { "channel": "bloomberg_television", "mentions": 31 },
    ...
  ],
  "theses": [
    {
      "thesis": "Bitcoin likely to reach new ATH...",
      "sentiment": "bullish",
      "conviction": "high",
      "channel": "into_the_cryptoverse"
    },
    ...
  ]
}

Deep intelligence on a single ticker. Includes full sentiment breakdown, conviction distribution, per-channel analysis, and individual analyst theses.

GET /api/divergence

GET /api/divergence $0.03 USDC 
// Tickers where analysts disagree — trade signals
{
  "divergences": [
    {
      "ticker": "TSLA",
      "bullish_pct": 52.3,
      "bearish_pct": 47.7,
      "spread": 4.6,
      "total_mentions": 89
    },
    ...
  ]
}

Tickers with high analyst disagreement. When smart analysts disagree, that's where the opportunity lives.

Error Handling

HTTP Status Codes

200  OK — Data returned successfully
402  Payment Required — Send USDC, replay with header
400  Bad Request — Missing or invalid parameters
404  Not Found — Ticker not in dataset
500  Server Error — Retry with backoff

Agent Integration Example

// Pseudocode for agent integration
const res = await fetch('https://sorenlux.ai/api/intel/BTC');

if (res.status === 402) {
  const payment = await res.json();
  // Send payment.price USDC to payment.wallet on Base
  await sendUSDC(payment.wallet, payment.price);
  
  // Replay with payment proof
  const data = await fetch('https://sorenlux.ai/api/intel/BTC', {
    headers: { 'x-payment-verified': 'true' }
  });
  return data.json();
}