Skip to main content
Create a wallet with a positions array defining your yield allocation strategy. You can source positions from the quote endpoint or specify them manually.

​
Create a portfolio wallet

curl -X POST "$BASE_URL/v2/portfolio-wallets" \
  -H "Authorization: Bearer $BRAID_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "0b7e3b4d-88a5-4a75-8c0f-3b7b4f9d9f1d",
    "label": "Treasury Portfolio",
    "positions": [
      { "positionKey": "usdz", "targetWeightBps": 6000 },
      { "positionKey": "rlp", "targetWeightBps": 4000 }
    ]
  }'
FieldRequiredDescription
requestIdYesUUID v4 idempotency key
labelYesHuman-readable wallet name
positionsYesArray of { positionKey, targetWeightBps }. Weights must sum to 10,000 bps.

​
Wallet statuses

StatusMeaning
creatingWallet is being provisioned (deposit addresses being generated)
activeReady to receive deposits and process withdrawals
disabledSuspended — deposits and withdrawals are blocked
archivedPermanently closed
After creation, the wallet transitions from creating to active once deposit addresses are provisioned (typically a few seconds).

​
Wallet response

{
  "id": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "label": "Treasury Portfolio",
  "createdAt": "2026-02-05T08:15:00.000Z",
  "depositAddresses": {
    "arbitrum": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "ethereum": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "base": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "polygon": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "optimism": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "solana": "So11111111111111111111111111111111111111112"
  },
  "balance": {
    "totalUsd": "82500.00",
    "withdrawableUsd": "82500.00",
    "earnedUsd": "1250.00"
  },
  "strategy": {
    "allocations": [
      { "positionKey": "usdz", "pct": 60 },
      { "positionKey": "rlp", "pct": 40 }
    ],
    "status": "aligned"
  },
  "positions": [
    { "positionKey": "usdz", "name": "Anzen USDz", "valueUsd": "52500.00" },
    { "positionKey": "rlp", "name": "Resolv LP", "valueUsd": "30000.00" }
  ]
}
FieldDescription
balance.totalUsdTotal wallet value (principal + yield) across all positions
balance.withdrawableUsdUnreserved balance available for withdrawal
balance.earnedUsdCumulative yield earned
depositAddressesPer-chain deposit addresses (supported chains)
strategy.allocationsTarget allocations (positionKey + pct percentage)
strategy.statusaligned (holdings match targets) or rebalancing (drift correction in progress)
positionsCurrent holdings with USD values per yield source

​
Rebalancing and drift

Portfolio wallets use best-effort target weights. Over time (or after deposits/withdrawals), holdings can drift from targets. The strategy.status field shows whether the wallet is aligned or rebalancing. The system periodically rebalances to bring positions back toward target weights. The drift trigger threshold is 200 bps. For more on cash positions and how undeployed funds are handled, see Balances and Yield. For the relationship between bridge domains and withdrawal sourcing, see Bridge domains.

​
List wallets

curl "$BASE_URL/v2/portfolio-wallets?limit=25" \
  -H "Authorization: Bearer $BRAID_API_TOKEN"
Returns a paginated list of wallets: 
{
  "data": [
    {
      "id": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
      "label": "Treasury Portfolio",
      "createdAt": "2026-02-05T08:15:00.000Z",
      "balance": {
        "totalUsd": "82500.00",
        "withdrawableUsd": "82500.00",
        "earnedUsd": "1250.00"
      },
      "strategy": {
        "allocations": [
          { "positionKey": "usdz", "pct": 60 },
          { "positionKey": "rlp", "pct": 40 }
        ],
        "status": "aligned"
      }
    }
  ],
  "nextCursor": null
}
See API Conventions for pagination parameters.

​
Look up a wallet

Look up a wallet by requestId or label: 
curl "$BASE_URL/v2/portfolio-wallets/lookup?requestId=$REQUEST_ID" \
  -H "Authorization: Bearer $BRAID_API_TOKEN"

curl "$BASE_URL/v2/portfolio-wallets/lookup?label=Treasury%20Portfolio" \
  -H "Authorization: Bearer $BRAID_API_TOKEN"

​
Sandbox notes

In sandbox, depositAddresses.ethereum is a Sepolia address and depositAddresses.solana is a Solana devnet address. Position keys and request shapes are identical to production. usdz is simulated in sandbox because USDZ is not available on testnets. The positionKey remains usdz for integration parity.

​
Next steps