Add useCrossVmSpendFt docs

docs/tools/kit/index.md

@@ -24,6 +24,7 @@ sidebar_position: 1
 
 - [`useCrossVmTokenBalance`](#usecrossvmtokenbalance) – Query fungible token balances across Cadence and Flow EVM
 - [`useCrossVmBatchTransaction`](#usecrossvmbatchtransaction) – Execute mutliple EVM transactions in a single atomic Cadence transaction
+- [`useCrossVmSpendToken`](#usecrossvmspendnft) – Bridge fungible tokens from Cadence to Flow EVM and execute arbitrary EVM transactions
 
 ## Installation
 
@@ -421,6 +422,10 @@ function TransactionStatusComponent() {
 
 ### `useCrossVmTokenBalance`
 
+<Callout type="info">
+This feature is currently only supported on Testnet & Mainnet networks.  Emulator support will be added in a future release.
+</Callout>
+
 ```tsx
 import { useFlowQuery } from '@onflow/kit';
 ```
@@ -580,5 +585,80 @@ function CrossVmBatchTransactionExample() {
 }
 ```
 
+---
+
+### `useCrossVmSpendToken`
+
+<Callout type="info">
+This feature is currently only supported on Testnet & Mainnet networks.  Emulator support will be added in a future release.
+</Callout>
+
+```tsx
+import { useCrossVmSpendToken } from "@onflow/kit"
+```
+
+Bridge FTs from Cadence to Flow EVM and execute arbitrary EVM transactions to atomically spend them.
+
+#### Parameters:
+- `mutation?: UseMutationOptions<string, Error, UseCrossVmSpendTokenMutateArgs>` – Optional TanStackQuery mutation options
+
+Where `UseCrossVmSpendTokenMutateArgs` is defined as:
+
+```typescript
+interface UseCrossVmSpendTokenMutateArgs {
+  vaultIdentifier: string; // Cadence vault identifier (e.g. "0x1cf0e2f2f715450.ExampleToken.Vault")
+  amount: string; // Amount of tokens to bridge, as a decimal string (e.g. "1.23")
+  calls: EVMBatchCall[]; // Array of EVM calls to execute after bridging
+}
+```
+
+#### Returns: `UseCrossVmSpendTokenResult`
+
+Where `UseCrossVmSpendTokenResult` is defined as:
+
+```typescript
+interface UseCrossVmSpendTokenResult extends Omit<
+  UseMutationResult<string, Error, UseCrossVmSpendTokenMutateArgs>,
+  "mutate" | "mutateAsync"
+> {
+  spendToken: (args: UseCrossVmSpendTokenMutateArgs) => void; // Function to trigger the FT bridging and EVM calls
+  spendTokenAsync: (args: UseCrossVmSpendTokenMutateArgs) => Promise<string>; // Async version of spendToken
+}
+```
+
+```tsx
+function CrossVmSpendTokenExample() {
+  const { spendToken, isPending, error, data: txId } = useCrossVmSpendToken()
+
+  const handleSpendToken = () => {
+    spendToken({
+      vaultIdentifier: "0x1cf0e2f2f715450.ExampleToken.Vault", // Cadence vault identifier
+      amount: "1.23", // Amount of tokens to bridge to EVM
+      calls: [
+        {
+          abi: myEvmContractAbi, // EVM contract ABI
+          address: "0x01234567890abcdef01234567890abcdef", // EVM contract address
+          function: "transfer", // EVM function to call
+          args: [
+            "0xabcdef01234567890abcdef01234567890abcdef", // Recipient address
+          ],
+        },
+      ],
+    })
+  }
+
+  return (
+    <div>
+      <button onClick={handleSpendToken} disabled={isPending}>
+        Bridge and Spend FTs
+      </button>
+      {isPending && <p>Sending transaction...</p>}
+      {error && <p>Error: {error.message}</p>}
+      {txId && <p>Cadence Transaction ID: {txId}</p>}
+    </div>
+  )
+}
+```
+
 [commit-reveal scheme]: ../../build/advanced-concepts/randomness#commit-reveal-scheme
 [Configuration Guide]: ../flow-cli/flow.json/configuration.md