Drillr — Financial Research for Agents

Drillr exposes its AI research agent and financial data pipeline to external agents through three equivalent channels: MCP (Streamable HTTP), REST API, and a command-line tool. All three accept the same drl_* API key and expose the same data.

What you can do

• search — Ask natural-language questions about companies, sectors, tickers, filings, earnings. Runs server-side for 5-15s and returns a synthesized answer with source attribution.
• signals — Browse a curated feed of high-score market events (news + filings + alerts), filterable by ticker / sector / date.
• articles — Read published analyst articles with related-ticker, sector, and reference metadata.
• watchlists — Create, list, and mutate per-user ticker collections. Persisted across sessions on the user's Drillr account.

---

Detecting the deployment context

Your onboarding path depends on ONE question:

Can the user run shell commands on the machine where you are running, and see the output directly in the same conversation?

Physical hardware doesn't matter. A Mac mini, MacBook, home NAS, Raspberry Pi, or cloud VM can all serve either path. What matters is whether the user's current channel to you is co-located with your shell or relayed through a chat channel.

Path A — Indirect (relayed)

Signals that suggest Path A:

• User is chatting with you via Telegram / WhatsApp / Slack / Discord / a web chat UI / any IM
• Your input channel is text-only — you have no shared terminal
• User mentions they're on a phone, or away from the host machine
• Your runtime is a bot webhook (e.g. Telegram bot handler)
• The user cannot paste the output of ls ~/.config/ back to you

→ Use Onboarding A below.

Path B — Direct (co-located)

Signals that suggest Path B:

• You are running as Claude Code, a local Claude Agent SDK session, or any CLI the user is typing into right now
• You have a Bash / shell tool and anything you run is visible to the user in the same pane
• The user can copy-paste your suggested export or config-edit commands and run them immediately

→ Use Onboarding B below.

When unsure, ask the user

Quick setup question: are you talking to me through a terminal on the same machine I'm running on — where I can suggest shell commands for you to run — or through a separate channel like Telegram / WhatsApp / a web chat?

---

Prerequisites — getting an API key

Do NOT attempt any tool call until you have a drl_* key accessible to your runtime. If it's missing, run the onboarding path that matches your deployment context.

Onboarding A — Indirect (IM / web chat / remote host)

The user reaches you through a text-only relay and cannot touch your filesystem. They will complete the key creation from whatever browser they have (phone, tablet, or desktop) and paste the key back to you.

Step 1 — Tell the user (verbatim):

To use Drillr I need an API key. From any browser (your phone is fine):

1. Open https://drillr.ai/developer/keys
2. Sign in — Google sign-in is the quickest; email/password also works
3. Tap "Create API key" → give it a name (e.g. "my-agent") → copy the drl_... string
4. Paste it back to me here. The key is shown only once.

After I confirm it works, you can delete your message.

Step 2 — When the key arrives, persist it:

Write it to ~/.config/drillr/config.json with file mode 0600:

{ "api_key": "drl_..." }

Equivalent shell:

mkdir -p ~/.config/drillr
umask 077
cat > ~/.config/drillr/config.json <<EOF
{ "api_key": "$KEY" }
EOF
chmod 600 ~/.config/drillr/config.json

Step 3 — Verify the key works:

curl -sS -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer drl_..." \
  https://gateway.drillr.ai/api/v1/watchlists

Expect HTTP 200. On 401, the key is invalid — apologize, ask the user to regenerate, and rerun Step 1.

Step 4 — Confirm to the user, masked:

Stored drl_xxxxxxxx_...e9f2. You can safely delete your message now.

Rules:

• Never echo the full key back to the user
• Never write the key into conversation logs, prompts, or scratchpads
• Never commit it to any file other than ~/.config/drillr/config.json
• If storage fails (permission denied, etc.), tell the user the exact error — don't silently hold the key in memory

Onboarding B — Direct (terminal co-located with user)

The user can run shell commands and see their output. Pick ONE of the three equivalent options and instruct the user accordingly. All three expect the same drl_* key created at https://drillr.ai/developer/keys.

B1. MCP via Claude Code (recommended for Claude Code users)

Tell the user:

1. Create an API key at https://drillr.ai/developer/keys (Google sign-in is easiest)

2. Add to ~/.claude.json (or merge into the existing mcpServers object):

   {
     "mcpServers": {
       "drillr": {
         "type": "http",
         "url": "https://gateway.drillr.ai/mcp",
         "headers": {
           "Authorization": "Bearer ${DRILLR_API_KEY}"
         }
       }
     }
   }
   

3. Add export DRILLR_API_KEY=drl_... to your shell rc (~/.zshrc / ~/.bashrc) and restart the shell

4. Restart Claude Code. /mcp should list drillr as connected.

B2. CLI

npm install -g drillr-cli
drillr auth set-key drl_...
drillr watchlist list     # verify: should list (or print "no watchlists yet")

B3. REST with env var

export DRILLR_API_KEY=drl_...
curl -H "Authorization: Bearer $DRILLR_API_KEY" \
     https://gateway.drillr.ai/api/v1/watchlists

---

Choosing a channel (after onboarding completes)

Pick based on your runtime's capabilities:

Runtime characteristic	Preferred channel
Has native MCP client support	MCP
HTTP only (no MCP, no shell)	REST
Shell / subprocess available	CLI or REST

All three are equivalent in data and rate limit. MCP tool names operate by natural names (e.g. watchlist by name); REST uses UUIDs.

---

Capabilities

Research & data lookup — search

Ask natural-language questions about companies, tickers, sectors, filings, earnings. Runs 5-15s server-side and returns markdown text with source references.

Channel	Call
MCP	search({ question, session_id?, context? })
REST	POST /api/v1/search with { question, session_id?, stream? }
CLI	drillr search "<question>"

Session continuity: pass the returned session_id in the next call to continue the same research conversation. Use context to pass background info that refines the answer.

Data coverage:

• Market data — real-time quotes, historical OHLCV, index prices & composition (S&P 500, Dow, NASDAQ 100)
• Fundamentals — income / balance / cash flow statements (quarterly & annual), valuation ratios, company snapshots
• Earnings — call transcripts with AI summaries, calendar with EPS/revenue estimates vs actuals
• Analyst research — ratings & price targets (~550K events from 500+ firms), consensus rollups
• SEC filings — semantic search across 10-K, 10-Q, 8-K, 20-F, 6-K, S-1, F-1
• Corporate events — M&A, debt issuance, securities offerings
• People & governance — executive profiles, compensation, appointments & departures
• Ownership — insider trades (Form 3/4/5), institutional holdings (13F-HR, 13D/G)
• News — aggregated financial news with importance scoring
• Company discovery — by industry, product, technology, business model, supply chain
• Alternative data — energy, data centers, semiconductors, compute & inference pricing, AI model development, platform adoption, sentiment, macro & trade, patents

When to use search:

• Stock prices, company financials, market data
• SEC filing content (risk factors, revenue breakdown, MD&A)
• Earnings summaries or analyst consensus
• Insider trading or institutional ownership
• Alternative data (AI value chain, energy, semiconductors)
• Compare companies or sectors

Example questions that work well:

• "What is AAPL's current PE ratio, and how does it compare to MSFT?"
• "Summarize NVDA's latest 10-Q earnings"
• "Which semiconductor companies had insider buying this month?"

Signals — signals

A curated investment-event feed. Each signal is one market event (one SUBJECT × one ACTION × one TIME), already aggregated across outlets — you get one record per event, not one per article.

Coverage — sources rolled into the feed:

• News & wires: Finnhub, NewsAPI, GDELT, FMP, Bloomberg, Reuters, WSJ, FT, CNBC
• Filings: SEC 8-K, 13D/G, 6-K (foreign issuers), structured 8-K earnings data, earnings-call summaries
• Corporate disclosure: press releases
• Macro & policy: Fed / FOMC / BOJ / ECB / SEC / White House / Truth Social
• Market microstructure: analyst ratings, insider trading, intraday price movers
• Social: select financial subreddits

Freshness: signals appear within ~3–5 minutes of the originating event.

Channel	Call
MCP	signals({ tickers?, sector?, since?, limit?, offset? })
REST	GET /api/v1/signals?tickers=AAPL,MSFT&sector=Technology&since=...&limit=20
CLI	drillr signals --tickers AAPL,MSFT --limit 5

Response shape: { headline, summary, suggested_tickers[], sector[], created_at }, ordered newest first.

Articles — article_list / article_get

Research articles spanning company-specific analysis, event coverage, and industry trackers.

What you'll find:

• Company & thesis — focused single-name or small-group analysis (1–3 tickers), peer comparisons, annual ticker theses, SEC-filing follow-ups
• Event coverage — postmortems on what just happened, watch-pieces on pending events (policy decisions, upcoming earnings, lawsuits), follow-up checkpoints on previously covered events, macro-event analysis
• Industry & sector — thematic industry pieces (≥5 names), recurring sector trackers

Channel	Call
MCP	article_list({ ticker?, tag?, limit?, offset? }) / article_get({ article_id })
REST	GET /api/v1/articles?ticker=NVDA&limit=10 / GET /api/v1/articles/:id
CLI	drillr articles list --ticker NVDA / drillr articles get <uuid>

article_get returns the article body (markdown), plus topics and references arrays. article_list returns 11 public fields per row (id, title, summary, content, related_tickers, tags, sector, citation, published_at, created_at, word_count).

Watchlists

Per-user ticker collections. Owner-isolated (RLS): each key only sees and mutates its owner's watchlists. Attempting to access another user's watchlist by UUID returns 404, not 403.

MCP (by name)	REST (by UUID)
watchlist_list	GET /api/v1/watchlists
watchlist_create({ name, tickers? })	POST /api/v1/watchlists
watchlist_add({ ticker, watchlist_name? })	POST /api/v1/watchlists/:id/tickers
watchlist_remove({ ticker, watchlist_name? })	DELETE /api/v1/watchlists/:id/tickers/:ticker
watchlist_delete({ watchlist_name })	DELETE /api/v1/watchlists/:id

CLI: drillr watchlist {list|create|add|remove|delete} — see drillr watchlist --help.

MCP tools accept watchlist names (chat-friendly). REST uses UUIDs (URL-friendly). If watchlist_name is omitted on add, a default "My Watchlist" is used (created on miss).

---

Typical workflows

"Daily research briefing"

User: "Can you do a daily morning briefing on my portfolio?"

1. watchlist_list — see what tickers the user already tracks
2. If empty, ask the user for tickers; then watchlist_create
3. Each morning, execute in order:
   • signals({ tickers: [...watchlist_tickers], since: "<24h-ago ISO>" })
   • For any high-interest signal, search({ question: "Deeper context on <headline>" })
   • article_list({ ticker: ... }) for any ticker with fresh activity
4. Synthesize into a chat-sized briefing (headline + 1-2 sentences + links)

"Quick lookup"

User: "What's Nvidia's market cap?"

1. search({ question: "What is NVDA's current market cap?" })
2. Relay the answer and any cited sources

"Sector scan"

User: "Any interesting biotech moves this week?"

1. signals({ sector: ["Health Care"], since: "<7d-ago ISO>", limit: 30 })
2. For each signal the user asks about, article_list({ ticker }) or a follow-up search with session_id from the prior call

---

Error handling

HTTP	code string	What to do
400	invalid_body / invalid_query / invalid_id	Fix parameter shape and retry (don't pester the user)
401	unauthenticated / key_invalid	Re-read the stored key; if still 401, rerun Prerequisites — the key is absent or wrong
401	key_revoked	Tell the user their key was revoked; they need to create a new one at the developer portal
401	key_expired	Tell the user their key expired; same fix
403		Key is valid but lacks external scope — user needs to issue a different key
404	not_found	Resource doesn't exist, or RLS hides it (someone else's). Do NOT assume just-deleted
429		Inspect retry_after_seconds in the body; sleep and retry
502	upstream_error	Transient data-source failure; retry once after 2-3s, then surface to user

On any 401: re-read ~/.config/drillr/config.json or the DRILLR_API_KEY env var BEFORE asking the user. You have the configuration — diagnose first, then instruct.

Never tell the user to "check their configuration."

---

Rate limits

30 requests per minute per API key. On 429 the response body includes retry_after_seconds (1-60s). For workflows that fan out (e.g., scanning a 50-ticker watchlist), pace at ≤0.5 req/s or batch via a single search or signals call with multiple tickers.

---

Advanced

Drillr also supports OAuth 2.1 for MCP clients that implement Dynamic Client Registration (e.g., Claude Code's built-in MCP OAuth). This skill deliberately does not cover that path because:

• OAuth access tokens expire hourly and require client-side refresh that not all MCP runtimes implement correctly
• The browser callback step assumes the user and agent share a machine; Path A deployments (remote host / IM-driven) cannot complete it

For agent automation, prefer the drl_* API key flow above. If you are a human user setting up Claude Code on your own laptop and prefer the OAuth UX, see the Drillr developer portal (https://drillr.ai/developer/docs).

---

Reference

• Developer portal: https://drillr.ai/developer
• Create / manage API keys: https://drillr.ai/developer/keys
• Full API reference: https://drillr.ai/developer/docs
• Gateway base URL: https://gateway.drillr.ai
• MCP endpoint: https://gateway.drillr.ai/mcp
• CLI on npm: drillr-cli (npm install -g drillr-cli)

Tracks External API v1 (2026-04). Breaking changes will ship as /api/v2/* alongside /api/v1/*.