Read the docs.

pip install -U xfinlink

Create a free account to get your API key, then:

import xfinlink as xfl

xfl.set_api_key("YOUR_API_KEY")   # or set XFINLINK_API_KEY in your environment

prices       = xfl.prices("AAPL", start="2024-01-01")
fundamentals = xfl.fundamentals("AAPL", period_type="annual", period="5y")
ratios       = xfl.metrics("AAPL", period_type="ttm")
members      = xfl.index("sp500")

ticker period_end  revenue  net_income
  AAPL 2021-09-25   365817       94680
  AAPL 2022-09-24   394328       99803
  AAPL 2023-09-30   383285       96995
  AAPL 2024-09-28   391035       93736
  AAPL 2025-09-27   416161      112010

Two things to know before your first call.

1. Every Python call returns the last 12 months unless you pass start or period. period accepts "1w", "1mo", "3mo", "6mo", "1y" through "30y", "ytd", "max".
2. Values are not all on the same scale. /v1/fundamentals and /v1/metrics report money in millions of USD; /v1/prices reports whole dollars and whole share counts. Per-share figures are dollars everywhere.

Pass your key in the X-API-Key header. It is shown on your dashboard and can be regenerated at any time.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/prices/AAPL?start=2024-01-01"

The Python client sends the header for you. Set the key either way:

import xfinlink as xfl
xfl.set_api_key("YOUR_API_KEY")     # in code
# export XFINLINK_API_KEY=...    # or in the environment

On a free key: 1 ticker per request, history starts 12 months back, 100 requests a day (max 40 in any hour). Insiders, holdings and managers return 402.

Without a key: only /v1/search and /v1/resolve answer, at 60 requests an hour per IP. Resolve then omits ticker validity dates, classifications and index membership.

Daily OHLCV with split-adjusted close, total return, and dividend and split events. Prices are dollars, shares_outstanding is a whole share count, market_cap is whole dollars.

df = xfl.prices("AAPL", start="2024-01-01", fields=["close", "volume"])

 entity_id ticker entity_name            gics_sector       date     close   volume
         1   AAPL   Apple Inc Information Technology 2024-01-02 185.64000 81752737
         1   AAPL   Apple Inc Information Technology 2024-01-03 184.25000 58136569
         1   AAPL   Apple Inc Information Technology 2024-01-04 181.91000 71280275
         1   AAPL   Apple Inc Information Technology 2024-01-05 181.17999 62064040

Income statement, balance sheet and cash flow as reported. Money is in millions of USD, share counts are in millions, per-share figures are dollars.

A bad fiscal_year or period_end is ignored with a warning in meta rather than failing the request.

By default you get one row per fiscal period. Where the preferred filing left a field empty and a sibling filing for the same period had it, the value is filled in and the field name is listed in filled_from_historical on that row.

df = xfl.fundamentals("AAPL", period_type="annual", period="5y",
                     fields=["revenue", "net_income", "eps_diluted"])

# With revenue segments
df = xfl.fundamentals("AAPL", include_segments=True)

ticker period_end  revenue  net_income  eps_diluted
  AAPL 2021-09-25   365817       94680         5.61
  AAPL 2022-09-24   394328       99803         6.11
  AAPL 2023-09-30   383285       96995         6.13
  AAPL 2024-09-28   391035       93736         6.08
  AAPL 2025-09-27   416161      112010         7.46

Every company that has ever used a ticker, with the dates it held it, its classifications, its index membership and its verified succession links.

info = xfl.resolve("GM")
for entity in info["data"]["GM"]["entities"]:
    print(entity["name"], entity["ticker_valid_from"], entity["ticker_valid_to"])

General Motors Corporation (pre-2009 bankruptcy) 1962-07-02 2009-06-01
General Motors Company 2010-11-18 None

Succession links

Where a verified link exists between two entity records, resolve returns it on the entity as succession: predecessors are records whose history runs into this one, successors are records this one's history runs into. Each link carries entity_id, name, event_type and event_date, and is verified against SEC filings.

Links are direct and one hop: a succession running through three companies reads as two links. The block is omitted for an entity with no verified links; when present, both arrays are present and either can be empty. It is returned with or without an API key, is part of the default include="all" response, and can be requested alone with include="events".

Pass a link's entity_id to reach a predecessor's own data, which the ticker no longer reaches:

info = xfl.resolve("TWX")
entity = info["data"]["TWX"]["entities"][0]
print(entity["entity_id"], entity["succession"]["predecessors"])

df = xfl.fundamentals(entity_id=7441, period="max")  # the predecessor's own statements
print(len(df), df["period_end"].max().date())

14682 [{'entity_id': 7441, 'name': 'TIME WARNER INC', 'event_type': 'merger', 'event_date': '2001-01-11'}]
183 2000-12-31

Find entities by name, ticker, sector, type, or classification code. Returns entity_id, ticker, entity_name, entity_type, gics_sector, gics_sub_industry, sic, naics, country.

df = xfl.search(q="apple", limit=5)
df = xfl.search(gics_sector="Consumer Staples")

ticker                  entity_name            gics_sector
 7076B            APPLE BANCORP INC             Financials
  AAPL                    Apple Inc Information Technology
APPB.1  APPLEBEES INTERNATIONAL INC Consumer Discretionary
   MLP MAUI LAND & PINEAPPLE CO INC            Real Estate
TAVI.1       THORN APPLE VALLEY INC       Consumer Staples

Index members, today or on any past date. Four indices: sp500, ndx100, djia, russell2000. Returns entity_id, ticker, entity_name, added_date, removed_date.

df = xfl.index("sp500")                      # 499 members today
df = xfl.index("sp500", as_of="2000-01-01")   # 454 members then

An as_of roster carries the company name and ticker recorded on each membership spell — what the member traded under on that date: a 2000-01-01 S&P 500 snapshot shows WORLDCOM INC GA NEW under WCOM. The live roster (no as_of) carries today's names and tickers, so the same company can appear under different labels in the two; entity_id is the stable key across both.

Rows with entity_id: null are membership spells with no linked entity record; they carry the point-in-time ticker and entity_name from the membership record. ticker is null on the earliest members, whose spells all ended by 1962; entity_name is always present. Rows without an entity_id cannot be joined to prices, fundamentals or metrics — drop them before merging.

Membership changes — /v1/index/{index_name}/events

One row per addition and per removal, oldest first. Returns entity_id, ticker, entity_name, index, event_type, effective_date. Each row carries the name and ticker recorded for that membership spell, not a modern one. entity_id is null on events from an unlinked membership spell, on the same terms as the roster above.

meta.event_coverage_start is the date each index's record opens. Members already in the index on that date are the founding roster, not additions, so they are not returned as events. Removals always are.

df = xfl.index_events("sp500", start="2024-01-01", end="2024-12-31",
                     event_type="added")

 entity_id ticker              entity_name index event_type effective_date
     16667   DECK     DECKERS OUTDOOR CORP SP500      added     2024-03-18
      3143     GE      GENERAL ELECTRIC CO SP500      added     2024-03-18
     32621   SMCI SUPER MICRO COMPUTER INC SP500      added     2024-03-18
     23642   SOLV           SOLVENTUM CORP SP500      added     2024-04-01
     23644    GEV          G E VERNOVA INC SP500      added     2024-04-02

Insider transactions from SEC Form 3, 4 and 5 filings, one row per transaction, 1996 to today. Shares and prices are split-adjusted. Paid plans only; free keys get 402.

Always returned: entity_id, ticker, entity_name, transaction_date, filing_date, form_type, insider_name, insider_role, transaction_code, transaction_type, acquisition_or_disposition, shares, shares_held_after, transaction_price, transaction_value, ownership_type, is_amendment, document_id. Add with fields=: insider_role_other, sequence_in_filing, data_quality.

df = xfl.insiders("NVDA", transaction_type="open_market_sell", period="2y")

ticker transaction_date   insider_name insider_role  shares  transaction_price
  NVDA       2026-06-18 STEVENS MARK A     Director  565615           210.4372
  NVDA       2026-06-18 STEVENS MARK A     Director  319385           209.6952
  NVDA       2026-06-03 Neal Stephen C     Director   15500           215.7331
  NVDA       2026-03-20 KRESS COLETTE M.          CFO    180           171.9951

Who holds a security, quarter by quarter, from SEC Form 13F. One row per manager, security and quarter, biggest positions first. Coverage starts 1978 and refreshes weekly. Paid plans only; free keys get 402.

Fields: entity_id, ticker, entity_name, report_date, shares, manager_id, manager_name, manager_type, filing_date, value_usd, sole_voting, shared_voting, no_voting, security_class, put_call, source, is_amendment.

A new quarter fills in over roughly 45 days as filers submit; data_through gives the latest quarter in your response. Positions before 2000 resolve less completely than later ones. Join on entity_id, not ticker, when combining with other endpoints.

# Who held Apple at the end of 2026 Q1
df = xfl.holdings("AAPL", quarter="2026-03-31")

# Positions worth at least $1bn
df = xfl.holdings("MSFT", quarter="2026-03-31", min_value=1_000_000_000)

ticker report_date                    manager_name     shares    value_usd
  AAPL  2026-03-31                 BlackRock, Inc. 1144695425 290512251859
  AAPL  2026-03-31 VANGUARD CAPITAL MANAGEMENT LLC  953847648 242076924860
  AAPL  2026-03-31               STATE STREET CORP  602341409 152868226190

Find an institutional manager by name, then pull their portfolio. Only managers with at least one position are returned. Paid plans only; free keys get 402.

Fields: manager_id, manager_name, manager_type, country, cik, first_quarter, last_quarter, id_regime.

Their portfolio — /v1/managers/{manager_id}/holdings

Same rows and fields as /v1/holdings, sorted by position value, with the manager in the envelope instead of on every row. Takes start, end, quarter, min_shares, min_value, fields, limit and cursor — not the manager or security filters.

# Find Berkshire, then pull their 2026 Q1 portfolio
mgrs = xfl.managers("berkshire hathaway")
mid = mgrs.loc[mgrs["manager_name"] == "Berkshire Hathaway Inc", "manager_id"].iloc[0]

df = xfl.manager_holdings(mid, quarter="2026-03-31")

ticker          entity_name    shares   value_usd
  AAPL            Apple Inc 227917808 57843260493
   AXP  AMERICAN EXPRESS CO 151610700 45859204536
    KO         COCA COLA CO 400000000 30420000000
   BAC BANK OF AMERICA CORP 513624165 25039178044
   CVX         CHEVRON CORP  84375856 17457364606

Ratios and scores, already computed. Ratios are decimals (0.46 = 46%). Market cap and enterprise value are in millions of USD. Per-share values are dollars.

Growth needs a prior period to compare against, so ask for more than one: period="5y" or an explicit start.

# Trailing-12-month valuation snapshot
df = xfl.metrics("AAPL", period_type="ttm", fields=["valuation"])

# Year-over-year growth, five years
df = xfl.metrics("AAPL", period_type="annual", period="5y", fields=["growth"])

# One row per trading day for the last 90 days
df = xfl.metrics("AAPL", period_type="daily", fields=["pe_ratio", "realized_volatility_21d"])

ticker period_end  revenue_growth  eps_diluted_growth
  AAPL 2021-09-25             NaN                 NaN
  AAPL 2022-09-24        0.077938            0.089127
  AAPL 2023-09-30       -0.028005            0.003273
  AAPL 2024-09-28        0.020220           -0.008157
  AAPL 2025-09-27        0.064255            0.226974

Valuation

Profitability

Leverage

Liquidity

Efficiency

Per-Share

Dividends

Scores

Growth

Volatility

Annualized, as a decimal (0.2628 = 26.28% a year). A value needs the window's full count of trading days, spanning no more than about 1.5x the normal calendar time (46 / 137 / 548 days). Otherwise it is null, meaning not measurable here. Do not read that as zero.

adj_close is adjusted backwards onto today's share basis. To adjust forwards from a date instead, take raw close and split_ratio and compound the ratios forward:

import xfinlink as xfl

df = xfl.prices("AAPL", start="2020-08-27", end="2020-09-02",
                fields=["close", "split_ratio"], adjust="none")
df = df.sort_values("date")

factor = df["split_ratio"].fillna(1.0).cumprod()
df["forward_adj_close"] = df["close"] * factor

      date ticker     close  split_ratio  forward_adj_close
2020-08-27   AAPL 500.04001          NaN          500.04001
2020-08-28   AAPL 499.23001          NaN          499.23001
2020-08-31   AAPL 129.03999          4.0          516.15996
2020-09-01   AAPL 134.17999          NaN          536.71996
2020-09-02   AAPL 131.39999          NaN          525.59996

There is no dividend-adjusted price field: that series rewrites its own history at every dividend. Stable values plus total returns are stored instead — build it yourself:

import xfinlink as xfl

df = xfl.prices("AAPL", period="5y", fields=["adj_close", "return_daily"])

df["total_return_index"] = (1 + df["return_daily"]).cumprod()
df["div_adj_close"] = (df["adj_close"].iloc[-1] * df["total_return_index"]
                        / df["total_return_index"].iloc[-1])

Price fields and fundamentals fields sit on different bases. Do not mix them by hand.

adj_close is on today's split basis. Fundamentals per-share fields (eps_diluted, dividends_per_share) are as filed, with no split adjustment. Dividing one by the other gives a wrong P/E whenever a split happened between the reporting date and today. Use /v1/metrics, which handles the bases for you, or adjust the fundamentals side first.

Money is in millions of USD on /v1/fundamentals and /v1/metrics, and in whole dollars on /v1/prices and /v1/holdings. market_cap exists on both prices and metrics, on those two different scales.

Path 1 — let an LLM write the code

1. Get your API key (free)
2. pip install -U xfinlink
3. Copy the block below into Claude, ChatGPT or Cursor as context
4. Describe what you want

Loading llms.txt…

Path 2 — connect the MCP server, no code

1. Get your API key (free)
2. Add the server URL below to your AI platform
3. Ask anything — “What’s AAPL’s P/E ratio?”

https://api.xfinlink.com/mcp?api_key=YOUR_API_KEY

Tools: get_prices, get_fundamentals, get_metrics, resolve_ticker, search, get_index, get_index_events, get_insiders, get_holdings, get_manager_holdings, search_managers

Claude (Anthropic)

Web (claude.ai) — Free, Pro, Max, Team and Enterprise plans.

1. Profile icon → Settings → Connectors
2. + → Add custom connector
3. Name xfinlink, URL https://api.xfinlink.com/mcp?api_key=YOUR_API_KEY
4. Create, then start a new chat

Claude Desktop — Settings → Developer → Edit Config, add this, restart:

{
  "mcpServers": {
    "xfinlink": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.xfinlink.com/mcp?api_key=YOUR_API_KEY"]
    }
  }
}

ChatGPT (OpenAI)

Needs Plus, Pro, Team, Enterprise or Edu.

1. Settings → Apps & Connectors → Advanced Settings → turn on Developer Mode
2. Connectors → Create. Name xfinlink, URL https://api.xfinlink.com/mcp?api_key=YOUR_API_KEY, Authentication None
3. New chat → + → More → Developer Mode → Add sources → enable xfinlink

Grok (xAI)

Needs a paid Grok account.

1. Menu → Connectors → Add custom connector
2. Name xfinlink, URL https://api.xfinlink.com/mcp?api_key=YOUR_API_KEY
3. Enable it per conversation

Through the xAI API instead:

from openai import OpenAI

client = OpenAI(
    api_key="your-xai-api-key",
    base_url="https://api.x.ai/v1",
)

response = client.responses.create(
    model="grok-4.20-reasoning",
    input=[{"role": "user", "content": "What's AAPL's quarterly revenue trend?"}],
    tools=[{
        "type": "mcp",
        "server_url": "https://api.xfinlink.com/mcp?api_key=YOUR_API_KEY",
        "server_label": "xfinlink",
    }],
)

Perplexity

Needs Pro, Max or Enterprise.

1. Account Settings → Connectors → + Custom connector → Remote
2. Name xfinlink, URL https://api.xfinlink.com/mcp?api_key=YOUR_API_KEY, Authentication None, Transport Streamable HTTP
3. Tick the acknowledgement, Add, then click the card to enable it
4. In a new search, toggle xfinlink under Sources

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "xfinlink": {
      "url": "https://api.xfinlink.com/mcp?api_key=YOUR_API_KEY"
    }
  }
}

Sign up for a key. See pricing for higher limits.

Errors return JSON with an error code. The Python client raises XfinlinkError with the same message.

{"error":"bad_request","status":400,"detail":"Invalid start date format (YYYY-MM-DD)"}
{"error":"unauthorized","message":"API key required. Get one free at https://xfinlink.com/signup"}
{"error":"not_found","status":404,"detail":"No matching entities for: ZZZZZZ"}
{"error":"Daily limit reached (100 requests/day). Resets at midnight UTC.","retry_after_seconds":28800}