getDepositStatus

Fetch the custody handover, credit, and allocation lifecycle for a registered deposit.

Fetch the current lifecycle state for a deposit registered via logDeposit or sendDeposit.

The SDK calls GET /api/v1/users/deposits/{depositId}/v2, which includes allocation fields. The legacy GET /api/v1/users/deposits/{depositId} route returns handover and credit only.

Use this for one-off checks. To await credit after handover_pending, use waitForDepositCredit. To await allocation after credit, use waitForDepositPosition.

Requires connectAccount() on the same ZyfaiSDK instance.

Signature

getDepositStatus(depositId: string): Promise<DepositLifecycleResponse>

Parameters

Parameter	Type	Required	Description
depositId	string	✅	Lifecycle UUID from logDeposit().deposit.id or sendDeposit().registration.id

Returns

Current deposit lifecycle state.

Return Type

type DepositLifecycleStatus =
  | "handover_pending"
  | "credited"
  | "recovered_to_eoa"
  | "position_pending"
  | "positioned";

type DepositPositionOutcome =
  | "pending"
  | "positioned"
  | "skipped"
  | "failed";

interface DepositLifecycleResponse {
  id: string;
  status: DepositLifecycleStatus;
  balanceCredited: boolean;
  statusUrl: string;
  positionOutcome?: DepositPositionOutcome | null;
  crosschain?: boolean;
  executionTxHash?: string | null;
}

Field	Description
status	Custody, credit, and allocation lifecycle stage
balanceCredited	Whether this deposit has been added to the Safe balance
statusUrl	Authenticated API path for polling (used internally by the SDK)
positionOutcome	Allocation result when rebalance has run (skipped if deploy was not attempted)
crosschain	Whether this deposit used a crosschain path
executionTxHash	Bridge or execution tx when crosschain is true

Treat a deposit as spendable on the Safe when balanceCredited === true and status !== "recovered_to_eoa". handover_pending means the transfer is recorded but not yet credited. position_pending / positioned mean credit completed and allocation may still be in progress or done.

Example

const result = await sdk.logDeposit(8453, txHash, "100000000");

const status = await sdk.getDepositStatus(result.deposit.id);
console.log(status.status);
console.log(status.balanceCredited);

if (status.balanceCredited && status.status !== "recovered_to_eoa") {
  console.log("Deposit is credited on the Safe");
}

Related methods

• waitForDepositCredit — poll until credited
• waitForDepositPosition — poll until positioned or skipped