Wallets

Initialize wallet signing

Changed on Nov 2, 2026

Sets up Managed custody for the project's named provider by creating its active signing configuration and first wallet. Production projects use BYOK only: there this returns 403 with details.reason custody_mode_not_allowed, and wallets are created in a Custody Connection with POST /v1/wallets and connectionId.

post/v1/wallets/initialize

Request

Base URL
http://localhost:8787
URL
http://localhost:8787/v1/wallets/initialize
Auth
HTTP bearer

Headers

x-project-idstring

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

Example:prj_example

Idempotency-Keystring

Optional, and honored when sent. 1-255 printable ASCII characters; send a UUID per logical operation and reuse it on every retry. Within 24 hours, a retry with the same key and the same request returns the stored status and body with the response header Idempotent-Replayed: true. Keys are scoped to the credential: within 24 hours, the same key with a different request, or from a different credential, returns 422 IDEMPOTENCY_KEY_REUSED; after that, the same key from a different credential runs as a new request. A rotated API key is a new credential, so after any rotation read the resource with GET to see whether the original request ran, and never resend a money request under the new credential without checking first. A key whose original request is still running returns 409 IDEMPOTENCY_KEY_IN_FLIGHT with Retry-After. A 400, 401, 403, 409 or 429 refusal is not stored, so the same key runs again once the cause is fixed. Access is checked before the key on every request, so a refused request never claims the key, and a credential that has since lost access to the named resource gets 403 instead of the stored response. A replay is a snapshot of the original response: read the current state with GET instead of sending the request again. If the original request never recorded its outcome (it crashed), a same-key retry gets 409 IDEMPOTENCY_KEY_IN_FLIGHT until 15 minutes plus the route's lease have passed since the original was sent (about 16 minutes, or about 20 for transfer batches), then 409 IDEMPOTENCY_KEY_OUTCOME_UNKNOWN with no Retry-After, as does every later retry with that key: read the resource with GET to see whether it ran, then send again with a new key. A 5xx is stored and replayed like any other answer; retry it with a new key.

Example:idempotency_example_12345

Request body

Response

Wallet signing initialized

configIdstring required

Created wallet signing config ID.

publicKeystring required

Public key of the provisioned root wallet.

walletIdstring required

Provider wallet ID of the provisioned root wallet.

Example response

{
  "configId": "cfg_example",
  "publicKey": "So11111111111111111111111111111111111111112",
  "walletId": "privy_wallet_123"
}

Changes

Nov 2, 20269f0b1d561064 Revision changes
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
Oct 30, 2026f4a0135eca08 Revision changes
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status

Operation history (13 revisions)