{"openapi":"3.1.0","info":{"title":"Mattheus Public Data API","version":"1.0.0","description":"Generated unauthenticated, cache-first public market intelligence contract. State-changing, account-management, hidden, disabled, and canary-only routes are excluded."},"servers":[{"url":"https://app.mattheus.ai/"},{"url":"/"}],"security":[],"tags":[{"name":"Public Data"}],"paths":{"/api/v1/public/markets":{"get":{"operationId":"public_markets","tags":["Public Data"],"summary":"List public markets","description":"Unauthenticated cache-first market intelligence with freshness metadata.","parameters":[],"responses":{"200":{"description":"List public markets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicMarketsEnvelope"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope, policy, regulatory, certification, or approval gate denied the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-mattheus":{"visibility":"public","auth":"none","scopes":[],"mcpGroup":"public_data","sdk":{"typescript":"client.public.markets.list()","python":"await client.public.markets.list()"},"freshness":{"asOfRequired":true,"maxAgeMs":60000},"idempotency":"none","retryPolicy":"safe","requiredHeaders":[],"errorCodes":[]}}},"/api/v1/public/markets/{asset}":{"get":{"operationId":"public_market","tags":["Public Data"],"summary":"Get public market by asset or market id","description":"Returns one public market summary or a stale not-found envelope.","parameters":[{"name":"asset","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get public market by asset or market id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicMarketEnvelope"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope, policy, regulatory, certification, or approval gate denied the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-mattheus":{"visibility":"public","auth":"none","scopes":[],"mcpGroup":"public_data","sdk":{"typescript":"client.public.markets.get(asset)","python":"await client.public.markets.get(asset)"},"freshness":{"asOfRequired":true,"maxAgeMs":60000},"idempotency":"none","retryPolicy":"safe","requiredHeaders":[],"errorCodes":[]}}},"/api/v1/public/markets/{asset}/history":{"get":{"operationId":"public_market_history","tags":["Public Data"],"summary":"Get bounded cached public market history","description":"Returns bounded historical candle observations from the Mattheus cache-backed candle store without submitting or signing any transaction.","parameters":[{"name":"asset","in":"path","required":true,"schema":{"type":"string"}},{"name":"resolution","in":"query","required":false,"description":"Requested candle bucket. Defaults to one day and never fabricates intervals finer than stored observations.","schema":{"type":"string","enum":["1m","5m","15m","30m","1h","4h","1d"],"default":"1d"}},{"name":"from","in":"query","required":false,"description":"Inclusive RFC 3339 lower time bound.","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"description":"Inclusive RFC 3339 upper time bound. Defaults to the request time.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"description":"Maximum returned points from 1 through 366.","schema":{"type":"integer","minimum":1,"maximum":366,"default":366}}],"responses":{"200":{"description":"Get bounded cached public market history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicMarketHistoryEnvelope"}}}},"400":{"description":"The requested bounds, resolution, or limit are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope, policy, regulatory, certification, or approval gate denied the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Market not found; returns a stale empty history envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicMarketHistoryEnvelope"}}}},"409":{"description":"Idempotency or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-mattheus":{"visibility":"public","auth":"none","scopes":[],"mcpGroup":"public_data","sdk":{"typescript":"client.public.markets.history(asset, options)","python":"await client.public.markets.history(asset, **options)"},"freshness":{"asOfRequired":true,"maxAgeMs":60000},"idempotency":"none","retryPolicy":"safe","requiredHeaders":[],"errorCodes":["invalid_public_market_history_query"]}}},"/api/v1/public/markets/{asset}/orderbook":{"get":{"operationId":"public_market_orderbook","tags":["Public Data"],"summary":"Get bounded cached public order-book depth","description":"Returns at most 100 cumulative bid and ask levels from an approved Mattheus public snapshot cache. Anonymous requests do not call the venue directly, and the response cannot place, prepare, sign, or execute an order.","parameters":[{"name":"asset","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get bounded cached public order-book depth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicOrderbookEnvelope"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope, policy, regulatory, certification, or approval gate denied the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Market is unavailable or does not support the public order-book surface.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The read-only public order-book source is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-mattheus":{"visibility":"public","auth":"none","scopes":[],"mcpGroup":"public_data","sdk":{"typescript":"client.public.markets.orderbook(asset)","python":"await client.public.markets.orderbook(asset)"},"freshness":{"asOfRequired":true,"maxAgeMs":5000},"idempotency":"none","retryPolicy":"safe","requiredHeaders":[],"errorCodes":["public_orderbook_not_available","public_orderbook_unavailable"]}}},"/api/v1/public/protocols/{protocol}":{"get":{"operationId":"public_protocol","tags":["Public Data"],"summary":"Get public protocol metadata","description":"Returns public protocol availability, visibility, and certification metadata.","parameters":[{"name":"protocol","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get public protocol metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicProtocolEnvelope"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope, policy, regulatory, certification, or approval gate denied the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-mattheus":{"visibility":"public","auth":"none","scopes":[],"mcpGroup":"public_data","sdk":{"typescript":"client.public.protocols.get(protocol)","python":"await client.public.protocols.get(protocol)"},"freshness":{"asOfRequired":true,"maxAgeMs":60000},"idempotency":"none","retryPolicy":"safe","requiredHeaders":[],"errorCodes":[]}}},"/api/v1/public/status":{"get":{"operationId":"public_status","tags":["Public Data"],"summary":"Get public data plane status","description":"Reports cache state, source health, and market/protocol counts.","parameters":[],"responses":{"200":{"description":"Get public data plane status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicStatusEnvelope"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope, policy, regulatory, certification, or approval gate denied the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-mattheus":{"visibility":"public","auth":"none","scopes":[],"mcpGroup":"public_data","sdk":{"typescript":"client.public.status()","python":"await client.public.status()"},"freshness":{"asOfRequired":true,"maxAgeMs":60000},"idempotency":"none","retryPolicy":"safe","requiredHeaders":[],"errorCodes":[]}}},"/api/v1/public/data/markets.json":{"get":{"operationId":"public_markets_json","tags":["Public Data"],"summary":"Get public markets JSON mirror","description":"JSON mirror for crawlers, caches, examples, and static clients.","parameters":[],"responses":{"200":{"description":"Get public markets JSON mirror","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicMarketsEnvelope"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope, policy, regulatory, certification, or approval gate denied the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-mattheus":{"visibility":"public","auth":"none","scopes":[],"mcpGroup":"public_data","sdk":{"typescript":"client.public.markets.list()","python":"await client.public.markets.list()"},"freshness":{"asOfRequired":true,"maxAgeMs":60000},"idempotency":"none","retryPolicy":"safe","requiredHeaders":[],"errorCodes":[]}}},"/api/v1/public/data/protocols.json":{"get":{"operationId":"public_protocols_json","tags":["Public Data"],"summary":"Get public protocols JSON mirror","description":"JSON mirror of public protocol metadata.","parameters":[],"responses":{"200":{"description":"Get public protocols JSON mirror","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicProtocolsEnvelope"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope, policy, regulatory, certification, or approval gate denied the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-mattheus":{"visibility":"public","auth":"none","scopes":[],"mcpGroup":"public_data","sdk":{"typescript":"client.public.protocols.list()","python":"await client.public.protocols.list()"},"freshness":{"asOfRequired":true,"maxAgeMs":60000},"idempotency":"none","retryPolicy":"safe","requiredHeaders":[],"errorCodes":[]}}},"/api/v1/public/openapi.public.json":{"get":{"operationId":"public_openapi","tags":["Public Data"],"summary":"Get generated public OpenAPI","description":"Returns the generated public OpenAPI 3.1 contract.","parameters":[],"responses":{"200":{"description":"Get generated public OpenAPI","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Scope, policy, regulatory, certification, or approval gate denied the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-mattheus":{"visibility":"public","auth":"none","scopes":[],"mcpGroup":"public_data","sdk":{"typescript":"fetch('/openapi.public.json')","python":"httpx.get('/openapi.public.json')"},"freshness":{"asOfRequired":false},"idempotency":"none","retryPolicy":"safe","requiredHeaders":[],"errorCodes":[]}}}},"components":{"schemas":{"PublicErrorCode":{"type":"string","enum":["ACTION_NOT_CERTIFIED","ACTION_CANARY_ONLY","POLICY_DENIED","POLICY_UNAVAILABLE","VENUE_UNHEALTHY","QUOTE_STALE","INSUFFICIENT_BALANCE","IDEMPOTENCY_CONFLICT","EXECUTION_DISABLED"],"description":"Stable public execution/API error code. Internal gate names may appear only in details."},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true},"retryAfter":{"type":"integer"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"nextAction":{"oneOf":[{"type":"string"},{"type":"object","additionalProperties":true}]}},"additionalProperties":true},"Freshness":{"type":"object","required":["asOf","stale"],"properties":{"asOf":{"type":"string","format":"date-time"},"freshnessMs":{"type":"integer"},"stale":{"type":"boolean"},"staleReason":{"type":"string"},"sourceStatus":{"type":"string","enum":["healthy","degraded","down","unknown"]}},"additionalProperties":true},"PublicEnvelope":{"type":"object","required":["schemaVersion","generatedAt","freshness","data"],"properties":{"schemaVersion":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"freshness":{"$ref":"#/components/schemas/Freshness"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}},"methodology":{"type":"string"},"citations":{"type":"array","items":{"type":"object","additionalProperties":true}},"relatedActions":{"type":"array","items":{"type":"object","additionalProperties":true}},"data":true},"additionalProperties":true},"PublicMarketsEnvelope":{"allOf":[{"$ref":"#/components/schemas/PublicEnvelope"}]},"PublicMarketEnvelope":{"allOf":[{"$ref":"#/components/schemas/PublicEnvelope"}]},"PublicProtocolsEnvelope":{"allOf":[{"$ref":"#/components/schemas/PublicEnvelope"}]},"PublicProtocolEnvelope":{"allOf":[{"$ref":"#/components/schemas/PublicEnvelope"}]},"PublicStatusEnvelope":{"allOf":[{"$ref":"#/components/schemas/PublicEnvelope"}]},"MarketGraphEnvelope":{"allOf":[{"$ref":"#/components/schemas/PublicEnvelope"}]}}},"x-mattheus-contract":{"schemaVersion":"mattheus.api-contracts.v1","generatedFrom":"packages/api-contracts/src/registry.json","publicErrorCodes":["ACTION_NOT_CERTIFIED","ACTION_CANARY_ONLY","POLICY_DENIED","POLICY_UNAVAILABLE","VENUE_UNHEALTHY","QUOTE_STALE","INSUFFICIENT_BALANCE","IDEMPOTENCY_CONFLICT","EXECUTION_DISABLED"],"excludes":["internal routes","legacy compatibility aliases","first-party-only frontend routes","state-changing routes","blocked actions","hidden tools","canary actions"]},"x-mattheus-ai-providers":[{"id":"anthropic","label":"Anthropic","models":["claude-sonnet-5","claude-opus-4-8","claude-haiku-4-5-20251001"]},{"id":"openai","label":"OpenAI","models":["gpt-5.6-luna"]},{"id":"google","label":"Google","models":["gemini-3.5-flash","gemini-3.1-flash-lite"]},{"id":"xai","label":"xAI","models":["grok-4.3"]},{"id":"mistral","label":"Mistral","models":["mistral-large-2512"]},{"id":"openrouter","label":"OpenRouter","models":["openai/gpt-5.2","google/gemini-3.1-flash-lite"]}]}