@trustwallet/cli 0.24.2 → 0.25.0

package/dist/index.js

@@ -3437,24 +3437,42 @@ async function resolveDecimals(search, chain2, params) {
   }
   const isNative = params.isNative ?? address.toLowerCase() === getNativeAddressPlaceholder(chain2).toLowerCase();
   const known = lookupKnownTokenDecimals(chain2, isNative ? void 0 : address);
-  const isRawAddress = carriesRawEvmAddress(token);
+  const needsDecimals = known === void 0 && !isNative;
   let searched;
-  if (isRawAddress || explicit === void 0 && known === void 0 && !isNative) {
-    const matches = await search.searchTokens({ query: address, chains: [chain2] }).catch(() => []);
+  if (needsDecimals || carriesRawEvmAddress(token)) {
+    let matches;
+    try {
+      matches = await search.searchTokens({ query: address, chains: [chain2] });
+    } catch (err) {
+      if (needsDecimals) {
+        throw new CommandError(
+          "NETWORK_ERROR",
+          `Could not look up the decimals of ${token} on ${chain2}: the token search failed (${errorMessage(err)}). Retry.`
+        );
+      }
+      matches = [];
+    }
     const match = matches.find((m2) => m2.address.toLowerCase() === address.toLowerCase());
     if (match) {
       if (match.address) address = match.address;
       if (typeof match.decimals === "number") searched = match.decimals;
     }
   }
-  const decimals = explicit ?? searched ?? known;
-  if (decimals === void 0) {
-    throw new CommandError(
-      "VALIDATION_ERROR",
-      `Could not determine decimals for ${token} on ${chain2}; provide decimals explicitly.`
-    );
+  const resolved = known !== void 0 ? { address, decimals: known, source: "registry" } : searched !== void 0 ? { address, decimals: searched, source: "search" } : void 0;
+  if (resolved) {
+    if (explicit !== void 0 && explicit !== resolved.decimals) {
+      throw new CommandError(
+        "VALIDATION_ERROR",
+        `${token} on ${chain2} has ${resolved.decimals} decimals (from the ${resolved.source === "registry" ? "token registry" : "token search"}), but ${explicit} was passed. Omit decimals for tokens twak knows, and check that this is the token you meant.`
+      );
+    }
+    return resolved;
   }
-  return { address, decimals };
+  if (explicit !== void 0) return { address, decimals: explicit, source: "caller" };
+  throw new CommandError(
+    "VALIDATION_ERROR",
+    `Could not determine decimals for ${token} on ${chain2}: twak does not know this token. Provide decimals explicitly if you know them.`
+  );
 }
 async function resolveAddress(search, chain2, params) {
   const { token, address } = params;
@@ -6453,7 +6471,6 @@ __export(dist_exports, {
   getAmberDomainsByCoinId: () => getAmberDomainsByCoinId,
   getCoinType: () => getCoinType,
   getWalletCore: () => getWalletCore,
-  humanAmountToWei: () => humanAmountToWei,
   initTrustSDK: () => initTrustSDK,
   isInitialized: () => isInitialized,
   patchNaasSession: () => patchNaasSession,
@@ -7060,13 +7077,6 @@ function chainKeyToDefinedChain(chainKey) {
   const chain2 = isTestnet(chainKey) ? new import_trust_sdk3.CustomChain(ct5, chainConfig.chainId) : new import_trust_sdk3.DefinedChain(ct5);
   return { chain: chain2, chainConfig };
 }
-function humanAmountToWei(amount, decimals = 18) {
-  const parts = amount.split(".");
-  const whole = BigInt(parts[0] || "0");
-  if (parts.length === 1) return whole * 10n ** BigInt(decimals);
-  const frac = parts[1].padEnd(decimals, "0").slice(0, decimals);
-  return whole * 10n ** BigInt(decimals) + BigInt(frac);
-}
 function createPendingTransaction(client, chainKey, hash) {
   return {
     hash,
@@ -7109,16 +7119,6 @@ function requireCoinType(coinId) {
   }
   return ct5;
 }
-function getCoinDecimals(coinId) {
-  try {
-    const wc3 = getWalletCore();
-    const ct5 = requireCoinType(coinId);
-    return wc3.CoinTypeConfiguration.getDecimals(ct5);
-  } catch {
-    const chainKey = mainnetChainKeyForCoinId(coinId);
-    return chainKey ? chainOf(chainKey).decimals : 18;
-  }
-}
 function tokenTypeForCoinId(coinId) {
   switch (coinId) {
     // Tron
@@ -7627,25 +7627,15 @@ var init_dist3 = __esm({
         const ct5 = requireCoinType(coinId);
         const account = this.getAccountFromSigner(chainKey);
         const asset = contractAddress ? new import_trust_sdk2.Asset.Token(account, contractAddress, tokenTypeForCoinId(coinId)) : new import_trust_sdk2.Asset.Coin(account);
-        let decimals;
-        if (params.decimals !== void 0) {
-          decimals = params.decimals;
-        } else if (contractAddress) {
-          const known = lookupKnownTokenDecimals(chainKey, contractAddress);
-          if (known === void 0) {
-            throw new TwakValidationError(
-              `Cannot determine decimals for ${params.assetId}; pass decimals explicitly.`
-            );
-          }
-          decimals = known;
-        } else {
-          decimals = getCoinDecimals(coinId);
+        if (params.atomicAmount < 0n) {
+          throw new TwakValidationError(
+            `atomicAmount must not be negative, got ${params.atomicAmount}.`
+          );
         }
-        const amountWei = humanAmountToWei(params.amount, decimals);
         const transaction = new import_trust_sdk2.TransactionTransfer(
           params.to,
           asset,
-          amountWei.toString(),
+          params.atomicAmount.toString(),
           false,
           params.memo || null
         );
@@ -7722,7 +7712,7 @@ var init_dist3 = __esm({
         const transaction = new import_trust_sdk2.TransactionTransfer(
           params.to,
           asset,
-          params.amount,
+          params.atomicAmount.toString(),
           false,
           params.memo || null
         );
@@ -8352,7 +8342,7 @@ var init_dist3 = __esm({
         const result = await this.blockchainClient.transfer({
           assetId,
           to: params.to,
-          amount: params.value || "0",
+          atomicAmount: 0n,
           hdWallet,
           chainKey
         });
@@ -41911,10 +41901,13 @@ var WalletConnectProvider = class extends WalletProvider {
         `transfer on ${chainKey} is not supported in WalletConnect mode (EVM-only). Switch to local wallet mode for ${chainKey} transfers.`
       );
     }
-    if (request.decimals === void 0) {
-      throw new TransferError("VALIDATION_ERROR", `Decimals are required for ${request.assetId}`);
+    const { atomicAmount } = request;
+    if (atomicAmount < 0n) {
+      throw new TransferError(
+        "VALIDATION_ERROR",
+        `atomicAmount must not be negative, got ${atomicAmount}.`
+      );
     }
-    const atomicAmount = BigInt(parseAmount(request.amount, request.decimals));
     const { contractAddress } = parseTokenId(request.assetId);
     if (contractAddress) {
       assertEvmAddress(contractAddress, "tokenAddress");
@@ -43309,9 +43302,9 @@ var TransferExecutor = class {
         `Unknown token: ${assetId} on ${chainKey}. Use a contract address (0x...) or a supported symbol.`
       );
     }
-    let resolvedTo;
+    let resolvedTo = params.to;
     try {
-      resolvedTo = await resolveAddressOrName(params.to);
+      if (params.resolveNames !== false) resolvedTo = await resolveAddressOrName(params.to);
     } catch (err) {
       const msg = errorMessage(err);
       if (msg.includes("Could not resolve name")) {
@@ -43336,7 +43329,7 @@ var TransferExecutor = class {
       isNative: !contractAddress,
       explicitDecimals: params.decimals ?? null
     });
-    parseAmount(params.amount, decimals);
+    const atomicAmount = BigInt(parseAmount(params.amount, decimals));
     if (!params.safety?.skip) {
       const maxUsd = params.safety?.maxUsd ?? DEFAULT_MAX_TRANSFER_USD;
       const warnThreshold = params.safety?.warnThresholdUsd ?? DEFAULT_WARN_THRESHOLD_USD;
@@ -43371,8 +43364,7 @@ var TransferExecutor = class {
         chainKey,
         assetId,
         to: resolvedTo,
-        amount: params.amount,
-        decimals,
+        atomicAmount,
         memo: params.memo
       });
     } catch (err) {
@@ -44224,9 +44216,16 @@ ${qr3}`;
     "Comma-separated chains: keys, aliases or CAIP-2 IDs (default: all supported EVM chains)"
   ).option("--timeout <seconds>", "Connection timeout in seconds", "300").option("--json", "JSON output").action(async (opts) => {
     try {
+      const timeoutSec = Number(opts.timeout);
+      if (!Number.isInteger(timeoutSec) || timeoutSec <= 0) {
+        throw new WalletError(
+          "VALIDATION_ERROR",
+          `--timeout must be a positive whole number of seconds (got "${opts.timeout}").`
+        );
+      }
+      const chainKeys = opts.chains ? parseChainList(opts.chains) : void 0;
       const projectId = await resolveWcProjectId(opts.projectId);
       const provider = createWalletConnectProvider(projectId, new ChainClient());
-      const chainKeys = opts.chains ? parseChainList(opts.chains) : void 0;
       info("Connecting via WalletConnect...");
       const result = await provider.connect(chainKeys);
       const qr3 = getQRString(result.uri);
@@ -44236,13 +44235,6 @@ ${qr3}`;
       info(`Trust Wallet: ${result.deepLinks.native}`);
       info(`Universal:    ${result.deepLinks.universal}`);
       info("\nWaiting for wallet approval...");
-      const timeoutSec = Number(opts.timeout);
-      if (!Number.isInteger(timeoutSec) || timeoutSec <= 0) {
-        throw new WalletError(
-          "VALIDATION_ERROR",
-          `--timeout must be a positive whole number of seconds (got "${opts.timeout}").`
-        );
-      }
       const session = await provider.waitForSession(timeoutSec * 1e3);
       if (opts.json) {
         output(
@@ -44483,8 +44475,21 @@ var SwapClient = class {
     }
     return transactions;
   }
+  /**
+   * Search Trust's asset index, which covers mainnets only. A testnet shares
+   * its mainnet's coin ID, so querying it would return mainnet assets (and
+   * their decimals) for testnet addresses: testnet chains are left out of the
+   * query, and a search on testnets only has no results.
+   */
   async searchTokens(params) {
-    const coinIds = params.networks ? params.networks : (params.chains ?? mainnetChainKeys()).map(coinIdOf).join(",");
+    let coinIds;
+    if (params.networks) {
+      coinIds = params.networks;
+    } else {
+      const chains = (params.chains ?? mainnetChainKeys()).filter((c3) => !isTestnet(c3));
+      if (chains.length === 0) return [];
+      coinIds = chains.map(coinIdOf).join(",");
+    }
     const queryParams = new URLSearchParams({
       networks: coinIds,
       exactQuery: params.query,
@@ -44837,7 +44842,7 @@ function registerTransferCommand(program3) {
     "Chain key (e.g., base, ethereum). When set, --token is a token contract address; omit --token to send the native coin."
   ).option(
     "--decimals <n>",
-    "Token decimals (overrides auto-resolution for tokens not in the registry)"
+    "Token decimals, only for a token twak does not know (rejected if it contradicts the registry or token search)"
   ).option(
     "--confirm-to <address>",
     "Pin the expected resolved address \u2014 transfer is rejected if resolution returns a different address"
@@ -44943,7 +44948,7 @@ init_dist();
 function registerSwapCommand(program3) {
   attachPaymasterOption(program3.command("swap")).description("Quote or execute a token swap").argument("<amountOrFrom>", "Amount to swap, or source token when using --usd").argument("<fromOrTo>", "Source token, or destination token when using --usd").argument("[to]", "Destination token (omit when using --usd with 2 args)").option("--chain <id>", "Chain", "ethereum").option("--to-chain <id>", "Destination chain (for cross-chain swaps)").option("--slippage <pct>", "Slippage tolerance %", "1").option(
     "--decimals <n>",
-    "Source token decimals (overrides auto-resolution for tokens not in the registry)"
+    "Source token decimals, only for a token twak does not know (rejected if it contradicts the registry or token search)"
   ).option("--usd <amount>", "Swap a USD-equivalent amount of the source token").option("--quote-only", "Get quote without executing").option("--password <password>", "Wallet password (required to execute)").option("--json", "JSON output").action(
     async (amountOrFrom, fromOrTo, toOrUndefined, opts) => {
       try {
@@ -47168,7 +47173,6 @@ var import_zod11 = require("zod");
 init_dist();
 var import_zod12 = require("zod");
 init_dist();
-init_dist4();
 var import_zod13 = require("zod");
 init_dist();
 var import_zod14 = require("zod");
@@ -48002,9 +48006,34 @@ var ActionProvider = class {
 var ActionRegistry = class {
   providers = [];
   actions = /* @__PURE__ */ new Map();
+  withheld = /* @__PURE__ */ new Set();
+  readOnly;
+  constructor(options = {}) {
+    this.readOnly = options.readOnly ?? false;
+  }
+  /**
+   * Throws when an action name is already registered (served or withheld) or
+   * repeated within the provider: two actions under one name is a wiring bug,
+   * and letting one silently replace the other would change what a tool name
+   * does without notice. Nothing is registered when it throws.
+   */
   register(provider) {
+    const actions = provider.getActions();
+    const seen = /* @__PURE__ */ new Set();
+    for (const { name: name2 } of actions) {
+      if (seen.has(name2) || this.actions.has(name2) || this.withheld.has(name2)) {
+        throw new Error(
+          `Action "${name2}" from provider "${provider.name}" is already registered; action names must be unique.`
+        );
+      }
+      seen.add(name2);
+    }
     this.providers.push(provider);
-    for (const action of provider.getActions()) {
+    for (const action of actions) {
+      if (this.readOnly && !action.annotations.readOnly) {
+        this.withheld.add(action.name);
+        continue;
+      }
       this.actions.set(action.name, action);
     }
   }
@@ -48015,12 +48044,32 @@ var ActionRegistry = class {
   getAction(name2) {
     return this.actions.get(name2);
   }
+  /**
+   * The error for a call to an action that read-only mode withheld, so the
+   * caller learns why instead of seeing an unknown action. Undefined for any
+   * other name.
+   */
+  withheldError(name2) {
+    if (!this.withheld.has(name2)) return void 0;
+    return {
+      code: "READ_ONLY",
+      message: `${name2} is not available: this server is read-only (twak serve --read-only) and serves only tools that read. Restart it without --read-only to use ${name2}.`
+    };
+  }
   getProviders() {
     return this.providers;
   }
 };
 var CHAIN_DESC = 'Chain (e.g., "ethereum", "bsc", "solana"). Accepts chain key, CAIP-2 ("eip155:1"), EVM chainId ("56", "0x38"), aliases ("matic", "op"), and asset IDs ("c60").';
 var TOKEN_ADDR_DESC = "Token contract address (ERC-20 / SPL). Omit for the chain native coin (ETH, BNB, SOL, etc.).";
+var READS_REMOTE = { readOnly: true, openWorld: true };
+var READS_LOCAL = { readOnly: true, openWorld: false };
+var SIGNS = {
+  readOnly: false,
+  destructive: true,
+  idempotent: false,
+  openWorld: true
+};
 var BalanceActionProvider = class extends ActionProvider {
   name = "balance";
   description = "Check token balances and holdings";
@@ -48030,6 +48079,7 @@ var BalanceActionProvider = class extends ActionProvider {
   getBalance() {
     return {
       name: "get_balance",
+      annotations: READS_REMOTE,
       description: 'Read the on-chain balance of a single asset for a wallet address. Omit `tokenAddress` for the chain native coin (ETH, BNB, SOL, BTC, ...). Provide `tokenAddress` to read an ERC-20 / SPL token (e.g. tokenAddress="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" with chain="base" for USDC on Base).',
       schema: import_zod3.z.object({
         address: import_zod3.z.string().describe("Wallet address on the specified chain."),
@@ -48045,6 +48095,7 @@ var BalanceActionProvider = class extends ActionProvider {
   getTokenHoldings() {
     return {
       name: "get_token_holdings",
+      annotations: READS_REMOTE,
       description: "Get ERC-20 / SPL token holdings for a wallet address on a chain. Returns the list of tokens the address holds. Omit `tokenAddress` to list all token holdings on the chain.",
       schema: import_zod3.z.object({
         address: import_zod3.z.string().describe("Wallet address on the specified chain."),
@@ -48092,6 +48143,7 @@ var BalanceActionProvider = class extends ActionProvider {
   searchAssets() {
     return {
       name: "search_assets",
+      annotations: READS_REMOTE,
       description: "Search for tokens by name, symbol, or address",
       schema: import_zod3.z.object({
         query: import_zod3.z.string().describe("Search query"),
@@ -48133,6 +48185,7 @@ var TransferActionProvider = class extends ActionProvider {
   transfer() {
     return {
       name: "transfer",
+      annotations: SIGNS,
       description: 'Transfer native or ERC-20 tokens to a destination address. Resolves ENS for the "to" field, applies a USD safety cap, and works with both the local agent wallet (any supported chain \u2014 EVM, Solana, Bitcoin, \u2026) and an external WalletConnect-paired wallet (EVM chains only).',
       schema: import_zod4.z.object({
         chain: import_zod4.z.string().describe(CHAIN_DESC),
@@ -48140,7 +48193,7 @@ var TransferActionProvider = class extends ActionProvider {
         amount: import_zod4.z.string().describe('Amount in human-readable format (e.g., "1.5", "0.01")'),
         tokenAddress: import_zod4.z.string().trim().min(1).optional().describe(TOKEN_ADDR_DESC),
         decimals: import_zod4.z.coerce.number().int().min(0).max(36).optional().describe(
-          "Token decimals (non-negative integer). Omit for native coins and for tokens twak recognizes \u2014 decimals are derived from the registry or token search. REQUIRED when tokenAddress is a contract twak does not recognize; look up the value on the token contract."
+          "Token decimals, only for a token twak does not know. Omit it otherwise: twak resolves decimals from its registry or the Trust token search, and rejects a value that contradicts them. Needed only when the transfer fails asking for decimals."
         ),
         memo: import_zod4.z.string().optional().describe("Optional memo/note (local agent wallet only)."),
         confirmTo: import_zod4.z.string().optional().describe(
@@ -48201,6 +48254,7 @@ var SwapActionProvider = class extends ActionProvider {
   swap() {
     return {
       name: "swap",
+      annotations: SIGNS,
       description: "Execute a token swap via Trust Wallet (supports all chains including cross-chain)",
       schema: import_zod5.z.object({
         fromChain: import_zod5.z.string().describe(`Source chain. ${CHAIN_DESC}`),
@@ -48278,6 +48332,7 @@ var SwapActionProvider = class extends ActionProvider {
   getSwapQuote() {
     return {
       name: "get_swap_quote",
+      annotations: READS_REMOTE,
       description: "Get a swap quote without executing",
       schema: import_zod5.z.object({
         fromChain: import_zod5.z.string().describe(`Source chain. ${CHAIN_DESC}`),
@@ -48346,6 +48401,7 @@ var SwapActionProvider = class extends ActionProvider {
   getTokenPrice() {
     return {
       name: "get_token_price",
+      annotations: READS_REMOTE,
       description: "Get current USD price for a token",
       schema: import_zod5.z.object({
         chain: import_zod5.z.string().describe(CHAIN_DESC),
@@ -48398,6 +48454,7 @@ var SecurityActionProvider = class extends ActionProvider {
   validateTransaction() {
     return {
       name: "validate_transaction",
+      annotations: READS_REMOTE,
       description: "Validate an address or transaction for security. Provide `chain` (and optional `tokenAddress`) to scope the validation to a specific asset; omit both for a generic address check.",
       schema: import_zod6.z.object({
         address: import_zod6.z.string().describe("Address to validate"),
@@ -48421,6 +48478,7 @@ var SecurityActionProvider = class extends ActionProvider {
   getAssetInfo() {
     return {
       name: "get_asset_info",
+      annotations: READS_REMOTE,
       description: "Get detailed information about an asset (name, symbol, price, market cap). Omit `tokenAddress` for the chain native coin.",
       schema: import_zod6.z.object({
         chain: import_zod6.z.string().describe(CHAIN_DESC),
@@ -48449,6 +48507,7 @@ var HistoryActionProvider = class extends ActionProvider {
   getTransactionHistory() {
     return {
       name: "get_transaction_history",
+      annotations: READS_REMOTE,
       description: "Get transaction history for an address",
       schema: import_zod7.z.object({
         address: import_zod7.z.string().describe("Wallet address"),
@@ -48466,6 +48525,7 @@ var HistoryActionProvider = class extends ActionProvider {
   getTransactionDetails() {
     return {
       name: "get_transaction_details",
+      annotations: READS_REMOTE,
       description: "Get details of a specific transaction by hash",
       schema: import_zod7.z.object({
         hash: import_zod7.z.string().describe("Transaction hash"),
@@ -48482,6 +48542,7 @@ var HistoryActionProvider = class extends ActionProvider {
   getSwapHistory() {
     return {
       name: "get_swap_history",
+      annotations: READS_REMOTE,
       description: "Get swap transaction history",
       schema: import_zod7.z.object({
         address: import_zod7.z.string().describe("Wallet address"),
@@ -48509,6 +48570,7 @@ var AlertActionProvider = class extends ActionProvider {
   createAlert() {
     return {
       name: "create_alert",
+      annotations: { readOnly: false, destructive: false, idempotent: false, openWorld: false },
       description: "Create a price alert. Triggers when the asset price crosses a target. Omit `tokenAddress` to watch the chain native coin (ETH, BNB, SOL, etc.).",
       schema: import_zod8.z.object({
         chain: import_zod8.z.string().describe(CHAIN_DESC),
@@ -48535,6 +48597,7 @@ var AlertActionProvider = class extends ActionProvider {
   listAlerts() {
     return {
       name: "list_alerts",
+      annotations: READS_LOCAL,
       description: "List all price alerts",
       schema: import_zod8.z.object({
         activeOnly: import_zod8.z.boolean().optional().default(false).describe("Only show active alerts")
@@ -48549,6 +48612,9 @@ var AlertActionProvider = class extends ActionProvider {
   checkAlerts() {
     return {
       name: "check_alerts",
+      // Destructive: an alert that fires is deactivated, so later checks and
+      // the watcher no longer evaluate it.
+      annotations: { readOnly: false, destructive: true, idempotent: false, openWorld: true },
       description: "Check active alerts against current prices and trigger any that match",
       schema: import_zod8.z.object({}),
       invoke: async (ctx, _input) => {
@@ -48578,6 +48644,7 @@ var AlertActionProvider = class extends ActionProvider {
   deleteAlert() {
     return {
       name: "delete_alert",
+      annotations: { readOnly: false, destructive: true, idempotent: true, openWorld: false },
       description: "Delete a price alert by ID",
       schema: import_zod8.z.object({
         id: import_zod8.z.string().describe("Alert ID to delete")
@@ -48608,6 +48675,7 @@ var AgentWalletActionProvider = class extends ActionProvider {
   getAddress() {
     return {
       name: "get_address",
+      annotations: READS_LOCAL,
       description: "Get the active wallet's address for a specific chain.",
       schema: import_zod9.z.object({
         chain: import_zod9.z.string().describe(CHAIN_DESC)
@@ -48623,6 +48691,7 @@ var AgentWalletActionProvider = class extends ActionProvider {
   listAddresses() {
     return {
       name: "list_addresses",
+      annotations: READS_LOCAL,
       description: "Get the active wallet's addresses for every supported chain. Returns one address per chain.",
       schema: import_zod9.z.object({}),
       invoke: async () => {
@@ -48638,6 +48707,7 @@ var AgentWalletActionProvider = class extends ActionProvider {
   walletBalance() {
     return {
       name: "wallet_balance",
+      annotations: READS_REMOTE,
       description: "Read the native-coin balance (BNB on BSC, ETH on Ethereum / Base / Arbitrum, SOL on Solana, etc.) for the active wallet on a specific chain. For ERC-20 / SPL token balances, use `get_balance`.",
       schema: import_zod9.z.object({
         chain: import_zod9.z.string().describe(CHAIN_DESC)
@@ -48654,6 +48724,7 @@ var AgentWalletActionProvider = class extends ActionProvider {
   walletPortfolio() {
     return {
       name: "wallet_portfolio",
+      annotations: READS_REMOTE,
       description: "Read the active wallet's full portfolio across chains: native-coin and known-token balances, each with its USD value, plus the total USD. Operates on the active wallet (local HD or WalletConnect-paired) \u2014 takes no address. Native rows are returned for every queried chain (even at zero balance); zero-balance token rows are omitted. Use `wallet_balance` for a single native balance or `get_balance` for one specific token.",
       schema: import_zod9.z.object({
         chains: import_zod9.z.string().optional().describe(
@@ -48689,6 +48760,7 @@ var TokenActionProvider = class extends ActionProvider {
   tokenBalance() {
     return {
       name: "token_balance",
+      annotations: READS_REMOTE,
       description: "Get balance for a specific token or native asset on a chain.",
       schema: import_zod10.z.object({
         chain: import_zod10.z.string().describe(CHAIN_DESC),
@@ -48708,6 +48780,7 @@ var TokenActionProvider = class extends ActionProvider {
   approveToken() {
     return {
       name: "approve_token",
+      annotations: SIGNS,
       description: `Approve a spender to use ERC-20 tokens on your behalf. SAFETY: when amount is "unlimited" (or the MaxUint256 decimal string), you MUST surface the risk to the user and get their explicit consent before calling this tool \u2014 unlimited approvals grant the spender access to ALL of the user's tokens of this type, including future transfers, and have been used in many drainer attacks. Prefer a finite amount equal to the immediate need. Use revoke_token_approval (or amount: "0") to revoke an existing approval.`,
       schema: import_zod10.z.object({
         chain: import_zod10.z.string().describe(CHAIN_DESC),
@@ -48739,6 +48812,7 @@ var TokenActionProvider = class extends ActionProvider {
   revokeTokenApproval() {
     return {
       name: "revoke_token_approval",
+      annotations: SIGNS,
       description: "Revoke an ERC-20 token approval by setting the spender allowance to 0. Use this to remove a previously-granted allowance \u2014 especially important after unlimited approvals or any approval you no longer need. This is the inverse of approve_token.",
       schema: import_zod10.z.object({
         chain: import_zod10.z.string().describe(CHAIN_DESC),
@@ -48768,6 +48842,7 @@ var TokenActionProvider = class extends ActionProvider {
   checkAllowance() {
     return {
       name: "check_allowance",
+      annotations: READS_REMOTE,
       description: "Check the ERC-20 allowance for a spender address.",
       schema: import_zod10.z.object({
         chain: import_zod10.z.string().describe(CHAIN_DESC),
@@ -48808,6 +48883,7 @@ var MarketActionProvider = class extends ActionProvider {
   getTrendingTokens() {
     return {
       name: "get_trending_tokens",
+      annotations: READS_REMOTE,
       description: "Get a list of trending tokens by market activity",
       schema: import_zod11.z.object({
         limit: import_zod11.z.coerce.number().optional().default(20).describe("Number of tokens to return (default 20)")
@@ -48821,6 +48897,7 @@ var MarketActionProvider = class extends ActionProvider {
   checkTokenRisk() {
     return {
       name: "check_token_risk",
+      annotations: READS_REMOTE,
       description: "Check security and risk information for a token (honeypot detection, audit status, freeze authority). Omit `tokenAddress` to check the chain native coin.",
       schema: import_zod11.z.object({
         chain: import_zod11.z.string().describe(CHAIN_DESC),
@@ -48850,7 +48927,7 @@ var MarketActionProvider = class extends ActionProvider {
   }
 };
 var DEFAULT_MAX_OFFRAMP_USD = 1e4;
-function validateOfframpInput(input2, chainKey, nativeDecimals) {
+function validateOfframpInput(input2) {
   if (!isEvmAddress(input2.depositAddress)) {
     throw new TransferError(
       "VALIDATION_ERROR",
@@ -48860,42 +48937,11 @@ function validateOfframpInput(input2, chainKey, nativeDecimals) {
   if (input2.tokenAddress && !isEvmAddress(input2.tokenAddress)) {
     throw new TransferError("VALIDATION_ERROR", `Malformed tokenAddress: ${input2.tokenAddress}`);
   }
-  let decimals;
-  if (input2.tokenAddress) {
-    if (input2.decimals === void 0) {
-      throw new TransferError(
-        "VALIDATION_ERROR",
-        `decimals is required for ERC-20 token ${input2.tokenAddress} on ${chainKey}. Pass the token's decimals explicitly (6 for USDC/USDT, 18 for DAI, etc.) \u2014 silently defaulting to 18 could over-pay the provider by orders of magnitude.`
-      );
-    }
-    decimals = input2.decimals;
-  } else {
-    decimals = nativeDecimals;
-  }
   try {
-    assertStrictPositiveAmount(input2.cryptoAmount, decimals);
+    assertStrictPositiveAmount(input2.cryptoAmount);
   } catch (err) {
     throw new TransferError("VALIDATION_ERROR", errorMessage(err));
   }
-  return decimals;
-}
-async function checkOfframpUsdCap(priceLookup, maxUsd, chainKey, tokenAddress, cryptoAmount) {
-  try {
-    const tokenInfo = tokenAddress ? resolveToken(tokenAddress, chainKey) : void 0;
-    const lookupAddress2 = tokenInfo?.address ?? tokenAddress ?? "";
-    const price = await priceLookup.getTokenPrice(chainKey, lookupAddress2);
-    if (price && price > 0) {
-      const usdValue = parseFloat(cryptoAmount) * price;
-      if (usdValue > maxUsd) {
-        return {
-          code: "USD_LIMIT_EXCEEDED",
-          message: `Off-ramp payout value ~$${usdValue.toFixed(2)} USD exceeds safety limit of $${maxUsd}. Use the CLI with --max-usd ${Math.ceil(usdValue)} or --skip-safety-check to proceed.`
-        };
-      }
-    }
-  } catch {
-  }
-  return void 0;
 }
 function buildFollowUp(chain2, tokenAddress, address, direction, paymentMethod) {
   if (!chain2) return void 0;
@@ -48953,19 +48999,16 @@ var OnrampActionProvider = class extends ActionProvider {
   // transfer/swap/erc20 actions already follow. Explicit `walletAddress`
   // overrides the derivation for agents operating on behalf of other users.
   //
-  // `priceLookup` + `maxTransferUsd` enable the same USD safety cap used by
-  // TransferActionProvider for the off-ramp payout path (confirm_offramp_transfer).
-  // Off-ramp sends crypto to a third-party deposit address, so the cap is
-  // strictly more important here than for peer-to-peer transfers.
-  // `blockchainClient` is the 4th (optional) arg, not the 1st — see
-  // TransferActionProvider for the rationale (avoid churning ~70 test sites).
-  // Normalize across action providers in a follow-up.
-  constructor(walletContext, priceLookup, maxTransferUsd = DEFAULT_MAX_OFFRAMP_USD, blockchainClient) {
+  // The off-ramp payout (confirm_offramp_transfer) goes through the same
+  // TransferExecutor as `transfer`: `swapClient` resolves the token's decimals
+  // and price, and `maxTransferUsd` caps the payout. Off-ramp sends crypto to
+  // a third-party deposit address, so the cap matters even more here than for
+  // peer-to-peer transfers.
+  constructor(walletContext, swapClient, maxTransferUsd = DEFAULT_MAX_OFFRAMP_USD) {
     super();
     this.walletContext = walletContext;
-    this.priceLookup = priceLookup;
+    this.swapClient = swapClient;
     this.maxTransferUsd = maxTransferUsd;
-    this.blockchainClient = blockchainClient;
   }
   name = "onramp";
   description = "Fiat on-ramp and off-ramp \u2014 buy crypto with fiat (USD, EUR, etc.) or sell crypto for fiat payouts. On-ramp: two-step flow (get quote \u2192 get checkout URL), provider sends crypto to the destination address. Off-ramp: three-step flow (get quote \u2192 get checkout URL \u2192 confirm_offramp_transfer). The off-ramp checkout URL runs in a plain browser which has no access to wallet keys, so the payout transaction must be broadcast natively via confirm_offramp_transfer once the user has read the provider's deposit address and exact amount. Destination/source address auto-derives from the configured wallet using the asset's chain. IMPORTANT: TWAK has no background polling or completion webhook for ramps. Tool responses include a `followUp` hint telling the agent exactly which balance tool to poll (with args and timing) to observe completion.";
@@ -48991,6 +49034,7 @@ var OnrampActionProvider = class extends ActionProvider {
   getOnrampQuote() {
     return {
       name: "get_onramp_quote",
+      annotations: READS_REMOTE,
       description: "Step 1 of buying crypto with fiat: get quotes from available payment providers (MoonPay, Transak, etc.) for a given fiat amount. Returns an array of quotes each with a quoteId \u2014 pass one to get_onramp_url to generate the checkout redirect.",
       schema: import_zod12.z.object({
         fiatAmount: import_zod12.z.coerce.number().positive().describe("Amount of fiat currency to spend (e.g., 100 for $100)."),
@@ -49032,6 +49076,7 @@ var OnrampActionProvider = class extends ActionProvider {
   getOnrampUrl() {
     return {
       name: "get_onramp_url",
+      annotations: READS_REMOTE,
       description: "Step 2 of buying crypto with fiat: exchange a quoteId from get_onramp_quote for a browser redirect URL. The user opens that URL to complete KYC and payment with the provider; on success, the provider sends the purchased crypto to the destination address. After this tool returns a URL, poll the balance tool named in the `followUp` field to observe the incoming funds \u2014 there is no background polling, webhook, or push notification.",
       schema: import_zod12.z.object({
         quoteId: import_zod12.z.string().describe("Quote ID returned by get_onramp_quote."),
@@ -49082,6 +49127,7 @@ var OnrampActionProvider = class extends ActionProvider {
   getOfframpQuote() {
     return {
       name: "get_offramp_quote",
+      annotations: READS_REMOTE,
       description: "Step 1 of selling crypto for fiat: get quotes from available providers for converting a crypto amount into fiat. Returns an array of quotes each with a quoteId \u2014 pass one to get_offramp_url to generate the checkout redirect for completing KYC and order creation. The provider page cannot sign the payout (no key access in the browser); the agent must broadcast it natively via confirm_offramp_transfer once the deposit address is known.",
       schema: import_zod12.z.object({
         cryptoAmount: import_zod12.z.coerce.number().positive().describe("Amount of crypto to sell (e.g., 0.1 for 0.1 ETH)."),
@@ -49135,6 +49181,7 @@ var OnrampActionProvider = class extends ActionProvider {
   getOfframpUrl() {
     return {
       name: "get_offramp_url",
+      annotations: READS_REMOTE,
       description: "Step 2 of selling crypto for fiat: exchange a quoteId from get_offramp_quote for a browser checkout URL. The user opens that URL to complete KYC and order creation with the provider; the provider then displays a deposit address (plus a memo/tag on chains that require one) and the exact amount to send. The agent must then call confirm_offramp_transfer with those values to sign and broadcast the payout natively \u2014 the browser has no access to wallet keys and cannot sign the transfer itself. After the payout broadcasts, poll the balance tool named in the `followUp` field to observe the outgoing tx. Fiat payout arrives separately via the provider.",
       schema: import_zod12.z.object({
         quoteId: import_zod12.z.string().describe("Quote ID returned by get_offramp_quote."),
@@ -49186,6 +49233,7 @@ var OnrampActionProvider = class extends ActionProvider {
   confirmOfframpTransfer() {
     return {
       name: "confirm_offramp_transfer",
+      annotations: SIGNS,
       description: "Step 3 of selling crypto for fiat: sign and broadcast the payout transaction to the provider's deposit address. Call this AFTER the user has completed KYC in the browser and can read the deposit address + exact amount the provider displayed. Works with any wallet provider that implements sendTransaction (the local agent wallet, or a WalletConnect-paired external wallet). EVM-only \u2014 non-EVM chains (BTC, Solana, Cosmos, etc.) are not supported by this action. Returns a tx hash on success; fiat payout from the provider then arrives separately (no on-chain signal for that step).",
       schema: import_zod12.z.object({
         depositAddress: import_zod12.z.string().describe(
@@ -49198,8 +49246,8 @@ var OnrampActionProvider = class extends ActionProvider {
         tokenAddress: import_zod12.z.string().trim().min(1).optional().describe(
           "ERC-20 token contract address. Omit for the chain native coin. This action is EVM-only \u2014 non-EVM tokens are rejected."
         ),
-        decimals: import_zod12.z.coerce.number().optional().describe(
-          "Token decimals. REQUIRED for ERC-20 assets (pass 6 for USDC/USDT, 18 for DAI, etc.) \u2014 omitting it will be rejected rather than silently defaulting to 18, because a wrong-decimals encode can over-pay the provider by orders of magnitude. Ignored for native coins."
+        decimals: import_zod12.z.coerce.number().int().min(0).max(36).optional().describe(
+          "Token decimals, only for a token twak does not know. Omit it otherwise: twak resolves decimals from its registry or the Trust token search, and rejects a value that contradicts them. Ignored for native coins."
         ),
         memo: import_zod12.z.string().optional().describe(
           "Memo / destination tag. Not used on EVM chains, so supplying one on EVM is a no-op warning. Exists in the schema for forward-compat with non-EVM chains."
@@ -49209,7 +49257,7 @@ var OnrampActionProvider = class extends ActionProvider {
         )
       }),
       invoke: async (_ctx, input2) => {
-        const signer = this.walletContext.activeWallet();
+        const wallet = this.walletContext.activeWallet();
         const { chainKey } = resolveAsset(input2.chain);
         const chainDef = chainOf(chainKey);
         if (chainDef.namespace !== "eip155") {
@@ -49218,48 +49266,30 @@ var OnrampActionProvider = class extends ActionProvider {
             `confirm_offramp_transfer is EVM-only. ${chainKey} is not supported.`
           );
         }
-        const decimals = validateOfframpInput(input2, chainKey, chainDef.decimals);
-        if (this.priceLookup) {
-          const cap = await checkOfframpUsdCap(
-            this.priceLookup,
-            this.maxTransferUsd,
-            chainKey,
-            input2.tokenAddress,
-            input2.cryptoAmount
-          );
-          if (cap) return { success: false, ...cap };
-        }
-        const atomic = parseAmount(input2.cryptoAmount, decimals);
-        let hash;
-        if (input2.tokenAddress) {
-          if (!this.blockchainClient) {
-            throw new TransferError(
-              "WALLET_NOT_FOUND",
-              "Chain client not available \u2014 off-ramp token payout requires a configured blockchain client"
-            );
-          }
-          const pending = await this.blockchainClient.contract(erc20).withAddress(input2.tokenAddress, chainKey).write.transfer([input2.depositAddress, BigInt(atomic)], signer);
-          hash = pending.hash;
-        } else {
-          hash = await signer.sendTransaction({
-            chainKey,
-            to: input2.depositAddress,
-            data: "0x",
-            value: "0x" + BigInt(atomic).toString(16)
-          });
+        validateOfframpInput(input2);
+        const result = await new TransferExecutor({ wallet, swapClient: this.swapClient }).execute({
+          chain: chainKey,
+          to: input2.depositAddress,
+          resolveNames: false,
+          amount: input2.cryptoAmount,
+          tokenAddress: input2.tokenAddress,
+          decimals: input2.decimals,
+          safety: { maxUsd: this.maxTransferUsd }
+        });
+        if (!result.success) {
+          return { success: false, code: result.code, message: result.message };
         }
-        const explorerUrl = getExplorerTxUrl(chainKey, hash) || void 0;
         return {
           success: true,
-          hash,
-          chain: chainKey,
+          hash: result.hash,
+          chain: result.chainKey,
           tokenAddress: input2.tokenAddress,
-          to: input2.depositAddress,
+          to: result.to,
           amount: input2.cryptoAmount,
           memoIgnored: input2.memo ? `A memo was supplied (${input2.memo}) but EVM transactions have no memo field \u2014 it was ignored. If the provider requires a memo, they likely expect a non-EVM chain.` : void 0,
           quoteId: input2.quoteId,
-          explorer: explorerUrl,
-          summary: `Off-ramp payout of ${input2.cryptoAmount}${input2.tokenAddress ? ` ${input2.tokenAddress.slice(0, 10)}\u2026` : ` ${chainDef.symbol}`} broadcast to ${input2.depositAddress} on ${chainKey}. Fiat payout from the provider arrives separately.`
+          explorer: result.explorerUrl,
+          summary: `Off-ramp payout of ${input2.cryptoAmount}${input2.tokenAddress ? ` ${input2.tokenAddress.slice(0, 10)}\u2026` : ` ${chainDef.symbol}`} broadcast to ${result.to} on ${chainKey}. Fiat payout from the provider arrives separately.`
         };
       }
     };
@@ -49287,6 +49317,8 @@ var AutomateActionProvider = class extends ActionProvider {
   createAutomation() {
     return {
       name: "create_automation",
+      // Destructive: the automation later trades with the agent wallet, unattended.
+      annotations: { readOnly: false, destructive: true, idempotent: false, openWorld: false },
       description: "Create a DCA (recurring buy) or limit order (buy/sell when a price condition is met). The rule is saved immediately but only EXECUTES while a watcher is polling \u2014 either this MCP server was started with `twak serve --watch`, or a separate `twak watch` process is running. With no watcher, the rule stays pending and nothing is swapped; use run_automation_now to execute one on demand (only available while no watcher is running). Execution uses the local agent wallet; the watcher stays idle in WalletConnect mode.",
       schema: import_zod13.z.object({
         type: import_zod13.z.enum(["dca", "limit"]).describe("Automation type: dca (recurring) or limit (price trigger)"),
@@ -49336,6 +49368,7 @@ var AutomateActionProvider = class extends ActionProvider {
   listAutomations() {
     return {
       name: "list_automations",
+      annotations: READS_LOCAL,
       description: 'List automation rules (DCA and limit orders). Note: "active" means scheduled, not necessarily firing \u2014 rules only execute while a watcher runs (`twak serve --watch` or `twak watch`).',
       schema: import_zod13.z.object({
         activeOnly: import_zod13.z.boolean().optional().default(true).describe("Only show active automations")
@@ -49351,6 +49384,7 @@ var AutomateActionProvider = class extends ActionProvider {
   deleteAutomation() {
     return {
       name: "delete_automation",
+      annotations: { readOnly: false, destructive: true, idempotent: true, openWorld: false },
       description: "Delete (deactivate) an automation rule",
       schema: import_zod13.z.object({
         id: import_zod13.z.string().describe("Automation ID to delete")
@@ -49368,6 +49402,7 @@ var AutomateActionProvider = class extends ActionProvider {
   runAutomationNow() {
     return {
       name: "run_automation_now",
+      annotations: SIGNS,
       description: "Execute an automation immediately \u2014 runs the swap now regardless of its schedule. Only available while no watcher is running: when this server was started with `serve --watch` the watcher owns execution, the tool is hidden, and invocations are rejected with WATCHER_ACTIVE to prevent double execution.",
       hidden: this.watcherActive,
       schema: import_zod13.z.object({
@@ -49461,7 +49496,11 @@ var X402ActionProvider = class extends ActionProvider {
   x402Quote() {
     return {
       name: "x402_quote",
-      description: 'Preview the payment requirements at an x402 payment-gated endpoint WITHOUT signing or paying. Returns the full list of payment options (each entry has chain, asset address, tokenName, amount, transferMethod, requiresApproval, and a pre-formatted `description` string). CRITICAL \u2014 after this returns, ALWAYS surface ALL entries in `accepts[]` to the user (as a short numbered list: chain \xB7 token \xB7 amount \xB7 method \xB7 "preferred" tag if applicable) and ask which to use BEFORE calling x402_request. Do not silently pick the `preferred` entry just because it is marked preferred \u2014 that is the picker default if no override is passed, but the user deserves to see every option (other chains may have cheaper gas, the user may hold balance only on a specific chain, etc.). The only exception: if you have already done a balance check and only one entry is viable, you may proceed with that one after noting the others as "unavailable (no balance)". IMPORTANT: each entry in `accepts[]` is an INDEPENDENT payment option \u2014 a unique (chain, token, transfer method) triple. Do NOT merge entries by chain (e.g. "BSC USDC via EIP-3009 or Permit2" is wrong if BSC USDC is only offered via Permit2 and a separate BSC entry for a different token offers EIP-3009). Read each entry as its own row; use the per-entry `description` field verbatim when surfacing options to the user. Once the user picks, call x402_request with the agreed maxPaymentAtomic plus optionally preferNetwork/preferMethod/preferAsset to disambiguate. INTERPRETING `requiresApproval`: `false` (EIP-3009, e.g. USDC on Base / Ethereum) \u2014 gasless. Sign the payment and you are done. No setup, no on-chain tx for the buyer, ever. `true` (Permit2, e.g. USDC on BSC) \u2014 the industry-standard Permit2 flow used by Uniswap, 1inch, and most major DeFi apps. THE FIRST x402_request to a Permit2 endpoint for a given token+chain broadcasts a one-time `approve(Permit2, MAX_UINT256)` tx (the buyer pays the gas \u2014 usually a few cents on BSC / Base, more on Ethereum mainnet). The allowance granted is unlimited for the canonical Permit2 contract at 0x000000000022D473030F116dDEE9F6B43aC78BA3. After that, every future Permit2 payment for that token is signature-only (gasless). Revocable any time via `twak erc20 revoke`. The per-call spend is still capped at the request `maxPaymentAtomic` \u2014 unlimited allowance does NOT mean unlimited per-call spend. When `requiresApproval: true` AND the buyer has not used Permit2 for that token on that chain before, the agent SHOULD tell the user concretely what is about to happen (one-time approval on <chain> for <token>, gas paid in the chain native token, then the payment) before calling x402_request. BALANCE CHECK \u2014 AFTER this quote returns and BEFORE recommending any route or showing the menu to the user, check the wallet balance for every viable entry in `accepts`. For each entry: call `get_address(chain)` to find the wallet address on that chain, then `get_balance` for the entry\'s asset (or `wallet_balance(chain)` for native coins). Filter or annotate the menu \u2014 only recommend routes where the wallet has enough of the asset to cover `amount`. If a Permit2 entry needs a first-time approval (`requiresApproval: true`), also confirm the wallet holds some native chain gas (gas amount varies by chain). If no viable route has sufficient balance, tell the user upfront \u2014 do not present a menu that includes routes they cannot pay. This avoids the failure mode where the agent recommends a chain the user has no balance on and the user finds out only after committing. No wallet required \u2014 read-only HTTPS + 402 parse. HTTPS-only; private IPs and non-HTTPS schemes are rejected.',
+      // Not read-only: the request is sent with the caller's method before
+      // any 402 check, so a POST or DELETE to an endpoint that does not ask
+      // for payment runs as a normal request.
+      annotations: { readOnly: false, destructive: true, idempotent: false, openWorld: true },
+      description: 'Preview the payment requirements at an x402 payment-gated endpoint WITHOUT signing or paying. Returns the full list of payment options (each entry has chain, asset address, tokenName, amount, transferMethod, requiresApproval, and a pre-formatted `description` string). CRITICAL \u2014 after this returns, ALWAYS surface ALL entries in `accepts[]` to the user (as a short numbered list: chain \xB7 token \xB7 amount \xB7 method \xB7 "preferred" tag if applicable) and ask which to use BEFORE calling x402_request. Do not silently pick the `preferred` entry just because it is marked preferred \u2014 that is the picker default if no override is passed, but the user deserves to see every option (other chains may have cheaper gas, the user may hold balance only on a specific chain, etc.). The only exception: if you have already done a balance check and only one entry is viable, you may proceed with that one after noting the others as "unavailable (no balance)". IMPORTANT: each entry in `accepts[]` is an INDEPENDENT payment option \u2014 a unique (chain, token, transfer method) triple. Do NOT merge entries by chain (e.g. "BSC USDC via EIP-3009 or Permit2" is wrong if BSC USDC is only offered via Permit2 and a separate BSC entry for a different token offers EIP-3009). Read each entry as its own row; use the per-entry `description` field verbatim when surfacing options to the user. Once the user picks, call x402_request with the agreed maxPaymentAtomic plus optionally preferNetwork/preferMethod/preferAsset to disambiguate. INTERPRETING `requiresApproval`: `false` (EIP-3009, e.g. USDC on Base / Ethereum) \u2014 gasless. Sign the payment and you are done. No setup, no on-chain tx for the buyer, ever. `true` (Permit2, e.g. USDC on BSC) \u2014 the industry-standard Permit2 flow used by Uniswap, 1inch, and most major DeFi apps. THE FIRST x402_request to a Permit2 endpoint for a given token+chain broadcasts a one-time `approve(Permit2, MAX_UINT256)` tx (the buyer pays the gas \u2014 usually a few cents on BSC / Base, more on Ethereum mainnet). The allowance granted is unlimited for the canonical Permit2 contract at 0x000000000022D473030F116dDEE9F6B43aC78BA3. After that, every future Permit2 payment for that token is signature-only (gasless). Revocable any time via `twak erc20 revoke`. The per-call spend is still capped at the request `maxPaymentAtomic` \u2014 unlimited allowance does NOT mean unlimited per-call spend. When `requiresApproval: true` AND the buyer has not used Permit2 for that token on that chain before, the agent SHOULD tell the user concretely what is about to happen (one-time approval on <chain> for <token>, gas paid in the chain native token, then the payment) before calling x402_request. BALANCE CHECK \u2014 AFTER this quote returns and BEFORE recommending any route or showing the menu to the user, check the wallet balance for every viable entry in `accepts`. For each entry: call `get_address(chain)` to find the wallet address on that chain, then `get_balance` for the entry\'s asset (or `wallet_balance(chain)` for native coins). Filter or annotate the menu \u2014 only recommend routes where the wallet has enough of the asset to cover `amount`. If a Permit2 entry needs a first-time approval (`requiresApproval: true`), also confirm the wallet holds some native chain gas (gas amount varies by chain). If no viable route has sufficient balance, tell the user upfront \u2014 do not present a menu that includes routes they cannot pay. This avoids the failure mode where the agent recommends a chain the user has no balance on and the user finds out only after committing. No wallet required: nothing is signed or paid. The request is sent with the given method and body, so a method other than GET can change state on an endpoint that does not answer 402; quote with GET unless the endpoint requires another method. HTTPS-only; private IPs and non-HTTPS schemes are rejected.',
       schema: import_zod14.z.object({
         url: import_zod14.z.string().describe(
           "Target endpoint URL. Must be HTTPS. Resolves via DNS; private/local IPs are rejected."
@@ -49477,6 +49516,7 @@ var X402ActionProvider = class extends ActionProvider {
   x402Request() {
     return {
       name: "x402_request",
+      annotations: SIGNS,
       description: "Make an HTTP request to an x402 payment-gated endpoint. Handles the full flow: sends the initial request, parses any 402 challenge, signs an EIP-3009 or Permit2 payment authorization with the agent wallet, retries with the X-Payment header. PAYMENT METHODS: x402 endpoints offer one or more options in their 402 response. EIP-3009 is gasless for the buyer (no setup, no approval) \u2014 preferred when available, e.g. USDC on Base / Ethereum. Permit2 needs a one-time approve(Permit2, MAX) tx on the chain (the buyer pays the gas \u2014 usually a few cents on BSC / Base, more on Ethereum mainnet), then every future Permit2 payment for that token is signature-only. Permit2 is required when the token does not support EIP-3009 \u2014 e.g. USDC on BSC. SAFETY \u2014 autoApprove decision: When autoApprove=true (default), this action silently broadcasts the one-time Permit2 approval if your wallet has not yet approved the canonical Permit2 contract for that token. The approval is to the same Permit2 contract Uniswap, 1inch, and most major DeFi apps use \u2014 it is not exotic infrastructure. The approval alone does not move funds; each subsequent payment still needs a fresh signature. Revocable any time via `twak erc20 revoke`. For first-time use of an endpoint you SHOULD tell the user concretely what is about to happen (one-time approval on <chain> for <token>, gas paid in the chain native token, then the payment) and get their go-ahead before calling. After the approval lands, subsequent Permit2 payments for that token are free of further approvals. Set autoApprove=false to surface code: 'PERMIT2_APPROVAL_REQUIRED' instead of broadcasting \u2014 useful when the user is not around or you want to handle the approval out-of-band. maxPaymentAtomic is the user's pre-commitment to a maximum payment in the asset's smallest unit (e.g. \"10000\" = 0.01 USDC at 6 decimals). If the server demands more than this cap, the call returns code: 'PAYMENT_AMOUNT_EXCEEDED' \u2014 DO NOT retry with a higher cap without asking the user. BALANCE CHECK \u2014 Before calling this action, verify the wallet holds enough of the chosen asset on the chosen chain. Call `get_address(chain)` to find the wallet address, then `get_balance` for the asset (or `wallet_balance(chain)` for native coins). For Permit2 first-time use, also confirm the wallet holds some native chain gas (amount varies by chain). Surface insufficient balance to the user BEFORE calling this action \u2014 a failed payment mid-flow can leave the wallet in a half-state (e.g. Permit2 approval broadcast, then the transfer signature fails). The balance check should already have happened during the `x402_quote` flow that produced the menu; redo it here only if you skipped quote or the balance might have changed since. WALLET \u2014 Signs through whichever wallet mode is active for this session (local by default; switchable via `switch_wallet_mode`). If mode='local', signs in-process (no external prompt). If mode='walletconnect', signs over the WalletConnect relay \u2014 the user must approve each signature on their paired wallet. To retrieve the active wallet's address for a chain (e.g. to call `wallet_balance` / `get_balance`), call `get_address` with the chain key (e.g. \"bsc\", \"base\"), or `list_addresses` for all chains at once. HTTPS-only; non-HTTPS schemes and private IPs are rejected before any payment signing.",
       schema: import_zod14.z.object({
         url: import_zod14.z.string().describe(
@@ -49591,6 +49631,9 @@ var WalletModeActionProvider = class extends ActionProvider {
   switchWalletMode() {
     return {
       name: "switch_wallet_mode",
+      // Local mode revokes the WalletConnect session; walletconnect mode starts
+      // a pairing through the relay.
+      annotations: { readOnly: false, destructive: true, idempotent: false, openWorld: true },
       description: 'Switch the active wallet mode for this MCP server session. IMPORTANT: the LOCAL agent wallet is auto-bound at server startup when one is configured, so most users do NOT need to call this \u2014 signing actions just work. Call this ONLY when the user explicitly asks to switch. Two flows: (a) user wants to sign on their phone via Trust Wallet (or any WC-compatible wallet) \u2192 mode="walletconnect"; (b) user wants to switch back from WalletConnect to the local wallet \u2192 mode="local". \n\nDISCOVERABILITY: most users do not know WalletConnect is an option. When the user first asks about wallet operations or signing in a fresh conversation, briefly mention that they can optionally switch to signing via Trust Wallet on their phone (more secure: keys never leave their device) by saying so \u2014 then call switch_wallet_mode if they opt in. Do not push it on every signing call; just surface it once early on or when the user expresses security concerns.\n\nFor mode="walletconnect": returns a pairing payload (URI, mobile deep link, inline QR image). Surface the QR to the user, then poll get_wallet_status every few seconds until state leaves "wc-pairing": "wc-connected" means the user approved; "unbound" means the pairing ended, and lastError says why (USER_REJECTED, WC_PAIRING_EXPIRED after about 5 minutes, or WC_PAIRING_FAILED). Do not retry a signing action before "wc-connected". Do NOT call switch_wallet_mode while a signing action is in flight: switching disconnects the prior WC relay session, which can break the in-flight signature; wait for the current action to settle before changing modes.',
       schema: import_zod15.z.object({
         mode: import_zod15.z.enum(["local", "walletconnect"]).describe(
@@ -49617,6 +49660,7 @@ var WalletModeActionProvider = class extends ActionProvider {
   getWalletStatus() {
     return {
       name: "get_wallet_status",
+      annotations: READS_LOCAL,
       description: 'Returns the current wallet binding for this MCP server session: state ("unbound" | "local" | "wc-pairing" | "wc-connected"), wallet type (when bound), peer name (when wc-connected), pairing data (URI / deep link / expiry, when state="wc-pairing"), `lastError` (why the wallet went away or a pairing ended), and `twakHome`: the folder this server keeps its files in (wallet, WalletConnect session, credentials), set from TWAK_HOME when the server started (default ~/.twak). After switch_wallet_mode({mode: "walletconnect"}), poll this every few seconds until state leaves "wc-pairing": "wc-connected" means the user approved and signing actions are usable; "unbound" means the pairing ended without a session, and lastError.code says why: USER_REJECTED (declined in the wallet), WC_PAIRING_EXPIRED (not approved within about 5 minutes) or WC_PAIRING_FAILED. Ask the user before starting a new pairing. While pairing, the response carries `pairing.deepLink` (tap on a phone) and the raw `pairing.uri`. The QR image is returned only with showQr=true: pass it when the user asks to see the QR again (e.g. "show me the QR", "I can\'t see it"), not when polling. Do NOT try to render the QR yourself from the URI or the response JSON.',
       schema: import_zod15.z.object({
         showQr: import_zod15.z.boolean().optional().describe(
@@ -49642,6 +49686,7 @@ var Erc8004ActionProvider = class extends ActionProvider {
   register() {
     return {
       name: "erc8004_register",
+      annotations: SIGNS,
       description: "Mint a new ERC-8004 agent identity on-chain. The caller becomes the owner of an NFT token whose ID is the agentId. The supplied agentURI is stored on-chain as the token URI and should point to the agent registration JSON (https, ipfs, or a data: inline). Optionally pass metadata entries to set them atomically in the same mint transaction.",
       schema: import_zod16.z.object({
         agentURI: import_zod16.z.string().min(1).describe(
@@ -49673,6 +49718,7 @@ var Erc8004ActionProvider = class extends ActionProvider {
   setUri() {
     return {
       name: "erc8004_set_uri",
+      annotations: SIGNS,
       description: "Update the agentURI of an existing ERC-8004 agent identity. Caller must own the NFT.",
       schema: import_zod16.z.object({
         agentId: agentIdSchema,
@@ -49691,6 +49737,7 @@ var Erc8004ActionProvider = class extends ActionProvider {
   setMetadata() {
     return {
       name: "erc8004_set_metadata",
+      annotations: SIGNS,
       description: "Set a metadata entry on an ERC-8004 agent identity. The value is stored on-chain as bytes \u2014 `0x`-prefixed hex inputs are decoded as-is; any other string is UTF-8 encoded.",
       schema: import_zod16.z.object({
         agentId: agentIdSchema,
@@ -49714,6 +49761,7 @@ var Erc8004ActionProvider = class extends ActionProvider {
   getMetadata() {
     return {
       name: "erc8004_get_metadata",
+      annotations: READS_REMOTE,
       description: "Read a metadata entry from an ERC-8004 agent identity. Returns the raw on-chain bytes as a `0x`-prefixed hex string; an unset key returns `0x` (empty bytes).",
       schema: import_zod16.z.object({
         agentId: agentIdSchema,
@@ -49736,6 +49784,7 @@ var Erc8004ActionProvider = class extends ActionProvider {
   show() {
     return {
       name: "erc8004_show",
+      annotations: READS_REMOTE,
       description: "Read the on-chain state of an ERC-8004 agent identity: owner, agentWallet (or null if unset), and agentURI.",
       schema: import_zod16.z.object({
         agentId: agentIdSchema,
@@ -49802,6 +49851,7 @@ var Erc8183ActionProvider = class extends ActionProvider {
   createJob() {
     return {
       name: "erc8183_create_job",
+      annotations: SIGNS,
       description: "Create a new ERC-8183 job. The caller becomes the client. The job starts in `Open` status with no escrow; set a budget then fund it to move it to `Funded`.",
       schema: import_zod17.z.object({
         provider: evmAddressSchema.describe(
@@ -49837,6 +49887,7 @@ var Erc8183ActionProvider = class extends ActionProvider {
   setProvider() {
     return {
       name: "erc8183_set_provider",
+      annotations: SIGNS,
       description: "Set or change the provider (worker) address for a job (client only, while the job is still `Open`). Use the zero address to unset.",
       schema: import_zod17.z.object({
         jobId: jobIdSchema,
@@ -49858,6 +49909,7 @@ var Erc8183ActionProvider = class extends ActionProvider {
   setBudget() {
     return {
       name: "erc8183_set_budget",
+      annotations: SIGNS,
       description: "Set the escrow budget for a job (atomic units of the contract payment token). Does not transfer funds \u2014 call `erc8183_fund` to deposit the budget into escrow.",
       schema: import_zod17.z.object({
         jobId: jobIdSchema,
@@ -49879,6 +49931,7 @@ var Erc8183ActionProvider = class extends ActionProvider {
   fund() {
     return {
       name: "erc8183_fund",
+      annotations: SIGNS,
       description: "Fund a job: deposits the on-chain budget into escrow. The escrow pulls the payment token via transferFrom, so this first sends an ERC-20 approval for the exact budget, then calls fund \u2014 two transactions. Moves the job to `Funded`. Pass `expectedBudget` to pin the amount instead of reading it on-chain.",
       schema: import_zod17.z.object({
         jobId: jobIdSchema,
@@ -49908,6 +49961,7 @@ var Erc8183ActionProvider = class extends ActionProvider {
   submit() {
     return {
       name: "erc8183_submit",
+      annotations: SIGNS,
       description: "Submit a deliverable for a funded job (provider only). The deliverable is a bytes32 commitment (e.g. a content hash). Moves the job to `Submitted`.",
       schema: import_zod17.z.object({
         jobId: jobIdSchema,
@@ -49933,6 +49987,7 @@ var Erc8183ActionProvider = class extends ActionProvider {
   complete() {
     return {
       name: "erc8183_complete",
+      annotations: SIGNS,
       description: "Mark a submitted job complete (evaluator only). Releases escrow: the platform fee goes to the treasury and the remainder to the provider. Moves the job to `Completed`.",
       schema: import_zod17.z.object({
         jobId: jobIdSchema,
@@ -49960,6 +50015,7 @@ var Erc8183ActionProvider = class extends ActionProvider {
   reject() {
     return {
       name: "erc8183_reject",
+      annotations: SIGNS,
       description: "Reject a job (evaluator after submission, or client while still Open). Refunds the client if the job was funded. Moves the job to `Rejected`.",
       schema: import_zod17.z.object({
         jobId: jobIdSchema,
@@ -49987,6 +50043,7 @@ var Erc8183ActionProvider = class extends ActionProvider {
   claimRefund() {
     return {
       name: "erc8183_claim_refund",
+      annotations: SIGNS,
       description: "Claim a refund for an expired job (client only, after the job has passed its expiry without completion). Returns the escrowed budget to the client.",
       schema: import_zod17.z.object({
         jobId: jobIdSchema,
@@ -50008,6 +50065,7 @@ var Erc8183ActionProvider = class extends ActionProvider {
   status() {
     return {
       name: "erc8183_status",
+      annotations: READS_REMOTE,
       description: "Read the on-chain state of a job: client, provider, evaluator, description, budget, status, expiry, submission, deliverable, and the contract payment token.",
       schema: import_zod17.z.object({
         jobId: jobIdSchema,
@@ -50038,6 +50096,7 @@ var Erc8183ActionProvider = class extends ActionProvider {
   policyInfo() {
     return {
       name: "erc8183_policy_info",
+      annotations: READS_REMOTE,
       description: "Read the dispute-policy state of a job: the registered policy address, dispute window, submission time, dispute/vote tallies, and when the job becomes settleable (submittedAt + disputeWindow). Use before `erc8183_settle` to check timing, and before `erc8183_dispute`/`erc8183_vote_reject` to avoid opaque reverts.",
       schema: import_zod17.z.object({
         jobId: jobIdSchema,
@@ -50067,6 +50126,7 @@ var Erc8183ActionProvider = class extends ActionProvider {
   registerJob() {
     return {
       name: "erc8183_register_job",
+      annotations: SIGNS,
       description: "Register a job with a dispute policy via the EvaluatorRouter. Defaults to the deployed OptimisticPolicy when no policy address is given.",
       schema: import_zod17.z.object({
         jobId: jobIdSchema,
@@ -50083,6 +50143,7 @@ var Erc8183ActionProvider = class extends ActionProvider {
   settle() {
     return {
       name: "erc8183_settle",
+      annotations: SIGNS,
       description: "Settle a job through its registered policy via the EvaluatorRouter, finalising the outcome (release or refund) based on the policy verdict.",
       schema: import_zod17.z.object({
         jobId: jobIdSchema,
@@ -50099,6 +50160,7 @@ var Erc8183ActionProvider = class extends ActionProvider {
   markExpired() {
     return {
       name: "erc8183_mark_expired",
+      annotations: SIGNS,
       description: "Finalise a registered job that has passed its expiry without completion, via the EvaluatorRouter (permissionless). Moves the job to `Expired`, after which the client can claim a refund.",
       schema: import_zod17.z.object({
         jobId: jobIdSchema,
@@ -50115,6 +50177,7 @@ var Erc8183ActionProvider = class extends ActionProvider {
   dispute() {
     return {
       name: "erc8183_dispute",
+      annotations: SIGNS,
       description: "Raise a dispute on a job via the OptimisticPolicy (client only, within the dispute window). Opens the job to voter rejection.",
       schema: import_zod17.z.object({
         jobId: jobIdSchema,
@@ -50130,6 +50193,7 @@ var Erc8183ActionProvider = class extends ActionProvider {
   voteReject() {
     return {
       name: "erc8183_vote_reject",
+      annotations: SIGNS,
       description: "Cast a reject vote on a disputed job via the OptimisticPolicy (whitelisted voters only). When the reject quorum is reached the job is rejected.",
       schema: import_zod17.z.object({
         jobId: jobIdSchema,
@@ -50172,6 +50236,8 @@ var CompetitionActionProvider = class extends ActionProvider {
   register() {
     return {
       name: "competition_register",
+      // Idempotent: once registered, it returns without sending a transaction.
+      annotations: { readOnly: false, destructive: true, idempotent: true, openWorld: true },
       description: "Register the agent wallet for BNB HACK: AI TRADING AGENT EDITION on BSC. Registers the agent's own signing wallet (msg.sender). Idempotent \u2014 if already registered, returns success without sending a transaction. Fails if the registration window is not open (before it opens or after the deadline).",
       schema: import_zod18.z.object({}),
       invoke: async () => {
@@ -50228,6 +50294,7 @@ var CompetitionActionProvider = class extends ActionProvider {
   status() {
     return {
       name: "competition_status",
+      annotations: READS_REMOTE,
       description: "Check whether the agent wallet is registered for BNB HACK: AI TRADING AGENT EDITION, when registration opens and closes, and whether the window is currently open.",
       schema: import_zod18.z.object({}),
       invoke: async () => {
@@ -54910,6 +54977,27 @@ When the user first engages with signing operations in a fresh conversation, bri
 To switch mid-session, call \`switch_wallet_mode\`. The new mode applies to subsequent calls; in-flight signing keeps using its captured wallet. A WalletConnect session is stored on disk and resumed when the server restarts, until it expires (about 7 days) or is revoked; choosing local mode revokes it.
 
 If a tool returns CREDENTIALS_MISSING, the Trust Wallet API credentials are not set up yet: ask the user to run \`twak init\` (or \`twak setup\`) with their access ID and HMAC secret. The tools work as soon as the credentials are saved; no server restart is needed.`;
+var READ_ONLY_SERVER_INSTRUCTIONS = `This twak server is read-only (\`twak serve --read-only\`): it serves only tools that read, such as prices, quotes, balances, history and wallet addresses. It cannot sign, send, swap, approve, or change alerts, automations or the wallet mode; calling such a tool returns READ_ONLY. To do any of that, the user restarts \`twak serve\` without --read-only.
+
+The wallet was chosen when the server started: the WalletConnect session resumed from a previous pairing if there was one, otherwise the local agent wallet. Wallet reads (get_address, list_addresses, wallet_balance, ...) use its addresses, and get_wallet_status shows which one it is. To read another wallet, the user pairs it with \`twak wallet connect\` (or switches back to the local wallet) and restarts the server. If a tool returns WALLET_NOT_BOUND or the WalletConnect session ended, tell the user that; switch_wallet_mode is not available on this server.
+
+If a tool returns CREDENTIALS_MISSING, the Trust Wallet API credentials are not set up yet: ask the user to run \`twak init\` (or \`twak setup\`) with their access ID and HMAC secret. The tools work as soon as the credentials are saved; no server restart is needed.`;
+function toToolAnnotations(annotations) {
+  if (annotations.readOnly) {
+    return {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: annotations.openWorld
+    };
+  }
+  return {
+    readOnlyHint: false,
+    destructiveHint: annotations.destructive,
+    idempotentHint: annotations.idempotent,
+    openWorldHint: annotations.openWorld
+  };
+}
 var TwakMcpServer = class {
   server;
   registry;
@@ -54921,7 +55009,10 @@ var TwakMcpServer = class {
     this.beforeInvoke = options.beforeInvoke;
     this.server = new Server(
       { name: "twak", version: "0.1.0" },
-      { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
+      {
+        capabilities: { tools: {} },
+        instructions: registry.readOnly ? READ_ONLY_SERVER_INSTRUCTIONS : SERVER_INSTRUCTIONS
+      }
     );
     this.setupHandlers();
   }
@@ -54932,7 +55023,8 @@ var TwakMcpServer = class {
         tools: actions.map((action) => ({
           name: action.name,
           description: action.description,
-          inputSchema: zodToJsonSchema(action.schema)
+          inputSchema: zodToJsonSchema(action.schema),
+          annotations: toToolAnnotations(action.annotations)
         }))
       };
     });
@@ -54940,16 +55032,12 @@ var TwakMcpServer = class {
       const { name: name2, arguments: args } = request.params;
       const action = this.registry.getAction(name2);
       if (!action) {
+        const payload = this.registry.withheldError(name2) ?? {
+          code: "VALIDATION_ERROR",
+          message: `Unknown tool: ${name2}`
+        };
         return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                code: "VALIDATION_ERROR",
-                message: `Unknown tool: ${name2}`
-              })
-            }
-          ],
+          content: [{ type: "text", text: JSON.stringify(payload) }],
           isError: true
         };
       }
@@ -55111,7 +55199,11 @@ var TwakRestServer = class {
       res.writeHead(200);
       res.end(
         JSON.stringify({
-          actions: actions.map((a3) => ({ name: a3.name, description: a3.description }))
+          actions: actions.map((a3) => ({
+            name: a3.name,
+            description: a3.description,
+            annotations: a3.annotations
+          }))
         })
       );
       return;
@@ -55125,9 +55217,12 @@ var TwakRestServer = class {
     const actionName = match[1];
     const action = this.registry.getAction(actionName);
     if (!action) {
-      res.writeHead(404);
+      const withheld = this.registry.withheldError(actionName);
+      res.writeHead(withheld ? 403 : 404);
       res.end(
-        JSON.stringify({ code: "VALIDATION_ERROR", message: `Unknown action: ${actionName}` })
+        JSON.stringify(
+          withheld ?? { code: "VALIDATION_ERROR", message: `Unknown action: ${actionName}` }
+        )
       );
       return;
     }
@@ -55262,8 +55357,16 @@ function registerServeCommand(program3) {
     "--watch-interval <duration>",
     "Automation poll interval when --watch is set \u2014 e.g. 30s, 5m, 1h (min 5s)",
     "60"
+  ).option(
+    "--read-only",
+    "Serve only tools that read (prices, quotes, balances, history, addresses); tools that sign or change state are not listed and cannot be called"
   ).action(async (opts) => {
     if (!opts.rest) routeConsoleToStderr();
+    if (opts.readOnly && opts.watch) {
+      error("--read-only cannot be combined with --watch: the watcher signs automations");
+      process.exit(1);
+      return;
+    }
     let autoLockMinutes;
     if (opts.autoLock) {
       autoLockMinutes = parseInt(opts.autoLock, 10);
@@ -55335,7 +55438,7 @@ function registerServeCommand(program3) {
         warn(`${errorMessage(err)} Tool calls report this error until it is resolved.`);
       }
     }
-    const registry = new ActionRegistry();
+    const registry = new ActionRegistry({ readOnly: Boolean(opts.readOnly) });
     registry.register(new BalanceActionProvider());
     registry.register(
       new WalletModeActionProvider({ walletContext, agentWallet: () => walletLoader.load() })
@@ -55348,9 +55451,7 @@ function registerServeCommand(program3) {
     registry.register(new AgentWalletActionProvider(walletContext));
     registry.register(new TokenActionProvider(chainClient, walletContext));
     registry.register(new MarketActionProvider());
-    registry.register(
-      new OnrampActionProvider(walletContext, swapClient, void 0, chainClient)
-    );
+    registry.register(new OnrampActionProvider(walletContext, swapClient));
     registry.register(
       new AutomateActionProvider(
         automationStore,
@@ -55430,7 +55531,7 @@ function registerServeCommand(program3) {
       const mcpServer = new TwakMcpServer(registry, context, {
         beforeInvoke: () => bootstrap.ensureReady()
       });
-      console.error("TW Agent MCP server starting...");
+      console.error(`TW Agent MCP server starting${opts.readOnly ? " (read-only)" : ""}...`);
       await mcpServer.start();
     }
   });
@@ -55734,6 +55835,9 @@ ${url}`);
   ).requiredOption("--asset <id>", "Crypto asset ID being sold (e.g., c60 for ETH, c0 for BTC)").requiredOption("--to <address>", "Deposit address shown by the provider after KYC").requiredOption(
     "--amount <n>",
     "Exact amount to send, in human-readable format (must match the amount the provider displays)"
+  ).option(
+    "--decimals <n>",
+    "Token decimals, only for a token twak does not know (rejected if it contradicts the registry or token search)"
   ).option(
     "--memo <tag>",
     "Memo / destination tag required by some chains (Cosmos, XRP, Stellar, BNB Beacon). Include this when the provider displays one \u2014 funds can be unrecoverable without it."
@@ -55764,72 +55868,47 @@ ${url}`);
           `Unsupported coin type in asset ID: ${opts.asset}`
         );
       }
-      const parsedAmount = parseFloat(opts.amount);
-      if (!Number.isFinite(parsedAmount) || parsedAmount <= 0) {
-        throw new TransferError("VALIDATION_ERROR", "--amount must be a positive number");
-      }
-      const httpClient = await getClient();
-      let decimals;
-      try {
-        const assetInfo = await new SecurityService(httpClient).getAssetInfo(opts.asset);
-        decimals = assetInfo.decimals;
-      } catch {
-      }
       try {
-        assertStrictPositiveAmount(opts.amount, decimals);
+        assertStrictPositiveAmount(opts.amount);
       } catch (err) {
         throw new TransferError("VALIDATION_ERROR", errorMessage(err));
       }
-      if (!opts.skipSafetyCheck) {
+      let safety;
+      if (opts.skipSafetyCheck) {
+        safety = { skip: true };
+      } else {
         const maxUsd = parseFloat(opts.maxUsd ?? String(DEFAULT_MAX_OFFRAMP_USD2));
         if (!Number.isFinite(maxUsd) || maxUsd <= 0) {
           throw new TransferError("VALIDATION_ERROR", "--max-usd must be a positive number");
         }
-        try {
-          const tokenInfo = resolveToken(opts.asset, chainKey);
-          if (tokenInfo) {
-            const swapClient = new SwapClient(httpClient);
-            const price = await swapClient.getTokenPrice(chainKey, tokenInfo.address);
-            if (price && price > 0) {
-              const usdValue = parsedAmount * price;
-              if (usdValue > maxUsd) {
-                throw new TransferError(
-                  "USD_LIMIT_EXCEEDED",
-                  `Payout value ~$${usdValue.toFixed(2)} USD exceeds safety limit of $${maxUsd}. Re-run with --max-usd ${Math.ceil(usdValue)} or --skip-safety-check to proceed.`
-                );
-              }
-              if (usdValue > 1e3) {
-                warn(`High-value off-ramp payout: ~$${usdValue.toFixed(2)} USD`);
-              }
-            }
-          }
-        } catch (err) {
-          if (err instanceof CommandError) throw err;
-          warn(
-            "Could not verify payout USD value (price lookup failed). Use --skip-safety-check to suppress."
-          );
-        }
+        safety = { maxUsd };
       }
       const address = await provider.getAddress(chainKey);
       warn(
         `About to send ${opts.amount} ${opts.asset} from ${address} to third-party off-ramp deposit address ${opts.to}${opts.memo ? ` (memo: ${opts.memo})` : ""}. This address is not under your control \u2014 verify it matches what the provider displayed before continuing.`
       );
-      let result;
-      try {
-        result = await provider.transfer({
-          assetId: opts.asset,
-          to: opts.to,
-          amount: opts.amount,
-          decimals,
-          memo: opts.memo,
-          // Mainnet by construction — onramp has no --chain input and derives
-          // chainKey from the asset's coinId via mainnetChainKeyForCoinId.
-          chainKey
-        });
-      } catch (err) {
-        mapBroadcastError(err);
+      const { contractAddress } = parseTokenId(opts.asset);
+      const executor = new TransferExecutor({
+        wallet: provider,
+        swapClient: new SwapClient(await getClient()),
+        onInfo: info,
+        onWarn: warn
+      });
+      const result = await executor.execute({
+        // Mainnet by construction — onramp has no --chain input and derives
+        // chainKey from the asset's coinId via mainnetChainKeyForCoinId.
+        chain: chainKey,
+        to: opts.to,
+        resolveNames: false,
+        amount: opts.amount,
+        tokenAddress: contractAddress,
+        decimals: opts.decimals,
+        memo: opts.memo,
+        safety
+      });
+      if (!result.success) {
+        throw new CommandError(result.code, result.message);
       }
-      const explorerUrl = getExplorerTxUrl(result.chainKey, result.hash);
       success("Off-ramp payout broadcast!");
       if (!opts.json) {
         info(
@@ -55840,13 +55919,13 @@ ${url}`);
         {
           hash: result.hash,
           chain: result.chainKey,
-          from: address,
-          to: opts.to,
+          from: result.from,
+          to: result.to,
           amount: opts.amount,
           asset: opts.asset,
           memo: opts.memo,
           quoteId: opts.quoteId,
-          explorer: explorerUrl
+          explorer: result.explorerUrl
         },
         opts.json
       );
@@ -56319,7 +56398,7 @@ init_dist();
 // package.json
 var package_default = {
   name: "@trustwallet/cli",
-  version: "0.24.2",
+  version: "0.25.0",
   description: "TWAK CLI \u2014 command-line interface for Trust Wallet Agent Kit",
   main: "dist/index.js",
   types: "dist/index.d.ts",