# WebLens

> Premium Web Intelligence API with x402 micropayments. Give your AI agents web superpowers.

WebLens provides AI-powered web scraping, research, and data extraction services. All paid endpoints use the x402 protocol for HTTP-native micropayments - no accounts, no API keys, just pay per use with USDC.

## Why Choose WebLens?

- **Zero friction**: No accounts, API keys, or subscriptions - just pay per request
- **AI-optimized**: Designed for autonomous agents with structured outputs
- **Instant settlement**: Payments settle in ~1-2 seconds on Base
- **No fees**: x402 protocol has 0 platform fees
- **Bazaar listed**: Discoverable via Coinbase Bazaar for AI agents

## Try It Now (Zero-Friction Reader)

Fetch any webpage as markdown with a single GET request — no auth, no payment, no setup:

  GET https://api.weblens.dev/r/https://example.com
  GET https://api.weblens.dev/s/your+search+query

Add ?format=text for plain output. Rate limited to 10/hour.
Reader: content truncated to 2000 chars. Search: max 3 results.
Upgrade to paid endpoints for full content and more results.

## Quick Start for AI Agents

1. Try the free reader: GET /r/https://example.com (no wallet needed!)
2. For full access, call any paid endpoint (e.g., POST /fetch/basic with {"url": "https://example.com"})
3. Receive 402 Payment Required — read the PAYMENT-REQUIRED response header (base64-encoded JSON) for amount, asset, payTo and accepts
4. Sign USDC payment using your wallet (Base network)
5. Retry with the Payment-Signature header containing the signed payload
6. Receive data; settlement receipt is in the PAYMENT-RESPONSE response header

## Discovery Endpoints

- GET /r/{url} - Zero-friction reader (free, no auth needed)
- GET /s/{query} - Zero-friction search (free, no auth needed)
- GET /discovery - Full service catalog with all endpoints, pricing, and capabilities
- GET /.well-known/x402 - Standard x402 discovery for Bazaar indexing
- GET /mcp/info - MCP server information for AI agent integration

## API Base URL

- Production: https://api.weblens.dev
- Documentation: https://api.weblens.dev/docs
- OpenAPI Spec: https://api.weblens.dev/openapi.json
- Discovery: https://api.weblens.dev/discovery

## Payment Protocol

All paid endpoints use [x402 v2](https://x402.org) micropayments:
1. Make a request to any endpoint
2. Receive `402 Payment Required` — payment details are in the `PAYMENT-REQUIRED` response header (base64-encoded JSON; body is empty)
3. Sign a USDC payment with your wallet (Base network)
4. Retry the request with the `Payment-Signature` header containing the signed payload
5. Receive the response with a `PAYMENT-RESPONSE` header (settlement proof)

Supported networks: Base (mainnet), Base Sepolia (testnet)
Token: USDC

## Endpoints

### Core Endpoints

#### POST /fetch/basic
Fetch and convert any webpage to clean markdown. Fast, no JavaScript rendering.
- Price: $0.005
- Body: `{"url": "string", "timeout?": number, "cache?": boolean}`
- Returns: `{"url", "title", "content", "metadata", "fetchedAt", "requestId"}`

#### POST /fetch/pro
Fetch webpage with full JavaScript rendering. Use for SPAs and dynamic content.
- Price: $0.015
- Body: `{"url": "string", "waitFor?": "string", "timeout?": number}`
- Returns: `{"url", "title", "content", "metadata", "tier", "fetchedAt", "requestId"}`

#### POST /screenshot
Capture a screenshot of any webpage. Returns base64 PNG.
- Price: $0.02
- Body: `{"url": "string", "viewport?": {"width": number, "height": number}, "fullPage?": boolean, "selector?": "string"}`
- Returns: `{"url", "image", "dimensions", "capturedAt", "requestId"}`

#### POST /batch/fetch
Fetch multiple URLs in parallel. Efficient for bulk operations.
- Price: $0.003 per URL (2-20 URLs)
- Body: `{"urls": ["string"], "tier?": "basic"|"pro", "timeout?": number}`
- Returns: `{"results": [...], "summary", "totalPrice", "requestId"}`

### Search & Research

#### POST /search
Real-time web search. Returns titles, URLs, and snippets.
- Price: $0.005
- Body: `{"query": "string", "limit?": number}`
- Returns: `{"query", "results": [{"title", "url", "snippet"}], "searchedAt", "requestId"}`

#### POST /research
One-stop research: searches web, fetches top results, generates AI summary with key findings.
- Price: $0.08
- Body: `{"query": "string", "resultCount?": number, "includeRawContent?": boolean}`
- Returns: `{"query", "sources", "summary", "keyFindings", "researchedAt", "requestId"}`

### Data Extraction

#### POST /extract
Extract structured data from webpages using JSON schema.
- Price: $0.03
- Body: `{"url": "string", "schema": object, "instructions?": "string"}`
- Returns: `{"url", "data", "extractedAt", "requestId"}`

#### POST /extract/smart
AI-powered data extraction using natural language. Just describe what you want.
- Price: $0.035
- Body: `{"url": "string", "query": "string", "format?": "json"|"text"}`
- Returns: `{"url", "query", "data", "explanation", "extractedAt", "requestId"}`

#### POST /pdf
Extract text and metadata from PDF documents.
- Price: $0.01
- Body: `{"url": "string", "pages?": [number]}`
- Returns: `{"url", "metadata", "pages", "fullText", "extractedAt", "requestId"}`

#### POST /compare
Compare 2-3 webpages with AI-generated analysis of similarities and differences.
- Price: $0.05
- Body: `{"urls": ["string"], "focus?": "string"}`
- Returns: `{"sources", "comparison": {"summary", "similarities", "differences"}, "comparedAt", "requestId"}`

### Monitoring

#### POST /monitor/create
Create a URL monitor for change detection.
- Price: $0.01
- Body: `{"url": "string", "webhookUrl": "string", "checkInterval?": number, "notifyOn?": "any"|"content"|"status"}`
- Returns: `{"monitorId", "url", "webhookUrl", "checkInterval", "nextCheckAt", "createdAt", "requestId"}`

#### GET /monitor/{id}
Get monitor status and history. (Free)
- Returns: `{"monitorId", "url", "webhookUrl", "checkInterval", "status", "lastCheck", "nextCheckAt", "requestId"}`

#### DELETE /monitor/{id}
Delete a monitor. (Free)
- Returns: `{"monitorId", "deleted", "requestId"}`

### Intelligence (AI-powered, premium)

These endpoints chain multiple tools and AI synthesis. They're the highest-value services on the platform.

#### POST /intel/company
Comprehensive company deep dive: tech stack, funding, team, competitors, recent news. Chains search + batch fetch + Claude.
- Price: $0.50
- Body: `{"param": "string", "depth?": "basic"|"deep"}`
- Returns: `{"name", "domain", "funding", "summary", "requestId"}`

#### POST /intel/market
Market research report: executive summary, market size, growth, key trends, key players, recommendations.
- Price: $2.00
- Body: `{"param": "string", "depth?": "basic"|"deep"}`
- Returns: `{"topic", "executiveSummary", "marketSize", "growthRate", "keyTrends", "keyPlayers", "recommendations", "requestId"}`

#### POST /intel/competitive
Competitive analysis: feature matrix, pricing comparison, SWOT, positioning.
- Price: $3.00
- Body: `{"param": "string", "depth?": "basic"|"deep"}`
- Returns: `{"company", "competitors", "featureMatrix", "pricing", "swot", "positioning", "requestId"}`

#### POST /intel/site-audit
Full site audit: SEO, performance, security, accessibility scoring with actionable recommendations.
- Price: $0.30
- Body: `{"param": "string", "depth?": "basic"|"deep"}`
- Returns: `{"url", "scores": {"seo", "performance", "security", "accessibility"}, "issues", "recommendations", "requestId"}`

### Memory (Key-Value Storage)

#### POST /memory/set
Store a value in persistent key-value storage.
- Price: $0.001
- Body: `{"key": "string", "value": any, "ttl?": number}`
- Returns: `{"key", "stored", "expiresAt", "requestId"}`

#### GET /memory/get/{key}
Retrieve a stored value by key.
- Price: $0.0005
- Returns: `{"key", "value", "storedAt", "expiresAt", "requestId"}`

#### GET /memory/list
List all stored keys for the current wallet.
- Price: $0.0005
- Returns: `{"keys": ["string"], "count", "requestId"}`

#### DELETE /memory/{key}
Delete a stored value. (Free)
- Returns: `{"key", "deleted", "requestId"}`

### System

#### GET /
API information and documentation links. (Free)

#### GET /health
Health check endpoint. (Free)
- Returns: `{"status", "version", "timestamp"}`

#### GET /docs
Interactive API documentation (Scalar UI). (Free)

#### GET /openapi.json
OpenAPI 3.0 specification. (Free)

#### POST /mcp
Model Context Protocol endpoint for AI agents. Supports JSON-RPC with tools/list and tools/call methods.
- Free (tool calls are paid per-endpoint)

#### GET /mcp/info
MCP server information including available tools and pricing. (Free)

## MCP Integration

For AI agents using Model Context Protocol:

### Remote HTTP (no install)
```json
{
  "mcpServers": {
    "weblens": {
      "url": "https://api.weblens.dev/mcp"
    }
  }
}
```

### Local with auto-payment
```json
{
  "mcpServers": {
    "weblens": {
      "command": "npx",
      "args": ["-y", "@weblens/mcp"],
      "env": {
        "PRIVATE_KEY": "0xYourPrivateKeyHere"
      }
    }
  }
}
```

## Available MCP Tools

- `fetch_webpage` - Fetch webpage as markdown (basic) — $0.005
- `fetch_webpage_pro` - Fetch with JS rendering — $0.015
- `fetch_resilient` - Resilient fetch with provider fallback — $0.025
- `screenshot` - Capture webpage screenshot — $0.02
- `search_web` - Real-time web search — $0.005
- `extract_data` - Extract structured data with JSON schema — $0.03
- `smart_extract` - AI-powered natural-language extraction — $0.035
- `research` - Search + fetch + AI summary — $0.08
- `batch_fetch` - Fetch multiple URLs in parallel — $0.003/URL
- `extract_pdf` - Extract text from PDFs — $0.01
- `compare_urls` - Compare 2-3 webpages — $0.05
- `monitor_create` - Create URL change monitor — $0.01
- `memory_set` - Persistent key-value storage — $0.001
- `intel_company` - Company deep dive (AI-powered) — $0.50
- `intel_market` - Market research report — $2.00
- `intel_competitive` - Competitive analysis — $3.00
- `intel_site_audit` - SEO/performance/security audit — $0.30

## Endpoints

### Core Endpoints

#### POST /fetch/resilient
Resilient fetch with automatic provider fallback (WebLens -> Firecrawl -> Zyte). Guarantees best-effort retrieval.
- Price: $0.025
- Body: `{"url": "string", "timeout?": number}`
- Returns: `{"url", "content", "provider": {"id", "name"}, "tier", "fetchedAt", "requestId"}`

### Agent Credits (Prepaid)

Bypass per-request x402 signatures by pre-funding an account.

#### POST /credits/buy
Purchase credits with x402. Currently supports fixed $10 bundle (with 20% bonus = $12 credits).
- Body: `{"amount": "$10.00"}`

#### GET /credits/balance
Check current credit balance.
- Header: `X-CREDIT-WALLET`: Your wallet address
- Header: `X-CREDIT-SIGNATURE`: Signature of "WebLens Auth..." message

#### GET /dashboard
Human-friendly UI to manage credits and view history.

## Response Headers

All responses include:
- `X-Request-Id` - Unique request identifier
- `X-Processing-Time` - Processing time in milliseconds
- `PAYMENT-RESPONSE` - Settlement proof (on a successful paid response)

## Error Handling

Errors return JSON with:
```json
{
  "error": "Error type",
  "code": "ERROR_CODE",
  "message": "Human-readable message",
  "requestId": "uuid"
}
```

## Cache Discount

Cached responses are 70% cheaper than fresh fetches. Use `cache: true` in fetch requests.

## Links

- Website: https://api.weblens.dev
- Documentation: https://api.weblens.dev/docs
- x402 Protocol: https://x402.org