getGaslessDepositPolicy

Read the gasless deposit policy for one of an owner’s GaslessWallets — the deterministic deposit address plus the collateral and fee terms — directly from the GaslessLayer.


import { getGaslessDepositPolicy } from "@symmio/trading-core";
import { formatUnits } from "viem";
 
const policy = await getGaslessDepositPolicy(config, { owner });
showDepositAddress(policy.depositAddress);
showMinimum(formatUnits(policy.settlementMinimum, policy.collateralDecimals));

Six RPC reads (the service exposes no read endpoints): getGaslessWalletAddress(owner, walletId), collateralToken() and that token’s decimals(), depositFee(), minimumDeposit() and getWalletCreationFee(owner, walletId). walletId defaults to 0n, the original wallet; pass another id to read that wallet’s address and creation fee. The deposit address is a pure CREATE2 view — safe to display before any transaction — and collateral sent there can only ever reach a sub-account owned by owner.

Every amount is in the collateral token’s own units; format them with collateralDecimals. Watch the address’s balance with the existing collateral-balance read, getCollateralBalance, and enable settlement once it reaches settlementMinimum:


import { getCollateralBalance } from "@symmio/trading-core";
 
const observed = await getCollateralBalance(config, { owner: policy.depositAddress });
const canSettle = observed >= policy.settlementMinimum;

settlementMinimum is max(minimumDeposit, depositFee + walletCreationFee + 1n). The GaslessLayer rejects a settlement unless the swept balance both reaches minimumDeposit and exceeds the deposit fee plus the creation fee, and the creation fee applies only while the wallet is not deployed yet.

Send only the configured collateral token to the address — nothing else is swept, and the settlement consumes the wallet’s entire observed balance (additional funds arriving before settlement settle together, with the fees off the top). Wallets of the same owner never share balances, so give funding flows that must not be swept together their own wallet ids.

While walletCreationFee is non-zero, the service’s acceptance estimate overstates the credited amount, because it subtracts only the deposit fee. See getGaslessWalletCreationFee before offering that flow.

Parameters

ownerAddressrequired

The owner onboarding through gasless deposit. Pass the owner’s address, never a GaslessWallet address.

walletIdbigintdefault 0noptional

Which of the owner’s wallets receives the deposit, from 0n through 2^256 - 1. 0n is the original wallet.

chainIdnumberoptional

Target chain id. Defaults to the config’s defaultChainId.

Returns

Promise<GetGaslessDepositPolicyReturnType>

walletIdbigint

The wallet id the policy was read for — 0n when the parameter was omitted.

depositAddressAddress

The deterministic deposit address: the GaslessWallet of (owner, walletId).

collateralTokenAddressAddress

The only token the settlement sweeps.

collateralDecimalsnumber

The collateral token’s ERC-20 decimals() — the scale of every amount in this policy.

depositFeebigint

Flat fee deducted from the observed balance at settlement (collateral token units).

minimumDepositbigint

Minimum observed balance the service will settle (collateral token units).

walletCreationFeebigint

One-time fee the settlement also deducts when it deploys the wallet (collateral token units). 0n once the wallet is deployed.

settlementMinimumbigint

max(minimumDeposit, depositFee + walletCreationFee + 1n) — the smallest balance that settles: it must both reach the minimum and exceed the deposit and creation fees. Gate the settlement UI on this.

Query options


import { getGaslessDepositPolicyQueryOptions } from "@symmio/trading-core";
import { useQuery } from "@tanstack/react-query";
 
useQuery(getGaslessDepositPolicyQueryOptions(config, { owner, walletId: 1n }));

An omitted walletId keys the same as 0n. The creation fee drops to 0n once any action deploys the wallet, so refetch the policy after a settlement or a wallet operation. useGaslessDepositPolicy and the React relay hooks handle that invalidation.

Throws

SymmError("validation", "GASLESS_WALLET_ID_INVALID") — walletId is not a bigint from 0n through 2^256 - 1 (a JavaScript number included). Thrown before any RPC call.
SymmError("config", "GASLESS_NOT_CONFIGURED") / ("config", "GASLESS_UNSUPPORTED_CONTRACTS_VERSION").
SymmError("api", "GASLESS_WALLET_UNAVAILABLE") — the gateway returned the zero address for the wallet.
Viem read errors. A GaslessLayer that has not been upgraded to the multi-wallet interface reverts with empty data.