Deposits

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.

to:    0x21246509968c4d24611f414560971AEc2e3A079B
chain: ethereum
token: USDC

Minimum amounts

There is no minimum deposit amount. However, small deposits may remain as undeployed cash 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.

Sandbox

Use the explicit sandbox key depositAddresses.ethereum_sepolia. Fund it with Sepolia USDC from the Circle faucet.
Use depositAddresses.solana_devnet for Solana Devnet USDC deposits.
To receive Ground’s mock USDT on Ethereum Sepolia, request it from the sandbox faucet for depositAddresses.ethereum_sepolia, then poll the request until it is confirmed.
Sandbox USDT uses Ground’s mock token. 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. Wallets with automatic rebalancing deploy cash toward percentage targets. Otherwise deposits stay in cash until the partner calls /allocate.

Deposit response

Ethereum Sepolia

{
  "id": "797a5ca3-2a1c-443b-b190-ca951964aa35",
  "walletId": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "amount": "10.000000",
  "token": "usdc",
  "chain": "ethereum_sepolia",
  "fromAddress": "0x76f8fc6667e239f83a547d4e16225d6a34f6fa22",
  "txHash": "0xe2e8a534960a7cf19932b35759788a0de4fa131d46d3e36a96a4802b6b93e5e1",
  "status": "completed",
  "cashPositionId": "cash:ethereum_sepolia:usdc",
  "createdAt": "2026-07-09T21:34:17.973Z",
  "completedAt": "2026-07-09T21:34:17.973Z"
}

Solana Devnet

Solana responses use base58 addresses and transaction signatures while preserving the same deposit shape:

{
  "id": "797a5ca3-2a1c-443b-b190-ca951964aa36",
  "walletId": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "amount": "10.000000",
  "token": "usdc",
  "chain": "solana_devnet",
  "fromAddress": "DmaePN7kL6WjSecMaH4urdS8zN8FwNPTxbdTqFwAw6Fd",
  "txHash": "yTeUkZfSRTRZRdp9UcwRRMtqbeeViAFRWKiTLapi2qPrd7omYfatYsEt2Cak2rFoGDEuLeBPQJPjn7YF88yyWRZ",
  "status": "completed",
  "cashPositionId": "cash:solana_devnet:usdc",
  "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`
`walletId`	Portfolio wallet credited by the deposit
`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)
`cashPositionId`	Credited cash position ID, or `null` until the deposit completes
`createdAt`	When the deposit was first detected
`completedAt`	When the deposit finalized and posted (`null` while processing)

List deposits

curl "$BASE_URL/v2/wallets/$WALLET_ID/deposits?limit=25" \
  -H "Authorization: Bearer $GROUND_API_TOKEN"

const resp = await fetch(`${BASE_URL}/v2/wallets/${walletId}/deposits?limit=25`, {
  headers: { Authorization: `Bearer ${GROUND_API_TOKEN}` },
});
const { data, nextCursor } = await resp.json();

{
  "data": [
    {
      "id": "797a5ca3-2a1c-443b-b190-ca951964aa35",
      "walletId": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
      "amount": "10.000000",
      "token": "usdc",
      "chain": "ethereum_sepolia",
      "fromAddress": "0x76f8fc6667e239f83a547d4e16225d6a34f6fa22",
      "txHash": "0xe2e8a534960a7cf19932b35759788a0de4fa131d46d3e36a96a4802b6b93e5e1",
      "status": "completed",
      "cashPositionId": "cash:ethereum_sepolia:usdc",
      "createdAt": "2026-07-09T21:34:17.973Z",
      "completedAt": "2026-07-09T21:34:17.973Z"
    }
  ],
  "nextCursor": null
}

Supports cursor-based pagination. See API Conventions.

Fetch a deposit by ID

curl "$BASE_URL/v2/wallets/$WALLET_ID/deposits/$DEPOSIT_ID" \
  -H "Authorization: Bearer $GROUND_API_TOKEN"

Look up by transaction hash

curl "$BASE_URL/v2/wallets/$WALLET_ID/deposits/lookup?txHash=$TX_HASH" \
  -H "Authorization: Bearer $GROUND_API_TOKEN"

Optionally scope to a specific chain:

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.

Next steps

Balances and Yield — track how deposits are allocated and earning yield
Withdraw Funds — withdraw USDC or USDT from the wallet
Webhooks — subscribe to deposit status events

Getting Started

Wallet Lifecycle

Approvals

Monitoring & Webhooks

Security

Resources

Fund the wallet

Minimum amounts

Sandbox

Deposit lifecycle

Deposit response

Ethereum Sepolia

Solana Devnet

List deposits

Fetch a deposit by ID

Look up by transaction hash

Deposit webhooks

Next steps

​Fund the wallet

​Minimum amounts

​Sandbox

​Deposit lifecycle

​Deposit response

​Ethereum Sepolia

​Solana Devnet

​List deposits

​Fetch a deposit by ID

​Look up by transaction hash

​Deposit webhooks

​Next steps

Fund the wallet

Minimum amounts

Sandbox

Deposit lifecycle

Deposit response

Ethereum Sepolia

Solana Devnet

List deposits

Fetch a deposit by ID

Look up by transaction hash

Deposit webhooks

Next steps