Stocks Cowboy API Documentation

The intelligence layer for AI trading agents. Real-time SEC Form 4 filings, computed signals, and correlated news — via REST or native MCP server.

🤖 Agent-First: Connect in 30 Seconds

Stocks Cowboy is the first insider trading API built natively for AI agents. Every response includes LLM-ready action_prompt fields. No parsing needed.

claude_desktop_config.json
// Add to your MCP settings — works in Claude Desktop, Cursor, Windsurf, etc.
{
  "mcpServers": {
    "stocks-cowboy": {
      "command": "uvx",
      "args": ["stockscowboy-mcp"],
      "env": {
        "STOCKS_COWBOY_API_KEY": "sk_pro_your_key_here"
      }
    }
  }
}
Terminal
# Install the MCP server as a standalone tool
pip install stockscowboy-mcp

# Run with your API key
STOCKS_COWBOY_API_KEY=sk_pro_xxx stockscowboy-mcp
Docker
# Pull and run the containerized MCP server
docker run -e STOCKS_COWBOY_API_KEY=sk_pro_xxx \
  stockscowboy/mcp-server:latest

MCP Tools Reference

Once connected, your AI agent gets access to 4 tools — no code needed. The agent calls them like functions.

TOOL health_check

Verify API connectivity. Returns status, filing count, signal count.

TOOL get_insider_trades

Fetch SEC Form 4 filings by ticker with day/value filters.

TOOL get_market_signals

AI-enriched signals: cluster buys, high conviction, large sales. Each includes an action_prompt.

TOOL get_recent_news

Correlated news for a ticker. Matched to insider activity for contextual analysis.

💡 Every signal response includes an action_prompt field designed to be piped directly into an LLM's reasoning loop — no parsing or transformation needed. Your agent says "get me NVDA signals" and gets back ready-to-reason intelligence.

Example: Agent Conversation

What your agent sees after connecting
User: "What insider activity happened at Tesla this week?"

Agent calls: get_insider_trades(ticker="TSLA", days=7)

Agent calls: get_market_signals(ticker="TSLA", days=7)

Agent responds: "This week, 3 Tesla insiders sold a combined
$24M in shares. The largest was CFO Vaibhav Taneja selling
$12.4M. However, these appear to be planned 10b5-1 sales
and our signal engine filtered them as noise. No high-conviction
buy signals were detected. Current confidence: LOW."

Authentication

All API requests require an API key passed via the X-API-Key header.

Request Header 
X-API-Key: sk_pro_your_api_key_here
💡 Get your API key by subscribing on the pricing page. Paid plans provision live API keys immediately after checkout.

Base URL

All endpoints are relative to:

Base URL
https://stockscowboy.com
📌 API schema is frozen at v1.0.0. All responses include an X-API-Version header. Breaking changes will increment the major version — your integrations won't break unexpectedly.

Rate Limits

Rate limits are enforced per API key on a daily basis. Limits reset at midnight UTC.

Tier Daily Limit MCP Tools Price
Pro 5,000 calls/day All 4 tools $10/mo
Enterprise 50,000 calls/day All 4 tools + priority support $49.99/mo
Design Partner Unlimited All tools + direct Slack $500/mo (limited spots)

When you exceed your limit, the API returns 429 Too Many Requests with a Retry-After header.

Error Codes

Code Meaning
200 Success
400 Bad request — invalid parameters
401 Unauthorized — missing or invalid API key
403 Forbidden — tier doesn't have access
429 Rate limit exceeded
500 Internal server error

GET /v1/trades

Fetch real-time insider trades from SEC Form 4 filings. Returns the most recent trades across all tickers.

Parameters

Parameter Type Required Description
ticker string optional Filter by stock ticker (e.g., AAPL, NVDA)
tx_type string optional Transaction type: P (purchase), S (sale), A (award)
min_value number optional Minimum transaction value in USD
days integer optional Look-back window in days (default: 7)
limit integer optional Max results to return (default: 50)

Example

cURL
curl -H "X-API-Key: YOUR_KEY" \
  "https://stockscowboy.com/v1/trades?ticker=NVDA&days=7"
Python
import requests

response = requests.get(
    "https://stockscowboy.com/v1/trades",
    headers={"X-API-Key": "YOUR_KEY"},
    params={"ticker": "NVDA", "days": 7}
)
print(response.json())
JavaScript
const res = await fetch(
  "https://stockscowboy.com/v1/trades?ticker=NVDA&days=7",
  { headers: { "X-API-Key": "YOUR_KEY" } }
);
const data = await res.json();
console.log(data);

GET /v1/trades/{ticker}

Get all insider trades for a specific ticker symbol.

Path Parameters

Parameter Type Required Description
ticker string required Stock ticker symbol (e.g., AAPL)

Query Parameters

Parameter Type Required Description
days integer optional Look-back window (default: 90)
tx_type string optional Filter by transaction type
cURL
curl -H "X-API-Key: YOUR_KEY" \
  "https://stockscowboy.com/v1/trades/AAPL?days=30"

GET /v1/trades/cluster

Detect coordinated insider buying — multiple insiders purchasing the same stock within a time window. This is the strongest signal for predicting outsized returns.

Parameters

Parameter Type Required Description
window_days integer optional Time window for cluster detection (default: 7)
min_insiders integer optional Minimum number of unique insiders (default: 3)
days integer optional Look-back window (default: 30)
⚡ Cluster buys highlight multiple insiders purchasing the same stock inside a short time window.
cURL
curl -H "X-API-Key: YOUR_KEY" \
  "https://stockscowboy.com/v1/trades/cluster?window_days=7&min_insiders=3"

GET /v1/signals

Computed trading signals with conviction ratings and LLM-ready action prompts. Each signal is enriched with context designed to be piped directly into your AI agent's reasoning loop.

Parameters

Parameter Type Required Description
ticker string optional Filter by ticker
days integer optional Look-back window (default: 7)
min_confidence number optional Minimum confidence score 0.0–1.0

Response

JSON Response
{
  "signals": [
    {
      "id": 42,
      "ticker": "NVDA",
      "signal_type": "cluster_buy",
      "confidence": 0.94,
      "action_prompt": "3 insiders purchased $2.1M of NVDA within 5 days. CEO + CFO + VP Engineering. Correlates with positive H100 supply news. HIGH CONVICTION BUY.",
      "created_at": "2024-05-20T14:22:01Z"
    }
  ],
  "count": 1
}

GET /v1/news/{ticker}

Correlated news articles for a specific ticker. Auto-aggregated from financial sources and matched to insider activity for contextual analysis.

Parameters

Parameter Type Required Description
ticker string required Stock ticker (path parameter)
limit integer optional Max articles to return (default: 50)
cURL
curl -H "X-API-Key: YOUR_KEY" \
  "https://stockscowboy.com/v1/news/TSLA?limit=10"

Quickstart

Get up and running in under 60 seconds.

1. Get your API key

Subscribe on the pricing page to provision your live API key.

2. Make your first request

Python
import requests

# Replace with your API key
API_KEY = "sk_pro_your_key_here"

# Fetch today's highest-conviction signals
response = requests.get(
    "https://stockscowboy.com/v1/signals",
    headers={"X-API-Key": API_KEY},
    params={"days": 7, "min_confidence": 0.8}
)

signals = response.json()["signals"]
for s in signals:
    print(f"{s['ticker']} — {s['signal_type']} — {s['confidence']}")
    print(f"  → {s['action_prompt']}")

3. Pipe into your AI agent

Python — LLM Integration 
from openai import OpenAI

client = OpenAI()

# Get the latest signal
signal = signals[0]

# Send to your AI agent for analysis
completion = client.chat.completions.create(
    model="gpt-4",
    messages=[{
        "role": "system",
        "content": "You are a trading analyst. Analyze this insider trading signal and recommend an action."
    }, {
        "role": "user",
        "content": signal["action_prompt"]
    }]
)

print(completion.choices[0].message.content)

Ready to get started?

Get your API key in 30 seconds.

Get API Key →