REST API

Integrate ObsiFlow signals into your trading bot or dashboard. All endpoints are available at /api/v1.

Configuration

Python Service Base URL

Node Service Base URL

User ID (for testing)

Health & Status

GET/healthCheck Python service health

GET/healthCheck Node.js service health

GET/api/v1/ollama-kg/healthCheck Ollama Knowledge Graph service health

User Wallets

Manage user wallets and track holdings.

POST/api/v1/users/demo_user/walletsAdd a wallet for tracking

View Request Body

{
  "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "metadata": {
    "label": "Main Trading Wallet",
    "type": "user",
    "chain": "ethereum"
  }
}

GET/api/v1/users/demo_user/walletsGet all wallets for a user

GET/api/v1/users/demo_user/holdingsGet holdings for a user

News API

GET/api/v1/news/listList all news articles

POST/api/v1/news/fetchManually trigger news fetching (no body required)

Whale Wallets

GET/api/v1/whale/listList all whale wallets

GET/api/v1/whale/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb/transactionsGet transaction history for a whale wallet

POST/api/v1/whale/detectDetect whale transaction and generate signal

View Request Body

{
  "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "from_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "to_address": "0x8ba1f109551bD432803012645Hac136c22C9c8C7",
  "amount": "1000000000000000000",
  "token": "ETH",
  "transaction_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "value_usd": 2500000,
  "chain": "ethereum",
  "user_id": "demo_user",
  "triggering_news": {
    "title": "Whale moves 1000 ETH to exchange",
    "url": "https://example.com/news",
    "text": "Large whale wallet moved significant amount to exchange"
  },
  "event_data": {
    "type": "whale_transaction",
    "description": "Large transfer detected"
  }
}

Signal API

Generate and retrieve trading signals with FDC verification support. Signals include attestation types (WalletBalance, BalanceDecreasingTransaction) and verification requirements.

GET/api/v1/signal/latestGet latest signals

GET/api/v1/signal/pendingGet pending verification signals

GET/api/v1/signal/demo_user_signal_123Get specific signal by ID with full verification details

POST/api/v1/signal/generateGenerate immediate signal (Phase 1) with FDC verification. Response includes attestation_type and verification_required fields.

View Request Body

{
  "user_id": "demo_user",
  "event_id": "event_whale_tx_1769527684180",
  "event_data": {
    "type": "whale_transaction",
    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "from_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "to_address": "0x8ba1f109551bD432803012645Hac136c22C9c8C7",
    "amount": "1000000000000000000",
    "token": "ETH",
    "transaction_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "value_usd": 2500000,
    "chain": "ethereum",
    "description": "Large whale transaction detected"
  },
  "triggering_wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "triggering_news": {
    "title": "Whale moves 1000 ETH",
    "url": "https://example.com/news",
    "text": "Large whale wallet moved significant amount",
    "source": "crypto_news"
  }
}

GET/api/v1/users/demo_user/signalsGet all signals for a user

AI & Recommendations

Generate AI-powered trading recommendations with knowledge graph visualization.

POST/api/v1/ai/analyzeAnalyze and generate AI recommendation with knowledge graph

View Request Body

{
  "user_id": "demo_user",
  "context_data": {
    "market_conditions": "bullish",
    "risk_tolerance": "medium",
    "time_horizon": "short",
    "preferences": {
      "tokens": [
        "BTC",
        "ETH",
        "FLR"
      ]
    }
  }
}

POST/api/v1/ai/mock-triggerMock AI trigger - automatically finds concerning news and generates signal

POST/api/v1/ai/generate-strategyGenerate AI strategy for a user

View Request Body

{
  "user_id": "demo_user",
  "context_data": {
    "time_horizon": "short",
    "risk_level": "medium",
    "market_conditions": "volatile",
    "holdings": [
      {
        "token": "BTC",
        "amount": 0.5,
        "value_usd": 25000
      }
    ]
  }
}

GET/api/v1/ai/fdc-status/demo_userGet FDC verification status for a user

Knowledge Graph API

Generate knowledge graphs from news, transactions, and entities using Ollama.

POST/api/v1/ollama-kg/generateGenerate knowledge graph from news and transactions

View Request Body

{
  "user_id": "demo_user",
  "title": "Crypto Market Analysis - 2026-01-27",
  "description": "Knowledge graph generated from news and transactions",
  "news": [
    {
      "text": "Bitcoin price surged to $65,000 today as institutional investors continue to adopt cryptocurrency. Ethereum also saw gains, reaching $3,500. Major exchanges like Coinbase and Binance reported record trading volumes.",
      "source": "crypto_news_1"
    },
    {
      "text": "Uniswap V3 launched on Polygon network, enabling cheaper transactions for DeFi users. The protocol now supports multiple chains including Ethereum, Polygon, and Optimism.",
      "source": "defi_news_1"
    }
  ],
  "transactions": [
    {
      "from_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "to_address": "0x8ba1f109551bD432803012645Hac136c22C9c8C7",
      "token": "ETH",
      "amount": 10000,
      "tx_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "timestamp": "2026-01-27T15:28:04.180Z"
    }
  ],
  "entities": [
    {
      "name": "Bitcoin",
      "entity_type": "token",
      "metadata": {
        "symbol": "BTC",
        "blockchain": "Bitcoin"
      }
    },
    {
      "name": "Ethereum",
      "entity_type": "token",
      "metadata": {
        "symbol": "ETH",
        "blockchain": "Ethereum"
      }
    }
  ],
  "regenerate_news": true,
  "return_html": true,
  "return_data": true,
  "save_to_db": true
}

GET/api/v1/ollama-kg/user/demo_userGet user's knowledge graphs

GET/api/v1/ollama-kg/listList all knowledge graphs

Trading Bots

POST/api/v1/bots/registerRegister a new trading bot

View Request Body

{
  "user_id": "demo_user",
  "name": "My Trading Bot v1.0",
  "metadata": {
    "version": "1.0",
    "strategy": "momentum",
    "risk_level": "medium",
    "description": "Automated trading bot for crypto signals"
  }
}

Entities

GET/api/v1/entitiesGet all entities

Node.js Service - Wallet Mapping

POST/api/v1/wallets/mapMap wallet and discover sub-wallets

View Request Body

{
  "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "wallet_type": "user"
}

Node.js Service - Market Data

GET/api/v1/market/pricesGet prices for multiple symbols

GET/api/v1/market/price/BTCGet price for a specific symbol

Node.js Service - FDC

POST/api/v1/fdc/requestRequest FDC attestation

View Request Body

{
  "data_type": "market_data",
  "data": {
    "price": 50000,
    "symbol": "BTC",
    "timestamp": "2026-01-27T15:28:04.180Z"
  }
}

Pricing Tiers

Manage user pricing tiers and subscriptions. Tiers determine access levels and feature availability.

GET/api/v1/pricing/tier/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbGet user's current pricing tier by wallet address

GET/api/v1/pricing/tiersList all available pricing tiers

POST/api/v1/pricing/tier/upgradeUpgrade user to premium tier after payment

View Request Body

{
  "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "payment_tx_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}

PUT/api/v1/pricing/tier/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbUpdate user's pricing tier (admin)

View Request Body

{
  "tier_id": "premium",
  "payment_tx_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}