> 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/reference/move/nexus_interface/payment.md).
# nexus\_interface::payment
* [Struct `AgentVaultPaymentAuthorization`](#struct-agentvaultpaymentauthorization)
* [Struct `ExecutionPayment`](#struct-executionpayment)
* [Struct `ExecutionPaymentInnerV1`](#struct-executionpaymentinnerv1)
* [Struct `ExecutionPaymentVertexLock`](#struct-executionpaymentvertexlock)
* [Struct `InvocationRequest`](#struct-invocationrequest)
* [Struct `InvocationLockReceipt`](#struct-invocationlockreceipt)
* [Struct `InvocationSettlementReceipt`](#struct-invocationsettlementreceipt)
* [Struct `TaskPaymentReserve`](#struct-taskpaymentreserve)
* [Struct `TaskPaymentReserveInnerV1`](#struct-taskpaymentreserveinnerv1)
* [Struct `AgentSkillPaymentCreatedEvent`](#struct-agentskillpaymentcreatedevent)
* [Struct `TaskPaymentReserveRefilledEvent`](#struct-taskpaymentreserverefilledevent)
* [Struct `TaskExecutionPaymentCreatedEvent`](#struct-taskexecutionpaymentcreatedevent)
* [Struct `TaskPaymentReserveCanceledEvent`](#struct-taskpaymentreservecanceledevent)
* [Struct `TaskExecutionPaymentFinalizedEvent`](#struct-taskexecutionpaymentfinalizedevent)
* [Struct `GasPaymentConsumedEvent`](#struct-gaspaymentconsumedevent)
* [Struct `ExecutionPaymentFeesRecordedEvent`](#struct-executionpaymentfeesrecordedevent)
* [Struct `ExecutionPaymentToolCostSnapshottedEvent`](#struct-executionpaymenttoolcostsnapshottedevent)
* [Struct `ExecutionAccomplishedEvent`](#struct-executionaccomplishedevent)
* [Struct `ExecutionRefundedEvent`](#struct-executionrefundedevent)
* [Enum `PaymentSourceKind`](#enum-paymentsourcekind)
* [Enum `ExecutionPaymentFinalState`](#enum-executionpaymentfinalstate)
* [Enum `SkillPaymentPolicy`](#enum-skillpaymentpolicy)
* [Constants](#constants)
* [Function `new_task_execution_payment`](#function-new_task_execution_payment)
* [Function `snapshot_payment_tool_cost`](#function-snapshot_payment_tool_cost)
* [Function `consume_payment_for_verified_leader_submission`](#function-consume_payment_for_verified_leader_submission)
* [Function `consume_payment_for_verified_leader_submission_to_recipient`](#function-consume_payment_for_verified_leader_submission_to_recipient)
* [Function `consume_task_payment_reserve_for_sender`](#function-consume_task_payment_reserve_for_sender)
* [Function `refill_execution_payment_from_coin`](#function-refill_execution_payment_from_coin)
* [Function `new_invocation_request`](#function-new_invocation_request)
* [Function `lock_invocation`](#function-lock_invocation)
* [Function `invocation_request_execution_id`](#function-invocation_request_execution_id)
* [Function `invocation_request_vertex_key`](#function-invocation_request_vertex_key)
* [Function `invocation_request_tool_id`](#function-invocation_request_tool_id)
* [Function `invocation_request_tool_fqn`](#function-invocation_request_tool_fqn)
* [Function `invocation_request_cashier_id`](#function-invocation_request_cashier_id)
* [Function `invocation_request_payment_id`](#function-invocation_request_payment_id)
* [Function `invocation_request_source`](#function-invocation_request_source)
* [Function `invocation_request_price_snapshot`](#function-invocation_request_price_snapshot)
* [Function `invocation_request_authorized_at_ms`](#function-invocation_request_authorized_at_ms)
* [Function `into_invocation_request`](#function-into_invocation_request)
* [Function `into_invocation_lock_receipt`](#function-into_invocation_lock_receipt)
* [Function `settle_invocation`](#function-settle_invocation)
* [Function `into_invocation_settlement_receipt`](#function-into_invocation_settlement_receipt)
* [Function `payment_leader_gas_consumed`](#function-payment_leader_gas_consumed)
* [Function `priority_charge_for`](#function-priority_charge_for)
* [Function `settlement_priority_delta_for_leader_gas`](#function-settlement_priority_delta_for_leader_gas)
* [Function `settlement_charge_required`](#function-settlement_charge_required)
* [Function `payment_available_settlement_funds`](#function-payment_available_settlement_funds)
* [Function `payment_available_settlement_charge`](#function-payment_available_settlement_charge)
* [Function `settlement_charge_missing`](#function-settlement_charge_missing)
* [Function `consume_priority_fee_for_settlement`](#function-consume_priority_fee_for_settlement)
* [Function `invocation_locked`](#function-invocation_locked)
* [Function `locked_invocation_id`](#function-locked_invocation_id)
* [Function `accomplish_invoker_payment`](#function-accomplish_invoker_payment)
* [Function `refund_invoker_payment`](#function-refund_invoker_payment)
* [Function `payment_source_kind_user_funded`](#function-payment_source_kind_user_funded)
* [Function `payment_source_kind_agent_funded`](#function-payment_source_kind_agent_funded)
* [Function `payment_source_kind_is_user_funded`](#function-payment_source_kind_is_user_funded)
* [Function `payment_source_kind_is_agent_funded`](#function-payment_source_kind_is_agent_funded)
* [Function `payment_source_kind_user`](#function-payment_source_kind_user)
* [Function `payment_source_kind_agent_id`](#function-payment_source_kind_agent_id)
* [Function `payment_final_state_pending`](#function-payment_final_state_pending)
* [Function `payment_final_state_accomplished`](#function-payment_final_state_accomplished)
* [Function `payment_final_state_refunded`](#function-payment_final_state_refunded)
* [Function `payment_policy_user_funded`](#function-payment_policy_user_funded)
* [Function `payment_policy_agent_funded`](#function-payment_policy_agent_funded)
* [Function `payment_policy_is_agent_funded`](#function-payment_policy_is_agent_funded)
* [Function `payment_policy_max_budget_mist`](#function-payment_policy_max_budget_mist)
* [Function `assert_payment_policy`](#function-assert_payment_policy)
* [Function `payment_agent_id`](#function-payment_agent_id)
* [Function `payment_skill_id`](#function-payment_skill_id)
* [Function `payment_interface_revision`](#function-payment_interface_revision)
* [Function `payment_execution_id`](#function-payment_execution_id)
* [Function `payment_consumed`](#function-payment_consumed)
* [Function `payment_funds`](#function-payment_funds)
* [Function `payment_source_kind`](#function-payment_source_kind)
* [Function `payment_locked_budget_mist`](#function-payment_locked_budget_mist)
* [Function `payment_final_state`](#function-payment_final_state)
* [Function `payment_max_budget_mist`](#function-payment_max_budget_mist)
* [Function `payment_gas_budget_mist`](#function-payment_gas_budget_mist)
* [Function `payment_priority_fee_reserve_mist`](#function-payment_priority_fee_reserve_mist)
* [Function `payment_priority_fee_percentage`](#function-payment_priority_fee_percentage)
* [Function `payment_priority_fee_charged`](#function-payment_priority_fee_charged)
* [Function `payment_accomplished`](#function-payment_accomplished)
* [Function `payment_refunded`](#function-payment_refunded)
* [Function `payment_locks`](#function-payment_locks)
* [Function `payment_available_funds`](#function-payment_available_funds)
* [Function `can_lock_payment_vertex_with_amount`](#function-can_lock_payment_vertex_with_amount)
* [Function `has_payment_tool_cost_snapshot`](#function-has_payment_tool_cost_snapshot)
* [Function `payment_tool_cost`](#function-payment_tool_cost)
* [Function `task_payment_reserve_task_id`](#function-task_payment_reserve_task_id)
* [Function `task_payment_reserve_agent_id`](#function-task_payment_reserve_agent_id)
* [Function `task_payment_reserve_skill_id`](#function-task_payment_reserve_skill_id)
* [Function `task_payment_reserve_interface_version`](#function-task_payment_reserve_interface_version)
* [Function `task_payment_reserve_authorization_id`](#function-task_payment_reserve_authorization_id)
* [Function `task_payment_reserve_occurrence_budget_mist`](#function-task_payment_reserve_occurrence_budget_mist)
* [Function `task_payment_reserve_remaining_funds`](#function-task_payment_reserve_remaining_funds)
* [Function `task_payment_reserve_source_kind`](#function-task_payment_reserve_source_kind)
* [Function `task_payment_reserve_payment_policy`](#function-task_payment_reserve_payment_policy)
* [Function `refill_task_payment_reserve_address_funded`](#function-refill_task_payment_reserve_address_funded)
* [Function `cancel_task_payment_reserve_address_funded`](#function-cancel_task_payment_reserve_address_funded)
* [Function `accomplish_task_execution_payment`](#function-accomplish_task_execution_payment)
* [Function `refund_task_execution_payment`](#function-refund_task_execution_payment)
* [Function `priority_fee_percentage`](#function-priority_fee_percentage)
* [Function `priority_fee_mist_for_gas_budget`](#function-priority_fee_mist_for_gas_budget)
* [Function `budget_split_mist`](#function-budget_split_mist)
* [Function `gas_budget_mist_for_max_budget_mist`](#function-gas_budget_mist_for_max_budget_mist)
* [Function `destroy_empty_task_payment_reserve`](#function-destroy_empty_task_payment_reserve)
### Struct `AgentVaultPaymentAuthorization`
Capability proving an agent vault is authorized to settle a payment for a given agent.
```move
public struct AgentVaultPaymentAuthorization has copy, drop
```
Fields
`agent_id: sui::object::ID`
#### Struct `ExecutionPayment`
Custodied payment for one standard agent execution.
```move
public struct ExecutionPayment has key, store
```
Fields
`id: sui::object::UID`
#### Struct `ExecutionPaymentInnerV1`
Version one stored layout for \[[`ExecutionPayment`](#nexus_interface_payment_ExecutionPayment)].
The stable \[[`ExecutionPayment`](#nexus_interface_payment_ExecutionPayment)] cannot contain these fields because its published layout must remain unchanged while stored data evolves.
```move
public struct ExecutionPaymentInnerV1 has store
```
Fields
`execution_id: addressagent_id: sui::object::IDskill_id: u64interface_revision:` [`nexus_interface::version::InterfaceVersion`](/reference/move/nexus_interface/version.md#nexus_interface_version_InterfaceVersion)`payment_policy:` [`nexus_interface::payment::SkillPaymentPolicy`](#nexus_interface_payment_SkillPaymentPolicy)`source_kind:` [`nexus_interface::payment::PaymentSourceKind`](#nexus_interface_payment_PaymentSourceKind)`max_budget_mist: u64gas_budget_mist: u64priority_fee_reserve_mist: u64locked_budget_mist: u64funds: sui::balance::Balanceconsumed: u64tool_fee_charged: u64priority_fee_charged: u64`[`priority_fee_percentage`](#nexus_interface_payment_priority_fee_percentage)`: u64accomplished: boolrefunded: boolfinal_state:` [`nexus_interface::payment::ExecutionPaymentFinalState`](#nexus_interface_payment_ExecutionPaymentFinalState)`tool_cost_snapshot: sui::vec_map::VecMap, u64>locked_vertices: vector<`[`nexus_interface::payment::ExecutionPaymentVertexLock`](#nexus_interface_payment_ExecutionPaymentVertexLock)`>`
#### Struct `ExecutionPaymentVertexLock`
Locked payment line for a runtime vertex.
```move
public struct ExecutionPaymentVertexLock has copy, drop, store
```
Fields
`vertex_key: vectorinvocation_id: sui::object::IDamount: u64`
#### Struct `InvocationRequest`
Canonical workflow and payment data offered to one economic policy.
```move
public struct InvocationRequest
```
Fields
`execution_id: addressvertex_key: vectortool_id: sui::object::IDtool_fqn: vectorcashier_id: sui::object::IDpayment_id: sui::object::IDsource:` [`nexus_interface::payment::PaymentSourceKind`](#nexus_interface_payment_PaymentSourceKind)`price_snapshot: u64authorized_at_ms: u64`
#### Struct `InvocationLockReceipt`
Linear authority to place one exact Invocation under its execution.
```move
public struct InvocationLockReceipt
```
Fields
`vertex_key: vectorinvocation_id: sui::object::IDamount: u64`
#### Struct `InvocationSettlementReceipt`
Linear authority to resolve one exact Invocation once.
```move
public struct InvocationSettlementReceipt
```
Fields
`invocation_id: sui::object::IDwas_refunded: bool`
#### Struct `TaskPaymentReserve`
Durable payment custody stored under a scheduler Task.
Occurrence correlation belongs to the owning Task. The reserve records only the identity and policy needed to create and settle execution payments.
```move
public struct TaskPaymentReserve has key, store
```
Fields
`id: sui::object::UID`
#### Struct `TaskPaymentReserveInnerV1`
Version one stored layout for \[[`TaskPaymentReserve`](#nexus_interface_payment_TaskPaymentReserve)].
The stable \[[`TaskPaymentReserve`](#nexus_interface_payment_TaskPaymentReserve)] cannot contain these fields because its published layout must remain unchanged while stored data evolves.
```move
public struct TaskPaymentReserveInnerV1 has store
```
Fields
`task_id: sui::object::IDagent_id: sui::object::IDskill_id: u64interface_version:` [`nexus_interface::version::InterfaceVersion`](/reference/move/nexus_interface/version.md#nexus_interface_version_InterfaceVersion)`authorization_id: sui::object::IDsource:` [`nexus_interface::payment::PaymentSourceKind`](#nexus_interface_payment_PaymentSourceKind)`refund_recipient: std::option::Option`Address that receives unused funds from an address-funded Task payment reserve. Agent-vault-funded reserves retain no address refund recipient.`occurrence_budget_mist: u64remaining_funds: sui::balance::Balancepayment_policy:` [`nexus_interface::payment::SkillPaymentPolicy`](#nexus_interface_payment_SkillPaymentPolicy)
#### Struct `AgentSkillPaymentCreatedEvent`
Emitted when a new execution payment is created and its budget is locked.
```move
public struct AgentSkillPaymentCreatedEvent has copy, drop
```
Fields
`payment_id: addressexecution_id: addressagent_id: sui::object::IDskill_id: u64interface_revision:` [`nexus_interface::version::InterfaceVersion`](/reference/move/nexus_interface/version.md#nexus_interface_version_InterfaceVersion)`payment_policy:` [`nexus_interface::payment::SkillPaymentPolicy`](#nexus_interface_payment_SkillPaymentPolicy)`source_kind:` [`nexus_interface::payment::PaymentSourceKind`](#nexus_interface_payment_PaymentSourceKind)`max_budget_mist: u64gas_budget_mist: u64priority_fee_reserve_mist: u64locked_budget_mist: u64`[`priority_fee_percentage`](#nexus_interface_payment_priority_fee_percentage)`: u64`
#### Struct `TaskPaymentReserveRefilledEvent`
Emitted when a \[[`TaskPaymentReserve`](#nexus_interface_payment_TaskPaymentReserve)] receives more funds.
```move
public struct TaskPaymentReserveRefilledEvent has copy, drop
```
Fields
`task_id: sui::object::IDreserve_id: addressagent_id: sui::object::IDskill_id: u64interface_version:` [`nexus_interface::version::InterfaceVersion`](/reference/move/nexus_interface/version.md#nexus_interface_version_InterfaceVersion)`source_kind:` [`nexus_interface::payment::PaymentSourceKind`](#nexus_interface_payment_PaymentSourceKind)`refill_amount: u64occurrence_budget_mist: u64remaining_funds: u64`
#### Struct `TaskExecutionPaymentCreatedEvent`
Emitted when a reserve creates the payment for one Task occurrence.
```move
public struct TaskExecutionPaymentCreatedEvent has copy, drop
```
Fields
`task_id: sui::object::IDreserve_id: addressoccurrence_id: u64execution_id: addresspayment_id: addressagent_id: sui::object::IDskill_id: u64interface_version:` [`nexus_interface::version::InterfaceVersion`](/reference/move/nexus_interface/version.md#nexus_interface_version_InterfaceVersion)`source_kind:` [`nexus_interface::payment::PaymentSourceKind`](#nexus_interface_payment_PaymentSourceKind)`budget: u64remaining_funds: u64`
#### Struct `TaskPaymentReserveCanceledEvent`
Emitted when a \[[`TaskPaymentReserve`](#nexus_interface_payment_TaskPaymentReserve)] returns all remaining funds.
```move
public struct TaskPaymentReserveCanceledEvent has copy, drop
```
Fields
`task_id: sui::object::IDreserve_id: addressagent_id: sui::object::IDskill_id: u64interface_version:` [`nexus_interface::version::InterfaceVersion`](/reference/move/nexus_interface/version.md#nexus_interface_version_InterfaceVersion)`source_kind:` [`nexus_interface::payment::PaymentSourceKind`](#nexus_interface_payment_PaymentSourceKind)`refunded_amount: u64remaining_funds: u64`
#### Struct `TaskExecutionPaymentFinalizedEvent`
Emitted when the payment for one Task occurrence reaches a final state.
```move
public struct TaskExecutionPaymentFinalizedEvent has copy, drop
```
Fields
`task_id: sui::object::IDreserve_id: addressoccurrence_id: u64execution_id: addresspayment_id: addressagent_id: sui::object::IDskill_id: u64interface_version:` [`nexus_interface::version::InterfaceVersion`](/reference/move/nexus_interface/version.md#nexus_interface_version_InterfaceVersion)`final_state:` [`nexus_interface::payment::ExecutionPaymentFinalState`](#nexus_interface_payment_ExecutionPaymentFinalState)`remaining_funds: u64`
#### Struct `GasPaymentConsumedEvent`
Emitted when gas is consumed from an execution payment.
```move
public struct GasPaymentConsumedEvent has copy, drop
```
Fields
`payment_id: addressexecution_id: addressagent_id: sui::object::IDskill_id: u64interface_revision:` [`nexus_interface::version::InterfaceVersion`](/reference/move/nexus_interface/version.md#nexus_interface_version_InterfaceVersion)`amount: u64consumed_total: u64`
#### Struct `ExecutionPaymentFeesRecordedEvent`
Emitted when payment fee totals are updated after gas, tool, or priority settlement.
```move
public struct ExecutionPaymentFeesRecordedEvent has copy, drop
```
Fields
`payment_id: addressexecution_id: addressagent_id: sui::object::IDskill_id: u64gas_fee_mist: u64tool_fee_mist: u64priority_fee_mist: u64`[`priority_fee_percentage`](#nexus_interface_payment_priority_fee_percentage)`: u64`
#### Struct `ExecutionPaymentToolCostSnapshottedEvent`
Emitted when a tool's cost is snapshotted onto an execution payment.
```move
public struct ExecutionPaymentToolCostSnapshottedEvent has copy, drop
```
Fields
`payment_id: addressexecution_id: addressagent_id: sui::object::IDtool_fqn: vectorcost: u64`
#### Struct `ExecutionAccomplishedEvent`
Emitted when an execution payment is accomplished.
```move
public struct ExecutionAccomplishedEvent has copy, drop
```
Fields
`execution_id: addresspayment_id: addressagent_id: sui::object::IDskill_id: u64interface_revision:` [`nexus_interface::version::InterfaceVersion`](/reference/move/nexus_interface/version.md#nexus_interface_version_InterfaceVersion)
#### Struct `ExecutionRefundedEvent`
Emitted when an execution payment is refunded, carrying the refund reason.
```move
public struct ExecutionRefundedEvent has copy, drop
```
Fields
`execution_id: addresspayment_id: addressagent_id: sui::object::IDskill_id: u64interface_revision:` [`nexus_interface::version::InterfaceVersion`](/reference/move/nexus_interface/version.md#nexus_interface_version_InterfaceVersion)`refund_reason: vector`
#### Enum `PaymentSourceKind`
Concrete payment source recorded on execution payments and scheduled reserves.
```move
public enum PaymentSourceKind has copy, drop, store
```
Variants
Variant `UserFundeduser: address`Variant `AgentFundedagent_id: sui::object::ID`
#### Enum `ExecutionPaymentFinalState`
Final lifecycle state for an execution payment.
```move
public enum ExecutionPaymentFinalState has copy, drop, store
```
Variants
Variant `Pending`Variant `Accomplished`Variant `Refunded`
#### Enum `SkillPaymentPolicy`
Payment limits and source mode required by a skill.
```move
public enum SkillPaymentPolicy has copy, drop, store
```
Variants
Variant `UserFunded`Variant `AgentFundedmax_budget_mist: u64`
#### Constants
```move
#[error]
const EPaymentBudgetExceeded: vector = b"TAP payment budget exceeded";
```
```move
#[error]
const EPaymentSourceMismatch: vector = b"TAP payment source does not match policy";
```
```move
#[error]
const EInvalidPaymentPolicy: vector = b"TAP payment policy is invalid";
```
```move
#[error]
const EPaymentAlreadyFinalized: vector = b"TAP payment is already finalized";
```
```move
#[error]
const EPaymentRefillAmountZero: vector = b"TAP execution payment refill amount is zero";
```
```move
#[error]
const EPaymentToolCostMissing: vector = b"TAP payment tool cost snapshot is missing";
```
```move
#[error]
const EPaymentToolCostAlreadySnapshotted: vector = b"TAP payment tool cost snapshot is immutable";
```
```move
#[error]
const EPaymentVertexAlreadyLocked: vector = b"TAP payment vertex is already locked";
```
```move
#[error]
const EPaymentVertexLockMissing: vector = b"TAP payment vertex lock is missing";
```
```move
#[error]
const EInvocationMismatch: vector = b"Invocation does not match the payment lock";
```
```move
#[error]
const EPaymentHasLocks: vector = b"TAP payment has vertex locks";
```
```move
#[error]
const EInvalidPriorityFee: vector = b"TAP priority fee must be in 10..=10000";
```
```move
#[error]
const EPaymentOverflow: vector = b"TAP payment arithmetic overflow";
```
```move
#[error]
const ETaskPaymentReserveAuthorizationMismatch: vector = b"TAP scheduled payment authorization mismatch";
```
```move
const DEFAULT_PRIORITY_FEE_PERCENTAGE: u64 = 20;
```
```move
const MIN_PRIORITY_FEE_PERCENTAGE: u64 = 10;
```
```move
const MAX_PRIORITY_FEE_PERCENTAGE: u64 = 10000;
```
#### Function `new_task_execution_payment`
Creates the payment for one Task occurrence.
The occurrence budget is split from the reserve. The owning Task records the relationship between the occurrence and the resulting execution.
```move
public fun new_task_execution_payment(reserve: &mut nexus_interface::payment::TaskPaymentReserve, authorization: &nexus_interface::authorization::AgentSkillAuthorization, execution_id: address, occurrence_id: u64, priority_fee_percentage: u64, ctx: &mut sui::tx_context::TxContext): nexus_interface::payment::ExecutionPayment
```
#### Function `snapshot_payment_tool_cost`
Records the immutable snapshotted cost for a Tool on an ExecutionPayment. Aborts if the payment is already accomplished or refunded, or when that Tool already has a snapshot.
```move
public fun snapshot_payment_tool_cost(payment: &mut nexus_interface::payment::ExecutionPayment, tool_fqn: vector, cost: u64)
```
#### Function `consume_payment_for_verified_leader_submission`
Consumes gas from an execution payment, reimbursing the transaction sender's address balance.
```move
public fun consume_payment_for_verified_leader_submission(payment: &mut nexus_interface::payment::ExecutionPayment, amount: u64, ctx: &mut sui::tx_context::TxContext)
```
#### Function `consume_payment_for_verified_leader_submission_to_recipient`
Consumes gas from an execution payment, reimbursing the given recipient's address balance; a no-op when the amount is zero. Aborts if the payment is final or if \[`amount`] exceeds available funds.
```move
public fun consume_payment_for_verified_leader_submission_to_recipient(payment: &mut nexus_interface::payment::ExecutionPayment, amount: u64, recipient: address)
```
#### Function `consume_task_payment_reserve_for_sender`
Consumes gas from a \[[`TaskPaymentReserve`](#nexus_interface_payment_TaskPaymentReserve)] and reimburses the transaction sender.
Authorization is exactly mutable access to \[[`TaskPaymentReserve`](#nexus_interface_payment_TaskPaymentReserve)]. The caller cannot select another reimbursement address. Does nothing when the amount is zero.
```move
public fun consume_task_payment_reserve_for_sender(reserve: &mut nexus_interface::payment::TaskPaymentReserve, amount: u64, ctx: &mut sui::tx_context::TxContext)
```
#### Function `refill_execution_payment_from_coin`
Adds coin funds to an execution payment, increasing its max budget, and returns the refill amount. Aborts if the coin value is zero, or if the payment is already accomplished or refunded.
```move
public fun refill_execution_payment_from_coin(payment: &mut nexus_interface::payment::ExecutionPayment, coin: sui::coin::Coin): u64
```
#### Function `new_invocation_request`
Creates canonical policy input for one workflow \[Invocation].
```move
public fun new_invocation_request(payment: &nexus_interface::payment::ExecutionPayment, vertex_key: vector, tool_id: sui::object::ID, tool_fqn: vector, cashier_id: sui::object::ID, clock: &sui::clock::Clock): nexus_interface::payment::InvocationRequest
```
#### Function `lock_invocation`
Records one exact Invocation obligation and returns its placement authority.
```move
public fun lock_invocation(payment: &mut nexus_interface::payment::ExecutionPayment, vertex_key: vector, invocation_id: sui::object::ID, amount: u64): nexus_interface::payment::InvocationLockReceipt
```
#### Function `invocation_request_execution_id`
Returns the execution recorded by \[InvocationRequest].
```move
public fun invocation_request_execution_id(request: &nexus_interface::payment::InvocationRequest): address
```
#### Function `invocation_request_vertex_key`
Returns the runtime vertex key recorded by \[InvocationRequest].
```move
public fun invocation_request_vertex_key(request: &nexus_interface::payment::InvocationRequest): vector
```
#### Function `invocation_request_tool_id`
Returns the Tool recorded by \[InvocationRequest].
```move
public fun invocation_request_tool_id(request: &nexus_interface::payment::InvocationRequest): sui::object::ID
```
#### Function `invocation_request_tool_fqn`
Returns the Tool name recorded by \[InvocationRequest].
```move
public fun invocation_request_tool_fqn(request: &nexus_interface::payment::InvocationRequest): vector
```
#### Function `invocation_request_cashier_id`
Returns the cashier recorded by \[InvocationRequest].
```move
public fun invocation_request_cashier_id(request: &nexus_interface::payment::InvocationRequest): sui::object::ID
```
#### Function `invocation_request_payment_id`
Returns the payment recorded by \[InvocationRequest].
```move
public fun invocation_request_payment_id(request: &nexus_interface::payment::InvocationRequest): sui::object::ID
```
#### Function `invocation_request_source`
Returns the payment source recorded by \[InvocationRequest].
```move
public fun invocation_request_source(request: &nexus_interface::payment::InvocationRequest): nexus_interface::payment::PaymentSourceKind
```
#### Function `invocation_request_price_snapshot`
Returns the snapshotted Tool price recorded by \[InvocationRequest].
```move
public fun invocation_request_price_snapshot(request: &nexus_interface::payment::InvocationRequest): u64
```
#### Function `invocation_request_authorized_at_ms`
Returns the authorization time recorded by \[InvocationRequest].
```move
public fun invocation_request_authorized_at_ms(request: &nexus_interface::payment::InvocationRequest): u64
```
#### Function `into_invocation_request`
Consumes \[InvocationRequest] and returns its canonical fields.
```move
public fun into_invocation_request(request: nexus_interface::payment::InvocationRequest): (address, vector, sui::object::ID, vector, sui::object::ID, sui::object::ID, nexus_interface::payment::PaymentSourceKind, u64, u64)
```
#### Function `into_invocation_lock_receipt`
Consumes \[InvocationLockReceipt] and returns the exact placement fields.
```move
public fun into_invocation_lock_receipt(receipt: nexus_interface::payment::InvocationLockReceipt): (vector, sui::object::ID, u64)
```
#### Function `settle_invocation`
Resolves one exact Invocation obligation.
A finalized obligation withdraws the amount recorded by its lock. A refunded obligation only removes the lock and leaves all funds available.
```move
public fun settle_invocation(payment: &mut nexus_interface::payment::ExecutionPayment, vertex_key: vector, invocation_id: sui::object::ID, was_refunded: bool): (sui::balance::Balance, nexus_interface::payment::InvocationSettlementReceipt)
```
#### Function `into_invocation_settlement_receipt`
Consumes \[InvocationSettlementReceipt] and returns its exact fields.
```move
public fun into_invocation_settlement_receipt(receipt: nexus_interface::payment::InvocationSettlementReceipt): (sui::object::ID, bool)
```
#### Function `payment_leader_gas_consumed`
Returns the base leader gas consumed by the payment, excluding paid tool fees and priority.
```move
public fun payment_leader_gas_consumed(payment: &nexus_interface::payment::ExecutionPayment): u64
```
#### Function `priority_charge_for`
Returns the cumulative priority charge due for the payment's consumed leader gas.
```move
public fun priority_charge_for(payment: &nexus_interface::payment::ExecutionPayment): u64
```
#### Function `settlement_priority_delta_for_leader_gas`
Returns the priority delta due after adding a settlement's valid payable leader gas.
```move
public fun settlement_priority_delta_for_leader_gas(payment: &nexus_interface::payment::ExecutionPayment, payable_leader_gas: u64): u64
```
#### Function `settlement_charge_required`
Returns the base leader gas plus priority delta required for a committed-result settlement.
```move
public fun settlement_charge_required(payment: &nexus_interface::payment::ExecutionPayment, payable_leader_gas: u64): u64
```
#### Function `payment_available_settlement_funds`
Returns spendable payment funds for settlement after preserving locked tool payments.
```move
public fun payment_available_settlement_funds(payment: &nexus_interface::payment::ExecutionPayment): u64
```
#### Function `payment_available_settlement_charge`
Returns the amount currently available for a settlement requiring the given leader gas.
```move
public fun payment_available_settlement_charge(payment: &nexus_interface::payment::ExecutionPayment, payable_leader_gas: u64): u64
```
#### Function `settlement_charge_missing`
Returns the missing amount for a committed-result settlement, or zero when payable.
```move
public fun settlement_charge_missing(payment: &nexus_interface::payment::ExecutionPayment, payable_leader_gas: u64): u64
```
#### Function `consume_priority_fee_for_settlement`
Records and splits a committed-result settlement's priority delta.
```move
public fun consume_priority_fee_for_settlement(payment: &mut nexus_interface::payment::ExecutionPayment, priority_delta: u64): sui::balance::Balance
```
#### Function `invocation_locked`
Returns whether \[payment] contains an obligation for \[vertex\_key].
```move
public fun invocation_locked(payment: &nexus_interface::payment::ExecutionPayment, vertex_key: vector): bool
```
#### Function `locked_invocation_id`
Returns the exact \[Invocation] locked for \[vertex\_key], if one exists.
```move
public fun locked_invocation_id(payment: &nexus_interface::payment::ExecutionPayment, vertex_key: vector): std::option::Option
```
#### Function `accomplish_invoker_payment`
Marks a user-funded payment accomplished and returns any remaining funds to the funding user; a no-op if already accomplished. Aborts if the payment still has locked vertices, if its source is not user-funded, or if it is already refunded.
```move
public fun accomplish_invoker_payment(payment: &mut nexus_interface::payment::ExecutionPayment, ctx: &mut sui::tx_context::TxContext)
```
#### Function `refund_invoker_payment`
Marks a user-funded payment refunded and returns all remaining funds to the funding user; a no-op if already refunded. Aborts if the payment still has locked vertices, if its source is not user-funded, or if it is already accomplished.
```move
public fun refund_invoker_payment(payment: &mut nexus_interface::payment::ExecutionPayment, refund_reason: vector, ctx: &mut sui::tx_context::TxContext)
```
#### Function `payment_source_kind_user_funded`
Constructs a user-funded payment source for the given user address.
```move
public fun payment_source_kind_user_funded(user: address): nexus_interface::payment::PaymentSourceKind
```
#### Function `payment_source_kind_agent_funded`
Constructs an agent-funded payment source for the given agent.
```move
public fun payment_source_kind_agent_funded(agent_id: sui::object::ID): nexus_interface::payment::PaymentSourceKind
```
#### Function `payment_source_kind_is_user_funded`
Returns whether the payment source is user-funded.
```move
public fun payment_source_kind_is_user_funded(source: &nexus_interface::payment::PaymentSourceKind): bool
```
#### Function `payment_source_kind_is_agent_funded`
Returns whether the payment source is agent-funded.
```move
public fun payment_source_kind_is_agent_funded(source: &nexus_interface::payment::PaymentSourceKind): bool
```
#### Function `payment_source_kind_user`
Returns the funding user address of a user-funded payment source. Aborts if the source is agent-funded.
```move
public fun payment_source_kind_user(source: &nexus_interface::payment::PaymentSourceKind): address
```
#### Function `payment_source_kind_agent_id`
Returns the agent id of an agent-funded payment source. Aborts if the source is user-funded.
```move
public fun payment_source_kind_agent_id(source: &nexus_interface::payment::PaymentSourceKind): sui::object::ID
```
#### Function `payment_final_state_pending`
Returns the pending execution payment final state.
```move
public fun payment_final_state_pending(): nexus_interface::payment::ExecutionPaymentFinalState
```
#### Function `payment_final_state_accomplished`
Returns the accomplished execution payment final state.
```move
public fun payment_final_state_accomplished(): nexus_interface::payment::ExecutionPaymentFinalState
```
#### Function `payment_final_state_refunded`
Returns the refunded execution payment final state.
```move
public fun payment_final_state_refunded(): nexus_interface::payment::ExecutionPaymentFinalState
```
#### Function `payment_policy_user_funded`
Returns the user-funded skill payment policy.
```move
public fun payment_policy_user_funded(): nexus_interface::payment::SkillPaymentPolicy
```
#### Function `payment_policy_agent_funded`
Returns an agent-funded skill payment policy with the given maximum budget. Aborts if the maximum budget is zero.
```move
public fun payment_policy_agent_funded(max_budget_mist: u64): nexus_interface::payment::SkillPaymentPolicy
```
#### Function `payment_policy_is_agent_funded`
Returns whether the skill payment policy is agent-funded.
```move
public fun payment_policy_is_agent_funded(policy: nexus_interface::payment::SkillPaymentPolicy): bool
```
#### Function `payment_policy_max_budget_mist`
Returns the maximum budget of the payment policy, or zero for a user-funded policy.
```move
public fun payment_policy_max_budget_mist(policy: nexus_interface::payment::SkillPaymentPolicy): u64
```
#### Function `assert_payment_policy`
Asserts that a payment source and budget satisfy the skill payment policy for the given agent. Aborts if a user-funded policy is not user-funded, if an agent-funded budget is zero or exceeds the policy maximum, or if the agent-funded source's agent does not match.
```move
public fun assert_payment_policy(agent_id: sui::object::ID, policy: nexus_interface::payment::SkillPaymentPolicy, source: &nexus_interface::payment::PaymentSourceKind, max_budget_mist: u64)
```
#### Function `payment_agent_id`
Returns the agent id owning the execution payment.
```move
public fun payment_agent_id(payment: &nexus_interface::payment::ExecutionPayment): sui::object::ID
```
#### Function `payment_skill_id`
Returns the skill id of the execution payment.
```move
public fun payment_skill_id(payment: &nexus_interface::payment::ExecutionPayment): u64
```
#### Function `payment_interface_revision`
Returns the interface revision the execution payment was created under.
```move
public fun payment_interface_revision(payment: &nexus_interface::payment::ExecutionPayment): nexus_interface::version::InterfaceVersion
```
#### Function `payment_execution_id`
Returns the execution id the payment funds.
```move
public fun payment_execution_id(payment: &nexus_interface::payment::ExecutionPayment): address
```
#### Function `payment_consumed`
Returns the total amount consumed from the execution payment so far.
```move
public fun payment_consumed(payment: &nexus_interface::payment::ExecutionPayment): u64
```
#### Function `payment_funds`
Returns the current balance of funds held by the execution payment.
```move
public fun payment_funds(payment: &nexus_interface::payment::ExecutionPayment): u64
```
#### Function `payment_source_kind`
Returns the funding source of the execution payment.
```move
public fun payment_source_kind(payment: &nexus_interface::payment::ExecutionPayment): nexus_interface::payment::PaymentSourceKind
```
#### Function `payment_locked_budget_mist`
Returns the MIST budget locked by the execution payment, including refills.
```move
public fun payment_locked_budget_mist(payment: &nexus_interface::payment::ExecutionPayment): u64
```
#### Function `payment_final_state`
Returns the execution payment's lifecycle final state.
```move
public fun payment_final_state(payment: &nexus_interface::payment::ExecutionPayment): nexus_interface::payment::ExecutionPaymentFinalState
```
#### Function `payment_max_budget_mist`
Returns the execution payment's total gas-plus-priority ceiling in MIST.
```move
public fun payment_max_budget_mist(payment: &nexus_interface::payment::ExecutionPayment): u64
```
#### Function `payment_gas_budget_mist`
Returns the maximal transaction gas and Tool invocation budget in MIST.
```move
public fun payment_gas_budget_mist(payment: &nexus_interface::payment::ExecutionPayment): u64
```
#### Function `payment_priority_fee_reserve_mist`
Returns the priority-fee reserve in MIST derived from the total ceiling.
```move
public fun payment_priority_fee_reserve_mist(payment: &nexus_interface::payment::ExecutionPayment): u64
```
#### Function `payment_priority_fee_percentage`
Returns the priority fee percentage stored on the execution payment.
```move
public fun payment_priority_fee_percentage(payment: &nexus_interface::payment::ExecutionPayment): u64
```
#### Function `payment_priority_fee_charged`
Returns the priority fee charged during terminal settlement.
```move
public fun payment_priority_fee_charged(payment: &nexus_interface::payment::ExecutionPayment): u64
```
#### Function `payment_accomplished`
Returns whether the execution payment has been accomplished.
```move
public fun payment_accomplished(payment: &nexus_interface::payment::ExecutionPayment): bool
```
#### Function `payment_refunded`
Returns whether the execution payment has been refunded.
```move
public fun payment_refunded(payment: &nexus_interface::payment::ExecutionPayment): bool
```
#### Function `payment_locks`
Returns the number of currently locked vertices on the execution payment.
```move
public fun payment_locks(payment: &nexus_interface::payment::ExecutionPayment): u64
```
#### Function `payment_available_funds`
Returns the base execution funds still available to spend in MIST.
```move
public fun payment_available_funds(payment: &nexus_interface::payment::ExecutionPayment): u64
```
#### Function `can_lock_payment_vertex_with_amount`
Returns whether available funds can cover a vertex amount.
```move
public fun can_lock_payment_vertex_with_amount(payment: &nexus_interface::payment::ExecutionPayment, amount: u64): bool
```
#### Function `payment_tool_cost`
Returns the snapshotted cost for the given tool on the execution payment. Aborts if no cost snapshot exists for the tool.
```move
public fun payment_tool_cost(payment: &nexus_interface::payment::ExecutionPayment, tool_fqn: vector): u64
```
#### Function `has_payment_tool_cost_snapshot`
Returns whether an ExecutionPayment has frozen the supplied Tool price.
```move
public fun has_payment_tool_cost_snapshot(payment: &nexus_interface::payment::ExecutionPayment, tool_fqn: &vector): bool
```
#### Function `task_payment_reserve_task_id`
Returns the Task that owns the reserve.
```move
public fun task_payment_reserve_task_id(self: &nexus_interface::payment::TaskPaymentReserve): sui::object::ID
```
#### Function `task_payment_reserve_agent_id`
Returns the agent id of the reserve.
```move
public fun task_payment_reserve_agent_id(self: &nexus_interface::payment::TaskPaymentReserve): sui::object::ID
```
#### Function `task_payment_reserve_skill_id`
Returns the skill id of the reserve.
```move
public fun task_payment_reserve_skill_id(self: &nexus_interface::payment::TaskPaymentReserve): u64
```
#### Function `task_payment_reserve_interface_version`
Returns the interface version of the reserve.
```move
public fun task_payment_reserve_interface_version(self: &nexus_interface::payment::TaskPaymentReserve): nexus_interface::version::InterfaceVersion
```
#### Function `task_payment_reserve_authorization_id`
Returns the id of the agent-skill authorization bound to the reserve.
```move
public fun task_payment_reserve_authorization_id(self: &nexus_interface::payment::TaskPaymentReserve): sui::object::ID
```
#### Function `task_payment_reserve_occurrence_budget_mist`
Returns the per-occurrence budget of the reserve.
```move
public fun task_payment_reserve_occurrence_budget_mist(self: &nexus_interface::payment::TaskPaymentReserve): u64
```
#### Function `task_payment_reserve_remaining_funds`
Returns the remaining funds held by the reserve.
```move
public fun task_payment_reserve_remaining_funds(self: &nexus_interface::payment::TaskPaymentReserve): u64
```
#### Function `task_payment_reserve_source_kind`
Returns the funding source of the reserve.
```move
public fun task_payment_reserve_source_kind(self: &nexus_interface::payment::TaskPaymentReserve): nexus_interface::payment::PaymentSourceKind
```
#### Function `task_payment_reserve_payment_policy`
Returns the skill payment policy of the reserve.
```move
public fun task_payment_reserve_payment_policy(self: &nexus_interface::payment::TaskPaymentReserve): nexus_interface::payment::SkillPaymentPolicy
```
#### Function `refill_task_payment_reserve_address_funded`
Adds user funds to a \[[`TaskPaymentReserve`](#nexus_interface_payment_TaskPaymentReserve)].
```move
public fun refill_task_payment_reserve_address_funded(reserve: &mut nexus_interface::payment::TaskPaymentReserve, coin: sui::coin::Coin)
```
#### Function `cancel_task_payment_reserve_address_funded`
Returns all user funds held by a \[[`TaskPaymentReserve`](#nexus_interface_payment_TaskPaymentReserve)].
```move
public fun cancel_task_payment_reserve_address_funded(reserve: &mut nexus_interface::payment::TaskPaymentReserve, ctx: &mut sui::tx_context::TxContext)
```
#### Function `accomplish_task_execution_payment`
Accomplishes one Task execution and restores its unused funds.
```move
public fun accomplish_task_execution_payment(reserve: &mut nexus_interface::payment::TaskPaymentReserve, payment: &mut nexus_interface::payment::ExecutionPayment, occurrence_id: u64)
```
#### Function `refund_task_execution_payment`
Refunds one Task execution and restores its unused funds.
```move
public fun refund_task_execution_payment(reserve: &mut nexus_interface::payment::TaskPaymentReserve, payment: &mut nexus_interface::payment::ExecutionPayment, occurrence_id: u64, refund_reason: vector)
```
#### Function `priority_fee_percentage`
Normalizes an optional priority-fee percentage to the effective on-chain value.
```move
public fun priority_fee_percentage(priority_fee_percentage: std::option::Option): u64
```
#### Function `priority_fee_mist_for_gas_budget`
Computes the priority fee in MIST as `floor(gas_budget_mist *` [`priority_fee_percentage`](#nexus_interface_payment_priority_fee_percentage) `/ 100)`.
```move
public fun priority_fee_mist_for_gas_budget(gas_budget_mist: u64, priority_fee_percentage: u64): u64
```
#### Function `budget_split_mist`
Computes the maximal base gas budget and its priority reserve for a total MIST ceiling.
```move
public fun budget_split_mist(max_budget_mist: u64, priority_fee_percentage: u64): (u64, u64)
```
#### Function `gas_budget_mist_for_max_budget_mist`
Computes the largest base gas budget that fits within a total MIST ceiling.
```move
public fun gas_budget_mist_for_max_budget_mist(max_budget_mist: u64, priority_fee_percentage: u64): u64
```
#### Function `destroy_empty_task_payment_reserve`
Destroys a \[[`TaskPaymentReserve`](#nexus_interface_payment_TaskPaymentReserve)] after all funds were returned.
```move
public fun destroy_empty_task_payment_reserve(reserve: nexus_interface::payment::TaskPaymentReserve)
```
---
# 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/reference/move/nexus_interface/payment.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.