Cash Funding

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. Pass physical inventory positions rather than a synthetic Cash display row.

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.

Getting Started

SDK Reference

Guides & Examples

Technical Deep Dive

Combine Matching Balances

Purchase from Account Cash

Controlled Integration

Pending Actions and Recovery

​Combine Matching Balances

​Purchase from Account Cash

​Controlled Integration

​Pending Actions and Recovery

Combine Matching Balances

Purchase from Account Cash

Controlled Integration

Pending Actions and Recovery