Wallet Policies: Programmable On-Chain Transaction Rules

Wallet policies are rules stored in the wallet’s on-chain state that the smart contract evaluates before executing any transaction. A valid passkey signature is necessary to authorize a transaction, but it is not sufficient — every active policy must also pass. Policies give you fine-grained control over what an authorized user can do, adding a programmable safety layer that protects users from accidental overspending, interaction with unapproved contracts, or other undesirable wallet behavior.

Why Policies Exist

A traditional wallet has no concept of policy: a valid signature equals execution. SocketFi smart wallets separate the authorization question (who is signing?) from the policy question (should this be allowed?):

Traditional wallet:
  Valid signature → Execute

SocketFi smart wallet:
  Valid signature → Policy evaluation → Execute (only if all policies pass)

This means even a fully authenticated user can be protected by wallet-level rules they or your application configured. Policies are enforced by the on-chain contract, so they cannot be bypassed at the application layer.

Policy Categories

SocketFi wallets support five categories of policy:

Spending Limits

Restrict the total value that can leave the wallet over a rolling time window. Spending limits can be applied globally or per-asset.

Policy: max 500 USDC per day

Transaction: transfer 200 USDC  →  200 < 500  ✅ Allowed
Transaction: transfer 350 USDC  →  200 + 350 > 500  ❌ Rejected

Contract Restrictions

Maintain an allowlist of Soroban contract addresses the wallet may interact with. Any invocation targeting a contract not on the list is rejected before execution.

Allowed contracts:
  CCONTRACT_A...
  CCONTRACT_B...

Transaction: invoke CCONTRACT_A...  ✅ Allowed
Transaction: invoke CCONTRACT_X...  ❌ Rejected (not on allowlist)

Authorization Rules

Introduce additional authorization requirements for specific operation types. For example, you might require extra verification for transfers above a high-value threshold, or restrict which wallet operations are available to a specific session type.

Recovery Controls

Govern when and how account recovery may proceed. Examples include mandatory waiting periods between a recovery request and execution, approval thresholds, or restrictions on who may initiate recovery.

Fee Controls

Limit the maximum fee a transaction may consume, restrict which assets may be used to pay fees, or cap deferred fee balances. Transactions that would exceed fee policy are rejected before submission.

Policy Evaluation Order

Policies are evaluated after authorization passes but before any execution occurs. The evaluation order is:

① Verify signature (Authorization Engine)
② Verify nonce     (Authorization Engine)
③ Verify expiration (Authorization Engine)
─────────────────────────────────────────
④ Evaluate Spending Limit policies    (Policy Engine)
⑤ Evaluate Contract Restriction policies
⑥ Evaluate Authorization Rule policies
⑦ Evaluate Fee Control policies
⑧ Evaluate Recovery Control policies (only for recovery ops)
─────────────────────────────────────────
⑨ Execute

Every policy must pass. If any single policy fails, execution stops immediately and the wallet state is not changed.

Multiple Policies

Wallets can have multiple active policies of the same or different categories. All must pass for a transaction to execute:

Policy 1: Spending limit — max 500 USDC/day
Policy 2: Contract allowlist — only contracts A, B, C
Policy 3: Fee limit — max 0.1 XLM per transaction

Transaction: transfer 200 USDC to CCONTRACT_A...

  Policy 1: 200 USDC ≤ 500 USDC daily limit  ✅
  Policy 2: CCONTRACT_A is on the allowlist   ✅
  Policy 3: Fee = 0.05 XLM ≤ 0.1 XLM         ✅

→ Execute

Transaction: transfer 200 USDC to CCONTRACT_X...

  Policy 1: 200 USDC ≤ 500 USDC daily limit  ✅
  Policy 2: CCONTRACT_X is NOT on allowlist   ❌

→ Reject immediately (Policy 3 is never evaluated)

Any single policy failure stops execution immediately. The remaining policies in the evaluation chain are not checked. Design your policy set with this in mind — a policy that fires frequently for legitimate transactions will block those transactions entirely.

Wallet Policy Profiles

Different applications call for different policy configurations. Here are three common profiles to use as starting points:

Consumer Wallet

Focused on protecting everyday users from accidental large transfers and phishing.

Spending limit:        500 USDC / day
Contract allowlist:    [app contract, DEX contract]
Fee limit:             0.5 XLM / transaction

This profile lets users do everything they need for normal app usage while capping potential loss from a compromised session.

Gaming Wallet

Locked to the game’s own contract ecosystem to prevent assets from being moved outside the game environment.

Contract allowlist:    [game items contract, marketplace contract]
Spending limit:        1000 game tokens / day
Contract restriction:  block all contracts not on allowlist

Players can trade within the game freely, but no external contract can drain the wallet.

Fintech Wallet

Designed for high-value transactions with additional controls on large transfers and fee exposure.

Spending limit:        10,000 USDC / day
High-value threshold:  additional authorization required above 2,500 USDC
Fee limit:             1.0 XLM / transaction
Contract allowlist:    [payment processor, custody contract]

Routine transactions proceed normally. High-value transfers trigger additional authorization steps.

Updating Policies

Policy updates are themselves protected wallet operations. They require a valid authorization from the wallet’s bound credential — just like any other state-changing operation.

// Update a spending limit policy (SDK handles authorization internally)
const result = await socketfi.requestTransaction({
  contractId: walletAddress,
  method: "update_policy",
  args: {
    policyType: "spending_limit",
    asset: "USDC",
    limitPerDay: 1000n,
  },
});

Because policy updates require wallet authorization, a compromised session cannot silently remove safety policies. The passkey holder must explicitly approve any policy change.

Policy Failure Reasons

Failure	Cause
Spending limit exceeded	The requested transfer would push the rolling window spend over the configured limit
Contract not allowed	The target contract is not on the wallet’s allowlist
Fee limit exceeded	The transaction fee exceeds the configured maximum
Recovery rule violated	A recovery operation does not meet configured waiting period or approval requirements
Time restriction active	The operation is outside the configured time window

Get Started

Authentication

Embedded Wallets

Transactions

Smart Wallet

Security

Wallet Policies: Programmable On-Chain Transaction Rules

Why Policies Exist

Policy Categories

Spending Limits

Contract Restrictions

Authorization Rules

Recovery Controls

Fee Controls

Policy Evaluation Order

Multiple Policies

Wallet Policy Profiles

Updating Policies

Policy Failure Reasons

​Why Policies Exist

​Policy Categories

​Spending Limits

​Contract Restrictions

​Authorization Rules

​Recovery Controls

​Fee Controls

​Policy Evaluation Order

​Multiple Policies

​Wallet Policy Profiles

​Updating Policies

​Policy Failure Reasons

Why Policies Exist

Policy Categories

Spending Limits

Contract Restrictions

Authorization Rules

Recovery Controls

Fee Controls

Policy Evaluation Order

Multiple Policies

Wallet Policy Profiles

Updating Policies

Policy Failure Reasons