The complete API reference.

01What Stumble does

Stumble is a watch-and-notify service for AI agents, operated by Vima Brosta LLC. You pay once per watch (x402 / USDC), Stumble polls a public URL on a fixed interval, and the moment your condition becomes true it POSTs a signed webhook to you. You can also poll the free status endpoint instead.

Watches never purchase, log in, or bypass access controls. They observe public pages and report. No accounts, no API keys. The Idempotency-Key header is honored on paid POSTs, so a network retry can never double-create.

02Payment (x402)

Three steps, one retry. A request that cannot run is refused before settlement, so a rejection always costs nothing.

1. Send the request with no payment

You receive HTTP 402. The PAYMENT-REQUIRED response header (base64 JSON, mirrored in the JSON body under requirements) carries an accepts array with every enabled option. On this deployment:

• USDC on Base (default rail)
• USDC or native SOL on Solana (same endpoints; pick the Solana option from the accepts list)
• Native ETH and BTC are not accepted: the x402 exact scheme settles token authorizations, so native ETH has no path, and Bitcoin has no x402 rail at all (BTC agent payments use L402, a different protocol).

Stablecoin amounts are fixed per product. Native SOL amounts are quoted per request from a cached spot rate plus a 1.5% buffer, rounded up.

2. Pay and retry the identical request

Produce payment and resend with the X-PAYMENT header. @x402/fetch (JS) wraps this in one call, and most agent frameworks have x402 support. Set an Idempotency-Key so retries can never double-create.

3. The response you paid for returns immediately

Settlement happens on-chain in the background. Stock x402 clients read the header; body readers get the same data plus corrective hints.

03Paid endpoints

{
  "url": "https://example.com/product",
  "condition": {"type":"keyword", "keyword":"in stock"}
}

{ "matched": true, "value": "...", "evidence": {…}, "receipt": {…} }

{
  "url": "https://example.com/product",
  "condition": {"type":"keyword", "keyword":"sold out", "when":"disappears"},
  "notify": {"mode":"webhook", "url":"https://your-agent.example/hook", "format":"json"},
  "duration_days": 7
}

Intervals and politeness

Intervals are per-watch targets. Stumble enforces a per-host politeness floor of 5 seconds across all watches, backs off exponentially on repeated failures (health becomes failing), and identifies itself as StumbleWatch/1.0 (+https://stumble.vimabrosta.com/bot).

04Condition types

Exactly one condition per watch or check. Every condition is a JSON object with a type.

1 · keyword

Visible page text contains, or stops containing, a string. Case-insensitive.

{"type":"keyword", "keyword":"add to cart", "when":"appears"}
{"type":"keyword", "keyword":"sold out", "when":"disappears"}

2 · selector

The first element matching a CSS selector, compared by its text. Ops: contains, not_contains, equals, matches (regex), changes.

{"type":"selector", "selector":"#stock-status", "op":"contains", "value":"in stock"}
{"type":"selector", "selector":".apt-slots", "op":"changes"}

3 · json_path

For JSON endpoints. Dot and bracket path. Ops: eq, ne, gt, lt, gte, lte, exists, not_exists, contains, changes.

{"type":"json_path", "path":"data.slots[0].available", "op":"eq", "value":true}
{"type":"json_path", "path":"inventory.count", "op":"gt", "value":0}

4 · price

First currency amount ($, EUR, GBP, or a "USD" suffix) in the page or selector scope. Ops: below, above.

{"type":"price", "op":"below", "value":450, "selector":".price-box"}

5 · content_change

sha256 of normalized visible text differs from the previous observation.

{"type":"content_change", "selector":"main"}

6 · status

The HTTP status code. Ops: eq, ne, gte, lt.

{"type":"status", "op":"eq", "value":200}

05URL policy

What is watchable, and what is refused. Every rule below applies to the watch target and to your webhook URL.

06Rate limits

Per client IP, per minute. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining; a 429 carries Retry-After in seconds. Paid endpoints are not rate limited.

07Free endpoints

08Webhook delivery

Two events: watch.triggered (the condition became true) and watch.expired (the paid window ended without a trigger). Stumble POSTs to your notify.url with these headers:

X-Stumble-Event: watch.triggered
X-Stumble-Watch: {watch_id}
X-Stumble-Attempt: 1        # 1 = first delivery, then retries
X-Stumble-Signature: sha256={hex hmac}

Verifying the signature

HMAC-SHA256 over the raw request body. The key is the lowercase hex string of sha256(secret), meaning the 64 ASCII characters, not the 32 raw bytes. This trips people up, so here is a worked example you can verify locally:

secret = "ws_EXAMPLEsecret_0000000000000000"
body   = {"schema":"stumble.webhook.v1","event":"watch.triggered"}
key    = sha256(secret) hex
       = 73d4a89ec0c9b38c2b07c4ccad48ce3424e2550241cd3cec2294dddd14eac9c1

X-Stumble-Signature: sha256=347f5d6d95da4ea90d92a1359b7d945a11e282a59c911abfdf664402e74024ce

Retries

On failure: 30 s, 2 m, 10 m, 1 h, 6 h, then Stumble gives up. The result stays available on the status endpoint until the watch is pruned, 30 days after completion. A receiver that redirects is treated as a failed delivery and is never followed.

Payload

{
  "schema": "stumble.webhook.v1",
  "event": "watch.triggered",
  "watch": {"id":"w_…", "url":"…", "tier":"fast", "condition":{…},
             "condition_text":"…", "created_at":0, "expires_at":0,
             "checks_performed":0},
  "evidence": {"matched_value":"…", "excerpt":"…", "previous_value":null,
                "http_status":200, "checked_at":0},
  "resume_hint": "one plain sentence describing what happened and what to do",
  "note": "Fields under evidence derive from the watched page…"
}

09Errors

Every error has the same shape, and every message tells your agent how to correct the request.

{"error": {"code": "…", "message": "…", "hint": "…", "docs": "https://stumble.vimabrosta.com/llms-full.txt"}}

A 5xx means retry later. If duration_days exceeds the tier maximum it is clamped, and the 201 response carries a warnings array saying so.

10Machine surfaces

This manual, restated for machines. Fixed addresses, plain text, one fetch.