✦ Docs · v1

API reference.

SPIDERNET ships one product: a worker opens a Chrome window for you. Everything in this doc is built on that. The API is small on purpose.

Overview

Every endpoint accepts JSON over HTTPS, returns JSON, charges in USDC. There is no SDK lock-in; you can write a wrapper in 40 lines. We publish official bindings for Node and Python because they cover 90% of agent builders.

The gateway lives at https://api.spidernet.io. The public demo gateway at spidernet.studioklin.com proxies to the same routers with a 50-render/day cap and no key required.

Authentication

Pass your API key as a Bearer token. Get one by signing the SIWS message at spidernet.studioklin.com/keys (available launch week).

# every request
Authorization: Bearer sk_live_a8f3b21c9e...

Billing in USDC

Costs settle per epoch (every 24h) in USDC on Solana. Each response includes cost_usdc; we batch micropayments so you don't pay gas per render.

$SPIDER holders get a 10% rebate on gateway fees, paid in USDC at epoch close, when staked at the 100k tier.

Rate limits

Free public gateway: 50 renders / day per IP. No key.
Authenticated default: 100 concurrent requests, 1M renders / month.
Raise by staking $SPIDER. See /#token on the home page.

POST /v1/render

Render a URL. Returns HTML, a PNG screenshot, or both.

Request

Field	Type		Description
url	string	required	Absolute URL to render. Must start with http:// or https://.
return	enum	optional	`html`, `png`, `both`. Defaults to `html`.
wait	enum	optional	`load`, `networkidle`, `domcontentloaded`, or a CSS selector to wait for. Defaults to `load`.
region	enum	optional	Continent or ISO country code. `auto` by default. See regions.
viewport	object	optional	`{ width, height }`. Defaults to `1280×800`.
block	array	optional	Resource types to block. `["image","font","stylesheet"]` common.
js	string	optional	JavaScript to evaluate in page context after load. Return value is included in response.

Response

{
  "id": "job_01HZ8R3M2K...",
  "worker": "jp-osaka-#421",
  "region": "JP",
  "rtt_ms": 890,
  "cost_usdc": 0.001,
  "status": 200,
  "html": "<!doctype html> ...",
  "png": "data:image/png;base64,iVBORw0K...",
  "timing": { "dns": 12, "connect": 38, "ttfb": 220, "render": 620 }
}

POST /v1/fill

Fill out a form and submit. The worker carries the session for the call, then discards it.

{
  "url": "https://example.com/contact",
  "fill": [
    { "selector": "#email", "value": "hi@example.com" },
    { "selector": "textarea[name=msg]", "value": "hello" }
  ],
  "submit": "button[type=submit]",
  "wait_for": ".thanks-page"
}

POST /v1/extract

Render and pull structured data by selector. Cheaper than asking an LLM to parse HTML for you.

{
  "url": "https://news.ycombinator.com",
  "extract": {
    "items": {
      "selector": "tr.athing",
      "fields": {
        "title": ".titleline a",
        "href": { "selector": ".titleline a", "attr": "href" },
        "rank": ".rank"
      }
    }
  }
}

POST /v1/session (preview)

POST /v1/session

Reserve a sticky worker for a session. Multiple requests share cookies and local storage. Billed per minute of held attention. Ships 2027.

Node / TypeScript

import { Spidernet } from "@spidernet/sdk";

const net = new Spidernet({ apiKey: process.env.SPIDER_KEY });

const page = await net.render({
  url: "https://news.ycombinator.com",
  return: "both",
  wait: "networkidle"
});

console.log(page.worker, page.cost_usdc);

Python

from spidernet import Spidernet

net = Spidernet(api_key=os.environ["SPIDER_KEY"])

page = net.render(
    url="https://news.ycombinator.com",
    return_="both",
    wait="networkidle",
)

print(page.worker, page.cost_usdc)

Raw curl

curl https://api.spidernet.io/v1/render \
  -H "Authorization: Bearer $SPIDER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://news.ycombinator.com","return":"both","wait":"networkidle"}'

Error codes

200Success. html and/or png populated.

400Malformed request. See error.field for the offending field.

401Missing or invalid Bearer token.

402Account in arrears. Top up USDC or wait for next epoch settlement.

408Worker timeout. Job auto-retries up to 3 times; this is the final fail.

429Rate limit hit. Backoff hint in Retry-After.

451URL on the network-wide blocklist (CSAM, malware, sanctioned).

503No worker available for the requested region. Retry without region constraint.

Worker regions

Pass an ISO country code (JP, DE, US-CA) or a continent code (AS, EU, NA, SA, AF, OC). auto picks the cheapest worker reachable to the target.

Current top supply (workers / region): Japan (1,432), United States (1,205), Germany (812), South Korea (760), Brazil (621), Nigeria (480), France (392), United Kingdom (310), Australia (285), Turkey (240), Philippines (218), Canada (204), India (193), Spain (152), Mexico (140), and 49 more.

Wait conditions

load: window.onload fires. Default.
domcontentloaded: DOMContentLoaded fires. Fastest, no images.
networkidle: 500ms of no network activity. Best for SPAs.
"div.results": any CSS selector. Polls until matched or 10s timeout.

Need something not in here? The SPIDERNET protocol is open. Workers can advertise capabilities (CAPTCHA-handling, fingerprint-rotation, mobile-emulation) and you can route to them by tag. We document the long tail at spidernet.studioklin.com/protocol at launch.