webcap

webcap

Screenshot any URL, extract structured data, monitor pages for changes — all via a single HTTP API call. Pay-per-call with no accounts, no API keys.

GET  /v1/extract/preview?url=...  →  Free preview (title, headings, links)
POST /v1/x402/capture             →  PNG/JPEG/PDF screenshot + persistent link
POST /v1/x402/extract             →  Structured JSON (title, headings, markdown)
POST /v1/x402/video               →  Scroll-capture video (WebM/VP8)
POST /v1/watches                  →  Scheduled monitoring with webhook alerts

Pricing: $0.001/screenshot · $0.01/extraction batch · No subscriptions, no minimums.

Why webcap?

Feature	webcap	Screenshot APIs (typical)
Price	$0.001/screenshot	$0.01–0.10/screenshot
Accounts required	No	Yes
API keys	No	Yes
Payment	Card (Stripe) or crypto (USDC)	Credit card only
Batch support	Up to 50 URLs per payment	Limited
Self-hostable	Yes (Docker)	No
Open source	Yes (MIT)	No

Features

Endpoint	What you get	Price
POST /v1/x402/capture	Screenshot as PNG/JPEG/PDF (base64) + persistent public artifact link + OG metadata	$0.001
POST /v1/x402/extract	Structured page data as JSON: title, description, headings, paragraphs, links, images, word count, markdown. Batch up to 50 URLs per payment.	$0.01
POST /v1/x402/audit	SEO basics + link/OG health in one call	$0.002
POST /v1/x402/map-lite	Site URL list from sitemap/robots + 1-hop crawl (up to 50 URLs)	$0.002
POST /v1/x402/video	Scroll-capture a page as WebM/VP8 video	$0.005
POST /v1/watches	Create a scheduled monitor (free to create, prepay 100-run packs)	$0.10–$1.00/pack

Bearer-token rail (no signing key)

The same products are buyable with an API key: POST /v1/register ({"address"} → {apiKey}), fund with a plain USDC transfer via POST /v1/invoice, then send Authorization: Bearer <apiKey> to POST /v1/extract, POST /v1/audit, POST /v1/map-lite, POST /v1/video, POST /v1/analyze, or POST /v1/analyze/batch. Every call costs 1 credit, refunded whenever the call does not return 200; an empty balance answers 402 with a 1-credit top-up invoice. Watches fund the same way: POST /v1/watches/{id}/topup {"runs": 100} (capture pack 10 credits, extract pack 100). Full spec: GET /openapi.json (tags: accounts).

Free endpoints (no payment)

Endpoint	Description
GET /v1/extract/preview?url=...	Bounded preview: title, headings, links, word count (10 req/min/IP)
GET /v1/og?url=...	Open Graph link-preview metadata
POST /v1/watches	Create a scheduled monitor (free; prepay via top-up)
GET /v1/health	Liveness check
POST /v1/feedback	Tell webcap something (machine or human): {"message":"…","category?"?:"bug|suggestion|pricing|docs|integration|other","endpoint"?:"…"}. No account, rate-limited 60/hr. Human form: GET /feedback

Quick start

Use as an MCP server (agent runtimes)

webcap ships an MCP server, so any MCP host (Claude Desktop, Cursor, agent frameworks) can call it as a tool. Two ways to wire it: a remote endpoint (no install at all) or the stdio server from a checkout.

The remote endpoint is the cheapest path for an agent — nothing to install, no package registry, no account:

{
  "mcpServers": {
    "webcap": { "url": "https://webcap.shoutsid.fyi/mcp" }
  }
}

POST /mcp speaks MCP Streamable HTTP (JSON-RPC 2.0 over HTTPS; GET is deliberately 405 because the server never opens an SSE stream). It holds no wallet, so it never spends on a caller's behalf: the free tools run directly, and a paid tool returns the live x402 402 challenge for your own client to settle. The endpoint is also described in /.well-known/mcp-tools.json and openapi.json.

It is listed in the official MCP Registry as io.github.shoutsid-lab/webcap, so a runtime that reads the registry can discover it without this README:

curl -s 'https://registry.modelcontextprotocol.io/v0/servers?search=webcap'

The stdio server runs locally and can settle paid calls itself. The free tools need no configuration; set WEBCAP_MCP_WALLET_KEY to a Base-mainnet USDC key to let the paid tools settle automatically (gasless — the payer signs EIP-3009, the facilitator pays gas). With no key, paid tools return the x402 402 challenge for the host to pay. No wallet at all? Set WEBCAP_MCP_API_KEY to an operator-funded account key instead (POST /v1/register, then fund via POST /v1/invoice): paid tools bill 1 credit each from that balance. A configured wallet wins over the key.

From a source checkout — npm ci && npm run build — then point args at its dist/mcp/stdio.js:

{
  "mcpServers": {
    "webcap": {
      "command": "node",
      "args": ["/absolute/path/to/webcap/dist/mcp/stdio.js"],
      "env": { "WEBCAP_MCP_WALLET_KEY": "0x..." }
    }
  }
}

(npm run mcp runs the TypeScript directly, so no build step is needed there.) The npm release will be @shoutsid/webcap — the unscoped webcap name belongs to an unrelated package, and it is not published yet — so until then the remote endpoint above is the install-free option.

Tools, all 8 of them (every one is also in /.well-known/openai-tools.json and /.well-known/mcp-tools.json):

• Free: webcap_service_catalog (every paid endpoint and price, the network and payTo, the how-to-pay flow, and the caller's remaining free allowance), webcap_preview (bounded peek), webcap_og
• Paid: webcap_capture (png/jpeg/pdf screenshot or PDF, or an mp4/webm scroll video — always recorded as WebM/VP8), webcap_extract (one URL or a batch of up to 50), webcap_audit, webcap_map_lite, webcap_analyze

The free rail is not a tool, it is an allowance: an unpaid call to any of the five paid tools runs the real product, free, inside a rolling per-IP window (default 50 calls / 24h). No wallet, signature or account — every response carries x-webcap-allowance-* headers saying where you stand, and when the window is spent the same call answers the normal x402 402 challenge. A failed call does not consume the allowance. Tunable with WEBCAP_ALLOWANCE_CALLS, WEBCAP_ALLOWANCE_WINDOW_HOURS and WEBCAP_ALLOWANCE_GLOBAL_LIMIT.

Feedback is a REST rail, not a tool: POST /v1/feedback.

Capture a screenshot

# 1. POST without payment → HTTP 402 + a PAYMENT-REQUIRED header
curl -si -X POST "https://webcap.shoutsid.fyi/v1/x402/capture" \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com/"}'

# 2. Decode the base64 challenge → sign a gasless EIP-3009 transfer → retry with PAYMENT-SIGNATURE

JavaScript (with x402 auto-payment)

import axios from 'axios';
import { x402Client, wrapAxiosWithPayment } from '@x402/axios';
import { ExactEvmScheme } from '@x402/evm';
import { privateKeyToAccount } from 'viem/accounts';

// Needs USDC on Base mainnet (no ETH needed — facilitator pays gas)
const payer = privateKeyToAccount(process.env.PAYER_KEY);
const client = new x402Client().register('eip155:*', new ExactEvmScheme(payer));
const api = wrapAxiosWithPayment(
  axios.create({ baseURL: 'https://webcap.shoutsid.fyi' }),
  client,
);

// Capture a screenshot (auto: unpaid → 402 → sign → retry)
const { data } = await api.post('/v1/x402/capture', { url: 'https://example.com', format: 'png' });
console.log(data.artifact.url);  // persistent public screenshot link

Python

import os
from x402 import X402Client
from x402.schemes import ExactEvmScheme
from eth_account import Account

payer = Account.from_key(os.environ["PAYER_KEY"])
client = X402Client().register("eip155:*", ExactEvmScheme(payer))

response = client.post(
    "https://webcap.shoutsid.fyi/v1/x402/capture",
    json={"url": "https://example.com", "format": "png"},
)
print(response.json()["artifact"]["url"])  # persistent public screenshot link

Extract structured data

# Single URL
curl -s -X POST "https://webcap.shoutsid.fyi/v1/x402/extract" \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com"}'

# Batch (up to 50 URLs, one payment covers the whole batch)
curl -s -X POST "https://webcap.shoutsid.fyi/v1/x402/extract" \
  -H 'content-type: application/json' \
  -d '{"urls":["https://a.com","https://b.com"],"schema":"company name + tagline"}'

How payment works

The live rail is crypto (x402, USDC on Base) — no accounts, no API keys. Card payments are an operator option, not a hosted feature: until an operator sets STRIPE_SECRET_KEY, POST /v1/stripe/checkout answers stripe_not_configured and points at the crypto rail. (The hosted deployment at https://webcap.shoutsid.fyi is card-less today.)

Card payments (Stripe, when configured)

1. POST /v1/stripe/checkout with a pack id — Stripe Checkout handles the rest.
2. Enter your card details. Credits are added to your account instantly.
3. Use API key authentication for subsequent calls.

Crypto payments (x402 — no accounts needed)

webcap uses x402 v2 — a gasless, accountless payment protocol built on HTTP 402:

1. POST a paid route with no payment → HTTP 402 + a PAYMENT-REQUIRED header carrying a base64 x402 v2 challenge.
2. Read the challenge: USDC amount, merchant address, chain info.
3. Sign a gasless EIP-3009 transferWithAuthorization (from your wallet, to the merchant, for the amount). No ETH needed — the facilitator submits the tx and pays gas.
4. Retry the same request with the signed payload in the PAYMENT-SIGNATURE header. The facilitator verifies your USDC balance, settles on-chain, and returns the result.

No accounts. No API keys. No credits. Just HTTP + your choice of payment.

Self-hosting

# Clone the repo
git clone https://github.com/shoutsid-lab/webcap.git
cd webcap

# Install dependencies
npm install

# Copy and configure environment
cp .env.example .env
# Edit .env with your settings

# Build and run
npm run build
npm start

From the release tarball (no npm registry account)

The packaged MCP server also ships as a GitHub release asset — install it like any npm dependency, without publishing to npm:

# npm 12+ (Node 24) blocks remote tarball URLs by default — opt in explicitly:
npm install --allow-remote=all https://github.com/shoutsid-lab/webcap/releases/download/v0.1.0/shoutsid-webcap-0.1.0.tgz
# npm <= 11 accepts the URL without the flag:
npm install https://github.com/shoutsid-lab/webcap/releases/download/v0.1.0/shoutsid-webcap-0.1.0.tgz
npx webcap-mcp   # stdio MCP server

For MCP hosts the no-install path stays primary: point them at the remote endpoint https://webcap.shoutsid.fyi/mcp (streamable HTTP, no package).

Docker

docker compose build
docker compose up -d

The Docker setup includes health checks, resource limits, and persistent data volumes. See docker-compose.yml for details.

The stack also carries the public edge: the cloudflared service runs the webcap Cloudflare tunnel, with its ingress in cloudflared/config.yml and its credential in CF_TUNNEL_TOKEN (.env). Nothing publishes the app beyond loopback, so the tunnel container is the only way in — and docker compose up -d without it leaves webcap.shoutsid.fyi answering Cloudflare's 530.

docker compose ps cloudflared                       # Up, not Restarting
docker compose logs --tail 20 cloudflared           # "Registered tunnel connection"
curl -s -o /dev/null -w '%{http_code}\n' https://webcap.shoutsid.fyi/v1/health   # 200

Local development (Anvil testnet)

npm install
npm run chain:up    # Starts Anvil with mintable USDC

WEBCAP_CHAIN=local \
WEBCAP_USDC_ADDRESS=$(jq -r .usdcContract /tmp/webcap-chain.json) \
WEBCAP_MERCHANT_ADDRESS=$(jq -r .merchant.address /tmp/webcap-chain.json) \
npm start

Configuration

All environment variables are documented in .env.example. Key ones:

Variable	Description	Default
WEBCAP_CHAIN	Network: base, base-sepolia, or local	base-sepolia
WEBCAP_PUBLIC_BASE_URL	Public URL for artifact links	required
WEBCAP_X402_PRICE_USDC	Price per screenshot in USDC	0.001
WEBCAP_X402_EXTRACT_PRICE_USDC	Price per extraction in USDC	0.01
X402_FACILITATOR_URL	Payment facilitator endpoint	https://x402.org/facilitator

API reference

Full OpenAPI 3.1 spec: GET /openapi.json

Agent discovery: GET /.well-known/x402, GET /v1/x402/service, GET /llms.txt, GET /skill.md

Tests

npm test           # full vitest suite (tests/**/*.test.ts, no exclusions)
npm run typecheck  # Type checking

Both must pass before a change ships. Deliberately no test/file counts here: they have gone stale twice (a reader caught the second one in issue #1), and a number nobody regenerates is worse than no number. npm test prints the current totals.

Claim audit

npm run audit:claims                                        # against localhost:8080
npm run audit:claims -- --base-url https://webcap.shoutsid.fyi  # against a deployment

The tests check the code; this checks the claims — it reads README.md, /skill.md and /llms.txt and verifies every METHOD /path they advertise is actually served, that every documented price equals the 402 challenge amount, and that the free surface describes the same prices as the paid routes. It exits non-zero on any failure, so it can gate a deploy. Issue #1 was filed by an agent that did this by hand; this is the same check as a command.

License

MIT — see LICENSE for details.

Links

• Live API: https://webcap.shoutsid.fyi
• GitHub: https://github.com/shoutsid-lab/webcap
• OpenAPI docs: https://webcap.shoutsid.fyi/openapi.json