​
Overview

CDP Wallets support Policies that enable developers to govern account and project behavior. Policies provide flexible configuration for enforcing controls based on transaction parameters such as destination address and transaction value.

​
Use cases

  • Wallet transaction filtering: Prevent transfers to known malicious or restricted addresses
  • Allowlisted access to project features: Restrict access only to approved addresses to interact with a smart contract or mint a token
  • Transaction limits per address: Limit financial risk by capping transaction values
  • Prevent signing of fraudulent messages: Ensure compromised clients cannot prove control of your accounts

​
Policy field definitions

A policy is defined by the following fields:
FieldDescriptionValid values
scopeThe level at which a policy gets appliedproject or account
rulesA list of rules that are used to govern the behavior of accountsAn array of rules
actionThe action to take when a policy is appliedaccept or reject
operationThe operation to perform when a policy is appliedsignEvmTransaction, sendEvmTransaction, signEvmMessage, signEvmHash, signEvmTypedData, signSolTransaction, sendSolTransaction, prepareUserOperation, or sendUserOperation
criteriaThe list of logical expressions that are evaluated to a transaction to determine whether a rule should be applied or notAn array of criteria. See API Reference for more details.

​
Evaluation process

A project-level policy will be evaluated first, followed by any account-level policies. Read more technical details on policy evaluation in the API Reference documentation.
project-policy.json
{
  "description": "An example project level policy",
  "scope": "project",
  "rules": [
    {
      "action": "accept",
      "operation": "signEvmTransaction",
      "criteria": [
        {
          "type": "ethValue",
          "ethValue": "1000000000000000000",
          "operator": "<="
        }
      ]
    },
    {
      "action": "accept",
      "operation": "signEvmTransaction",
      "criteria": [
        {
          "type": "ethValue",
          "ethValue": "2000000000000000000",
          "operator": "<="
        },
        {
          "type": "evmAddress",
          "addresses": [
            "0x123"
          ],
          "operator": "in"
        }
      ]
    }
  ]
}

​
Supported operations

Each rule defines the behavior of a certain operation. The operation corresponds to a CDP v2 API. Currently, the following operations are supported: EVM Operations:
  • signEvmTransaction: To identify incoming signing transactions on an EVM compatible network
  • sendEvmTransaction: To identify incoming signing transactions that are then sent to a supported network
  • signEvmTypedData: To identify incoming typed data to be signed by an account
  • signEvmMessage: To identify incoming messages to be signed by an account
  • signEvmHash: To identify incoming hash to be signed by an account
  • prepareUserOperation: For preparing user operations on a smart account
  • sendUserOperation: For sending user operations using a smart account
Solana Operations:
  • signSolTransaction: To identify incoming signing transactions on the Solana network
  • sendSolTransaction: To identify incoming signing transactions that are then sent to the Solana mainnet or devnet network.
You can find more details in the API reference documentation.

​
API Key Configuration

In order to securely manage Policies via API or SDK, you’ll need to manually configure an API key with a specific scope. This scope is required to perform the following API operations:
  • Create Policy
  • Update Policy
  • Delete Policy
  • Account Policy assignment
When you’re creating a new API Key, first expand the API restrictions panel then scroll down to the API-specific restrictions section. Ensure that Manage (modify policies) is checked before key creation as seen in the following screenshot.
Policies Scope

​
Define a policy

Policies can be defined via CDP Portal UI or via the CDP SDK.
You may only create one project-level policy per project.

​
UI (CDP Portal)

  1. Navigate to Policies in the CDP Portal.
    Policies UI
  2. Click the Create new policy button to access the JSON editor. The modal will contain a sample policy that you can edit, but you can also use some of the examples in our EVM Policies or Solana Policies documentation.
    JSON Editor
  3. Define the policy and click the Create button. If successful, you should see a “Policy created” message.
  4. Refresh the page to see the new policy listed in the Policies dashboard:
    Policy Engine dashboard
    Click the View button to edit or delete the policy.
  5. Account level policies should be added to the account programmatically via the SDK. 
    import { CdpClient } from "@coinbase/cdp-sdk";
    import dotenv from "dotenv";

    dotenv.config();

    const cdp = new CdpClient();

    const account = await cdp.evm.createAccount();

    const policyId = "" // Paste the policy ID created on portal.

    // Update the account to add the account policy.
    const updatedAccount = await cdp.evm.updateAccount({
      address: account.address,
      update: {
        accountPolicy: policyId,
      }
    })

    console.log("Updated account %s with policy: %s", updatedAccount.address, updatedAccount.policies);

​
Programmatically

In order to manage Policies via SDK or API, you need to have an API Key with Policy management enabled
To create a policy programmatically, you can use the CDP SDK. The code below demonstrates basic policy creation and management:
  1. Create an EVM account named PolicyAccount
  2. Create an account-level policy that only allows transactions less than or equal to 1 ETH to the address 0x000000000000000000000000000000000000dEaD
  3. Apply the policy to the account we created
  4. Create another account named OtherPolicyAccount which has the above policy applied during creation
  5. Create a project-level policy that only allows transactions less than or equal to 5 ETH to the address 0x000000000000000000000000000000000000dEaD
A project-level policy is automatically applied to all accounts in the project on creation.An account-level policy may be applied to an account in 2 ways: during account creation, or after account creation by updating the account.
    import { CdpClient } from "@coinbase/cdp-sdk";

    const cdp = new CdpClient();

    const account = await cdp.evm.getOrCreateAccount({
      name: "PolicyAccount"
    });
    console.log("Account address:", account.address);

    // Create policy
    const policy = await cdp.policies.createPolicy({
      policy: {
        scope: "account",
        description: "Account Allowlist Example",
        rules: [
          {
            action: "accept",
            operation: "signEvmTransaction",
            criteria: [
              {
                type: "ethValue",
                ethValue: "1000000000000000000", // 1 ETH in wei
                operator: "<=",
              },
              {
                type: "evmAddress",
                addresses: ["0x000000000000000000000000000000000000dEaD"],
                operator: "in",
              },
            ],
          },
        ],
      },
    });
    console.log("Created policy:", policy.id);

    // Apply policy to the account
    const updatedAccount = await cdp.evm.updateAccount({
      address: account.address,
      update: {
        accountPolicy: policy.id
      }
    });
    console.log("Applied policy to account:", updatedAccount.address);

    // Create another account with policy immediately applied to it
    const otherAccount = await cdp.evm.createAccount({
      name: "OtherPolicyAccount",
      accountPolicy: policy.id
    });
    console.log("Other account address:", otherAccount.address);

    // Create project policy example
    const projectPolicy = await cdp.policies.createPolicy({
      policy: {
        scope: "project",
        description: "Project Transaction Limit Example",
        rules: [
          {
            action: "accept",
            operation: "signEvmTransaction",
            criteria: [
              {
                type: "ethValue",
                ethValue: "5000000000000000000", // 5 ETH in wei
                operator: "<=",
              },
              {
                type: "evmAddress",
                addresses: ["0x000000000000000000000000000000000000dEaD"],
                operator: "in",
              },
            ],
          },
        ],
      },
    });
    console.log("Created project policy:", projectPolicy.id);
A project-level policy is automatically applied to all accounts in the project on creation.An account-level policy may be applied to an account in 2 ways: during account creation, or after account creation by updating the account.
For more detailed examples and specific policy configurations, see:

​
Video: Watch and learn

Watch the video to learn how to implement and manage policies with CDP Server Wallet, which covers:
  • An overview of policy engine setup and configuration
  • How to create project-level and account-level policies
  • Best practices for implementing transaction controls and security measures