Agentic Access

Give Claude, ChatGPT, Codex, Claude Code, Gemini CLI, Cursor or your own scripts live access to Fintwit: AI stock ratings and chart analysis, what investors on X are trending, buying, selling and holding, company financials, insider trades, a stock screener and your own portfolios. Every endpoint is also an MCP tool. Included with Fintwit Pro.

Create your API key

Agentic Access connects your own AI agent to Fintwit data. Looking for Fintwit's built-in assistant? That's the AI Agent.

REST base URL https://fintwit.ai/v1

MCP server https://fintwit.ai/mcp (Streamable HTTP)

OpenAPI https://fintwit.ai/v1/openapi.json

Responses are JSON { data, meta }. Money is USD; fields ending in _pct are percents.

Quick start

curl "https://fintwit.ai/v1/ai-scores?tickers=NVDA,AAPL" \
  -H "Authorization: Bearer fw_YOUR_KEY"

Authentication

Create keys on the API Keys page (Pro). Up to 5 named keys; each is shown once — store it like a password and revoke it if it leaks.

Send the key in one of these ways:

Authorization: Bearer KEY (recommended)
x-api-key: KEY
?key=KEY — for connectors that only accept a URL

New keys can take a couple of minutes to activate.

Authenticated request

curl "https://fintwit.ai/v1/usage" \
  -H "Authorization: Bearer fw_YOUR_KEY"

Rate limits

500 requests per day and 30 per minute, shared across all your keys (days reset 00:00 UTC).
Batch tickers: one get_ai_scores call with 10 tickers counts as 1 request.
MCP handshake messages (initialize, tools/list) and /v1/usage are free.
Personal, non-commercial use. Business or higher volume? Contact us.

Errors

400	bad_request	Invalid parameter — message says which
401	invalid_api_key	Missing or unknown key
403	pro_required / key_revoked	Pro plan ended, or key revoked
404	not_found	Unknown endpoint
429	rate_limited / daily_quota_exceeded	Over 30/min or 500/day

Error response

{
  "error": "bad_request",
  "message": "tickers: between 1 and 10 tickers"
}

Connect an agent

Claude (web, desktop & mobile)

In Claude, open Settings → Connectors → Add custom connector.
Name it Fintwit and paste your connector URL (below). Leave OAuth fields empty.
Start a chat, enable the Fintwit connector from the tools menu, and ask a question.

Custom connectors are available on Claude's paid plans. Connectors added on claude.ai also appear in the Claude desktop and mobile apps.

Connector URL

https://fintwit.ai/mcp?key=fw_YOUR_KEY

Claude Code

Run this once in your terminal, then ask Claude Code about any stock.

Terminal

claude mcp add --transport http fintwit https://fintwit.ai/mcp \
  --header "Authorization: Bearer fw_YOUR_KEY"

ChatGPT

Custom GPT: Explore GPTs → Create → Configure → Create new action.
Import from URL: https://fintwit.ai/v1/openapi.json
Authentication → API Key → Auth type Bearer → paste your key. Save and chat with your GPT.
Or, where ChatGPT offers MCP connectors (developer mode), add a connector with the URL below and no authentication.

Connector URL

https://fintwit.ai/mcp?key=fw_YOUR_KEY

Codex

Add Fintwit to your Codex config at ~/.codex/config.toml (used by the Codex CLI and IDE extension):
Restart Codex; run /mcp to confirm the Fintwit tools are listed.

config.toml

[mcp_servers.fintwit]
url = "https://fintwit.ai/mcp?key=fw_YOUR_KEY"

Gemini CLI

Add Fintwit to ~/.gemini/settings.json (merge into mcpServers if you already have some):
Restart Gemini CLI and run /mcp to confirm the Fintwit tools are listed, then ask about any stock.

settings.json

{
  "mcpServers": {
    "fintwit": {
      "httpUrl": "https://fintwit.ai/mcp",
      "headers": {
        "Authorization": "Bearer fw_YOUR_KEY"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (or Settings → MCP → Add server):

mcp.json

{
  "mcpServers": {
    "fintwit": {
      "url": "https://fintwit.ai/mcp",
      "headers": {
        "Authorization": "Bearer fw_YOUR_KEY"
      }
    }
  }
}

Other agents & scripts

If the agent supports MCP connectors or custom tools by URL, use the connector URL below.
If it supports OpenAPI / custom actions, import https://fintwit.ai/v1/openapi.json with Bearer auth.
Scripts and automations (n8n, Make, Zapier, Python): call the REST API with the Authorization header.

Connector URL

https://fintwit.ai/mcp?key=fw_YOUR_KEY

API reference

AI scores

GET/v1/ai-scores

MCP tool: get_ai_scores

Fintwit's AI rating for up to 10 stocks in one call (counts as 1 request): investment score 0-100, fundamental and technical sub-scores 0-10, risk, sentiment, short/medium/long price targets with dates, and a written rationale. Tickers without a rating return rating: null.

Parameter	Description
tickersstringrequired	Comma-separated US tickers, max 10. e.g. NVDA,AAPL

Request

curl "https://fintwit.ai/v1/ai-scores?tickers=NVDA" \
  -H "Authorization: Bearer fw_YOUR_KEY"

Response

{
  "data": [
    {
      "ticker": "NVDA",
      "company": "NVIDIA Corporation",
      "price": 229.28,
      "rating": {
        "investment_score": 84,
        "fundamental_score": 8,
        "technical_score": 8,
        "risk": "medium",
        "sentiment": "bullish",
        "price_targets": {
          "short": {
            "price": 245,
            "date": "2026-12-14"
          },
          "medium": {
            "price": 270,
            "date": "2027-03-14"
          },
          "long": {
            "price": 295,
            "date": "2027-09-11"
          }
        },
        "rationale": "…",
        "rated_on": "2026-09-14"
      }
    }
  ],
  "meta": {
    "endpoint": "get_ai_scores",
    "as_of": "2026-10-11T07:41:21Z",
    "requests_today": 12
  }
}

AI chart analysis

GET/v1/chart-analysis

MCP tool: get_chart_analysis

Fintwit's AI read of each stock's 3-month chart: trend and confidence, key support/resistance levels, momentum, positive/negative context and a plain-English narrative. Each analysis is valid for 24 hours; if none exists it is generated on the spot (usually a few seconds). If generation is still running, the ticker returns status: "generating" — call again in ~30 seconds.

Parameter	Description
tickersstringrequired	Comma-separated US tickers, max 5

Request

curl "https://fintwit.ai/v1/chart-analysis?tickers=RH" \
  -H "Authorization: Bearer fw_YOUR_KEY"

Response

{
  "data": [
    {
      "ticker": "RH",
      "status": "ready",
      "generated_at": "2026-10-11T17:10:35Z",
      "analysis": {
        "timeframe": "3M",
        "asOf": "2026-10-09",
        "currentPrice": 116.99,
        "cards": {
          "trend": {
            "status": "Downtrend",
            "confidence": 67
          }
        },
        "narrative": {
          "whatsHappening": "RH has been moving lower over the last three months…"
        }
      }
    }
  ],
  "meta": {
    "endpoint": "get_chart_analysis"
  }
}

Most bought / sold on X

GET/v1/signals/most-bought · /v1/signals/most-sold

MCP tool: get_most_bought / get_most_sold

Stocks the most tracked investors on X reported buying (or selling and trimming) within the window, ranked by investors_pct — the percent of all investors Fintwit tracks who reported the trade.

Parameter	Description
windowstring	3d (default), 7d or 30d
sectorstring	e.g. TECHNOLOGY, HEALTHCARE
min_market_capinteger	Minimum market cap in USD
limit / offsetinteger	Page size 1-100 (default 25) / rows to skip

Request

curl "https://fintwit.ai/v1/signals/most-bought?window=7d&limit=10" \
  -H "Authorization: Bearer fw_YOUR_KEY"

Response

{
  "data": [
    {
      "rank": 1,
      "ticker": "MU",
      "company": "Micron Technology Inc",
      "sector": "TECHNOLOGY",
      "market_cap": 1169870553000,
      "price": 1029,
      "change_pct": -0.66,
      "perf_30d_pct": 0.12,
      "investors_pct": 2.31,
      "last_mentioned": "2026-10-08T17:01:17Z"
    }
  ],
  "meta": {
    "window": "7d",
    "limit": 10,
    "offset": 0
  }
}

Top holdings on X

GET/v1/signals/top-holdings

MCP tool: get_top_holdings

Stocks most widely held across portfolios shared by investors on X. holders_pct is the percent of those portfolios that hold the stock.

Parameter	Description
sectorstring	Sector filter
limit / offsetinteger	1-100 / rows to skip

Request

curl "https://fintwit.ai/v1/signals/top-holdings?limit=20" \
  -H "Authorization: Bearer fw_YOUR_KEY"

Response

{
  "data": [
    {
      "rank": 1,
      "ticker": "META",
      "company": "Meta Platforms Inc.",
      "holders_pct": 29.14,
      "price": 718.67,
      "perf_30d_pct": 9.94
    }
  ],
  "meta": {
    "limit": 20,
    "offset": 0
  }
}

Financial statements

GET/v1/financials

MCP tool: get_financials

Income statement, balance sheet or cash flow, most recent period first, all values in USD with margins and YoY growth in percent.

Parameter	Description
tickerstringrequired	US ticker, e.g. MSFT
statementstring	income (default), balance or cashflow
periodstring	annual (default) or quarterly
limitinteger	Periods to return, 1-10 (default 5)

Request

curl "https://fintwit.ai/v1/financials?ticker=MSFT&statement=income&limit=1" \
  -H "Authorization: Bearer fw_YOUR_KEY"

Response

{
  "data": [
    {
      "period_end": "2026-06-30",
      "fiscal_period": "FY",
      "revenue": 331839000000,
      "revenue_growth_yoy_pct": 17.79,
      "gross_margin_pct": 67.94,
      "operating_income": 155237000000,
      "operating_margin_pct": 46.78,
      "net_income": "…"
    }
  ],
  "meta": {
    "ticker": "MSFT",
    "statement": "income",
    "period": "annual",
    "currency": "USD"
  }
}

Insider trades

GET/v1/insider-trades

MCP tool: get_insider_trades

SEC Form 4 open-market purchases and sales by company insiders — a company's 50 most recent, or market-wide for the last 30 days (newest and largest first).

Parameter	Description
tickerstring	Omit for market-wide
typestring	buy, sell or all (default)
ceo_onlyboolean	Market-wide: CEO trades only
limit / offsetinteger	1-100 (default 25) / rows to skip

Request

curl "https://fintwit.ai/v1/insider-trades?type=buy&limit=25" \
  -H "Authorization: Bearer fw_YOUR_KEY"

Response

{
  "data": [
    {
      "ticker": "QTEX",
      "company": "QTREX Quantum Ltd.",
      "transaction_date": "2026-10-09",
      "type": "buy",
      "insider": "Ben-Noon Dagi Shahar",
      "role": "director, Chief Executive Officer",
      "is_ceo": true,
      "shares": 18181,
      "price": 1.67,
      "value_usd": 30362,
      "sec_filing_url": "https://www.sec.gov/…"
    }
  ],
  "meta": {
    "limit": 25,
    "offset": 0,
    "window": "30d"
  }
}

Stock screener

GET/v1/screener

MCP tool: screen_stocks

Screen active US stocks by fundamentals and Fintwit AI score. All filters optional and combined with AND; percents are in percent (5 = 5%).

Parameter	Description
sectorstring	Sector
min_market_cap / max_market_capinteger	USD
max_peinteger	Max trailing P/E
min_ai_scoreinteger	0-100
min_dividend_yieldinteger	Percent
min_revenue_growthinteger	Latest quarter YoY, percent
sort_bystring	market_cap (default), ai_score, pe, dividend_yield, revenue_growth, change_pct
order / limit / offset	desc\|asc · 1-100 · rows to skip

Request

curl "https://fintwit.ai/v1/screener?sector=TECHNOLOGY&min_ai_score=80&sort_by=ai_score&limit=3" \
  -H "Authorization: Bearer fw_YOUR_KEY"

Response

{
  "data": [
    {
      "ticker": "BOX",
      "company": "Box Inc",
      "sector": "TECHNOLOGY",
      "market_cap": 4898067000,
      "ai_score": 87,
      "ai_risk": "medium",
      "pe_trailing": 51.74,
      "pe_forward": 17.61,
      "revenue_growth_qtr_yoy_pct": 9.23
    }
  ],
  "meta": {
    "limit": 3,
    "offset": 0,
    "total": 41
  }
}

Your portfolios

GET/v1/portfolios

MCP tool: get_portfolios

The portfolios in your own Fintwit account — manual and broker-synced — with holdings count, market value, cost basis, today's change, unrealized gain, and Fintwit's AI portfolio analysis: rating, overall assessment, alignment with your goals and risk level, each with the AI's reasoning. Only your data is ever returned.

Request

curl "https://fintwit.ai/v1/portfolios" \
  -H "Authorization: Bearer fw_YOUR_KEY"

Response

{
  "data": [
    {
      "portfolio_id": "26549",
      "name": "Robinhood Roth IRA",
      "source": "brokerage",
      "holdings": 8,
      "market_value": 98914.56,
      "cost_basis": 83825.9,
      "day_change": 412.3,
      "day_change_pct": 0.42,
      "unrealized_gain": 15088.66,
      "unrealized_gain_pct": 18,
      "ai_rating": 7,
      "ai_analysis": {
        "rating": 7,
        "overall": "The portfolio is heavily concentrated in technology and infrastructure…",
        "alignment": "High",
        "alignment_reason": "…",
        "risk_level": "High",
        "risk_reason": "…",
        "analyzed_on": "2026-10-10"
      }
    }
  ],
  "meta": {
    "currency": "USD"
  }
}

Portfolio holdings

GET/v1/portfolios/holdings

MCP tool: get_portfolio_holdings

Positions in your portfolio(s): shares, price, market value, cost basis, today's change, unrealized gain, weight in the portfolio, the stock's Fintwit AI score, and the AI's recommendation for that position (Buy / Hold / Sell) with its reasoning. Omit portfolio_id for all portfolios.

Parameter	Description
portfolio_idstring	From /v1/portfolios; omit for every portfolio

Request

curl "https://fintwit.ai/v1/portfolios/holdings?portfolio_id=26549" \
  -H "Authorization: Bearer fw_YOUR_KEY"

Response

{
  "data": [
    {
      "portfolio_id": "26549",
      "portfolio": "Robinhood Roth IRA",
      "ticker": "CRDO",
      "company": "Credo Technology",
      "type": "equity",
      "shares": 65.04,
      "price": 211.9,
      "market_value": 13781.38,
      "cost_basis": 10000.9,
      "unrealized_gain": 3780.48,
      "unrealized_gain_pct": 37.81,
      "weight_pct": 13.93,
      "ai_score": 81,
      "ai_recommendation": "Buy",
      "ai_recommendation_reason": "Consistent earnings outperformance and secular growth in data center networking…"
    }
  ],
  "meta": {
    "currency": "USD",
    "portfolios": 1
  }
}

Portfolio recommendations

GET/v1/portfolios/recommendations

MCP tool: get_portfolio_recommendations

Stocks Fintwit's AI recommends adding to your portfolio(s), personalised to each portfolio's holdings and your preferences, with the AI's reasoning, current price and AI score.

Parameter	Description
portfolio_idstring	From /v1/portfolios; omit for every portfolio

Request

curl "https://fintwit.ai/v1/portfolios/recommendations?portfolio_id=26549" \
  -H "Authorization: Bearer fw_YOUR_KEY"

Response

{
  "data": [
    {
      "portfolio_id": "26549",
      "portfolio": "Robinhood Roth IRA",
      "ticker": "DELL",
      "company": "Dell Technologies Inc",
      "price": 562.89,
      "ai_score": 87,
      "ai_risk": "medium",
      "reasoning": "The company is benefiting from a massive surge in AI-server demand…",
      "recommended_on": "2026-10-10"
    }
  ],
  "meta": {
    "portfolios": 1
  }
}

Usage

GET/v1/usage

MCP tool: get_usage

Requests used and remaining today. Free — does not count toward your limit.

Request

curl "https://fintwit.ai/v1/usage" \
  -H "Authorization: Bearer fw_YOUR_KEY"

Response

{
  "data": {
    "requests_today": 12,
    "daily_limit": 500,
    "remaining_today": 488,
    "per_minute_limit": 30,
    "resets_at": "2026-10-11T23:59:59Z"
  }
}

Agentic Access

Authentication

Rate limits

Errors

Claude (web, desktop & mobile)

Claude Code

ChatGPT

Codex

Gemini CLI

Cursor

Other agents & scripts

AI scores

AI chart analysis

Trending on X

Most bought / sold on X

Top holdings on X

Financial statements

Insider trades

Stock screener

Your portfolios

Portfolio holdings

Portfolio recommendations

Usage