ForInvest

Returns analyst forecast and broker model portfolio data for BIST securities. **type="forecast"** — Analyst target price forecasts: - mode="averages": Consensus target prices (lowest/average/highest) and buy/sell/hold counts per symbol. - mode="detail": Target price forecasts filtered by broker and/or symbol. - mode="history": Historical price target revisions by broker for a symbol. **type="portfolio"** — Broker model portfolios: - mode="averages": Broker consensus target prices (lowest/average/highest) and analyst count per symbol. - mode="list": Target prices and portfolio weights filtered by broker, symbol, or both. - mode="updates": Recent broker model portfolio changes. last must be 1, 7, 14, or 30 days; default is 7. Client-side response reduction is applied after normalization and does not change the upstream request: filter selects rows by fields, limit caps rows after filtering, and calculate returns an aggregate or selected row using sum, count, min, max, avg, first, or last. Numeric calculations require field, for example {function: "avg", field: "targetPrice"}; multiple operations and groupBy are supported in order filter → limit → calculate. For keyed multi-symbol responses, transformations apply independently to each symbol's array and preserve symbol keys. The existing last parameter in portfolio updates remains its upstream day-window control; use limit for local output reduction. **Examples:** - Forecast averages: type: "forecast", mode: "averages", symbolCodes: ["GARAN", "THYAO"] - Forecast detail: type: "forecast", mode: "detail", brokerCode: "ACP", symbolCode: "GARAN" - Forecast history: type: "forecast", mode: "history", brokerCode: "FNY", symbolCode: "GARAN" - Portfolio averages: type: "portfolio", mode: "averages", symbolCodes: ["GARAN", "ASELS"] - Portfolio list: type: "portfolio", mode: "list", symbolCode: "GARAN" - Portfolio updates: type: "portfolio", mode: "updates", last: 7 Time zone: Europe/Istanbul.

analystData

Resolves one or more broker codes to full brokerage firm records: BrokerId, BrokerCode, BrokerShortName, BrokerName, BrokerLegacyCode, BrokerType, BrokerStatus. Matches both internal codes (GDK) and legacy codes (GDK.B). **Example:** brokerDefinitions with brokerCodes: ["GDK", "FNY.B"] Use when you have verified broker codes from symbolSearchFlex or analystData forecasts/model portfolios and need their names. Time zone: Europe/Istanbul.

brokerDefinitions

Returns historical settlement (takas/custody) positions for BIST symbols. Use mode "at" for one date or "last" for recent days. The optional rc parameter filters the response to specific broker/institution codes; it does not provide order-book depth. Example: { mode: "at", codes: ["GARAN"], at: "20250110", rc: ["CIY.B"] }. Time zone: Europe/Istanbul.

brokerActivity

Returns company profile information for one or more BIST symbols. By default, returns a compact profile with the main identity, activity, dates, capital, management, and employee fields to reduce LLM context size. Use the optional fields parameter to request a different projection. fields must use the exact normalized names: BistCode, IpoDate, EstablishmentDate, FirstTransactionDate, Phone, Fax, FieldOfActivity, RegisteredCapital, GeneralManager, EmployeeUnion, EmployerUnion, NumberOfEmployee, Address, Website, BoardMembers, CompanyName, Partners, Shareholders, ExchangePosition. Large fields such as Partners, Shareholders, BoardMembers, ExchangePosition, Address, Website, Phone, and Fax are not returned by default; request them explicitly when needed. If fields is provided, only those fields are returned. **Examples:** - Compact default: companyInfos with codes: ["GARAN"] - Ownership details: companyInfos with codes: ["GARAN"], fields: ["CompanyName", "Shareholders", "Partners"] - Contact details: companyInfos with codes: ["GARAN"], fields: ["CompanyName", "Address", "Phone", "Website"] Time zone: Europe/Istanbul.

companyInfos

Returns corporate actions data: splits, dividends, rights issues, and future scheduled events. Types: - "historyByCode": Historical corporate actions for specified symbols. Fields: Date, Code, RightsIssuePercent, BonusIssuePercent, DividendPercent, GrossDividendAmount, NetDividendAmount, AdjustmentRatio. - "historyByDate": Corporate actions within a date range. Fields: Date, SymbolCode, RightIssuesPercent, BonusIssuesPercent, DividendPercent, GrossDividendAmount, NetDividendAmount, SplitRatio, SplitStatus, Exchange. Exchange can be BIST, CSE, or ATHEX. - "future": Future scheduled stock splits. Omit codes to return all symbols; when codes are provided the result is keyed by input code. Fields: symbolCode, announcementDate, isExecuted, rightsIssuePercent, bonusIssuePercent, otherRightsPercent, dividendPercent, isSpkApproved, futureCapital, currentCapital, effectiveDate, rightsDate, bonusDate, scripDate, otherRightsDate. - "dividendChamps": Top 20 BIST stocks by dividend yield per year. History GrossDividendAmount and NetDividendAmount are amounts, not percentages; null means unavailable. Client-side response reduction is applied after normalization and does not change the upstream request: filter selects rows by fields, limit caps rows after filtering, and calculate supports sum, count, min, max, avg, first, or last. Numeric calculations require field, for example {function: "avg", field: "DividendPercent"}; multiple operations and groupBy are supported in order filter → limit → calculate. For keyed symbol responses, transformations apply independently to each symbol's array and preserve symbol keys. **Examples:** - By code: type: "historyByCode", codes: ["GARAN", "ASELS"] - By date: type: "historyByDate", from: "20240101", to: "20241231", exchange: "BIST" - Future: type: "future", codes: ["GARAN"] — or omit codes for all symbols - Dividend champs: type: "dividendChamps", from: 2023, to: 2024 Time zone: Europe/Istanbul.

corporateActions

Returns economic calendar events: date, country, event name, importance level (1-3), and actual/forecast/previous values. Client-side response reduction is applied after normalization and does not change the upstream request: filter selects rows by fields, limit caps rows after filtering, and calculate supports sum, count, min, max, avg, first, or last. Numeric calculations require field, for example {function: "avg", field: "EventDate"}; multiple operations and groupBy are supported in order filter → limit → calculate. **Example:** economicCalendar with countryCode: "US", from/to for date range, filter: {field: "ImportanceLevel", op: "gte", value: 2}, limit: 10. Time zone: Europe/Istanbul.

economicCalendar

Returns financial ratio and fundamental analysis data. Modes: - "lastQuarter": Latest quarter metrics (NetProfit, EBITDA, ROA, ROE, debt ratios) per symbol. - "multiPeriod": Financial ratios across multiple quarters. Specify starting term and number of periods. - "snapshot": Real-time fundamental analysis metrics (P/E, P/B, EPS, dividend yield, market cap) per symbol. **Examples:** - lastQuarter: mode: "lastQuarter", codes: ["GARAN", "ASELS"] - multiPeriod: mode: "multiPeriod", codes: ["GARAN"], term: "2024-12", iry: 4 - snapshot: mode: "snapshot", codes: ["GARAN", "THYAO"] Time zone: Europe/Istanbul.

financialRatios

Returns financial statement data: balance sheet, income statement, or cash flow. - type "balance": Assets, liabilities, equity line items. Auto-discovers recent periods (use limit). - type "income": Revenue, expenses, net profit line items. Requires explicit term (e.g., "2024-12"). - type "cashFlow": Operating/investing/financing activities. Auto-discovers recent periods (use limit). Parameters: - codes: Symbol codes (parallel execution) - type: "balance" | "income" | "cashFlow" - consolidated: true (default) for consolidated statements - term: Required for income type. Format: "YYYY-M" (e.g., "2024-3", "2024-12") - limit: For balance/cashFlow — number of recent periods to return (default 4, max 20) **Examples:** - Balance: codes: ["GARAN"], type: "balance", limit: 4, consolidated: true - Income: codes: ["GARAN", "ASELS"], type: "income", term: "2024-12", consolidated: true - Cash Flow: codes: ["THYAO"], type: "cashFlow", limit: 4 Time zone: Europe/Istanbul.

financialStatements

Fuzzy full-text search across ForInvest symbol definitions. Searches code, name, issuer, exchange, and metadata fields with typo tolerance. Use for BIST, US equities available from the CBOE/EDGX feed, and other ForInvest-indexed symbols. **When to use:** - User mentions a company/asset name partially or with typos (e.g., "garant" → finds "Garanti Bankası") - Search policy: preserve the user's natural wording first. If the user says "ons altın", "altın", or "petrol", search those words first; do not prematurely rewrite them to tickers like "XAU/USD". Only try English equivalents if needed. - Finding symbols when exact code is unknown - Exploring available instruments in a sector or category - Searching US equities (e.g., Tesla, Apple) with superDomain: "us-equity" ** DIRECTIVE: superDomain is required. Always choose the most specific superDomain for the user's query. Do not send "default"; broad default search is used only as an internal fallback when a non-broker superDomain returns no results.** **Available superDomains:** - "bist-stock": Stocks traded on Borsa Istanbul (BIST). Use for Turkish equities, shares, and company stocks. - "us-equity": US equities available from the CBOE/EDGX feed. Use for US stock symbol discovery. Coverage is limited to the feed definitions available to ForInvest. - "fx": Currency pairs and generic precious-metal quotes, including gold, silver, platinum and palladium crosses and available gram-based quotes. - "global-index": International market indexes. Use for foreign indexes. - "crypto": Cryptocurrency instruments. Use for crypto assets and pairs. - "spot": Instruments in ForInvest's SPOT catalog, including Grand Bazaar, bank and exchange-office quotes, local precious-metal products and indicative values. This scope does not cover all non-derivative commodities. - "bist-derivatives": VIOP futures contracts, warrants, and options. Use for derivatives, VIOP sözleşmeleri, varantlar, and opsiyonlar. - "bist-broker": BIST broker/intermediary institutions. Use for searching brokers by code, name, or type. - "tefas-funds": TEFAS mutual funds (yatırım fonları). Use for searching Turkish investment funds by name or code. **Parameters:** - key (optional): Single search term; can be a partial name, ticker, or keyword. Prefer the user's original natural-language wording first; use ticker-style input only if the user explicitly gives it or it is already known. - keys (optional): Multiple search terms of at least 2 characters each. Uses the same where/superDomain for all keys. - At least one non-empty search term must be supplied through key or keys. - topPercent (optional, 1-100, default: 40): Controls the relevance-score cutoff; higher values retain more candidates. Usually leave at default. - where (optional): Filter object with domain, exchange, market, securityType, index, and/or marketSector fields (e.g., { domain: "BIST" }, { domain: "FX" }, { domain: "CBOE", exchange: "EDGX" }, { index: "XU030" }) - superDomain (required): Choose the most specific index to search first (e.g., "bist-stock", "us-equity", "bist-derivatives"). Non-broker searches fall back to the default index if no results are found. **Returns:** For a single key, matching symbols with: code, name, securityType, domain, exchange, market, marketSector, and sector. For multiple keys, returns the same result structure grouped under "queries". **Instructions** - Where clause (filtering) should only be used if specified by the agent prompt. Do not use filters that are not specified here. - For natural-language asset requests, search the asset name/phrase first (e.g., "ons altın"), not a guessed symbol code or parity. - For US equity intent, use superDomain: "us-equity". Do not route US equities through "bist-stock" or rely on the internal default fallback. - Use "fx" for currency pairs and generic precious-metal quotes; use "spot" for the SPOT catalog instruments described above. Use "global-index" for foreign indexes and "crypto" for cryptocurrencies. - Neither the word "spot", an exchange value of "SPOT", nor an ounce/gram unit alone determines the search scope. - Use "bist-derivatives" only when the request explicitly targets futures, warrants, options, or VIOP instruments. - Treat CBOE/EDGX as the ForInvest feed venue. Do not infer a company's primary NYSE/NASDAQ listing unless another reliable result explicitly provides it. **Example queries:** - User asks: "Ons altın saatlik grafikte..." → use { "key": "ons altın", "superDomain": "fx" }, not a guessed symbol code - "çeyrek altın" → spot gold instruments, { "key": "çeyrek altın", "superDomain": "spot" } - "garanti" → GARAN (Garanti Bankası stock), { "key": "garanti", "superDomain": "bist-stock" } - "tesla" → TSLA:EDGX, { "key": "Tesla", "superDomain": "us-equity" } - "apple" → AAPL:EDGX, { "key": "Apple", "superDomain": "us-equity" } - "dolar" or "usd" → FX pairs, { "key": "dolar", "superDomain": "fx" } - "DAX" or "FTSE 100" → foreign indexes, { "key": "DAX", "superDomain": "global-index" } - "bitcoin" or "ethereum" → cryptocurrencies, { "key": "bitcoin", "superDomain": "crypto" } - "bist 30" → XU030 index, eg.: { "key": "BIST 30", "superDomain": "bist-stock" } - "tahvil" or "bond" → Government and corporate bonds, eg.: { "key": "tahvil", "superDomain": "bist-stock" } - "viop" → VIOP futures contracts / VIOP sözleşmeleri, eg.: { "key": "garanti", "superDomain": "bist-derivatives" } - "varant" → Warrants, eg.: { "key": "garanti", "superDomain": "bist-derivatives" } - "opsiyon" → Options, eg.: { "key": "akbank", "superDomain": "bist-derivatives" } - Other words for filtering Varant -> { "securityType": "Warrant" }, Opsiyon -> { "securityType": "Option" } - "aracı kurum" or "broker" → Broker institutions, eg.: { "key": "garanti", "superDomain": "bist-broker" } - "fon" or "yatırım fonu" → TEFAS mutual funds, eg.: { "key": "garanti", "superDomain": "tefas-funds" } - Multi search → { "keys": ["garanti", "akbank"], "superDomain": "bist-stock" } - Index members → { "mode": "byIndex", "index": "XU030" } **mode "byIndex":** Returns all BIST symbols belonging to a given index code. No search key needed. Popular indexes: XU030 (BIST 30), XU050 (BIST 50), XU100 (BIST 100), XUTUM (Tüm), XBANK (Banka), XUSIN (Sınai), XUMAL (Mali), XUHIZ (Hizmetler), XHOLD (Holding), XGIDA (Gıda), XELKT (Elektrik), XTEKS (Tekstil), XKMYA (Kimya), XTRZM (Turizm), XBLSM (Bilişim), XUTEK (Teknoloji), XTMTU (Temettü), KATLM (Katılım 30). **Example:** mode: "byIndex", index: "XU030" Time zone: Europe/Istanbul.

symbolSearchFlex

Returns licensed fund portfolio report data. Requires LIC_TEFASFUND_AND_EUROBOND. Modes: - mode="periods": Lists every available monthly portfolio report period for a fund. - mode="holdings": Returns all holdings for a monthly report. category can restrict asset groups; fundPeriod defaults upstream to the latest report. limit and sorting apply independently within each category. navWeight is the recommended client-facing weight. - mode="positionChanges": Compares the latest two consecutive reports and groups positions as increased, decreased, new, or exited. category=["stockDomestic"] is recommended for equity-focused views. Examples: - Available periods: { mode: "periods", fundCode: "IPJ" } - Latest holdings: { mode: "holdings", fundCode: "IPJ", category: ["stockDomestic"], sortBy: "navWeight", sortDirection: "DESC" } - A specific report: { mode: "holdings", fundCode: "IPJ", fundPeriod: "2026-07" } - Domestic stock changes: { mode: "positionChanges", fundCode: "IPJ", category: ["stockDomestic"], deltaType: ["increased", "decreased", "new", "exited"] } Time zone: Europe/Istanbul.

fundPortfolio