Named Lists
Named lists are reusable collections of addresses or values used in policy rules. They simplify policy management by centralizing allowlists, blocklists, and other collections.
What is a Named List?
A named list is a collection of values that can be referenced by policies:
- Centralized Management — Update once, apply everywhere
- Policy Reuse — Reference lists in multiple policies
- Easy Auditing — Track list membership changes
- Dynamic Updates — Modify lists without changing policies
List Types
| Type | Description | Example Use |
|---|---|---|
ADDRESS | Blockchain addresses (0x...) | Allowlisted recipients, blocked addresses |
How Lists Work with Policies
Named lists are referenced in policy conditions using the IN_LIST and NOT_IN_LIST operators:
Common Use Cases
Counterparty Allowlist
Maintain a list of verified business partners and exchanges:
| List Name | Type | Purpose |
|---|---|---|
approved-counterparties | ADDRESS | KYC-verified recipient addresses |
Policy usage: Block transfers to addresses NOT in this list.
Sanctions Blocklist
Block known sanctioned or high-risk addresses:
| List Name | Type | Purpose |
|---|---|---|
sanctioned-addresses | ADDRESS | OFAC and other sanctioned addresses |
Policy usage: Block transfers to addresses IN this list.
Internal Vaults
Track your organization's vault addresses:
| List Name | Type | Purpose |
|---|---|---|
internal-vaults | ADDRESS | All vault addresses owned by organization |
Policy usage: Allow transfers between internal vaults without approval.
Policy usage: Block transactions to chains NOT in this list.
List Membership Checking
Before submitting a transaction, you can verify if an address is in a list:
This enables:
- Pre-flight validation before transaction submission
- User feedback ("This recipient is not on your allowlist")
- Conditional UI flows
Best Practices
Naming Conventions
Use clear, descriptive names:
| Good | Bad |
|---|---|
approved-counterparties-production | list1 |
ofac-sanctioned-addresses | blocklist |
internal-treasury-vaults | vaults |
Organization
| Practice | Description |
|---|---|
| Separate by purpose | Different lists for allowlists, blocklists, internal addresses |
| Include descriptions | Document the list's purpose and update criteria |
| Use consistent formatting | Lowercase addresses, consistent naming conventions |
Maintenance
| Practice | Description |
|---|---|
| Regular audits | Review list contents periodically |
| Document changes | Track who added/removed items and why |
| Version control | Consider exporting lists for backup |
| Automate updates | Use API for dynamic list management |
Security
| Practice | Description |
|---|---|
| Verify before adding | Confirm addresses before adding to allowlists |
| Monitor blocklists | Keep sanctioned address lists current |
| Limit access | Control who can modify critical lists |
| Audit trail | Review list modification logs |
Integration Patterns
Automated Allowlist Sync
Sync your allowlist with an external KYC system:
Related Topics
- Policies — Using lists in policy rules
- Transactions — Policy evaluation during transactions
API Reference
For complete API documentation including endpoints, request/response examples, and code samples:
- List all named lists —
GET /api/v1/named-lists - Create a new named list —
POST /api/v1/named-lists - Get named list by ID —
GET /api/v1/named-lists/{id} - Update a named list —
PUT /api/v1/named-lists/{id} - Delete a named list —
DELETE /api/v1/named-lists/{id} - Add items to a named list —
POST /api/v1/named-lists/{id}/items - Remove items from a named list —
DELETE /api/v1/named-lists/{id}/items - Check if value exists in list —
GET /api/v1/named-lists/{id}/check/{value}
Named Lists
Named lists are reusable collections of addresses or values used in policy rules. They simplify policy management by centralizing allowlists, blocklists, and other collections.
What is a Named List?
A named list is a collection of values that can be referenced by policies:
- Centralized Management — Update once, apply everywhere
- Policy Reuse — Reference lists in multiple policies
- Easy Auditing — Track list membership changes
- Dynamic Updates — Modify lists without changing policies
List Types
| Type | Description | Example Use |
|---|---|---|
ADDRESS | Blockchain addresses (0x...) | Allowlisted recipients, blocked addresses |
How Lists Work with Policies
Named lists are referenced in policy conditions using the IN_LIST and NOT_IN_LIST operators:
Common Use Cases
Counterparty Allowlist
Maintain a list of verified business partners and exchanges:
| List Name | Type | Purpose |
|---|---|---|
approved-counterparties | ADDRESS | KYC-verified recipient addresses |
Policy usage: Block transfers to addresses NOT in this list.
Sanctions Blocklist
Block known sanctioned or high-risk addresses:
| List Name | Type | Purpose |
|---|---|---|
sanctioned-addresses | ADDRESS | OFAC and other sanctioned addresses |
Policy usage: Block transfers to addresses IN this list.
Internal Vaults
Track your organization's vault addresses:
| List Name | Type | Purpose |
|---|---|---|
internal-vaults | ADDRESS | All vault addresses owned by organization |
Policy usage: Allow transfers between internal vaults without approval.
Policy usage: Block transactions to chains NOT in this list.
List Membership Checking
Before submitting a transaction, you can verify if an address is in a list:
This enables:
- Pre-flight validation before transaction submission
- User feedback ("This recipient is not on your allowlist")
- Conditional UI flows
Best Practices
Naming Conventions
Use clear, descriptive names:
| Good | Bad |
|---|---|
approved-counterparties-production | list1 |
ofac-sanctioned-addresses | blocklist |
internal-treasury-vaults | vaults |
Organization
| Practice | Description |
|---|---|
| Separate by purpose | Different lists for allowlists, blocklists, internal addresses |
| Include descriptions | Document the list's purpose and update criteria |
| Use consistent formatting | Lowercase addresses, consistent naming conventions |
Maintenance
| Practice | Description |
|---|---|
| Regular audits | Review list contents periodically |
| Document changes | Track who added/removed items and why |
| Version control | Consider exporting lists for backup |
| Automate updates | Use API for dynamic list management |
Security
| Practice | Description |
|---|---|
| Verify before adding | Confirm addresses before adding to allowlists |
| Monitor blocklists | Keep sanctioned address lists current |
| Limit access | Control who can modify critical lists |
| Audit trail | Review list modification logs |
Integration Patterns
Automated Allowlist Sync
Sync your allowlist with an external KYC system:
Related Topics
- Policies — Using lists in policy rules
- Transactions — Policy evaluation during transactions
API Reference
For complete API documentation including endpoints, request/response examples, and code samples:
- List all named lists —
GET /api/v1/named-lists - Create a new named list —
POST /api/v1/named-lists - Get named list by ID —
GET /api/v1/named-lists/{id} - Update a named list —
PUT /api/v1/named-lists/{id} - Delete a named list —
DELETE /api/v1/named-lists/{id} - Add items to a named list —
POST /api/v1/named-lists/{id}/items - Remove items from a named list —
DELETE /api/v1/named-lists/{id}/items - Check if value exists in list —
GET /api/v1/named-lists/{id}/check/{value}