Documentation

The TideTrade API

Name: TideTrade market snapshot: the tide on 140 crypto assets today
Creator: TideTrade

Read-only JSON, the same rows as the scanner: for every asset, whether the tide is in or out on the last completed candle, how far the close sits from its line and when it last flipped. Pull it into a spreadsheet, a bot, a dashboard or an assistant; Claude and ChatGPT can call it directly. Nothing here forecasts anything, and the rule behind every row is published.

Five endpoints

`GET /api/v1/snapshot`	Today's tide on every asset, the day's flips, the current weekly report. Public, no key, any origin.
`GET /api/v1/snapshot.csv`	The same, one CSV row per asset, for spreadsheets.
`GET /api/v1/rules`	The rule manifest. Public.
`GET /api/v1/status`	Operational status: last reads, late rows, corrections, ledger hashes. Public, any origin.
`GET /api/v1/states`	The state of every asset, daily or weekly. Needs a Pro key.

The snapshot, free

The market as the rule reads it, with no key: every asset's row (the same fields as the states below), crypto breadth and the Core 30 by state, the flips on the newest candle with their prices, and the week's Sunday Tide Report. Add ?tf=W for weekly candles. It is cached for a minute and limited to 60 requests a minute per address; the rows change a few times a day after the writer's slots, so fetch it once and keep it.

curl https://tidetrade.app/api/v1/snapshot
curl -o tide.csv https://tidetrade.app/api/v1/snapshot.csv

The same two files are also served at /snapshot.json and /snapshot.csv, outside the /api/ prefix, for fetchers that refuse API-looking paths. Readable from any origin, so a page, a notebook, a spreadsheet's import function or an assistant with a web tool can fetch it directly. Ask an assistant to "fetch https://tidetrade.app/api/v1/snapshot and tell me which Core assets are tide out" and it has the day's facts rather than a guess. The machine-readable index of everything public is at /llms.txt.

Authentication

Create a key on your account page. It is shown once and starts with tl_. Send it in the Authorization header:

curl -H "Authorization: Bearer tl_…" https://tidetrade.app/api/v1/states?tf=D

A ?key= query parameter is accepted too, but keys in URLs end up in logs, so prefer the header. Revoke a key from the same page; one key per integration makes that painless. The public endpoints need no key; what a key adds is the states endpoint for your own integrations, with history and alerts to follow.

States

tf=D for daily candles (the default), tf=W for weekly. The answer names the rule version it was computed under, when the writer finished the run, the counts per band and one row per asset:

{
  "rule": { "id": "tl-rule-v1", "version": "1.3.1", "manifest": "/api/v1/rules" },
  "timeframe": "D",
  "asOf": "2026-10-19T00:05:14.105Z",
  "counts": { "IN": 55, "OUT": 71, "SLACK": 14, "WARMING": 0 },
  "assets": [
    { "id": "btc", "name": "Bitcoin", "symbol": "BTC", "class": "crypto", "tier": "core",
      "band": "IN", "dir": "UP", "close": 107250, "line": 104180.5,
      "distanceAtr": 1.14, "distancePct": 2.9, "candleStart": "2026-10-18", "source": "kraken",
      "flippedOn": "2026-10-06", "flipPrice": 98210 },
    …
  ]
}

Field	Meaning
`id`	Universe id, the same as in /asset/{id}.
`name, symbol`	Display name and ticker.
`class`	crypto, index or commodity. Indices and commodities are an alpha and not for decisions.
`tier`	core (30 liquid names) or extended.
`band`	IN, OUT or SLACK; null while an asset is still warming up (a new listing inside the indicator's warm-up).
`dir`	UP or DOWN: the rule's direction on the last completed candle. A flip is a change between consecutive candles.
`close`	Close of the last completed candle, in the venue's dollar quote.
`line`	The Tideline on that candle: Supertrend(10, 3).
`distanceAtr`	Distance of the close from the line in ATR(10), in the direction's own sense: how far above the line for UP, how far below it for DOWN. Slack water is within 0.5.
`distancePct`	The same distance as a percentage of the close.
`candleStart`	Start date of the candle the state was read from, UTC.
`source`	Venue the candle came from: kraken, coinbase or yahoo.
`flippedOn, flipPrice`	The candle on which the direction last changed and its close; null when no flip is on record.

Assets still warming up carry listedOn and addedOn instead of a reading. The full field list with types is in the OpenAPI document.

When the data changes

States are read on completed candles only, so the rows change a few times a day and never in between. Poll after the slots, not continuously:

00:05 UTC: venue-fed crypto, the daily close.
06:00 UTC: Yahoo-fed indices and commodities, once their session day has ended.
08:30 UTC: Yahoo-fed crypto, once Yahoo has published the day.
14:00 Europe/London: weekly candles for every asset.

The status page and /api/v1/status show when each slot last ran and whether it was complete; a run that could not record is marked degraded and the previous rows stay in place.

Limits and errors

60 requests a minute per key; above that 429 with a Retry-After header.
401: no key, or an invalid or revoked one. 403: the key's account has no current Pro plan.
Errors are JSON: { "error": "…" }.
States answers are not cached; the manifest is cached for five minutes and the status for one.

Versioning

The API path carries its own version: v1 only gains fields, and anything renamed or removed would appear under a new path. The rule is versioned separately in the manifest, with a changelog and a hash; every states answer names the rule version its rows were computed under, currently 1.3.1.

Add TideTrade to Claude or ChatGPT

The same data as tools an assistant can call, over the Model Context Protocol (MCP), the standard both Claude and ChatGPT use for connectors. No account, no key, read-only; 120 requests a minute per address.

https://tidetrade.app/mcp

Claude: in Settings, under Connectors, add a custom connector with the name TideTrade and this URL; no sign-in step. In Claude Code: claude mcp add --transport http tidetrade https://tidetrade.app/mcp.
ChatGPT: in Settings, under Apps and Connectors, turn on developer mode and create a connector with this URL and no authentication; the search and fetch tools are the pair ChatGPT's research mode uses.
Any other MCP client (Cursor, VS Code, Windsurf, a script): Streamable HTTP, stateless, JSON answers; a config entry needs only the URL.

Six tools, every one read-only:

snapshot: today's tide on every asset, with filters by state, tier and class, daily or weekly.
asset: one coin by id, symbol or name: its state and room to its line, the record of its trips, its flips.
report: a Sunday Tide Report by week, or the latest.
rule: the published rule manifest.
search and fetch: the generic pair connectors expect; search returns ids, fetch returns one document.

Then ask: "Which Core assets are tide out today, and how far below their lines?", "What has the rule's record been on Solana?", "Summarise this week's Sunday Tide Report." The answers carry candle dates and the same notice as this page: states, not forecasts.

For tools and agents

MCP server: https://tidetrade.app/mcp
OpenAPI 3.1: /docs/api/openapi.json; the public endpoints alone, for a GPT or any agent without a key: /docs/api/openapi-public.json
Plain-text index for assistants: /llms.txt. The free snapshot is also described as a Dataset in this page's structured data.
API catalog (RFC 9727): /.well-known/api-catalog, also named in a Link header on every page.
Machine-readable rule: /api/v1/rules. Public status: /api/v1/status.

Create a key Pricing The rule Status

The API is decision support, not financial advice: it reports the mechanical state of a published rule on completed candles and forecasts nothing. Cryptoassets are high-risk; trend rules lose money in sideways markets. Use is subject to the disclaimer.