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

```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": "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](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": "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"
  }
}
```

<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",
  "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

```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