> For the complete documentation index, see [llms.txt](https://docs.talus.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talus.network/faq/04-payments.md). # Payments {% hint style="info" %} **Audience:** Nexus adopters and integrators. **Goal:** Answer funding, Tool cost, settlement, and refund questions so you can trace where execution money is held and released. {% endhint %} This page covers who pays for an execution, how the budget is held and released, and how tool payment differs from the gas that fuels transactions. The [concepts page](/faq/02-concepts.md) draws the agent-funded versus user-funded distinction; here is the mechanism. The payment model joins Task/Occurrence/Execution inspection with policy-backed `Invocation`, ToolCashier policy witnesses, and exact timeout/refund ordering. Use the selected build’s `--help`, `nexus task occurrence cost`, and `nexus execution inspect`, and verify that its bindings and configured package IDs match the target network before running a command. See the [Invocation policy and settlement model](/concepts/06-payment-vaults-reserves-and-settlement.md#invocation-policy-and-settlement-model) for the complete identity and custody rules. #### Payment models **What payment models does a skill support?** A skill's payment policy picks one of two models, chosen when the skill is defined: * **Address-funded (user-funded)** — the submitting signer supplies the prepayment coin for an address-controlled Task. The standard constructor records that signer as the immutable Task controller, stores the explicit `refund_recipient` as the `PaymentSourceKind::UserFunded` beneficiary and final address-funded reserve destination, and defaults that recipient to the signer when omitted. * **Agent-funded** — the agent funds the execution from its own payment vault, capped by a maximum budget the policy carries. The payment records the agent's id as its source and cannot exceed that budget. The signer/controller, UserFunded beneficiary, and policy `refund_to` address are separate roles. A caller or leader that later triggers work does not become the recorded funding source, and `refund_to` manages a refunded policy entitlement rather than the Task reserve. The [concepts page](/faq/02-concepts.md) frames when to pick each; the rest of this page describes how the chosen model's money is handled. **Where do agent-funded payments come from?** From the agent's **payment vault** — a SUI balance held as a child of the agent object. You top it up and inspect it through the CLI: ``` nexus tap vault balance --alias nexus tap vault deposit --alias --amount ``` Because custody of the agent object controls the vault, whoever holds the agent controls its funds. An agent-funded run draws down the vault up to the skill's budget; a user-funded run does not touch the vault at all. **Budget and settlement** **How is a budget held during an execution?** Each execution creates a custodied **execution payment** that holds the funds for that run. As the walk reaches each tool-call vertex, the protocol locks that vertex's cost against the payment: the payment tracks a maximum budget, a locked amount, and the amount actually consumed, plus a snapshot of each tool's cost and a per-vertex lock line. Locking a vertex reserves its cost so the run cannot overspend; if the total would exceed the budget, the lock is rejected rather than silently overrunning. **How is each step settled?** Each `ExecutionPaymentVertexLock` identifies a runtime vertex with `vertex_key`, `invocation_id`, and `amount`. The corresponding Invocation carries the Tool, cashier, beneficiary, policy, funding, and refund identity. Settlement consumes the matching `InvocationSettlementReceipt`, updates `ExecutionPayment`, emits its effects/events, and clears the payment lock. Inspect the Task/Occurrence/Execution payment state and transaction effects through the selected CLI/SDK: ``` nexus tap payments show --payment-id nexus task occurrence cost --task-id --occurrence-id ``` FixedPrice Invocations, including price zero, and FiniteCredits or TimePass entitlements all follow that exact Invocation path. A hosted projection may omit the receipt view, but the authoritative object and transaction effects still determine whether settlement charged or refunded; do not infer the outcome from a UI failure label. **What happens to unused budget?** Unused funds are not limited to failed runs. A successful run may use less than its budget while it is active, but payment finalization returns the unused ExecutionPayment balance through the recorded source path. For scheduled work, it returns first to `TaskPaymentReserve`; the reserve returns to its ultimate address or Agent-vault source only when the Task closes under its controller/Agent authority. A finalized `ExecutionPayment` does not retain unused funds. A zero-priced FixedPrice Invocation and a refunded policy entitlement remain auditable through the exact Invocation, payment lock, receipt, and transaction effects. **Gas versus budget** **What is the difference between the tool budget and Sui gas?** There are three distinct meters and custody paths: * **Immediate transaction SUI gas** — the signer or leader pays the transaction from owned coins or its SUI address balance. * **Payable leader gas reimbursement** — eligible leader commit and settlement gas is recorded with the committed result and settled from `ExecutionPayment` when the complete charge fits. * **Tool and priority charges** — the `ExecutionPaymentVertexLock` accounts for the amount held against one exact `invocation_id`, the Invocation and settlement/refund receipt provide policy-specific identity and outcome, and the priority reserve accounts for the separately payable priority path. Immediate gas is not the same as an execution budget, but eligible recorded Leader gas reimbursement is part of ExecutionPayment settlement. The payment model here explains which recorded charges can later become payable; public docs do not publish process funding instructions. Tool owners configure accepted policy families in `ToolCashier`, a caller selects one through `InvocationPolicyCall` in the SDK or `nexus execution authorize` in the CLI, and the exact Invocation carries its lock, settlement, refund, and entitlement identity. Verify that the selected binary’s help, generated bindings, configured package IDs, and transaction effects agree before relying on the surface. ToolCashier owner commands concern policy configuration and collection of completed Invocations or deposits, not per-execution lock reconciliation. **Which balance is insufficient?** * **Task/Occurrence inspection or dispatch effects prove reserve shortage, and no Execution exists:** run `nexus task refill --task-id --amount-mist `. For an Agent-controlled Task, the signer must control the recorded Agent and its vault must contain the amount. “No Execution” alone is not proof of shortage because permanent Task rejection also creates none. * **Execution is active, but that walk has no Invocation lock or committed result:** authorization failed because ExecutionPayment could not cover either the verified-Leader submission charge or snapshotted Tool amount. Refill with `nexus tap payments refill`; the refill transaction also requests every active walk whose payment is ready. If this walk still requires authorization, the selected active Leader holding the exact Leader capability retries `nexus execution authorize`; an ordinary wallet user refills and observes rather than acquiring that capability. The failed transaction leaves no persisted lock even when it formed one transiently before the atomic rollback. * **Walk is `PendingSettlement` with a committed result, Invocation lock, and insufficient-settlement marker:** refill the ExecutionPayment, then run `nexus tap execution settle --execution-id --walk-index `. A later Leader submission does not replace that retry. * **The Sui transaction itself lacks gas:** fund or select the submitter’s address/gas coin. Neither `nexus task refill` nor `nexus tap payments refill` pays immediate transaction gas. Both authorization balance failures use `EPaymentBudgetExceeded`; distinguish them by the failed transaction’s Move abort location and historical Execution amounts. Read the snapshotted Tool amount from `ExecutionPayment`/Invocation state, not the Tool price reported at inspection time. `payment::lock_invocation` identifies a Tool-price shortage, while `consume_payment_for_verified_leader_submission` identifies the verified-Leader reimbursement shortage. If the selected client does not expose that abort location or snapshot, stop and report the diagnostic gap. If authorization reports `ETransactionBudgetExceeded`, stop retrying and ask the network operator to compare the charge with the LeaderRegistry maximum; refill does not fix it. If FiniteCredits are exhausted, use or obtain valid credits or restore an eligible refunded credit. If a TimePass is inactive, use one whose immutable interval includes authorization time or choose another accepted policy. Follow a Custom policy’s own documented recovery because it has no universal refill action. **How do I refill settlement gas and move a pending walk forward?** If `ExecutionPayment` cannot cover an eligible Leader gas charge, the protocol retains the committed Tool result, records the settlement shortfall, and leaves the walk pending. A refill restores payment capacity and requests every payment-ready active walk, but it does not settle the retained result or advance this pending walk by itself. 1. Inspect the Execution, payment, walk index, committed result, and transaction effects. Refill that live Execution payment from any caller's coin, or use the matching Agent authority when the value should come from its vault: ``` nexus tap payments refill --execution-id --amount nexus tap payments refill --execution-id --amount --agent-id ``` 2. Retry the committed-result settlement. Because this walk is already recorded in the insufficient-payment marker, any caller may retry it permissionlessly as soon as the refill makes the charge affordable; it does not need to wait for the normal timeout: ``` nexus tap execution settle --execution-id --walk-index ``` 3. Re-read the Execution and payment. Confirm this walk index is no longer listed as payment-insufficient and its committed result cleared, then confirm the walk is finished or a new `RequestWalkExecutionEvent` was emitted for its next active vertex. Other underfunded walks may keep the execution-wide shortfall record present. The low-level Move settlement entry point settles the committed result and its exact Invocation. The selected public CLI command and high-level SDK/PTB settlement helper compose that entry point with `emit_payment_ready_walk_requests`; the refill helpers compose the same emission after their top-up. There is no separate public CLI or high-level SDK command that a user can run only to emit requests. A pending committed result without an insufficient-payment marker still needs its normal timeout or an eligible Leader settlement path before a permissionless caller can settle it. After settlement, re-read the Execution: no new request can be correct when no active walk is payment-ready, but a payment-ready active walk that remains unrequested is a missing transition to report to the network operator. Do not refill or settle again unless the durable state still satisfies that operation's preconditions. See [On-Chain Result Resolution](/concepts/11-onchain-result-resolution.md#pending-settlement-and-affordability), [`nexus tap` CLI reference](/reference/cli/tap.md#nexus-tap-payments-refill), and [Workflow Actions](/reference/sdk/actions-workflow.md#workflowactionssettle_committed_tool_result_for_walk). A pending committed result is not abortable. Abort applies only when at least one active walk is at or beyond twice its stored effective timeout, no committed result awaits settlement, and payment locks are cleared by exact Invocation refund. The SDK/CLI may atomically clean finalized invalid-stamp raw results during abort; a consumable or unfinalized result blocks it. If an Invocation remains locked, resolve the expired walk with its exact `invocation_id` first; after the Execution is terminal, settle the owning scheduler Occurrence separately and verify zero in-flight work before closing the Task. *** **Where do I go next?** * [Concepts](/faq/02-concepts.md) — the agent-funded versus user-funded distinction, framed by role. * [Authoring](/faq/03-authoring.md) — where a step's per-invocation cost is set on a tool. * [DAG and Execution](/concepts/05-workflow-dag-execution.md) — public leader-gas records and settlement state. * [Execute and settle an agent](/guides/agent-usage/execute-and-settle-agent.md) — the end-to-end payment walkthrough. * Reference — the [Invocation policy and settlement model](/concepts/06-payment-vaults-reserves-and-settlement.md#invocation-policy-and-settlement-model) for policy-backed locks, receipts, refunds, and ToolCashier collection, plus the [`tap`](/reference/cli/tap.md) and [`gas`](/reference/cli/gas.md) CLI pages for generated command flags. * [Glossary](/glossary/glossary.md) — budget, settlement, vault, and policy terms. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.talus.network/faq/04-payments.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.