External deposit building blocks

Use these methods for sponsored, custom-wallet, or queue-backed transaction flows where your integration submits the transfer itself. Authenticate the same SDK instance with connectAccount() first. On a first deposit, call setup before you submit the transfer; after the transfer, call logDeposit with the transaction hash.

Complete lifecycle

Authenticate with connectAccount() on the same SDK instance.
Run ensureFirstDepositSetup() before a first-deposit transfer.
Build ERC-20 calldata with buildDepositTransfer().
Submit that calldata through your wallet, relayer, or transaction service, then wait for its on-chain receipt.
Register the confirmed transaction with logDeposit().
Use getDepositStatus() for a one-off lifecycle check, or waitForDepositCredit() to wait until it is credited and investable.

logDeposit() can return handover_pending. Do not treat the deposit as investable until its status is credited and balanceCredited is true. A recovered_to_eoa status is terminal: the funds were returned to the EOA and must not be registered or transferred again without checking the transaction and lifecycle state first.

`ensureFirstDepositSetup`

Idempotently configures protocols and chains for a first deposit. It does nothing after the USDC profile has chains configured. When setup runs, it throws if protocol configuration cannot be persisted (for example API or pool lookup failures). Treat errors as blocking: do not submit a transfer until setup succeeds or returns { applied: false } because the account was already configured.

ensureFirstDepositSetup(strategy?: Strategy): Promise<{ applied: boolean }>

`buildDepositTransfer`

Resolves the user’s Safe and returns standard ERC-20 transfer calldata.

buildDepositTransfer({
  userAddress: string;
  chainId: SupportedChainId;
  amount: string;
  asset: SupportedAsset;
}): Promise<{
  safeAddress: Address;
  tokenAddress: Address;
  to: Address;
  data: Hex;
  value: "0";
}>

Example

await sdk.connectAccount(walletProvider, 8453);

await sdk.ensureFirstDepositSetup("conservative");
const transaction = await sdk.buildDepositTransfer({
  userAddress,
  chainId: 8453,
  amount: "100000000", // 100 USDC
  asset: "USDC",
});

const txHash = await transactionService.send({
  to: transaction.to,
  data: transaction.data,
});

const registration = await sdk.logDeposit(
  8453,
  txHash,
  "100000000",
  transaction.tokenAddress,
);

if (registration.deposit.status === "handover_pending") {
  // Optional one-off check for UI status or recovery handling.
  const status = await sdk.getDepositStatus(registration.deposit.id);
  console.log("Deposit status:", status.status);

  // Or wait until the deposit is investable.
  const credited = await sdk.waitForDepositCredit(registration.deposit.id, 8453);
  console.log("Deposit credited:", credited.id);
}

Lifecycle helpers

Helper	Use it when	Result
`logDeposit`	You have a confirmed external transfer hash	Registers it and returns the initial lifecycle record
`getDepositStatus`	A UI or recovery flow needs one current state check	`handover_pending`, `credited`, or `recovered_to_eoa`
`waitForDepositCredit`	The flow should pause until funds are investable	Resolves only when `credited` and `balanceCredited` are true

Getting Started

Smart Wallet API

Intelligence Layer

Complete lifecycle

`ensureFirstDepositSetup`

`buildDepositTransfer`

Example

Lifecycle helpers

​Complete lifecycle

​ensureFirstDepositSetup

​buildDepositTransfer

​Example

​Lifecycle helpers

Complete lifecycle

`ensureFirstDepositSetup`

`buildDepositTransfer`

Example

Lifecycle helpers