Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

💰Fund Agent* and User-Paid Executions

Audience: Agent developers and operators of application-owned funding.

Goal: Fund the correct execution source, resolve a payment shortfall, and prove settlement clears.

This guide covers the two supported execution funding paths. An Agent-funded Task draws from the selected Agent's AgentPaymentVault, whether that Agent is registry-created, embedded in an application, or part of a Talus Agent Package (TAP); a user-funded Task draws from the user or application-selected execution source. Keep TAP application business state separate from generic Agent payment custody, and choose the source that the skill contract accepts before scheduling.

Authorize an execution from the selected funding source
Phase 1: Authorize from live ExecutionPayment capacity. Keyed facts: TaskPaymentReserve creates ExecutionPayment; the exact invocation amount is checked on ExecutionPayment; EPaymentBudgetExceeded occurs before a new lock; funding repair and retry remain separate from retained-result settlement.
Settle a retained result after payment refill
Phase 2: Settle a retained result after payment refill.

1. Identify the funding source

Read the skill’s payment policy and record whether it is AgentFunded with a maximum budget or UserFunded. Do not schedule an Agent-funded Task with a user source. Initial funding follows the selected policy; a live user-funded ExecutionPayment may later accept a nonzero SUI coin from any caller without changing its recorded source or refund identity.

For Agent-funded work, retain custody of the selected Agent's AgentPaymentVault and confirm its available balance. For user-funded work, confirm the execution source belongs to the address or application that the Task will use. Transaction gas is separate from both sources.

2. Fund and schedule

Fund and schedule the selected funding source using the wallet-authorized public CLI or SDK flow available in the selected build. The hosted Nexus API is a read-only service and a provider-issued API key cannot sign these Sui mutations. The exact command or builder varies by client version; use the generated Task reference and CLI Task reference for the documented fields rather than copying an unverified command.

Create the Task with the matching skill, inputs, schedule, and funding policy. Read back the Task reserve and the first occurrence before dispatch. Record the Task ID, occurrence ID, source kind, and expected budget in your evidence.

3. Inspect execution payment

After scheduler admission creates the execution, inspect the matching TaskPaymentReserve and ExecutionPayment state. Confirm the execution points to the expected Task and source and record the reserved, committed, pending, and settled amounts that the selected reference exposes.

4. Resolve a shortfall

First identify the walk state. An authorization-time EPaymentBudgetExceeded leaves the active walk without a persisted Invocation lock or committed result. An insufficient-settlement marker leaves the walk PendingSettlement with its committed result and Invocation lock. Neither condition proves that the Tool failed, and the Task reserve is not proof of completed settlement.

  1. Read the Execution, walk, payment source, refund identity, available amount, Invocation lock, committed result, and insufficient-settlement marker.

  2. Add a nonzero SUI coin with nexus tap payments refill --execution-id <id> --amount <mist>; this top-up does not change the recorded source, controller, or refund recipient and also requests every active walk whose payment is ready. Add --agent-id <agent-id> only when the matching Agent vault should supply the value.

  3. If authorization rolled back with no persisted lock/result, the selected active Leader holding the exact Leader capability retries nexus execution authorize with the same walk, runtime vertex, and policy arguments.

  4. If the committed result and insufficient-settlement marker remain, run nexus tap execution settle --execution-id <id> --walk-index <index>; do not abort the pending result.

  5. Re-read the marker, ExecutionPayment, Invocation lock, committed result, and next walk/request state. Do not create a second Task to hide the first result.

5. Prove completion

Settlement is proven when the pending shortfall clears, the committed result is removed when the walk can advance, the walk reaches its next state or terminal state, and the reserve/accounting effects match the source. Preserve transaction effects and events for the Task, execution, payment, and settlement.

If the execution expires, follow On-Chain Result Resolution for the permissionless resolution or abort condition. Do not claim a refund from an HTTP failure alone.

Outcome

You have a Task whose funding source matches its skill policy and evidence showing either successful settlement or a specific pending condition that can be refilled and retried.

Next

For Tool-owner economics, continue to Configure Tool Invocation Rules and Collect Revenue.

Last updated