nexus-alpha 1.0.1

Python SDK for NEXUS Alpha — institutional alternative data signals from SEC EDGAR filings

NEXUS Alpha Python SDK

Institutional alternative data signals from SEC EDGAR filings.

Installation

pip install nexus-alpha          # Core (REST API only)
pip install nexus-alpha[pandas]  # + DataFrame support
pip install nexus-alpha[stream]  # + WebSocket streaming
pip install nexus-alpha[all]     # Everything

Quick Start

from nexus_alpha import NexusAlpha

client = NexusAlpha("your-api-key")
# Or: NEXUS_ALPHA_API_KEY=your-key in env, then NexusAlpha()

# Top signals right now
for s in client.signals.top(limit=10):
    print(f"{s.ticker:6s} | {s.signal:12s} | conf={s.confidence:.3f} | {s.freshness_status}")
    print(f"  {s.rationale[:100] if s.rationale else ''}")

Output:

NVDA   | OVERWEIGHT   | conf=0.712 | LIVE
  GPU demand accelerating; data center revenue beat by 18%
MSFT   | BUY          | conf=0.683 | LIVE
  Azure growth +29% YoY; AI copilot ARR surpassed $5B

Signal Retrieval

# Search with filters
signals = client.signals.search(
    ticker="NVDA",
    signal="BUY",
    min_confidence=0.65,
)

# Full history → pandas DataFrame (Tier 1+)
df = client.signals.history(
    date_from="2024-01-01",
    date_to="2024-12-31",
    min_confidence=0.65,
    limit=500,
).to_dataframe()

print(df[["ticker", "signal_date", "signal", "confidence"]].head())

Bulk CSV Export (Tier 2+)

# Downloads up to 10,000 signals as a DataFrame
df = client.data.export(date_from="2022-01-01")
df.to_csv("nexus_signals.csv", index=False)
print(f"Downloaded {len(df)} signals")

Analytics & Backtest

perf = client.analytics.performance()

# Best hold period (highest Sharpe)
best = perf.best_hold_period
print(f"Best: {best.hold_days}d hold | Sharpe {best.sharpe_annualized} | WR {best.win_rate:.1%}")
# Best: 60d hold | Sharpe 1.2 | WR 70.6%

# Equity curve → DataFrame
eq_df = perf.equity_curve.to_dataframe()
print(eq_df[["quarter", "portfolio_return", "spy_return", "excess_return"]])

# Per-confidence-bucket breakdown
for band, stats in best.by_confidence_bucket.items():
    print(f"  {band}: {stats['win_rate']:.0%} WR, {stats['mean']:+.1f}% avg return")

Real-Time Signal Stream (Tier 1+)

Blocking (foreground)

def handle_signal(signal: dict):
    print(f"📡 NEW: {signal['ticker']} → {signal['signal']} (conf={signal['confidence']:.3f})")
    print(f"   {signal.get('rationale', '')}")

client.stream(handle_signal)  # blocks; Ctrl-C to stop

Non-blocking (background thread)

import time

thread = client.stream_async(handle_signal)

# Do other work while signals stream in
while True:
    time.sleep(1)

Account Usage

usage = client.account.usage()
print(f"Tier: {usage.tier_name}")
print(f"Requests today: {usage.requests_today}")
print(f"Remaining this hour: {usage.remaining_this_hour()}")

Error Handling

from nexus_alpha import NexusAlpha, AuthError, RateLimitError, TierError

try:
    signals = client.signals.history(limit=5000)
except TierError as e:
    print(f"Need Tier {e.required_tier}+ — upgrade at nexusalphaai.com")
except RateLimitError:
    print("Rate limit hit — wait for next hour window")
except AuthError:
    print("Invalid API key")

Environment Variable

Set NEXUS_ALPHA_API_KEY to avoid passing the key in code:

export NEXUS_ALPHA_API_KEY=your-api-key

client = NexusAlpha()  # reads from env automatically

API Tiers

Tier	Price	Rate limit	History	Bulk export	Stream
Insight	$5k/mo	100/hr	500 rows	❌	✅
Intelligence	$15k/mo	500/hr	5,000 rows	✅ (10k)	✅
Institutional	$50k/mo	5,000/hr	5,000 rows	✅ (10k)	✅

Subscribe at nexusalphaai.com.

Backtest Summary

Walk-forward validated 2022–2025 (long-only signals):

Hold Period	Avg Return	vs SPY	Sharpe	Win Rate
20 days	+0.61%	−0.11%	0.35	58.8%
40 days	+3.63%	+1.34%	1.13	58.8%
60 days	+4.79%	+2.45%	1.20	70.6%

Key finding: 0.65–0.70 confidence band → 90% win rate, +12.3% avg return at 60d. IC is negative above 0.75 confidence → signals capped at 0.75.

⚠️ Important: Per-signal excess return (+2.45% vs SPY) reflects information edge per trade. Full equal-weight portfolio simulation: +9.5% vs SPY +26.2% (2022–2025). These signals are designed as information overlays on existing positions, not standalone portfolios. Full methodology →

---

Signals are informational only and do not constitute investment advice. NEXUS Alpha is not a registered investment adviser.