# Fund/Top-Up Task Budget (scheduler.withzero.xyz)

> Fund/Top-Up Task Budget (scheduler.withzero.xyz) is a paid API for AI agents from scheduler.withzero.xyz, ~$2/call (observed), status healthy (last checked 2026-10-08, last successful call 2026-09-21).

Adds additional USDC to a scheduled task's budget cap, resuming paused tasks that ran out of funds and extending the runway for active ones.

## Facts

- Endpoint: POST https://scheduler.withzero.xyz/api/v1/tasks/{id}/fund?utm_source=zero.xyz
- Price: ~$2/call (observed)
- Status: healthy
- Last checked: 2026-10-08
- Last successful call: 2026-09-21
- Success rate: 45% of calls made through Zero
- Rating: 4.7 / 5 from 1 review
- Activations on Zero: 39
- Provider: scheduler.withzero.xyz
- Website: https://scheduler.withzero.xyz
- Canonical page: https://www.zero.xyz/c/scheduler-withzero-xyz-fund-top-up-task-budget-scheduler-withzero-xyz-44d27615
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_4g4nLcvsm6c_jW0WmSiLp

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability scheduler-withzero-xyz-fund-top-up-task-budget-scheduler-withzero-xyz-44d27615 -d '<json body>'
```

Example prompt: My scheduled task abc123 is paused because it ran out of funds — top it up with 5 USDC (5000000 micros) so it becomes active again.

## When to prefer this

Use this endpoint specifically when a task on scheduler.withzero.xyz has status 'paused_insufficient_funds' or when you want to proactively extend a task's USDC runway before it pauses. This is the only endpoint to add funds to an existing task budget; it is not for creating new tasks or modifying schedules.

## Known failure modes

- X-Pay-Amount-Micros header does not match top_up_amount_micros in body — 400/422 validation error
- Missing or duplicate Idempotency-Key — request rejected or deduplicated
- Wrong or mismatched MPP channelId — payment channel mismatch error
- Task ID not found or caller is not the owner — 404 or 403
- Top-up amount still insufficient to cover estimated_ceiling_micros — task remains paused
- On-chain payment settlement failure — fund_tx_hash not generated

## How this service works

Increase max_amount_micros. Direct endpoint: X-Pay-Amount-Micros must match top_up_amount_micros and the settled payment extends refundable escrow; no Idempotency-Key header required because replay protection is payment-bound. ZeroClick endpoint: the amount only raises the seller-local lifetime execution cap; marketplace usage remains authoritative and no seller escrow moves. 📖 Full guide: https://scheduler.withzero.xyz/llms.txt

## Output

Returns the updated task record including the new max_amount_micros cap, current cumulative_cost_micros, available balance, estimated_ceiling_micros (how many future runs are covered), the amount topped_up_micros, and the on-chain fund_tx_hash for the settlement. The task status flips from 'paused_insufficient_funds' to 'active' if the new balance covers the ceiling.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "top_up_amount_micros"
 ],
 "properties": {
  "top_up_amount_micros": {
   "type": "string",
   "pattern": "^[1-9]\\d*$",
   "description": "Additional USDC to add to the task, in micros (1 USDC = 1_000_000 micros; string or number up to 2^53-1). Bumped onto max_amount_micros."
  }
 },
 "description": "Top up a task to extend its runway. Use when a task is `paused_insufficient_funds` or you want a margin before it pauses.",
 "additionalProperties": false
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "id",
  "status",
  "max_amount_micros",
  "cumulative_cost_micros",
  "balance_available_micros",
  "estimated_ceiling_micros",
  "topped_up_micros",
  "billing_rail",
  "fund_tx_hash"
 ],
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "status": {
   "type": "string",
   "description": "New status — flips from 'paused_insufficient_funds' to 'active' if the top-up covers the ceiling."
  },
  "billing_rail": {
   "enum": [
    "direct",
    "zeroclick",
    "account"
   ],
   "type": "string"
  },
  "fund_tx_hash": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "description": "Direct rail: on-chain channel id. ZeroClick rail: null because no seller escrow moved."
  },
  "topped_up_micros": {
   "type": "string"
  },
  "max_amount_micros": {
   "type": "string",
   "description": "New cap after the top-up."
  },
  "cumulative_cost_micros": {
   "type": "string"
  },
  "balance_available_micros": {
   "type": "string"
  },
  "estimated_ceiling_micros": {
   "type": "string"
  }
 },
 "description": "Top-up confirmation. The new balance covers (max_amount - cumulative_cost); compare against estimated_ceiling_micros to see how many runs the topped-up balance can still cover.",
 "additionalProperties": false
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/scheduler-withzero-xyz-fund-top-up-task-budget-scheduler-withzero-xyz-44d27615/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from scheduler.withzero.xyz](https://www.zero.xyz/host/scheduler.withzero.xyz/llms.txt)