SearchAccounts

Searches accounts using flexible text criteria within the hierarchy.

Performs case-insensitive substring matching on display names, returning accounts that match the search criteria.

Overview

Method Options

Authorisation specification of the SearchAccounts method.

Type	METHOD_TYPE_READ
Access Level	METHOD_ACCESS_LEVEL_AUTHORISED
Roles	ROLE_WALLET_ADMIN ROLE_WALLET_VIEWER ROLE_WALLET_ACCOUNT_ADMIN ROLE_WALLET_ACCOUNT_VIEWER

Parameters

Request and response parameter message overview:

Input: SearchAccountsRequest Message

Field	Type	Required	Description
Sorting	Field Type Required Description Field string False Field to sort by. Supported values: "number" or empty string for default ordering. Order meshtrade.type.v1.SortingOrder False Sort order for results.	False	Optional sorting configuration.
DisplayName	string	False	Optional substring to search for in account display names. Case-insensitive partial matching.
PopulateLedgerData	bool	False	When true, fetches current balances and state from the ledger. When false, returns only stored metadata without live data.

Returns: SearchAccountsResponse Message

Field	Type	Description
Accounts	meshtrade.wallet.account.v1.Account[]	Collection of accounts matching the search criteria.

Protobuf

syntax = "proto3";

package meshtrade.wallet.account.v1;

import "buf/validate/validate.proto";
import "meshtrade/option/method_options/v1/method_options.proto";
import "meshtrade/type/v1/sorting.proto";
import "meshtrade/type/v1/token.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 ledger wallet accounts and their lifecycle operations (BETA).

   This service provides comprehensive account management capabilities across multiple
   ledger 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 ledger 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.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_ACCOUNT_ADMIN
      ]
      verification_status: VERIFICATION_STATUS_VERIFIED
    };
  }

  /*
     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.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_ACCOUNT_ADMIN
      ]
      verification_status: VERIFICATION_STATUS_VERIFIED
    };
  }

  /*
     Opens an account on the 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 ledger operation.
  */
  rpc OpenAccount(OpenAccountRequest) returns (OpenAccountResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_ACCOUNT_ADMIN
      ]
      verification_status: VERIFICATION_STATUS_VERIFIED
    };
  }

  /*
     Adds the given users as signatories to an account on the ledger.

     Returns a transaction reference for monitoring the ledger operation.
  */
  rpc AddSignatoriesToAccount(AddSignatoriesToAccountRequest) returns (AddSignatoriesToAccountResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_ACCOUNT_ADMIN
      ]
      verification_status: VERIFICATION_STATUS_VERIFIED
    };
  }

  /*
     Removes the given users as signatories from an account on the ledger.

     Returns a transaction reference for monitoring the ledger operation.
  */
  rpc RemoveSignatoriesFromAccount(RemoveSignatoriesFromAccountRequest) returns (RemoveSignatoriesFromAccountResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_ACCOUNT_ADMIN
      ]
      verification_status: VERIFICATION_STATUS_VERIFIED
    };
  }

  /*
     Retrieves a specific account by its resource identifier.

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

  /*
     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.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_VIEWER,
        ROLE_WALLET_ACCOUNT_ADMIN,
        ROLE_WALLET_ACCOUNT_VIEWER
      ]
      verification_status: VERIFICATION_STATUS_VERIFIED
    };
  }

  /*
     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.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_VIEWER,
        ROLE_WALLET_ACCOUNT_ADMIN,
        ROLE_WALLET_ACCOUNT_VIEWER
      ]
      verification_status: VERIFICATION_STATUS_VERIFIED
    };
  }

  /*
     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.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_VIEWER,
        ROLE_WALLET_ACCOUNT_ADMIN,
        ROLE_WALLET_ACCOUNT_VIEWER
      ]
      verification_status: VERIFICATION_STATUS_VERIFIED
    };
  }

  /*
     Registers tokens to an account on the ledger.

     Performs the necessary operations to configure the account to receive
     and hold the specified tokens. Returns a transaction reference for
     monitoring the ledger operation.
  */
  rpc RegisterTokensToAccount(RegisterTokensToAccountRequest) returns (RegisterTokensToAccountResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_ACCOUNT_ADMIN
      ]
      verification_status: VERIFICATION_STATUS_VERIFIED
    };
  }

  /*
     Deregisters tokens from an account on the ledger.

     Performs the necessary operations to configure the account such that it
     can no longer receive or hold the specified tokens. The balance of each
     specified token must be zero before this method will succeed. Returns a
     transaction reference for monitoring the ledger operation.
  */
  rpc DeregisterTokensFromAccount(DeregisterTokensFromAccountRequest) returns (DeregisterTokensFromAccountResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_ACCOUNT_ADMIN
      ]
      verification_status: VERIFICATION_STATUS_VERIFIED
    };
  }
}

/*
   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 ledger.
*/
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 a transaction reference to monitor the ledger operation to open the account.
*/
message OpenAccountResponse {
  /*
     Transaction reference for monitoring the ledger operation to open the account.
     The Account is open once this transaction has succeeded.
     Format: transactions/{ULIDv2}.
  */
  string ledger_transaction = 1;
}

/*
   Request to add signatories to an account on the ledger.
*/
message AddSignatoriesToAccountRequest {
  /*
     The resource name of the account to which signatories should be added.
     Format: accounts/{ULIDv2}.
  */
  string name = 1 [(buf.validate.field) = {
    string: {
      len: 35
      pattern: "^accounts/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];

  /*
     The resource names of the (api)users to add as signatories on the identified account.
     Format: iam/api_users/{ULIDv2} or users/{ULIDv2}.
     At least one user must be provided.
  */
  repeated string users = 2 [(buf.validate.field) = {
    repeated: {
      min_items: 1
      max_items: 100
      items: {
        cel: {
          id: "users.format"
          message: "each user must be iam/api_users/{ULID} or users/{ULID}"
          expression: "this.matches('^users/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$') || this.matches('^iam/api_users/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$')"
        }
      }
    }
  }];
}

/*
   Response containing a transaction reference to monitor the ledger operation to add signatories.
*/
message AddSignatoriesToAccountResponse {
  /*
     Transaction reference for monitoring the ledger operation to add the given users as signatories.
     The signatories are added once this transaction has succeeded.
     Format: transactions/{ULIDv2}.
  */
  string ledger_transaction = 1;
}

/*
   Request to remove signatories from an account on the ledger.
*/
message RemoveSignatoriesFromAccountRequest {
  /*
     The resource name of the account from which signatories should be removed.
     Format: accounts/{ULIDv2}.
  */
  string name = 1 [(buf.validate.field) = {
    string: {
      len: 35
      pattern: "^accounts/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];

  /*
     The resource names of the (api)users to remove as signatories from the identified account.
     Format: api_users/{ULIDv2} or users/{ULIDv2}.
     At least one user must be provided.
  */
  repeated string users = 2 [(buf.validate.field) = {
    repeated: {
      min_items: 1
      max_items: 100
      items: {
        cel: {
          id: "users.format"
          message: "each user must be iam/api_users/{ULID} or users/{ULID}"
          expression: "this.matches('^users/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$') || this.matches('^iam/api_users/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$')"
        }
      }
    }
  }];
}

/*
   Response containing a transaction reference to monitor the ledger operation to remove signatories.
*/
message RemoveSignatoriesFromAccountResponse {
  /*
     Transaction reference for monitoring the ledger operation to remove the given users as signatories.
     The signatories are removed once this transaction has succeeded.
     Format: transactions/{ULIDv2}.
  */
  string ledger_transaction = 1;
}

/*
   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 ledger.
     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 ledger.
     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 ledger.
     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 ledger.
     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;
}

/*
   Request to register tokens to an account on the ledger.
*/
message RegisterTokensToAccountRequest {
  /*
     The resource name of the account to which tokens should be registered.
     Format: accounts/{ULIDv2}.
  */
  string name = 1 [(buf.validate.field) = {
    string: {
      len: 35
      pattern: "^accounts/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];

  /*
     The tokens to register on the identified account.
     At least one token must be provided.
  */
  repeated type.v1.Token tokens = 2 [(buf.validate.field) = {
    repeated: {
      min_items: 1
      max_items: 10
    }
  }];
}

/*
   Response containing a transaction reference to monitor the ledger operation to register tokens.
*/
message RegisterTokensToAccountResponse {
  /*
     Transaction reference for monitoring the ledger operation to register the tokens on the account.
     The account is configured to hold/receive the given tokens once this transaction has succeeded.
     Format: transactions/{ULIDv2}.
  */
  string ledger_transaction = 1;
}

/*
   Request to deregister tokens from an account on the ledger.
*/
message DeregisterTokensFromAccountRequest {
  /*
     The resource name of the account from which tokens should be deregistered.
     Format: accounts/{ULIDv2}.
  */
  string name = 1 [(buf.validate.field) = {
    string: {
      len: 35
      pattern: "^accounts/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];

  /*
     The tokens to deregister from the identified account.
     At least one token must be provided.
  */
  repeated type.v1.Token tokens = 2 [(buf.validate.field) = {
    repeated: {
      min_items: 1
      max_items: 10
    }
  }];
}

/*
   Response containing a transaction reference to monitor the ledger operation to deregister tokens.
*/
message DeregisterTokensFromAccountResponse {
  /*
     Transaction reference for monitoring the ledger operation to deregister the tokens from the account.
     The account will no longer be configured to hold/receive the given tokens once this transaction has succeeded.
     Format: transactions/{ULIDv2}.
  */
  string ledger_transaction = 1;
}

Code Examples

Select supported SDK in the language of your choice for a full example of how to invoke the this method:

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()

	// Search for accounts by display name substring
	request := &accountv1.SearchAccountsRequest{
		DisplayName:        "Trading", // Search for accounts with "Trading" in name
		PopulateLedgerData: false,     // Set to true to fetch live blockchain data
			Sorting: &accountv1.SearchAccountsRequest_Sorting{
			Field: "number",                                 // Sort by account number
			Order: typev1.SortingOrder_SORTING_ORDER_DESC, // Descending order
		},
	}

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

	// Display search results
	log.Printf("Found %d accounts matching '%s':", len(response.Accounts), request.DisplayName)
	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_DESC
from meshtrade.wallet.account.v1 import (
    AccountService,
    SearchAccountsRequest,
)


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:
        # Search for accounts by display name substring
        request = SearchAccountsRequest(
            display_name="Trading",  # Search for accounts with "Trading" in name
            populate_ledger_data=False,  # Set to True to fetch live blockchain data
            sorting=SearchAccountsRequest.Sorting(
                field="number",  # Sort by account number
                order=SORTING_ORDER_DESC,  # Descending order
            ),
        )

        # Call the SearchAccounts method
        response = service.search_accounts(request)

        # Display search results
        print(f"Found {len(response.accounts)} accounts matching '{request.display_name}':")
        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.SearchAccountsRequest;
import co.meshtrade.api.wallet.account.v1.Service.SearchAccountsResponse;
import co.meshtrade.api.type.v1.Sorting.SortingOrder;

import java.util.Optional;

public class SearchAccountsExample {
    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()) {
            // Search for accounts by display name substring
            SearchAccountsRequest request = SearchAccountsRequest.newBuilder()
                .setDisplayName("Trading")       // Search for accounts with "Trading" in name
                .setPopulateLedgerData(false)    // Set to true to fetch live blockchain data
                .setSorting(SearchAccountsRequest.Sorting.newBuilder()
                    .setField("number")                               // Sort by account number
                    .setOrder(SortingOrder.SORTING_ORDER_DESC)         // Descending order
                    .build())
                .build();

            // Call the SearchAccounts method
            SearchAccountsResponse response = service.searchAccounts(request, Optional.empty());

            // Display search results
            System.out.println("Found " + response.getAccountsCount() + 
                             " accounts matching '" + request.getDisplayName() + "':");
            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("SearchAccounts failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

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