{
  "openapi": "3.1.0",
  "info": {
    "title": "Moai.cash Public APIs",
    "description": "Public, unauthenticated, read-only APIs for token prices, historical charts, token news, and fiat exchange rates. No authentication required. All endpoints are GET. Base URL: https://moai.cash",
    "version": "1.0.0",
    "contact": { "name": "Moai.cash", "url": "https://moai.cash/contact" }
  },
  "servers": [{ "url": "https://moai.cash" }],
  "externalDocs": {
    "description": "API documentation (service-doc)",
    "url": "https://moai.cash/docs/api"
  },
  "paths": {
    "/api/token-price": {
      "get": {
        "summary": "Token prices",
        "description": "Current prices for one or more tokens by CoinGecko id, with 24h change, market cap, and volume. Cached ~60s.",
        "parameters": [
          {
            "name": "ids",
            "in": "query",
            "required": true,
            "description": "Comma-separated CoinGecko coin ids (e.g. bitcoin,ethereum).",
            "schema": { "type": "string" },
            "example": "bitcoin,ethereum"
          },
          {
            "name": "currencies",
            "in": "query",
            "required": false,
            "description": "Comma-separated fiat currencies to report prices in. Default: usd,eur,gbp,cad,aud.",
            "schema": { "type": "string" },
            "example": "usd,eur"
          }
        ],
        "responses": {
          "200": {
            "description": "Map of coin id to price object.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": { "type": "object" }
                }
              }
            }
          },
          "400": { "description": "Missing ids parameter." },
          "502": { "description": "Upstream price provider error." }
        }
      }
    },
    "/api/token-prices-batch": {
      "get": {
        "summary": "All token prices (batch)",
        "description": "Prices for every token Moai tracks, in a single request. Cached ~60s.",
        "parameters": [
          {
            "name": "currencies",
            "in": "query",
            "required": false,
            "description": "Comma-separated fiat currencies (default usd).",
            "schema": { "type": "string" },
            "example": "usd"
          }
        ],
        "responses": {
          "200": {
            "description": "Map of coin id to price object.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": { "type": "object" }
                }
              }
            }
          },
          "502": { "description": "Upstream price provider error." }
        }
      }
    },
    "/api/token-chart": {
      "get": {
        "summary": "Token price history",
        "description": "Historical market chart (prices, market caps, volumes) for a token by CoinGecko id. Cached ~10 minutes.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "description": "CoinGecko coin id (e.g. bitcoin).",
            "schema": { "type": "string" },
            "example": "bitcoin"
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Number of days of history (default 30). Use 'max' for full history.",
            "schema": { "type": "string" },
            "example": "30"
          },
          {
            "name": "currency",
            "in": "query",
            "required": false,
            "description": "Target fiat currency (default usd).",
            "schema": { "type": "string" },
            "example": "usd"
          }
        ],
        "responses": {
          "200": {
            "description": "Market chart data.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "prices": {
                      "type": "array",
                      "items": {
                        "type": "array",
                        "items": {
                          "oneOf": [{ "type": "number" }, { "type": "string" }]
                        }
                      }
                    },
                    "market_caps": {
                      "type": "array",
                      "items": { "type": "array" }
                    },
                    "total_volumes": {
                      "type": "array",
                      "items": { "type": "array" }
                    }
                  }
                }
              }
            }
          },
          "400": { "description": "Missing id parameter." },
          "502": { "description": "Upstream provider error." }
        }
      }
    },
    "/api/token-news": {
      "get": {
        "summary": "Token news",
        "description": "Latest news headlines for a token symbol (up to 5 items). Cached ~1 hour. If no CryptoCompare API key is configured, returns { news: [], configured: false }.",
        "parameters": [
          {
            "name": "symbol",
            "in": "query",
            "required": true,
            "description": "Token symbol (e.g. BTC, ETH).",
            "schema": { "type": "string" },
            "example": "BTC"
          }
        ],
        "responses": {
          "200": {
            "description": "News items.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "news": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": { "type": "string" },
                          "url": { "type": "string" },
                          "source": { "type": "string" },
                          "publishedOn": { "type": "number" }
                        }
                      }
                    },
                    "configured": { "type": "boolean" }
                  }
                }
              }
            }
          },
          "400": { "description": "Missing symbol parameter." }
        }
      }
    },
    "/api/fiat-rates": {
      "get": {
        "summary": "Fiat exchange rates",
        "description": "Current exchange rate between two fiat currencies (and optional daily history). Source: Frankfurter / ECB. Current rate cached 1h; history cached 6h.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Base currency code (default USD).",
            "schema": { "type": "string" },
            "example": "USD"
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Quote currency code (default EUR).",
            "schema": { "type": "string" },
            "example": "EUR"
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "If >0, include daily history for this many days.",
            "schema": { "type": "integer", "default": 0 },
            "example": 30
          }
        ],
        "responses": {
          "200": {
            "description": "Exchange rate (and optional history).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "rate": { "type": "number" },
                    "inverse": { "type": "number" },
                    "date": { "type": "string" },
                    "history": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "date": { "type": "string" },
                          "rate": { "type": "number" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "502": { "description": "Upstream provider error." }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "Service health",
        "description": "Health check referenced as the status link relation from the API catalog.",
        "responses": {
          "200": {
            "description": "Service is healthy.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "status": { "type": "string" } }
                }
              }
            }
          }
        }
      }
    }
  }
}