ListAccounts

Method Details

Description: Lists all accounts within the authenticated group's hierarchical scope.

Returns the complete set of accounts accessible to the executing context, including accounts owned by the group and all descendant groups.

Required Roles: Check proto file for roles

Parameters:

• Sorting (message) (required): Optional sorting configuration.
• PopulateLedgerData (bool): When true, fetches current balances and state from the blockchain. When false, returns only stored metadata without live data.

Returns: ListAccountsResponse

Method Type: METHOD_TYPE_READ

Code Examples

Go

package main

import (
	"context"
	"log"

	accountv1 "github.com/meshtrade/api/go/wallet/account/v1"
	typev1 "github.com/meshtrade/api/go/type/v1"
)

func main() {
	ctx := context.Background()

	// Default configuration is used and credentials come from MESH_API_CREDENTIALS
	// environment variable or default discovery methods. Zero config required
	// unless you want custom configuration.
	service, err := accountv1.NewAccountService()
	if err != nil {
		log.Fatalf("Failed to create service: %v", err)
	}
	defer service.Close()

	// Create request with service-specific parameters
	request := &accountv1.ListAccountsRequest{
		PopulateLedgerData: false, // Set to true to fetch live blockchain data
			Sorting: &accountv1.ListAccountsRequest_Sorting{
			Field: "number",                                // Sort by account number
			Order: typev1.SortingOrder_SORTING_ORDER_ASC, // Ascending order
		},
	}

	// Call the ListAccounts method
	response, err := service.ListAccounts(ctx, request)
	if err != nil {
		log.Fatalf("ListAccounts failed: %v", err)
	}

	// Display all accounts in the hierarchy
	log.Printf("Found %d accounts:", len(response.Accounts))
	for _, account := range response.Accounts {
		log.Printf("  Account %s:", account.Number)
		log.Printf("    Name: %s", account.Name)
		log.Printf("    Display Name: %s", account.DisplayName)
		log.Printf("    Ledger: %s", account.Ledger)
		log.Printf("    State: %s", account.State)
	}
}

Python

from meshtrade.type.v1.sorting_pb2 import SORTING_ORDER_ASC
from meshtrade.wallet.account.v1 import (
    AccountService,
    ListAccountsRequest,
)


def main():
    # Default configuration is used and credentials come from MESH_API_CREDENTIALS
    # environment variable or default discovery methods. Zero config required
    # unless you want custom configuration.
    service = AccountService()

    with service:
        # Create request with optional parameters
        request = ListAccountsRequest(
            populate_ledger_data=False,  # Set to True to fetch live blockchain data
            sorting=ListAccountsRequest.Sorting(
                field="number",  # Sort by account number
                order=SORTING_ORDER_ASC,  # Ascending order
            ),
        )

        # Call the ListAccounts method
        response = service.list_accounts(request)

        # Display all accounts in the hierarchy
        print(f"Found {len(response.accounts)} accounts:")
        for account in response.accounts:
            print(f"  Account {account.number}:")
            print(f"    Name: {account.name}")
            print(f"    Display Name: {account.display_name}")
            print(f"    Ledger: {account.ledger}")
            print(f"    State: {account.state}")


if __name__ == "__main__":
    main()

Java

import co.meshtrade.api.wallet.account.v1.AccountService;
import co.meshtrade.api.wallet.account.v1.Service.ListAccountsRequest;
import co.meshtrade.api.wallet.account.v1.Service.ListAccountsResponse;
import co.meshtrade.api.type.v1.Sorting.SortingOrder;

import java.util.Optional;

public class ListAccountsExample {
    public static void main(String[] args) {
        // Default configuration is used and credentials come from MESH_API_CREDENTIALS
        // environment variable or default discovery methods. Zero config required
        // unless you want custom configuration.
        try (AccountService service = new AccountService()) {
            // Create request with optional parameters
            ListAccountsRequest request = ListAccountsRequest.newBuilder()
                .setPopulateLedgerData(false)  // Set to true to fetch live blockchain data
                .setSorting(ListAccountsRequest.Sorting.newBuilder()
                    .setField("number")                              // Sort by account number
                    .setOrder(SortingOrder.SORTING_ORDER_ASC)         // Ascending order
                    .build())
                .build();

            // Call the ListAccounts method
            ListAccountsResponse response = service.listAccounts(request, Optional.empty());

            // Display all accounts in the hierarchy
            System.out.println("Found " + response.getAccountsCount() + " accounts:");
            response.getAccountsList().forEach(account -> {
                System.out.println("  Account " + account.getNumber() + ":");
                System.out.println("    Name: " + account.getName());
                System.out.println("    Display Name: " + account.getDisplayName());
                System.out.println("    Ledger: " + account.getLedger());
                System.out.println("    State: " + account.getState());
            });
        } catch (Exception e) {
            System.err.println("ListAccounts failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Protobuf

syntax = "proto3";

package meshtrade.wallet.account.v1;

import "buf/validate/validate.proto";
import "meshtrade/iam/role/v1/role.proto";
import "meshtrade/option/v1/method_type.proto";
import "meshtrade/type/v1/sorting.proto";
import "meshtrade/wallet/account/v1/account.proto";

option go_package = "github.com/meshtrade/api/go/wallet/account/v1;account_v1";
option java_package = "co.meshtrade.api.wallet.account.v1";

/*
   AccountService manages blockchain wallet accounts and their lifecycle operations (BETA).

   This service provides comprehensive account management capabilities across multiple
   blockchain networks (Stellar, Solana, Bitcoin, Ethereum). Accounts serve as the 
   primary containers for holding and managing digital assets on the Mesh platform.
   
   Key capabilities include account creation, opening on-chain, balance queries,
   and account lifecycle management. All operations are scoped to the authenticated
   group's hierarchy and require appropriate wallet domain permissions.

   Note: This service is currently in BETA. Interface and functionality may change.
*/
service AccountService {
  /*
     Creates a new account record in the system (off-chain).

     The account is created in a pending state and must be explicitly opened
     on the blockchain using OpenAccount before it can receive funds or execute
     transactions. Account ownership must match the executing context.
  */
  rpc CreateAccount(CreateAccountRequest) returns (meshtrade.wallet.account.v1.Account) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_WRITE;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_ACCOUNT_ADMIN
      ]
    };
  }

  /*
     Updates an existing account's mutable metadata.

     Only the display_name field can be modified. All other fields including
     ownership, ledger, and account number are immutable after creation.
  */
  rpc UpdateAccount(UpdateAccountRequest) returns (meshtrade.wallet.account.v1.Account) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_WRITE;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_ACCOUNT_ADMIN
      ]
    };
  }

  /*
     Opens an account on the blockchain ledger.

     Initializes the account on-chain, making it ready to receive deposits
     and execute transactions. Returns the opened account and a transaction
     reference for monitoring the blockchain operation.
  */
  rpc OpenAccount(OpenAccountRequest) returns (OpenAccountResponse) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_WRITE;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_ACCOUNT_ADMIN
      ]
    };
  }

  /*
     Retrieves a specific account by its resource identifier.

     Provides access to account metadata and optionally fetches live
     balance data from the blockchain when populate_ledger_data is true.
  */
  rpc GetAccount(GetAccountRequest) returns (meshtrade.wallet.account.v1.Account) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_VIEWER,
        ROLE_WALLET_ACCOUNT_ADMIN,
        ROLE_WALLET_ACCOUNT_VIEWER
      ]
    };
  }

  /*
     Retrieves an account using its Account Number.

     Provides a convenient lookup method using the 7-digit account number.
     Optionally fetches live balance data when populate_ledger_data is true.
  */
  rpc GetAccountByNumber(GetAccountByNumberRequest) returns (meshtrade.wallet.account.v1.Account) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_VIEWER,
        ROLE_WALLET_ACCOUNT_ADMIN,
        ROLE_WALLET_ACCOUNT_VIEWER
      ]
    };
  }

  /*
     Lists all accounts within the authenticated group's hierarchical scope.

     Returns the complete set of accounts accessible to the executing context,
     including accounts owned by the group and all descendant groups.
  */
  rpc ListAccounts(ListAccountsRequest) returns (ListAccountsResponse) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_VIEWER,
        ROLE_WALLET_ACCOUNT_ADMIN,
        ROLE_WALLET_ACCOUNT_VIEWER
      ]
    };
  }


  /*
     Searches accounts using flexible text criteria within the hierarchy.

     Performs case-insensitive substring matching on display names,
     returning accounts that match the search criteria.
  */
  rpc SearchAccounts(SearchAccountsRequest) returns (SearchAccountsResponse) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_VIEWER,
        ROLE_WALLET_ACCOUNT_ADMIN,
        ROLE_WALLET_ACCOUNT_VIEWER        
      ]
    };
  }
}

/*
   Request to create a new account.
*/
message CreateAccountRequest {
  /*
     The account configuration for creation.
     The name, number, ledger_id, and owners fields will be ignored and assigned by the system.
  */
  meshtrade.wallet.account.v1.Account account = 1  [(buf.validate.field) = {required: true}];
}

/*
   Request to update an existing account.
*/
message UpdateAccountRequest {
  /*
     Complete account resource with updated fields.
     Only display_name can be modified.
  */
  meshtrade.wallet.account.v1.Account account = 1  [(buf.validate.field) = {required: true}];
}

/*
   Request to open an account on the blockchain.
*/
message OpenAccountRequest {
  /*
     The resource name of the account to open.
     Format: accounts/{ULIDv2}.
  */
  string name = 1 [(buf.validate.field) = {
    string: {
      len: 35,
      pattern: "^accounts/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];
}

/*
   Response containing the opened account and transaction details.
*/
message OpenAccountResponse {
  /*
     The account after successful opening on the blockchain.
  */
  meshtrade.wallet.account.v1.Account account = 1;

  /*
     Transaction reference for monitoring the blockchain operation.
     Format: transactions/{ULIDv2}.
  */
  string ledger_transaction = 3;
}

/*
   Request to retrieve a specific account.
*/
message GetAccountRequest {
  /*
     The resource name of the account to retrieve.
     Format: accounts/{ULIDv2}.
  */
  string name = 1 [(buf.validate.field) = {
    string: {
      len: 35,
      pattern: "^accounts/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];
  
  /*
     When true, fetches current balances and state from the blockchain.
     When false, returns only stored metadata without live data.
  */
  bool populate_ledger_data = 2;
}

/*
   Request to retrieve an account by its account number.
*/
message GetAccountByNumberRequest {
  /*
     The Account Number.
     Must be a 7-digit number starting with '1'.
  */
  string account_number = 1 [(buf.validate.field) = {
    string: {
      pattern: "^1[0-9]{6}$"
    }
  }];

  /*
     When true, fetches current balances and state from the blockchain.
     When false, returns only stored metadata without live data.
  */
  bool populate_ledger_data = 2;
}

/*
   Request to list all accounts in the hierarchy.
*/
message ListAccountsRequest {
  /*
     Sorting configuration for organizing results.
  */
  message Sorting {
    /*
       Field to sort by.
       Supported values: "number" or empty string for default ordering.
    */
    string field = 1 [(buf.validate.field) = {
      string: {
        in: [
          "",
          "number"
        ]
      }
      cel: {
        id: "field.valid"
        message: "field must be one of: number, or empty"
        expression: "this in ['', 'number']"
      }
    }];

    /*
       Sort order for results.
    */
    meshtrade.type.v1.SortingOrder order = 2;
  }

  /*
     Optional sorting configuration.
  */
  Sorting sorting = 1;

  /*
     When true, fetches current balances and state from the blockchain.
     When false, returns only stored metadata without live data.
  */
  bool populate_ledger_data = 2;
}

/*
   Response containing a list of accounts.
*/
message ListAccountsResponse {
  /*
     Collection of accounts in the hierarchy.
  */
  repeated meshtrade.wallet.account.v1.Account accounts = 1;
}

/*
   Request to search accounts with filtering criteria.
*/
message SearchAccountsRequest {
  /*
     Sorting configuration for organizing results.
  */
  message Sorting {
    /*
       Field to sort by.
       Supported values: "number" or empty string for default ordering.
    */
    string field = 1 [(buf.validate.field) = {
      string: {
        in: [
          "",
          "number"
        ]
      }
      cel: {
        id: "field.valid"
        message: "field must be one of: number, or empty"
        expression: "this in ['', 'number']"
      }
    }];

    /*
       Sort order for results.
    */
    meshtrade.type.v1.SortingOrder order = 2;
  }

  /*
     Optional sorting configuration.
  */
  Sorting sorting = 1;

  /*
     Optional substring to search for in account display names.
     Case-insensitive partial matching.
  */
  string display_name = 2 [(buf.validate.field) = {
    string: {max_len: 255}
    cel: {
      id: "display_name.max_length"
      message: "display_name search term must not exceed 255 characters"
      expression: "size(this) <= 255"
    }
  }];

  /*
     When true, fetches current balances and state from the blockchain.
     When false, returns only stored metadata without live data.
  */
  bool populate_ledger_data = 3;
}

/*
   Response containing search results.
*/
message SearchAccountsResponse {
  /*
     Collection of accounts matching the search criteria.
  */
  repeated meshtrade.wallet.account.v1.Account accounts = 1;
}

Advanced Configuration

For advanced client configuration options (custom endpoints, TLS settings, timeouts), see the SDK Configuration Guide.

Other Methods

• Wallet Account v1 Method List - For Other methods