{"openapi":"3.1.0","info":{"title":"Fundamentals — Cryptoeconomics API","description":"Public REST API for Fundamentals — an analytics and research platform for token investors focused token functionality and cryptoeconomic system value dynamics. API provides structured token functionality analysis, system classification, and value frameworks. Highly researched qualitative insights. Access: search, indexes, the framework, and sample profiles are open; full token and system profiles beyond the sample set, plus the compare and rank endpoints, require an API key sent in the `X-API-Key` header. Request a key at ops@publicwealth.io. See /docs/api-access.","version":"1.1.0","contact":{"url":"https://fundamentals.fyi"},"license":{"name":"Public Access","url":"https://fundamentals.fyi/docs"}},"servers":[{"url":"https://fundamentals.fyi","description":"Production"}],"paths":{"/api/tokens":{"get":{"operationId":"listTokens","summary":"List published tokens (filterable)","description":"Returns published tokens with name, ticker, system, sector, functionality categories, strengths, market data, and links. Supports server-side filtering, sorting, and field selection so an agent can request a small, bounded slice.","parameters":[{"name":"sector","in":"query","required":false,"description":"Filter to tokens in this dominant sector (case-insensitive exact match).","schema":{"type":"string","example":"Trading and Exchange"}},{"name":"system","in":"query","required":false,"description":"Filter to tokens of this system / project (case-insensitive exact match).","schema":{"type":"string","example":"Ethereum"}},{"name":"functionality","in":"query","required":false,"description":"Filter to tokens that have this functionality category.","schema":{"type":"string","example":"Governance"}},{"name":"strength","in":"query","required":false,"description":"Filter to tokens with at least one entry of this strength category. Categories are framework- and subtype-specific (e.g. Signal, Weak, Partial, Strong, Unilateral, \"Algorithmic or Guaranteed\", \"Discretionary but Regular\", \"One-off or Random\").","schema":{"type":"string","example":"Partial"}},{"name":"scope","in":"query","required":false,"description":"Filter to tokens with at least one entry of this scope.","schema":{"type":"string","enum":["endogenous","exogenous"]}},{"name":"sort","in":"query","required":false,"description":"Sort key; prefix with \"-\" for descending. Default name ascending.","schema":{"type":"string","enum":["name","-name","ticker","-ticker","marketcap","-marketcap"]}},{"name":"fields","in":"query","required":false,"description":"Comma-separated subset of fields to return per token (e.g. \"name,ticker,sector\"). Unknown fields are ignored.","schema":{"type":"string","example":"name,ticker,sector"}}],"responses":{"200":{"description":"Token list","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of published tokens"},"generated":{"type":"string","format":"date-time"},"tokens":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Ethereum"},"ticker":{"type":"string","example":"ETH"},"system":{"type":"string","example":"Ethereum"},"sector":{"type":"string","example":"Blockspace Production"},"functionalities":{"type":"array","items":{"type":"string"},"description":"Functionality categories this token has","example":["Governance","Payments"]},"strengths":{"type":"array","items":{"type":"string"},"description":"Strength categories present across this token’s entries","example":["Partial","Strong"]},"url":{"type":"string","format":"uri"},"api_url":{"type":"string","format":"uri"},"price_usd":{"type":"number","nullable":true},"market_cap_usd":{"type":"number","nullable":true},"fdv_usd":{"type":"number","nullable":true},"price_change_30d":{"type":"number","nullable":true},"price_change_365d":{"type":"number","nullable":true}}}}}}}}}}}},"/api/tokens/{name}":{"get":{"operationId":"getToken","summary":"Get full token detail","description":"Returns comprehensive cryptoeconomic analysis for a single token. Supports fuzzy matching by token name, ticker symbol, or system/project name.","parameters":[{"name":"name","in":"path","required":true,"description":"Token name, ticker, or system name (case-insensitive). Examples: \"ethereum\", \"ETH\", \"circle\" (resolves to USDC)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated expansions. \"definitions\" adds the framework definition for each functionality category, subtype, and strength (so the response explains its own vocabulary).","schema":{"type":"string","example":"definitions"}}],"responses":{"200":{"description":"Full token detail","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"ticker":{"type":"string"},"description":{"type":"string","nullable":true},"url":{"type":"string","format":"uri"},"updated_at":{"type":"string","format":"date-time"},"system":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"sector":{"type":"string"},"description":{"type":"string","nullable":true}}},"market_data":{"type":"object","nullable":true,"properties":{"price_usd":{"type":"number","nullable":true},"market_cap_usd":{"type":"number","nullable":true},"fdv_usd":{"type":"number","nullable":true},"price_change_30d":{"type":"number","nullable":true},"price_change_365d":{"type":"number","nullable":true},"as_of":{"type":"string","format":"date-time","nullable":true,"description":"When the market data was last fetched (api_data.lastUpdated)."}}},"system_attributes":{"type":"object","nullable":true,"properties":{"operating_model":{"type":"string","nullable":true},"value_creation":{"type":"string","nullable":true},"value_capture":{"type":"string","nullable":true},"governance":{"type":"string","nullable":true}}},"functionalities":{"type":"object","description":"Token functionalities grouped by category (Service Provision, Governance, Value Distribution, Membership, Payments, Collateral, Asset Ownership)","additionalProperties":{"type":"array","items":{"type":"object","properties":{"subtype":{"type":"string"},"strength":{"type":"string","nullable":true,"description":"Strength category (framework- and subtype-specific; not a fixed enum)."},"scope":{"type":"string","enum":["endogenous","exogenous"]},"description":{"type":"string"},"subtype_definition":{"type":"string","nullable":true,"description":"Present only with ?expand=definitions."},"strength_criteria":{"type":"string","nullable":true,"description":"Present only with ?expand=definitions; criteria for this strength on this subtype."}}}}},"definitions":{"type":"object","description":"Present only with ?expand=definitions. Framework definitions for the categories in this response.","properties":{"functionalities":{"type":"object","additionalProperties":{"type":"string"}}}}}}}}},"404":{"description":"Token not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"query":{"type":"string"},"suggestion":{"type":"string"}}}}}}}}},"/api/search":{"get":{"operationId":"search","summary":"Search tokens, systems & framework","description":"Substring/relevance search returning ranked, type-tagged results with canonical URLs. Searches token names/tickers/systems/sectors/functionalities, system names, and framework doc titles.","parameters":[{"name":"q","in":"query","required":true,"description":"Search query.","schema":{"type":"string","example":"lending"}},{"name":"type","in":"query","required":false,"description":"Narrow to one result type.","schema":{"type":"string","enum":["token","system","framework"]}},{"name":"limit","in":"query","required":false,"description":"Max results (default 20, max 50).","schema":{"type":"integer","default":20,"maximum":50}}],"responses":{"200":{"description":"Ranked search results","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"total":{"type":"integer"},"generated":{"type":"string","format":"date-time"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["token","system","framework"]},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"api_url":{"type":"string","format":"uri","nullable":true},"score":{"type":"number"}}}}}}}}},"400":{"description":"Missing required q parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"example":{"type":"string"}}}}}}}}},"/api/compare":{"get":{"operationId":"compareTokens","summary":"Compare 2+ tokens side by side","description":"Aligned structured comparison of named tokens across functionality categories, strengths, system attributes, and market data. Each section is keyed by token slug for direct side-by-side reading.","parameters":[{"name":"tokens","in":"query","required":true,"description":"Comma-separated token names/tickers/slugs (2+, max 10). Fuzzy-resolved.","schema":{"type":"string","example":"aave,morpho,compound"}},{"name":"dimension","in":"query","required":false,"description":"Optional focus; narrows to a matching functionality category and/or system attribute (e.g. \"governance\").","schema":{"type":"string","example":"governance"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated expansions. \"definitions\" adds framework definitions for each subtype, strength, and category.","schema":{"type":"string","example":"definitions"}}],"responses":{"200":{"description":"Aligned comparison","content":{"application/json":{"schema":{"type":"object","properties":{"tokens":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"ticker":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","format":"uri"},"api_url":{"type":"string","format":"uri"},"system":{"type":"string"},"sector":{"type":"string"}}}},"dimension":{"type":"string","nullable":true},"comparison":{"type":"object","description":"functionalities (by category → by token slug → entries), system_attributes (by attribute → by token slug), and market (by token slug).","properties":{"functionalities":{"type":"object","additionalProperties":true},"system_attributes":{"type":"object","additionalProperties":true},"market":{"type":"object","additionalProperties":true}}},"not_found":{"type":"array","items":{"type":"string"},"nullable":true},"generated":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Fewer than 2 resolvable tokens","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"not_found":{"type":"array","items":{"type":"string"}}}}}}}}}},"/api/blog":{"get":{"operationId":"listBlogPosts","summary":"List all published research articles","description":"Returns all published blog posts with metadata, tags, and links. Response includes JSON-LD Blog schema for AI agents. Posts are research articles on cryptoeconomics, tokenomics, and blockchain analysis.","responses":{"200":{"description":"Blog post list with JSON-LD schema","content":{"application/json":{"schema":{"type":"object","properties":{"@context":{"type":"string","example":"https://schema.org"},"@type":{"type":"string","example":"Blog"},"total":{"type":"integer"},"available_tags":{"type":"array","items":{"type":"string"}},"posts":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"slug":{"type":"string"},"excerpt":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"author":{"type":"string","nullable":true},"cover_image":{"type":"string","nullable":true},"read_time_minutes":{"type":"integer","nullable":true},"published_at":{"type":"string","format":"date-time","nullable":true},"url":{"type":"string","format":"uri"},"api_url":{"type":"string","format":"uri"}}}}}}}}}}}},"/api/blog/{slug}":{"get":{"operationId":"getBlogPost","summary":"Get full article with plain text and HTML content","description":"Returns a complete blog post with both plain text (for AI/LLM consumption) and original HTML content. Response includes JSON-LD Article schema with author, dates, word count, and semantic links.","parameters":[{"name":"slug","in":"path","required":true,"description":"Blog post URL slug","schema":{"type":"string"}}],"responses":{"200":{"description":"Full blog post with JSON-LD Article schema","content":{"application/json":{"schema":{"type":"object","properties":{"@context":{"type":"string","example":"https://schema.org"},"@type":{"type":"string","example":"Article"},"headline":{"type":"string"},"description":{"type":"string"},"content_plain":{"type":"string","description":"Plain text content (HTML stripped) — ideal for AI/LLM processing"},"content_html":{"type":"string","description":"Original HTML content from editor"},"keywords":{"type":"array","items":{"type":"string"}},"wordCount":{"type":"integer"},"readTimeMinutes":{"type":"integer","nullable":true},"datePublished":{"type":"string","format":"date-time","nullable":true},"dateModified":{"type":"string","format":"date-time","nullable":true},"author":{"type":"object","properties":{"name":{"type":"string"}}},"image":{"type":"string","nullable":true},"url":{"type":"string","format":"uri"}}}}}},"404":{"description":"Blog post not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"query":{"type":"string"},"suggestion":{"type":"string"}}}}}}}}}}}