utxoIQ API Reference

GET /api/v1/insights/latest HTTP/1.1
Host: api.utxoiq.com
X-API-Key: uiq_live_xxxxxxxxxxxxxxxxxxxx

# 1. Login — obtain tokens
curl -X POST https://api.utxoiq.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "yourpassword"}'

# Response:
# { "access_token": "eyJ...", "refresh_token": "rt_...", "token_type": "bearer", "expires_in": 900 }

# 2. Use the access token
curl https://api.utxoiq.com/api/v1/insights/latest \
  -H "Authorization: Bearer eyJ..."

# 3. Refresh before expiry
curl -X POST https://api.utxoiq.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "rt_..."}'

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please slow down.",
    "details": { "retry_after": 42 }
  },
  "request_id": "req_01HXYZ..."
}

curl "https://api.utxoiq.com/api/v1/insights/latest?limit=5&min_confidence=0.7" \
  -H "X-API-Key: uiq_live_xxxxxxxxxxxxxxxxxxxx"

# Response
{
  "insights": [
    {
      "id": "01HXYZ...",
      "signal_type": "whale",
      "headline": "Large accumulation detected — 2,400 BTC moved to cold storage",
      "summary": "A cluster of wallets linked to long-term holders...",
      "confidence": 0.91,
      "timestamp": "2026-04-04T09:12:00Z",
      "block_height": 894210,
      "tags": ["accumulation", "cold-storage"],
      "is_predictive": false,
      "chart_url": null
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 5
}

// Connect with JWT token as query param
const ws = new WebSocket(
  'wss://api.utxoiq.com/ws/insights?token=eyJ...'
);

ws.onopen = () => console.log('Connected to insight feed');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  // msg.type: "insight" | "heartbeat" | "connected"
  if (msg.type === 'insight') {
    const { id, signal_type, headline, confidence } = msg.data;
    console.log(`[${signal_type}] ${headline} — ${confidence}`);
  }
};

// Heartbeat — reply to keep connection alive
ws.addEventListener('message', (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === 'heartbeat') ws.send(JSON.stringify({ type: 'pong' }));
});

// No auth required — public system status
const ws = new WebSocket('wss://api.utxoiq.com/ws/monitoring');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  // { block_height, mempool_size, ingestion_lag_ms, active_connections }
};

pip install utxoiq

from utxoiq import UtxoIQClient

client = UtxoIQClient(api_key="uiq_live_xxxxxxxxxxxxxxxxxxxx")

# Fetch latest insights
insights = client.insights.get_latest(limit=10, min_confidence=0.7)
for insight in insights:
    print(f"[{insight.signal_type}] {insight.headline} — {insight.confidence:.0%}")

client = UtxoIQClient()
client.login(email="you@example.com", password="yourpassword")
# Tokens stored in memory; auto-refreshed before expiry

profile = client.get("/api/v1/auth/profile").json()
print(profile["email"])

# Get smart money exchange flows (Pro+)
flows = client.get(
    "/api/v1/smart-money/flows",
    params={"days": 30}
).json()

# Whale movements
whales = client.get(
    "/api/v1/smart-money/whales",
    params={"min_amount_btc": 100}
).json()

# Create a whale alert
alert = client.alerts.create({
    "name": "Big whale move",
    "signal_type": "whale",
    "min_confidence": 0.85,
    "conditions": {"min_amount_btc": 500}
})
print(f"Alert created: {alert['id']}")

# List alerts
alerts = client.alerts.list()
for a in alerts:
    print(f"  - {a['name']} ({a['status']})")

# Delete
client.alerts.delete(alert["id"])

brief = client.daily_brief.get_today()
print(brief["summary"])
for category, items in brief["by_category"].items():
    print(f"\n{category.upper()}")
    for item in items:
        print(f"  • {item['headline']}")

from utxoiq import UtxoIQClient
from utxoiq.exceptions import (
    AuthenticationError,
    RateLimitError,
    SubscriptionRequiredError,
    NotFoundError,
)
import time

client = UtxoIQClient(api_key="uiq_live_xxxxxxxxxxxxxxxxxxxx")

try:
    insights = client.insights.get_latest(limit=50)
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited — retry in {e.retry_after}s")
    time.sleep(e.retry_after or 60)
except SubscriptionRequiredError:
    print("This feature requires a Pro or Power plan")
except NotFoundError:
    print("Resource not found")

npm install @utxoiq/sdk

import { UtxoIQClient } from '@utxoiq/sdk';

const client = new UtxoIQClient({ apiKey: 'uiq_live_xxxxxxxxxxxxxxxxxxxx' });

const insights = await client.insights.getLatest({ limit: 10, minConfidence: 0.7 });
insights.forEach(({ signalType, headline, confidence }) =>
  console.log(`[${signalType}] ${headline} — ${(confidence * 100).toFixed(0)}%`)
);

const client = new UtxoIQClient();
await client.login('you@example.com', 'yourpassword');
// Tokens stored in memory; Axios interceptor auto-refreshes on 401

const profile = await client.get('/api/v1/auth/profile');
console.log(profile.data.email);

// Create
const alert = await client.alerts.create({
  name: 'Mempool spike',
  signal_type: 'mempool',
  min_confidence: 0.8,
  conditions: { fee_rate_threshold: 50 },
});

// List
const { alerts } = await client.alerts.list();

// Update
await client.alerts.update(alert.id, { min_confidence: 0.9 });

// Delete
await client.alerts.delete(alert.id);

import { RealtimeWebSocket } from '@utxoiq/sdk';

const ws = new RealtimeWebSocket({
  baseUrl: 'wss://api.utxoiq.com',
  token: accessToken,        // JWT access token
  onInsight: (insight) => {
    console.log('[New insight]', insight.headline);
  },
  onError: (err) => console.error('WS error:', err),
  autoReconnect: true,       // reconnect on disconnect
});

ws.connect();

// Later:
ws.disconnect();

import { StreamingChat } from '@utxoiq/sdk';

const stream = new StreamingChat({
  baseUrl: 'https://api.utxoiq.com',
  apiKey: 'uiq_live_xxxxxxxxxxxxxxxxxxxx',
});

await stream.query({
  message: 'What does the current mempool data suggest about fee pressure?',
  role: 'analyst',
  onToken: (token) => process.stdout.write(token),
  onDone: () => console.log('\nStream complete'),
});

import {
  UtxoIQError,
  AuthenticationError,
  RateLimitError,
  SubscriptionRequiredError,
} from '@utxoiq/sdk';

try {
  const insights = await client.insights.getLatest({ limit: 50 });
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Invalid credentials');
  } else if (err instanceof RateLimitError) {
    const delay = (err.retryAfter ?? 60) * 1000;
    console.error(`Rate limited — retrying in ${delay}ms`);
    await new Promise(r => setTimeout(r, delay));
  } else if (err instanceof SubscriptionRequiredError) {
    console.error('Upgrade required for this feature');
  } else if (err instanceof UtxoIQError) {
    console.error(`API error [${err.statusCode}]: ${err.message}`);
  }
}

# Streaming chat request (SSE)
curl -X POST https://api.utxoiq.com/api/v1/chat/query \
  -H "X-API-Key: uiq_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "Is now a good time to transact on-chain?",
    "role": "analyst",
    "provider": "anthropic",
    "model": "claude-sonnet-4-6"
  }'

# List providers and models
curl https://api.utxoiq.com/api/v1/chat/providers \
  -H "X-API-Key: uiq_live_xxxxxxxxxxxxxxxxxxxx"

# List roles
curl https://api.utxoiq.com/api/v1/chat/roles \
  -H "X-API-Key: uiq_live_xxxxxxxxxxxxxxxxxxxx"