{"openapi":"3.1.0","info":{"title":"TideTrade API","version":"1","summary":"Read-only tide states for 140 crypto assets on one published rule, read on completed candles.","description":"Read-only GET endpoints. The market snapshot (JSON and CSV), the rule manifest and the operational status are public: no key, readable from any origin. The keyed states endpoint serves Pro accounts the same rows. The same data is served as MCP tools at https://tidetrade.app/mcp for Claude, ChatGPT and other assistants. Nothing here forecasts anything: every row is the mechanical state of tl-rule-v1 version 1.3.1 on the last completed candle. Decision support, not financial advice.","termsOfService":"https://tidetrade.app/disclaimer"},"servers":[{"url":"https://tidetrade.app"}],"externalDocs":{"url":"https://tidetrade.app/docs/api","description":"Human-readable documentation"},"paths":{"/api/v1/rules":{"get":{"operationId":"getRules","summary":"The rule manifest","description":"The published rule behind every state, flip and alert: indicator parameters, ATR method, candle definitions per venue, data sources, schedule, record types, the universe snapshot, the changelog and a SHA-256 of the whole manifest. Public, cached for five minutes.","responses":{"200":{"description":"The live manifest, in a list so retired versions can be published beside it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RulesResponse"}}}}}}},"/api/v1/status":{"get":{"operationId":"getStatus","summary":"Operational status","description":"When each part of the universe was last read, whether the read was complete, late rows and corrections in the last week, the latest ledger hashes and cross-venue agreement on the newest candle. Public, readable from any origin, cached for a minute.","responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}}}}},"/api/v1/snapshot":{"get":{"operationId":"getSnapshot","summary":"The market snapshot, free","description":"Today's tide on every asset: band, direction, close, the Tideline, distance from it, candle, venue and last flip, plus crypto breadth and the Core 30, the flips on the newest candle and the current weekly report. No key, any origin, 60 requests a minute per client address, cached for a minute; the data changes a few times a day after the writer's slots, so cache it rather than poll.","parameters":[{"name":"tf","in":"query","required":false,"schema":{"type":"string","enum":["D","W"],"default":"D"},"description":"Timeframe: D for daily candles, W for weekly."}],"responses":{"200":{"description":"The snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Snapshot"}}}},"429":{"description":"More than 60 requests in a minute from this address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}}}}},"/api/v1/snapshot.csv":{"get":{"operationId":"getSnapshotCsv","summary":"The market snapshot as CSV","description":"The same snapshot as one CSV row per asset (id, name, symbol, class, tier, band, dir, close, line, distanceAtr, distancePct, candleStart, source, flippedOn, flipPrice), for spreadsheets. Same limits as the JSON.","parameters":[{"name":"tf","in":"query","required":false,"schema":{"type":"string","enum":["D","W"],"default":"D"}}],"responses":{"200":{"description":"CSV, UTF-8, CRLF rows, a header row first.","content":{"text/csv":{"schema":{"type":"string"}}}},"429":{"description":"More than 60 requests in a minute from this address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/states":{"get":{"operationId":"getStates","summary":"Tide state of every asset","description":"The same rows as the scanner on completed candles: band, direction, close, the Tideline, distance from it and the last flip, for every asset in the universe. Needs a Pro API key. 60 requests a minute per key; the data changes a few times a day, so poll after the slots, not continuously.","security":[{"apiKey":[]}],"parameters":[{"name":"tf","in":"query","required":false,"schema":{"type":"string","enum":["D","W"],"default":"D"},"description":"Timeframe: D for daily candles, W for weekly."}],"responses":{"200":{"description":"States","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatesResponse"}}}},"401":{"description":"No key, or an invalid or revoked key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key belongs to an account without a current Pro plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests in a minute for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"A Pro API key, created at /account/api and shown once. Keys start with tl_. Send it as \"Authorization: Bearer <key>\"; a ?key= query parameter is also accepted but ends up in logs, so prefer the header."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"Band":{"type":["string","null"],"enum":["IN","OUT","SLACK",null],"description":"IN: direction up and the close more than half an ATR(10) above the line. OUT: direction down and more than half an ATR below it. SLACK: within half an ATR on either side. null while an asset is still warming up."},"Direction":{"type":["string","null"],"enum":["UP","DOWN",null],"description":"The rule's direction on the last completed candle; a flip is a change between consecutive candles."},"AssetState":{"type":"object","required":["id","name","symbol","class","tier","band","close","distanceAtr","distancePct","flippedOn"],"properties":{"id":{"type":"string","description":"Universe id, the same as in /asset/{id}."},"name":{"type":"string"},"symbol":{"type":"string"},"class":{"type":"string","enum":["crypto","index","commodity"],"description":"Indices and commodities are an alpha and not for decisions."},"tier":{"type":"string","enum":["core","extended"],"description":"Core: 30 liquid names. Extended: the rest."},"band":{"$ref":"#/components/schemas/Band"},"dir":{"$ref":"#/components/schemas/Direction"},"close":{"type":["number","null"],"description":"Close of the last completed candle, in the venue's dollar quote."},"line":{"type":["number","null"],"description":"The Tideline on that candle: Supertrend(10, 3)."},"distanceAtr":{"type":["number","null"],"description":"Distance of the close from the line in ATR(10), measured in the direction's own sense: how far above the line for UP, how far below it for DOWN. The slack band is within 0.5."},"distancePct":{"type":["number","null"],"description":"The same distance as a percentage of the close."},"candleStart":{"type":["string","null"],"format":"date","description":"Candle start date, YYYY-MM-DD, UTC."},"source":{"type":["string","null"],"enum":["kraken","coinbase","yahoo",null],"description":"Venue the candle came from."},"flippedOn":{"type":["string","null"],"format":"date","description":"Start date of the candle on which the direction last changed; null when none is on record."},"flipPrice":{"type":["number","null"],"description":"Close of that flip candle."},"listedOn":{"type":["string","null"],"format":"date","description":"Present only for assets still warming up: when the venue listed it."},"addedOn":{"type":["string","null"],"format":"date","description":"Present only for assets still warming up: when it joined the universe."}}},"Counts":{"type":"object","required":["IN","OUT","SLACK","WARMING"],"properties":{"IN":{"type":"integer"},"OUT":{"type":"integer"},"SLACK":{"type":"integer"},"WARMING":{"type":"integer"}}},"StatesResponse":{"type":"object","required":["rule","timeframe","asOf","counts","assets"],"properties":{"rule":{"type":"object","required":["id","version","manifest"],"properties":{"id":{"type":"string"},"version":{"type":"string"},"manifest":{"type":"string","description":"Path of the rule manifest these rows were computed under."}}},"timeframe":{"type":"string","enum":["D","W"]},"asOf":{"type":["string","null"],"format":"date-time","description":"When the writer finished the run these rows come from."},"counts":{"$ref":"#/components/schemas/Counts"},"assets":{"type":"array","items":{"$ref":"#/components/schemas/AssetState"}}}},"Breadth":{"type":"object","required":["in","slack","out","warming","total"],"properties":{"in":{"type":"integer"},"slack":{"type":"integer"},"out":{"type":"integer"},"warming":{"type":"integer"},"total":{"type":"integer"}}},"Flip":{"type":"object","required":["id","symbol","name","candleStart","toDir","price"],"properties":{"id":{"type":"string"},"symbol":{"type":"string"},"name":{"type":"string"},"candleStart":{"type":"string","format":"date"},"toDir":{"type":"string","enum":["UP","DOWN"],"description":"UP: tide in. DOWN: tide out."},"price":{"type":["number","null"],"description":"Close of the flip candle."}}},"Snapshot":{"type":"object","required":["rule","timeframe","asOf","candle","breadth","core","flips","report","assets","links","notice"],"properties":{"rule":{"type":"object","required":["id","version","manifest"],"properties":{"id":{"type":"string"},"version":{"type":"string"},"manifest":{"type":"string"}}},"timeframe":{"type":"string","enum":["D","W"]},"asOf":{"type":["string","null"],"format":"date-time","description":"When the writer finished the run these rows come from."},"candle":{"type":["string","null"],"format":"date","description":"Start date of the newest completed crypto candle in the rows."},"breadth":{"$ref":"#/components/schemas/Breadth","description":"The crypto assets by state."},"core":{"$ref":"#/components/schemas/Breadth","description":"The Core 30 by state."},"flips":{"type":"array","description":"Flips on the newest candle, crypto only.","items":{"$ref":"#/components/schemas/Flip"}},"report":{"type":["object","null"],"description":"The newest Sunday Tide Report in the archive.","properties":{"week":{"type":"string","description":"ISO week, e.g. 2026-W43."},"sunday":{"type":"string","format":"date"},"url":{"type":"string"},"summary":{"type":"object"}}},"assets":{"type":"array","items":{"$ref":"#/components/schemas/AssetState"}},"links":{"type":"object","description":"Paths of the related machine-readable resources."},"notice":{"type":"string"}}},"RuleManifest":{"type":"object","required":["rule_id","version","status","indicator","manifest_hash"],"properties":{"rule_id":{"type":"string"},"version":{"type":"string"},"status":{"type":"string"},"effective_from":{"type":"string","format":"date-time"},"indicator":{"type":"object","description":"Name, period, multiplier, source and ATR method."},"output":{"type":"string"},"candles":{"type":"object"},"display_bands":{"type":"object"},"position_convention":{"type":"string"},"data_sources":{"type":"object"},"schedule":{"type":"object"},"record_types":{"type":"object"},"universe":{"type":"object"},"code_commit":{"type":"string"},"changelog_url":{"type":"string"},"changelog":{"type":"array","items":{"type":"object"}},"manifest_hash":{"type":"string","description":"SHA-256 of the canonical JSON of everything above."}},"additionalProperties":true},"RulesResponse":{"type":"object","required":["rules","live"],"properties":{"rules":{"type":"array","items":{"$ref":"#/components/schemas/RuleManifest"}},"live":{"type":"string","description":"rule_id of the live rule."}}},"Status":{"type":"object","required":["now","slots","live","corrections","correctionCount","hashes"],"properties":{"now":{"type":"string","format":"date-time"},"venues":{"type":"array","description":"Cross-venue agreement on the newest daily candle.","items":{"type":"object","properties":{"id":{"type":"string"},"venue":{"type":"string"},"candle":{"type":"string","format":"date"},"checked":{"type":"integer"},"agreeing":{"type":"integer"},"rate":{"type":"number"},"maxCloseDiffPct":{"type":"number"}}}},"slots":{"type":"array","description":"One entry per writer slot.","items":{"type":"object","properties":{"label":{"type":"string"},"finishedAt":{"type":["string","null"],"format":"date-time"},"ageHours":{"type":["number","null"]},"loaded":{"type":["string","null"],"description":"\"loaded/total\" assets."},"recorded":{"type":"boolean"},"expectedAssets":{"type":"integer"},"state":{"type":"string","enum":["ok","degraded","stale","never"]}}}},"live":{"type":"object","description":"Live flips in the window, on time and late.","properties":{"total":{"type":"integer"},"late":{"type":"integer"},"onTime":{"type":"integer"},"windowDays":{"type":"integer"}}},"lateRows":{"type":"array","items":{"type":"object"}},"corrections":{"type":"array","items":{"type":"object"}},"correctionCount":{"type":"integer"},"hashes":{"type":"array","description":"The latest daily ledger hashes.","items":{"type":"object"}}},"additionalProperties":true}}}}