{
  "openapi": "3.1.0",
  "info": {
    "title": "DollarTrader — crypto ETF holdings & dollar calculators",
    "version": "1.0.0",
    "description": "REST mirror of the DollarTrader MCP tools. Data is issuer-sourced and weekly; always relay the as_of date. CC BY 4.0 — attribute DollarTrader (dollar-trader.com). Not financial advice.",
    "contact": {
      "url": "https://dollar-trader.com/contact.html"
    },
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://dollartrader-mcp.gp-apps.workers.dev"
    }
  ],
  "paths": {
    "/v1/funds": {
      "get": {
        "summary": "List crypto ETFs in the dataset",
        "description": "List every US-listed crypto ETF / ETP / treasury company in the DollarTrader holdings dataset, optionally filtered by asset. Returns key, ticker, name, issuer, type and the snapshot date. Use the key or ticker with get_etf_holdings.",
        "operationId": "list_funds",
        "parameters": [
          {
            "name": "asset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "BTC",
                "ETH",
                "SOL",
                "XRP",
                "LTC",
                "HYPE"
              ]
            },
            "description": "Filter by underlying asset: BTC, ETH, SOL, XRP, LTC or HYPE. Omit for all."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad input"
          }
        }
      }
    },
    "/v1/funds/{fund}": {
      "get": {
        "summary": "Get coins held and coins per share for one fund",
        "description": "How much Bitcoin/Ethereum/Solana/XRP/Litecoin/HYPE does a given ETF or treasury company hold, and how much per share? Returns the issuer-reported (or clearly flagged derived) figure with its as-of date, shares outstanding, fee, custodian and the exact source URL. Always quote the as_of date when relaying the number.",
        "operationId": "get_etf_holdings",
        "parameters": [
          {
            "name": "fund",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Ticker or key"
          },
          {
            "name": "spot_price_usd",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Optional current price of the underlying asset in USD; if given, the implied NAV per share (coins_per_share × price) is returned."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad input"
          }
        }
      }
    },
    "/v1/history/{fund}": {
      "get": {
        "summary": "Weekly history of coins held / coins per share",
        "description": "Weekly time series of coins_held and coins_per_share for one fund, from the first DollarTrader snapshot to the latest. Use it to see fee decay, staking accretion, splits, and flows. Series length grows by one point per week.",
        "operationId": "get_fund_history",
        "parameters": [
          {
            "name": "fund",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad input"
          }
        }
      }
    },
    "/v1/changes": {
      "get": {
        "summary": "What changed since last week",
        "description": "Week-over-week changes for every fund (coins held and coins per share, % change) with anomaly flags: ratio_move (>15%), holdings_move (>25%), renamed. Good for 'anything unusual in crypto ETFs this week?'.",
        "operationId": "get_changes",
        "parameters": [
          {
            "name": "flagged_only",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Return only rows that carry a flag."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad input"
          }
        }
      }
    },
    "/v1/compare": {
      "get": {
        "summary": "Compare several funds side by side",
        "description": "Side-by-side coins held, coins per share, fee, custodian, staking flag and data quality for 2–8 funds. Pass a spot price to also get implied NAV per share. Treasury companies are included but are not directly comparable to spot ETFs (no fee, equity risk).",
        "operationId": "compare_etfs",
        "parameters": [
          {
            "name": "funds",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "description": "comma-separated"
            },
            "description": "Tickers or keys, e.g. [\"IBIT\",\"FBTC\",\"GBTC\"]"
          },
          {
            "name": "spot_price_usd",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Optional underlying price in USD for implied NAV per share. Only meaningful if all funds share the same asset."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad input"
          }
        }
      }
    },
    "/v1/calc/fee-drag": {
      "get": {
        "summary": "Compound cost of an ETF expense ratio",
        "description": "How much an annual expense ratio costs over time versus a no-fee benchmark, given an investment, an assumed annual return and a horizon. Pass fee_pct directly, or funds (tickers) to use each fund's actual fee from the dataset. Same formula as dollar-trader.com/fee-drag.html.",
        "operationId": "fee_drag",
        "parameters": [
          {
            "name": "investment",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "Starting amount in USD"
          },
          {
            "name": "annual_return_pct",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "Assumed annual return of the underlying, in percent (e.g. 30 for 30%)"
          },
          {
            "name": "years",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Horizon in years"
          },
          {
            "name": "fee_pct",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Annual expense ratio in percent (e.g. 0.25). Ignored if funds is given."
          },
          {
            "name": "funds",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "comma-separated"
            },
            "description": "Compare actual fees of these funds"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad input"
          }
        }
      }
    },
    "/v1/calc/inflation": {
      "get": {
        "summary": "US dollar purchasing power between two years (CPI-U)",
        "description": "Convert a dollar amount between any two years from 1913 to 2024 using BLS CPI-U annual averages. Answers 'what is $X from year A worth in year B' and 'how much purchasing power has been lost'. Same table as dollar-trader.com/inflation-calc.html.",
        "operationId": "inflation_adjust",
        "parameters": [
          {
            "name": "amount",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "Dollar amount"
          },
          {
            "name": "from_year",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Year the amount is denominated in"
          },
          {
            "name": "to_year",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Year to express it in"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad input"
          }
        }
      }
    },
    "/v1/calc/future-purchasing-power": {
      "get": {
        "summary": "Project purchasing power forward at an assumed inflation rate",
        "description": "Given today's amount, a number of years and an assumed average inflation rate, return how much will be needed in the future to match today's purchasing power, and what today's amount will be worth then.",
        "operationId": "future_purchasing_power",
        "parameters": [
          {
            "name": "amount",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "Amount in today's dollars"
          },
          {
            "name": "years",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Years ahead"
          },
          {
            "name": "inflation_pct",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "Assumed average annual inflation in percent (e.g. 3)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad input"
          }
        }
      }
    },
    "/v1/calc/ss-break-even": {
      "get": {
        "summary": "Social Security break-even age (claim early vs. delay)",
        "description": "Compare claiming Social Security at an earlier age vs. a later age. Returns the break-even age with COLA applied, lifetime totals to a chosen life expectancy, and an 'invest the early checks' scenario at an assumed market return — plus an optional surviving-spouse view. Users should take their benefit estimates from ssa.gov/myaccount. Same model as dollar-trader.com/ss-calculator.html. Educational only.",
        "operationId": "ss_break_even",
        "parameters": [
          {
            "name": "early_age",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Earlier claiming age (62–69)"
          },
          {
            "name": "early_monthly",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "Monthly benefit at the earlier age, USD"
          },
          {
            "name": "delayed_age",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Later claiming age (63–70)"
          },
          {
            "name": "delayed_monthly",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "Monthly benefit at the later age, USD"
          },
          {
            "name": "cola_pct",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Annual cost-of-living adjustment in percent. Default 2.5."
          },
          {
            "name": "market_return_pct",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Assumed annual return if early checks are invested, in percent. Default 7."
          },
          {
            "name": "life_expectancy",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Age used for lifetime totals. Default 85."
          },
          {
            "name": "survivor_claim_age",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Optional: age the surviving spouse would claim (60–67) to include a survivor-benefit comparison."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad input"
          }
        }
      }
    }
  },
  "x-mcp": {
    "endpoint": "https://dollartrader-mcp.gp-apps.workers.dev/mcp",
    "transport": "streamable-http"
  }
}