RoundWatch

RoundWatch watches one exact future Algorand MainNet USDC payment when no transaction ID exists yet. A caller defines the expected payment, pays a one-time x402 service fee, receives a durable watch ID, and can exit. RoundWatch persists the obligation and scan progress, then exposes verified on-chain evidence for later retrieval.

Production: Algorand MainNet · Circle USDC · x402 v2 · GoPlausible facilitator · Bazaar cataloged · remote MCP endpoint · durable restart recovery.

What it solves

A short-lived agent, job, or service may need to know whether a particular payment arrives after the caller has stopped running. Keeping that caller alive to poll an Algorand Indexer is unnecessary if a durable observer can own the wait instead.

RoundWatch lets a caller define the expected payment, purchase one watch through x402, and exit. The service persists the obligation, continues scanning Algorand, and records the matching transaction for later retrieval.

A backend that already operates durable Indexer or subscriber infrastructure may reasonably implement this itself. RoundWatch is for callers that do not want to own that operational component.

Related MCP server: Amanah MCP

Lifecycle

1. The client submits the exact expected sender, receiver, atomic amount, and optional invoice note.

2. x402 returns payment requirements and the client signs the service payment locally.

3. GoPlausible verifies and settles the service payment.

4. RoundWatch activates the persisted watch only after the exact service-payment transaction is confirmed; that transaction's confirmed round becomes the scan baseline.

5. The caller may exit while RoundWatch polls the Algorand Indexer.

6. The watch becomes matched when an exact future USDC asset transfer appears.

7. The caller reads the durable result with GET /v1/watch/:id.

See Architecture for the normal, recovery, and matching paths.

See Roadmap for the current product direction and prioritization.

Live production service

The production server does not contain or need a wallet mnemonic or private key.

Economics v1 is live in production as of 2026-09-20 at 80ed94c746f2eac4a784a3738c6dbe8306ecfa3e. An external unsigned POST /v1/watch received HTTP 402 and verified MainNet, exact, ASA 31566704, the approved receiver, challenge tag, and amount 20000. The historical paid MainNet proof below remains evidence of the earlier 0.001 USDC contract.

API

Health

GET /health

Production response:

{
  "status": "ok",
  "network": "mainnet"
}

Create a watch

POST /v1/watch
Content-Type: application/json

Example body:

{
  "idempotencyKey": "invoice-2026-09-16-001",
  "expectedSender": "3YFZ47IAKPB4H6B7U6MXI35HCAB5E6DA47UANIHOON53J7I5SMXUSYQXQQ",
  "expectedReceiver": "EQPLN32HPLPGBCNPOZUL6BL34CTNQGT3VAAMNAJWSIZGQ5CUNXOHB634XY",
  "atomicAmount": "1",
  "invoiceNote": "roundwatch:invoice-2026-09-16-001"
}

An ordinary request receives 402 Payment Required. An x402-capable client reads the payment requirements, signs the advertised service payment, and retries the same request. RoundWatch returns success only after settlement and durable activation succeed:

{
  "watchId": "f5d2fb6f-b224-4aae-989c-87a5418fd2ae",
  "message": "The watch is returned only if x402 settlement and durable activation succeed"
}

Request fields:

The watched asset is not a request field. The server selects the USDC ASA from its explicit network configuration: MainNet ASA 31566704 or TestNet ASA 10458941.

The server controls the lifetime, work budget, and admission policy. New watches have an immutable eligibility deadline 30 minutes after createdAt and a durable 500-turn background work budget; callers cannot override either value. Passing the wall-clock deadline does not itself expire a watch; proof requires complete chain coverage through a closing checkpoint. If the work budget is exhausted first, the watch terminates as indeterminate with terminalReason=work_budget_exhausted, never as a false expired. At most 50 unfinished obligations may be open globally and at most 5 may be open for the verified service payer. Capacity exhaustion returns HTTP 429 before settlement.

Read a watch

GET /v1/watch/f5d2fb6f-b224-4aae-989c-87a5418fd2ae

The response is { "watch": ... }. This abridged matched example shows the stable consumer-facing fields; the live record also exposes settlement and scan metadata when available:

{
  "watch": {
    "id": "f5d2fb6f-b224-4aae-989c-87a5418fd2ae",
    "state": "matched",
    "expectedSender": "3YFZ47IAKPB4H6B7U6MXI35HCAB5E6DA47UANIHOON53J7I5SMXUSYQXQQ",
    "expectedReceiver": "EQPLN32HPLPGBCNPOZUL6BL34CTNQGT3VAAMNAJWSIZGQ5CUNXOHB634XY",
    "assetId": 31566704,
    "atomicAmount": "1",
    "invoiceNote": "roundwatch:invoice-2026-09-16-001",
    "createdAt": "2026-09-16T12:00:00.000Z",
    "expiresAt": "2026-09-16T12:30:00.000Z",
    "matchedTransaction": "VZKWYELPR4HHXPXM476NRLNU4JUKAEUUD4HGHFNAHDRD5IBFB2MA",
    "matchedRound": 65096073
  }
}

Unknown IDs return HTTP 404.

Watch states

Exact matching

A transaction matches only when all configured properties agree:

• sender;

• receiver;

• network-selected USDC ASA;

• atomic amount; and

• invoice note, when the request supplied one.

Only confirmed asset transfers strictly after the confirmed service-payment round are considered; same-round invoice transfers remain excluded. Sender, receiver, ASA, atomic amount, and optional note must match, and the transaction block time must be strictly before the creation-based deadline. Processing time does not affect eligibility.

x402 payment and recovery

The Hono resource server uses x402 v2 and the hosted GoPlausible facilitator. Before settlement, RoundWatch persists the deterministic Algorand service-payment transaction ID and immutable receiver, ASA, atomic amount, payer, FirstValid, and LastValid terms derived from the verified signed payload. After settlement, an exact Indexer lookup supplies the confirmed service-payment round, which becomes both the activation baseline and initial cursor.

If the process stops after on-chain settlement but before activation is committed, the reconciliation worker looks up that exact transaction under persisted exponential backoff. It activates only when the original immutable terms agree. A bare 404 is retryable; only a sufficiently covered post-LastValid historical absence search can establish terminal nonpayment. A definitive confirmed mismatch fails closed.

All Indexer calls share one token-bucket/concurrency dispatcher. Scans use finite round windows and page-level validation; each page and retry consumes capacity. Each durable work turn is additionally guarded to at most four logical Indexer request opportunities for active polling or three for settlement reconciliation, so the default 500-turn contract has a conservative 2,000-background-request ceiling. Validated historical scan pages may be reused across sweeps, but the process-local LRU is bounded by both entry count and serialized payload bytes. Pagination tokens stay in memory, so restart replays the unfinished window from its durable cursor. When the deadline has passed, RoundWatch fixes an indexed block whose timestamp is at or after the deadline as closingRound; only complete validated coverage through that round can produce expired. Status reads never manufacture expiry from wall time.

Local development

Requirements:

• Node.js 24;

• pnpm 12.3.4 (declared by the workspace); and

• a TestNet account only if you intentionally exercise a paid local flow.

Install dependencies:

pnpm install --frozen-lockfile

Copy apps/server/.env.example to apps/server/.env and configure a public TestNet receiver address:

ROUNDWATCH_NETWORK=testnet
AVM_ADDRESS=<public TestNet receiver address>
FACILITATOR_URL=https://facilitator.goplausible.xyz
ROUNDWATCH_DB_PATH=data/roundwatch.sqlite
ROUNDWATCH_POLL_INTERVAL_MS=5000
ROUNDWATCH_RECONCILE_INTERVAL_MS=5000
ROUNDWATCH_WATCH_TTL_MS=1800000
ROUNDWATCH_MAX_OPEN_WATCHES=50
ROUNDWATCH_MAX_OPEN_WATCHES_PER_PAYER=5
ROUNDWATCH_WORK_UNIT_BUDGET=500
ROUNDWATCH_INDEXER_REQUESTS_PER_SECOND=4
ROUNDWATCH_INDEXER_BURST=4
ROUNDWATCH_INDEXER_CONCURRENCY=2
ROUNDWATCH_SCAN_ROUND_WINDOW=100
ROUNDWATCH_SCAN_PAGE_CACHE_ENTRIES=16
ROUNDWATCH_SCAN_PAGE_CACHE_BYTES=8388608
ROUNDWATCH_SCAN_QUERY_VARIANT=C
PORT=4021

Then start the server:

pnpm dev:server

Free checks:

curl -i http://localhost:4021/health
curl -i -X POST http://localhost:4021/spike/watch \
  -H "content-type: application/json" \
  --data '{"idempotencyKey":"local-invoice-001","expectedSender":"3YFZ47IAKPB4H6B7U6MXI35HCAB5E6DA47UANIHOON53J7I5SMXUSYQXQQ","expectedReceiver":"EQPLN32HPLPGBCNPOZUL6BL34CTNQGT3VAAMNAJWSIZGQ5CUNXOHB634XY","atomicAmount":"1"}'

The second request should return HTTP 402 before any payment. The server's default local route is /spike/watch, not the production /v1/watch route.

Paid TestNet utilities use apps/client/.env and keep signing in the client process. Never use a funded MainNet mnemonic for local development and never commit an .env file. The automated test suite does not require a wallet or make payments.

TestNet and MainNet separation

See Deployment before operating MainNet.

Tests and CI

Run the local verification suite:

pnpm typecheck
pnpm -C apps/server test
pnpm -C apps/client test
docker build -t roundwatch-local .

GitHub Actions performs a full-depth checkout, scans complete Git history with Gitleaks, rejects tracked .env files other than examples, installs from the frozen lockfile, typechecks both workspaces, runs server and MainNet safety tests, and builds the production image. Tests are synthetic/read-only and do not authorize MainNet spending.

Security model

• Wallet signing belongs to the client; the resource server needs only its public receiver address.

• MainNet startup validates the network, receiver address, HTTPS endpoints, public base URL, and persistent database path.

• Service settlement is reconciled against exact on-chain fields before recovery activation.

• Future invoice matching is exact, and activation never starts without a safe round cursor.

• SQLite uniqueness on the idempotency key prevents duplicate watch creation.

• Transactional global/per-payer admission and the shared finite Indexer dispatcher bound persistent and external work; capacity rejection happens before settlement.

• .env files and wallet material must never be committed; CI enforces tracked-env and full-history secret checks.

The status API is not an authenticated vault: anyone who knows a watch ID can query its public record. Do not put sensitive information in invoiceNote or use RoundWatch metadata as a secret store. See Security for trust boundaries and operational assumptions.

MainNet proof

The production flow was executed successfully on 2026-09-16:

• x402 service settlement: OJMUUHJPZVXS6MNW4TISXXAZIHAPNYNM446DAFY35OAJOBDDOPYA, confirmed round 65095955;

• durable watch: 7c606f02-0257-4dfd-b59c-a13b61f480f0;

• later invoice transfer: VZKWYELPR4HHXPXM476NRLNU4JUKAEUUD4HGHFNAHDRD5IBFB2MA, confirmed round 65096073;

• RoundWatch reported the same invoice transaction as matched at round 65096073.

Independent MainNet Indexer verification confirmed both transfers used Circle USDC ASA 31566704, the expected sender and receiver, and atomic amounts 1000 for the service payment and 1 for the watched invoice. The matched watch persisted across multiple Render redeploys.

After the initial MainNet proof, the production service received a larger correctness/resource hardening merge at 18e8712431bc02a904dd5a3f227b2f5a49e9f6f7. That release replaced wall-clock-only expiry with chain-time eligibility plus a fixed closing checkpoint, activated watches from the exact confirmed service-payment round, bounded all Indexer work through a shared dispatcher, added fair bounded servicing across watches, and strengthened settlement reconciliation and pagination validation. Render deployed that merge successfully and free production smoke checks returned the expected MainNet health, x402 402, and status behavior.

A follow-up production fix at d05fabaea6124ed5658dd13cf06167a885aefeb0 replaced an invalid Bazaar example receiver with a checksum-valid Algorand address and added regression coverage. A post-deploy external 402 smoke decoded the live payment-required header and verified the production URL, MainNet network, exact scheme, ASA 31566704, amount 1000, and checksum-valid Bazaar example addresses. No second paid MainNet E2E was performed after these hardening releases or is implied.

GoPlausible Bazaar had already discovered the production resource with the correct URL, network, asset, amount, receiver, challenge tag, and settleCount: 1. On 2026-09-16, the merchant leaderboard entry showed bazaar: true, challenge: true, settles: 1, and volume: 0.001. Its observed rank of 145 among 147 entries is a dated observation, not a permanent project property.

Detailed evidence is in MainNet Readiness.

Current limitations

• The current challenge-release policy is a 30-minute eligibility deadline, a 500-turn durable work budget, 50 global open obligations, and 5 open obligations per verified service payer. These are operational safety bounds, not a commercial SLA or final pricing/capacity policy.

• There is no cancellation operation, SLA, or long-term pricing policy.

• The current deployment is a single application instance with an in-process poller/reconciler and local persistent SQLite. It is not a horizontally coordinated worker system.

• Each poll sweep gives every active watch at most one bounded servicing turn; pagination yields between sweeps, and FIFO Indexer dispatch enforces the global request bound. The tuning values are not an SLA or arbitrary-scale claim.

• Results are retrieved by polling; there is no webhook or push-notification API.

• Watch status is readable without authentication by anyone who knows the watch ID.

Repository structure

.
├── apps/
│   ├── server/              # Hono API, x402 integration, SQLite, Indexer workers
│   └── client/              # TestNet utilities and guarded MainNet verification runner
├── docs/
│   ├── ARCHITECTURE.md
│   ├── DEPLOYMENT.md
│   ├── MAINNET_READINESS.md
│   ├── SECURITY.md
│   ├── FAULT_INJECTION.md
│   └── ROUNDWATCH_SPIKE.md
├── .github/workflows/ci.yml
├── Dockerfile
└── README.md

Historical TestNet development evidence remains in RoundWatch Spike and Fault Injection. The current product and production contract are described here and in the four operational documents linked above.