---
name: marketintell
description: AI analyst desk for stocks, options, and crypto. Use this skill to query MarketIntell API for natural-language market analysis with sourced citations, conviction scoring, and trade setups (entry/stop/targets) across crypto and US equities. Agent-native — PoW signup, MCP server, REST + SSE, structured JSON outputs. Use when the user asks about stocks, options, crypto, trade setups, market analysis, NVDA, AAPL, BTC, ETH, options flow, earnings, technical levels, on-chain data, or autonomous trading.
license: Proprietary. https://marketintell.ai/terms
compatibility: Requires curl or any HTTP client. Optional MCP host (Claude Code, Cursor, OpenClaw). API key via PoW self-registration or signup at marketintell.ai.
metadata:
  author: MarketIntell
  version: "1.1"
  base_url: https://api.marketintell.ai
  mcp_url: https://api.marketintell.ai/mcp/sse
  homepage: https://marketintell.ai
allowed-tools: Bash(curl:*) Read
---

# MarketIntell API

**The AI analyst desk for stocks, options, and crypto.** We don't sell research software — we sell the trade. Proof: an autonomous Polymarket bot has been calling this API since March 2026, deploying real USDC on-chain. Live record at wallet `0x0Cbf3EDaa604DCa2BC45E06c3469D66Bb4BC5A66`: 11 markets, 11 won, +$981 net (+23.4% on $4,197 deployed). Small sample, 100% so far — verify in one click at polymarket.com/profile/0x0Cbf3EDaa604DCa2BC45E06c3469D66Bb4BC5A66.

The HOW is agent-native. An agent can discover this API at `marketintell.ai/skill.md`, sign up via SHA-256 proof-of-work, and place its first analyzed trade in under 5 seconds.

Natural-language questions route through an 8-step Chain-of-Thought pipeline backed by 27+ external services (CoinGecko, CoinGlass, LunarCrush, Nansen, DeFiLlama, Polymarket, Yahoo Finance, Hyperliquid, Massive, Twelve Data, Financial Datasets, FRED, SEC EDGAR, Exa, xAI Grok, X/Twitter, Firecrawl, Dome, and more). Every answer ships with sourced citations, a conviction score, and a complete trade setup (direction, entry, stop, targets).

# Why agents pick MarketIntell

| Agents need | MarketIntell ships |
|---|---|
| Machine-readable interface | REST `/v1/chat`, SSE streaming, JSON-schema outputs |
| MCP-native tools | Production MCP at `https://api.marketintell.ai/mcp/sse` — 13 tools: `chat`, `chat_deep`, `alpha_signals`, `signal_performance`, `screener`, `portfolio_list`, `portfolio_create`, `portfolio_analyze`, `sessions_list`, `billing_status`, `health`, `register_challenge`, `register`. Diagnostics: `/mcp/diagnostics` |
| Programmatic signup | `POST /v1/auth/challenge` → SHA-256 PoW → key in 2 seconds |
| No human required | The Polymarket bot has been live-trading real USDC since Mar 2026 — 11/11 markets won so far, on-chain |
| Structured outputs | `response_format: json_schema` returns parseable JSON, not prose |
| Proof it works | +$981 real USDC, 11/11 markets won (small sample), on-chain auditable wallet |

Two asset domains:

- **`crypto`** — tokens, derivatives, on-chain, smart money, prediction markets
- **`us_equities`** — stocks + options across S&P 500 and major US tickers: earnings, options flow, institutional flow, sector rotation, fundamentals

Base URL: `https://api.marketintell.ai`

## Authentication

Include in all requests:

```
Authorization: Bearer <key>
```

Keys start with `mi_` and are shown only once at signup. Store securely.

### Agent Self-Registration (Recommended)

Obtain a key autonomously via proof-of-work challenge:

**Step 1 — Get challenge:**

```bash
CHALLENGE=$(curl -s -X POST https://api.marketintell.ai/v1/auth/challenge \
  -H "Content-Type: application/json")
echo "$CHALLENGE" | jq .
# → { challenge_id, prefix, difficulty: 4, algorithm: "sha256", expires_in: 300 }
```

**Step 2 — Solve proof-of-work:**

```bash
CID=$(echo "$CHALLENGE" | jq -r '.data.challenge_id')
PREFIX=$(echo "$CHALLENGE" | jq -r '.data.prefix')

NONCE=$(python3 -c "
import hashlib
prefix='$PREFIX'; nonce=0
while True:
    if hashlib.sha256((prefix+str(nonce)).encode()).hexdigest().startswith('0000'):
        print(nonce); break
    nonce += 1
")
echo "Solved: nonce=$NONCE"
```

**Step 3 — Signup with solution:**

```bash
SIGNUP=$(curl -s -X POST https://api.marketintell.ai/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"my-agent\",\"challenge_id\":\"$CID\",\"nonce\":\"$NONCE\",\"agent\":\"openclaw\"}")
echo "$SIGNUP" | jq .
# → { key: "mi_k_...", claim_url: "/v1/auth/claim/<id>" }
```

Save the key — it is returned exactly once. Challenge-verified signups bypass IP rate limits.

### Simple Signup (Rate Limited)

For quick access without proof-of-work (3 per hour per IP):

```bash
curl -s -X POST https://api.marketintell.ai/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "email": "agent@example.com"}'
```

### Human Key Claim

Associate an agent-created key with your email:

```bash
curl -s -X POST https://api.marketintell.ai/v1/auth/claim/<KEY_ID> \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'
```

## Diagnostics

```bash
# Without auth — health + version + endpoints
curl -s https://api.marketintell.ai/v1/doctor | jq .

# With auth — adds key info, quota, tier, provider health
curl -s https://api.marketintell.ai/v1/doctor \
  -H "Authorization: Bearer $API_KEY" | jq .
```

## Endpoints

### POST /v1/chat (Primary)

Ask any market question in natural language. Returns multi-specialist analysis with trade setups, source citations, and conviction scoring.

```bash
# Crypto query
curl -s -X POST https://api.marketintell.ai/v1/chat \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Should I long or short ETH right now?"}'

# US equities query
curl -s -X POST https://api.marketintell.ai/v1/chat \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Why is NVDA underperforming the SOX?", "domain": "us_equities"}'

# Options flow query (US equities)
curl -s -X POST https://api.marketintell.ai/v1/chat \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Unusual options flow on TSLA today", "domain": "us_equities"}'
```

**Request body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `message` | string | yes | Natural language query (1–10,000 chars) |
| `domain` | enum | no | `crypto` \| `us_equities`. Auto-detected if omitted. |
| `mode` | enum | no | `fast` (default, T1 agent) or `deep` (T3 supervisor — multi-specialist debate). |
| `session_id` | string (uuid) | no | Continue a conversation. Auto-created if null. |
| `stream` | boolean | no | SSE streaming. Default false. |
| `response_format` | object | no | `{"type":"text"}` (prose) or `{"type":"json_schema","json_schema":{"name":"trade_setup"}}` (structured JSON) |

For structured output, supply both `json_schema.name` (string label) and `json_schema.schema` (a JSON Schema object describing the response shape). Example: `{"type":"json_schema","json_schema":{"name":"trade_setup","schema":{"type":"object","properties":{"direction":{"type":"string"},"entry":{"type":"number"},"stop":{"type":"number"},"targets":{"type":"array","items":{"type":"number"}}}}}}`. The schema is required.

**Response:**

```json
{
  "success": true,
  "data": {
    "session_id": "uuid",
    "content": "Full markdown analysis with trade setup, entry/stop/targets...",
    "structured_output": null,
    "specialists_used": ["technical", "derivatives", "market_state"],
    "latency_ms": 2345,
    "correlation": {
      "alignment": "BULLISH",
      "score": 7.5,
      "confirming": ["Strong momentum above key EMAs", "Positive funding rates"],
      "contradicting": ["Macro headwinds from DXY strength"]
    }
  }
}
```

**Specialist routines (26 across 2 domains):**

| Domain | Specialists |
|--------|-------------|
| Universal (engine vocab) | `technical`, `derivatives`, `macro`, `social`, `smart_money`, `polymarket`, `fundamentals`, `defi`, `trenches`, `market_state`, `research`, `reasoning`, `correlation` |
| Crypto plugin | `price_movement`, `microstructure`, `social_sentiment`, `onchain`, `hyperliquid`, `nansen_deep`, `investigation` |
| US equities + options plugin | `institutional`, `earnings`, `sector`, `options_flow`, `news_sentiment`, `prediction` |

**Example queries:**

Stocks + options (US):
- "Why is NVDA underperforming the SOX?"
- "Show me unusual options flow on TSLA"
- "What does the VIX term structure say about S&P risk?"
- "Compare AAPL vs MSFT earnings momentum"
- "Best sector rotation right now"
- "Put/call skew on QQQ heading into FOMC"

Crypto:
- "Should I long or short BTC here?"
- "ETH key support/resistance levels"
- "Hyperliquid funding rates for SOL"
- "What are whales buying right now?"
- "Polymarket odds on BTC 100k?"
- "Best DeFi yields right now"

### Other Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/v1/alpha?limit=20&offset=0&domain=crypto` | Alpha signals with direction, entry, stop, targets |
| GET | `/v1/alpha/performance` | Signal accuracy stats (1h/4h/24h win rates) |
| GET | `/v1/alpha/confluence` | Multiple signals aligning on same token/direction |
| GET | `/v1/alpha/backtest?hours=24` | Backtest recent signals (max 168h) |
| POST | `/v1/screener` | Token/equity screener (mode: fundamental/momentum) |
| GET | `/v1/leaderboard?domain=crypto&window=30d` | Public win-rate stats by signal/domain (window: `30d` \| `90d` \| `180d`) |
| GET | `/v1/sessions` | List conversation sessions |
| POST | `/v1/sessions/:id/messages` | Continue a session |
| GET | `/v1/portfolio` | List portfolios |
| POST | `/v1/portfolio` | Create portfolio with holdings |
| POST | `/v1/portfolio/:id/analyze` | AI-powered portfolio analysis |
| GET | `/v1/tokens` | List all supported tokens (crypto + equities universe) |
| GET | `/v1/tokens/:symbol` | Token details (pairs, leverage, aliases) |
| GET | `/v1/auth/me` | Key info, tier, quota, scopes |
| POST | `/v1/auth/challenge` | Get PoW challenge for signup |
| POST | `/v1/auth/signup` | Create API key |
| POST | `/v1/auth/claim/:keyId` | Human claims agent-created key |
| GET | `/health` | Basic health check (no auth) |

## Tiers

The platform has four tiers in the ladder `free < builder < pro < enterprise`. During the YC partner walk-through window the platform runs in **demo mode** — every signup gets the full feature surface (no rate, scope, daily-quota, or model gates). Production tier policy below applies once demo mode is disabled.

| Tier | Queries/Day | Rate Limit | Model | Scopes |
|------|-------------|------------|-------|--------|
| Free | 20 | 60 req/min | Sonnet 4 | `read`, `chat` |
| Builder ($49/mo) | 5,000 | 120 req/min | Sonnet 4 | + `alpha` (programmatic API tier) |
| Pro ($99/mo) | 25,000 | 300 req/min | Opus 4.5 | + `webhooks` (full CoT, deep mode, agent dashboard) |
| Enterprise (from $5k/mo) | unlimited | 1000 req/min | Opus 4.5 | All scopes (SLA, white-label, on-prem option) |

**Demo mode** (currently active): every key behaves like enterprise — unlimited queries, every scope, Opus 4.5, deep-mode T3 supervisor open to all, every alpha endpoint open. Toggle off via the `DEMO_MODE` env flag on the API.

## Rate Limiting

All responses include:

```
X-RateLimit-Limit: <max requests per window>
X-RateLimit-Remaining: <remaining in current window>
X-RateLimit-Reset: <seconds until window resets>
```

On `429 Too Many Requests`: read `X-RateLimit-Reset` header and wait that many seconds.

## Data Sources

27+ external services across 8 categories:

| Category | Sources |
|----------|---------|
| Market data | CoinGecko, DexScreener, Messari, TwelveData, Yahoo Finance |
| On-chain | DefiLlama, Nansen, Snapshot |
| Derivatives | Hyperliquid, CoinGlass, Massive |
| Social / search | LunarCrush, X/Twitter, xAI Grok, Exa, Firecrawl |
| Prediction markets | Polymarket, Kalshi, Manifold |
| Macro | FRED, Alpha Vantage, Finnhub, Massive (forex/options/stocks) |
| Fundamentals | FinancialDatasets, SEC EDGAR, Token Unlocks |
| Infrastructure | Dome, RTDS |

## Error Handling

```json
{
  "success": false,
  "error": "Human-readable error message",
  "request_id": "uuid"
}
```

| Code | Meaning | Recovery |
|------|---------|----------|
| 400 | Bad request | Check required fields |
| 401 | Missing or invalid API key | Verify key starts with `mi_` |
| 403 | Key lacks required scope or tier | Upgrade tier (or wait for demo mode if active) |
| 404 | Resource not found | Check endpoint path / IDs |
| 429 | Rate limited | Sleep `X-RateLimit-Reset` seconds, retry |
| 500 | Server error | Retry after 3s, max 2 retries |
| 503 | Service unavailable | Check `/v1/doctor` for provider status |

Full API docs: [docs.marketintell.ai](https://docs.marketintell.ai)