SDK — @cron/sdk

TypeScript SDK for interacting with Cron Protocol from any environment.

Install

bash
npm install @cron/sdk

CronClient

CronClient is the main entry point. It exposes managers for plans, subscriptions, charges, and events.

typescript
import { CronClient } from "@cron/sdk";

const cron = new CronClient({
  chain: "base",          // "base" | "baseSepolia" | "arbitrum" | "arbitrumSepolia"
  walletClient,           // viem WalletClient (for write operations)
  publicClient,           // optional — created automatically if omitted
  rpcUrl,                 // optional — overrides default public RPC
});

PlanManager

Accessed via cron.plans.

create()

typescript
const { planId, txHash } = await cron.plans.create({
  token: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  amount: parseUnits("9.99", 6),
  interval: 2592000,          // 30 days
  gracePeriod: 259200,        // 3 days
  agentCompatible: false,     // allow AI agents to subscribe
  metadata: {
    name: "Pro Plan",
    description: "Full access",
    features: ["unlimited", "priority support"],
  },
});

get()

typescript
const plan = await cron.plans.get(planId);
// plan.merchant, plan.token, plan.amount, plan.interval, plan.active, ...

pause() / unpause()

typescript
await cron.plans.pause(planId);
await cron.plans.unpause(planId);

search()

Find plans by criteria — useful for AI agents discovering APIs to subscribe to.

typescript
const plans = await cron.plans.search({
  serviceType: "api_access",
  maxAmount: parseUnits("50", 6),
  agentCompatible: true,
});

SubscriptionManager

Accessed via cron.subscriptions.

subscribe()

typescript
const { subscriptionId, txHash } = await cron.subscriptions.subscribe({
  planId,
  mintNFT: true,  // optional — mint CronNFT identity token
});

getStatus()

typescript
const status = await cron.subscriptions.getStatus({ planId, subscriber });
// "Active" | "PastDue" | "Cancelled" | "Expired"

cancel()

typescript
await cron.subscriptions.cancel(planId);

list()

typescript
// All subscriptions for an address
const subs = await cron.subscriptions.list({ subscriber: address });

// All subscribers for a plan
const subs = await cron.subscriptions.list({ planId });

ChargeManager

Accessed via cron.charges. Used by keepers.

typescript
// Check if a subscription is due for charge
const isDue = await cron.charges.isDue({ planId, subscriber });

// Execute a single charge (keeper earns 0.5% bounty)
await cron.charges.charge({ planId, subscriber });

// Batch charge multiple subscriptions
await cron.charges.batchCharge([
  { planId: 1n, subscriber: "0x..." },
  { planId: 2n, subscriber: "0x..." },
]);

EventListener

Subscribe to real-time on-chain events.

typescript
const listener = cron.events.listen();

listener.on("SubscriptionCreated", (event) => {
  console.log("New subscriber:", event.subscriber);
});

listener.on("Charged", (event) => {
  console.log("Charge executed:", event.amount);
});

listener.on("SubscriptionCancelled", (event) => {
  revokeAccess(event.subscriber);
});

// Stop listening
listener.stop();

[i] Chain config

Chain configurations (RPC URLs, contract addresses) live in src/utils/chains.ts. Pass rpcUrl to override the default public endpoint.

ABIs

The SDK exports all contract ABIs for direct use with viem or wagmi:

typescript
import {
  CRON_REGISTRY_ABI,
  CRON_NFT_ABI,
  PAYMENT_ROUTER_ABI,
  AGENT_BUDGET_MANAGER_ABI,
  getChainById,
} from "@cron/sdk";

MPP Transport

The SDK includes an optional MPP transport for accessing paid Cron APIs via micropayments. Install mppx as a peer dependency to enable it.

bash
npm install @cron/sdk mppx
typescript
import { MppTransport } from "@cron/sdk";
import { privateKeyToAccount } from "viem/accounts";

const mpp = new MppTransport({
  account: privateKeyToAccount("0x..."),
  maxSessionDeposit: "5",  // $5 cap per session
});

// Payment-aware fetch — handles 402 automatically
const plans = await mpp.getJSON("https://api.cronprotocol.xyz/api/plans");

// Stream SSE data from paid endpoints
for await (const chunk of mpp.streamSSE("https://api.cronprotocol.xyz/api/plans/stream")) {
  console.log(JSON.parse(chunk));
}

[i] Optional dependency

mppx is an optional peer dependency. The SDK works without it — MPP features are only activated when mppx is installed.