Bullrun

Screen the global Bullrun stock universe with the same rule engine as the app screener. Filter by sector, industry, country/countries, primary vs secondary listings, active vs inactive listings, lookback mode, AND/OR rule groups, comparison operators, money units, growth metrics and latest-value metrics. Returns a compact table of matching stocks. Read-only.

{
  "type": "object",
  "properties": {
    "sector": {
      "type": "string",
      "description": "Exact sector name to filter by, e.g. \"Technology\", \"Healthcare\". Omit for all sectors."
    },
    "industry": {
      "type": "string",
      "description": "Exact industry name to filter by, e.g. \"Software - Infrastructure\". Omit for all industries."
    },
    "country": {
      "type": "string",
      "description": "Exact country name to filter by, e.g. \"United States\", \"Germany\". Omit for all countries."
    },
    "countries": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Exact country names to include. Use this for multi-country screens; it overrides country when provided."
    },
    "lookbackMode": {
      "type": "string",
      "enum": [
        "annual",
        "quarterly"
      ],
      "default": "annual",
      "description": "Whether rule evaluation uses annual or quarterly reporting periods."
    },
    "lookback": {
      "type": "integer",
      "minimum": 1,
      "maximum": 40,
      "default": 3,
      "description": "How many reporting periods to evaluate. Growth rules need at least 2 comparable periods."
    },
    "mode": {
      "type": "string",
      "enum": [
        "annual",
        "quarterly"
      ],
      "description": "Deprecated alias for lookbackMode; kept for compatibility."
    },
    "periods": {
      "type": "integer",
      "minimum": 1,
      "maximum": 40,
      "description": "Deprecated alias for lookback; kept for compatibility."
    },
    "rules": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "metric": {
            "type": "string",
            "enum": [
              "revenueGrowthPct",
              "netIncomeGrowthPct",
              "grossProfitGrowthPct",
              "operatingIncomeGrowthPct",
              "ebitdaGrowthPct",
              "freeCashflowGrowthPct",
              "epsGrowthPct",
              "operatingCashflowGrowthPct",
              "dividendGrowthPct",
              "latestRevenue",
              "latestNetIncome",
              "latestGrossProfit",
              "latestOperatingIncome",
              "latestEbitda",
              "latestDilutedEps",
              "latestDividendsPerShare",
              "latestFreeCashflow",
              "latestOperatingCashflow",
              "latestCash",
              "latestTotalAssets",
              "latestTotalDebt",
              "latestStockholdersEquity",
              "marketCap",
              "peRatio",
              "dividendYield"
            ],
            "description": "Metric to filter on."
          },
          "operator": {
            "type": "string",
            "enum": [
              ">=",
              "<=",
              ">",
              "<",
              "=",
              ".."
            ],
            "default": ">=",
            "description": "Comparison operator. Use '..' for an inclusive between range."
          },
          "value": {
            "type": [
              "string",
              "number"
            ],
            "description": "Threshold value. For money metrics, combine with unit for K/M/B/T scaling."
          },
          "valueMax": {
            "type": [
              "string",
              "number"
            ],
            "description": "Upper bound for '..' range rules. Ignored for other operators."
          },
          "unit": {
            "type": "string",
            "enum": [
              "",
              "K",
              "M",
              "B",
              "T"
            ],
            "default": "",
            "description": "Optional money unit for money metrics: '', K, M, B or T."
          },
          "groupId": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "description": "Rules with the same groupId are ANDed; different groups are ORed."
          }
        },
        "required": [
          "metric"
        ],
        "additionalProperties": false
      },
      "default": [],
      "description": "Fundamental rules. Same groupId means AND; different groupIds mean OR."
    },
    "minMarketCap": {
      "type": "number",
      "minimum": 0,
      "description": "Compatibility shortcut: adds marketCap >= this absolute value to every rule group."
    },
    "includeSecondary": {
      "type": "boolean",
      "default": false,
      "description": "Include secondary cross-listings of the same security. Default false (primary listings only)."
    },
    "includeInactive": {
      "type": "boolean",
      "default": false,
      "description": "Include delisted/inactive tickers with no recent price bar. Default false."
    },
    "sortBy": {
      "type": "string",
      "enum": [
        "revenueGrowthPct",
        "netIncomeGrowthPct",
        "grossProfitGrowthPct",
        "operatingIncomeGrowthPct",
        "ebitdaGrowthPct",
        "freeCashflowGrowthPct",
        "epsGrowthPct",
        "operatingCashflowGrowthPct",
        "dividendGrowthPct",
        "latestRevenue",
        "latestNetIncome",
        "latestGrossProfit",
        "latestOperatingIncome",
        "latestEbitda",
        "latestDilutedEps",
        "latestDividendsPerShare",
        "latestFreeCashflow",
        "latestOperatingCashflow",
        "latestCash",
        "latestTotalAssets",
        "latestTotalDebt",
        "latestStockholdersEquity",
        "marketCap",
        "peRatio",
        "dividendYield",
        "revenueGrowth"
      ],
      "default": "marketCap",
      "description": "Metric to sort by. revenueGrowth is accepted as an alias for revenueGrowthPct."
    },
    "order": {
      "type": "string",
      "enum": [
        "desc",
        "asc"
      ],
      "default": "desc",
      "description": "Sort direction. Nulls always sort last regardless of direction."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25,
      "description": "Maximum number of stocks to return (1-100)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Look up ETFs by name, ticker or ISIN, with classification, listing, index, distribution-policy, AUM, expense-ratio and yield filters. Best for finding a known fund. For ranking questions ("cheapest", "largest", "best performing", "most liquid") prefer screen_etfs, which evaluates the whole universe: here minAum and minYieldTtmPct are applied only to a bounded profile-enriched candidate scan, so do not describe the result as exhaustive when candidateCapReached is true. Use get_etf_snapshot for one listing, get_etf_fund to resolve an ISIN across venues, and get_etf_holdings for constituents. Read-only.

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "description": "Free-text ETF search by ticker, fund name, or ISIN (e.g. IE00B4L5Y983). Omit for a broad screen."
    },
    "category": {
      "type": "string",
      "description": "Exact broad ETF category/asset-class filter, e.g. Equity, Fixed Income, Commodity, Crypto, or Real Estate. Call get_etf_filter_options for valid values."
    },
    "focus": {
      "type": "string",
      "description": "Exact ETF focus/exposure filter, e.g. Japan, TOPIX, or Equity - Australia."
    },
    "region": {
      "type": "string",
      "description": "Exact portfolio or investment-region filter."
    },
    "domicile": {
      "type": "string",
      "description": "Exact fund domicile filter."
    },
    "exchange": {
      "type": "string",
      "description": "Exact listing exchange filter."
    },
    "currency": {
      "type": "string",
      "description": "Exact trading-currency filter."
    },
    "indexKey": {
      "type": "string",
      "description": "Exact tracked-index key, e.g. SP500 or MSCI_WORLD. Use get_etf_index_group to rank every fund on one index by cost."
    },
    "distributionPolicy": {
      "type": "string",
      "enum": [
        "ACCUMULATING",
        "DISTRIBUTING"
      ],
      "description": "Accumulating (reinvests income) or distributing (pays it out)."
    },
    "minAum": {
      "type": "number",
      "minimum": 0,
      "description": "Minimum assets under management in the profile's reported currency units."
    },
    "maxExpenseRatioPct": {
      "type": "number",
      "minimum": 0,
      "description": "Maximum annual expense ratio in percentage points, e.g. 0.25 means 0.25%."
    },
    "minYieldTtmPct": {
      "type": "number",
      "minimum": 0,
      "description": "Minimum trailing yield in percentage points, e.g. 2 means 2%."
    },
    "sortBy": {
      "type": "string",
      "enum": [
        "relevance",
        "ticker",
        "name",
        "aum",
        "expense_ratio",
        "yield"
      ],
      "default": "relevance",
      "description": "Sort field. Relevance preserves Bullrun search ordering."
    },
    "sortDirection": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "default": "desc"
    },
    "includeSecondary": {
      "type": "boolean",
      "default": false
    },
    "includeInactive": {
      "type": "boolean",
      "default": false
    },
    "scanLimit": {
      "type": "integer",
      "minimum": 25,
      "maximum": 500,
      "default": 100,
      "description": "Maximum coarse-search candidates to enrich before applying quantitative filters/sorts, 25-500."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25,
      "description": "Maximum matching ETFs to return, 1-100."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "object",
      "additionalProperties": {}
    },
    "coverage": {
      "type": "object",
      "additionalProperties": {}
    },
    "matchesInScannedCandidates": {
      "type": "integer",
      "minimum": 0
    },
    "returned": {
      "type": "integer",
      "minimum": 0
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": {}
      }
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "query",
    "coverage",
    "matchesInScannedCandidates",
    "returned",
    "results",
    "warnings"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Screen the WHOLE ETF universe by numeric rules and fund attributes in one pass — expense ratio, AUM, yield, trailing returns, volatility, liquidity, top-10 concentration, fund age and holdings count — combined with issuer, index, domicile, UCITS status, distribution policy, currency hedging and constituent look-through (holdingSearch finds funds by what they hold). Prefer this over search_etfs for any "cheapest / largest / best performing / most liquid" question: search_etfs only filters a bounded candidate scan, while this evaluates the full universe and reports evaluatedCount and matchCount. Percentages are percentage points. This is the heaviest read in the API and is metered against a small per-day action budget, so build one well-specified screen rather than probing repeatedly. Read-only.

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "description": "Free-text match on ticker, fund name or ISIN. Omit to screen the whole universe."
    },
    "assetClass": {
      "type": "string",
      "description": "Exact asset-class group: EQUITY, FIXED_INCOME, COMMODITY, REAL_ESTATE, MULTI_ASSET, CASH, CURRENCY, DIGITAL_ASSETS, ALTERNATIVES or OTHER."
    },
    "category": {
      "type": "string",
      "description": "Exact category string. Call get_etf_filter_options for the valid values; a wrong guess silently returns zero rows."
    },
    "domicile": {
      "type": "string",
      "description": "Exact fund domicile, e.g. \"Ireland\", \"Luxembourg\", \"United States\"."
    },
    "region": {
      "type": "string",
      "description": "Exact investment-region string."
    },
    "exchange": {
      "type": "string",
      "description": "Exact listing exchange, e.g. XETRA, LSE, \"NYSE ARCA\"."
    },
    "currency": {
      "type": "string",
      "description": "Exact trading currency, e.g. EUR, USD, GBX."
    },
    "indexKey": {
      "type": "string",
      "description": "Exact tracked-index key, e.g. SP500, MSCI_WORLD, NASDAQ100. Use get_etf_index_group to compare every fund on one index instead."
    },
    "distributionPolicy": {
      "type": "string",
      "enum": [
        "ACCUMULATING",
        "DISTRIBUTING"
      ],
      "description": "Accumulating (reinvests income) or distributing (pays it out) — the usual first cut for a European investor."
    },
    "productType": {
      "type": "string",
      "description": "Exact wrapper type, e.g. UCITS_FUND."
    },
    "ucitsStatus": {
      "type": "string",
      "enum": [
        "UCITS",
        "NON_UCITS"
      ],
      "description": "UCITS restricts to wrappers a European retail investor can actually buy."
    },
    "issuer": {
      "type": "string",
      "description": "Substring match on the fund family/issuer, e.g. \"iShares\", \"Amundi\", \"Vanguard\"."
    },
    "strategy": {
      "type": "string",
      "description": "Exact strategy classification string."
    },
    "benchmarkSearch": {
      "type": "string",
      "description": "Substring match on the stated benchmark name."
    },
    "marketDevelopment": {
      "type": "string",
      "description": "Exact market-development classification, e.g. developed vs emerging."
    },
    "currencyHedged": {
      "type": "string",
      "enum": [
        "HEDGED",
        "NOT_LABELLED_HEDGED"
      ],
      "description": "HEDGED selects funds labelled currency-hedged. NOT_LABELLED_HEDGED selects funds not so labelled — absence of a label is not proof a fund is unhedged."
    },
    "holdingSearch": {
      "type": "string",
      "description": "Look-through filter: find funds by a CONSTITUENT ticker or company name, e.g. \"NVDA\" or \"NVIDIA\". Only funds with a stored holdings snapshot can match."
    },
    "holdingMode": {
      "type": "string",
      "enum": [
        "INCLUDES",
        "EXCLUDES"
      ],
      "default": "INCLUDES",
      "description": "INCLUDES keeps funds holding the constituent. EXCLUDES keeps only funds with a holdings snapshot that confirms absence — funds with no snapshot are dropped, never assumed clean."
    },
    "holdingMinWeightPct": {
      "type": "number",
      "minimum": 0,
      "maximum": 100,
      "description": "Minimum constituent weight in percentage points for holdingSearch to count as a match."
    },
    "rules": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "metric": {
            "type": "string",
            "enum": [
              "expenseRatioPct",
              "totalAssets",
              "yieldTtmPct",
              "holdingsCount",
              "fundAgeYears",
              "inceptionYear",
              "nav",
              "return1mPct",
              "return3mPct",
              "return6mPct",
              "return1yPct",
              "returnYtdPct",
              "volatility1yPct",
              "avgVolume90d",
              "avgTurnover90d",
              "top10ConcentrationPct"
            ],
            "description": "Numeric metric to filter on."
          },
          "operator": {
            "type": "string",
            "enum": [
              ">=",
              "<=",
              ">",
              "<",
              "=",
              ".."
            ],
            "default": ">=",
            "description": "Comparison operator. Use '..' for an inclusive between range with valueMax."
          },
          "value": {
            "type": [
              "string",
              "number"
            ],
            "description": "Threshold. For money metrics combine with unit for K/M/B/T scaling."
          },
          "valueMax": {
            "type": [
              "string",
              "number"
            ],
            "description": "Upper bound for '..' range rules. Ignored for other operators."
          },
          "unit": {
            "type": "string",
            "enum": [
              "",
              "K",
              "M",
              "B",
              "T"
            ],
            "default": "",
            "description": "Optional money unit for money metrics: '', K, M, B or T."
          },
          "groupId": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "description": "Rules with the same groupId are ANDed; different groups are ORed."
          }
        },
        "required": [
          "metric"
        ],
        "additionalProperties": false
      },
      "default": [],
      "description": "Numeric rules. A fund with no value for a ruled metric never matches that rule."
    },
    "includeSecondary": {
      "type": "boolean",
      "default": false,
      "description": "Include secondary venue listings of the same fund. Default false — one row per fund's primary listing."
    },
    "sortBy": {
      "type": "string",
      "enum": [
        "expenseRatioPct",
        "totalAssets",
        "yieldTtmPct",
        "return1mPct",
        "return3mPct",
        "return6mPct",
        "return1yPct",
        "returnYtdPct",
        "volatility1yPct",
        "avgVolume90d",
        "avgTurnover90d",
        "top10ConcentrationPct",
        "holdingsCount",
        "nav",
        "ticker",
        "name"
      ],
      "default": "totalAssets",
      "description": "Sort field applied to the returned rows."
    },
    "order": {
      "type": "string",
      "enum": [
        "desc",
        "asc"
      ],
      "default": "desc",
      "description": "Sort direction. Nulls always sort last regardless of direction."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25,
      "description": "Maximum ETFs to return, 1-100."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "object",
      "additionalProperties": {}
    },
    "coverage": {
      "type": "object",
      "additionalProperties": {}
    },
    "matchCount": {
      "type": "integer",
      "minimum": 0
    },
    "returned": {
      "type": "integer",
      "minimum": 0
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": {}
      }
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "query",
    "coverage",
    "matchCount",
    "returned",
    "results",
    "warnings"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Answer "what is the cheapest way to track <index>?". Returns every fund tracking one index ordered cheapest fee first, deduplicated to one row per FUND rather than per venue listing (a five-venue UCITS fund is one choice, not five) with its listingCount and venues. Defaults to UCITS-buyable domiciles. Omit indexKey to list the available index families. Fees are percentage points and the response states how many funds publish no fee at all, so a "cheapest" claim is never made over silently omitted funds. Read-only.

{
  "type": "object",
  "properties": {
    "indexKey": {
      "type": "string",
      "description": "Normalized index key, e.g. SP500, MSCI_WORLD, NASDAQ100, MSCI_EM, EURO_STOXX_50, TOPIX, FTSE100. Omit to list every index family that has at least one fund."
    },
    "scope": {
      "type": "string",
      "enum": [
        "ucits",
        "all"
      ],
      "default": "ucits",
      "description": "ucits (default) restricts to domiciles a European retail investor can actually buy. all adds US-domiciled trackers, which look cheaper but are not purchasable by EU retail."
    },
    "distributionPolicy": {
      "type": "string",
      "enum": [
        "ACCUMULATING",
        "DISTRIBUTING"
      ],
      "description": "Optionally keep only accumulating or only distributing share classes."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25,
      "description": "Maximum funds (or index families) to return, 1-100."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "index_group",
        "index_list"
      ]
    },
    "indexKey": {
      "type": [
        "string",
        "null"
      ]
    },
    "scope": {
      "type": "string"
    },
    "found": {
      "type": "boolean"
    },
    "coverage": {
      "type": "object",
      "additionalProperties": {}
    },
    "funds": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": {}
      }
    },
    "indexFamilies": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": {}
      }
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "mode",
    "indexKey",
    "scope",
    "found",
    "coverage",
    "funds",
    "indexFamilies",
    "warnings"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Resolve one FUND rather than one listing. Given an ISIN (or any venue ticker of the fund) it returns the fund's identity, costs, index, distribution policy, wrapper type and every venue it is listed on with exchange and trading currency. Use this when the user quotes an ISIN, asks "which ticker do I buy on my exchange?", or when several tickers may be the same underlying fund. Ratios are percentage points. Read-only.

{
  "type": "object",
  "properties": {
    "isin": {
      "type": "string",
      "description": "Fund ISIN, e.g. IE00B4L5Y983. The identifier European factsheets and brokers quote."
    },
    "ticker": {
      "type": "string",
      "description": "Any venue listing ticker of the fund, e.g. EUNL.DE or IWDA.L. Resolved to its fund ISIN first. Provide this or isin."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "object",
      "additionalProperties": {}
    },
    "found": {
      "type": "boolean"
    },
    "fund": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ]
    },
    "listings": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": {}
      }
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "query",
    "found",
    "fund",
    "listings",
    "warnings"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List the exact values accepted by the categorical filters on search_etfs and screen_etfs — asset classes, categories, index keys, product/wrapper types, regions, domiciles, currencies, exchanges, and (on request) issuers and focus strings. Those filters match exactly, so a guessed string returns zero rows and looks like "no such ETF exists"; call this first whenever a filter value is not already known to be valid. Read-only.

{
  "type": "object",
  "properties": {
    "facets": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "assetClasses",
          "categories",
          "indexKeys",
          "productTypes",
          "regions",
          "domiciles",
          "currencies",
          "exchanges",
          "sectors",
          "fundFamilies",
          "industries"
        ]
      },
      "minItems": 1,
      "description": "Which facets to return. Defaults to everything except the long tails fundFamilies (~890 issuers) and industries (~650 focus strings) — request those explicitly, ideally with search."
    },
    "search": {
      "type": "string",
      "description": "Case-insensitive substring filter applied to every requested facet, e.g. \"ishares\" against fundFamilies or \"world\" against categories."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000,
      "default": 100,
      "description": "Maximum values per facet, 1-1000. Each facet reports its untruncated total."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "facets": {
      "type": "object",
      "additionalProperties": {}
    },
    "totals": {
      "type": "object",
      "additionalProperties": {
        "type": "number"
      }
    },
    "truncatedFacets": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "search": {
      "type": [
        "string",
        "null"
      ]
    },
    "notes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "facets",
    "totals",
    "truncatedFacets",
    "search",
    "notes"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch a modular snapshot for one exact ETF listing. The include array controls which of identity, classification, market, fund_data (NAV/AUM), costs, income, and benchmark are fetched and returned. Unrequested modules are omitted; requested-but-unavailable modules are named explicitly. Ratios use percentage points. Read-only.

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "description": "Exact Bullrun ETF listing ticker, including its exchange suffix when present, e.g. SPY, VWRL.L, or EUNL.DE."
    },
    "include": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "identity",
          "classification",
          "market",
          "fund_data",
          "costs",
          "income",
          "benchmark"
        ]
      },
      "minItems": 1,
      "maxItems": 7,
      "default": [
        "identity",
        "classification",
        "market",
        "costs"
      ],
      "description": "Only these snapshot modules are fetched and returned. Default: identity, classification, market, costs."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string"
    },
    "found": {
      "type": "boolean"
    },
    "requestedModules": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "identity",
          "classification",
          "market",
          "fund_data",
          "costs",
          "income",
          "benchmark"
        ]
      }
    },
    "availableModules": {
      "type": "array",
      "items": {
        "$ref": "#/properties/requestedModules/items"
      }
    },
    "missingModules": {
      "type": "array",
      "items": {
        "$ref": "#/properties/requestedModules/items"
      }
    },
    "modules": {
      "type": "object",
      "additionalProperties": {}
    },
    "asOf": {
      "type": "object",
      "additionalProperties": {}
    },
    "dataQuality": {
      "type": "object",
      "additionalProperties": {}
    }
  },
  "required": [
    "ticker",
    "found",
    "requestedModules",
    "availableModules",
    "missingModules",
    "modules",
    "asOf",
    "dataQuality"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Return the latest stored ETF holdings snapshot with opaque cursor pagination. The response reports the provider's stated holdings count, stored row count, covered weight, and whether the stored rows appear complete. Treat isComplete=false or null as partial look-through data. Historical as-of selection will be added when the upstream API exposes it. Read-only.

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "description": "Exact Bullrun ETF listing ticker, including its exchange suffix when present."
    },
    "cursor": {
      "type": "string",
      "description": "Opaque nextCursor returned by a previous get_etf_holdings call for the same ticker."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25,
      "description": "Maximum holdings to return on this page, 1-100."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string"
    },
    "asOfDate": {
      "type": [
        "string",
        "null"
      ]
    },
    "returned": {
      "type": "integer",
      "minimum": 0
    },
    "totalRowsAvailable": {
      "type": "integer",
      "minimum": 0
    },
    "nextCursor": {
      "type": [
        "string",
        "null"
      ]
    },
    "coverage": {
      "type": "object",
      "additionalProperties": {}
    },
    "holdings": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": {}
      }
    }
  },
  "required": [
    "ticker",
    "asOfDate",
    "returned",
    "totalRowsAvailable",
    "nextCursor",
    "coverage",
    "holdings"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch ETF price or price-return history at daily, weekly, or monthly intervals. NAV, true total-return, benchmark, and premium/discount series are returned only when their required source data or an explicit benchmark ticker exists; unavailable requested series are named explicitly and never approximated with price returns. Read-only.

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "description": "Exact Bullrun ETF listing ticker."
    },
    "series": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "price",
          "price_return",
          "nav",
          "total_return",
          "benchmark",
          "premium_discount"
        ]
      },
      "minItems": 1,
      "maxItems": 6,
      "default": [
        "price"
      ],
      "description": "Requested series. Unsupported stored series are reported in unavailableSeries rather than synthesized."
    },
    "benchmarkTicker": {
      "type": "string",
      "minLength": 1,
      "description": "Exact priced ticker to use when benchmark is requested. A benchmark name alone cannot resolve a price series safely."
    },
    "interval": {
      "type": "string",
      "enum": [
        "daily",
        "weekly",
        "monthly"
      ],
      "default": "daily"
    },
    "startDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "endDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1300,
      "default": 260,
      "description": "Maximum recent daily source bars to load before date filtering and interval aggregation."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string"
    },
    "requestedSeries": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "price",
          "price_return",
          "nav",
          "total_return",
          "benchmark",
          "premium_discount"
        ]
      }
    },
    "availableSeries": {
      "type": "array",
      "items": {
        "$ref": "#/properties/requestedSeries/items"
      }
    },
    "unavailableSeries": {
      "type": "array",
      "items": {
        "$ref": "#/properties/requestedSeries/items"
      }
    },
    "interval": {
      "type": "string",
      "enum": [
        "daily",
        "weekly",
        "monthly"
      ]
    },
    "series": {
      "type": "object",
      "additionalProperties": {}
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {}
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "ticker",
    "requestedSeries",
    "availableSeries",
    "unavailableSeries",
    "interval",
    "series",
    "metadata",
    "warnings"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Calculate sector, country, currency, and broad asset exposure from the latest stored ETF holdings and Bullrun instrument mappings. Factor and thematic look-through are reported unavailable until dedicated source data exists. Coverage states how much fund weight and how many holding symbols were resolved, so partial top-holdings data is never presented as full exposure. Read-only.

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "description": "Exact Bullrun ETF listing ticker."
    },
    "types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "sector",
          "country",
          "currency",
          "asset",
          "factor",
          "thematic"
        ]
      },
      "minItems": 1,
      "maxItems": 6,
      "default": [
        "sector",
        "country",
        "currency",
        "asset"
      ]
    },
    "limitPerType": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string"
    },
    "requestedTypes": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "sector",
          "country",
          "currency",
          "asset",
          "factor",
          "thematic"
        ]
      }
    },
    "availableTypes": {
      "type": "array",
      "items": {
        "$ref": "#/properties/requestedTypes/items"
      }
    },
    "unavailableTypes": {
      "type": "array",
      "items": {
        "$ref": "#/properties/requestedTypes/items"
      }
    },
    "exposures": {
      "type": "object",
      "additionalProperties": {}
    },
    "coverage": {
      "type": "object",
      "additionalProperties": {}
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "ticker",
    "requestedTypes",
    "availableTypes",
    "unavailableTypes",
    "exposures",
    "coverage",
    "warnings"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Calculate drawdown, annualized volatility, downside volatility, historical VaR, Sharpe, Sortino and Calmar ratios from stored daily close prices. With benchmarkTicker, also calculates beta, correlation, tracking error, active return and information ratio on aligned dates. Results are price-return risk, not distribution-adjusted total-return risk. Read-only.

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "description": "Exact Bullrun ETF listing ticker."
    },
    "days": {
      "type": "integer",
      "minimum": 30,
      "maximum": 1825,
      "default": 370,
      "description": "Calendar-day lookback for daily close-price risk calculations."
    },
    "benchmarkTicker": {
      "type": "string",
      "minLength": 1,
      "description": "Optional exact priced benchmark/proxy ticker for beta, correlation, tracking error, active return, and information ratio."
    },
    "riskFreeRatePct": {
      "type": "number",
      "minimum": -10,
      "maximum": 30,
      "default": 0,
      "description": "Annual risk-free rate in percentage points for Sharpe, Sortino, and Calmar ratios."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string"
    },
    "lookbackDays": {
      "type": "integer"
    },
    "methodology": {
      "type": "object",
      "additionalProperties": {}
    },
    "coverage": {
      "type": "object",
      "additionalProperties": {}
    },
    "risk": {
      "type": "object",
      "additionalProperties": {}
    },
    "benchmarkRelative": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ]
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "ticker",
    "lookbackDays",
    "methodology",
    "coverage",
    "risk",
    "benchmarkRelative",
    "warnings"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Return a normalized side-by-side comparison of two to ten ETFs across selected classification, market, fund-data, cost, income, benchmark, price-performance, price-risk, and holdings modules. Leaders are mechanical extrema, not recommendations. Currency and partial-holdings caveats are explicit. Read-only.

{
  "type": "object",
  "properties": {
    "tickers": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "minItems": 2,
      "maxItems": 10,
      "description": "Two to ten exact Bullrun ETF listing tickers."
    },
    "include": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "classification",
          "market",
          "fund_data",
          "costs",
          "income",
          "benchmark",
          "performance",
          "risk",
          "holdings"
        ]
      },
      "minItems": 1,
      "maxItems": 9,
      "default": [
        "classification",
        "market",
        "fund_data",
        "costs",
        "income",
        "benchmark"
      ]
    },
    "performanceDays": {
      "type": "integer",
      "minimum": 30,
      "maximum": 1825,
      "default": 370
    }
  },
  "required": [
    "tickers"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "tickers": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "requestedModules": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "classification",
          "market",
          "fund_data",
          "costs",
          "income",
          "benchmark",
          "performance",
          "risk",
          "holdings"
        ]
      }
    },
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": {}
      }
    },
    "leaders": {
      "type": "object",
      "additionalProperties": {}
    },
    "coverage": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": {}
      }
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "tickers",
    "requestedModules",
    "rows",
    "leaders",
    "coverage",
    "warnings"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Compare two to ten ETFs using their latest stored holdings. Returns pairwise shared holdings, weighted overlap (sum of the smaller weight for each shared holding), each fund's weight in shared names, and the largest duplicate exposures. Coverage is explicit because provider holdings may be partial top-holdings samples. Read-only.

{
  "type": "object",
  "properties": {
    "tickers": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "minItems": 2,
      "maxItems": 10,
      "description": "Two to ten exact Bullrun ETF listing tickers."
    },
    "topSharedLimit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    }
  },
  "required": [
    "tickers"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "tickers": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "methodology": {
      "type": "object",
      "additionalProperties": {}
    },
    "coverage": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": {}
      }
    },
    "pairs": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": {}
      }
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "tickers",
    "methodology",
    "coverage",
    "pairs",
    "warnings"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Analyze an ETF candidate against one signed-in user's portfolio. Combines Bullrun's price-history candidate fit (correlation, beta and pro-forma volatility) with latest-holdings look-through that identifies direct and ETF-contained duplicate underlying positions. Coverage is explicit and partial provider holdings make duplicate exposure a lower bound. Requires OAuth read:portfolios. Read-only.

{
  "type": "object",
  "properties": {
    "portfolioId": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "description": "Portfolio id returned by list_portfolios."
    },
    "candidateTicker": {
      "type": "string",
      "minLength": 1,
      "description": "Exact Bullrun ETF listing ticker to test."
    },
    "candidateWeightPct": {
      "type": "number",
      "minimum": 0.1,
      "maximum": 50,
      "default": 5
    },
    "days": {
      "type": "integer",
      "minimum": 30,
      "maximum": 1825,
      "default": 370
    },
    "includeLookThrough": {
      "type": "boolean",
      "default": true
    }
  },
  "required": [
    "portfolioId",
    "candidateTicker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "portfolioId": {
      "type": "integer"
    },
    "candidateTicker": {
      "type": "string"
    },
    "candidateWeightPct": {
      "type": "number"
    },
    "priceRiskFit": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ]
    },
    "lookThroughFit": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ]
    },
    "coverage": {
      "type": "object",
      "additionalProperties": {}
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "portfolioId",
    "candidateTicker",
    "candidateWeightPct",
    "priceRiskFit",
    "lookThroughFit",
    "coverage",
    "warnings"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Simulate expense-ratio, assumed bid/ask spread, commissions, and recurring contributions over a holding period. Compares the same gross-return path with and without costs and reports direct charges plus ending-value drag. Taxes, FX, market impact and brokerage-specific fees are excluded unless represented by the inputs. Read-only.

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "description": "Exact Bullrun ETF listing ticker."
    },
    "initialInvestment": {
      "type": "number",
      "minimum": 0,
      "default": 10000
    },
    "contributionAmount": {
      "type": "number",
      "minimum": 0,
      "default": 0
    },
    "contributionFrequency": {
      "type": "string",
      "enum": [
        "none",
        "monthly",
        "quarterly",
        "annual"
      ],
      "default": "monthly"
    },
    "years": {
      "type": "number",
      "minimum": 0.25,
      "maximum": 50,
      "default": 10
    },
    "grossAnnualReturnPct": {
      "type": "number",
      "minimum": -99,
      "maximum": 100,
      "default": 0,
      "description": "Assumed annual return before ETF and trading costs, in percentage points. Default 0 isolates direct costs."
    },
    "expenseRatioPct": {
      "type": "number",
      "minimum": 0,
      "maximum": 20,
      "description": "Optional expense-ratio override in percentage points. Otherwise uses the stored ETF profile value."
    },
    "spreadPct": {
      "type": "number",
      "minimum": 0,
      "maximum": 20,
      "default": 0,
      "description": "Assumed full bid/ask spread in percentage points; each purchase pays half the spread."
    },
    "commissionPerTrade": {
      "type": "number",
      "minimum": 0,
      "default": 0
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string"
    },
    "assumptions": {
      "type": "object",
      "additionalProperties": {}
    },
    "results": {
      "type": "object",
      "additionalProperties": {}
    },
    "costBreakdown": {
      "type": "object",
      "additionalProperties": {}
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "ticker",
    "assumptions",
    "results",
    "costBreakdown",
    "warnings"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Compatibility tool for older clients: search the Bullrun ETF universe and optionally bundle profile, recent prices, and latest holdings for an exact ticker. New clients should use search_etfs, get_etf_snapshot, and get_etf_holdings for smaller responses, structured output, quantitative filters, and explicit coverage metadata. Read-only.

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "description": "Free-text ETF search by ticker or fund name. Omit to list the first ETFs."
    },
    "ticker": {
      "type": "string",
      "description": "Exact ETF ticker for profile, prices, and optional holdings, e.g. SPY, VWRL.L, EUNL.DE."
    },
    "category": {
      "type": "string",
      "description": "Exact broad ETF asset-class filter, such as Equity, Fixed Income, Commodity, Crypto, or Real Estate. Kept as category for API compatibility."
    },
    "focus": {
      "type": "string",
      "description": "Exact ETF exposure filter, such as Japan, Equity - Australia, TOPIX, or an exchange/source exposure label. Kept as focus for API compatibility."
    },
    "domicile": {
      "type": "string",
      "description": "Exact ETF domicile filter."
    },
    "exchange": {
      "type": "string",
      "description": "Exact exchange filter, e.g. NYSE ARCA, LSE, XETRA."
    },
    "currency": {
      "type": "string",
      "description": "Exact trading currency filter, e.g. USD, EUR, CHF."
    },
    "includeSecondary": {
      "type": "boolean",
      "default": false,
      "description": "Include secondary/cross-listed ETF tickers. Default false."
    },
    "includeInactive": {
      "type": "boolean",
      "default": false,
      "description": "Include ETFs with no recent price bar. Default false."
    },
    "includeHoldings": {
      "type": "boolean",
      "default": true,
      "description": "When ticker is supplied, include latest holdings. Ignored for broad searches."
    },
    "holdingsLimit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25,
      "description": "Maximum holdings to return for an exact ticker, 1-100."
    },
    "priceLimit": {
      "type": "integer",
      "minimum": 0,
      "maximum": 250,
      "default": 1,
      "description": "Recent daily price rows to return for an exact ticker. Use 0 to skip prices."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25,
      "description": "Maximum ETF search rows to return, 1-100."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch a consolidated metrics snapshot for a single stock by ticker: identity (company, exchange, currency, sector, industry, country, ISIN), latest daily price (OHLCV), latest valuation (market cap, P/E, dividend yield, annual dividend per share), the most recent reported financials (revenue, gross/operating income, EBITDA, net income, diluted EPS, free & operating cash flow, total debt, cash, total assets, equity) and a short company description. Use the exact ticker as listed on Bullrun - the native local-exchange symbol (e.g. AAPL, BMW, ABBN, NESN, or a numeric code like 005930), NOT Yahoo-style country suffixes like BMW.DE or ABBN.SW. If a ticker returns no data, use screen_stocks (by sector/country) to find the exact symbol. Read-only.

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "description": "The stock ticker exactly as listed on Bullrun - the native local-exchange symbol, e.g. \"AAPL\", \"BMW\" (not \"BMW.DE\"), \"ABBN\" (not \"ABBN.SW\"), \"NESN\", or a numeric code like \"005930\". Do not append Yahoo-style country suffixes."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch 1-15 years of historical financial statements for one exact Bullrun ticker. Returns annual and/or quarterly rows grouped into income statement, balance sheet, cash flow, per-share metrics, margins, source currency, and annual growth/CAGR consistency checks. Use this when evaluating multi-year revenue/net-income growth, margin trajectories, leverage, cash flow quality, or whether a stock passed a rule such as 10% revenue and net-income growth every year.

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "description": "The ticker exactly as listed on Bullrun - the native local-exchange symbol, e.g. \"AAPL\", \"BMW\" (not \"BMW.DE\"), \"ABBN\" (not \"ABBN.SW\"), \"NESN\", or a numeric code like \"005930\". Do not append Yahoo-style country suffixes; if a lookup returns nothing, use screen_stocks to find the exact symbol."
    },
    "periodType": {
      "type": "string",
      "enum": [
        "annual",
        "quarterly",
        "both"
      ],
      "default": "both",
      "description": "Return annual rows, quarterly rows, or both. Annual rows use fiscalQuarter=0."
    },
    "years": {
      "type": "integer",
      "minimum": 1,
      "maximum": 15,
      "default": 10,
      "description": "How many fiscal years of history to return, counting backward from the latest fiscal year available."
    },
    "includeEmptyRows": {
      "type": "boolean",
      "default": false,
      "description": "Include sparse rows that have no major income statement, balance sheet, cash-flow, or EPS values."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Compute annual quality, moat, earnings-quality, and capital-allocation metrics for one exact Bullrun ticker from existing financial statements: ROIC, ROE/ROA, ROIC-vs-supplied-WACC, accruals, cash conversion, capex intensity, dividend payout/growth, diluted share-count changes, and a buyback proxy. Read-only.

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "description": "The ticker exactly as listed on Bullrun - the native local-exchange symbol, e.g. \"AAPL\", \"BMW\" (not \"BMW.DE\"), \"ABBN\" (not \"ABBN.SW\"), \"NESN\", or a numeric code like \"005930\". Do not append Yahoo-style country suffixes; if a lookup returns nothing, use screen_stocks to find the exact symbol."
    },
    "years": {
      "type": "integer",
      "minimum": 2,
      "maximum": 15,
      "default": 10,
      "description": "How many fiscal years of annual history to evaluate."
    },
    "estimatedWaccPct": {
      "type": "number",
      "minimum": 0,
      "maximum": 50,
      "description": "Optional user-supplied WACC assumption, in percent. When omitted, ROIC-vs-WACC spread is returned as null."
    },
    "taxRateFallbackPct": {
      "type": "number",
      "minimum": 0,
      "maximum": 50,
      "default": 21,
      "description": "Fallback tax rate used for NOPAT only when reported tax/pretax data is missing or unusable."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch forward consensus revenue/EPS/EBITDA estimates, management guidance ranges, and estimate-revision percentages for one exact Bullrun ticker. Also derives simple forward P/E and PEG-style context from the latest close when EPS estimates are available. Read-only.

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "description": "The ticker exactly as listed on Bullrun, e.g. \"AAPL\", \"CRWD\", \"SPGI\"."
    },
    "periodType": {
      "type": "string",
      "enum": [
        "annual",
        "quarterly",
        "both"
      ],
      "default": "both",
      "description": "Return annual estimates, quarterly estimates, or both."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 80,
      "description": "Maximum estimate rows to return."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch period-specific operating KPIs and unit-economics metrics for one exact Bullrun ticker: ARR, net revenue retention, RPO, billings, customer counts, payments volume, cross-border volume, processed transactions, or other domain-specific metrics when populated. Read-only.

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "description": "The ticker exactly as listed on Bullrun, e.g. \"CRWD\", \"SNOW\", \"V\"."
    },
    "metricKey": {
      "type": "string",
      "description": "Optional exact metric key to filter, e.g. ARR, NRR, RPO, BILLINGS, PAYMENT_VOLUME."
    },
    "category": {
      "type": "string",
      "description": "Optional category filter such as SaaS, payments, marketplace, banking, or other domain labels."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 300,
      "default": 120,
      "description": "Maximum KPI rows to return."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch segment, geography, product, customer, or other revenue breakdown rows for one exact Bullrun ticker. Use this to separate cyclical businesses from recurring segments or inspect geographic exposure instead of relying on blended revenue. Read-only.

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "description": "The ticker exactly as listed on Bullrun, e.g. \"SPGI\", \"MSFT\", \"V\"."
    },
    "dimension": {
      "type": "string",
      "enum": [
        "segment",
        "geography",
        "product",
        "customer",
        "other",
        "all"
      ],
      "default": "all",
      "description": "Breakdown dimension to return, or all dimensions."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 300,
      "default": 160,
      "description": "Maximum breakdown rows to return."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch speaker-tagged earnings-call transcript chunks for one exact Bullrun ticker, optionally filtered by fiscal period or search text. Use this for management guidance language, analyst Q&A, and qualitative judgment that is not visible in financial statements. Read-only.

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "description": "The ticker exactly as listed on Bullrun, e.g. \"CRWD\", \"SPGI\", \"V\"."
    },
    "fiscalYear": {
      "type": "integer",
      "minimum": 1900,
      "maximum": 2200,
      "description": "Optional fiscal year filter."
    },
    "fiscalQuarter": {
      "type": "integer",
      "minimum": 1,
      "maximum": 4,
      "description": "Optional fiscal quarter filter."
    },
    "search": {
      "type": "string",
      "description": "Optional case-insensitive text/speaker search across transcript chunks."
    },
    "maxChunks": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 80,
      "description": "Maximum speaker-tagged transcript chunks to return."
    },
    "maxCharsPerChunk": {
      "type": "integer",
      "minimum": 200,
      "maximum": 4000,
      "default": 1600,
      "description": "Maximum characters per transcript chunk in the MCP response."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Use when the user refers to THEIR portfolio(s) or holdings — e.g. "my portfolios", "what portfolios do I have", "how are my investments doing", "show my holdings", "my account". Lists the signed-in Bullrun user's virtual portfolios with computed summaries: name, base currency, total value (USD), day change, cost basis and total return, plus position counts. Start here when a portfolio question doesn't name a specific portfolio, then pass a portfolioId to get_portfolio_context or get_portfolio_analytics. Requires connecting this server to a Bullrun account (OAuth, read:portfolios scope) — it returns that user's own data only. privacyMode defaults to "full" (includes absolute $ amounts); pass "weights_only" to hide absolute money and return only relative figures (returns %, counts). Read-only.

{
  "type": "object",
  "properties": {
    "privacyMode": {
      "type": "string",
      "enum": [
        "full",
        "weights_only"
      ],
      "description": "\"full\" (default) includes absolute $; \"weights_only\" hides cash/value/cost-basis and keeps only %."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Use when the user asks to look at, review, or analyze THEIR portfolio / holdings / positions — e.g. "analyze my portfolio", "how is my portfolio doing", "what's in my portfolio", "review my holdings", "how am I invested", "what should I improve". Fetches a deep snapshot of ONE of the signed-in user's portfolios: the summary (value, day change, total return), every holding (with position weight %, sector and return) and Bullrun's computed insights (benchmark comparison, concentration, diversification, dividend income). Pass a portfolioId from list_portfolios (call that first if the user hasn't named a portfolio). The response ALWAYS returns the complete holdings list with each position flagged matched/unmatched, plus a `coverage` summary: holdings that Bullrun can't link to its universe (ETFs, funds, untracked tickers) carry no weight, sector, insight or ML score, so weights/insights/ML below describe ONLY the matched subset. Read the coverage banner (the first text block) and never present matched-only figures as the whole portfolio. For risk/diversification math, correlations, factor exposure, or whether to add a specific stock, use get_portfolio_analytics instead. Requires OAuth (read:portfolios) and returns the caller's own data only. privacyMode defaults to "full" (absolute $ included); "weights_only" returns only relative figures. Read-only.

{
  "type": "object",
  "properties": {
    "portfolioId": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "description": "The portfolio id, as returned by list_portfolios."
    },
    "days": {
      "type": "integer",
      "minimum": 7,
      "maximum": 3700,
      "description": "Insights look-back window in days (default 30)."
    },
    "privacyMode": {
      "type": "string",
      "enum": [
        "full",
        "weights_only"
      ],
      "description": "\"full\" (default) includes absolute $; \"weights_only\" returns only relative figures."
    }
  },
  "required": [
    "portfolioId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Use when the user asks about THEIR portfolio's risk, diversification, or concentration, or whether to add a stock — e.g. "is my portfolio diversified", "how risky is my portfolio", "am I too concentrated", "what's my exposure to X", "should I add NVDA", "would AAPL improve my diversification". Fetches portfolio-level relationship analytics for one signed-in user's portfolio: correlation and annualized covariance matrices across holdings, contribution-to-risk, concentration by weight and risk, currency/sector/country exposures, value/growth/momentum/quality/size proxy factor scores, scenario/stress tests (rates +100bp, oil -20%, USD +10%), and optional candidateTicker fit analysis showing correlation to the current portfolio plus pro-forma volatility (set candidateTicker when the user asks whether to add a specific stock). Pass a portfolioId from list_portfolios. The risk math only covers holdings with enough price history, dropping unpriced/unmatched ones (ETFs, funds, untracked tickers) and renormalizing all percentages over what remains; the response leads with a `coverage` banner (first text block) stating how many holdings were excluded, so never read these figures as the whole portfolio. For a plain holdings/value snapshot and the full matched/unmatched breakdown use get_portfolio_context instead. Requires OAuth (read:portfolios) and returns the caller's own data only. privacyMode defaults to "full"; "weights_only" hides absolute USD amounts while keeping weights, percentages, correlations and scores.

{
  "type": "object",
  "properties": {
    "portfolioId": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "description": "The portfolio id, as returned by list_portfolios."
    },
    "days": {
      "type": "integer",
      "minimum": 30,
      "maximum": 1825,
      "description": "Calendar-day lookback for daily USD return analytics. Default 370."
    },
    "candidateTicker": {
      "type": "string",
      "minLength": 1,
      "description": "Optional exact Bullrun ticker to test as a candidate diversifier - the native local-exchange symbol, e.g. AAPL, BMW, ABBN, NESN (not Yahoo-style suffixes like BMW.DE)."
    },
    "candidateWeightPct": {
      "type": "number",
      "minimum": 0,
      "maximum": 50,
      "description": "Optional hypothetical candidate allocation for pro-forma volatility. Default 5 (%)."
    },
    "privacyMode": {
      "type": "string",
      "enum": [
        "full",
        "weights_only"
      ],
      "description": "\"full\" (default) includes absolute USD amounts; \"weights_only\" returns only relative figures."
    }
  },
  "required": [
    "portfolioId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Use when the user wants you to BUILD or PROPOSE a brand-new portfolio for them — e.g. "build me a portfolio", "put together a dividend portfolio", "draft a portfolio of AI stocks", "create a new portfolio for $10k". Generates a REVIEWABLE paper-portfolio draft for the signed-in Bullrun user from a natural-language brief (e.g. "a diversified European dividend portfolio"). Requires OAuth with the write:drafts scope and a Bullrun Pro account. This is DRAFT-ONLY and never changes any live position: the draft is saved to the user's account and appears in the Bullrun Portfolio tab under "Pending AI drafts", where the user reviews it and explicitly accepts it to create a new portfolio (or discards it). To suggest additions to an EXISTING portfolio instead, use create_position_draft. Tickers are chosen only from Bullrun's priced stock/ETF universe; pass instrumentUniverse for stocks only, ETFs only, or a mix. If the brief is vague, first ask ONE quick round of up to three multiple-choice questions (investing style, region focus, and size), each with a default the user can accept with "just pick for me", then build; skip any dimension the user already specified and do not interrogate across multiple turns.

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "maxLength": 600,
      "description": "What kind of portfolio to draft, e.g. \"a defensive dividend portfolio of large EU stocks\". Optional: if you omit it, the server collects a quick style/region/size brief from the user directly (a native form on clients that support elicitation; otherwise it asks you to gather those first)."
    },
    "startingCash": {
      "type": "number",
      "minimum": 100,
      "maximum": 100000000,
      "description": "Starting cash in USD (default 10000)."
    },
    "maxPositions": {
      "type": "integer",
      "minimum": 3,
      "maximum": 20,
      "description": "Maximum number of holdings (3-20, default 10)."
    },
    "instrumentUniverse": {
      "type": "string",
      "enum": [
        "stocks",
        "etfs",
        "mix"
      ],
      "description": "Candidate universe: stocks only, ETFs only, or a mix. Default mix unless the prompt says otherwise."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Use when the user asks what to BUY or ADD to an EXISTING portfolio — e.g. "what should I buy next", "suggest a stock or ETF for my portfolio", "what should I add", "recommend a position", "any ideas to round out my holdings". Generates REVIEWABLE suggested additions for one existing Bullrun portfolio. Requires OAuth with the write:drafts scope and a Bullrun Pro account. This is DRAFT-ONLY: the suggested position(s) are saved to the user's account and appear in the Bullrun Portfolio tab under Pending AI drafts, where the user reviews and accepts them into the target portfolio or discards them. It never changes live holdings by itself. To draft a whole new portfolio from scratch use create_portfolio_draft; to test whether a specific named ticker fits, use get_portfolio_analytics with candidateTicker. Pass instrumentUniverse for stocks only, ETFs only, or a mix. If it is unclear, first confirm which portfolio (use list_portfolios when the user has more than one) and how many ideas (a single best idea or a few) in ONE quick step; otherwise just build.

{
  "type": "object",
  "properties": {
    "portfolioId": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "description": "The Bullrun portfolio id to propose additions for. Use list_portfolios first if unsure."
    },
    "maxPositions": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5,
      "description": "How many suggested additions to save, 1-5. Use 1 for a single-position idea; default 3."
    },
    "instrumentUniverse": {
      "type": "string",
      "enum": [
        "stocks",
        "etfs",
        "mix"
      ],
      "description": "Candidate universe: stocks only, ETFs only, or a mix. Default mix."
    }
  },
  "required": [
    "portfolioId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Use when YOU (or the user) have ALREADY decided the exact holdings and want them saved as-is — e.g. after researching and settling on a specific basket with target weights. Persists a REVIEWABLE paper-portfolio draft built from the tickers you supply, sized by weight (percent) or by explicit USD amount. Unlike create_portfolio_draft this does NOT use the LLM and NEVER re-selects tickers: your basket lands exactly as given. It is NOT Pro-gated (it mirrors manual position entry, which is free) and needs only OAuth with the write:drafts scope. DRAFT-ONLY: the draft is saved to the user's Bullrun account and appears in the Portfolio tab under "Pending AI drafts", where the user reviews it and explicitly accepts it (creating a NEW portfolio) or discards it — it never changes any live position. Tickers must exist in Bullrun's priced stock/ETF universe; any that cannot be priced are returned in `unresolved` and skipped (use search_etfs / get_etf_snapshot / screen_stocks / get_stock_metrics to confirm exact tickers first). For a vague brief where the model should pick, use create_portfolio_draft instead.

{
  "type": "object",
  "properties": {
    "positions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "ticker": {
            "type": "string",
            "description": "Exact Bullrun ticker, used verbatim (never re-picked), e.g. VWCE.DE, SMH, ROG.SW."
          },
          "weight": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "Target weight as a PERCENT (e.g. 46 for 46%). If the weights across positions sum to <=100 the remainder is held as cash; any other sum is normalised to fully invested. Use weight OR amountUsd across the basket, not both."
          },
          "amountUsd": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "Explicit USD amount to allocate to this holding. If ANY position uses amountUsd, sizing is by amount for all."
          }
        },
        "required": [
          "ticker"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 30,
      "description": "The exact holdings to persist (1-30). Tickers are used verbatim, never re-selected."
    },
    "name": {
      "type": "string",
      "maxLength": 72,
      "description": "Portfolio name. Default \"Custom Portfolio Draft\"."
    },
    "startingCash": {
      "type": "number",
      "minimum": 100,
      "maximum": 100000000,
      "description": "Total portfolio cash in USD. Default 10000 in weight mode; the sum of amounts in amount mode."
    },
    "cashPct": {
      "type": "number",
      "minimum": 0,
      "maximum": 95,
      "description": "Explicit cash percentage to hold back. Overrides the weight-remainder rule."
    }
  },
  "required": [
    "positions"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Discover what the connected Bullrun account can do BEFORE attempting an action, so you can plan instead of learning by hitting a 403. Reports whether you are authenticated and as WHICH identity (email + userId), whether the account has Bullrun Pro and why (subscription / trial / admin), the granted OAuth scopes, portfolio usage vs the free/max limits, and a per-tool entitlement map: create_portfolio_from_positions (free), create_portfolio_draft and create_position_draft (Pro-only), and whether another portfolio can be created now. Call this first when a draft/write tool might be gated, or to confirm which account a request will act on. Read-only.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}