Create wallet

POST/v1/walletsRun in dashboard

A body naming both, or neither, is rejected with 400. With an Idempotency-Key, SDP never records a second wallet for one key: a retry returns the wallet an earlier attempt recorded, including after the 24-hour key window. Privy and Coinbase CDP also receive a request id derived from the key, so they dedupe at the provider. A provider failure is stored as a 503, and a new key is a new provider request. A 503 can mean the provider created the wallet before the error, and with a provider other than Privy or Coinbase CDP, a failure that left no SDP wallet row makes even the same key a new provider request after 24 hours: before any retry after an ambiguous failure, whatever the key, check GET /v1/wallets and, if the wallet is not there, the provider account. The provider request id and the recorded-wallet lookup both include the credential, so after an API key rotation, once the key's 24-hour record has expired, the same key under the new credential is a new provider request and can create a second wallet: after a rotation, list wallets with GET /v1/wallets and check the provider account before retrying a create.

Requires an API key with the wallets.manage action.

HeadersCopy Anchor Link

• x-project-id · string · min length 1 · example prj_example

  Required for dashboard sessions. API keys use their assigned project.

• Idempotency-Key · string

  Use a unique 1–255 printable ASCII key per operation. Reuse it with the same request on retries. An in-flight attempt returns 409; a changed request returns 422. Retry and recovery rules.

Request bodyCopy Anchor Link

application/json · required

Create wallet request body. Names exactly one owner: provider (Managed config) or connectionId (Custody Connection); a body naming both, or neither, is rejected with 400.

Any of:

• Create a wallet under the project's Managed config for provider. · must not include connectionId

  • provider · string · required · one of local, fireblocks, privy, coinbase_cdp, para, turnkey, dfns, ibm_haven, anchorage, utila · example privy

    Provider whose Managed config owns the new wallet. A project holds one active config per provider.

  • label · string · max length 100 · example Mint authority wallet

    Optional label for the new wallet.

  • purpose · string · one of transfer, fee_payer · default transfer

    What the wallet is for. Defaults to transfer, the only purpose a payment, transfer batch or recurring payment can send from.

• Create a wallet under a Custody Connection. · must not include provider

  • connectionId · string · required · min length 1 · example cconn_123

    Custody Connection (BYOK) that owns the new wallet.

  • label · string · max length 100 · example Mint authority wallet

    Optional label for the new wallet.

  • purpose · string · one of transfer, fee_payer · default transfer

    What the wallet is for. Defaults to transfer, the only purpose a payment, transfer batch or recurring payment can send from.

ResponsesCopy Anchor Link

• 201 Wallet created

  • data · object · required

    Created wallet response payload.

    • wallet · object · required

      Wallet details.

      • id · string · required · example cw_example

        Wallet record ID.

      • custodyConfigId · string · example cfg_example

        Owning custody configuration ID.

      • custodyConnectionId · string · example cconn_example

        Owning Custody Connection ID.

      • provider · string · one of local, fireblocks, privy, coinbase_cdp, para, turnkey, dfns, ibm_haven, anchorage, utila · example privy

        Wallet signing provider.

      • isRuntimeExecutionAllowed · boolean · required · example true

        Whether SDP currently permits attempting runtime execution through this wallet's owner. This is request-time admission, not Provider health or a success guarantee.

      • walletId · string · required · min length 1 · example privy_wallet_123

        Provider wallet ID.

      • publicKey · string · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112

        Base58-encoded Solana address.

      • label · string | null · required · example Root Signing Wallet

        Optional wallet label.

      • purpose · string | null · required · example root

        Optional wallet purpose.

      • status · string · required · one of active, inactive · example active

        Wallet status.

      • createdAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z

        ISO 8601 timestamp.

      • balances · object[]

        Tracked token balances when requested and successfully observed. Omitted when the balance lookup is unavailable; an empty array is a successful zero-token result.

        • token · string · required · example USDC

          Tracked token symbol.

        • mint · string · required · min length 32 · max length 44 · example 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU

          Tracked token mint address.

        • amount · string · required · example 1250000

          Raw token amount as a string.

        • uiAmount · string · required · example 1.25

          Human-readable token balance.

        • decimals · integer · required · min 0 · example 6

          Token decimals.

        • usdPrice · number · example 1

          Resolved USD price per token when available.

        • usdValue · number · example 125.5

          Resolved USD value of this balance when pricing is available.

      One of:

      • Owned by a Managed config. · must include custodyConfigId · must not include custodyConnectionId

      • Owned by a Custody Connection. · must include custodyConnectionId · must not include custodyConfigId

  • meta · object · required

    Response metadata.

    • requestId · string · required · min length 1 · example req_example

      Request identifier for tracing.

    • timestamp · string · required · format date-time · example 2025-01-01T00:00:00.000Z

      ISO 8601 timestamp.

• 400 Bad Request

  • error · object · required

    Standard error payload.

    • code · string · required

      Machine-readable error code.

    • message · string · required

      Human-readable error message.

    • details · object

      Optional error details for debugging.

      • * · any

  • meta · object

    • requestId · string · min length 1 · example req_example

      Request identifier for tracing.

• 401 Unauthorized

  Same fields as 400.

• 403 Forbidden. Requires the wallets.manage action: an API key must hold it (a module's manage or execute also covers its read), and a signed-in member's organization role must include it. Without it the error is INSUFFICIENT_PERMISSIONS and error.details.action names the action. Any other 403 names its own reason. Forbidden: the caller lacks the route's action or the API key is wallet-scoped, or the provider account was refused. A refusal's details.reason names the failed check: custody_mode_not_allowed when provider names a Managed config in a Production project (Production is BYOK only: create the wallet in a Custody Connection with connectionId), custody_provider_not_in_release_channel, or provider_not_entitled.

  Same fields as 400.

• 404 Not Found

  Same fields as 400.

• 409 Conflict

  Same fields as 400.

• 422 Unprocessable Entity

  Same fields as 400.

• 500 Internal Server Error

  Same fields as 400.

• 503 Service Unavailable

  Same fields as 400.