Create a Wallet

Creating a wallet is asynchronous. POST /v2/wallets returns immediately with status: "creating". Poll GET /v2/wallets/{id} for wallet activation and use only deposit addresses returned for the intended network. Address readiness is independent of wallet activity status. Stellar deposits require a separate one-time setup after the wallet becomes active.

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": "RWA Yield Portfolio",
    "strategy": {
      "allocations": {
        "usdc": [
          { "yieldSourceId": "ground-ustb-vault", "pct": 50 },
          { "yieldSourceId": "ground-jaaa-usdc-vault", "pct": 50 }
        ],
        "usdt": [
          { "yieldSourceId": "cash", "pct": 100 }
        ]
      }
    }
  }'

Field	Required	Description
`requestId`	Yes	UUID v4 idempotency key
`label`	No	Human-readable wallet name
`autoRebalance`	No	`true` for target-based allocation; `false` for manual allocation. Defaults to `true` when a strategy is provided. Required when omitting `strategy`.
`strategy`	When automatic	Object containing `allocations`; omit for `autoRebalance: false`.
`strategy.allocations`	When automatic	Targets keyed by the source catalog’s `allocationGroup`: `usdc`, `usdt`, or `usdt:tron`. Each included array must sum to 100%.

Place each yield source under its catalog allocationGroup from GET /v2/wallets/yield-sources. Use cash to keep funds uninvested in that group; omitted groups start at 100% cash. See Allocation groups for network compatibility and How Auto Rebalancing Works to choose automatic or manual allocation. The request above uses RWA sources available in the production catalog. Both production and sandbox expose ground-jaaa-usdt-vault under usdt. Sandbox also exposes token-specific JTRSY rows when returned by its live catalog: ground-jtrsy-usdc-vault belongs under usdc, and ground-jtrsy-usdt-vault belongs under usdt. Always use the live environment-specific catalog rather than assuming a row is active. 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": "RWA 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": "ground-ustb-vault", "targetWeightBps": 5000 },
      { "yieldSourceId": "ground-jaaa-usdc-vault", "targetWeightBps": 5000 }
    ],
    "usdt": [
      { "yieldSourceId": "cash", "targetWeightBps": 10000, "token": "usdt", "chain": "ethereum" }
    ]
  }
}

Polling for activation

Poll GET /v2/wallets/{id} every 1-2 seconds until the wallet becomes active or fails. The example below waits for activation; before funding, also check address readiness for the intended network:

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 wallet is active. Fund only a network whose address has appeared in depositAddresses; overall address setup can still be provisioning. See Address readiness. This example shows the addresses already available:

{
  "id": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "label": "RWA 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": "ground-ustb-vault",
      "kind": "yield_source",
      "label": "Invesco USTB tokenized by Superstate",
      "valueUsd": "0.000000",
      "yieldSourceId": "ground-ustb-vault",
      "pct": 50
    },
    {
      "id": "ground-jaaa-usdc-vault",
      "kind": "yield_source",
      "label": "Janus Henderson JAAA (USDC)",
      "valueUsd": "0.000000",
      "yieldSourceId": "ground-jaaa-usdc-vault",
      "pct": 50
    }
  ],
  "strategyAllocations": {
    "usdc": [
      { "yieldSourceId": "ground-ustb-vault", "targetWeightBps": 5000 },
      { "yieldSourceId": "ground-jaaa-usdc-vault", "targetWeightBps": 5000 }
    ],
    "usdt": [
      { "yieldSourceId": "cash", "targetWeightBps": 10000, "token": "usdt", "chain": "ethereum" }
    ]
  }
}

Sandbox ready response

Sandbox returns the same wallet shape with explicit testnet keys for its two supported USDC chains:

{
  "id": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "status": "idle",
  "depositAddresses": {
    "solana_devnet": "DmaePN7kL6WjSecMaH4urdS8zN8FwNPTxbdTqFwAw6Fd",
    "ethereum_sepolia": "0xFf71D07826d0aFcEcDF07Be9c499f9DDF3ee5cFa"
  }
}

Key fields

Field	Description
`status`	`"creating"` during wallet setup, `"idle"` when no workflow is active, `"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`	Ready per-network deposit addresses. Standard addresses appear as their setup completes. Stellar appears after its separate setup and approval.
`addressProvisioning`	General deposit address setup state: `provisioning`, `ready`, or `failed`. Independent of wallet activity status; already available addresses remain usable.
`balance.totalUsd`	Total economically owned wallet value
`balance.withdrawableUsd`	Gross amount that can be withdrawn now, before plan-specific fees
`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 allocation group. 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

Use the network-specific testnet address returned by your wallet and the supported test asset for that network. See Supported Chains for Ethereum Sepolia, Solana Devnet, Stellar Testnet, and TRON Shasta funding.

Getting Started

Wallet Lifecycle

Fees

Approvals

Monitoring & Webhooks

Security

Resources

API Reference

Create a Wallet

Create a portfolio wallet

Creating response

Polling for activation

Ready response

Sandbox ready response

Key fields

Failed response

Rebalancing

Sandbox notes

​Create a portfolio wallet

​Creating response

​Polling for activation

​Ready response

​Sandbox ready response

​Key fields

​Failed response

​Rebalancing

​Sandbox notes

Create a portfolio wallet

Creating response

Polling for activation

Ready response

Sandbox ready response

Key fields

Failed response

Rebalancing

Sandbox notes