OpenAccount

Method Details

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

Required Roles: Check proto file for roles

Parameters:

• Name (string) (required): The resource name of the account to open. Format: accounts/{ULIDv2}.

Returns: OpenAccountResponse

Method Type: Unknown

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

	// Open a previously created account on the blockchain
	request := &accountv1.OpenAccountRequest{
		Name: "accounts/01HQ3K5M8XYZ2NFVJT9BKR7P4C", // Account to open
	}

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

	// Account is now open on the blockchain
	log.Printf("Account opened successfully on blockchain:")
	log.Printf("  Account Name: %s", response.Account.Name)
	log.Printf("  Account Number: %s", response.Account.Number)
	log.Printf("  Ledger ID: %s", response.Account.LedgerId)
	log.Printf("  State: %s", response.Account.State)
	log.Printf("  Transaction: %s", response.LedgerTransaction)
	log.Printf("\nUse the transaction reference to monitor the blockchain operation.")
}

Python

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


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:
        # Open a previously created account on the blockchain
        request = OpenAccountRequest(
            name="accounts/01HQ3K5M8XYZ2NFVJT9BKR7P4C"  # Account to open
        )

        # Call the OpenAccount method
        response = service.open_account(request)

        # Account is now open on the blockchain
        print("Account opened successfully on blockchain:")
        print(f"  Account Name: {response.account.name}")
        print(f"  Account Number: {response.account.number}")
        print(f"  Ledger ID: {response.account.ledger_id}")
        print(f"  State: {response.account.state}")
        print(f"  Transaction: {response.ledger_transaction}")
        print("\nUse the transaction reference to monitor the blockchain operation.")


if __name__ == "__main__":
    main()

Java

import co.meshtrade.api.wallet.account.v1.AccountService;
import co.meshtrade.api.wallet.account.v1.Service.OpenAccountRequest;
import co.meshtrade.api.wallet.account.v1.Service.OpenAccountResponse;

import java.util.Optional;

public class OpenAccountExample {
    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()) {
            // Open a previously created account on the blockchain
            OpenAccountRequest request = OpenAccountRequest.newBuilder()
                .setName("accounts/01HQ3K5M8XYZ2NFVJT9BKR7P4C")  // Account to open
                .build();

            // Call the OpenAccount method
            OpenAccountResponse response = service.openAccount(request, Optional.empty());

            // Account is now open on the blockchain
            System.out.println("Account opened successfully on blockchain:");
            System.out.println("  Account Name: " + response.getAccount().getName());
            System.out.println("  Account Number: " + response.getAccount().getNumber());
            System.out.println("  Ledger ID: " + response.getAccount().getLedgerId());
            System.out.println("  State: " + response.getAccount().getState());
            System.out.println("  Transaction: " + response.getLedgerTransaction());
            System.out.println("\nUse the transaction reference to monitor the blockchain operation.");
        } catch (Exception e) {
            System.err.println("OpenAccount 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