> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zyf.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# logDeposit

Register a deposit that you executed yourself with the Zyfai backend.

[`sendDeposit`](/docs/sdk/api/send-deposit) already calls this after the ERC-20 transfer. If you send the transfer from your frontend, Privy, Biconomy, or any custom wallet, you **must** call `logDeposit`. Otherwise the backend never sees the deposit: a reserved pool wallet is not handed over to the user, and yield / portfolio tracking does not start.

<Warning title="Required when you transfer yourself">
  Skip this only if you used [`sendDeposit`](/docs/sdk/api/send-deposit). Any external transfer path must call `logDeposit` after the transaction confirms.
</Warning>

Typical cases:

* You already have a transaction hash from an independently-created transfer
* You need to recover or replay registration after a prior registration failure

For a new sponsored / gasless or custom-wallet deposit, use
[external deposit building blocks](/docs/sdk/api/external-deposit-building-blocks).
It prepares the transfer and registers the transaction without requiring
separate setup calls.

For an intentionally split flow, use
[external deposit building blocks](/docs/sdk/api/external-deposit-building-blocks)
before registering the resulting hash here.

The token is automatically selected based on the chain if not provided.

## Signature

```typescript theme={null}
logDeposit(chainId: SupportedChainId, txHash: string, amount: string, tokenAddress?: string): Promise<LogDepositResponse>
```

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `chainId` | `SupportedChainId` | ✅ | Chain ID where the deposit was made |
| `txHash` | `string` | ✅ | Transaction hash of the deposit |
| `amount` | `string` | ✅ | Amount in least decimal units (e.g., "100000000" for 100 USDC with 6 decimals) |
| `tokenAddress` | `string` | ❌ | Token address (auto-selected based on chain if not provided) |

## Returns

Log deposit response with success status and lifecycle metadata.

A successful registration can return `handover_pending`: the transfer is verified and recorded, but it is not yet credited or investable. Use [`waitForDepositCredit`](/docs/sdk/api/wait-for-deposit-credit) until the Safe balance is credited, then [`waitForDepositPosition`](/docs/sdk/api/wait-for-deposit-position) when the UI should wait for allocation.

## HTTP endpoint

The SDK posts to `POST /api/v1/users/log_deposit/v2`, which returns **`202 Accepted`** with a `DepositLifecycleResponse` body. The legacy `POST /api/v1/users/log_deposit` route returns **`201 Created`** with no body. Custody handover completes asynchronously in the background.

## Return Type

```typescript theme={null}
type DepositLifecycleStatus =
  | "handover_pending"
  | "credited"
  | "recovered_to_eoa"
  | "position_pending"
  | "positioned";

interface DepositLifecycleResponse {
  id: string;
  status: DepositLifecycleStatus;
  balanceCredited: boolean;
  statusUrl: string;
  positionOutcome?: "pending" | "positioned" | "skipped" | "failed" | null;
  crosschain?: boolean;
  executionTxHash?: string | null;
}

interface LogDepositResponse {
  success: boolean;
  message: string;
  deposit: DepositLifecycleResponse;
}
```

| `deposit.status` | Meaning |
| - | - |
| `handover_pending` | Accepted; custody handover or balance credit still in progress |
| `credited` | Credited to the Safe balance |
| `position_pending` | Credited; rebalance into a position in progress |
| `positioned` | Allocation finished (or terminal for this poll surface) |
| `recovered_to_eoa` | Terminal — funds returned to the EOA instead of being credited |

## Example

```typescript theme={null}
// Execute deposit with Privy (sponsored transaction)
const txHash = await privyWallet.sendTransaction({
  to: safeAddress,
  data: transferData,
});

// Log the deposit to Zyfai backend
const result = await sdk.logDeposit(
  8453,           // chainId
  txHash,         // transaction hash from Privy
  "100000000"     // 100 USDC
);
console.log(result.success); // true
console.log(result.deposit.status); // "handover_pending" or "credited"

// Wait for credit when handover is still pending
if (result.deposit.status === "handover_pending") {
  const credited = await sdk.waitForDepositCredit(result.deposit.id, 8453);
  const positioned = await sdk.waitForDepositPosition(result.deposit.id, 8453);
  console.log("Deposit credited:", credited.id, positioned.status);
}
```

## Example with custom token

```typescript theme={null}
// Log deposit with specific token address
const result = await sdk.logDeposit(
  8453,
  "0xTransactionHash...",
  "100000000",
  "0xCustomTokenAddress..." // Optional: override default token
);
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.