Skip to main content
Create a wallet with a strategy object defining your yield allocation. Build the allocation manually using yield source IDs from GET /v2/wallets/yield-sources.

​
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": [
        { "yieldSourceId": "syrup-usdc", "pct": 40 },
        { "yieldSourceId": "morpho-gauntlet-usdc", "pct": 30 },
        { "yieldSourceId": "morpho-steakhouse-usdc", "pct": 30 }
      ]
    }
  }'
FieldRequiredDescription
requestIdYesUUID v4 idempotency key
labelNoHuman-readable wallet name (defaults to null if omitted)
strategyYesObject containing allocations array
strategy.allocationsYesArray of { yieldSourceId, pct }. Percentages must sum to 100.
Each allocation must include yieldSourceId from the live yield source catalog and pct (integer, 0-100). The endpoint returns 201 for a new wallet creation, or 200 for an idempotent replay of the same requestId.

​
Wallet response

The canonical wallet response (GET /v2/wallets/:id) provides a clean, neobank-style shape with balances and current positions: 
{
  "id": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "label": "Core Yield Portfolio",
  "createdAt": "2026-02-05T08:15:00Z",
  "depositAddresses": {
    "arbitrum": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "base": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "ethereum": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "polygon": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "solana": "7nYzKxM3bP4oEFbqkPmA5E2rYJ8HqKz8vFg9abc1"
  },
  "balance": {
    "totalUsd": "100000.000000",
    "withdrawableUsd": "100000.000000",
    "availableToInitiateUsd": "100000.000000",
    "pendingWithdrawalUsd": "0.000000",
    "inTransitUsd": "0.000000",
    "earnedUsd": "1250.000000"
  },
  "positions": [
    { "yieldSourceId": "syrup-usdc", "name": "Syrup USDC", "valueUsd": "40000.000000", "pct": 40 },
    { "yieldSourceId": "morpho-gauntlet-usdc", "name": "Morpho Gauntlet USDC Prime", "valueUsd": "30000.000000", "pct": 30 },
    { "yieldSourceId": "morpho-steakhouse-usdc", "name": "Morpho Steakhouse USDC Prime", "valueUsd": "30000.000000", "pct": 30 }
  ]
}

​
Key fields

FieldDescription
balance.totalUsdTotal economically owned wallet value across all positions
balance.withdrawableUsdConservative amount that can be withdrawn now
balance.availableToInitiateUsdBackwards-compatible alias of withdrawableUsd on wallet responses
balance.pendingWithdrawalUsdValue currently encumbered by active withdrawal(s)
balance.inTransitUsdValue currently in transit (e.g. funds being bridged or deployed into a yield position)
balance.earnedUsdLifetime yield earned
depositAddressesPer-chain addresses to fund the wallet (deposit rails only)
positionsCurrent holdings with USD values and target allocations per yield source

​
Rebalancing

Portfolio wallets are best-effort targets. Over time, or after deposits and withdrawals, holdings can 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). See Supported Chains for details. Request shapes are identical to production, but the live yield source catalog can differ by environment.