RoundWatch

<p align="center">
  <img src="https://roundwatch.observer/roundwatch-og.jpg" alt="RoundWatch — durable Algorand payment monitoring" width="900" />
</p>

<h1 align="center">RoundWatch</h1>

<p align="center">
  <strong>Durable Algorand USDC payment monitoring for autonomous x402 workflows.</strong>
</p>

<p align="center">
  <a href="https://roundwatch.observer/">Website</a> ·
  <a href="https://roundwatch.observer/start">Quickstart</a> ·
  <a href="https://roundwatch.observer/algorand-payment-monitoring-api">Technical guide</a> ·
  <a href="https://roundwatch-api.onrender.com/">Live API</a> ·
  <a href="https://roundwatch-api.onrender.com/openapi.json">OpenAPI</a> ·
  <a href="https://roundwatch-api.onrender.com/llms.txt">llms.txt</a> ·
  <a href="server.json">MCP Registry</a> ·
  <a href="docs/ARCHITECTURE.md">Architecture</a>
</p>

<p align="center">
  <a href="https://github.com/Vladyslav-webDev/RoundWatch/actions/workflows/ci.yml">
    <img src="https://github.com/Vladyslav-webDev/RoundWatch/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" />
  </a>
  <img src="https://img.shields.io/badge/Algorand-MainNet-000000" alt="Algorand MainNet" />
  <img src="https://img.shields.io/badge/x402-v2-6f42c1" alt="x402 v2" />
  <img src="https://img.shields.io/badge/USDC-ASA%2031566704-2775CA" alt="Circle USDC ASA 31566704" />
  <img src="https://img.shields.io/badge/license-MIT-2ea44f" alt="MIT license" />
</p>

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.

## 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](docs/ARCHITECTURE.md) for the normal, recovery, and matching paths.

See [Roadmap](ROADMAP.md) for the current product direction and prioritization.

## Live production service

| Property | Current value |
| --- | --- |
| API | `https://roundwatch-api.onrender.com` |
| Create a watch | `POST /v1/watch` |
| Read a watch | `GET /v1/watch/:id` |
| Health | `GET /health` |
| Network | Algorand MainNet |
| CAIP-2 | `algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=` |
| Asset | Circle USDC, ASA `31566704` |
| Service price | `0.02 USDC` (`20000` atomic units) |
| Service receiver | `EQPLN32HPLPGBCNPOZUL6BL34CTNQGT3VAAMNAJWSIZGQ5CUNXOHB634XY` |
| Facilitator | `https://facilitator.goplausible.xyz` |
| Hosting | Render, with persistent SQLite storage mounted at `/data` |
| Eligibility deadline | 30 minutes from durable creation; terminal `expired` requires complete validated chain coverage through a fixed closing checkpoint |
| Work budget | 500 durable background work turns per watch; exhaustion terminates as `indeterminate`, never as `expired` |
| Open-obligation capacity | 50 globally; 5 per verified service payer |

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

```http
GET /health
```

Production response:

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

### Create a watch

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

Example body:

```json
{
  "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:

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

Request fields:

| Field | Required | Rules |
| --- | --- | --- |
| `idempotencyKey` | Yes | String, 8–128 characters. It is globally unique in the service database. Reuse returns HTTP `409` with the existing public watch record and does not activate a second watch. |
| `expectedSender` | Yes | Checksum-valid 58-character Algorand address. |
| `expectedReceiver` | Yes | Checksum-valid 58-character Algorand address. It is the receiver of the future invoice payment, not necessarily the RoundWatch service receiver. |
| `atomicAmount` | Yes | Positive integer string, at most JavaScript's maximum safe integer (`9007199254740991`). For six-decimal USDC, `1000` means `0.001 USDC`. |
| `invoiceNote` | No | Exact UTF-8 note to match, 1–128 bytes when present. |

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

```http
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:

```json
{
  "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

| State | Meaning |
| --- | --- |
| `settlement_pending` | The watch specification and deterministic service-payment identity are persisted, but activation is not yet proven. Reconciliation can recover a settlement/activation crash window. |
| `active` | The exact service-payment transaction is confirmed; its confirmed round is the activation baseline and initial scan cursor. The poller is looking for the future invoice payment. |
| `matched` | An exact matching future asset transfer was found. The matching transaction ID and confirmed round are stored. |
| `settlement_unknown` | Settlement did not produce an immediately usable activation. An ambiguous outcome remains eligible for exact reconciliation; a definitive on-chain mismatch is terminal and remains fail-closed in this public state. |
| `expired` | The deadline's complete eligible chain range was scanned through a fixed closing checkpoint with no exact match. The terminal record remains readable. |
| `indeterminate` | The durable per-watch work budget was exhausted before a positive match or complete expiry proof. The record is terminal and does not claim absence. |

### 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.