Quickstart

This quickstart walks through the full Portfolio Wallet lifecycle: reviewing yield sources, creating a wallet, funding it, and initiating a withdrawal.

Prerequisites

Create your API key at portal.groundtech.co, then export it below.

export BASE_URL="https://sandbox.groundtech.co"
export GROUND_API_TOKEN="your_api_token"

See API Conventions for authentication, pagination, rate limits, and error handling.

1. Review the yield source catalog

Fetch the current yield source catalog, then decide the allocation you want to use for wallet creation.

curl -X GET "$BASE_URL/v2/wallets/yield-sources" \
  -H "Authorization: Bearer $GROUND_API_TOKEN"

2. Create a Portfolio Wallet

Choose the allocation strategy you’d like for your wallet:

curl -X POST "$BASE_URL/v2/wallets" \
  -H "Authorization: Bearer $GROUND_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "0b7e3b4d-88a5-4a75-8c0f-3b7b4f9d9f1d",
    "label": "Core Yield Portfolio",
    "strategy": {
      "allocations": {
        "usdc": [
          { "yieldSourceId": "syrup-usdc", "pct": 40 },
          { "yieldSourceId": "morpho-gauntlet-usdc", "pct": 30 },
          { "yieldSourceId": "morpho-steakhouse-usdc", "pct": 30 }
        ],
        "usdt": [
          { "yieldSourceId": "cash", "pct": 100 }
        ]
      }
    }
  }'

The create response returns immediately with status: "creating" and an empty depositAddresses object. Poll GET /v2/wallets/{id} until status is "idle"; the ready wallet response includes depositAddresses keyed by supported chain.

3. Deposit a stablecoin

Send USDC on a supported chain or USDT on Ethereum to the wallet’s deposit address. In sandbox, use Sepolia USDC or Ground’s mock Sepolia USDT. Do not send public testnet USDT to the sandbox mock-token integration. You can get Sepolia USDC from the Circle faucet or bridge testnet ETH via the Sepolia faucet.

4. Check balance and yield

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

{
  "id": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "label": "Core Yield Portfolio",
  "status": "idle",
  "balance": {
    "totalUsd": "100250.000000",
    "earnedUsd": "250.000000",
    "reservedUsd": "0.000000",
    "withdrawableUsd": "100250.000000"
  },
  "createdAt": "2026-02-05T08:15:00.000Z",
  "positions": [
    { "id": "cash:ethereum_sepolia:usdc", "kind": "cash", "label": "Cash (Ethereum Sepolia)", "valueUsd": "0.000000" },
    { "id": "syrup-usdc", "pct": 40, "kind": "yield_source", "label": "Syrup USDC", "valueUsd": "40100.000000", "yieldSourceId": "syrup-usdc", "mode": "active", "apyBps": 491 },
    { "id": "morpho-gauntlet-usdc", "pct": 30, "kind": "yield_source", "label": "Morpho Gauntlet USDC Prime", "valueUsd": "30075.000000", "yieldSourceId": "morpho-gauntlet-usdc", "mode": "active", "apyBps": 500 },
    { "id": "morpho-steakhouse-usdc", "pct": 30, "kind": "yield_source", "label": "Morpho Steakhouse USDC Prime", "valueUsd": "30075.000000", "yieldSourceId": "morpho-steakhouse-usdc", "mode": "active", "apyBps": 500 }
  ],
  "strategyAllocations": {
    "usdc": [
      { "yieldSourceId": "syrup-usdc", "targetWeightBps": 4000 },
      { "yieldSourceId": "morpho-gauntlet-usdc", "targetWeightBps": 3000 },
      { "yieldSourceId": "morpho-steakhouse-usdc", "targetWeightBps": 3000 }
    ],
    "usdt": [
      { "yieldSourceId": "cash", "targetWeightBps": 10000, "token": "usdt", "chain": "ethereum_sepolia" }
    ]
  },
  "failureReason": null,
  "depositAddresses": {
    "solana_devnet": "DmaePN7kL6WjSecMaH4urdS8zN8FwNPTxbdTqFwAw6Fd",
    "ethereum_sepolia": "0xFf71D07826d0aFcEcDF07Be9c499f9DDF3ee5cFa"
  }
}

Sandbox keys depositAddresses by explicit testnet chain (ethereum_sepolia, solana_devnet). Production uses canonical chain names (ethereum, base, arbitrum, polygon, solana). See Supported Chains.

5. Preview a withdrawal

curl -X POST "$BASE_URL/v2/wallets/$WALLET_ID/withdrawal-preview" \
  -H "Authorization: Bearer $GROUND_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationChain": "ethereum_sepolia",
    "amountUsd": 65000,
    "token": "usdc"
  }'

{
  "amountRequestedUsd": "65000.000000",
  "feeUsd": "0.000000",
  "withdrawableUsd": "100250.000000",
  "totalUsdAfterWithdrawal": "35250.000000",
  "estimatedCompletionTime": "PT2H",
  "maxCompletionTime": "PT4H"
}

6. Initiate a withdrawal

curl -X POST "$BASE_URL/v2/wallets/$WALLET_ID/withdrawals" \
  -H "Authorization: Bearer $GROUND_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "df8b7be6-e110-4f6d-9b2d-7c44a5b1f0b0",
    "destinationChain": "ethereum_sepolia",
    "amountUsd": 65000,
    "token": "usdc",
    "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
  }'

7. Track the withdrawal

Poll the withdrawal or subscribe to webhooks:

curl "$BASE_URL/v2/wallets/$WALLET_ID/withdrawals/$WITHDRAWAL_ID" \
  -H "Authorization: Bearer $GROUND_API_TOKEN"

The withdrawal moves through processing and then a terminal status such as completed, partially_completed, failed, or cancelled. If approval is required, a payout leg and its external payout step enter pending_customer_approval; complete the approval in Ground Portal or through the approval integration enabled for your organization. See Transaction Approvals.

Next steps

API Conventions — authentication, pagination, rate limits, error codes
Create a Wallet — wallet lifecycle and response shape
Deposits — funding and deposit tracking
Withdraw Funds — full withdrawal lifecycle and payout legs
Webhooks — real-time status notifications

Getting Started

Wallet Lifecycle

Approvals

Monitoring & Webhooks

Security

Resources

Prerequisites

1. Review the yield source catalog

2. Create a Portfolio Wallet

3. Deposit a stablecoin

4. Check balance and yield

5. Preview a withdrawal

6. Initiate a withdrawal

7. Track the withdrawal

Next steps

​Prerequisites

​1. Review the yield source catalog

​2. Create a Portfolio Wallet

​3. Deposit a stablecoin

​4. Check balance and yield

​5. Preview a withdrawal

​6. Initiate a withdrawal

​7. Track the withdrawal

​Next steps

Prerequisites

1. Review the yield source catalog

2. Create a Portfolio Wallet

3. Deposit a stablecoin

4. Check balance and yield

5. Preview a withdrawal

6. Initiate a withdrawal

7. Track the withdrawal

Next steps