Create a Wallet

Create a portfolio wallet and poll for activation.

POST /v2/wallets returns the wallet immediately. Its status is creating while initial setup is in progress, or idle when a prepared wallet is available. 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. EVM, Solana, TRON, and Stellar address setup proceeds automatically. See Stellar integration for Stellar funding and approval behavior.

​

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	Cash and yield-source targets keyed by the source catalog’s allocationGroup: usdc, usdt, or usdt:tron. Stock IDs are rejected. Each included array must sum to 100%.

Place each yield source under its catalog allocationGroup from GET /v2/wallets/assets. 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. A wallet still being created has no deposit addresses and zero balances; its configured targets can already appear as zero-value positions. A prepared wallet can return immediately with its ready addresses. 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": [
    {
      "id": "ground-ustb-vault",
      "kind": "yield_source",
      "label": "Invesco USTB tokenized by Superstate",
      "chain": "ethereum",
      "token": "usdc",
      "allocationGroup": "usdc",
      "valueUsd": "0.000000",
      "withdrawableUsd": "0.000000",
      "productId": "gustb-ethereum",
      "pct": 50
    },
    {
      "id": "ground-jaaa-usdc-vault",
      "kind": "yield_source",
      "label": "Janus Henderson JAAA (USDC)",
      "chain": "ethereum",
      "token": "usdc",
      "allocationGroup": "usdc",
      "valueUsd": "0.000000",
      "withdrawableUsd": "0.000000",
      "pct": 50
    }
  ],
  "strategyAllocations": {
    "usdc": [
      {
        "yieldSourceId": "ground-ustb-vault",
        "targetWeightBps": 5000,
        "chain": "ethereum",
        "token": "usdc",
        "allocationGroup": "usdc"
      },
      {
        "yieldSourceId": "ground-jaaa-usdc-vault",
        "targetWeightBps": 5000,
        "chain": "ethereum",
        "token": "usdc",
        "allocationGroup": "usdc"
      }
    ],
    "usdt": [
      {
        "yieldSourceId": "cash",
        "targetWeightBps": 10000,
        "token": "usdt",
        "chain": "ethereum",
        "allocationGroup": "usdt"
      }
    ],
    "usdt:tron": [
      {
        "yieldSourceId": "cash",
        "targetWeightBps": 10000,
        "token": "usdt",
        "chain": "tron",
        "allocationGroup": "usdt:tron"
      }
    ]
  },
  "autoRebalance": true
}

​

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. Other networks may still be preparing their addresses. 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",
    "tron": "TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV",
    "stellar": "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF"
  },
  "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",
      "pct": 50,
      "chain": "ethereum",
      "token": "usdc",
      "allocationGroup": "usdc",
      "withdrawableUsd": "0.000000",
      "productId": "gustb-ethereum"
    },
    {
      "id": "ground-jaaa-usdc-vault",
      "kind": "yield_source",
      "label": "Janus Henderson JAAA (USDC)",
      "valueUsd": "0.000000",
      "pct": 50,
      "chain": "ethereum",
      "token": "usdc",
      "allocationGroup": "usdc",
      "withdrawableUsd": "0.000000"
    }
  ],
  "strategyAllocations": {
    "usdc": [
      {
        "yieldSourceId": "ground-ustb-vault",
        "targetWeightBps": 5000,
        "chain": "ethereum",
        "token": "usdc",
        "allocationGroup": "usdc"
      },
      {
        "yieldSourceId": "ground-jaaa-usdc-vault",
        "targetWeightBps": 5000,
        "chain": "ethereum",
        "token": "usdc",
        "allocationGroup": "usdc"
      }
    ],
    "usdt": [
      {
        "yieldSourceId": "cash",
        "targetWeightBps": 10000,
        "token": "usdt",
        "chain": "ethereum",
        "allocationGroup": "usdt"
      }
    ],
    "usdt:tron": [
      {
        "yieldSourceId": "cash",
        "targetWeightBps": 10000,
        "token": "usdt",
        "chain": "tron",
        "allocationGroup": "usdt:tron"
      }
    ]
  },
  "autoRebalance": true
}

​

Sandbox ready response

This sandbox example uses a cash strategy and shows all four automatically prepared deposit networks: Ethereum Sepolia, Solana Devnet, TRON Shasta, and Stellar Testnet. During provisioning, only ready network addresses appear:

{
  "id": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "label": "Sandbox Treasury",
  "createdAt": "2026-10-19T12:00:00.000Z",
  "status": "idle",
  "failureReason": null,
  "depositAddresses": {
    "solana_devnet": "DmaePN7kL6WjSecMaH4urdS8zN8FwNPTxbdTqFwAw6Fd",
    "ethereum_sepolia": "0xFf71D07826d0aFcEcDF07Be9c499f9DDF3ee5cFa",
    "tron_shasta": "TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV",
    "stellar_testnet": "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF"
  },
  "balance": {
    "totalUsd": "0.000000",
    "withdrawableUsd": "0.000000",
    "reservedUsd": "0.000000",
    "earnedUsd": "0.000000"
  },
  "positions": [
    {
      "id": "cash:usdc",
      "kind": "cash",
      "label": "USDC",
      "allocationGroup": "usdc",
      "token": "usdc",
      "valueUsd": "0.000000",
      "pct": 100
    }
  ],
  "strategyAllocations": {
    "usdc": [
      {
        "yieldSourceId": "cash",
        "targetWeightBps": 10000,
        "token": "usdc"
      }
    ],
    "usdt": [
      {
        "yieldSourceId": "cash",
        "targetWeightBps": 10000,
        "token": "usdt",
        "chain": "ethereum_sepolia",
        "allocationGroup": "usdt"
      }
    ],
    "usdt:tron": [
      {
        "yieldSourceId": "cash",
        "targetWeightBps": 10000,
        "token": "usdt",
        "chain": "tron_shasta",
        "allocationGroup": "usdt:tron"
      }
    ]
  },
  "autoRebalance": true
}

​

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. Addresses appear as automatic setup completes. Other returned addresses are usable immediately.
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. A yield position’s id is its public yield-source ID. allocationGroup, token, and chain identify compatible funds; pct, when present, is the target weight within the group.
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": [],
  "strategyAllocations": {},
  "autoRebalance": true
}

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.