# DAMO Market State API

> A fixed, versioned definition of market state: recorded at the time, never recomputed, verifiable by anyone. Market state for crypto assets: four permanent state codes across ten fixed timeframes. Market state data only. Not a trading signal. Not investment advice.

## Quick start
- MCP: connect any Streamable HTTP MCP client to https://api.damolive.com/mcp (no account or key). Example call: get_market_state {"symbol": "BTCUSDT", "timeframes": ["1h", "1d"]}
- HTTP: curl -s "https://api.damolive.com/v1/market-state/BTCUSDT?timeframes=1h,1d"
- Example with a real response: https://api.damolive.com/skill.md

## What it gives
- Timeframes: 1m, 5m, 15m, 1h, 4h, 12h, 1d, 3d, 1w, 1M
- Symbols: tickers like BTCUSDT (https://api.damolive.com/v1/symbols). BTC, btc, BTC/USDT, BTC-PERP and Bitcoin are also accepted; a wrong symbol returns did_you_mean
- States: 1 bull_momentum, 2 weakening, 3 bear_momentum, 4 recovery (permanent codes)
- Layers: verified (closed candles, recorded once, never changed), live (forming candle, provisional)
- Time fields: verified as_of is when DAMO last wrote the record (UTC), not a candle time; each timeframe's candle close is states[tf].candle_close. live observed_at is when DAMO observed the forming candles; states[tf].candle_close_expected is when that candle will close. There is no generated_at.

## How it can be checked
- VERIFIED states are written once into an append-only hash chain; each UTC day gets an attestation anchored on Base mainnet (contract 0x67FeC2A19B3e3eb26d80Ad87D19e33dfc39F5766). Each VERIFIED value carries its seq and hash, so an answer that cites it can be checked later against the anchored daily attestation.

## What does not change
- The 4 state codes and 10 timeframes are permanent; any engine change is released as a new engine version (engine_version is in every VERIFIED value); recorded states are never recomputed.

## Not provided
- Prices or candles, order book, funding rates, intrabar events, forecasts or trading signals, bulk historical exports (the full recorded history is not offered as a download).

## Access
- Free tier: no key. 500 state values per client per UTC day (1 state value = 1 symbol x 1 timeframe)
- Optional timeframes selection (e.g. timeframes=15m,1h): only those are returned and counted; the vector keeps its 10 positions, others are null with status not_requested. Case-sensitive: 1m = minute, 1M = month.
- HTTP state responses carry an ETag. Send it back as the query parameter if_none_match=<ETag> (the If-None-Match header is also accepted where your connection passes it through): if nothing changed the API answers 304 Not Modified with no body, and it is not counted against the quota (the request rate limit still applies). VERIFIED states change only when a candle closes.
- Optional format=compact returns only symbol, layer, time, the 10-value vector, a short citation line and the remaining quota, plus stale: true when the data is old (no per-timeframe seq, hash or engine version; batch: one citation line for all results). It is counted the same way (state values). Default format=full is for citing and checking records.
- Every state response is signed with Ed25519 by DAMO. HTTP: header DAMO-Signature (kid, alg, sig). MCP: tool result _meta "com.damolive/signature". The signature covers the fields symbol, layer, as_of, observed_at, vector_order, vector, states, engine_version and chain_head that are present in each state object (batch: {"results": [...]} of those objects), serialized with RFC 8785 (JCS). quota, citation and other fields are not signed. Add proof=1 to also get it in the body as 'proof'. Public keys: https://api.damolive.com/.well-known/damo-keys.json
- OpenAPI: https://api.damolive.com/openapi.json
- MCP (Streamable HTTP): https://api.damolive.com/mcp
- Symbols: https://api.damolive.com/v1/symbols
- State definitions: https://api.damolive.com/v1/states
- Source: DAMO composite (crypto perpetual futures). Market states are computed from the DAMO composite, built from several public crypto perpetual futures markets. DAMO publishes its own state outputs only, not raw prices or candles. VERIFIED records with engine_version 1.0 (before 2026-10-26 00:00 UTC) were computed from a single reference market; engine 1.1 and later use the DAMO composite (same calculation, new input).
- Agent Skill: https://api.damolive.com/skill.md
- Site: https://damolive.com/llms.txt

## Terms
- Use of the API and MCP server is subject to the DAMO API terms: https://damolive.com/api-terms (among others: no reverse engineering of the state engine, no use of outputs to train or calibrate a model or service that reproduces DAMO states, no systematic collection beyond your own application's needs). Privacy: https://damolive.com/privacy