> 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/sdk/actions-tool.md).

# Tool Actions

**Audience:** Nexus SDK integrators (Rust).

**Area:** Tool actions.

**Generated from:** Nexus SDK public API at release `v2.1.1` commit `08bfe76e726922ce512d623fbc1d2e1bd786bcd4` (generated inventory preserved below).

The inventory below is the public Tool surface. Older ticket/payment compatibility APIs are historical and are not part of the documented declarations; see the [Invocation policy and settlement model](/concepts/06-payment-vaults-reserves-and-settlement.md#invocation-policy-and-settlement-model) for migration context.

### Tool administration capability boundary

The SDK's `set_verified` and `set_verified_ptb` operations update the Tool Registry verification flag and require the Tool Registry administration capability. A `CloneableOwnerCap<OverTool>` authorizes Tool-owner operations, while a `CloneableOwnerCap<OverToolCashier>` authorizes cashier policy operations; neither substitutes for `ToolRegistryAdminCap` or for registered-key and external result-verifier configuration.

Treat the verification flag, package registration, witness identity, and result-verifier setup as separate readbacks. Retain the exact capability object, transaction effects, and post-state Tool record before describing a Tool as verified.

### Source-derived public API inventory

#### `ToolCompatibility`

```rust
pub enum ToolCompatibility {
    /// The Tool selects the same package graph as the current Registry.
    Current,
    /// The SDK understands the Tool, and no live Registry mutation is required.
    LegacyUnderstood,
    /// The SDK understands the Tool, but live Registry use requires migration.
    MigrationRequired,
    /// The observed era and inner pair has no adapter in this SDK.
    Unsupported,
    /// The Tool could not be observed or decoded independently.
    Unavailable,
}
```

#### `EntitlementPurchaseResult`

```rust
pub struct EntitlementPurchaseResult {
    pub tx_digest: sui::types::Digest,
    pub entitlement_id: sui::types::Address,
    pub deposit_id: sui::types::Address,
}
```

#### `EntitlementIssueResult`

```rust
pub struct EntitlementIssueResult {
    pub tx_digest: sui::types::Digest,
    pub entitlement_id: sui::types::Address,
}
```

#### `FiniteCreditOffer`

```rust
pub struct FiniteCreditOffer {
    pub issuance_enabled: bool,
    pub price_per_credit: u64,
    pub minimum_credits: u64,
    pub maximum_credits: u64,
}
```

#### `TimePassOffer`

```rust
pub struct TimePassOffer {
    pub issuance_enabled: bool,
    pub price_per_ms: u64,
    pub minimum_duration_ms: u64,
    pub maximum_duration_ms: u64,
}
```

#### `ToolEconomy`

```rust
pub struct ToolEconomy {
    pub tool_id: sui::types::Address,
    pub cashier_id: sui::types::Address,
    pub policies: Vec<TypeName>,
    pub fixed_price_mist: u64,
    pub finite_credits: Option<FiniteCreditOffer>,
    pub time_pass: Option<TimePassOffer>,
}
```

#### `FiniteCreditAccess`

```rust
pub struct FiniteCreditAccess {
    pub account_id: sui::types::Address,
    pub remaining: u64,
    pub refunded_invocations: Vec<sui::types::Address>,
}
```

#### `TimePassAccess`

```rust
pub struct TimePassAccess {
    pub account_id: sui::types::Address,
    pub valid_from_ms: u64,
    pub valid_until_ms: u64,
    pub active: bool,
}
```

#### `ToolAccess`

```rust
pub struct ToolAccess {
    pub tool_id: sui::types::Address,
    pub cashier_id: sui::types::Address,
    pub beneficiary: PaymentSourceKind,
    pub observed_at_ms: u64,
    pub finite_credits: Option<FiniteCreditAccess>,
    pub time_pass: Option<TimePassAccess>,
}
```

#### `CollectableInvocation`

```rust
pub struct CollectableInvocation {
    pub object_ref: sui::types::ObjectReference,
    pub policy: TypeName,
    pub sources: Vec<sui::types::Address>,
    pub amount_mist: u64,
}
```

#### `CollectableDeposit`

```rust
pub struct CollectableDeposit {
    pub object_ref: sui::types::ObjectReference,
    pub amount_mist: u64,
}
```

#### `ToolCashierInbox`

```rust
pub struct ToolCashierInbox {
    pub invocations: Vec<CollectableInvocation>,
    pub deposits: Vec<CollectableDeposit>,
}
```

#### `ToolInspection`

```rust
pub struct ToolInspection {
    /// Requested fully qualified name.
    pub fqn: ToolFqn,
    /// Stable Tool object ID.
    pub tool_id: sui::types::Address,
    /// Stable cashier object ID.
    pub tool_cashier_id: sui::types::Address,
    /// Whether the stable Tool object exists.
    pub exists: bool,
    /// Current owner when the Tool was observed.
    pub owner: Option<sui::types::Owner>,
    /// Exact era type observed below the Tool anchor.
    pub witness_type: Option<sui::types::StructTag>,
    /// Exact inner type observed below the Tool anchor.
    pub inner_type: Option<sui::types::StructTag>,
    /// Compatibility classification isolated to this Tool.
    pub compatibility: ToolCompatibility,
    /// Complete supported Tool state.
    pub tool: Option<ToolState>,
    /// Current Registry verifier support while the Tool is registered.
    pub verifier_support: Option<ToolVerifierSupport>,
    /// Current external verifier record, when configured.
    pub external_verifier: Option<ExternalVerifier>,
    /// Current Registry timeout while the Tool is registered.
    pub timeout_ms: Option<u64>,
    /// Current invocation price while the Tool is registered.
    pub invocation_cost_mist: Option<u64>,
    /// Diagnostic detail for unsupported or unavailable state.
    pub detail: Option<String>,
}
```

#### `ToolActionResult`

```rust
pub struct ToolActionResult {
    /// Digest of the submitted transaction.
    pub tx_digest: sui::types::Digest,
}
```

#### `ToolCashierActionResult`

```rust
pub type ToolCashierActionResult = ToolActionResult;
```

#### `ToolActions`

```rust
pub struct ToolActions {
    pub(super) client: NexusClient,
}
```

#### `ToolActions::list_tools`

```rust
pub async fn list_tools(&self) -> Result<Vec<ToolInspection>, NexusError> {
```

#### `ToolActions::inspect_tool`

```rust
pub async fn inspect_tool(&self, fqn: &ToolFqn) -> Result<ToolInspection, NexusError> {
```

#### `ToolActions::update_timeout`

```rust
pub async fn update_timeout(
        &self,
        fqn: &ToolFqn,
        timeout: Duration,
        owner_cap: sui::types::Address,
    ) -> Result<ToolActionResult, NexusError> {
```

#### `ToolActions::update_url`

```rust
pub async fn update_url(
        &self,
        fqn: &ToolFqn,
        url: &str,
        owner_cap: sui::types::Address,
    ) -> Result<ToolActionResult, NexusError> {
```

#### `ToolActions::update_metadata`

```rust
pub async fn update_metadata(
        &self,
        fqn: &ToolFqn,
        description: &str,
        owner_cap: sui::types::Address,
    ) -> Result<ToolActionResult, NexusError> {
```

#### `ToolActions::set_invocation_cost`

```rust
pub async fn set_invocation_cost(
        &self,
        fqn: &ToolFqn,
        cost_mist: u64,
        cashier_admin: sui::types::Address,
    ) -> Result<ToolActionResult, NexusError> {
```

#### `ToolActions::set_verified`

```rust
pub async fn set_verified(
        &self,
        fqn: &ToolFqn,
        verified: bool,
    ) -> Result<ToolActionResult, NexusError> {
```

#### `ToolActions::configure_registered_key_verifier`

```rust
pub async fn configure_registered_key_verifier(
        &self,
        fqn: &ToolFqn,
        owner_cap: sui::types::Address,
    ) -> Result<ToolActionResult, NexusError> {
```

#### `ToolActions::configure_external_verifier`

```rust
pub async fn configure_external_verifier(
        &self,
        fqn: &ToolFqn,
        owner_cap: sui::types::Address,
        package_id: sui::types::Address,
        module_name: &str,
        function_name: &str,
        verifier_object_ids: &[sui::types::Address],
    ) -> Result<ToolActionResult, NexusError> {
```

#### `ToolActions::migrate_on_chain_package`

```rust
pub async fn migrate_on_chain_package(
        &self,
        fqn: &ToolFqn,
        target_package: sui::types::Address,
        owner_cap: sui::types::Address,
    ) -> Result<ToolActionResult, NexusError> {
```

#### `ToolActions::unregister`

```rust
pub async fn unregister(
        &self,
        fqn: &ToolFqn,
        owner_cap: sui::types::Address,
    ) -> Result<ToolActionResult, NexusError> {
```

#### `ToolActions::claim_collateral`

```rust
pub async fn claim_collateral(
        &self,
        fqn: &ToolFqn,
        owner_cap: sui::types::Address,
    ) -> Result<ToolActionResult, NexusError> {
```

#### `ToolActions::enable_time_passes`

```rust
pub async fn enable_time_passes(
        &self,
        tool_fqn: &ToolFqn,
        cashier_admin: sui::types::Address,
        price_per_ms: u64,
        minimum_duration_ms: u64,
        maximum_duration_ms: u64,
    ) -> Result<ToolCashierActionResult, NexusError> {
```

#### `ToolActions::close_time_pass_issuance`

```rust
pub async fn close_time_pass_issuance(
        &self,
        fqn: &ToolFqn,
        cashier_admin: sui::types::Address,
    ) -> Result<ToolCashierActionResult, NexusError> {
```

#### `ToolActions::open_time_pass_issuance`

```rust
pub async fn open_time_pass_issuance(
        &self,
        fqn: &ToolFqn,
        cashier_admin: sui::types::Address,
    ) -> Result<ToolCashierActionResult, NexusError> {
```

#### `ToolActions::update_time_pass_terms`

```rust
pub async fn update_time_pass_terms(
        &self,
        tool_fqn: &ToolFqn,
        cashier_admin: sui::types::Address,
        price_per_ms: u64,
        minimum_duration_ms: u64,
        maximum_duration_ms: u64,
    ) -> Result<ToolCashierActionResult, NexusError> {
```

#### `ToolActions::buy_time_pass`

```rust
pub async fn buy_time_pass(
        &self,
        tool_fqn: &ToolFqn,
        duration_ms: u64,
    ) -> Result<EntitlementPurchaseResult, NexusError> {
```

#### `ToolActions::buy_time_pass_for`

```rust
pub async fn buy_time_pass_for(
        &self,
        tool_fqn: &ToolFqn,
        duration_ms: u64,
        beneficiary: PaymentSourceKind,
    ) -> Result<EntitlementPurchaseResult, NexusError> {
```

#### `ToolActions::issue_time_pass`

```rust
pub async fn issue_time_pass(
        &self,
        tool_fqn: &ToolFqn,
        cashier_admin: sui::types::Address,
        beneficiary: PaymentSourceKind,
        valid_from_ms: u64,
        valid_until_ms: u64,
    ) -> Result<EntitlementIssueResult, NexusError> {
```

#### `ToolActions::enable_finite_credits`

```rust
pub async fn enable_finite_credits(
        &self,
        tool_fqn: &ToolFqn,
        cashier_admin: sui::types::Address,
        price_per_credit: u64,
        minimum_credits: u64,
        maximum_credits: u64,
    ) -> Result<ToolCashierActionResult, NexusError> {
```

#### `ToolActions::close_finite_credit_issuance`

```rust
pub async fn close_finite_credit_issuance(
        &self,
        fqn: &ToolFqn,
        cashier_admin: sui::types::Address,
    ) -> Result<ToolCashierActionResult, NexusError> {
```

#### `ToolActions::open_finite_credit_issuance`

```rust
pub async fn open_finite_credit_issuance(
        &self,
        tool_fqn: &ToolFqn,
        cashier_admin: sui::types::Address,
    ) -> Result<ToolCashierActionResult, NexusError> {
```

#### `ToolActions::update_finite_credit_terms`

```rust
pub async fn update_finite_credit_terms(
        &self,
        tool_fqn: &ToolFqn,
        cashier_admin: sui::types::Address,
        price_per_credit: u64,
        minimum_credits: u64,
        maximum_credits: u64,
    ) -> Result<ToolCashierActionResult, NexusError> {
```

#### `ToolActions::buy_finite_credits`

```rust
pub async fn buy_finite_credits(
        &self,
        tool_fqn: &ToolFqn,
        credits: u64,
    ) -> Result<EntitlementPurchaseResult, NexusError> {
```

#### `ToolActions::buy_finite_credits_for`

```rust
pub async fn buy_finite_credits_for(
        &self,
        tool_fqn: &ToolFqn,
        credits: u64,
        beneficiary: PaymentSourceKind,
    ) -> Result<EntitlementPurchaseResult, NexusError> {
```

#### `ToolActions::issue_finite_credits`

```rust
pub async fn issue_finite_credits(
        &self,
        tool_fqn: &ToolFqn,
        cashier_admin: sui::types::Address,
        beneficiary: PaymentSourceKind,
        credits: u64,
    ) -> Result<EntitlementIssueResult, NexusError> {
```

#### `ToolActions::restore_finite_credit_refund`

```rust
pub async fn restore_finite_credit_refund(
        &self,
        tool_fqn: &ToolFqn,
        invocation_id: sui::types::Address,
    ) -> Result<EntitlementIssueResult, NexusError> {
```

#### `ToolActions::inspect_access`

```rust
pub async fn inspect_access(
        &self,
        tool_fqn: &ToolFqn,
        beneficiary: PaymentSourceKind,
    ) -> Result<ToolAccess, NexusError> {
```

#### `ToolActions::inspect_economy`

```rust
pub async fn inspect_economy(&self, tool_fqn: &ToolFqn) -> Result<ToolEconomy, NexusError> {
```

#### `ToolActions::inspect_cashier_inbox`

```rust
pub async fn inspect_cashier_inbox(
        &self,
        tool_fqn: &ToolFqn,
    ) -> Result<ToolCashierInbox, NexusError> {
```

#### `ToolActions::collect_invocations`

```rust
pub async fn collect_invocations(
        &self,
        tool_fqn: &ToolFqn,
        cashier_admin: sui::types::Address,
        invocation_ids: &[sui::types::Address],
        recipient: sui::types::Address,
    ) -> Result<ToolCashierActionResult, NexusError> {
```

#### `ToolActions::collect_deposits`

```rust
pub async fn collect_deposits(
        &self,
        tool_fqn: &ToolFqn,
        cashier_admin: sui::types::Address,
        deposit_ids: &[sui::types::Address],
        recipient: sui::types::Address,
    ) -> Result<ToolCashierActionResult, NexusError> {
```

#### `generate_input_schema`

```rust
pub async fn generate_input_schema(
    client: Arc<sui::grpc::Client>,
    package_address: sui::types::Address,
    module_name: &str,
    execute_function: &str,
) -> AnyResult<String> {
```

#### `generate_input_schema_with_mode`

```rust
pub async fn generate_input_schema_with_mode(
    client: Arc<sui::grpc::Client>,
    package_address: sui::types::Address,
    module_name: &str,
    execute_function: &str,
) -> AnyResult<(String, OnchainToolMode)> {
```

#### `re-export generate_output_schema, types, convert_move_signature_to_schema, convert_move_type_to_schema, is_agent_vertex_authorization_proof_param, is_hidden_internal_tool_param, is_onchain_tool_result_param, is_tx_context_param`

```rust
pub use {
    input::{generate_input_schema, generate_input_schema_with_mode},
    output::generate_output_schema,
    types::{
        convert_move_signature_to_schema,
        convert_move_type_to_schema,
        is_agent_vertex_authorization_proof_param,
        is_hidden_internal_tool_param,
        is_onchain_tool_result_param,
        is_tx_context_param,
    },
};
```

#### `generate_output_schema`

```rust
pub async fn generate_output_schema(
    client: Arc<sui::grpc::Client>,
    package_address: sui::types::Address,
    module_name: &str,
    output_enum_name: &str,
) -> AnyResult<String> {
```

#### `convert_move_signature_to_schema`

```rust
pub fn convert_move_signature_to_schema(signature: &sui::grpc::OpenSignature) -> AnyResult<Value> {
```

#### `convert_move_type_to_schema`

```rust
pub fn convert_move_type_to_schema(move_type: &sui::grpc::OpenSignatureBody) -> AnyResult<Value> {
```

#### `is_tx_context_param`

```rust
pub fn is_tx_context_param(move_type: &sui::grpc::OpenSignatureBody) -> bool {
```

#### `is_hidden_internal_tool_param`

```rust
pub fn is_hidden_internal_tool_param(move_type: &sui::grpc::OpenSignatureBody) -> bool {
```

#### `is_onchain_tool_result_param`

```rust
pub fn is_onchain_tool_result_param(move_type: &sui::grpc::OpenSignatureBody) -> bool {
```

#### `is_agent_vertex_authorization_proof_param`

```rust
pub fn is_agent_vertex_authorization_proof_param(move_type: &sui::grpc::OpenSignatureBody) -> bool {
```

#### `ToolFqn`

```rust
pub struct ToolFqn {
    domain: String,
    name: String,
    version: u32,
}
```

#### `ToolFqn::domain`

```rust
pub fn domain(&self) -> &str {
```

#### `ToolFqn::name`

```rust
pub fn name(&self) -> &str {
```

#### `ToolFqn::version`

```rust
pub fn version(&self) -> u32 {
```

#### `fqn!`

```rust
macro_rules! fqn {
    ($fqn:expr) => {{
        ($fqn as &'static str).parse::<$crate::ToolFqn>().unwrap()
    }};
}
```


---

# 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/sdk/actions-tool.md?ask=<question>&goal=<user_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.