Payments

Update wallet policy

Updates payment policy rules for a custody wallet, activating a new control-profile revision. Supply expectedRevisionId to reject the update with 409 when another update has activated a revision since the policy was read. Wallet provisioning and default selection remain in /v1/wallets.

put/v1/payments/wallets/{walletId}/policies

Path parameters

walletIdstring required

Provider wallet ID — the walletId field returned by GET /v1/wallets. The wallet record id and the public key are not accepted.

Example:privy_wallet_123

Provider wallet ID — the walletId field returned by GET /v1/wallets. The wallet record id and the public key are not accepted.

Headers

x-project-idstring

Selects the active project for this request. Required for session/dashboard callers. Ignored when authenticating with an API key, whose scope is fixed to the key's project.

Example:prj_example

Selects the active project for this request. Required for session/dashboard callers. Ignored when authenticating with an API key, whose scope is fixed to the key's project.

Request body

commitMessagestring

Optional message describing the wallet policy revision changes.

defaultAction'allow' | 'deny' | 'approval_required' | 'review' required

Default action for the activated wallet control profile revision.

expectedRevisionIdstring nullable

Optimistic-concurrency precondition. When set, the update only applies if this matches the wallet's active control-profile revision id (use null to require that no profile is active); otherwise the request fails with 409. Omit to skip the check and overwrite unconditionally.

Example request

{
  "commitMessage": "Require approval for transfers above 10,000 USDC.",
  "defaultAction": "allow",
  "rules": [
    {
      "id": "approve-vault-deposits",
      "kind": "operation_type",
      "operationTypes": [
        "earn_vault_deposit"
      ],
      "action": "approval_required"
    }
  ],
  "expectedRevisionId": "wcpr_example"
}

Response

Wallet policy updated

Example response

{
  "data": {
    "policy": {
      "walletId": "privy_wallet_123",
      "controlProfile": {
        "createdAt": "2025-01-01T00:00:00.000Z",
        "updatedAt": "2025-01-01T00:00:00.000Z",
        "activatedAt": "2025-01-01T00:00:00.000Z"
      },
      "audit": {
        "recentEvaluations": [
          {
            "walletOperationId": "wop_example",
            "policyEvaluationId": "peval_example",
            "operationFamily": "payment",
            "operationType": "payment_transfer_execute",
            "asset": "USDC",
            "amount": "100.00",
            "destination": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
            "reasonCode": "wallet_policy_match",
            "reason": "Operation family payment matched policy.",
            "approvalRequestId": "appr_example",
            "operationCreatedAt": "2025-01-01T00:00:00.000Z",
            "operationUpdatedAt": "2025-01-01T00:00:00.000Z",
            "evaluatedAt": "2025-01-01T00:00:00.000Z"
          }
        ]
      }
    }
  },
  "meta": {
    "requestId": "req_example",
    "timestamp": "2025-01-01T00:00:00.000Z"
  }
}

Changes

Changed in 4 of the 12 revisions of this API.121018

Aug 25, 2026a04e2929537f35See the full diff
- ▲
  removed subschema #2 subschema #6 from the / request property oneOf list
  request-property-one-of-removed
- ▲
  added subschema #2 subschema #6 to the //// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  added subschema #2 subschema #6 to the /// response property oneOf list for the response status
  response-property-one-of-added
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added subschema #2 subschema #6 to the / request property oneOf list
  request-property-one-of-added
- ○
  added the non-success response with the status
  response-non-success-status-added
- ○
  removed subschema #2 subschema #6 from the //// response property oneOf list for the response status
  response-property-one-of-removed
- ○
  removed subschema #2 subschema #6 from the /// response property oneOf list for the response status
  response-property-one-of-removed
Aug 19, 2026f138f2b58663310See the full diff
- ▲
  removed subschema #1 subschema #2 subschema #6 from the / request property oneOf list
  request-property-one-of-removed
- ▲
  added subschema #1 subschema #2 subschema #6 to the //// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  added subschema #1 subschema #2 subschema #6 to the /// response property oneOf list for the response status
  response-property-one-of-added
- ○
  added subschema #1 subschema #2 subschema #6 to the / request property oneOf list
  request-property-one-of-added
- ○
  removed the issuance enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the payment enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the program enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the provider_admin enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the ramp enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the raw_sign enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the transfer enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed subschema #1 subschema #2 subschema #6 from the //// response property oneOf list for the response status
  response-property-one-of-removed
- ○
  removed subschema #1 subschema #2 subschema #6 from the /// response property oneOf list for the response status
  response-property-one-of-removed
Aug 15, 20263e302bba53865See the full diff
- ●
  added the new SERVICE_UNAVAILABLE enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new SERVICE_UNAVAILABLE enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new SERVICE_UNAVAILABLE enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new SERVICE_UNAVAILABLE enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new SERVICE_UNAVAILABLE enum value to the / response property for the response status
  response-property-enum-value-added
Aug 12, 2026f6134b5daa7f653See the full diff
- ▲
  the request property became required
  request-property-became-required
- ▲
  the request property became required
  request-property-became-required
- ▲
  the response property // became nullable for the status
  response-property-became-nullable
- ▲
  removed the required property // from the response with the status
  response-required-property-removed
- ▲
  removed the required property // from the response with the status
  response-required-property-removed
- ▲
  removed the required property // from the response with the status
  response-required-property-removed
- ●
  removed the request property
  request-property-removed
- ●
  removed the request property
  request-property-removed
- ●
  removed the request property
  request-property-removed
- ●
  removed the optional property // from the response with the status
  response-optional-property-removed
- ●
  removed the optional property // from the response with the status
  response-optional-property-removed
- ○
  the response property // became required for the status
  response-property-became-required
- ○
  the response property // became required for the status
  response-property-became-required
- ○
  the response property // became required for the status
  response-property-became-required

Full history