# CronSynth API Guide for AI Agents
# Complete autonomous agent integration documentation

## Service Overview

CronSynth is an externalized cron scheduling service designed specifically for autonomous AI agents operating in serverless environments. It provides time-driven coordination by triggering webhooks on schedule without requiring background processes.

## Core Problem Solved

Serverless AI agents cannot run background timers. When code execution completes, the environment shuts down. CronSynth solves this by:
- Running timers on dedicated infrastructure (Vercel Cron)
- Triggering agent webhooks at scheduled times
- Handling scheduling complexity, timezones, and reliability
- Providing on-chain attestation for reputation systems

## Base URL

Production: https://cronsynth.xyz

## Authentication

All API endpoints require x402 payment protocol authentication via the X-402-Session header.

### Getting a Session

⚠️ CURRENT LIMITATION: CronSynth uses a session-based x402 variant that requires sessions to be created externally, but we don't have a documented working session creation endpoint.

**Standard x402 Protocol** (HTTP 402 flow):
1. Request resource → Receive HTTP 402 Payment Required
2. HTTP 402 includes payment details (amount, recipient, reference)
3. Sign EIP-712 message authorizing payment
4. Send payment via payment facilitator (on-chain settlement)
5. Retry request with X-PAYMENT header containing payment proof

**CronSynth's Current Implementation**:
- Uses session-based variant (not standard HTTP 402 flow)
- Requires pre-created sessions via X-402-Session header
- Sessions must be verifiable via POST {X402_ENDPOINT}/verify
- Sessions must support charging via POST {X402_ENDPOINT}/charge

**How to Get Sessions**:
1. Contact Coinbase CDP: https://docs.cdp.coinbase.com/x402 (request API access)
2. Use payment facilitator: Find Base ecosystem services that provide x402 sessions
3. Standard x402 flow: Not yet supported by CronSynth (known limitation)

**For detailed guidance**: https://cronsynth.xyz/docs/x402_session_creation.md

NOTE: ETHYS is for agent discovery only, NOT payments. x402 is Coinbase's payment protocol.

### Session Format

Header: X-402-Session: <session-token>

## API Endpoints

### 1. POST /api/schedule

Create a new scheduled webhook trigger.

Request Headers:
- X-402-Session: <session-token>
- Content-Type: application/json

Request Body:
{
  "webhookUrl": "https://your-agent.example/webhook",
  "cron": "*/5 * * * *",
  "label": "optional-label"
}

Field Requirements:
- webhookUrl: Must be HTTPS, valid hostname, not blocked IP range
- cron: Standard 5-field cron expression, minimum 1-minute interval
- label: Optional human-readable identifier

Response (200 OK):
{
  "id": "sch_abc123...",
  "nextRun": 1701433200,
  "webhookSecret": "hex-encoded-secret-for-verification"
}

Error Responses:
- 400: Validation error (invalid cron, invalid URL, missing fields)
- 402: Payment required (invalid session, insufficient balance)
- 429: Quota exceeded (free tier: 1 schedule limit)

Cron Expression Rules:
- Format: minute hour day month weekday
- Minimum interval: 1 minute
- Timezone: UTC
- Examples:
  * "*/5 * * * *" - Every 5 minutes
  * "0 */2 * * *" - Every 2 hours
  * "0 0 * * *" - Daily at midnight UTC
  * "0 9 * * 1" - Every Monday at 9 AM UTC

### 2. POST /api/unschedule

Delete a schedule.

Request Headers:
- X-402-Session: <session-token>
- Content-Type: application/json

Request Body:
{
  "id": "sch_abc123..."
}

Response (200 OK):
{
  "ok": true
}

Error Responses:
- 400: Validation error (invalid ID, missing id)
- 402: Invalid session
- 403: Unauthorized (not schedule owner)
- 404: Schedule not found

### 3. GET /api/schedules

List all schedules owned by the authenticated agent.

Request Headers:
- X-402-Session: <session-token>

Response (200 OK):
{
  "schedules": [
    {
      "id": "sch_abc123...",
      "cron": "*/5 * * * *",
      "webhookUrl": "https://agent.example/webhook",
      "label": "rebalance-bot",
      "nextRun": 1701433200,
      "lastRunAt": 1701432900,
      "runCount": 48,
      "paused": false,
      "createdAt": 1701400000
    }
  ]
}

Note: webhookSecret is not included in list responses for security.

Error Responses:
- 402: Invalid session

### 4. GET /api/health

Public health check endpoint (no authentication required).

Response (200 OK):
{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": 1701433200,
  "metrics": {
    "totalSchedules": 1234,
    "totalTriggers": 56789,
    "activeSchedules": 890
  }
}

## Webhook Receiving

When your scheduled time arrives, CronSynth will POST to your webhookUrl.

### Webhook Request

Method: POST
Content-Type: application/json
Headers:
- X-CronSynth-Signature: HMAC-SHA256 signature
- X-CronSynth-Timestamp: Unix timestamp

Body:
{
  "scheduleId": "sch_abc123...",
  "timestamp": 1701433200,
  "runNumber": 48,
  "cron": "*/5 * * * *"
}

### Webhook Security

Always verify the X-CronSynth-Signature header to ensure the request is from CronSynth.

Signature Algorithm: HMAC-SHA256
Secret: webhookSecret from schedule creation response
Payload: JSON body as string
Format: hex-encoded HMAC

Verification Steps:
1. Extract X-CronSynth-Signature header
2. Compute HMAC-SHA256(webhookSecret, JSON.stringify(body))
3. Compare computed signature with header value
4. Reject if mismatch

### Webhook Response Handling

Your webhook endpoint should:
- Return 200 OK within 5 seconds to acknowledge receipt
- Process work asynchronously after responding
- CronSynth will retry on non-2xx responses (up to 3 retries with exponential backoff)

Response Codes:
- 200-299: Success (CronSynth marks trigger as successful)
- 300-499: Client error (CronSynth may retry)
- 500-599: Server error (CronSynth will retry with backoff)

Timeout: 5 seconds
Retry Count: 3 attempts
Retry Backoff: Exponential (1s, 2s, 4s)

## Pricing

### Free Tier
- 1 schedule maximum
- Unlimited triggers per schedule
- No daily trigger limit enforced
- No charge for schedule creation or triggers

### Pay-Per-Trigger
- Unlimited schedules
- $0.001 USDC per trigger
- $0.01 USDC per schedule creation

### Subscriptions
- Hourly: $0.05 USDC/hour (unlimited triggers)
- Weekly: $3.50 USDC/week (unlimited triggers)
- Monthly: $12.00 USDC/month (unlimited triggers)

Payment Network: Base L2 (Chain ID: 8453)
Payment Token: USDC (6 decimals)

## Limits and Constraints

Schedule Limits:
- Free tier: 1 schedule per owner
- Paid tier: Unlimited schedules

Field Size Limits:
- scheduleId: 32 characters
- webhookUrl: 2048 characters
- cron: 100 characters
- label: 100 characters

Webhook URL Requirements:
- Must be HTTPS
- Must be valid hostname (no IP addresses)
- Must not be in blocked IP ranges (see Vercel IP documentation)

Cron Expression Limits:
- Minimum interval: 1 minute
- Maximum lookahead: 1 year
- Timezone: UTC only

## Error Codes

400 Bad Request:
- Invalid cron expression
- Invalid webhook URL
- Missing required fields
- Field validation errors

402 Payment Required:
- Invalid or expired session
- Insufficient balance
- Payment verification failed

403 Forbidden:
- Not schedule owner (for unschedule)
- Access denied

404 Not Found:
- Schedule not found

429 Too Many Requests:
- Free tier quota exceeded
- Rate limit exceeded

500 Internal Server Error:
- Service error (retry with backoff)

## Best Practices

1. Always verify webhook signatures
2. Respond to webhooks quickly (< 5 seconds)
3. Process work asynchronously after responding
4. Use descriptive labels for schedules
5. Monitor your schedule health via /api/schedules
6. Handle retries idempotently
7. Store webhookSecret securely
8. Use appropriate cron intervals (not too frequent)

## Integration Example

Step 1: Get x402 Session
Create session via Coinbase CDP x402 API (https://docs.cdp.coinbase.com/x402)
→ Receive session token

IMPORTANT: x402 is Coinbase's payment protocol (HTTP 402), NOT ETHYS.
ETHYS is a separate service for agent discovery/registration only.

Step 2: Create Schedule
POST https://cronsynth.xyz/api/schedule
Headers: { "X-402-Session": "<token>" }
Body: { "webhookUrl": "https://agent.example/webhook", "cron": "*/5 * * * *" }
→ Receive schedule ID and webhookSecret

Step 3: Implement Webhook Endpoint
POST https://agent.example/webhook
- Verify X-CronSynth-Signature
- Process scheduled task
- Return 200 OK quickly

Step 4: Monitor
GET https://cronsynth.xyz/api/schedules
→ Check schedule status and run counts

## On-Chain Attestation

CronSynth provides best-effort on-chain attestation for reputation systems.

Contract: 0x3846Ab73eCb4A1590B56cEB88D9779471B82A314
Network: Base Mainnet (Chain ID: 8453)

Events:
- ScheduleCreated: When schedule is created
- ScheduleTriggered: When webhook is triggered
- SchedulePaused: When schedule is paused
- ScheduleResumed: When schedule is resumed
- ScheduleDeleted: When schedule is deleted

Note: Attestation is best-effort. Network congestion may cause delays.

## Discovery Files

For complete service discovery, see:
- /.well-known/ai-plugin.json - AI plugin manifest
- /.well-known/openapi.json - OpenAPI specification
- /.well-known/agents.json - Agent service discovery
- /.well-known/agent-card.json - ETHYS agent card
- /.well-known/x402.json - x402 protocol configuration
- /llms.txt - LLM integration guide
- /robots.txt - Web crawler instructions
- /sitemap.xml - Site structure

## Support

FAQ: https://cronsynth.xyz/docs/faq.md (answers to common questions)
User Guide: https://cronsynth.xyz/docs/user_guide.md
Status: https://cronsynth.xyz/api/health

## Related Services

- BlockWire (https://blockwire.xyz) - Real-time blockchain events
- ETHYS (https://ethys.dev) - Agent discovery and registration (separate from x402 payments)
- Coinbase CDP x402 (https://docs.cdp.coinbase.com/x402) - Payment protocol (HTTP 402)

## Version

API Version: 1.0.0
Last Updated: 2025-01-30