Quickstart

Create a wallet, deposit funds, and withdraw — all in 5 minutes.

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. This sandbox example uses the deployed USTB, stablecoin-explicit JAAA, and token-specific JTRSY rows; omit any row that is not present in your live response.

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": "RWA Yield Portfolio",
    "strategy": {
      "allocations": {
        "usdc": [
          { "yieldSourceId": "ground-ustb-vault", "pct": 34 },
          { "yieldSourceId": "ground-jaaa-usdc-vault", "pct": 33 },
          { "yieldSourceId": "ground-jtrsy-usdc-vault", "pct": 33 }
        ],
        "usdt": [
          { "yieldSourceId": "ground-jaaa-usdt-vault", "pct": 50 },
          { "yieldSourceId": "ground-jtrsy-usdt-vault", "pct": 50 }
        ]
      }
    }
  }'

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": "RWA 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": "ground-ustb-vault", "pct": 34, "kind": "yield_source", "label": "Invesco USTB tokenized by Superstate", "valueUsd": "34085.000000", "yieldSourceId": "ground-ustb-vault", "mode": "active", "apyBps": 330 },
    { "id": "ground-jaaa-usdc-vault", "pct": 33, "kind": "yield_source", "label": "Janus Henderson JAAA (USDC)", "valueUsd": "33082.500000", "yieldSourceId": "ground-jaaa-usdc-vault", "mode": "active", "apyBps": 687 },
    { "id": "ground-jtrsy-usdc-vault", "pct": 33, "kind": "yield_source", "label": "Janus Henderson JTRSY tokenized by Centrifuge", "valueUsd": "33082.500000", "yieldSourceId": "ground-jtrsy-usdc-vault", "mode": "active", "apyBps": 421 }
  ],
  "strategyAllocations": {
    "usdc": [
      { "yieldSourceId": "ground-ustb-vault", "targetWeightBps": 3400 },
      { "yieldSourceId": "ground-jaaa-usdc-vault", "targetWeightBps": 3300 },
      { "yieldSourceId": "ground-jtrsy-usdc-vault", "targetWeightBps": 3300 }
    ],
    "usdt": [
      { "yieldSourceId": "ground-jaaa-usdt-vault", "targetWeightBps": 5000 },
      { "yieldSourceId": "ground-jtrsy-usdt-vault", "targetWeightBps": 5000 }
    ]
  },
  "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",
  "processingEstimate": {
    "basis": "banking_days",
    "typicalCompletionDate": "2026-07-20",
    "typicalWindowEndDate": "2026-07-21"
  }
}

The estimate is calculated when you request the preview. Date values above are illustrative; use the response you receive when presenting withdrawal timing.

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