Cron Jobs · Event Triggers · Persistent Queue

AI Agent Task Scheduler

Cron Jobs and Event-Driven Automation for Autonomous Agents

Register persistent cron schedules and event-driven triggers that fire even when your agent is offline. Purple Flea keeps the job alive and sends a webhook when it's time to act.

Get API Key Webhook API Docs
4 Trigger Types
Persistent Survives Restarts
<1s Trigger Latency
∞ Jobs per Agent

Overview

Agents Need to Run on a Schedule

Autonomous AI agents are not always running. A trading agent might be invoked per-request by a user, or run as a serverless function that spins up only when needed. Even agents running continuously in a server process face the same fundamental problem: they cannot block on a sleep loop waiting for the next rebalancing window, a price threshold to be crossed, or a wallet transaction to arrive. Doing so wastes resources, ties up the process, and introduces fragility when the agent process restarts.

Purple Flea's scheduler is the infrastructure solution to this problem. Instead of your agent managing its own timers and event loops, it registers jobs with Purple Flea once, and Purple Flea takes responsibility for tracking time and conditions. When a job fires — whether it is a cron schedule, a price crossing a threshold, an incoming transaction, or an options contract approaching expiry — Purple Flea delivers a webhook POST to your registered endpoint. Your agent wakes up, handles the event, and goes back to sleep. The job persists in Purple Flea's queue across agent restarts, redeployments, and infrastructure events.

This decoupling between job registration and job execution is what makes truly autonomous agent behaviour possible at scale. A single agent can register hundreds of simultaneous jobs — daily compounding for each yield position, hourly rebalancing checks, per-token stop-loss monitors — without any of that logic living in the agent's own runtime. The agent's compute is used only when there is work to do, not while it is waiting for something to happen.

Works Best With

Trading API Price Oracle API Webhook API Yield Aggregator API DeFi Yield Agent

Trigger Types

Four Ways to Schedule Agent Actions

Each trigger type fires independently. A single agent can have any mix of all four types active simultaneously.

◯

1. Cron Schedules

Standard five-field cron syntax. Fire a webhook every 5 minutes, every hour, every Sunday at midnight, or any arbitrary schedule. Purple Flea uses UTC for all cron evaluation. Example: */5 * * * * — every 5 minutes.

▲

2. Price Triggers

Fire when an asset price crosses a threshold. Set ETH > $4000 or BTC < $60000. Purple Flea monitors price feeds via its own oracle API and delivers the webhook within one second of the threshold crossing.

▶

3. Transaction Webhooks

Fire when your agent's wallet receives or sends a specific token. Register on_receive(USDC, wallet_address) to be notified the moment a payment arrives. Useful for escrow flows, payment confirmations, and deposit detection.

▼

4. Time-to-Expiry Alerts

Fire N hours before an option, loan, or subscription expires. Register expiry_alert(position_id, hours_before=1) to give your agent time to roll, close, or extend a position before forced liquidation or expiry.

Cron Reference

Common Cron Schedules for Agent Tasks

Cron expressions follow the standard five-field format: minute, hour, day-of-month, month, day-of-week. All times are UTC.

* * * * * Every minute — for high-frequency price checks or position monitors
*/5 * * * * Every 5 minutes — for near-real-time portfolio checks without per-minute overhead
*/30 * * * * Every 30 minutes — for funding rate checks on perpetual futures positions
0 * * * * Every hour — for portfolio rebalancing and yield position checks
0 */6 * * * Every 6 hours — for less frequent rebalancing with lower gas costs
0 0 * * * Daily at midnight UTC — for daily P&L reporting, daily yield compounding
0 0 * * 0 Weekly on Sunday midnight — for weekly yield auto-compounding
0 9 * * 1-5 Weekdays at 09:00 UTC — for strategies aligned to traditional market open

Code Examples

Register Jobs, Handle Webhooks

1. Register a recurring cron job — daily yield compounding
import PurpleFlea from '@purpleflea/sdk';

const pf = new PurpleFlea({ apiKey: process.env.PURPLE_FLEA_API_KEY });

// Register a daily compounding job — fires every day at 00:00 UTC
const job = await pf.scheduler.createCron({
  name: 'daily-yield-compound',
  schedule: '0 0 * * *',
  url: 'https://my-agent.example.com/jobs/compound',
  payload: {
    action: 'compound_all_positions',
    agent_wallet: '0xYourAgentWallet'
  },
  timezone: 'UTC',
  enabled: true
});

console.log(`Job registered: ${job.id}, next fire: ${job.next_fire_at}`);
2. Register a price trigger — fire when ETH crosses $4,000
// Fire a webhook when ETH/USD rises above $4000
const priceTrigger = await pf.scheduler.createPriceTrigger({
  asset: 'ETH',
  currency: 'USD',
  condition: 'above',   // 'above' | 'below' | 'crosses'
  threshold: 4000,
  url: 'https://my-agent.example.com/jobs/eth-breakout',
  payload: { signal: 'eth_breakout_4k' },
  fire_once: true   // auto-delete after first fire
});

// Register a downside alert too
await pf.scheduler.createPriceTrigger({
  asset: 'ETH',
  currency: 'USD',
  condition: 'below',
  threshold: 2500,
  url: 'https://my-agent.example.com/jobs/eth-support-break',
  payload: { signal: 'eth_support_break' },
  fire_once: false   // keep firing if it stays below
});
3. Handle the webhook callback
// Express.js handler — receives all scheduler callbacks
app.post('/jobs/:action', async (req, res) => {
  const { action } = req.params;
  const { payload, fired_at, job_id } = req.body;

  // Always verify the Purple Flea signature
  if (!pf.scheduler.verifySignature(req)) {
    return res.status(401).json({ error: 'invalid signature' });
  }

  switch (action) {
    case 'compound':
      await compoundAllYieldPositions(payload.agent_wallet);
      break;
    case 'eth-breakout':
      await openLongPosition({ asset: 'ETH-PERP', size_usd: 5000 });
      break;
    case 'eth-support-break':
      await closeAllEthPositions();
      break;
  }

  res.json({ received: true, job_id });
});

Example Use Cases

What AI Agents Schedule in Production

Job Name Schedule / Trigger What the Agent Does
yield-compound 0 0 * * 0 Claim and reinvest all pending yield rewards from Aave, Convex, and Yearn positions
portfolio-rebalance 0 * * * * Check portfolio drift vs target allocation; rebalance if any asset drifts more than 5%
price-check */30 * * * * Fetch prices for all open positions; update internal stop-loss calculations
daily-pnl-report 0 23 * * * Compute daily realised and unrealised P&L; post summary to Telegram
usdc-receive-alert on_receive(USDC) Immediately deploy any incoming USDC to best available yield protocol
eth-above-4000 ETH > $4,000 Open long ETH-PERP position and set take-profit at $4,800
loan-expiry-alert expiry_alert(loan_id, 2h) Repay or extend Aave loan 2 hours before health factor hits liquidation threshold
gas-window-deploy gas < 10 gwei Execute batched token approvals and vault deposits when Ethereum gas is cheap

Persistence

Jobs Survive Agent Restarts

The most common failure mode for home-built agent schedulers is job loss on restart. A Node.js agent using setTimeout or a Python agent using schedule loses all registered jobs the moment the process exits — whether from a crash, a deployment, or an intentional restart. In a production environment with multiple agents, multiple deployments per day, and cloud infrastructure that may restart processes at any time, in-memory scheduling is not viable.

Purple Flea stores all registered jobs in a persistent durable queue. When a cron job fires, Purple Flea makes up to five delivery attempts with exponential back-off if your endpoint does not respond with a 2xx status code. If all five attempts fail, the job is marked as failed and you are notified via email and the API, but the job continues to be scheduled for its next fire time — a single delivery failure does not cancel the recurring schedule.

Jobs are tied to your API key, not to any specific server or agent instance. You can register a job from your laptop, shut the laptop down, and the job will fire correctly to your registered webhook URL on schedule. This makes the scheduler the natural complement to any serverless agent deployment — register the job once at agent startup, then let the serverless function sleep until Purple Flea calls it.

◆

Durable Storage

All jobs are persisted in Purple Flea's database. Process restarts, redeployments, and crashes do not affect scheduled jobs.

◆

Delivery Guarantees

Up to 5 delivery attempts per fire event with exponential back-off. Failed deliveries are logged and retrievable via the API.

◆

Webhook Signing

Every webhook delivery is HMAC-signed with your API key. Your agent can verify authenticity before processing any job payload.

Build Agents That Never Miss a Beat

Register your first cron job in minutes. Purple Flea's scheduler keeps your agent's tasks running reliably across restarts, deployments, and infrastructure events.

Get API Key Webhook API Docs