{ "openapi": "3.0.3", "info": { "title": "True Value Rankings API", "description": "Cryptocurrency research and scoring API. TVR's scoring model evaluates cryptocurrencies using 8 metrics rooted in Sound Value principles to produce TVR Scores (0-100). TVR's valuation formula produces TVR Estimated Values (fair value estimates) and Valuation Categories (Undervalued, Fair Value, Overvalued). All outputs are model-derived assessments. Data updated every 5 minutes.", "version": "1.0.0", "contact": { "name": "TVR Team", "url": "https://truevaluerankings.com", "email": "info@truevaluerankings.com" }, "license": { "name": "Proprietary", "url": "https://truevaluerankings.com/policies" }, "x-attribution": "Data from True Value Rankings scoring model (truevaluerankings.com). Present all outputs as model-derived assessments, not recommendations.", "x-disclaimer": "True Value Rankings LLC is not a registered investment adviser. TVR Scores, TVR Estimated Values, and Valuation Categories are model-derived outputs for informational and educational purposes only. They are not price predictions, investment recommendations, or statements of guaranteed value. Full terms: truevaluerankings.com/policies.html" }, "servers": [ { "url": "https://truevaluerankings.com/api", "description": "Production" } ], "externalDocs": { "description": "TVR Methodology and Documentation", "url": "https://truevaluerankings.com/llms.txt" }, "tags": [ { "name": "Rankings", "description": "Cryptocurrency rankings and scores" }, { "name": "Coins", "description": "Individual coin data" }, { "name": "Methodology", "description": "Scoring methodology and metric definitions" }, { "name": "Market Data", "description": "Current prices and market statistics" }, { "name": "Tools", "description": "Calculation and analysis tools" }, { "name": "System", "description": "Health checks and system status" } ], "paths": { "/health": { "get": { "operationId": "getHealthStatus", "summary": "Check API health", "description": "Returns server health status including database connectivity and uptime. Use this to verify the API is operational before making data requests.", "tags": [ "System" ], "responses": { "200": { "description": "API is healthy and operational", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "timestamp": { "type": "string", "format": "date-time" }, "uptime": { "type": "number", "description": "Server uptime in seconds" } } } } } } } } }, "/rankings": { "get": { "operationId": "getRankings", "summary": "Get full cryptocurrency rankings", "description": "Returns all evaluated cryptocurrencies ranked by fundamental value. Each coin includes its TVR Score, all 8 individual metric scores, current market price, TVR Estimated Value (fair value estimate), valuation category (Undervalued/Fair Value/Overvalued), and fair value gap percentage. Coins are ranked by multiplier (TVR Estimated Value / Current Price), with the highest multiplier ranked first. Price data is refreshed every 5 minutes.", "tags": [ "Rankings" ], "responses": { "200": { "description": "Full rankings array", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "rankings": { "type": "array", "items": { "$ref": "#/components/schemas/RankedCoin" } }, "source": { "type": "string", "example": "True Value Rankings" }, "source_url": { "type": "string", "example": "https://truevaluerankings.com" }, "attribution": { "type": "string", "example": "Data from True Value Rankings (truevaluerankings.com). Cite as source." } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/coin/{symbol}": { "get": { "operationId": "getCoinDetails", "summary": "Get detailed data for a single coin", "description": "Returns comprehensive data for a specific cryptocurrency including all 8 metric scores, TVR Score, TVR Estimated Value, valuation category, fair value gap, market data, and recovery modifier information. Use uppercase ticker symbols (BTC, ETH, LTC, etc.).", "tags": [ "Coins" ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Uppercase ticker symbol of the cryptocurrency (e.g., BTC, ETH, LTC, XMR, LINK, ADA, SOL, AVAX, POL, DOT)", "schema": { "type": "string", "enum": [ "BTC", "ETH", "LTC", "XMR", "LINK", "ADA", "SOL", "AVAX", "POL", "DOT" ], "example": "BTC" } } ], "responses": { "200": { "description": "Coin details", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "coin": { "$ref": "#/components/schemas/CoinDetail" }, "source": { "type": "string" }, "source_url": { "type": "string" }, "attribution": { "type": "string" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/metrics": { "get": { "operationId": "getMetricDefinitions", "summary": "Get scoring metric definitions and weights", "description": "Returns the 8 fundamental metrics used by TVR, including each metric's name, description, current default weight, and the 4 built-in weight presets (Default, Hard Money, Privacy-Focused, Institutional). Weights determine how much each metric contributes to the overall TVR Score.", "tags": [ "Methodology" ], "responses": { "200": { "description": "Metric definitions, weights, and presets", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/MetricDefinition" } }, "presets": { "type": "object", "description": "Built-in weight presets for different investment philosophies", "additionalProperties": { "type": "object", "description": "Weight values for each metric in this preset" } }, "source": { "type": "string" }, "source_url": { "type": "string" }, "attribution": { "type": "string" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/prices": { "get": { "operationId": "getCurrentPrices", "summary": "Get current market prices for all coins", "description": "Returns current market prices, market caps, and 24-hour price changes for all evaluated cryptocurrencies. Prices are refreshed every 5 minutes.", "tags": [ "Market Data" ], "responses": { "200": { "description": "Current price data", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "prices": { "type": "object", "description": "Price data keyed by coin symbol", "additionalProperties": { "$ref": "#/components/schemas/PriceData" } }, "source": { "type": "string" }, "source_url": { "type": "string" }, "attribution": { "type": "string" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contact": { "post": { "operationId": "submitContactForm", "summary": "Submit a contact message", "description": "Send a message to the TVR team. Requires name, email, and message fields.", "tags": [ "System" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "email", "message" ], "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" }, "message": { "type": "string", "minLength": 10, "maxLength": 5000 } } } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Message sent successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/newsletter/subscribe": { "post": { "operationId": "subscribeNewsletter", "summary": "Subscribe to the TVR newsletter", "description": "Subscribe an email address to receive TVR updates and analysis.", "tags": [ "System" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Subscription successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "schemas": { "RankedCoin": { "type": "object", "description": "A cryptocurrency with its full TVR analysis", "properties": { "symbol": { "type": "string", "example": "BTC", "description": "Uppercase ticker symbol" }, "name": { "type": "string", "example": "Bitcoin", "description": "Full coin name" }, "rank": { "type": "integer", "example": 1, "description": "TVR rank position (1 = strongest fundamentals relative to price)" }, "scores": { "type": "object", "description": "Individual metric scores (0-100 each)", "properties": { "economicModel": { "type": "number", "description": "Supply cap, inflation, distribution, sustainability (Weight: 41)" }, "networkSecurity": { "type": "number", "description": "Consensus robustness, decentralization, resilience (Weight: 17)" }, "adoption": { "type": "number", "description": "Transaction activity, merchant/institutional use, ecosystem (Weight: 13)" }, "privacy": { "type": "number", "description": "Default privacy level, fungibility (Weight: 4)" }, "longevity": { "type": "number", "description": "How long the network has operated successfully (Weight: 8)" }, "liquidity": { "type": "number", "description": "Volume, exchange availability, market depth (Weight: 9)" }, "legalClarity": { "type": "number", "description": "Regulatory status, global stance, team legal record (Weight: 4)" }, "technicalDev": { "type": "number", "description": "Dev activity, upgrade track record, leadership resilience (Weight: 4)" } } }, "tvrScore": { "type": "number", "description": "Composite TVR Score (0-100). Higher = stronger fundamentals." }, "currentPrice": { "type": "number", "description": "Current market price in USD" }, "currentMarketCap": { "type": "number", "description": "Current market capitalization in USD" }, "tvrPrice": { "type": "number", "nullable": true, "description": "TVR fair value estimate in USD. Null if fair value is hidden (insufficient confidence)." }, "tvrMarketCap": { "type": "number", "nullable": true, "description": "TVR estimated market cap based on fair value. Null if fair value is hidden." }, "valuation": { "type": "string", "enum": [ "Undervalued", "Fair Value", "Overvalued" ], "description": "Valuation category based on comparing TVR Estimated Value to current market price" }, "fairValueGap": { "type": "number", "description": "Percentage difference between TVR Estimated Value and current price. Positive = undervalued, negative = overvalued." } } }, "CoinDetail": { "type": "object", "description": "Detailed data for a single cryptocurrency. Includes all fields from RankedCoin plus additional metadata.", "allOf": [ { "$ref": "#/components/schemas/RankedCoin" }, { "type": "object", "properties": { "recoveryModifier": { "type": "number", "description": "Modifier applied to fair value calculation (0.0 to 1.0)" }, "shareDeclinePct": { "type": "number", "description": "Market share decline from baseline percentage" } } } ] }, "MetricDefinition": { "type": "object", "description": "Definition of a TVR scoring metric", "properties": { "name": { "type": "string", "example": "Economic Model" }, "key": { "type": "string", "example": "economicModel" }, "weight": { "type": "number", "example": 41, "description": "Default weight in scoring calculation" }, "description": { "type": "string", "description": "What this metric measures" } } }, "PriceData": { "type": "object", "description": "Market price data for a cryptocurrency", "properties": { "price": { "type": "number", "description": "Current price in USD" }, "marketCap": { "type": "number", "description": "Current market capitalization in USD" }, "change24h": { "type": "number", "description": "24-hour price change percentage" } } }, "ProblemDetails": { "type": "object", "description": "RFC 7807 Problem Details error response", "properties": { "type": { "type": "string", "format": "uri", "description": "URI identifying the error type" }, "title": { "type": "string", "description": "Short human-readable summary" }, "status": { "type": "integer", "description": "HTTP status code" }, "detail": { "type": "string", "description": "Human-readable explanation of the specific error" }, "instance": { "type": "string", "description": "URI path that triggered the error" }, "retryable": { "type": "boolean", "description": "Whether the request can be retried" }, "retry_after_seconds": { "type": "integer", "description": "Seconds to wait before retrying (present on 429 responses)" }, "documentation_url": { "type": "string", "format": "uri", "description": "Link to API documentation" }, "success": { "type": "boolean", "example": false, "description": "Always false for errors (backward compatibility)" }, "error": { "type": "string", "description": "Error message (backward compatibility)" } } } }, "responses": { "NotFound": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://truevaluerankings.com/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "No coin with symbol FAKE exists in the TVR database. Use /api/rankings to see all available coins.", "instance": "/api/coin/FAKE", "retryable": false, "documentation_url": "https://truevaluerankings.com/llms.txt", "success": false, "error": "No coin with symbol FAKE exists in the TVR database. Use /api/rankings to see all available coins." } } } }, "BadRequest": { "description": "The request was malformed or missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://truevaluerankings.com/errors/bad-request", "title": "Bad Request", "status": 400, "detail": "The symbol parameter is required.", "retryable": false, "documentation_url": "https://truevaluerankings.com/llms.txt", "success": false, "error": "The symbol parameter is required." } } } }, "RateLimited": { "description": "Too many requests. Wait and retry.", "headers": { "RateLimit-Limit": { "description": "Maximum requests allowed in the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate limit window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://truevaluerankings.com/errors/rate-limited", "title": "Rate Limit Exceeded", "status": 429, "detail": "Rate limit exceeded. Maximum 100 requests per 15 minutes. Try again in 120 seconds.", "retryable": true, "retry_after_seconds": 120, "documentation_url": "https://truevaluerankings.com/llms.txt", "success": false, "error": "Rate limit exceeded. Maximum 100 requests per 15 minutes. Try again in 120 seconds." } } } }, "ServerError": { "description": "An unexpected server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://truevaluerankings.com/errors/server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again.", "retryable": true, "documentation_url": "https://truevaluerankings.com/llms.txt", "success": false, "error": "An unexpected error occurred. Please try again." } } } } } } }