# Saffron Browser — Developer & Agent Documentation
> Sovereign headless browser automation and web scraping platform for AI agents.

## Core Capabilities
- 100% Steel.dev API Drop-In compatibility: Any client using `Steel(base_url="https://api.saffronbrowser.com/v1")` functions identically.
- 4-Vector Proxy Routing: Direct bare-metal Hetzner egress, IPv6 /64 random spray rotation ($0/GB), Tor circuit rotation, and US-East SOCKS5 residential gateway.
- Live CDP Screencast: SSE streaming on `/v1/sessions/:id/screencast` delivering real-time JPEG frames.
- Anti-Bot & Captcha Solving: Turnstile, Cloudflare Challenge, and reCAPTCHA bypass hooks.
- Zero-Charge Block Guarantee: Unsuccessful requests returning 403/429 are billed $0.00.

## API Endpoints
- `POST /v1/auth/signup`: Create tenant and get instant API key (`{"email": "founder@example.com"}`).
- `POST /v1/sessions`: Launch isolated browser session (`{"proxy": {"tier": "direct"}}`).
- `GET /v1/sessions/:id`: Session details and CDP websocket endpoint.
- `GET /v1/sessions/:id/screencast`: SSE video stream.
- `POST /v1/scrape`: Stateless URL to LLM markdown extraction.
- `POST /v1/screenshot`: Stateless URL screenshot.
- `POST /v1/pdf`: Stateless URL to PDF generation.
- `POST /v1/route/fetch`: Multi-vector proxy HTTP fetch.
- `GET /v1/billing/usage`: Real-time tenant credit balance and logs.
- `POST /v1/billing/checkout`: Generate Stripe checkout URL.

## Authentication
Pass your Saffron API Key via either:
- `Authorization: Bearer sb_live_...`
- `x-steel-key: sb_live_...`
- `x-grid-key: sb_live_...`

## MCP (Model Context Protocol) Server
Package: `@saffron/browser-mcp`
Run with: `npx -y @saffron/browser-mcp`
Env: `SAFFRON_BROWSER_KEY=sb_live_...`