Policies | Phoenix Wallet

Policies are rule sets that control what operations are permitted on lots. They enable you to implement business logic like spending restrictions, withdrawal limits, and usage constraints without custom code.

Policy Structure

Field	Type	Description
`id`	`string`	Unique identifier
`tenant_id`	`string`	Parent tenant identifier
`name`	`string`	Human-readable name
`version`	`integer`	Policy version number
`rules`	`array`	List of policy rules
`intents`	`array`	Allowed operation intents
`status`	`enum`	`ACTIVE`, `INACTIVE`, `DEPRECATED`
`created_at`	`timestamp`	Creation timestamp

How Policies Work

When an operation is requested, Phoenix Wallet:

Identifies the lots that could satisfy the operation
Checks each lot's policy against the operation's intent
Validates all rules in the policy
Allows or denies the operation based on policy evaluation

┌─────────────────────────────────────────────────────────────┐
│                    Operation Request                        │
│  Intent: "purchase"                                         │
│  Amount: $50                                                │
│  Wallet: user_123                                           │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Policy Evaluation                        │
│                                                             │
│  Lot #1 (Policy: "promotional")                            │
│    ✓ Intent "purchase" allowed                              │
│    ✓ Rule: amount <= available                              │
│    ✗ Rule: withdrawable = false (cannot use for cashout)   │
│    Result: ALLOWED for purchases                            │
│                                                             │
│  Lot #2 (Policy: "standard")                               │
│    ✓ Intent "purchase" allowed                              │
│    ✓ All rules pass                                         │
│    Result: ALLOWED                                          │
└─────────────────────────────────────────────────────────────┘

Intents

Intents describe the purpose of an operation. Policies specify which intents they permit:

Intent	Description	Example Use
`credit`	Adding funds	Deposits, rewards, refunds
`debit`	Removing funds	Purchases, fees
`purchase`	Spending on goods/services	Store purchases
`withdrawal`	Cashing out	Bank transfers
`transfer`	Moving between wallets	P2P transfers
`refund`	Reversing a transaction	Order cancellations
`adjustment`	Manual corrections	Support adjustments
`expire`	Expiration processing	System expiry

You can define custom intents specific to your business. For example, a gaming platform might use intents like bet, win, bonus_credit.

Policy Rules

Rules are conditions that must be satisfied for an operation to proceed. Each rule has a type and parameters:

Common Rule Types

Rule Type	Description	Parameters
`intent_allowed`	Operation intent must be in allowed list	`intents: ["purchase", "transfer"]`
`max_amount`	Single operation amount limit	`amount: "10000"`
`daily_limit`	Rolling 24-hour limit	`amount: "50000"`
`attribute_match`	Lot attribute requirements	`key: "withdrawable", value: "true"`
`time_window`	Only allow during specific times	`start: "09:00", end: "17:00"`
`min_balance`	Minimum balance must remain	`amount: "100"`

Creating a Policy

curl -X POST https://api.phoenixwallet.io/v1/policies \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "pol_promotional",
    "name": "Promotional Credits Policy",
    "rules": [
      {
        "type": "intent_allowed",
        "params": {
          "intents": ["purchase", "debit"]
        }
      },
      {
        "type": "attribute_match",
        "params": {
          "key": "withdrawable",
          "value": "false",
          "enforce_on": ["withdrawal"]
        }
      },
      {
        "type": "daily_limit",
        "params": {
          "amount": "10000",
          "asset_code": "USD"
        }
      }
    ]
  }'

Response:

{
  "id": "pol_promotional",
  "tenant_id": "ten_01HV8X9Y2KPQRS3T4UV5WX6YZ7",
  "name": "Promotional Credits Policy",
  "version": 1,
  "rules": [
    {
      "type": "intent_allowed",
      "params": {
        "intents": ["purchase", "debit"]
      }
    },
    {
      "type": "attribute_match",
      "params": {
        "key": "withdrawable",
        "value": "false",
        "enforce_on": ["withdrawal"]
      }
    },
    {
      "type": "daily_limit",
      "params": {
        "amount": "10000",
        "asset_code": "USD"
      }
    }
  ],
  "status": "ACTIVE",
  "created_at": "2024-01-15T10:30:00Z"
}

Policy Versioning

Policies are versioned to support evolution without breaking existing lots:

Policy: pol_standard
├── Version 1 (lots created before 2024-01-01)
│   └── Rules: basic spending limits
├── Version 2 (lots created 2024-01-01 to 2024-06-01)
│   └── Rules: added daily limits
└── Version 3 (current, lots created after 2024-06-01)
    └── Rules: added fraud prevention rules

When you update a policy, existing lots retain their original policy version. Only new lots get the new version. This ensures predictable behavior for existing balances.

Policy Examples

Standard Wallet Policy

Full access for regular deposits:

{
  "id": "pol_standard",
  "name": "Standard Wallet Policy",
  "rules": [
    {
      "type": "intent_allowed",
      "params": {
        "intents": ["credit", "debit", "purchase", "withdrawal", "transfer", "refund"]
      }
    }
  ]
}

Promotional Credits Policy

Non-withdrawable bonus credits:

{
  "id": "pol_promo",
  "name": "Promotional Credits",
  "rules": [
    {
      "type": "intent_allowed",
      "params": {
        "intents": ["purchase", "debit"]
      }
    },
    {
      "type": "max_amount",
      "params": {
        "amount": "5000",
        "per_transaction": true
      }
    }
  ]
}

High-Value Customer Policy

Higher limits for premium users:

{
  "id": "pol_premium",
  "name": "Premium Customer Policy",
  "rules": [
    {
      "type": "intent_allowed",
      "params": {
        "intents": ["credit", "debit", "purchase", "withdrawal", "transfer", "refund"]
      }
    },
    {
      "type": "daily_limit",
      "params": {
        "amount": "100000",
        "asset_code": "USD"
      }
    }
  ]
}

Policy Validation Errors

When a policy rule fails, the API returns detailed error information:

{
  "error": {
    "code": "POLICY_VIOLATION",
    "message": "Operation denied by policy",
    "details": {
      "policy_id": "pol_promotional",
      "rule_type": "intent_allowed",
      "reason": "Intent 'withdrawal' not permitted by policy"
    }
  }
}

Lots - Policies are assigned to lots
Ledger - Policy evaluations are recorded
Reservations - Policies affect what can be reserved