Wallet Rules

Wallet rules define automated behaviors and transfer limits for wallets. Each rule is scoped to a specific wallet, network, and network currency.

Rule Types

Type	Value	Description
Auto Transfer	auto_transfer	Automatically transfers funds based on conditions
Permissionless Transfer Limit	permissionless_transfer_limit	Limits the amount that can be transferred without approval

Wallet Rule Model

Field	Type	Description
id	string (UUID)	Unique rule identifier
created_by_user_id	string (UUID)	User who created the rule
wallet_id	string (UUID)	Wallet this rule applies to
name	string	Rule name
type	string	Rule type (auto_transfer or permissionless_transfer_limit)
network_id	string (UUID)	Network this rule applies to
network_currency_id	string (UUID)	Currency this rule applies to
priority	integer	Rule priority (1-100)
auto_transfer_type	string | null	Auto-transfer sub-type (see below)
auto_transfer_id	string (UUID) | null	Auto-transfer rule detail ID
auto_transfer_target_wallet_id	string (UUID) | null	Target wallet for auto-transfers
sign_and_approve_rule_id	string (UUID) | null	Sign-and-approve rule detail ID
permissionless_transfer_limit_id	string (UUID) | null	Permissionless transfer limit detail ID
created_at	string (ISO 8601)	Creation timestamp
updated_at	string (ISO 8601)	Last update timestamp
deleted_at	string (ISO 8601) | null	Soft deletion timestamp

---

Auto-Transfer Rules

Auto-transfer rules define conditions under which funds are automatically moved between wallets.

Auto-Transfer Sub-Types

Value	Description
auto	Fully automatic -- transfers execute without any user intervention
auto_with_approve	Automatic with approval -- transfers require user approval before execution
auto_with_sign	Automatic with signing -- transfers require cryptographic signing
approve	Approval only -- requires manual approval to trigger
sign	Sign only -- requires cryptographic signing to trigger

RuleLogic Structure

The rule_logic field defines the conditions for triggering an auto-transfer. It is a recursive tree structure using logical operators (AND/OR) and leaf conditions.

Operator Node

Groups multiple conditions with a logical operator.

{
  "operator": "AND",
  "conditions": [
    { "...condition or nested operator..." },
    { "...condition or nested operator..." }
  ],
  "network_currency_id": "880e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Required	Description
operator	string	No	AND or OR (defaults to AND if omitted)
conditions	array	Yes (for operators)	Array of nested conditions or operators
network_currency_id	string (UUID)	Yes	Currency context for evaluation

Leaf Condition

A single comparison condition.

{
  "field": "target.balance",
  "op": "<",
  "value": 100,
  "network_currency_id": "880e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Required	Description
field	string	Yes (for leaves)	Field to check (see valid fields below)
op	string	Yes (for leaves)	Comparison operator: =, <, >
value	any	Yes (for leaves)	Value to compare against
network_currency_id	string (UUID)	Yes	Currency context for evaluation

Valid Fields

Value	Description
target.balance	Target wallet balance

Valid Operators

Value	Description
=	Equal to
<	Less than
>	Greater than

RuleLogic Examples

Simple condition -- transfer when target balance drops below 100:

{
  "field": "target.balance",
  "op": "<",
  "value": 100,
  "network_currency_id": "880e8400-e29b-41d4-a716-446655440000"
}

AND condition -- transfer when balance is below 100 AND above 0:

{
  "operator": "AND",
  "conditions": [
    {
      "field": "target.balance",
      "op": "<",
      "value": 100,
      "network_currency_id": "880e8400-e29b-41d4-a716-446655440000"
    },
    {
      "field": "target.balance",
      "op": ">",
      "value": 0,
      "network_currency_id": "880e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "network_currency_id": "880e8400-e29b-41d4-a716-446655440000"
}

Nested conditions -- complex multi-currency logic:

{
  "operator": "OR",
  "conditions": [
    {
      "field": "target.balance",
      "op": "<",
      "value": 50,
      "network_currency_id": "880e8400-e29b-41d4-a716-446655440000"
    },
    {
      "operator": "AND",
      "conditions": [
        {
          "field": "target.balance",
          "op": "<",
          "value": 200,
          "network_currency_id": "880e8400-e29b-41d4-a716-446655440001"
        },
        {
          "field": "target.balance",
          "op": ">",
          "value": 10,
          "network_currency_id": "880e8400-e29b-41d4-a716-446655440001"
        }
      ],
      "network_currency_id": "880e8400-e29b-41d4-a716-446655440001"
    }
  ],
  "network_currency_id": "880e8400-e29b-41d4-a716-446655440000"
}

---

Sign and Approve Rules

Sign-and-approve rules define who can approve auto-transfer transactions and how many approvals are needed.

Field	Type	Required	Description
mandatory_user_id	string (UUID) | null	No	A specific user who MUST approve (in addition to others)
min_priority	integer | null	No	Minimum role priority required to approve (1-100)
max_priority	integer | null	No	Maximum role priority allowed to approve (1-100)
min_user_count	integer | null	No	Minimum number of unique approvals required (min: 1)

note

At least one field must be set. If both min_priority and max_priority are set, min_priority must be less than or equal to max_priority.

---

Permissionless Transfer Limit Rules

These rules cap the total amount that can be transferred from a wallet within a rolling time window without requiring approval.

Field	Type	Required	Description
max_amount	integer	Yes	Maximum transfer amount allowed in the time window (must be > 0)
time_period	string	Yes	Time period unit (see below)
time_period_value	integer	Yes	Number of time periods (must be > 0)

Time Period Values

Value	Description
hour	Hourly window
day	Daily window
week	Weekly window
month	Monthly window (30 days)
year	Yearly window (365 days)

Example: max_amount: 1000, time_period: "day", time_period_value: 1 means "max 1000 units per day".

---

Endpoints

Method	Path	Description
POST	/v1/wallets/{wallet_id}/rules	Create a wallet rule
GET	/v1/wallets/{wallet_id}/rules	List wallet rules
GET	/v1/wallets/{wallet_id}/rules/{id}	Get wallet rule detail
PUT	/v1/wallets/{wallet_id}/rules/{id}	Update a wallet rule