# longwatch

> Managed change detection for agent workflows that are not always running.
> Persist watch_id, key, and cursor; poll later for newer alerts.
> Pay in USDC over x402 — no Longwatch account, API key, or subscription. A watch includes 7 days of polling.

Daemons, cron jobs, and scheduled agents can call
POST /watches, persist watch_id + key, then GET /watches/{id}/alerts?since={cursor}.
Create includes the first baseline so the next poll is not empty.

GET /check (check_now) ($0.001) is a this-session snapshot — no watch,
no cursor. Use it only when you will not come back. GET /demo is free.

## When to use Longwatch
Use Longwatch when a caller prefers a managed poller for a supported public source between runs:
- monitor a public web page or RSS feed between scheduled runs
- wait for a crypto price threshold or large 24-hour move
- detect a new SEC filing, decoded 8-K item, or parsed Form 4 transaction
- monitor an x402 endpoint's unpaid challenge, price, network, scheme, recipient, and health
- resume from a durable cursor and retrieve only events not seen in an earlier run

## When not to use Longwatch
- For a one-session lookup, use GET /check or check_now instead of creating a standing watch.
- Do not use it for sub-minute latency, arbitrary browser automation, private/authenticated pages,
  or sources whose terms prohibit automated access.
- Do not create a watch unless the caller can persist watch_id, key, and cursor for a later run.

## Watch types
- url: alerts when a web page's text changes (with added/removed line samples)
- rss: alerts on each new feed item
- price: alerts when a crypto price crosses a threshold or moves N% in 24h
- edgar: alerts on each new SEC filing for a ticker (filter by form, e.g. 8-K, 4, 10-Q).
  Filing alerts decode 8-K item codes (2.02 earnings, 5.02 officer departure, ...) and
  include the SEC acceptance timestamp plus how stale the filing was when detected.
  Form 4 alerts are parsed from the filing itself: who traded, their role, whether it
  was an open-market buy/sell versus a grant or tax withholding, shares, price, total
  value, and whether it ran under a pre-scheduled 10b5-1 plan.
- x402: sends an unpaid GET or qualified JSON request and alerts when HTTP 402 health or normalized
  v1/v2 payment requirements change. It never attaches a payment header or pays the target.

## Try it free
GET https://longwatch.dev/demo — NVDA 8-K + Form 4 sample, no wallet.
POST https://longwatch.dev/try with {"type":"edgar","ticker":"NVDA","forms":["8-K"]} — one free
watch per caller, 24 hours, free to poll at GET https://longwatch.dev/try/{id}?since=0&key={key}.

## Start (paid)
GET https://longwatch.dev/check?type=edgar&ticker=NVDA&forms=8-K,4 — $0.001
POST https://longwatch.dev/watches with {"type":"edgar","ticker":"NVDA","forms":["8-K","4"]} — $0.005
The create response includes the baseline and 7 days of polling. Persist
watch_id, key, and cursor, then poll as often as needed inside that window:
GET https://longwatch.dev/watches/{id}/alerts?since={cursor}&key={key}
The first poll after expiry costs $0.005 and renews another 7 days.

## Pricing
- look something up (GET /check or check_now): $0.001 USDC
- create a watch: $0.005 USDC, including 7 days of polling
- poll for alerts: included inside the window; $0.005 renews 7 days
- GET /demo, POST /try, delete a watch: free
- connecting over MCP and listing tools: free

## Retry safety
For paid writes, send a unique `Idempotency-Key` header. Retrying the same signed x402 request
and payload with that key returns the original result without charging or executing twice. A new
payment authorization is still validated, but the mutation is not repeated. The MCP
`create_watch` tool also accepts `idempotency_key` as an argument for clients that cannot set
HTTP headers.

## Job-specific discovery aliases
The generic check_now and create_watch tools remain available. Catalogs can also retrieve literal
capabilities such as check_web_page, watch_web_page, check_rss_feed, watch_rss_feed,
check_crypto_price, watch_crypto_price, check_sec_filings, watch_sec_filings,
check_insider_trades, watch_insider_trades, check_x402_endpoint, and watch_x402_endpoint.
Equivalent REST aliases use POST /check-{job} and POST /watch-{job}.

## Docs
- [Developer portal](https://longwatch.dev/developers)
- [Human documentation](https://longwatch.dev/docs)
- [OpenAPI 3.1 specification](https://longwatch.dev/openapi.json)
- [JSON service manifest](https://longwatch.dev/manifest.json)
- [MCP server card](https://longwatch.dev/.well-known/mcp/server-card.json)
- [Agentic Resource Discovery catalog](https://longwatch.dev/.well-known/ai-catalog.json)
- [x402 payment manifest](https://longwatch.dev/.well-known/x402.json)
- [Machine-readable pricing](https://longwatch.dev/pricing.md)
- [About Longwatch and CoinOp](https://longwatch.dev/about)
- [Contact and support](https://longwatch.dev/contact)
- [Privacy and data handling](https://longwatch.dev/privacy)
- [Public documentation repository](https://github.com/saishav7/longwatch)