{"uid":"cap_4g4nLcvsm6c_jW0WmSiLp","slug":"scheduler-withzero-xyz-fund-top-up-task-budget-scheduler-withzero-xyz-44d27615","name":"Fund/Top-Up Task Budget (scheduler.withzero.xyz)","description":"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","url":"https://scheduler.withzero.xyz/api/v1/tasks/{id}/fund?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"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},"responseSchema":{"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},"example":null,"exampleRequest":null,"tags":[],"displayCostAmount":"0","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","requiresHandshake":false,"reviewCount":1,"rating":{"score":"0.92","successRate":"0.45","reviews":1,"stars":"4.7","state":"rated"},"availabilityStatus":"healthy","priceObserved":{"p10Cents":"200.0000","medianCents":"200.0000","p90Cents":"200.0000","minCents":"200.0000","maxCents":"200.0000","p95Cents":"200.0000","sampleCount":1,"varies":false,"failureChargeRate":0},"sessionDeposit":null,"pricing":{"kind":"dynamic","summary":"~$2/call (observed)","primary":null,"accepted":[]},"paymentMethods":[],"brandName":"scheduler.withzero.xyz","brandSlug":"scheduler-withzero-xyz-mpp","brandBaseUrl":"https://scheduler.withzero.xyz","brandDocsUrl":null,"whatItDoes":"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.","exampleAgentPrompt":"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.","exampleUseCases":null,"resultDescription":"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.","failureModes":["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"],"whenToPreferThis":"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.","instructions":"# Fund Task — top up the deposit\n\n## Workflow\n- Size the top-up: GET /api/v1/tasks/{id} → balance_available_micros, estimated_ceiling_micros (fund the deficit to clear one run's ceiling)\n- Needed when a task auto-pauses (balance < one run's ceiling) — then resume: POST /api/v1/tasks/{id}/resume\n\n## Contract\n- Header X-Pay-Amount-Micros must equal body top_up_amount_micros. 1 USDC = 1,000,000 micros.\n- NO Idempotency-Key needed — idempotency is keyed off the 402 payment; resubmitting the same credential de-dupes.\n- Reuses the original task's MPP channelId.","reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":39,"lastUsedAt":"2026-09-21T05:11:28.606Z","lastSuccessfullyRanAt":"2026-09-21T05:11:28.606Z","lastHealthCheckAt":"2026-10-08T06:30:06.293Z","isFirstParty":true,"canonicalSlug":"scheduler-withzero-xyz-fund-top-up-task-budget-scheduler-withzero-xyz-44d27615"}