Portfolio Wallets Quickstart

This quickstart walks through listing available yield sources, creating a Portfolio Wallet, waiting for it to activate, funding it via its deposit addresses, checking balances, and withdrawing.

Prerequisites

Set your base URL and API token once, then reuse them for every request. Use sandbox while you build, then switch to production by swapping the base URL. The endpoint structure stays the same, but sandbox uses explicit testnet chain keys such as ethereum_sepolia.

cURL

export BASE_URL="https://sandbox.groundtech.co"
export GROUND_API_KEY="your_api_token"

Conventions

JSON field names are camelCase.
Enum-like string values (for example status, type, and webhook event/eventTypes) are lower_snake_case.
- Example: payoutLeg.status = pending_customer_approval

1. List available yield sources

Fetch the yield sources you can allocate to. Each yield source has a stable id you will use as yieldSourceId when creating a wallet.

cURL

curl -X GET "$BASE_URL/v2/wallets/yield-sources" \
  -H "Authorization: Bearer $GROUND_API_KEY"

The response contains the catalog in its data array. Note each source’s id and apyBps to decide your allocation.

2. Create a portfolio wallet

Create a Portfolio Wallet by passing strategy.allocations with your chosen yield allocation. Allocation percentages must sum to 100.

cURL

curl -X POST "$BASE_URL/v2/wallets" \
  -H "Authorization: Bearer $GROUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "123e4567-e89b-42d3-a456-426614174000",
    "label": "Core Yield Portfolio",
    "strategy": {
      "allocations": [
        { "yieldSourceId": "syrup-usdc", "pct": 35 },
        { "yieldSourceId": "morpho-gauntlet-usdc", "pct": 35 },
        { "yieldSourceId": "morpho-steakhouse-usdc", "pct": 30 }
      ]
    }
  }'

const res = await fetch(`${BASE_URL}/v2/wallets`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${GROUND_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    requestId: "123e4567-e89b-42d3-a456-426614174000",
    label: "Core Yield Portfolio",
    strategy: {
      allocations: [
        { yieldSourceId: "syrup-usdc", pct: 35 },
        { yieldSourceId: "morpho-gauntlet-usdc", pct: 35 },
        { yieldSourceId: "morpho-steakhouse-usdc", pct: 30 },
      ],
    },
  }),
});

console.log(await res.json());

import requests

res = requests.post(
    f"{BASE_URL}/v2/wallets",
    headers={"Authorization": f"Bearer {GROUND_API_KEY}"},
    json={
        "requestId": "123e4567-e89b-42d3-a456-426614174000",
        "label": "Core Yield Portfolio",
        "strategy": {
            "allocations": [
                {"yieldSourceId": "syrup-usdc", "pct": 35},
                {"yieldSourceId": "morpho-gauntlet-usdc", "pct": 35},
                {"yieldSourceId": "morpho-steakhouse-usdc", "pct": 30},
            ],
        },
    },
)

print(res.json())

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	baseURL := os.Getenv("BASE_URL")
	apiToken := os.Getenv("GROUND_API_KEY")

	payload := map[string]any{
		"requestId": "123e4567-e89b-42d3-a456-426614174000",
		"label":     "Core Yield Portfolio",
		"strategy": map[string]any{
			"allocations": []map[string]any{
				{"yieldSourceId": "syrup-usdc", "pct": 35},
				{"yieldSourceId": "morpho-gauntlet-usdc", "pct": 35},
				{"yieldSourceId": "morpho-steakhouse-usdc", "pct": 30},
			},
		},
	}

	bodyBytes, _ := json.Marshal(payload)
	req, _ := http.NewRequest("POST", fmt.Sprintf("%s/v2/wallets", baseURL), bytes.NewReader(bodyBytes))
	req.Header.Set("Authorization", "Bearer "+apiToken)
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

The v2 request shape uses token-keyed allocation groups with yieldSourceId and pct. Wallet creation is asynchronous. The POST response returns immediately with status: "creating" and the wallet id, but depositAddresses are not yet available — they are populated once provisioning completes. Save the wallet id for the remaining steps:

cURL

export WALLET_ID="<wallet_id_from_create_response>"

3. Wait for the wallet to activate

Poll GET /v2/wallets/{id} every 1-2 seconds until status === "idle". Only then are depositAddresses populated. If status === "failed", inspect failureReason and retry creation with a new requestId. See Polling → Poll until wallet is active for a ready-to-paste snippet in cURL, Node, and Python.

4. Deposit actual funds

Once the wallet is active, grab the chain-specific deposit address from the poll response and send a stablecoin transfer from your custody to that address.

Plain

to:    <depositAddresses.arbitrum>   (the 0x address from the GET wallet response after status becomes idle)
chain: arbitrum
token: usdc
amount: 50,000.00

5. Await Deposit Confirmation

Deposits are detected on-chain and then processed. You can track the latest deposit status either by polling the deposits endpoints or by subscribing to webhooks. Poll (REST):

List deposits for a wallet: GET /v2/wallets/{id}/deposits
Fetch a single deposit: GET /v2/wallets/{id}/deposits/{depositId}

Example:

cURL

curl -X GET "$BASE_URL/v2/wallets/$WALLET_ID/deposits?limit=25" \
  -H "Authorization: Bearer $GROUND_API_KEY"

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	baseURL := os.Getenv("BASE_URL")
	apiToken := os.Getenv("GROUND_API_KEY")
	walletID := os.Getenv("WALLET_ID")

	req, _ := http.NewRequest(
		"GET",
		fmt.Sprintf("%s/v2/wallets/%s/deposits?limit=25", baseURL, walletID),
		nil,
	)
	req.Header.Set("Authorization", "Bearer "+apiToken)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

Webhook events:

portfolio_wallet.deposit.status_changed

Possible deposit statuses (deposit.status):

processing
completed
failed

6. Fetch the updated balance

Fetch the wallet to see current balances after the deposit is processed. Key fields in the response:

balance.totalUsd — total wallet value across positions, cash, and accrued yield
balance.withdrawableUsd — conservative amount the customer can withdraw now
balance.reservedUsd — customer-owned value currently reserved by active withdrawals or rebalances
balance.earnedUsd — lifetime yield earned since wallet creation
positions[] — current cash, bridge, and yield-source balances. Yield-source positions include target allocations.

cURL

curl -X GET "$BASE_URL/v2/wallets/$WALLET_ID" \
  -H "Authorization: Bearer $GROUND_API_KEY"

7. Withdraw (including the signing flow)

Ground uses Turnkey to manage signing flows, but you do not need a relationship with Turnkey to sign approvals.

Initiate a withdrawal. 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 Ground Turnkey approval endpoints.

cURL

curl -X POST "$BASE_URL/v2/wallets/$WALLET_ID/withdrawals" \
  -H "Authorization: Bearer $GROUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "df8b7be6-e110-4f6d-9b2d-7c44a5b1f0b0",
    "destinationChain": "ethereum_sepolia",
    "amountUsd": 65000,
    "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
  }'

const res = await fetch(`${BASE_URL}/v2/wallets/${WALLET_ID}/withdrawals`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${GROUND_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    requestId: "df8b7be6-e110-4f6d-9b2d-7c44a5b1f0b0",
    destinationChain: "ethereum_sepolia",
    amountUsd: 65000,
    destinationAddress: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  }),
});

console.log(await res.json());

import requests

res = requests.post(
    f"{BASE_URL}/v2/wallets/{WALLET_ID}/withdrawals",
    headers={"Authorization": f"Bearer {GROUND_API_KEY}"},
    json={
        "requestId": "df8b7be6-e110-4f6d-9b2d-7c44a5b1f0b0",
        "destinationChain": "ethereum_sepolia",
        "amountUsd": 65000,
        "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    },
)

print(res.json())

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	baseURL := os.Getenv("BASE_URL")
	apiToken := os.Getenv("GROUND_API_KEY")
	walletID := os.Getenv("WALLET_ID")

	payload := map[string]any{
		"requestId":          "df8b7be6-e110-4f6d-9b2d-7c44a5b1f0b0",
		"destinationChain":   "ethereum_sepolia",
		"amountUsd":          65000,
		"destinationAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
	}

	bodyBytes, _ := json.Marshal(payload)
	req, _ := http.NewRequest("POST", fmt.Sprintf("%s/v2/wallets/%s/withdrawals", baseURL, walletID), bytes.NewReader(bodyBytes))
	req.Header.Set("Authorization", "Bearer "+apiToken)
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

Save the id from the response (this is the withdrawal id used for status checks):

cURL

export WITHDRAWAL_ID="<withdrawal_id_from_withdraw_response>"

Customer approvals are completed in Ground Portal or through the Ground Turnkey approval endpoints: fetch GET /v2/turnkey/activities/pending, request POST /v2/turnkey/activity-approval-request, stamp the returned payload locally, then submit POST /v2/turnkey/activities/{activityId}/vote. See Transaction Approvals for verification checks and approval patterns.

8. Await Withdrawal Confirmation

After approval (if required), the withdrawal is kicked off automatically. You can track the latest withdrawal status either by polling the withdrawal endpoint or by subscribing to webhooks. Poll (REST):

cURL

curl -X GET "$BASE_URL/v2/wallets/$WALLET_ID/withdrawals/$WITHDRAWAL_ID" \
  -H "Authorization: Bearer $GROUND_API_KEY"

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	baseURL := os.Getenv("BASE_URL")
	apiToken := os.Getenv("GROUND_API_KEY")
	walletID := os.Getenv("WALLET_ID")
	withdrawalID := os.Getenv("WITHDRAWAL_ID")

	req, _ := http.NewRequest(
		"GET",
		fmt.Sprintf("%s/v2/wallets/%s/withdrawals/%s", baseURL, walletID, withdrawalID),
		nil,
	)
	req.Header.Set("Authorization", "Bearer "+apiToken)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

Webhook events:

portfolio_wallet.rebalance.status_changed (cash deployment and strategy adjustment progress)
portfolio_wallet.withdrawal.status_changed
portfolio_wallet.withdrawal.payout.status_changed (per-leg payouts)

Possible withdrawal statuses (withdrawal.status):

processing
partially_completed
completed
failed
cancelled

Possible payout leg statuses (withdrawal.payoutLegs[].status) and payout step states (withdrawal.payoutLegs[].steps[].state):

processing
created
pending_customer_approval
completed
failed
cancelled

Webhook payout and rebalance payloads include per-step workflow metadata such as name, chain, state, txKind, stepKind, protocolType, and sequenceRole. txHash is included when a broadcast transaction hash is available. For more detail, see Transaction Approvals and the API Reference withdrawal endpoints.

Getting Started

Wallet Lifecycle

Approvals

Monitoring & Webhooks

Security

Resources

Portfolio Wallets Quickstart

Prerequisites

Conventions

1. List available yield sources

2. Create a portfolio wallet

3. Wait for the wallet to activate

4. Deposit actual funds

5. Await Deposit Confirmation

6. Fetch the updated balance

7. Withdraw (including the signing flow)

8. Await Withdrawal Confirmation

​Prerequisites

​Conventions

​1. List available yield sources

​2. Create a portfolio wallet

​3. Wait for the wallet to activate

​4. Deposit actual funds

​5. Await Deposit Confirmation

​6. Fetch the updated balance

​7. Withdraw (including the signing flow)

​8. Await Withdrawal Confirmation

Prerequisites

Conventions

1. List available yield sources

2. Create a portfolio wallet

3. Wait for the wallet to activate

4. Deposit actual funds

5. Await Deposit Confirmation

6. Fetch the updated balance

7. Withdraw (including the signing flow)

8. Await Withdrawal Confirmation