GetAccountByNumber

Method Details

Description: 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.

Required Roles: Check proto file for roles

Parameters:

• AccountNumber (string): The Account Number. Must be a 7-digit number starting with '1'.
• PopulateLedgerData (bool): When true, fetches current balances and state from the blockchain. When false, returns only stored metadata without live data.

Returns: Account

Method Type: METHOD_TYPE_READ

Code Examples

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

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