Privy’s policy engine gives your application programmable control over how every wallet can be used. Instead of relying on ad-hoc checks in your code, you can define enforceable rules at the key level that govern what actions a wallet may take. With policies, you can configure:

• Transfer limits
• Time-bound signers
• Allowlists and denylists of transfer recipients
• Allowlists and denylists of smart contracts and programs
• Allowlists and denylists of networks
• Allowed time window for key export
• Granular constraints around calldata and parameters that can be passed to smart contracts
• Restrictions around signatures needed for transactions, such as EVM typed data (EIP712)

This allows teams to define security, compliance, and behavioral rules that are applied consistently across all wallets in production.

​

Concepts

Privy’s policy engine is defined by three core primitives: policies, rules, and conditions; and is designed to give developers precise control over wallets behavior. At a high-level:

• A policy is the complete set of constraints that govern a wallet. It is a list of rules that define the total set of actions that are allowed or denied for a wallet.
• A rule describes when an action should be allowed or denied. Each rule is composed of one or more conditions. When a request satisfies all of the conditions, the policy engine executes the action (ALLOW or DENY) prescribed by the rule.
• A condition is a Boolean expression that the policy engine evaluates against an incoming RPC request.

This structure makes Privy’s policy engine flexible enough for complex workflows and predictable enough for production environments. You can create and manage policies through the Privy Dashboard, nodeJS SDK, or via the REST API.

​

Policies

A policy is composed from a list of rules for each RPC method that a wallet can execute that define what actions are allowed or denied for the wallet. DENY actions take precedence over ALLOW actions. If no rules resolve, the policy will default to DENY.

​

Allowlisted RPCs and wallet actions

If a wallet’s policy does not include a rule for a given RPC method or wallet action API, usage of that RPC method or API will be denied. If a policy is set on a wallet, the policy must include a rule for any RPC methods or wallet action APIs that the wallet intends to use. Policy objects have the following properties:

Hide child attributes

​

version

'1.0'

Version of the policy. Currently, 1.0 is the only version.

​

name

string

Name to assign to policy.

​

chain_type

'ethereum' | 'solana' | 'tron' | 'sui'

Chain type for wallets that the policy will be applied to.

​

rules

Rule[]

A list of Rule objects describing what rules to apply to each RPC method (e.g. 'eth_sendTransaction') that the wallet can take.

​

Policy evaluation

By default, the trusted execution environment (secure enclave) enforces policies when processing wallet actions, such as signature requests, transactions, and key export. The enclave evaluates policy rules in a tamper-proof environment before any operations proceed. Privy enforces some policies at the API level. For example, limiting transfer sizes requires transaction simulation which runs outside the enclave today. When your application makes an RPC request on a wallet that has a policy, the policy engine evaluates the rules that are associated with the requested RPC method. For instance, if your application makes an 'eth_signTransaction' request, the policy engine will only evaluate rules associated with the 'eth_signTransaction' method in the policy. The rules are evaluated as follows:

1. If any rule evaluates to a DENY action, the policy engine will DENY the request.
2. If any rule evaluates to an ALLOW action, and no rules evaluate to DENY, then the policy engine will ALLOW the request.

If the request does not satisfy any of the rules for the policy, the policy engine defaults to DENY the request. This also applies to Solana transactions such that every Instruction in a Solana transaction is evaluated against the rules of the policy. Every instruction must evaluate to an ALLOW action for the transaction to be allowed.

​

Rules

The nested Rule object within the policy’s rules array. A rule is composed of an set of boolean conditions and an action (ALLOW or DENY) that is taken if an RPC request satisfies all of the conditions in the rule. Rule objects have the following fields:

Hide child attributes

​

name

string

Name to assign to the rule.

​

method

'eth_sendTransaction' | 'eth_signTransaction' | 'eth_signUserOperation' | 'eth_signTypedData_v4' | 'personal_sign' | 'eth_sign7702Authorization' | 'wallet_sendCalls' | 'signTransaction' | 'signAndSendTransaction' | 'signMessage' | 'exportPrivateKey' | 'exportSeedPhrase' | 'signRawMessageBytes' | 'signTransactionBytes' | 'tron_signTransaction' | 'tron_sendTransaction' | 'earn_deposit' | 'earn_withdraw' | 'transfer' | '*'

Method to apply the conditions to. If an RPC method, must correspond to the chain_type of the parent policy. Methods signRawMessageBytes and signTransactionBytes are applicable to Tron and Sui only. Use signRawMessageBytes for unparsed raw signing requests. Use signTransactionBytes for parsed transaction bytes that use Tron or Sui transaction field sources.

​

conditions

Condition[]

A set of boolean conditions that define the action the rule allows or denies. For exportPrivateKey, leave conditions empty.

​

action

'ALLOW' | 'DENY'

Whether the rule should allow or deny a wallet request if it satisfies all of the rule’s conditions.

Each rule corresponds to an individual action that should be allowed or denied by a wallet. For example, you might configure rules for a policy to:

• ALLOW transfers of the native token to a set of allowlisted recipient addresses
• DENY interactions with specific Ethereum smart contracts or Solana programs

​

Conditions

A condition is a boolean statement about a wallet request. When evaluating a wallet request against a rule, the policy engine checks whether the wallet request satisfies each of the boolean conditions in the rule. If all of the conditions are satisfied, the engine executes the action associated with the rule. Conditions allow you to define specific action types that should be allowed or denied for a wallet.

Hide child attributes

​

field_source

'ethereum_transaction' | 'ethereum_calldata' | 'ethereum_typed_data_domain' | 'ethereum_typed_data_message' | 'ethereum_7702_authorization' | 'solana_program_instruction' | 'solana_system_program_instruction' | 'solana_token_program_instruction' | 'tron_transaction' | 'tron_trigger_smart_contract_data' | 'sui_transaction_command' | 'sui_transfer_objects_command' | 'tempo_transaction' | 'message' | 'action_request_body' | 'system' | 'reference'

Data source from which to derive the field for the condition.

​

field

string

The attribute to evaluate for a wallet request. As an example, the field for the recipient of an EVM transaction is 'to'.

​

abi

JSON

Contract ABI to decode Ethereum or Tron calldata against. Should only be set for 'ethereum_calldata' or 'tron_trigger_smart_contract_data' policies. Must strictly be formatted as JSON.

​

operator

'eq' | 'neq' | 'lt' | 'lte' | 'gt' | 'gte' | 'in' | 'in_condition_set' | 'contains' | 'starts_with' | 'ends_with'

Boolean operator used to compare a field with a value

​

value

string | number | string[]

Static value to compare a field to.

Conditions for certain sources may have additional parameters. For instance, ethereum_calldata and tron_trigger_smart_contract_data conditions also require an abi parameter used to decode the calldata, and ethereum_typed_data_message conditions require a typed_data parameter to define the schema for the typed data message.

​

Field

Fields are attributes of a wallet request that can be parsed or interpreted from the wallet request. Examples of fields include the to parameter of an EVM transaction, the fee_payer parameter of a Solana transaction, or an spl_transfer_recipient field that is populated when the policy engine interprets a transaction. Fields are derived from field sources, which surface data from the wallet request. Possible field sources are listed below.

​

Operator

Operators are boolean operators used to compare fields and values. Operators include eq, neq, lt, lte, gt, gte, in, in_condition_set, contains, starts_with, and ends_with. All string comparisons are case-sensitive.

​

Values

A condition compares a field using its boolean operator to a static value. As an example, if a condition determines whether an Ethereum transaction has specific recipient address X, the value for the condition is X.