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. 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. Save the wallet ID and poll GET /v2/wallets/{id} for the deposit address on your intended network. Wallet activity status and address readiness are independent: an idle wallet may still be provisioning addresses, and a returned network address is usable while other addresses are being prepared. Stellar requires a separate deposit setup. Follow address readiness and use the returned network address before funding.

3. Deposit a stablecoin

Send a supported stablecoin to the returned address for your chosen network. First check address readiness; in sandbox, use that network’s supported test asset. 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, stellar_testnet, and tron_shasta). Production uses canonical chain names (ethereum, base, arbitrum, polygon, solana, stellar, and tron). Stellar mainnet is available in beta for enabled production environments. Stellar addresses appear only after their one-time setup. Use the mock USDT faucet if you need test USDT on Ethereum Sepolia. 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",
  "partnerFeeUsd": "0.000000",
  "amountToReceiveUsd": "65000.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

Getting Started

Wallet Lifecycle

Fees

Approvals

Monitoring & Webhooks

Security

Resources

API Reference

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