Create a Wallet

Creating a wallet is asynchronous. POST /v2/wallets returns immediately with status: "creating". Deposit addresses and on-chain state are not populated synchronously — poll GET /v2/wallets/{id} until status becomes "idle".

Create a portfolio wallet

curl -X POST "$BASE_URL/v2/wallets" \
  -H "Authorization: Bearer $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": 50 },
          { "yieldSourceId": "morpho-gauntlet-usdc", "pct": 50 }
        ],
        "usdt": [
          { "yieldSourceId": "cash", "pct": 100 }
        ]
      }
    }
  }'

Field	Required	Description
`requestId`	Yes	UUID v4 idempotency key
`label`	No	Human-readable wallet name
`strategy`	Yes	Object containing `allocations`
`strategy.allocations`	Yes	An object keyed by `usdc` and/or `usdt`. Each included array must sum to 100%.

Place each yield source under the token it accepts, as shown by its depositToken in GET /v2/wallets/yield-sources. Use cash to keep funds uninvested in that token. If you omit USDC or USDT when creating a wallet, that token defaults to 100% cash. A first POST with a new requestId returns 200 OK with a minimal creating envelope (no deposit addresses, zero balances). An idempotent replay with the same requestId and an identical payload returns 200 OK with the wallet’s current state. Reusing a requestId with a divergent payload (different label or allocations) returns 409 request_id_conflict — use a fresh requestId for a genuinely new wallet. See Idempotency for the full comparison rules.

Creating response

{
  "id": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "label": "Core Yield Portfolio",
  "status": "creating",
  "failureReason": null,
  "createdAt": "2026-02-05T08:15:00Z",
  "depositAddresses": {},
  "balance": {
    "totalUsd": "0.000000",
    "withdrawableUsd": "0.000000",
    "reservedUsd": "0.000000",
    "earnedUsd": "0.000000"
  },
  "positions": [],
  "strategyAllocations": {
    "usdc": [
      { "yieldSourceId": "syrup-usdc", "targetWeightBps": 5000 },
      { "yieldSourceId": "morpho-gauntlet-usdc", "targetWeightBps": 5000 }
    ],
    "usdt": [
      { "yieldSourceId": "cash", "targetWeightBps": 10000, "token": "usdt", "chain": "ethereum" }
    ]
  }
}

Polling for activation

Poll GET /v2/wallets/{id} every 1-2 seconds until status !== "creating":

async function waitUntilReady(walletId, apiToken) {
  while (true) {
    const res = await fetch(`${BASE_URL}/v2/wallets/${walletId}`, {
      headers: { Authorization: `Bearer ${apiToken}` },
    });
    const wallet = await res.json();
    if (wallet.status === "idle") return wallet;
    if (wallet.status === "failed") {
      throw new Error(`wallet ${walletId} failed: ${wallet.failureReason}`);
    }
    await new Promise((r) => setTimeout(r, 1500));
  }
}

See Polling for more on the poll pattern.

Ready response

Once status === "idle", the response is ready for deposits:

{
  "id": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "label": "Core Yield Portfolio",
  "status": "idle",
  "failureReason": null,
  "createdAt": "2026-02-05T08:15:00Z",
  "depositAddresses": {
    "arbitrum": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "base": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "ethereum": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "polygon": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "solana": "7nYzKxM3bP4oEFbqkPmA5E2rYJ8HqKz8vFg9abc1"
  },
  "balance": {
    "totalUsd": "0.000000",
    "withdrawableUsd": "0.000000",
    "reservedUsd": "0.000000",
    "earnedUsd": "0.000000"
  },
  "positions": [
    {
      "id": "syrup-usdc",
      "kind": "yield_source",
      "label": "Syrup USDC",
      "valueUsd": "0.000000",
      "yieldSourceId": "syrup-usdc",
      "pct": 50
    },
    {
      "id": "morpho-gauntlet-usdc",
      "kind": "yield_source",
      "label": "Morpho Gauntlet USDC Prime",
      "valueUsd": "0.000000",
      "yieldSourceId": "morpho-gauntlet-usdc",
      "pct": 50
    }
  ],
  "strategyAllocations": {
    "usdc": [
      { "yieldSourceId": "syrup-usdc", "targetWeightBps": 5000 },
      { "yieldSourceId": "morpho-gauntlet-usdc", "targetWeightBps": 5000 }
    ],
    "usdt": [
      { "yieldSourceId": "cash", "targetWeightBps": 10000, "token": "usdt", "chain": "ethereum" }
    ]
  }
}

Key fields

Field	Description
`status`	`"creating"` during provisioning, `"idle"` when ready, `"withdrawal_active"` / `"rebalance_active"` / `"withdrawal_and_rebalance_active"` while work is running, `"failed"` if setup terminated
`failureReason`	Populated only when `status === "failed"` — short human-readable reason
`depositAddresses`	Per-chain addresses to fund the wallet. Empty until `status === "idle"`.
`balance.totalUsd`	Total economically owned wallet value
`balance.withdrawableUsd`	Amount that can be withdrawn now
`balance.reservedUsd`	Customer-owned value currently reserved by active withdrawals or rebalances
`balance.earnedUsd`	Lifetime yield earned (monotonic)
`positions`	Current cash and yield-source holdings with USD values. Yield-source positions include `yieldSourceId` and `pct`; configured cash allocations may also include `pct`.
`strategyAllocations`	Desired targets grouped by stablecoin. Target weights use basis points and each returned group totals 10,000.

Failed response

If wallet setup fails terminally, GET /v2/wallets/{id} returns:

{
  "id": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "label": "Core Yield Portfolio",
  "status": "failed",
  "failureReason": "Turnkey create_wallet activity ACTIVITY_STATUS_REJECTED: act_abc",
  "createdAt": "2026-02-05T08:15:00Z",
  "depositAddresses": {},
  "balance": { "totalUsd": "0.000000", "withdrawableUsd": "0.000000", "reservedUsd": "0.000000", "earnedUsd": "0.000000" },
  "positions": []
}

Failed wallets cannot be recovered by retrying the same requestId. Create a new wallet with a fresh requestId and contact support if the failure reason is unclear.

Rebalancing

Portfolio wallets are best-effort targets. Over time, or after deposits and withdrawals, holdings drift from target allocations. The system rebalances to bring positions back toward the strategy targets. Deposits first appear as cash and are then deployed into the configured yield sources.

Sandbox notes

In sandbox, deposit address keys include the network suffix (e.g. ethereum_sepolia instead of ethereum). Sandbox USDT uses a Ground-owned mock contract. See Supported Chains for details.

Getting Started

Wallet Lifecycle

Approvals

Monitoring & Webhooks

Security

Resources

Create a Wallet

Create a portfolio wallet

Creating response

Polling for activation

Ready response

Key fields

Failed response

Rebalancing

Sandbox notes

​Create a portfolio wallet

​Creating response

​Polling for activation

​Ready response

​Key fields

​Failed response

​Rebalancing

​Sandbox notes

Create a portfolio wallet

Creating response

Polling for activation

Ready response

Key fields

Failed response

Rebalancing

Sandbox notes