> ## Documentation Index
> Fetch the complete documentation index at: https://spiceflow-docs.spicenet.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cash Funding

> Fund native account actions from matching balances or multiple account positions

SDK 4.19.0 supports two opt-in funding patterns through `useSpiceSupply`. Both keep quoting,
conversion, fees, spend caps and execution inside the SDK. Account balance display alone is not a
spendable quote; use the controller's availability and readiness fields.

## Combine Matching Balances

Set `combineSourceBalances: true` on `useSpiceSupply`, `SpiceSupply` or `useSpiceLock` when the action
should use eligible matching wallet and escrow positions together. It defaults to false.

Keep the selected full `Asset` and its amount. The SDK matches the same owner and token mapping,
accounts for reservations, avoids counting a position twice, and builds the necessary deposit or
withdrawal allocation. It does not combine arbitrary symbols, unrelated owners or stale balances.
Use `assets.getAvailableBalance(asset)` and `amount.availableBalance` instead of adding displayed
balances yourself. `max()` includes funding and fee requirements and can return `null`.

## Purchase from Account Cash

Use `fundingSources` when the UI presents one purchase budget funded from several nominated account
positions, without choosing a single source token. The contract is:

| Input | Meaning |
| - | - |
| `fundingSources.token` | Supported USDC token on the destination chain; budget denomination |
| `fundingSources.positionIds` | Physical account positions nominated with `assetPositionId(asset)` |
| `selectedAsset` | Must be `null` |
| `paymentAmount` | Total budget string in the funding token's units, despite this field's usual fixed-output role |
| `amountDirection` | `"input-inclusive"`; also the default when `fundingSources` is present |
| `destinationToken` | Token your protocol calls consume, on the same chain as the funding token |
| `buildActionCalls` | Protocol calls using the SDK's destination-token bigint after conversion and fees |

This mode requires the embedded 7702 account. It accepts eligible embedded-wallet positions and mapped
Spice balances owned by that account, subject to source-chain/token policy and available routes.
It cannot be combined with a selected asset, fee-only actions, `actionInput`, `actionProceeds` or
`actionExecution`. It does not pool external wallets into the account purchase.

The SDK uses credited Spice Cash before wallet conversion/deposit. It quotes source conversions,
funding, destination conversion and fees within the common USDC budget. Nominating a position does not
force it into the accepted plan if it is ineligible or unnecessary.

### Controlled Integration

This hook adapter accepts the host's budget, nominated inventory positions, and protocol builder.
Mount it under your existing provider stack and render the returned controller as in
[Custom UI Integration](https://spiceflow-docs.spicenet.io/guides/custom-ui.md). Pass physical inventory positions rather than a synthetic
Cash display row.

```tsx theme={null}
import {
  assetPositionId,
  useSpiceSupply,
  type Asset,
  type SpiceSupplyProps,
} from "@spicenet-io/spiceflow-ui";

export function useCashPurchase({
  budget,
  positions,
  destinationToken,
  fundingToken,
  buildActionCalls,
}: {
  budget: string;
  positions: Asset[];
  destinationToken: SpiceSupplyProps["destinationToken"];
  fundingToken: SpiceSupplyProps["destinationToken"];
  buildActionCalls: SpiceSupplyProps["buildActionCalls"];
}) {
  return useSpiceSupply({
    destinationToken,
    selectedAsset: null,
    fundingSources: {
      token: fundingToken,
      positionIds: positions.map(assetPositionId),
    },
    paymentAmount: budget,
    amountDirection: "input-inclusive",
    buildActionCalls,
  });
}
```

Use `flow.assets.fundingSources` for the eligible nominated inventory and
`flow.feeQuote?.fundingPlan` for the accepted allocation. Each plan source has its identity, token units,
source spend cap, available/reserved amount and minimum output. Do not encode a second funding plan in
the host. Show `flow.fees.preview`, wait for `flow.canExecute`, then call `flow.submit()`.

`flow.max()` returns a budget string in the common funding-token units. In this mode the selected asset
is null, so do not format all source debits with one selected asset's decimals; use each plan source's
own decimals. Conversions can change the destination amount without changing the total budget.

## Pending Actions and Recovery

Funding belongs to the original action. A pending funding leg is not permission to start a new
purchase or repeat a deposit. Render `status.pending`, `status.recoveryChecking` and
`status.recoveryError`; call `refreshStatus()` to check the original action. Continue using
`canExecute` for submission readiness. See [Recovery and completion](https://spiceflow-docs.spicenet.io/sdk/migration.md#recovery-and-completion).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.