Policy engine

Policies are a set of rules applied to wallets. These rules define what wallet actions are allowed, such as dollar limits on transactions, blocked destination addresses, or allowed contract addresses.

To apply a policy to a wallet, create a policy object configured with the desired ruleset, and create or update a wallet with that policy.

Policy object

A Policy contains a list of rules that are evaluated sequentially on the request submitted to a wallet.

If a rule evaluates to true, the action is taken immediately and later rules are bypassed. If there are no additional rules, the default action is taken. By default, wallets are created with the null policy, which indicates that no policy rules are applied and all requests are allowed.

Concretely, a Policy is an object with the following fields:

Field	Type	Description
id	string	The policy identifier.
rules	Rule[]	List of rules evaluated sequentially on the wallet request. Each rule evaluates to an action, if true.
default_action	'ALLOW' | 'DENY'	The action that is taken by default if all rules evaluate to false.

A Rule is of the format:

Field	Type	Description
method	string	The RPC method to which this rule applies. See the usage guides, such as 'eth_sendTransaction'.
conditions	Condition[]	A set of criteria that must all be true for the action to be triggered.
action	'ALLOW' | 'DENY'	The action that is taken if the conditions are true, bypassing all later rules. If DENY, the request is denied. If ALLOW, the request is allowed.

A Condition is of the format:

Field	Type	Description
field	string	A field of the wallet request body.
operator	string	Evaluation rule defining the relationship between field and value. Valid values are: 'eq' | 'neq' | 'gr' | 'gre' | 'lt' | 'lte'.
value	string	A value corresponding to the field of the wallet request body.

Examples

Policies are very expressive and can be used to represent a variety of high-level concepts.

{
  rules: [{
    method: "eth_sendTransaction",
    conditions: [{
      field: "params.transaction.to",
      operator: "eq",
      value: "0xE3070d3e4309afA3bC9a6b057685743CF42da77C"
    }],
    action: "DENY"
  }],
  default_action: "ALLOW"
}

Managing policies

Privy supports CREATE, READ, UPDATE, and DELETE semantics on the Policy object.

Action	Request
CREATE	POST /api/v1/policies
READ	GET /api/v1/policies/[policy_id]
UPDATE	POST /api/v1/policies/[policy_id]
DELETE	DELETE /api/v1/policies/[policy_id]

Creating a policy

To create a new policy, make a POST request to:

https://api.privy.io/v1/policies

Body

In the request body, include the following:

Field	Type	Description
rules	Rule[]	List of rules evaluated sequentially on the wallet request. Each rule evaluates to an action, if true.
default_action	'ALLOW' | 'DENY'	The action that is taken by default if all rules evaluate to false.

Response

In the response, Privy will send back the following if successful:

Field	Type	Description
id	string	ID of the created policy.

Example request

As an example, a sample request to create a new policy that allowlists a contract address might look like the following:

$ curl --request POST https://api.privy.io/v1/policies \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H "privy-authorization-signature: <authorization-signature-for-request>" \
-H 'Content-Type: application/json' \
-d '{
  "rules": [{
    "method": "eth_sendTransaction",
    "conditions": [{
      "field": "params.transaction.to",
      "operator": "eq",
      "value": "0xE3070d3e4309afA3bC9a6b057685743CF42da77C"
    }],
    "action": "ALLOW"
  }],
  "default_action": "DENY"
}'

A successful response will look like the following:

{
  "id": "nkod153bjktal94exysf79hq"
}

Updating a policy

To update a policy, make a POST request to:

https://api.privy.io/v1/policies/[policy_id]

In the request body, include the updated Policy object in the body. Any parameters not provided will be left unchanged.