API التوثيق

Trade Alpha unified signal feed - aggregated LONG/SHORT signals across AOE, Insider, MTE and manual sources with entry/exit prices and live PnL. Mirrors the open /api/trade-feed/signals feed.

• sourcefilter by origin, e.g. AOE / Insider Alpha / MTE / Manual
• symbolticker / symbol filter
• directionLONG / SHORT
• statusOPEN / CLOSED
• asset_typestocks / crypto / etf_index / ...
• timeframee.g. 1d / 4h
• exchangeexchange filter
• sort_bynewest (default) / oldest / strength / pnl
• page / page_sizepagination - page_size 1..200 (default 50)

curl -H "X-API-Key: <your_key>" \
  "https://blockcircle.com/api/v1/trade-feed?direction=LONG&status=OPEN&page_size=50"

{
  "signals": [
    {
      "id": "6a1731885f1df19e60508d46",
      "source": "AOE",
      "source_detail": "AOE Outperformer",
      "symbol": "0Y4G",
      "direction": "LONG",
      "entry_price": 46.6221,
      "current_price": 46.6221,
      "status": "CLOSED",
      "pnl_pct": 0.0,
      "signal_strength": 60,
      "asset_type": "etf_index",
      "timeframe": "1d",
      "notes": "AOE Score: 81/100, Phase: PHASE_B",
      "timestamp": "2026-05-27T18:01:44.318Z"
    }
  ]
}

MTE strategy listings - published backtester strategies with full performance blocks (PnL, Sharpe, win-rate, long/short split) and live webhook config. Mirrors the open /api/mte/strategies feed.

• asset_classstocks / crypto / ...
• tierA / B / C strategy grade
• statusactive / paused / ...
• sourcee.g. backtester
• searchname / symbol substring
• sort_bysort key (e.g. score / pnl / created)
• skip / limitpagination - limit 1..200 (default 50)

curl -H "X-API-Key: <your_key>" \
  "https://blockcircle.com/api/v1/mte?asset_class=stocks&tier=A&limit=50"

{
  "items": [
    {
      "name": "MET MTE 1day",
      "slug": "met-mte-1day",
      "symbol": "MET",
      "timeframe": "1day",
      "asset_class": "stocks",
      "tier": "A",
      "source": "backtester",
      "status": "active",
      "performance": {
        "total_pnl_pct": 152.14,
        "win_rate": 100.0,
        "total_trades": 26,
        "sharpe": 1.32,
        "sortino": 2.46,
        "max_drawdown_pct": -8.46,
        "score": 67.6
      },
      "signals": ["OPEN_LONG", "CLOSE_LONG"],
      "created_at": "2026-07-05T01:32:32.089Z"
    }
  ]
}

Whale Alpha activity stream - large on-chain / prediction-market position changes with size, value and % change, plus a rollup summary. Mirrors the open /api/whales/activity/public feed.

• event_typeentry / exit / size_increase / token_buy / ...
• sourcee.g. polymarket / onchain
• exclude_sourcesource to omit
• hourslookback window 1..168 (default 48)
• limit1..100 (default 50)
• offsetpagination offset

curl -H "X-API-Key: <your_key>" \
  "https://blockcircle.com/api/v1/whales?hours=48&limit=50"

{
  "activity": [
    {
      "_id": "6a4d7f674ab972374a0b7bb4",
      "address": "0x2005d16a84cee...875ea",
      "whale_name": "RN1",
      "source": "polymarket",
      "event_type": "size_increase",
      "title": "Switzerland vs. Colombia: Team to Advance",
      "outcome": "Colombia",
      "size": 90684.7312,
      "prev_size": 62913.2137,
      "change_pct": 44.1,
      "value": 45795.7892,
      "created_at": "2026-07-07T22:36:01.849Z"
    }
  ],
  "total": 12794,
  "summary": {
    "entries": 3030, "exits": 3153,
    "token_buys": 1029, "size_changes": 5582
  }
}

Political Alpha congressional & government trades - disclosed transactions across chambers/branches with politician, party, ticker, sector and dates. Mirrors the open /api/congress/trades feed.

• countryjurisdiction filter (e.g. US / UK)
• branchexec / judicial / fed / legislative / ...
• tickere.g. NVDA
• politician_namename substring
• partyD / R / I
• chamberHouse / Senate
• state2-letter state code
• transaction_typePurchase / Sale
• sort_by / sort_ordersort key (default filing_date) / asc / desc
• page / page_sizepagination - page_size 1..5000 (default 50)

curl -H "X-API-Key: <your_key>" \
  "https://blockcircle.com/api/v1/congress?ticker=NVDA&transaction_type=Purchase&page_size=50"

{
  "trades": [
    {
      "id": "6a4d0d6ef164100b1f0d1937",
      "politician_name": "Lloyd Doggett",
      "party": "D",
      "chamber": "House",
      "state": "TX",
      "asset_name": "The Home Depot Inc",
      "ticker": "HD",
      "asset_type": "Stock",
      "sector": "consumer-discretionary",
      "transaction_type": "Purchase",
      "owner": "not-disclosed",
      "transaction_date": "2026-06-18T00:00:00",
      "filing_date": "2026-07-07T13:02:13",
      "is_tradable": true
    }
  ]
}

Insider Alpha Form 4 filings - SEC insider transactions with insider role, issuer, direction and conviction/signal grading. Mirrors the open /api/insider-alpha/filings feed. (The richer, fully-filtered surface lives at /api/v1/insider-alpha/filings below.)

• transaction_typebuy / sell / all (default all)
• tickere.g. KEY
• insider_namecase-insensitive substring
• sector / industryoptional filters
• days_back0..3650 (0 = no floor)
• sort_by / sort_orderfiling_date (default) / trade_date / value / shares, asc/desc
• page / page_sizepagination - page_size 1..1000 (default 50)
• limitoptional row cap 1..1000

curl -H "X-API-Key: <your_key>" \
  "https://blockcircle.com/api/v1/insider?transaction_type=buy&days_back=90&page_size=50"

{
  "filings": [
    {
      "id": "6a4d7a6abc29e7cd43754350",
      "ticker": "KEY",
      "company_name": "KEYCORP /NEW/",
      "insider_name": "BANK OF NOVA SCOTIA",
      "insider_title": "",
      "is_director": true,
      "is_ten_percent": true,
      "transaction_code": "D",
      "transaction_type": "Disposition to issuer",
      "transaction_direction": "other",
      "filing_date": "2026-07-07T00:00:00+00:00",
      "trade_date": "2026-07-07T00:00:00+00:00"
    }
  ],
  "total": 2,
  "tier": "free"
}

Asset Outperformer (AOE) rankings - the scanned universe scored on multi-timeframe outperformance vs BTC/ETH/SOL benchmarks, with composite score and market phase. Mirrors the open /api/outperformers/scan feed.

• searchname / symbol substring
• asset_typecrypto / stocks / ...
• benchmarkcrypto (default) benchmark set
• timeframeall (default) / 24h / 7d / 30d / ...
• sort_bycomposite_score (default) / perf_* / ...
• sort_order-1 desc (default) / 1 asc
• skip / limitpagination - limit 1..500 (default 100)

curl -H "X-API-Key: <your_key>" \
  "https://blockcircle.com/api/v1/aoe?asset_type=crypto&sort_by=composite_score&limit=100"

{
  "items": [
    {
      "id": "69e9a1d118203b40f763226d",
      "symbol": "RETIRE",
      "name": "The Last Play",
      "asset_type": "crypto",
      "current_price": 0.00329373,
      "market_cap_rank": 1863,
      "perf_24h": 28.69,
      "perf_7d": 37.14,
      "perf_30d": 38.75,
      "outperf_vs_btc_24h": 28.91,
      "beats_btc_24h": true,
      "composite_score": 10.0,
      "market_phase": "PHASE_C",
      "avg_outperformance": 70.55
    }
  ]
}

Market Reversal Engine (MRE) signals - oversold/overbought reversal detections with direction, type, expected move and confidence score. Mirrors the open /api/mre/signals feed.

• tickersymbol filter (e.g. KRAKEN:ETHUSD)
• skip / limitpagination - limit 1..500 (default 100)

curl -H "X-API-Key: <your_key>" \
  "https://blockcircle.com/api/v1/mre?limit=100"

{
  "items": [
    {
      "_id": "6a4c8c5898a4fde9e43d1fe6",
      "ticker": "KRAKEN:ETHUSD",
      "ticker_display": "ETHUSD",
      "price": "1759.34",
      "interval": "15m",
      "asset_class": "crypto",
      "signal": {
        "what": "oversold",
        "direction": "LONG",
        "type": "SCALP",
        "condition": "Confirmed 5-minute break-out and AMS M6 shows weakness"
      },
      "expected_pct": 2.0,
      "score": 85
    }
  ],
  "total": 2073
}

Prediction-market warehouse - normalized markets across Polymarket, Kalshi, PredictIt, Manifold, Metaculus and Opinion, with prices, volume and liquidity. Mirrors the open /api/markets/warehouse feed.

• searchquestion / title substring
• platformscomma list - polymarket / kalshi / predictit / manifold / metaculus / opinion
• categorycategory filter (uses category_norm)
• sort / ordervolume_24h (default) / volume / liquidity / ..., asc/desc
• min_volume / min_volume_24h / min_liquiditynumeric floors
• max_days_to_expireonly markets expiring within N days
• created_daysonly markets first seen within N days
• cross_match_onlytrue = only cross-platform matched markets
• skip / limitpagination - limit 1..1000 (default 50)

curl -H "X-API-Key: <your_key>" \
  "https://blockcircle.com/api/v1/prediction?platforms=polymarket,kalshi&sort=volume_24h&limit=50"

{
  "items": [
    {
      "market_id": "0x7412d284...272abe",
      "platform": "polymarket",
      "event_title": "World Cup Winner",
      "question": "Will Egypt win the 2026 FIFA World Cup?",
      "yes_price": 0.0,
      "outcome_prices": [0.0, 1.0],
      "volume": 158580818.67,
      "volume_24h": 25057938.54,
      "category_norm": "sports",
      "active": true,
      "end_date": "2026-07-20T00:00:00Z"
    }
  ],
  "total": 57677,
  "platforms": {
    "polymarket": 23093, "kalshi": 27017, "predictit": 504,
    "manifold": 6535, "metaculus": 493, "opinion": 35
  },
  "has_more": true
}

Most recent data point for a scorecard (ams | mrs | gls) at a timeframe. Any tier: no history-window check.

• scorecardpath: ams (Altcoin), mrs (Macro Risk), gls (Global Liquidity)
• timeframe1H (default) · 4H · 8H · 12H · 1D · 1W · 1M

curl -H "X-API-Key: <your_key>" \
  "https://blockcircle.com/api/scorecards/ams/latest?timeframe=1D"

{
  "item": {
    "id": "6a4d...c1e",
    "scorecard": "ams",
    "timeframe": "1D",
    "timestamp": "2026-07-07T00:00:00Z",
    "data": { "ams": 62.4, "btc_dominance": 51.2, "... ": "..." }
  },
  "scorecard": "ams",
  "timeframe": "1D"
}

Paginated time-series history, newest first. History depth is capped to your tier's window; undated calls are floored to that window server-side.

• scorecardpath: ams | mrs | gls
• timeframeoptional: 1H · 4H · 8H · 12H · 1D · 1W · 1M
• from / toISO dates. Requesting older than your tier window returns 403.
• fieldscomma-separated field names to project (e.g. ams,btc_dominance)
• skip / limitpagination: limit 1..5000 (default 500)

curl -H "X-API-Key: <your_key>" \
  "https://blockcircle.com/api/scorecards/mrs/data?timeframe=1D&from=2026-06-01&limit=500"

{
  "items": [
    {
      "id": "6a4d...c1e",
      "scorecard": "mrs",
      "timeframe": "1D",
      "timestamp": "2026-07-07T00:00:00Z",
      "data": { "mrs": 38.1, "...": "..." }
    }
  ],
  "total": 1240,
  "scorecard": "mrs"
}

Streamed CSV export of a scorecard series, tier history-window enforced. Only format=csv is supported today.

• scorecardpath: ams | mrs | gls
• formatcsv (default / only value)
• timeframeoptional filter

curl -H "X-API-Key: <your_key>" \
  "https://blockcircle.com/api/scorecards/gls/export?timeframe=1W" -o gls.csv

# text/csv stream
timestamp,timeframe,gls,...
2026-07-07T00:00:00Z,1W,104.2,...
2026-06-30T00:00:00Z,1W,103.8,...

Paginated Form 4 insider filings with a full filter set. Free keys see data delayed 24h; higher tiers see it real-time.

• transaction_typebuy · sell · all (default all)
• tickere.g. NVDA
• insider_namecase-insensitive substring
• min_value / max_valueUSD magnitude filter
• days_back0..3650 (default 7)
• sort_byfiling_date · trade_date · value · shares
• page / page_sizepage_size 1..500 (default 50)

curl -H "X-API-Key: <your_key>" \
  "https://blockcircle.com/api/v1/insider-alpha/filings?ticker=NVDA&transaction_type=buy&days_back=90"

{
  "filings": [
    {
      "id": "671b...901",
      "ticker": "NVDA",
      "insider_name": "Jensen Huang",
      "insider_title": "CEO",
      "transaction_direction": "buy",
      "transaction_code": "P",
      "shares": 25000,
      "value": 3200000,
      "filing_date": "2026-04-15T14:30:00Z"
    }
  ],
  "total": 1,
  "page": 0,
  "page_size": 50,
  "has_more": false,
  "tier": "free",
  "data_lag_hours": 24
}

Searchable directory of insiders with lifetime buy/sell aggregates.

• qfuzzy name search
• min_filingsminimum lifetime filing count (default 1)
• sort_bytotal_buy_value · total_sell_value · filing_count · last_filing
• page / page_sizepage_size 1..500

curl -H "X-API-Key: <your_key>" \
  "https://blockcircle.com/api/v1/insider-alpha/insiders?q=huang&sort_by=total_buy_value"

{
  "insiders": [
    {
      "slug": "jensen-huang",
      "name": "Jensen Huang",
      "filing_count": 42,
      "total_buy_value": 3200000,
      "total_sell_value": 128000000
    }
  ],
  "total": 1,
  "page": 0,
  "page_size": 50
}

Company profile with rolling insider-flow windows and recent filings.

• tickerpath: e.g. AAPL
• include_filingstrue (default) to embed recent filings
• filings_limit1..2000 (default 500)

curl -H "X-API-Key: <your_key>" \
  "https://blockcircle.com/api/v1/insider-alpha/companies/AAPL"

{
  "ticker": "AAPL",
  "windows": {
    "30d": { "buy_value": 0, "sell_value": 4200000, "net": -4200000 },
    "90d": { "buy_value": 120000, "sell_value": 9800000, "net": -9680000 }
  },
  "filings": [ { "insider_name": "...", "transaction_direction": "sell" } ]
}

Cluster-buy detections: multiple insiders at one company buying inside a window.

• days_back1..365 (default 30)
• min_insiders2..50 distinct buyers (default 3)
• ticker / sectoroptional filters
• page / page_sizepage_size 1..500

curl -H "X-API-Key: <your_key>" \
  "https://blockcircle.com/api/v1/insider-alpha/clusters?days_back=30&min_insiders=3"

{
  "clusters": [
    {
      "ticker": "SMCI",
      "insider_count": 4,
      "total_value": 5100000,
      "detected_at": "2026-07-02T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 0,
  "page_size": 50,
  "has_more": false
}

Market-wide insider-flow rollups (24h / 7d / 30d) plus most-bought tickers.

• -no query params

curl -H "X-API-Key: <your_key>" \
  "https://blockcircle.com/api/v1/insider-alpha/stats/market"

{
  "last_24h": { "buy_value": 0, "sell_value": 0, "filings": 0 },
  "last_7d":  { "buy_value": 12400000, "sell_value": 88000000, "filings": 512 },
  "last_30d": { "...": "..." },
  "most_bought_7d": [ { "ticker": "NVDA", "value": 3200000, "count": 3 } ],
  "tier": "free"
}

Live quota check for the calling key. Current RPM / daily counts and remaining allowance.

• -no query params

curl -H "X-API-Key: <your_key>" \
  "https://blockcircle.com/api/v1/insider-alpha/usage"

{
  "tier": "free",
  "usage": {
    "rpm_used": 2, "rpm_remaining": 8,
    "daily_used": 17, "daily_remaining": 83
  },
  "reset_in_seconds": { "rpm": 60, "daily": 86400 }
}