Skip to main content
Polling is a good fit when you want a periodic reconciliation job (for example, every 1-5 minutes) and can tolerate some delay compared to webhooks.

​
Poll until wallet is ready

After creating a wallet, poll GET /v2/wallets/{id} every 1-2 seconds until status !== "creating":
cURL
while true; do
  STATUS=$(curl -s "$BASE_URL/v2/wallets/$WALLET_ID" \
    -H "Authorization: Bearer $GROUND_API_KEY" | jq -r .status)
  if [ "$STATUS" = "idle" ] || [ "$STATUS" = "failed" ]; then break; fi
  sleep 1.5
done

​
List wallets

cURL
curl -X GET "$BASE_URL/v2/wallets?limit=25" \
  -H "Authorization: Bearer $GROUND_API_KEY"
Next page:
cURL
curl -X GET "$BASE_URL/v2/wallets?limit=25&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $GROUND_API_KEY"

​
Get a single wallet

cURL
curl -X GET "$BASE_URL/v2/wallets/$WALLET_ID" \
  -H "Authorization: Bearer $GROUND_API_KEY"

​
List deposits

cURL
curl -X GET "$BASE_URL/v2/wallets/$WALLET_ID/deposits?limit=50" \
  -H "Authorization: Bearer $GROUND_API_KEY"

​
Activity feed

The activity endpoint provides a unified, reverse-chronological feed of customer-visible deposits, withdrawals, and rebalances. Omit walletId for organization-wide activity, or pass one or more walletId parameters to filter to specific wallets.
cURL
curl -X GET "$BASE_URL/v2/activity?walletId=$WALLET_ID&limit=20" \
  -H "Authorization: Bearer $GROUND_API_KEY"
Query parameters:
ParamDescription
limitMax items per page (default 20, max 100)
cursorOpaque cursor from nextCursor for pagination
walletIdOptional repeatable wallet ID filter. Omit for organization-wide activity.
typeOptional type filter: deposit, withdrawal, or rebalance
statusOptional comma-separated status filter: created, processing, completed, partially_completed, failed, cancelled, or all
To poll only active wallet work, use: 
curl -X GET "$BASE_URL/v2/activity?walletId=$WALLET_ID&status=created,processing&limit=20" \
  -H "Authorization: Bearer $GROUND_API_KEY"
Response: 
{
  "activity": [
    {
      "id": "8f9720c1-2679-4d56-afc3-9b18edb83ce2",
      "type": "deposit",
      "status": "completed",
      "amountUsd": "5000.000000",
      "timestamp": "2026-02-05T09:40:00.000Z",
      "deposit": {
        "id": "8f9720c1-2679-4d56-afc3-9b18edb83ce2",
        "amount": "5000.000000",
        "token": "usdc",
        "chain": "ethereum",
        "fromAddress": "0xfeed00000000000000000000000000000000beef",
        "txHash": "0xabc123...",
        "status": "completed",
        "createdAt": "2026-02-05T09:40:00.000Z",
        "completedAt": "2026-02-05T09:41:15.000Z"
      }
    },
    {
      "id": "11b17950-1f5c-4d36-8f0d-0f3d1d0c6a45",
      "type": "withdrawal",
      "status": "processing",
      "amountUsd": "65000.000000",
      "timestamp": "2026-02-05T11:00:00.000Z",
      "withdrawal": {
        "id": "11b17950-1f5c-4d36-8f0d-0f3d1d0c6a45",
        "amountRequestedUsd": "65000.000000",
        "amountPaidUsd": null,
        "feeUsd": "0.000000",
        "destinationChain": "ethereum",
        "destinationAddress": "0x76F8fc6667E239f83a547d4e16225d6a34f6FA22",
        "destinationToken": "usdc",
        "status": "processing",
        "legsCompleted": 0,
        "legsTotal": 1,
        "payoutLegs": [
          {
            "status": "pending_customer_approval",
            "amountUsd": "65000.000000",
            "from": { "kind": "yield_source", "id": "syrup-usdc", "label": "Syrup USDC" },
            "to": { "kind": "external_payout", "id": "external_payout:ethereum:usdc", "label": "External payout (Ethereum)" },
            "startedAt": "2026-02-05T11:00:00.000Z",
            "completedAt": null,
            "stepsCompleted": 1,
            "stepsTotal": 2,
            "steps": [
              { "label": "Redeeming from Syrup USDC", "status": "completed", "txHash": "0xdef456...", "txStatus": "confirmed" },
              { "label": "Sending payout", "status": "pending_customer_approval", "txHash": null, "txStatus": null }
            ]
          }
        ],
        "failureReason": null,
        "createdAt": "2026-02-05T11:00:00.000Z",
        "completedAt": null
      }
    },
    {
      "id": "449f9ed4-b924-4a2d-9b18-e372cc5c4d65",
      "type": "rebalance",
      "status": "created",
      "amountUsd": "12000.000000",
      "timestamp": "2026-02-05T12:00:00.000Z",
      "rebalance": {
        "id": "449f9ed4-b924-4a2d-9b18-e372cc5c4d65",
        "status": "created",
        "createdAt": "2026-02-05T12:00:00.000Z",
        "updatedAt": "2026-02-05T12:00:00.000Z",
        "startedAt": "2026-02-05T12:00:00.000Z",
        "completedAt": null,
        "legsCompleted": 0,
        "legsTotal": 1,
        "amountUsd": "12000.000000",
        "rebalanceLegs": [
          {
            "status": "created",
            "amountUsd": "12000.000000",
            "from": { "kind": "cash", "id": "cash:base:usdc", "label": "Cash (Base)" },
            "to": { "kind": "yield_source", "id": "morpho-gauntlet-usdc", "label": "Morpho Gauntlet USDC Prime" },
            "startedAt": "2026-02-05T12:00:00.000Z",
            "completedAt": null,
            "stepsCompleted": 0,
            "stepsTotal": 1,
            "steps": [
              { "label": "Depositing into Morpho Gauntlet USDC Prime", "status": "created", "txHash": null, "txStatus": null }
            ]
          }
        ],
        "failureReason": null
      }
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
FieldDescription
activity[].idUnique ID for the activity parent
activity[].type"deposit", "withdrawal", or "rebalance"
activity[].statusPublic status: created, processing, completed, failed, or cancelled
activity[].amountUsdAmount as a fixed-precision decimal string (6 decimal places)
activity[].timestampISO-8601 timestamp of when the activity occurred
activity[].depositPresent for deposit rows
activity[].withdrawalPresent for withdrawal rows
activity[].rebalancePresent for rebalance rows
nextCursorOpaque cursor for the next page, or null
hasMoreWhether more items exist beyond this page

​
List withdrawals

Filter by status to monitor in-flight withdrawals:
cURL
curl -X GET "$BASE_URL/v2/wallets/$WALLET_ID/withdrawals?status=processing&limit=50" \
  -H "Authorization: Bearer $GROUND_API_KEY"