> ## 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.

# 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](https://portal.groundtech.co), then export it below.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export BASE_URL="https://sandbox.groundtech.co"
export GROUND_API_TOKEN="your_api_token"
```

See [API Conventions](/docs/portfolio-wallets/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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://faucet.circle.com/) or bridge testnet ETH via the [Sepolia faucet](https://sepoliafaucet.com/).

## 4. Check balance and yield

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "$BASE_URL/v2/wallets/$WALLET_ID" \
  -H "Authorization: Bearer $GROUND_API_TOKEN"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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"
  }
}
```

<Note>
  Sandbox keys `depositAddresses` by explicit testnet chain (`ethereum_sepolia`, `solana_devnet`). Production uses canonical chain names (`ethereum`, `base`, `arbitrum`, `polygon`, `solana`). See [Supported Chains](/docs/portfolio-wallets/supported-chains).
</Note>

## 5. Preview a withdrawal

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
  }'
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "amountRequestedUsd": "65000.000000",
  "feeUsd": "0.000000",
  "withdrawableUsd": "100250.000000",
  "totalUsdAfterWithdrawal": "35250.000000",
  "estimatedCompletionTime": "PT2H",
  "maxCompletionTime": "PT4H"
}
```

## 6. Initiate a withdrawal

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/docs/portfolio-wallets/transaction-approvals).

## Next steps

* [API Conventions](/docs/portfolio-wallets/api-conventions) — authentication, pagination, rate limits, error codes
* [Create a Wallet](/docs/portfolio-wallets/create-wallet) — wallet lifecycle and response shape
* [Deposits](/docs/portfolio-wallets/deposits) — funding and deposit tracking
* [Withdraw Funds](/docs/portfolio-wallets/withdraw-funds) — full withdrawal lifecycle and payout legs
* [Webhooks](/docs/portfolio-wallets/webhooks) — real-time status notifications