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

# Deposits

> Fund a portfolio wallet and track deposit lifecycle.

After creating a wallet, fund it by sending a supported stablecoin to the wallet's deposit addresses.

## Fund the wallet

The wallet creation response includes `depositAddresses` — one address per supported chain. Send USDC on a supported chain or USDT on Ethereum. The EVM address can be the same for both tokens, so always validate the token and network before sending.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
to:    0x21246509968c4d24611f414560971AEc2e3A079B
chain: ethereum
token: USDC
```

### Minimum amounts

There is no minimum deposit amount. However, small deposits may remain as undeployed [cash](/docs/portfolio-wallets/balances-and-yield#cash-positions) if deploying them into yield positions is not economically efficient (considering gas costs, minimum trade sizing, and protocol constraints). This minimum is environment-configured and applied per executable rebalance leg: sandbox uses small minimums (e.g. 5 units per leg) so you can test with small amounts, while production minimums are typically higher. See [Balances and Yield](/docs/portfolio-wallets/balances-and-yield#when-idle-stablecoins-move-into-yield).

### Sandbox

* Use the explicit sandbox key `depositAddresses.ethereum_sepolia`. Fund it with Sepolia USDC from the [Circle faucet](https://faucet.circle.com/).
* Sandbox USDT uses Ground's mock token on Ethereum Sepolia. Do not send public Sepolia USDT to the mock-token contract or assume it represents support for other USDT networks.

## Deposit lifecycle

| Status       | Terminal | Meaning                                                                                                              |
| ------------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `processing` | No       | Ground detected the inbound stablecoin transaction for a workflow-idle wallet or is processing the finalized deposit |
| `completed`  | Yes      | Deposit finalized and posted; wallet balances updated                                                                |
| `failed`     | Yes      | Deposit processing failed                                                                                            |

Processing deposits are informational until finality. They can appear in deposit and activity APIs shortly after the source wallet broadcasts the transfer when the destination wallet has no active Ground-managed workflow, but they are not included in `balance.totalUsd`, `balance.withdrawableUsd`, or positions until ledger posting completes. Wallets with active rebalances, withdrawals, or protocol workflows may wait until final attribution before a deposit appears.

As deposits settle, the wallet's `balance.totalUsd` and `positions` update. Deployment follows the wallet's current strategy using the yield sources returned by the live catalog for that environment.

## Deposit response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "797a5ca3-2a1c-443b-b190-ca951964aa35",
  "amount": "10.000000",
  "token": "usdc",
  "chain": "ethereum_sepolia",
  "fromAddress": "0x76f8fc6667e239f83a547d4e16225d6a34f6fa22",
  "txHash": "0xe2e8a534960a7cf19932b35759788a0de4fa131d46d3e36a96a4802b6b93e5e1",
  "status": "completed",
  "createdAt": "2026-07-09T21:34:17.973Z",
  "completedAt": "2026-07-09T21:34:17.973Z"
}
```

| Field         | Description                                                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `id`          | Unique deposit identifier; when backed by an observed onchain event, the same ID is used from `processing` through `completed` |
| `amount`      | Deposit amount as a fixed-precision decimal string                                                                             |
| `chain`       | Source chain                                                                                                                   |
| `token`       | Deposited token (`usdc` or `usdt`)                                                                                             |
| `fromAddress` | Sender address (when available)                                                                                                |
| `txHash`      | Onchain transaction hash                                                                                                       |
| `status`      | Current status (see lifecycle table above)                                                                                     |
| `createdAt`   | When the deposit was first detected                                                                                            |
| `completedAt` | When the deposit finalized and posted (`null` while processing)                                                                |

## List deposits

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "$BASE_URL/v2/wallets/$WALLET_ID/deposits?limit=25" \
    -H "Authorization: Bearer $GROUND_API_TOKEN"
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const resp = await fetch(`${BASE_URL}/v2/wallets/${walletId}/deposits?limit=25`, {
    headers: { Authorization: `Bearer ${GROUND_API_TOKEN}` },
  });
  const { data, nextCursor } = await resp.json();
  ```
</CodeGroup>

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [
    {
      "id": "797a5ca3-2a1c-443b-b190-ca951964aa35",
      "amount": "10.000000",
      "token": "usdc",
      "chain": "ethereum_sepolia",
      "fromAddress": "0x76f8fc6667e239f83a547d4e16225d6a34f6fa22",
      "txHash": "0xe2e8a534960a7cf19932b35759788a0de4fa131d46d3e36a96a4802b6b93e5e1",
      "status": "completed",
      "createdAt": "2026-07-09T21:34:17.973Z",
      "completedAt": "2026-07-09T21:34:17.973Z"
    }
  ],
  "nextCursor": null
}
```

Supports cursor-based pagination. See [API Conventions](/docs/portfolio-wallets/api-conventions#pagination).

## Fetch a deposit by ID

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "$BASE_URL/v2/wallets/$WALLET_ID/deposits/$DEPOSIT_ID" \
  -H "Authorization: Bearer $GROUND_API_TOKEN"
```

## Look up by transaction hash

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "$BASE_URL/v2/wallets/$WALLET_ID/deposits/lookup?txHash=$TX_HASH" \
  -H "Authorization: Bearer $GROUND_API_TOKEN"
```

Optionally scope to a specific chain:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "$BASE_URL/v2/wallets/$WALLET_ID/deposits/lookup?txHash=$TX_HASH&chain=arbitrum" \
  -H "Authorization: Bearer $GROUND_API_TOKEN"
```

## Deposit webhooks

Subscribe to `portfolio_wallet.deposit.status_changed` for real-time deposit tracking. See [Webhooks](/docs/portfolio-wallets/webhooks).

## Next steps

* [Balances and Yield](/docs/portfolio-wallets/balances-and-yield) — track how deposits are allocated and earning yield
* [Withdraw Funds](/docs/portfolio-wallets/withdraw-funds) — withdraw USDC or USDT from the wallet
* [Webhooks](/docs/portfolio-wallets/webhooks) — subscribe to deposit status events