Managed Balance Refills

Managed balance refills let a user keep a USDC buffer on a selected chain. The user chooses a minimum balance and a refill amount, and sufwan-local-test can move USDC from another one of the user's managed chains after trading lowers the target-chain balance.

For example, a user can set a $100 minimum and a $50 refill amount on Polygon. After a completed trade:

The requested delivery is the larger of the configured refill amount or the amount needed to restore the minimum. Network and bridge fees are paid from the source balance and must stay within the user's configured maximum fee.

When a refill runsCopy Anchor Link

A refill is considered only after a trade has finished and all orders linked to that trade are in a terminal state, such as filled, cancelled, expired, or failed. sufwan-local-test refreshes the balance after the trade before comparing it with the policy minimum. See Funding. A deposit or a withdrawal does not start a refill.

Trading always takes priority:

• If another trade is active or queued, sufwan-local-test waits until queued trading is finished before considering the refill.
• Once a refill has started, a newly submitted trade waits for the refill to finish.
• sufwan-local-test runs at most one balance-moving operation for a user at a time.

Create a policyCopy Anchor Link

minimumRaw and refillAmountRaw are 6-decimal USD integer strings. 1000000 is $1. Optional: targetTokenSymbol "USDC", dailyCapRaw, and maxFeeRaw. A policy is enabled or paused. It is not an order, so it is never cancelled.

// Call after the user authenticates.
await client.createBalanceRefillPolicy({
  targetChainId: 137,
  minimumRaw: "100000000", // 1000000 = $1, so this is $100
  refillAmountRaw: "50000000", // $50
});

Create a managed balance refill policy.

The target chain must support managed USDC. A user can have one policy per target chain and can create policies for more than one chain.

By default, refills are limited to $1,002 per UTC day (up to $1,000 of refills plus fees) and $2 in fees per refill. Pass dailyCapRaw or maxFeeRaw when the user wants different limits. The daily cap is applied conservatively to each requested delivery plus its maximum allowed fee and must be large enough to cover the configured amounts and fee limit. See the Create balance refill policy API for field constraints and the complete request and response schemas.

Read, update, or pause a policyCopy Anchor Link

getBalanceRefillPolicies lists them. updateBalanceRefillPolicy changes minimumRaw, refillAmountRaw, dailyCapRaw, or maxFeeRaw, and sets status to enabled or paused.

After a transfer completes or fails, sufwan-local-test applies the policy's five-minute cooldown before another attempt can start. The policy response includes lastObservedRaw, lastEvaluatedAt, nextEligibleAt, and latestAttempt so your app can show its current state without reproducing the refill logic.

Monitor refill attemptsCopy Anchor Link

getBalanceRefillAttempts(policyId) returns the recent attempts. An attempt moves through reserved and executing, then ends as completed or failed. Use completedAmountRaw, feeRaw, and errorMessage to present the final outcome. The endpoint returns the 25 most recent attempts for the policy.

Source balances and feesCopy Anchor Link

sufwan-local-test selects an available managed USDC balance on a different supported chain. The source must have enough spendable USDC for the requested delivery and the maximum fee; funds already reserved for orders or other operations are not available to a refill.

Managed balance refills do not pull money from a bank account, card, or external wallet. If no eligible managed source balance is available, or if the fee or daily cap would be exceeded, no transfer starts. The policy remains enabled and can be considered again after a later completed trade.

A refill and a withdrawal cannot spend the same managed balance at the same time. If a refill is already in progress, a withdrawal returns 409. The withdrawal itself does not start a refill. The next eligible completed trade can. Deposits and withdrawals are on Funding.

API referenceCopy Anchor Link