API Documentation — IrrationalSignals

Quick Start

Get your first signal in under a minute:

Create an account to get your API key
Call the signals endpoint with your key
Receive live trading signals during market hours (10 AM – 4 PM ET)

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}`)
);

Authentication

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

X-API-Key: isk_free_abc123...

You receive your API key when you register. Keys are prefixed with tier information (e.g., isk_free_, isk_pro_, isk_max_).

For dashboard access, use a JWT Bearer token obtained from the login endpoint:

Authorization: Bearer eyJ...

Signals

GET /v1/signals

Get live trading signals. Available during US market hours (10 AM – 4 PM ET).

Query Parameters

Parameter	Type	Description
min_win_rate	float	Minimum per-symbol win rate (0.0–1.0)
max_win_rate	float	Maximum per-symbol win rate (0.0–1.0)
sector	string	Filter by sector (e.g., "tech")
hour	int	ET hour for same-day lookback (10–16)

Request

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.irrationalsignals.com/v1/signals?min_win_rate=0.65&sector=tech"

import requests

resp = requests.get(
    "https://api.irrationalsignals.com/v1/signals",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"min_win_rate": 0.65, "sector": "tech"}
)
signals = resp.json()

const params = new URLSearchParams({ min_win_rate: 0.65, sector: "tech" });
const resp = await fetch(
  `https://api.irrationalsignals.com/v1/signals?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const signals = await resp.json();

Response (Free Tier)

{
  "market_hour": "2026-03-13T17:00:00+00:00",
  "signal_count": 8,
  "tier": "free",
  "next_update": "2026-03-13T17:50:00+00:00",
  "signals": [
    {
      "symbol": "MRVL",
      "direction": "BUY",
      "win_rate": 0.78,
      "expected_return_pct": 0.0041,
      "current_price": 87.52,
      "sector": "tech",
      "status": "QUALIFIED"
    }
  ],
  "disclaimer": "Not investment advice. Signals are statistical observations, not recommendations."
}

Register

POST /v1/auth/register

Create a new account. Returns your API key — save it immediately, it won't be shown again.

Request Body

{
  "email": "user@example.com",
  "password": "SecurePass1!"
}

Password requirements: 8–128 characters, at least 1 uppercase, 1 lowercase, 1 digit, 1 special character.

Request

curl -X POST https://api.irrationalsignals.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "SecurePass1!"}'

import requests

resp = requests.post(
    "https://api.irrationalsignals.com/v1/auth/register",
    json={"email": "user@example.com", "password": "SecurePass1!"}
)
data = resp.json()
print(f"API Key: {data['api_key']}")  # Save this!

const resp = await fetch("https://api.irrationalsignals.com/v1/auth/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "user@example.com", password: "SecurePass1!" })
});
const data = await resp.json();
console.log(`API Key: ${data.api_key}`);  // Save this!

Response (201)

{
  "api_key": "isk_free_abc123...",
  "key_prefix": "isk_free_abc12345",
  "tier": "free",
  "created_at": "2026-03-13T10:00:00Z"
}

Login

POST /v1/auth/login

Authenticate and receive a JWT for dashboard access.

Request

curl -X POST https://api.irrationalsignals.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "SecurePass1!"}'

import requests

resp = requests.post(
    "https://api.irrationalsignals.com/v1/auth/login",
    json={"email": "user@example.com", "password": "SecurePass1!"}
)
token = resp.json()["access_token"]

const resp = await fetch("https://api.irrationalsignals.com/v1/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "user@example.com", password: "SecurePass1!" })
});
const { access_token } = await resp.json();

Response (200)

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "tier": "free",
  "expires_in": 3600
}

Rotate Key

POST /v1/auth/api-key/rotate

Revoke your current API key and generate a new one. Requires API key authentication.

Request

curl -X POST https://api.irrationalsignals.com/v1/auth/api-key/rotate \
  -H "X-API-Key: YOUR_API_KEY"

resp = requests.post(
    "https://api.irrationalsignals.com/v1/auth/api-key/rotate",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
new_key = resp.json()["api_key"]

const resp = await fetch("https://api.irrationalsignals.com/v1/auth/api-key/rotate", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" }
});
const { api_key } = await resp.json();

List Keys

GET /v1/auth/api-keys

List all API keys associated with your account.

Request

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

resp = requests.get(
    "https://api.irrationalsignals.com/v1/auth/api-keys",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
keys = resp.json()

const resp = await fetch("https://api.irrationalsignals.com/v1/auth/api-keys", {
  headers: { "X-API-Key": "YOUR_API_KEY" }
});
const keys = await resp.json();

Account

GET /v1/account

Get account info including keys and usage.

Request

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

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

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

Response

{
  "email": "user@example.com",
  "tier": "free",
  "is_active": true,
  "trial_ends_at": null,
  "created_at": "2026-03-13T10:00:00Z",
  "api_keys": [
    {
      "key_prefix": "isk_free_abc12345",
      "tier": "free",
      "is_active": true,
      "created_at": "2026-03-13T10:00:00Z"
    }
  ],
  "usage": {
    "tier": "free",
    "daily_limit": 200,
    "requests_today": 42,
    "requests_remaining": 158
  }
}

Usage

GET /v1/account/usage

Get usage statistics only.

Response

{
  "tier": "free",
  "daily_limit": 200,
  "requests_today": 42,
  "requests_remaining": 158
}

Billing

Stripe billing integration is coming soon. The following endpoints will be available:

POST /v1/billing/checkout

Create a Stripe checkout session for upgrading.

POST /v1/billing/portal

Open the Stripe customer portal to manage subscriptions.

Rate Limits

Requests are limited per day based on your tier:

Tier	Daily Limit	Per Hour (approx)
Free	200	~28
Pro	1,000	~143
Pro Max	5,000	~714

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

Code	Meaning
`401`	Invalid or missing authentication
`403`	Account deactivated
`409`	Duplicate email (registration)
`429`	Rate limit exceeded

Response by Tier

Signal responses include different fields based on your tier.

Pro Tier (additional fields)

{
  "conviction": {
    "pooled_win_rate": 0.68,
    "n_samples": 47
  },
  "execution_guidance": {
    "entry_price": 87.45,
    "expected_return_pct": 0.0041,
    "exit_target": 87.81,
    "primary_horizon": "1h"
  }
}

Pro Max Tier (additional fields)

{
  "execution_guidance": {
    "entry_price": 87.45,
    "expected_return_pct": 0.0041,
    "exit_target": 87.81,
    "stop_loss_armed": 87.23,
    "stop_loss_hard": 86.58,
    "primary_horizon": "1h",
    "horizon_end": "2026-03-13T18:50:00+00:00",
    "position_sizing_factor": 0.5,
    "predicted_drawdown_pct": -0.005
  },
  "preflight": {
    "vix_at_signal": 18.4,
    "avg_daily_volume": 12500000,
    "price_vs_entry_pct": 0.0008
  }
}