settleGaslessDepositNewAccount

Queue the sweep of an owner’s deposit address into a new wallet-owned sub-account — the cold-start onboarding step. The gateway creates the account, credits the net amount, and pays all the gas itself.


import { settleGaslessDepositNewAccount, SubAccountIsolationType } from "@symmio/trading-core";
import { zeroAddress } from "viem";
 
const receipt = await settleGaslessDepositNewAccount(config, {
  owner,
  walletId: 1n,
  affiliate: zeroAddress,
  accountData: { name: "Main", isolationType: SubAccountIsolationType.MARKET_DIRECTION, singleVAMode: true },
});

One POST {depositBase}/deposit-settlements/new-account, carrying owner and an explicit decimal walletId. The settlement sweeps the entire collateral balance at the selected wallet’s deposit address when the transaction executes, including anything that arrived after acceptance. It deducts the deposit fee, plus the wallet creation fee when this settlement is what first deploys the wallet. The worker re-checks balance, fee, and minimum before broadcasting, so an accepted settlement can still turn rejected — funds not yet visible, or moved. Poll the receipt’s requestId with service: "deposits".

The receipt’s amounts are acceptance-time estimates in the collateral token’s base units, not the settlement result. observedAmount is the balance the service saw when it accepted the request, and creditedAmount deducts only the deposit fee from it. It leaves out a wallet creation fee (the GaslessLayer’s getWalletCreationFee(owner, walletId)) and anything that arrives before execution. Label it as an estimate, and take the final credit from the settlement transaction’s WalletDepositSettled event or the new sub-account’s balance.

Each wallet id is a separate balance, and a settlement sweeps all of it. The action reads getGaslessWalletAddress(owner, walletId) before the submit and checks the acceptance’s wallet_id and deposit_address against it, throwing GASLESS_DEPOSIT_WALLET_MISMATCH (with the parsed receipt, request id included, in responseData) when they disagree — the vendor requires this check, because sweeping the wrong wallet moves funds the user never meant to move. Give a funding flow its own id when it must not share a balance with another, and read that id’s address again before every transfer.

succeeded does not mean the account is instantly usable — wait until the sub-account and its credited balance are readable on-chain (getUserSubAccounts + getAccountBalanceOf) before flipping the UI. And never reuse a completed settlement’s idempotency key: a replay by key returns the old record without re-checking the vault — mint a fresh key per attempt after any terminal status.

This action is a submit: it resolves with the 202 acceptance. React consumers do not need to follow it by hand — the matching hook in @symmio/trading-react confirms the request before it resolves and invalidates the reads this action changes. See the React gasless guide.

Parameters

ownerAddressrequired

Owner of the GaslessWallet being settled — an owner address, never a GaslessWallet address. The new sub-account is created for this owner. (Renamed from wallet, which the service still accepts as a legacy alias but the SDK no longer sends.)

walletIdbigintoptional

Which of the owner’s GaslessWallets to sweep. Defaults to 0n, the original wallet. Ids are an application convention — the contract registers none — so persist your assignment under (environment, protocolInstance, owner, walletId).

affiliateAddressrequired

Affiliate passed to the settlement; the zero address disables attribution. Use the zero address unless the deployment has an active affiliate to attribute to — an affiliate the deployment does not know reverts the settlement on-chain, after acceptance.

accountDataGaslessDepositAccountDatarequired

Creation data for the new sub-account: name (1–64 chars), isolationType, singleVAMode, optional metadata hex. isolationType and singleVAMode are deliberately required — they are product decisions (the lowcap flow uses MARKET_DIRECTION with singleVAMode: true; majors differ) and the service-side defaults would be silently wrong for either product. There is no symmioCore field — the gateway overwrites it with its configured core.

idempotencyKeystringoptional

Stable retry key; defaults to a random UUID. One key per settlement attempt: reuse it only to replay a submit whose response was lost, and mint a fresh one after any terminal status or any change to the wallet selection — or the service answers 409 IDEMPOTENCY_KEY_CONFLICT. See idempotency keys.

metadataRecord<string, unknown>optional

Non-secret client correlation data stored with the request.

chainIdnumberoptional

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

Returns

Promise<GaslessDepositSubmitReceipt>

requestIdstring

Stable tracking id — poll it with service: "deposits".

statusGaslessRequestStatus

Status at acceptance, normally queued.

depositAddressAddress

The deterministic deposit address being swept, as the service echoed it — verified against the requested wallet.

walletIdbigint

The wallet id the service settled. An acceptance that omits it means wallet 0.

ownerAddress

The owner the settlement was submitted for.

observedAmountbigint | null

Collateral balance the service observed at the address on acceptance (token base units). The sweep takes whatever is there at execution. null when the acceptance reported none.

paidFeebigint | null

The deposit fee in the acceptance-time estimate (token base units). Excludes a wallet creation fee.

creditedAmountbigint | null

The estimated net credit at acceptance (token base units), with only the deposit fee deducted. Not the final credit.

idempotencyKeystring

The key the settlement was submitted with — minted here when the caller passed none.

protocolInstancestring | null

The instance the settlement was accepted on, or null for a proxy base that names none.

Throws

SymmError("config", "GASLESS_NOT_CONFIGURED") / ("config", "GASLESS_UNSUPPORTED_CONTRACTS_VERSION").
SymmApiError with code GASLESS_SETTLEMENT_SUBMIT_FAILED — HTTP failure; DEPOSIT_BELOW_MINIMUM in the vendor detail means the address has not reached the settlement minimum yet.
SymmApiError with code GASLESS_SUBMIT_UNCONFIRMED — the outcome could not be established. The settlement may already be sweeping: replay the recorded bytes with resubmitGaslessRequest instead of submitting a new settlement.
SymmApiError with code GASLESS_DEPOSIT_WALLET_MISMATCH — the acceptance named another wallet id or deposit address. The settlement is already accepted, so the parsed receipt (with its requestId) rides in responseData: reconcile it before funding or settling anything else.
SymmError("validation", "GASLESS_WALLET_ID_INVALID") — a walletId outside 0 … 2^256 − 1, or a JavaScript number.