API Documentation

Quick Start

Get your first signal in under a minute:

1. Create an account to get your API key
2. Call the signals endpoint with your key
3. Receive live trading signals during market hours (10:47 AM – 3:47 PM ET) — see schedule

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.irrationalsignals.com/v1/signals

import requests

resp = requests.get(
    "https://api.irrationalsignals.com/v1/signals",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
data = resp.json()
for signal in data["signals"]:
    print(f"{signal['symbol']} {signal['direction']} — WR: {signal['win_rate']}")

const resp = await fetch("https://api.irrationalsignals.com/v1/signals", {
  headers: { "X-API-Key": "YOUR_API_KEY" }
});
const data = await resp.json();
data.signals.forEach(s =>
  console.log(`${s.symbol} ${s.direction} — WR: ${s.win_rate}`)
);

Python SDK

The official Python SDK wraps the API with typed models and error handling. Requires Python 3.9+.

Install

pip install irrationalsignals

Usage

from irrationalsignals import Client

client = Client("YOUR_API_KEY")
response = client.get_signals()

for signal in response.signals:
    print(f"{signal.symbol} {signal.direction} (win rate: {signal.win_rate:.0%})")
    if signal.execution_guidance:
        eg = signal.execution_guidance
        print(f"  Entry: ${eg.entry_price}  Exit: ${eg.exit_target}")

Filter by Sector or Hour

# Filter by sector
response = client.get_signals(sector="Technology")

# Same-day lookback (Max tier only)
response = client.get_signals(hour=14)

Error Handling

from irrationalsignals import Client, AuthError, RateLimitError, APIError

client = Client("YOUR_API_KEY")

try:
    response = client.get_signals()
except AuthError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after: {e.retry_after}s")
except APIError as e:
    print(f"API error {e.status_code}: {e.detail}")

View on PyPI

Authentication

All API requests require authentication via the X-API-Key header:

X-API-Key: isk_free_abc123...

Create an account to get your API key. Keys are prefixed with your tier (e.g., isk_free_, isk_pro_, isk_max_). You can manage your keys from the dashboard.

Signals

Get live trading signals. Available during US market hours — see signal schedule for exact times.

Query Parameters

Request

# Basic — get latest signals
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.irrationalsignals.com/v1/signals"

# Filter by sector
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.irrationalsignals.com/v1/signals?sector=Technology"

# Same-day lookback (Max only)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.irrationalsignals.com/v1/signals?hour=14"

import requests

# Basic — get latest signals
resp = requests.get(
    "https://api.irrationalsignals.com/v1/signals",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
signals = resp.json()

# Filter by sector
resp = requests.get(
    "https://api.irrationalsignals.com/v1/signals",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"sector": "Technology"}
)

# Same-day lookback (Max only)
resp = requests.get(
    "https://api.irrationalsignals.com/v1/signals",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"hour": 14}
)

// Basic — get latest signals
const resp = await fetch(
  "https://api.irrationalsignals.com/v1/signals",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const signals = await resp.json();

// Filter by sector
const bySector = await fetch(
  "https://api.irrationalsignals.com/v1/signals?sector=Technology",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);

// Same-day lookback (Max only)
const lookback = await fetch(
  "https://api.irrationalsignals.com/v1/signals?hour=14",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);

Response

Free tier gets 1 signal per day from the first market hour (10:47 AM ET); Pro gets up to 8 per hour; Pro Max gets all signals. Fields not available for your tier are omitted entirely.

{
  "market_hour": "2026-03-13T17:00:00+00:00",
  "signal_count": 1,
  "tier": "free",
  "next_update": "2026-03-13T17:50:00+00:00",
  "signals": [
    {
      "symbol": "MRVL",
      "direction": "BUY",
      "win_rate": 0.78,
      "win_rate_type": "per_symbol",
      "current_price": 87.52,
      "vix_at_signal": 18.4,
      "sector": "Technology",
      "industry": "Semiconductors",
      "execution_guidance": {
        "entry_price": 87.45,
        "expected_return_pct": 0.0123,
        "exit_target": 88.52,
        "primary_horizon": "2h"
      }
    }
  ],
  "disclaimer": "Not investment advice. Signals are statistical observations, not recommendations."
}

Response Fields

Signal Fields

Execution Guidance Fields

Included in every signal. Pro Max tier adds additional fields marked below.

Preflight Fields Pro Max only

Live market conditions fetched at request time. Use these to validate whether the signal's assumptions still hold before entering a trade.

Signal Schedule

Signals are generated 6 times per trading day, at approximately :47 past each hour from 10 AM to 3 PM Eastern Time. Each batch analyzes the current hour's :30 mid-hour bar.

Daily Signal Timetable

The schedule is the same year-round in ET. UTC times shift with US Daylight Saving Time (DST).

Key Details

• Timezone: All times are US Eastern (ET), which automatically adjusts for Daylight Saving Time. EDT (UTC-4) runs from the 2nd Sunday of March through the 1st Sunday of November; EST (UTC-5) runs the rest of the year.
• No signals before 10:47 AM ET: The first half-hour bar of each market hour must complete before signals can be generated.
• Last signal at 3:47 PM ET: The final signal analyzes the 3:00–3:30 PM bar. There is no signal for the 3:30–4:00 PM window as the market closes at 4:00 PM, leaving no actionable window.
• Non-trading days: No signals on weekends or US market holidays. The API returns an empty signals array.
• next_update field: Every API response includes a next_update timestamp (ISO 8601 / UTC) so you always know exactly when fresh signals will be available.
• hour parameter: Use the hour query parameter (ET hour, 10–15) to request signals for a specific market hour within the current day.

Rate Limits

Requests are limited per day based on your tier:

Rate limit info is included in response headers:

• X-RateLimit-Limit — your daily limit
• X-RateLimit-Remaining — requests remaining today

Errors

All errors follow RFC 7807 problem details format:

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or revoked API key."
}

Common Status Codes

Response by Tier

Each tier builds on the previous. Free gets 1 signal per day from the first market hour, Pro up to 8/hour, Max sees all (~16/hr avg). Signals are proportionally sampled across win-rate buckets.

Free & Pro Tiers

All tiers include direction, win rate, current price, VIX at signal time, sector, industry, and execution guidance (entry price, expected return, exit target, primary horizon). Free gets 1 signal from the first market hour; Pro gets up to 8/hr across all hours. Same response fields. See the Signals response example above.

Pro Max Tier — adds horizon end, preflight, and lookback

Adds a precise horizon end timestamp and live preflight checks (price drift vs. entry, intraday momentum, and relative volume — fetched at request time). Pro Max also unlocks same-day historical lookback via the hour query parameter. Fields not available for lower tiers are simply absent from their responses.

{
  "symbol": "MRVL",
  "direction": "BUY",
  "win_rate": 0.78,
  "win_rate_type": "per_symbol",
  "current_price": 87.52,
  "vix_at_signal": 18.4,
  "sector": "Technology",
  "industry": "Semiconductors",
  "execution_guidance": {
    "entry_price": 87.45,
    "expected_return_pct": 0.0123,
    "exit_target": 88.52,
    "primary_horizon": "2h",
    "horizon_end": "2026-03-13T19:30:00+00:00"
  },
  "preflight": {
    "price_vs_entry_pct": 0.0008,
    "intraday_range_position": 0.62,
    "relative_volume": 1.34,
    "checked_at": "2026-03-13T17:52:00+00:00"
  }
}