# RoundWatch

> RoundWatch is a durable payment-monitoring API for one exact future Algorand USDC payment when no transaction ID exists yet.

RoundWatch lets a short-lived agent or service define an expected payment, pay once for a durable watch through x402, exit, and later retrieve verified on-chain evidence.

## Use RoundWatch when

- You need to detect one exact future Algorand USDC transfer.
- The future transfer does not have a transaction ID yet.
- The caller should be able to terminate instead of running its own polling worker.
- Restart recovery and persisted scan progress matter.

## Do not use RoundWatch when

- You already know the transaction ID and only need ordinary confirmation.
- You already operate durable Algorand Indexer ingestion or equivalent subscriber infrastructure.
- You require a push webhook callback. RoundWatch is not a webhook delivery service; clients retrieve durable state later.

## Production contract

- Network: mainnet
- CAIP-2: algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=
- Watched asset: Algorand USDC ASA 31566704
- Create watch: POST /v1/watch
- Read watch: GET /v1/watch/{id}
- Recover lost watch ID after a paid response is lost (free): POST /v1/watch/recover
- Service price: 0.02 USDC (20000 atomic units)
- Service receiver: EQPLN32HPLPGBCNPOZUL6BL34CTNQGT3VAAMNAJWSIZGQ5CUNXOHB634XY
- Eligibility window: 1800000 ms from durable watch preparation; settlement time consumes part of this window
- Round boundary: transaction confirmed-round must be strictly greater than activationRound; the service-settlement round itself is ineligible
- Time boundary: transaction block round-time must be strictly earlier than expiresAt; a block timestamp exactly equal to expiresAt is ineligible
- Work budget: 500 durable background turns per watch
- x402 version: 2
- x402 scheme: exact

The x402 payment buys the RoundWatch monitoring service. It is separate from the future USDC payment that RoundWatch watches.

## Machine-readable API

- OpenAPI: https://roundwatch-api.onrender.com/openapi.json
- LLM instructions: https://roundwatch-api.onrender.com/llms.txt
- MCP Streamable HTTP: https://roundwatch-api.onrender.com/mcp
- MCP preferred protocol version: 2026-07-28
- Liveness: https://roundwatch-api.onrender.com/health
- Readiness: https://roundwatch-api.onrender.com/ready
- API root: https://roundwatch-api.onrender.com
- GitHub: https://github.com/Vladyslav-webDev/RoundWatch

The MCP server exposes read-only discovery and status tools plus preparation tools for the paid create request and the free exact recovery request. For modern MCP calls, send MCP-Protocol-Version: 2026-07-28 and the same protocol version in _meta.io.modelcontextprotocol/protocolVersion. The MCP layer does not hold a wallet and does not sign or settle the x402 payment.

## Human documentation

- Product: https://roundwatch.observer/
- Quickstart: https://roundwatch.observer/start
- Technical guide: https://roundwatch.observer/algorand-payment-monitoring-api

## Core behavior

A watch exact-matches sender, receiver, server-selected USDC ASA, atomic amount, and optional exact note for one top-level direct asset transfer. Unsigned create requests receive HTTP 402 with PAYMENT-REQUIRED and Bazaar input metadata before semantic body validation. Treat that 402 as service/discovery metadata, not as approval of the submitted body. On a retry carrying PAYMENT-SIGNATURE, RoundWatch parses and validates the watch specification before facilitator verification or settlement; invalid signed input returns HTTP 400 and cannot spend. Inner transactions, clawback transfers, and asset close-out transfers are outside the current matching contract and do not count as payments. Eligibility lasts 1800000 ms from durable watch preparation before x402 settlement completes, so settlement time consumes the window. The watched payment must confirm in a round strictly greater than activationRound; a same-round payment is ineligible. Its Algorand block round-time must be strictly earlier than expiresAt; a payment exactly at the deadline is ineligible. A successful create call returns a durable watch ID only after x402 settlement and durable activation are confirmed. Persist that ID immediately. If the paid create may have succeeded but its response was lost, do not repay: POST the exact original watch specification plus servicePayer to /v1/watch/recover. Recovery is free and exact-match only. Once RoundWatch confirmed the service settlement, recovery remains available even after the watch becomes expired or post-activation indeterminate; unsettled or settlement-ambiguous obligations remain hidden. Status retrieval is free and marked no-store. Terminal matched evidence includes the matching Algorand transaction ID and confirmed round. A terminal settlement-reconciliation outcome is explicitly surfaced on the watch record. Expiry is proof-based after complete indexed coverage; work-budget exhaustion returns indeterminate rather than claiming absence.