ai-cron-site

# cron402

x402-native **cron-as-a-service for AI agents**. Agents schedule webhook calls and pay per run in USDC on Base via the [x402 protocol](https://www.x402.org/) — no accounts, no API keys. The wallet *is* the credential.

- **Price:** $0.008 flat per run
- **Network:** Base mainnet (`eip155:8453`) — validated end-to-end on Sepolia first (settlement tx `0x01f7bed4…`)
- **Wallets:** built for Coinbase Agentic Wallets / any x402 client

---

## Architecture

```
┌────────────────────────────┐        ┌─────────────────────────────────────────┐
│  apps/web — SvelteKit      │        │  apps/api — Cloudflare Worker (Hono)    │
│  deployed to Vercel        │──────▶ │                                         │
│  - landing page            │        │  x402 paywall (@x402/hono v2)           │
│  - agent integration docs  │        │  ├─ POST /v1/crons            $0.008    │
│                            │        │  ├─ POST /v1/crons/topup/1|10|100       │
│                            │        │  ├─ GET  /v1/crons/:id        (free)    │
│                            │        │  ├─ POST /v1/crons/:id/pause|resume     │
│                            │        │  └─ DELETE /v1/crons/:id   (EIP-712)    │
└────────────────────────────┘        │                                         │
                                      │  CronJobDO (Durable Object per job)     │
                                      │  alarm() → dispatch webhook             │
                                      │  D1: jobs, executions, payments         │
                                      └─────────────────────────────────────────┘
                                                │ settle via facilitator
                                                ▼
                                         USDC on Base (Sepolia/mainnet)
```

### How scheduling works

- Every job gets its own **Durable Object** (`CronJobDO`). A `cron-parser`-computed next-run time is set as the DO's `alarm()` — exact to the minute for arbitrary cron expressions.
- Each fire: dispatch the target webhook (10s timeout) → up to 3 attempts with backoff → log the execution to D1 (kept: last 100 runs / 30 days per job) → consume 1 credit.
- Auto-pause rules: 3 consecutive failures → `paused`; zero credits → `exhausted`.
- A global Worker Cron Trigger (`* * * * *`) sweeps for missed alarms as a safety net.
- Top-ups reactivate `paused`/`exhausted` jobs automatically.

### How payments work

Paid endpoints are gated by [`@x402/hono`](https://www.npmjs.com/package/@x402/hono) v2 middleware:

1. Agent calls the endpoint with no auth.
2. Server responds `402 Payment Required` with instructions (price, network, `payTo`).
3. Agent signs an EIP-3009 USDC transfer from its wallet and retries.
4. The facilitator verifies + settles; settlement receipts land in D1.

Because the payer isn't online when an alarm fires, billing is **prepaid run credits**: creation includes 1 credit; packs of 1 / 10 / 100 cost $0.008 / $0.08 / $0.80. Credits never expire and top-ups are permissionless (anyone can fund any job).

Management actions (`pause`/`resume`/`delete`) require an EIP-712 signature over `ManageJob { action, jobId, timestamp }` from the payer key (±5 min validity).

---

## Repository layout

```
dev/ai-cron-site/
├── package.json               # pnpm workspaces + turbo tasks
├── turbo.json                 # build/check/lint pipeline
├── biome.json                 # Biome lint/format config
├── .env.example               # all env vars documented
├── packages/shared/
│   └── src/                   # zod schemas, constants, types, JSON Schemas
├── packages/mcp/
│   ├── src/index.ts           # cron402-mcp: MCP server (10 agent tools)
│   ├── src/schedule.ts        # plain-English → cron parsing, validation, next-run preview
│   └── src/store.ts           # remembers created job ids for list_crons
├── skills/cron402/SKILL.md    # drop-in agent skill for using the MCP server
└── apps/
    ├── api/                   # Cloudflare Worker
    │   ├── wrangler.jsonc     # DO bindings, D1 binding, cron trigger
    │   ├── .dev.vars.example  # local dev vars template
    │   ├── migrations/        # D1 schema (0001 init, 0002 notify_url)
    │   └── src/
    │       ├── index.ts       # Hono app, routes, lazy x402 middleware
    │       ├── scheduler.ts   # CronJobDO (alarm loop, retries, retention, notify)
    │       ├── auth.ts        # EIP-712 management-signature verification
    │       ├── payments.ts    # payer extraction from x402 headers
    │       ├── facilitator.ts # CDP hosted facilitator client
    │       ├── cdp-auth.ts    # CDP JWT signing (jose/WebCrypto)
    │       ├── openapi.ts     # OpenAPI 3.1 document builder
    │       └── types.ts       # Env bindings + typed DO stub interface
    └── web/                   # SvelteKit 5 → adapter-vercel (MS-DOS theme)
        └── src/routes/
            ├── +page.svelte          # landing
            ├── docs/+page.svelte     # agent integration guide
            ├── dashboard/+page.svelte # wallet-connected job console
            ├── llms.txt/+server.ts   # agent-readable site summary
            └── robots.txt/+server.ts # crawler policy (AI bots allowed)
```

## API reference

| Endpoint | Auth | Price | Description |
|---|---|---|---|
| `POST /v1/crons` | x402 | $0.008 | Create job (body: `{ schedule, target: { url, method?, headers?, body? }, maxRuns? }`). Includes 1 run credit. |
| `POST /v1/crons/topup/1` | x402 | $0.008 | Add 1 credit (body: `{ jobId }`) |
| `POST /v1/crons/topup/10` | x402 | $0.08 | Add 10 credits |
| `POST /v1/crons/topup/100` | x402 | $0.80 | Add 100 credits |
| `GET /v1/crons/:id` | free | — | Job status, credits, last 20 executions |
| `POST /v1/crons/:id/pause` | wallet-signed | — | Pause job |
| `POST /v1/crons/:id/resume` | wallet-signed | — | Resume job (requires credits) |
| `DELETE /v1/crons/:id` | wallet-signed | — | Delete job |
| `GET /health` | free | — | Liveness probe |
| `POST /v1/echo` | free | — | Test target for smoke tests |

Signed requests add two headers:
- `x-cron402-timestamp`: unix ms (valid ±5 min)
- `x-cron402-signature`: EIP-712 signature, domain `{ name: "cron402", version: "1" }`, primaryType `ManageJob`

### Limits & policies (v1)

- Min interval: 1 minute · Max 1,000 active jobs per payer wallet
- Retry policy: 3× with 1s/3s/8s backoff; non-retryable 4xx (except 429) fails immediately
- Log retention: last 100 executions or 30 days per job, whichever trims first

---

## Deployment status (live)

| Surface | URL |
|---|---|
| API (Cloudflare Workers) | https://cron402-api.user-defaults.workers.dev |
| Web (Vercel) | https://agentcron.site |
| OpenAPI spec | https://cron402-api.user-defaults.workers.dev/v1/openapi.json |
| Agent summary | https://agentcron.site/llms.txt |
| Job console | https://agentcron.site/dashboard |

Network: **Base mainnet** (`eip155:8453`) — flipped from Sepolia after a fully verified paid run. Receiving wallet secret `PAY_TO_ADDRESS` is set on the Worker. Facilitator: **Coinbase CDP hosted** (`CDP_API_KEY_ID`/`CDP_API_KEY_SECRET` secrets set; JWT auth implemented in `src/cdp-auth.ts`). D1 database `cron402` (id `b7e05d96-4737-4aa4-ab52-badcfacb3a22`) holds the schema from both migrations.

**Bazaar:** bazaar extensions are declared via `@x402/extensions/bazaar` (`info.input.type: "http"`); listing appears after a successful CDP settle that echoes the extension — do not claim currently indexed until validated.

### Execution webhooks

Pass optional `notifyUrl` when creating a job. After every fire, cron402 POSTs to it:

```json
{
  "type": "cron402.execution",
  "jobId": "…",
  "runAt": 1755000000000,
  "ok": true,
  "attempts": 1,
  "statusCode": 200,
  "error": null,
  "durationMs": 42
}
```

Notifications are best-effort (10s timeout, never affect scheduling).

### Human dashboard

`/dashboard` connects any injected EIP-1193 wallet (MetaMask etc.). Load a job by id to see status/credits/executions; pause/resume/delete request an `eth_signTypedData_v4` signature over `ManageJob` — exactly what agents sign, just through a browser wallet.

### MCP server (`cron402-mcp`)

Ten tools for any MCP client, designed so a **small model can schedule a cron without burning money on mistakes**:

| Tool | Cost | Purpose |
|---|---|---|
| `cron402_guide` | free | The full procedure, prices and rules — what a model reads first |
| `check_wallet` | free | Address, network, USDC/ETH balance, runs affordable |
| `preview_schedule` | free | Validate a schedule, show the next 5 UTC run times |
| `create_cron` | $0.008 | Create a job (includes 1 credit) |
| `topup_cron` | $0.008–$0.80 | Add 1 / 10 / 100 credits |
| `get_cron` | free | Status, credits, last 20 executions |
| `list_crons` | free | Jobs created from this machine, with live status |
| `pause_cron` · `resume_cron` · `delete_cron` | free | EIP-712 signed management |

What makes it usable by weak models:

- **Plain-English schedules** — `"every 15 minutes"`, `"every weekday at 9am"`, `"every monday at 5pm"`, `"weekly"`, or raw cron. Ambiguous input (`"every 2 weeks"`, `"at teatime"`) fails loudly with a suggested fix instead of silently scheduling the wrong time.
- **Timezone conversion** — pass an IANA `timezone` and the time-of-day is converted to the UTC cron the API stores, with the DST caveat spelled out in the response.
- **Free dry run before any spend** — `preview_schedule` costs nothing, and `create_cron` re-validates locally so a malformed schedule never reaches a paid request.
- **Money guardrails** — paid tools are labelled `PAID` with the exact amount, and every response carries a `next_step` telling the model not to call them twice.
- **Actionable errors** — `{ ok, error, next_step }` for insufficient funds, an unreachable API, a job owned by another wallet, or a `localhost` target.
- **Job memory** — the API has no list endpoint, so created ids are written to `~/.cron402/jobs.json` (override with `CRON402_