🛠️ Cron Scheduler

Register any webhook URL to be called on a recurring cron schedule. Supports standard 5-field cron expressions (minute hour dom month dow). SparkForge stores the registration and triggers your webhook at the scheduled time. List or delete your registrations at any time. Up to 20 schedules per wallet.

💡 register: $0.01 | list: $0.001 | delete: free

Request Body

Parameter	Type	Required	Description	Default
`action`	string	required	Operation: register \| list \| delete	—
`webhook`	string	optional	HTTPS URL to POST to on schedule (required for register)	—
`schedule`	string	optional	5-field cron expression, e.g. /5 * * * (required for register)	—
`payload`	object	optional	JSON payload to send to the webhook on each trigger	`{}`
`cronId`	string	optional	Cron ID to delete (required for delete)	—

Response Fields

Field	Type	Description
`action`	string	Operation performed
`cronId`	string	Unique cron registration ID
`schedule`	string	Cron expression that was registered
`webhook`	string	Webhook URL that will be called
`crons`	array	List of your cron registrations (list only)
`success`	boolean	Whether the operation succeeded

Code Examples

cURL

bash

# Register a cron job — fire every 5 minutes
curl -X POST https://sparkforge.sh/api/cron \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <x402-payment-token>" \
  -d '{
    "action": "register",
    "webhook": "https://myagent.example.com/tick",
    "schedule": "*/5 * * * *",
    "payload": { "task": "check-prices" }
  }'

# List your cron jobs
curl -X POST https://sparkforge.sh/api/cron \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <x402-payment-token>" \
  -d '{"action": "list"}'

Python

python

import requests

headers = {"Content-Type": "application/json", "X-PAYMENT": "<token>"}

# Register
r = requests.post("https://sparkforge.sh/api/cron", headers=headers, json={
    "action": "register",
    "webhook": "https://myagent.example.com/tick",
    "schedule": "0 * * * *",  # every hour
    "payload": {"task": "hourly-check"}
})
data = r.json()
print(f"Registered: {data['cronId']}")

# List
r2 = requests.post("https://sparkforge.sh/api/cron", headers=headers, json={"action": "list"})
print(r2.json()["crons"])

TypeScript / Node.js

typescript

// Register
const reg = await fetch402("https://sparkforge.sh/api/cron", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    action: "register",
    webhook: "https://myagent.example.com/tick",
    schedule: "*/5 * * * *",
    payload: { task: "check-prices" },
  }),
});
const { cronId } = await reg.json();
console.log("Registered:", cronId);

Example Response

json

{
  "action": "register",
  "cronId": "cron_1709500000000_abc1234",
  "schedule": "*/5 * * * *",
  "webhook": "https://myagent.example.com/tick",
  "message": "Registered. Your webhook will be called whenever the schedule matches.",
  "success": true
}

💳 Payment via x402

This endpoint costs $0.01 per call, paid in USDC on Base, Polygon, or Solana. Use the @x402/fetch library to handle payments automatically, or implement the x402 handshake manually.

bash

# Free demo mode (no payment)
curl https://sparkforge.sh/api/cron?demo=true

# Or try via MCP (Claude Desktop, Cursor, Windsurf)
# Add to mcp config: { "url": "https://sparkforge.sh/api/mcp" }