Address Book V2

Migrating from Address Book V1

Address Book V2 was released on 2026-03-31. V1 supported a single default address list only. V2 introduces multi-book support and governance workflows while keeping the existing "default" book intact — your V1 entries are still accessible via the default book. No migration of existing entries is required. V1 API endpoints are deprecated; use the V2 GraphQL queries and mutations documented here.

This guide outlines the transition to Address Book V2, a significant upgrade to our address management system. This version introduces multi-book support, enhanced governance workflows, and dynamic chain compatibility to provide greater flexibility and security for your assets.

Key Enhancements

Multiple Books: You are no longer limited to a single list. Manage multiple named address books (e.g., "Whitelisted Traders," "Cold Storage") alongside the legacy "default" book.

Mutable Definitions: You can now edit address book names and update the appliesTo wallet configurations after the book has been created.

Query Usage

1. List All Address Books

Retrieves all address books associated with the authenticated user, including metadata and nested entries. This is ideal for a high-level dashboard view.

2. Get Single Address Book

Retrieves a specific address book. Use the nextToken for paginating through large lists of entries.

3. Get Approvals

Retrieves pending or historical governance approvals related to address book changes.

Mutation Usage

1. Create a New Address Book

Creates a new container for addresses.

appliesTo: Set to ["*"] to target all wallets or provide specific wallet IDs.

approvalProcess: Defines the governance logic: NONE, WALLET or EMAIL.

2. Add Entries (Bulk or Single)

3. Edit an Address Book

Updates the metadata of an existing book. Note that the appliesTo array will completely overwrite the existing wallet associations.

4. Delete Operations

You can delete specific entries by providing an array of IDs, or delete an entire book.

Delete Entries:

Delete Entire Book:

Key Enhancements#

Query Usage#

1. List All Address Books#

2. Get Single Address Book#

3. Get Approvals#

Mutation Usage#

1. Create a New Address Book#

2. Add Entries (Bulk or Single)#

3. Edit an Address Book#

4. Delete Operations#