Predictive Models · API Reference

API Documentation

REST API delivering next-day direction and rate predictions for US equity special stocks. Permissioned access · JSON responses · daily data before 8:00 AM EST.

REST
Protocol
JSON
Response Format
2
Endpoints
~4K
ISINs per Day

Authentication

Every request requires an API key.

Pass your API key in the x-api-key request header. Keys are provisioned by Tidal Markets and scoped to the specific endpoints you have been granted access to — a key authorised for WaveCast-D only will receive a 403 on WaveCast-R requests.

Keep your key secret. Do not include it in client-side code or commit it to version control. If you believe your key has been compromised, contact Tidal Markets immediately for rotation.

Rate Limits
10 requests/second · 1,000 requests/day per key. Contact Tidal Markets if your use case requires higher throughput.
Request Header
x-api-key: YOUR_API_KEY
Example · cURL
curl -H “x-api-key: YOUR_API_KEY” \
  “https://7k7vl9c2ja.execute-api
    .us-east-1.amazonaws.com
    /prod/wavecast-d
    ?date=2026-07-17″

Endpoints

Base URL and available endpoints.

Base URL
https://7k7vl9c2ja.execute-api.us-east-1.amazonaws.com/prod
Method
Endpoint
Description
Model
GET
/wavecast-d
Next-day direction predictions (Up / Down) with calibrated conviction scores
WaveCast-D
GET
/wavecast-r
Next-day rate magnitude predictions in bps and % with confidence score
WaveCast-R

Direction Model

GET /wavecast-d

Returns next-day Up/Down direction predictions and calibrated conviction scores for all active US equity specials on the requested date. Access is restricted to your permissioned key.

Query Parameters
date Required string
The scoring date for which to retrieve predictions. Must be a trading day on which WaveCast-D has run.
Format: YYYY-MM-DD  ·  Example: 2026-07-17
isin Optional string
Filter the response to a single security. When omitted, all active specials for the requested date are returned (~4,000 ISINs).
Format: 12-character ISIN  ·  Example: US0003752047
Response Fields
Field Type Description
Date string Scoring date (YYYY-MM-DD)
ISIN string 12-character ISIN
PredictedDirection integer 1 = Up  ·  0 = Down
ProbabilityUp float Raw model probability (0–1)
DirectionConfidence float Calibrated conviction score (0–100). Higher = higher realized accuracy. Q5 ≥ 84.5%.
ModelVersion string Model version that produced this prediction (e.g. v4)
Request · All ISINs cURL
curl -H “x-api-key: YOUR_KEY” \
  “https://7k7vl9c2ja.execute-api
   .us-east-1.amazonaws.com
   /prod/wavecast-d
   ?date=2026-07-17″
Request · Single ISIN cURL
curl -H “x-api-key: YOUR_KEY” \
  “https://7k7vl9c2ja.execute-api
   .us-east-1.amazonaws.com
   /prod/wavecast-d
   ?date=2026-07-17
   &isin=US0003752047″
Response · 200 OK JSON
{
  “model”: “wavecast-d”,
  “date”: “2026-07-17”,
  “row_count”: 1,
  “isin_filter”: “US0003752047”,
  “data”: [
    {
      “Date”: “2026-07-17”,
      “ISIN”: “US0003752047”,
      “PredictedDirection”: 0,
      “ProbabilityUp”: 0.146310,
      “DirectionConfidence”: 70.738,
      “ModelVersion”: “v4”
    }
  ],
  “_meta”: {
    “client_id”: “client_acme_capital”,
    “duration_ms”: 90.5
  }
}

Rate Model

GET /wavecast-r

Returns next-day rate magnitude predictions in both basis points and percent for all active US equity specials on the requested date. One prediction per ISIN from tier-specific supervised machine learning models.

Query Parameters
date Required string
The scoring date for which to retrieve predictions. Must be a trading day on which WaveCast-R has run.
Format: YYYY-MM-DD  ·  Example: 2026-07-17
isin Optional string
Filter the response to a single security. When omitted, all active specials for the requested date are returned.
Format: 12-character ISIN  ·  Example: US0003752047
Response Fields
Field Type Description
Date string Scoring date (YYYY-MM-DD)
ISIN string 12-character ISIN
PredictedRate_bps float Predicted next-day IntrinsicRateAvg in basis points
PredictedRate_pct float Predicted next-day IntrinsicRateAvg as a decimal percent
RateConfidence float Calibrated conviction score (0–100) based on historical prediction distribution
ModelVersion string Model version that produced this prediction (e.g. v5)
Request · Single ISIN cURL
curl -H “x-api-key: YOUR_KEY” \
  “https://7k7vl9c2ja.execute-api
   .us-east-1.amazonaws.com
   /prod/wavecast-r
   ?date=2026-07-17
   &isin=US0003752047″
Response · 200 OK JSON
{
  “model”: “wavecast-r”,
  “date”: “2026-07-17”,
  “row_count”: 1,
  “isin_filter”: “US0003752047”,
  “data”: [
    {
      “Date”: “2026-07-17”,
      “ISIN”: “US0003752047”,
      “PredictedRate_bps”: 179.310,
      “PredictedRate_pct”: 1.793,
      “RateConfidence”: 89.78,
      “ModelVersion”: “v5”
    }
  ],
  “_meta”: {
    “client_id”: “client_acme_capital”,
    “duration_ms”: 151.2
  }
}
Important
WaveCast-R is a rate magnitude model only. Its implied direction (sign of predicted change) produces ~50% accuracy — a coin flip. Do not use it for directional decisions. Use WaveCast-D for direction.

Error Handling

All errors return JSON with a consistent structure.

HTTP Status Codes
Status Code Cause
200 — Success
400 MISSING_DATE
INVALID_DATE		 Missing or malformed date parameter
401 MISSING_KEY No x-api-key header present
403 PERMISSION_DENIED Key not authorised for this endpoint
404 NOT_FOUND Date is not a trading day, model has not run, or ISIN not in universe
500 INTERNAL_ERROR Unexpected server error — contact Tidal Markets
Error Response Shape
403 · PERMISSION_DENIED
{
  “error”: “Access denied. Your API key is
    not authorized for wavecast-r.
    Contact Tidal Markets to
    request access.”,
  “code”: “PERMISSION_DENIED”
}
404 · NOT_FOUND
{
  “error”: “No predictions available for
    wavecast-d on 2026-07-19.
    Check that the date is a
    trading day and that the
    model has run.”,
  “code”: “NOT_FOUND”
}

Code Examples

Query the API in your language of choice.

Python
import requests

API_KEY = “YOUR_API_KEY”
BASE_URL = “https://7k7vl9c2ja
  .execute-api.us-east-1
  .amazonaws.com/prod”

resp = requests.get(
  f“{BASE_URL}/wavecast-d”,
  headers={“x-api-key”: API_KEY},
  params={“date”: “2026-07-17”}
)
data = resp.json()
predictions = data[“data”]
R
library(httr)
library(jsonlite)

API_KEY <- “YOUR_API_KEY”

resp <- GET(
  “https://7k7vl9c2ja
   .execute-api.us-east-1
   .amazonaws.com
   /prod/wavecast-d”,
  add_headers(`x-api-key` = API_KEY),
  query = list(date = “2026-07-17”)
)
predictions <- fromJSON(
  content(resp, “text”)
)$data

Data Availability & Notes

What to expect, every trading day.

Daily Cadence

Available before 8:00 AM EST

Predictions are computed from the prior trading day’s loan data, which delivers at 7:00 AM EST. The API is available with fresh data before 8:00 AM EST each trading day.

Date Parameter

Trading days only

The date parameter must be a US trading day. Weekends, holidays, and days prior to WaveCast’s launch will return a 404. The date reflects the scoring date — the T-1 data used to generate predictions.

Universe

~4,000 active specials

Only ISINs with an intrinsic borrow rate above 20 bps on T-1 are scored. The universe varies daily as stocks enter and exit special status. Querying an ISIN not in the universe on a given date returns a 404.

Ready to connect?

API keys are provisioned by Tidal Markets as part of your data agreement. Contact us to request access or to rotate an existing key.

Request API Access
Explore the WaveCast Suite

THE INFORMATION CONTAINED HEREIN IS PROPRIETARY TO TIDAL MARKETS LLC AND DESIGNATED THIRD PARTIES. THESE ILLUSTRATIONS MAY NOT BE COPIED, EDITED, OR REDISTRIBUTED WITHOUT THE EXPRESS WRITTEN CONSENT OF TIDAL MARKETS LLC. ANY INFORMATION CONTAINED HEREIN DOES NOT CONSTITUTE OR IMPLY INVESTMENT ADVICE BY TIDAL MARKETS LLC OR ANY REPRESENTATIVES THEREOF. TIDAL MARKETS LLC DOES NOT GUARANTEE THE QUALITY, ACCURACY, OR COMPLETENESS OF THE INFORMATION CONTAINED HEREIN. ALL MATERIALS PROVIDED ARE FOR INFORMATIONAL PURPOSES ONLY AND IS NOT INTENDED FOR TRADING PURPOSES, NOR SHOULD BE CONSTRUED OR INTERPRETED AS A COURSE OF ACTION. TIDAL MARKETS LLC IS NOT RESPONSIBLE OR LIABLE IN ANY FORM TO ANY READER, FIRM OR CORPORATION, FOR ANY DAMAGES OR LOSSES ARISING FROM ANY USE OF THE INFORMATION CONTAINED HEREIN. PAST PERFORMANCE IS NOT INDICATIVE OF FUTURE RESULTS.