> Solana Developer Platform docs, served as Markdown. The [docs index](https://platform.solana.com/docs.md) lists every page and [llms.txt](https://platform.solana.com/docs/ai/llms.txt) the key ones; [SKILL.md](https://platform.solana.com/SKILL.md) has the rules for building on SDP. # Create wallet Provisions a new wallet under exactly one provider account: the project's Managed config for provider, or the Custody Connection named by connectionId. `POST /v1/wallets` 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](/docs/developing-with-sdp/authentication) with the `wallets.manage` action. ## Headers - **`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](/docs/developing-with-sdp/idempotency). ## Request body `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. ## Responses - **`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`. ## Example request ```bash tab="cURL" curl -X POST 'https://api.solana.com/v1/wallets' \ -H "Authorization: Bearer $SDP_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "provider": "privy", "label": "Treasury wallet", "purpose": "transfer" }' ``` ```ts tab="TypeScript" const res = await fetch("https://api.solana.com/v1/wallets", { method: "POST", headers: { Authorization: `Bearer ${process.env.SDP_API_KEY}`, "Idempotency-Key": crypto.randomUUID(), "Content-Type": "application/json" }, body: JSON.stringify({ "provider": "privy", "label": "Treasury wallet", "purpose": "transfer" }) }); ``` ```python tab="Python" import os, requests, uuid r = requests.post("https://api.solana.com/v1/wallets", headers={"Authorization": f"Bearer {os.environ['SDP_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())}, json={ "provider": "privy", "label": "Treasury wallet", "purpose": "transfer" }) ``` ## Example responses ```json tab="201" { "data": { "wallet": { "id": "cw_example", "custodyConfigId": "cfg_example", "provider": "privy", "isRuntimeExecutionAllowed": true, "walletId": "privy_wallet_123", "publicKey": "So11111111111111111111111111111111111111112", "label": "Root Signing Wallet", "purpose": "root", "status": "active", "createdAt": "2025-01-01T00:00:00.000Z" } }, "meta": { "requestId": "req_example", "timestamp": "2025-01-01T00:00:00.000Z" } } ``` ```json tab="403" { "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "Missing action: wallets.manage", "details": { "action": "wallets.manage" } }, "meta": { "requestId": "req_example" } } ``` Error responses use the [standard error shape](/docs/reference/conventions/errors).