Skip to main content

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.

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": [
        { "yieldSourceId": "syrup-usdc", "pct": 40 },
        { "yieldSourceId": "morpho-gauntlet-usdc", "pct": 30 },
        { "yieldSourceId": "morpho-steakhouse-usdc", "pct": 30 }
      ]
    }
  }'
The response includes depositAddresses — one per supported chain.

​
3. Deposit USDC

Send USDC to the wallet’s deposit address on any supported chain. In sandbox, use Sepolia USDC on Ethereum. 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",
  "createdAt": "2026-02-05T08:15:00.000Z",
  "depositAddresses": {
    "arbitrum": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "ethereum": "0x21246509968c4d24611f414560971AEc2e3A079B"
  },
  "balance": {
    "totalUsd": "100000.000000",
    "withdrawableUsd": "100000.000000",
    "reservedUsd": "0.000000",
    "earnedUsd": "1250.000000"
  },
  "positions": [
    { "id": "syrup-usdc", "kind": "yield_source", "label": "Syrup USDC", "valueUsd": "40000.000000", "pct": 40 },
    { "id": "morpho-gauntlet-usdc", "kind": "yield_source", "label": "Morpho Gauntlet USDC Prime", "valueUsd": "30000.000000", "pct": 30 },
    { "id": "morpho-steakhouse-usdc", "kind": "yield_source", "label": "Morpho Steakhouse USDC Prime", "valueUsd": "30000.000000", "pct": 30 }
  ]
}

​
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": "polygon",
    "amountUsd": 65000
  }'

{
  "amountRequestedUsd": "65000.000000",
  "feeUsd": "0.000000",
  "withdrawableUsd": "82500.000000",
  "totalUsdAfterWithdrawal": "35000.000000",
  "estimatedCompletionTime": "PT2H"
}

​
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",
    "amountUsd": 65000,
    "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 pending, processing, and a terminal status such as completed, failed, or cancelled. If approval is required, a payout leg and its external payout step enter pending_customer_approval; fetch /turnkey/activities/pending for the Turnkey activity to approve. See Transaction Approvals.

​
Next steps