GetAccountByNumber

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.

Overview

Method Options

Authorisation specification of the GetAccountByNumber 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: GetAccountByNumberRequest Message

Field	Type	Required	Description
AccountNumber	string	False	The Account Number. Must be a 7-digit number starting with '1'.
PopulateLedgerData	bool	False	When true, fetches current balances and state from the ledger. When false, returns only stored metadata without live data.

Returns: Account Message

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

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

	// Look up account using its 7-digit Account Number
	request := &accountv1.GetAccountByNumberRequest{
		AccountNumber:      "1234567", // 7-digit account number
		PopulateLedgerData: true,       // Fetch live blockchain data
	}

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

	// Display account information retrieved by number
	log.Printf("Account found by number %s:", request.AccountNumber)
	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)

	// Display balances if live data was populated
	if request.PopulateLedgerData && len(account.Balances) > 0 {
		log.Printf("  Balances:")
		for _, balance := range account.Balances {
			log.Printf("    %s: %s",
				balance.InstrumentMetadata.Name,
				balance.Amount.Value)
		}
	}
}

Python

from meshtrade.wallet.account.v1 import (
    AccountService,
    GetAccountByNumberRequest,
)


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:
        # Look up account using its 7-digit Account Number
        request = GetAccountByNumberRequest(
            account_number="1234567",  # 7-digit account number
            populate_ledger_data=True,  # Fetch live blockchain data
        )

        # Call the GetAccountByNumber method
        account = service.get_account_by_number(request)

        # Display account information retrieved by number
        print(f"Account found by number {request.account_number}:")
        print(f"  Name: {account.name}")
        print(f"  Display Name: {account.display_name}")
        print(f"  Ledger: {account.ledger}")
        print(f"  State: {account.state}")

        # Display balances if live data was populated
        if request.populate_ledger_data and account.balances:
            print("  Balances:")
            for balance in account.balances:
                print(f"    {balance.instrument_metadata.name}: {balance.amount.value}")


if __name__ == "__main__":
    main()

Java

import co.meshtrade.api.wallet.account.v1.AccountService;
import co.meshtrade.api.wallet.account.v1.Service.GetAccountByNumberRequest;
import co.meshtrade.api.wallet.account.v1.Account.Account;

import java.util.Optional;

public class GetAccountByNumberExample {
    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()) {
            // Look up account using its 7-digit Account Number
            GetAccountByNumberRequest request = GetAccountByNumberRequest.newBuilder()
                .setAccountNumber("1234567")  // 7-digit account number
                .setPopulateLedgerData(true)   // Fetch live blockchain data
                .build();

            // Call the GetAccountByNumber method
            Account account = service.getAccountByNumber(request, Optional.empty());

            // Display account information retrieved by number
            System.out.println("Account found by number " + request.getAccountNumber() + ":");
            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());

            // Display balances if live data was populated
            if (request.getPopulateLedgerData() && !account.getBalancesList().isEmpty()) {
                System.out.println("  Balances:");
                account.getBalancesList().forEach(balance -> 
                    System.out.println("    " + balance.getInstrumentMetadata().getName() + 
                                     ": " + balance.getAmount().getValue())
                );
            }
        } catch (Exception e) {
            System.err.println("GetAccountByNumber 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