# WithZero Scheduler Task Fund (Top-Up)

> WithZero Scheduler Task Fund (Top-Up) is a paid API for AI agents from agents.withzero.xyz, paid per call via MPP, $1/call, status unknown (last checked 2026-09-11).

Increases the maximum USDC budget for an existing scheduled task by adding funds to its escrow or raising its execution cap.

## Facts

- Endpoint: POST https://agents.withzero.xyz/api/v1/scheduler/tasks/{id}/fund
- Price: $1/call
- Payment: MPP
- Status: unknown
- Last checked: 2026-09-11
- Activations on Zero: 0
- Provider: agents.withzero.xyz
- Website: https://agents.withzero.xyz
- Canonical page: https://www.zero.xyz/c/agents-withzero-xyz-withzero-scheduler-task-fund-top-up-d566bcd1
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_b5FgKrF4w8j0cFPBSLt8b

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 agents-withzero-xyz-withzero-scheduler-task-fund-top-up-d566bcd1 -d '<json body>'
```

Example prompt: My scheduled task abc123 is paused because it ran out of funds — can you top it up with 5 USDC so it can keep running?

## When to prefer this

Use this endpoint when an existing WithZero scheduled task has paused due to insufficient funds (status: paused_insufficient_funds) or when you want to proactively add USDC runway before the task's balance is exhausted. This is the only endpoint for increasing a task's budget cap after creation — use the task-create endpoint if starting fresh. On the direct rail, funds move into on-chain refundable escrow; on the zeroclick rail, only the local execution cap is raised.

## Known failure modes

- 400 PRICE_RESOLVER_FAILED — X-Pay-Amount-Micros header missing, non-integer, or does not exactly match top_up_amount_micros body field
- 404 — task ID not found or caller does not own the task
- 402 — payment challenge not settled; funds not transferred
- 422 — top_up_amount_micros is zero or negative (pattern requires non-zero positive integer string)
- 503 — upstream payment rail or escrow service temporarily unavailable

## 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 object including: new max_amount_micros (raised cap), current status (may flip from paused_insufficient_funds to active), balance_available_micros, topped_up_micros, estimated_ceiling_micros (projected runs remaining), billing_rail (direct or zeroclick), and fund_tx_hash (on-chain channel ID for direct rail, null for zeroclick).

## 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"
   ],
   "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/agents-withzero-xyz-withzero-scheduler-task-fund-top-up-d566bcd1/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from agents.withzero.xyz](https://www.zero.xyz/host/agents.withzero.xyz/llms.txt)