Developers

PairSignal API

A REST API for cross-ratio signals, historical backtests, the pair screener and raw ratio series — the same engine that powers our alerts. Custody-free: the API reads public market data only, never your keys or funds.

Authentication Rate limits & tiers Errors GET /v1/signal GET /v1/top-pairs GET /v1/ratio POST /v1/backtest

Authentication

All /v1 endpoints require an API key. Create one in your dashboard under API access after activating an API plan. The key is shown once at creation — store it securely; we keep only a hash and cannot recover it.

Send the key as a Bearer token:

curl https://pairsignal.io/v1/signal?base=BTC&quote=ETH&timeframe=1h \
  -H "Authorization: Bearer psk_live_your_key_here"

An X-API-Key: psk_live_... header is also accepted. Keys carry the tier and access window of the account that owns them; revoking a key in the dashboard takes effect immediately.

Base URL: https://pairsignal.io · all endpoints are versioned under /v1 · responses are JSON.

Rate limits & tiers

Your plan sets the request rate, the daily quota and which endpoints you can call. Access runs on a pool of API days, billed per day in crypto — top up any number of days in the dashboard.

Tier	Price	Rate	Daily quota	Endpoints
Developer	$3 / day	60 req/min	5,000	signal, top-pairs, ratio (≤1,000 pts)
Pro	$8 / day	300 req/min	50,000	+ backtest, ratio ≤5,000 pts
Business	$20 / day	1,200 req/min	500,000	all, ratio unlimited depth

Every response carries the current limit state:

X-RateLimit-Limit: 50000
X-RateLimit-Remaining: 49997
X-RateLimit-Reset: 41820        # seconds until the daily quota resets (UTC midnight)

Exceeding the burst rate or the daily quota returns 429 rate_limited with a Retry-After header.

Errors

Errors use standard HTTP status codes and a consistent JSON body:

{ "error": { "code": "invalid_api_key", "message": "API key is invalid or has been revoked." } }

Status	Code	Meaning
400	`bad_request`	Missing or invalid parameter.
401	`invalid_api_key`	Key missing, malformed, unknown or revoked.
402	`api_access_required`	No active API plan, or API days exhausted.
403	`tier_upgrade_required`	Endpoint not included in your tier.
422	`insufficient_data`	Not enough history to compute a result.
429	`rate_limited`	Burst rate or daily quota exceeded.
502	`upstream_error`	Market-data source was unavailable.

Live signal

GET/v1/signal

Current cross-ratio R = mid(base) / mid(quote) and its percentile bands. Use it to know whether a pair is at an entry zone (R ≥ upper band) or an exit/reversion zone (R ≤ lower band).

Parameter	Type	Default	Notes
`base`	string	—	Required. Asset A symbol, e.g. `BTC`.
`quote`	string	—	Required. Asset B symbol, e.g. `ETH`.
`timeframe`	string	`15m`	Candle size: `5m`, `15m`, `1h`, `4h`…
`lookback`	int	`100`	Percentile window (20–1,000).
`pct_lo`	float	`5`	Lower-band percentile.
`pct_hi`	float	`95`	Upper-band percentile.

curl "https://pairsignal.io/v1/signal?base=BTC&quote=ETH&timeframe=1h" \
  -H "Authorization: Bearer psk_live_..."

{
  "base": "BTC", "quote": "ETH", "timeframe": "1h",
  "r_now": 18.42, "lower_band": 17.10, "upper_band": 19.05,
  "pct_lo": 5, "pct_hi": 95, "lookback": 100,
  "direction": "fall", "mode": "percentile"
}

Top pairs (screener)

GET/v1/top-pairs

The top crypto pairs from the PairSignal screener, ranked by score.

Parameter	Type	Default	Notes
`limit`	int	`20`	How many pairs to return (1–100).

curl "https://pairsignal.io/v1/top-pairs?limit=10" \
  -H "Authorization: Bearer psk_live_..."

{
  "count": 10,
  "items": [
    { "coin_a": "STRK", "coin_b": "ATOM", "score": 0.91,
      "zone": "bottom", "position": 0.04, "range_width_pct": 38.2,
      "sector": "L1", "timeframe": "15m" }
  ]
}

Ratio history

GET/v1/ratio

The historical ratio series R = close(base) / close(quote) built from aligned OHLCV candles. Depth is capped by your tier.

Parameter	Type	Default	Notes
`base`	string	—	Required. Asset A symbol.
`quote`	string	—	Required. Asset B symbol.
`timeframe`	string	`15m`	Candle size.
`limit`	int	`500`	Points to return; clamped to the tier ceiling.

curl "https://pairsignal.io/v1/ratio?base=BTC&quote=ETH&timeframe=1h&limit=500" \
  -H "Authorization: Bearer psk_live_..."

{
  "base": "BTC", "quote": "ETH", "timeframe": "1h", "count": 500,
  "series": [ { "t": 1718000000000, "r": 18.21 }, { "t": 1718003600000, "r": 18.33 } ]
}

Backtest

POST/v1/backtest

Replay the percentile entry→exit cycle over historical candles and get summary statistics plus individual trades. Pro and Business only. Send a JSON body:

Field	Type	Default	Notes
`base`	string	—	Required.
`quote`	string	—	Required.
`timeframe`	string	`15m`	Candle size.
`limit`	int	`1000`	Candles to replay (120–1,000).
`pct_lo` / `pct_hi`	float	`5` / `95`	Band percentiles.
`pct_lookback`	int	`100`	Percentile window.
`fee_pct`	float	`0.1`	Per-side fee assumption.

curl -X POST https://pairsignal.io/v1/backtest \
  -H "Authorization: Bearer psk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"base":"BTC","quote":"ETH","timeframe":"1h","limit":1000}'

{
  "base": "BTC", "quote": "ETH", "timeframe": "1h",
  "summary": {
    "count": 12, "win_rate": 75.0, "final_factor": 1.34,
    "avg_profit_pct": 2.6, "avg_bars_held": 41, "open_position": false
  },
  "trades": [
    { "r_entry": 19.02, "r_exit": 17.40, "profit_pct": 8.5, "bars_held": 38 }
  ]
}

Need a higher limit or a custom endpoint? [email protected].