Rulyfi Scanner API

Quickstart

1. Get an API key

Create a key on your account page: rulyfi.com → Account → API keys. It requires a paid plan (Plus or higher). Keys look like rk_live_… and are shown once — copy it when you create it.

2. Add the MCP server

Point any MCP client at the package with your key.

claude mcp add rulyfi --env RULYFI_API_KEY=rk_live_your_key -- npx -y @rulyfi/mcp

For Claude Desktop (Settings → Developer → Edit Config) or Cursor (.cursor/mcp.json), add:

{
  "mcpServers": {
    "rulyfi": {
      "command": "npx",
      "args": ["-y", "@rulyfi/mcp"],
      "env": { "RULYFI_API_KEY": "rk_live_your_key" }
    }
  }
}

3. Use it

The server exposes seven tools: list_indicators, list_symbols, validate_strategy, run_backtest, run_scan, get_scan_results, and download_export. A typical porting loop is: have the agent translate a Python/TradingView strategy into the Rulyfi format, call validate_strategy to fix it error-by-error, then run_backtest to check it.

REST API

Base URL https://api.rulyfi.com/v1. Authenticate with a bearer header on every request:

Authorization: Bearer rk_live_<your key>

Errors

Every error uses one envelope. code is a stable machine-readable string; hint is present when there is a useful next step (a 429 nudges you toward run_scan).

{
  "error": {
    "code": "rate_limited",
    "message": "Per-key rate limit exceeded (60 calls/min).",
    "hint": "Testing a parameter grid? Use run_scan — it tests a whole grid far more cheaply than thousands of single backtests."
  }
}

Codes: invalid_request, strategy_invalid, paid_tier_required (403), rate_limited / daily_cap_exceeded (429), insufficient_credits (402), candle_ref_not_found, candles_invalid, range_invalid, not_found, method_not_allowed, internal_error, unavailable. A missing, invalid, or revoked key returns 401.

Pricing & limits

Backtesting uses your Rulyfi credits at the same rate as the scanner: 1,000 API backtest calls = 1 credit, billed as a prepaid 1,000-call block, so normal use of tens or hundreds of calls per session is effectively free. Scans are billed by the size of the parameter grid, exactly like the web scanner.

When you hit a rate or daily limit the error nudges you toward run_scan, which tests a whole parameter grid far more cheaply than thousands of single backtests.

The candle_ref flow

The server never fetches candles itself — you provide them. Because agents typically hold the data fixed and vary only the strategy, you upload the candles once and reference them by candle_ref on subsequent calls. Candle references are scoped to your account. Small ranges (up to 5,000 bars) can be sent inline in the candles field instead.

# 1. Ask for a candle_ref for the market + range you want to test.
POST /v1/candles
{ "exchange": "binance", "symbol": "BTCUSDT", "timeframe": "1h",
  "start_ts": 1704067200000, "end_ts": 1719792000000 }

# -> cache miss: you get an upload target.
{ "candle_ref": "…", "cached": false,
  "upload_url": "https://…", "wire_format": "v4-gzip" }

# 2. PUT the gzip candle wire to upload_url (the MCP package does this for you).

# 3. Backtest — reference the candles by candle_ref. Change the strategy, reuse
#    the same candle_ref; no re-fetch, no re-upload.
POST /v1/backtests
{ "strategy": { … }, "candle_ref": "…", "walk_forward": false }

The MCP run_backtest tool does all of this in one call: it fetches candles locally (cached on your machine), uploads them once, and runs the backtest.

force_fresh & caching

Re-running an identical scan is served from the result cache for free — the same grid over the same symbols, range, and settings returns the cached leaderboard at zero credits. There is one consequence to know: a cache hit returns only the ranked rows, not a freshly computed full-population export, so a cached scan produces no parquet file. When you specifically need the full export, pass force_fresh: true on POST /v1/scans (or force_fresh in run_scan). That skips the cache and recomputes — which re-charges credits, so it is always an explicit opt-in, never automatic.

Reference