---
name: krawl
description: The deep-research skill for any AI agent. Turns a question into a structured markdown report with 50+ verified sources and inline citations in ~90 seconds — reading the web, X/Twitter, GitHub, and on-chain data. Works in Claude Code, OpenClaw, Hermes, Cursor, ChatGPT, and any runtime via API, MCP, or skill.md. Use when asked to research any topic in depth, analyze tokens/protocols, track whales, find narratives, assess risk, or discover yield strategies.
base_url: https://api.krawl.sh
---

# Krawl — the research skill for AI agents

A deep-research engine any agent can plug into. It reads the web, X/Twitter, GitHub, and on-chain data to produce structured markdown reports with verified inline citations. One call → 50+ sources checked → cited report in ~90 seconds. Authenticate with an API key, or let an autonomous agent pay per request via x402 (USDC on Base) — no account required.

Base URL: `https://api.krawl.sh`

## Authentication

Three ways to authenticate:

1. **API key** — get one at [krawl.sh](https://krawl.sh), or an instant free demo key via `POST /auth/demo-key` (no signup). Keys look like `krawl_live_...`, `krawl_demo_...`, `krawl_test_...`. Include in requests:

   ```
   X-API-Key: your_api_key
   ```

2. **x402 pay-per-request** — autonomous agents can pay per request in USDC on Base with no account. Call a research endpoint with no `X-API-Key` → get `HTTP 402` with payment requirements → retry with a signed `X-PAYMENT` header. Prices: $5.00 deep / $1.00 quick. See the x402 section below.

`POST /research`, `POST /research/upload`, and `POST /templates/{id}/research` accept **either** an API key **or** an x402 payment.

## Endpoints

### Deep Research (SSE Stream)

Start a deep research session. Returns a Server-Sent Events stream with real-time progress and the final report.

```
POST /research
```

```json
{
  "query": "What is EIP-4844 proto-danksharding and how does it reduce L2 fees?",
  "mode": "deep"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Research question (1–2000 chars) |
| `mode` | string | No | Research mode (default: `deep`) |
| `depth` | integer | No | Max agent steps (1–100, default 75) |
| `breadth` | integer | No | Parallel queries per level (1–10, default 4) |
| `depth_levels` | integer | No | Recursion depth (1–5, default 3) |
| `sources` | string[] | No | Allowed sources: `exa`, `x`, `github`, `crypto`, `web` |

#### Research Modes

| Mode | Best for |
|------|----------|
| `deep` | Comprehensive multi-topic research (default) |
| `quick` | Fast answers, fact checks (~30s) |
| `crypto` | Crypto/DeFi with on-chain data |
| `token-analysis` | Deep token analysis (tokenomics, metrics) |
| `protocol-research` | DeFi protocol deep dive |
| `whale-tracking` | Whale wallet and large transaction tracking |
| `narrative` | Market narrative and sentiment |
| `risk-assessment` | Risk analysis for projects/tokens |
| `yield-strategy` | Yield farming strategy research |

#### SSE Events

Response is `Content-Type: text/event-stream`. Key events:

| Event | Data | Description |
|-------|------|-------------|
| `plan` | `{status: {title}, plan?: [...]}` | Planning/synthesis phase updates |
| `source` | `{queryId, source: {title, url}}` | Source discovered |
| `learning` | `{}` | Knowledge extracted from content |
| `report_chunk` | `{text}` | Incremental report piece (stream these to build the full report) |
| `result` | `{markdown, sources[], total_sources, total_steps, model}` | Final complete result |
| `usage` | `{total_tokens, cost_usd, by_model, cost_ceiling_usd, ceiling_hit}` | Terminal token/cost metering snapshot |
| `error` | `{message}` | Error during research |

The full `EventType` enum has 27 values: `plan`, `thinking`, `query`, `source`, `content`, `x_search`, `browse_page`, `sources` (reserved), `report_chunk`, `result`, `error`, `done`, `node_started`, `node_completed`, `learning`, `gap_detected`, `outline_updated`, `citation_verified`, `audit`, `steer`, `chart`, `structured_output`, `review_pass`, `perspectives`, `memory_recall`, `document`, `usage`.

Example with curl:

```bash
curl -N -X POST "https://api.krawl.sh/research" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KRAWL_API_KEY" \
  -d '{"query": "What is EIP-4844?", "mode": "deep"}'
```

---

### Single-Source Search

Search a specific source without running full research.

```
POST /search
```

```json
{
  "query": "Ethereum Pectra upgrade",
  "source": "exa",
  "options": {}
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search query (1–2000 chars) |
| `source` | string | Yes | `exa`, `x`, `github`, `crypto`, or `web` |
| `options` | object | No | Source-specific options (see below) |

#### Source Options

**Exa** (web search):

| Option | Type | Description |
|--------|------|-------------|
| `num_results` | integer | 1–30 (default 8) |
| `category` | string | `news`, `company`, `research paper`, `github`, `financial report` |
| `start_date` | string | YYYY-MM-DD |
| `include_domains` | string[] | Domain filter |

**X/Twitter:**

| Option | Type | Description |
|--------|------|-------------|
| `from_date` | string | YYYY-MM-DD |
| `to_date` | string | YYYY-MM-DD |
| `include_handles` | string[] | Handles without @ prefix |
| `exclude_handles` | string[] | Handles to exclude |

**GitHub:**

| Option | Type | Description |
|--------|------|-------------|
| `num_results` | integer | Number of results |

**Crypto** (CoinGecko + DeFi Llama):

| Option | Type | Description |
|--------|------|-------------|
| `token_id` | string | CoinGecko ID, e.g. `bitcoin`, `ethereum`, `solana` |

**Web** (URL browsing):

| Option | Type | Description |
|--------|------|-------------|
| `url` | string | Specific URL to browse and extract |

---

### Results

| Method | Path | Description |
|--------|------|-------------|
| GET | `/results` | List all past research results |
| GET | `/results/:id` | Get specific result (id is UUID format) |

Result object:

```json
{
  "id": "e4d2467a-37f6-4899-a536-ff69311e9911",
  "query": "What is EIP-4844?",
  "mode": "deep",
  "markdown": "## Title\n\nReport with [inline citations](url)...",
  "sources": [{"title": "...", "url": "...", "snippet": "..."}],
  "total_sources": 22,
  "total_steps": 15,
  "duration_seconds": 87.3,
  "model": "bedrock/us.anthropic.claude-sonnet-4-6",
  "created_at": "2026-04-06T15:58:14+00:00"
}
```

---

### Audit Trail

```
GET /audit/:result_id
```

Returns step-by-step provenance for a research result.

```json
{
  "result_id": "...",
  "entries": [
    {
      "timestamp": "2026-04-06T15:58:14+00:00",
      "action": "search",
      "tool": "webSearch",
      "query": "EIP-4844 proto-danksharding",
      "sources_found": 8,
      "learnings_extracted": 3,
      "model": "bedrock/us.meta.llama3-3-70b-instruct-v1:0",
      "tokens_used": 1200,
      "duration_ms": 2172
    }
  ]
}
```

Actions: `search`, `extract`, `learn`, `gap_detect`, `synthesize`, `verify`, `query_generation`

---

### Lookouts (Scheduled Monitoring)

| Method | Path | Description |
|--------|------|-------------|
| POST | `/lookouts` | Create a scheduled research monitor |
| GET | `/lookouts` | List all lookouts |
| GET | `/lookouts/:id` | Get specific lookout |
| DELETE | `/lookouts/:id` | Delete a lookout |
| POST | `/lookouts/:id/run` | Manually trigger a lookout (2/min rate limit) |

Create lookout:

```json
{
  "query": "Solana DeFi TVL changes",
  "mode": "crypto",
  "schedule": "daily",
  "webhook_url": "https://hooks.example.com/krawl"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Research query (1–2000 chars) |
| `mode` | string | No | Research mode (default: `deep`) |
| `schedule` | string | Yes | `hourly`, `daily`, or `weekly` |
| `webhook_url` | string | No | URL to POST results to |

Limits: max 10 lookouts per key, min 60 minutes between manual runs.

---

### Steer Active Research

Inject a steering instruction into an in-progress research session.

```
POST /research/:research_id/steer
```

```json
{
  "instruction": "Focus more on layer 2 scaling solutions"
}
```

---

### Diagnostics

```
GET /health
```

Use for connectivity checks and diagnostics. Returns: `{"status": "ok"}`. No auth required.

---

## Usage, Billing & x402

### Usage metering

Every research request meters LLM tokens, USD cost, per-model breakdown, and search/source counts.

| Method | Path | Description |
|--------|------|-------------|
| GET | `/usage` | Current monthly usage rollup for the key |
| GET | `/usage/events` | Paginated per-request usage events |

The same snapshot streams as the terminal `usage` SSE event. Each request has a hard LLM cost ceiling ($2.50 deep / $0.40 quick); if crossed, the agent synthesizes with what it has and sets `ceiling_hit: true`.

### Key management & billing

| Method | Path | Description |
|--------|------|-------------|
| POST | `/auth/demo-key` | Instant free demo key (no signup) |
| POST | `/auth/keys` | Create a managed API key (admin only, `X-Admin-Key`) |
| GET | `/auth/keys` | List key metadata (admin only, `X-Admin-Key`) |
| DELETE | `/auth/keys` | Revoke the key in `X-API-Key` (self-service) |
| POST | `/billing/checkout` | Stripe Checkout session (upgrade to Pro) |
| POST | `/billing/portal` | Stripe billing portal |

### x402 (keyless pay-per-request)

Call a research endpoint with no `X-API-Key` → `HTTP 402` with `{x402Version:1, error, accepts:[...]}` → sign an EIP-3009 USDC-on-Base authorization → retry with a base64 `X-PAYMENT` header → receive the stream plus an `X-PAYMENT-RESPONSE` header. Prices: $5.00 deep / $1.00 quick (USDC, network `base`, scheme `exact`).

## Plans & Rate Limits

Quotas are per month and reset monthly. Rate limits are per plan.

| Plan | Deep krawls/mo | Search credits/mo | Rate limit |
|------|----------------|-------------------|------------|
| demo | 5 | 100 | 5/hour (≈24h key) |
| free | 25 | 1,000 | 10/min |
| payg | unlimited (metered) | unlimited (metered) | 60/min |
| pro | unlimited | unlimited | 120/min |

Other limits: max 3 concurrent research sessions, lookout manual runs 2/min, query length 2000 chars, request body 1 MB max.

## Errors

All errors return:

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

| Status | Meaning |
|--------|---------|
| 401 | Invalid or missing API key |
| 402 | Payment required — x402 payment needed (keyless), or monthly quota exhausted (`quota_exceeded`) |
| 404 | Resource not found |
| 413 | Request body too large |
| 422 | Validation error (check field types/values) |
| 429 | Rate limit exceeded — over your plan's rate limit |
| 503 | Server busy — 3 concurrent research sessions running |

Full API documentation: [docs.krawl.sh](https://docs.krawl.sh)