Samsung Developer

Develop

Mobile/Wearable

Visual Display

Digital Appliance

Family Hub

Platform

More Mobile Docs

Design

Distribute

Learn

Connect

api implementation samsung blockchain keystore api level get instance get seedhash check for mandatory app update is root seed backed up get supported coins get hd path get a list of addresses get a list of extended public keys sign a transaction is reboot authentication required go to samsung blockchain keystore settings handle error codes deeplinks samsung blockchain keystore api level samsung blockchain keystore api level plays a key role to ensure that the required api level of samsung blockchain keystore on a user’s device is properly installed to support the api that your android app tries to call for example, if your android app is trying to implement a new samsung blockchain keystore api that requires “api level 2”, your android app will need to check whether samsung blockchain keystore app installed on user’s device also supports api level 2 if a user’s app supports api level 1, then your app will need to guide users to update samsung blockchain keystore app to the latest version users can be directed to the update page in galaxy store otherwise, there will be a runtime exception due to api level exception when calling apis with level higher than the level supported by the user’s version the api level for each api will be mentioned in the javadoc, under “since” title, and developers can call “getkeystoreapilevel api” to check the current api level on the user’s device your android app will need to check the api level whenever needed – it may be at the beginning of running samsung blockchain keystore app or every time your app calls an api public void getkeystoreapilevel { int keystoreapilevel = scwservice getinstance getkeystoreapilevel ; boolean iskeystoreapisupported = keystoreapilevel > 0; } get instance scwservice getinstance will need to be used to call any of the apis provided by samsung blockchain keystore if samsung blockchain keystore is supported on the device, an instance will be returned if it is not available on the device, then null will be returned if null is returned, it means samsung blockchain keystore is not supported on the user’s device a different keystore or a wallet needs to be used scwservice scwserviceinstance = scwservice getinstance ; get seed hash getseedhash api aims to help developers distinguish two things 1 check whether user has set up samsung blockchain keystore 2 check whether root seed recovery phrase has been changed or not every time a new root seed or a wallet is created or restored, the seed hash in a string value will be changed actually, this is not the preimage of the real seed, but a pseudo hash value so, it is not possible to calculate the real seed with the pseudo one it is strongly recommended for the application to cache the returned hash value to reduce the number of times to check the derived address’s validity if the returned value is same as cached, the derived addresses are still valid, so the application keeps using these addresses otherwise, the application should refresh the addresses from new seed with getaddresslist or getextendedpublickeylist api whenever the application starts, it needs to call getseedhash in case that the returned value is a zero-length string, it means that there is no wallet in the samsung blockchain keystore so, the application ui needs to guide users to jump to samsung blockchain keystore to create a wallet with scwdeeplink main deeplink public void getseedhash { string seedhash = scwservice getinstance getseedhash ; boolean initialized = seedhash != null && seedhash length > 0 ; } check mandatory app update checkformandatoryappupdate api is to help developers check if a user must update samsung blockchain keystore because samsung blockchain keystore handles only one task at a time, make sure to not call the checkformandatoryappupdate api in the background as it may cause other api calls or requests to be cancelled if a mandatory app update is needed, users can be directed to the galaxy store using a deeplink, scwdeeplink galaxy_store otherwise, users will see the mandatory app update popups during an operation process, such as signing a transaction, and will need to update samsung blockchain keystore before proceeding note scwservice scwcheckformandatoryappupdatecallback will need to be implemented correspondingly scwservice scwcheckformandatoryappupdatecallback callback = new scwservice scwcheckformandatoryappupdatecallback { @override public void onmandatoryappupdateneeded boolean needed { if needed { startdeeplink scwdeeplink galaxy_store ; } } }; scwservice getinstance checkformandatoryappupdate callback ; how to handle the returned value a boolean needed value of whether a mandatory update is needed or not will be returned if needed, developers will need to guide users to go to samsung blockchain keystore app page in galaxy store to update is root seed backed up isrootseedbackedup api helps developers check if there is a backup of root seed since a user can create a wallet without a backup of root seed, developers can advise the user to make root seed backup if a backup of root seed is needed, the users will be directed to the page which backs up the mnemonic phrases in the samsung blockchain keystore using a deep link, scwdeeplink backup_wallet boolean isbackedup = scwservice getinstance isrootseedbackedup ; if !isbackedup { startdeeplink scwdeeplink backup_wallet ; } how to handle the returned value the result of root seed backup will be returned in a boolean type get supported coins getsupportedcoins api is used to find out which type of cryptocurrencies are supported, in case there is a different logic that developers must implement for different cryptocurrencies it is returned in an int array of standard coin types according to bip standard – for example, 60 for ethereum int[] supportedcoins = scwservice getinstance getsupportedcoins ; stringbuilder sb = new stringbuilder ; sb append "supported coins" append '\n' ; for int i = 0; i < supportedcoins length; i++ { sb append '[' append i append "] " append supportedcoins[i] append '\n' ; } string s = sb tostring ; get hd path gethdpath api helps developers derive hd path for a specified coin type this api can be used as a parameter when deriving an address and requesting to sign a transaction note that utxo-based cryptocurrency, such as bitcoin will not be supported for this api no callback will be needed for this api as hd path in string type will be returned immediately //derive hd path for the cryptocurrency that your app supports string ethereumhdpath = scwservice gethdpath scwcointype eth, 0 ; string klaytnhdpath = scwservice gethdpath scwcointype klay, 0 ; string tronhdpath = scwservice gethdpath scwcointype tron, 0 ; string stellarhdpath = scwservice gethdpath scwcointype xlm, 0 ; there are two parameters needed coin type and address index coin type use scwcointype class to specify the cryptocurrency that your app uses address index address index is like an account number it is recommended to use 0 as the default address index increasing the address index will generate a different account for example, if you need another ethereum account, then you can increase this address index to 1 if you need just one address for your service, then make sure to use the same coin type and same address index throughout your service so that user does not get confused with multiple addresses examples the returned value will be hd path in a string format this hd path will be needed for getaddresslist api and signing cryptocurrency apis scwservice gethdpath scwcointype eth, 0 will return “m/44’/60’/0’/0/0” scwservice gethdpath scwcointype eth, 1 will return “m/44’/60’/0’/0/1” scwservice gethdpath scwcointype klay, 0 will return “m/44’/8217’/0’/0/0” scwservice gethdpath scwcointype tron, 0 will return “m/44’/195’/0’/0/0” scwservice gethdpath scwcointype xlm, 0 will return “m/44’/148’/0’” for more details on hd path refer to key management section in understanding keystore you can find how hd path is used in samsung blockchain keystore get a list of addresses getaddresslist api allows developers to request to get a list of addresses that correspond to a list of hd paths a list of the hd path, compatible with bip-44 needs to be passed on to bring the addresses the depth of hd path should be between 3 and 6 also, scwservice scwgetaddresslistcallback will need to be implemented correspondingly scwservice scwgetaddresslistcallback callback = new scwservice scwgetaddresslistcallback { @override public void onsuccess list<string> addresslist { } @override public void onfailure int errorcode, string errormessage { //handle errors } }; string hdpath = scwservice gethdpath scwcointype eth, 0 ; arraylist<string> hdpathlist = new arraylist<> ; hdpathlist add hdpath ; scwservice getinstance getaddresslist callback, hdpathlist ; hierarchical deterministic path hd path examples hdpath for ethereum m/44'/60'/0'/0/0 hdpath for bitcoin m/44'/0'/0'/0/0 if you are unsure about what hd path is, then you can generate hd path with gethdpath api except for bitcoin how to handle the returned value the returned value will be a list of addresses in a list** format each address will correspond to the hd path in the arraylist minimize calling getaddresslist api by checking seed hash value to avoid calling getaddresslist api as much as possible, please utilize getseedhash api to check whether the root seed has been changed or not, since different seed hash value implies that the corresponding address has also been updated get a list of extended public keys getextendedpublickeylist api allows developers to request to get a list of extended public keys that correspond to a list of hd paths a list of the hd path, compatible with bip-44 needs to be passed on to bring the public key the depth of path should be between 3 and 6 take note that the scwservice scwgetextendedpublickeylistcallback will need to be implemented correspondingly scwservice scwgetextendedpublickeylistcallback callback = new scwservice scwgetextendedpublickeylistcallback { @override public void onsuccess list<byte[]> extendedpublickeylist { } @override public void onfailure int errorcode, string errormessage { //handle errors } }; string hdpath = scwservice gethdpath scwcointype eth, 0 ; arraylist<string> hdpathlist = new arraylist<> ; hdpathlist add hdpath ; scwservice getinstance getextendedpublickeylist callback, hdpathlist ; hierarchical deterministic path hd path examples hdpath for ethereum m/44'/60'/0'/0/0 hdpath for bitcoin m/44'/0'/0'/0/0 how to handle the returned value the returned value will be list <byte[]> that corresponds to each hd path requested in the arraylist each byte array is composed of 33 bytes of compressed public key and 32 bytes of chain code you can derive the child public key based on this data note that you need to derive the address of the compressed public key or call getaddresslist api to get the address minimize calling getextendedpublickeylist api by checking seed hash value use getseedhash api to check whether the root seed has been changed or not, since different seed hash value implies that corresponding public keys have also been updated sign a transaction there are seven apis that support signing cryptocurrency transactions ethereum, personal sign message in ethereum, bitcoin, klaytn, tron, personal sign message in tron, and stellar note only signing a transaction is included in the samsung blockchain keystore scope 1 signethtransaction api signethtransaction api as the name implies, sends a request to samsung blockchain keystore to sign an ethereum transaction likewise, scwservice scwsignethtransactioncallback will need to be implemented scwservice scwsignethtransactioncallback callback = new scwservice scwsignethtransactioncallback { @override public void onsuccess byte[] signedethtransaction { } @override public void onfailure int errorcode, string errormessage { //handle error } }; string toaddress = "0xe7425ee1bc64ab7c51ce3617cb83e76fd545f1a9"; string ethamount = "123 456789"; string ethgasprice = "12000000000"; string ethgaslimit = "21000"; string data = ""; long chainid = 1; string hdpath = scwservice gethdpath scwcointype eth, 0 ; byte[] encodedunsignedethtx = createrawtransaction toaddress, ethamount, ethgasprice, ethgaslimit, data ; private byte[] createrawtransaction param1, param2, … { //implement your code here } scwservice getinstance signethtransaction callback, encodedunsignedethtx, hdpath, chainid ; the parameters to take note are as follows encodedunsignedethtx a byte array of an rlp-encoded unsigned ethereum raw transaction hdpath hd path that corresponds to the address linked to your android app that also corresponds to the private key which is used for signing chainid chain id to prevent replay attacks between different chain for eip1559 transaction, chainid should be null how to handle the returned value the signed transaction will be returned in a byte array type in a rlp-encoded format 2 signethpersonalmessage api signethpersonalmessage api can be used to request to samsung blockchain keystore to sign a message in ethereum scwservice scwsignethpersonalmessagecallback will need to be implemented scwservice scwsignethpersonalmessagecallback callback = new scwservice scwsignethpersonalmessagecallback { @override public void onsuccess byte[] signedpersonalmessage { } @override public void onfailure int errorcode, string errormessage { //handle error } }; string hdpath = scwservice gethdpath scwcointype eth, 0 ; byte[] unsignedmsg = "to sign up, please sign this message " getbytes ; scwservice getinstance signethpersonalmessage callback, unsignedmsg, hdpath ; the parameters to take note are as follows unsignedmsg – a byte array of raw message to be signed by samsung blockchain keystore the "\u0019ethereum signed message \n" prefix will be added by samsung blockchain keystore, so your android app should not include the prefix in the message hdpath hd path that corresponds to the address linked to your android app that also corresponds to the private key which is used for signing how to handle the returned value the type of return is a byte array of signed message based on r, s, v values for a transaction’s signature respectively 3 signbtctransaction api signbtctransaction api can be used to create a request to samsung blockchain keystore to sign a bitcoin transaction the scwservice scwsignbtctransactioncallback will need to be implemented scwservice scwsignbtctransactioncallback callback = new scwservice scwsignbtctransactioncallback { @override public void onsuccess byte[] signedbtctransaction { } @override public void onfailure int errorcode, string errormessage { //handle error } }; list<utxo> utxos = new arraylist<> ; arraylist<string> inputhdpathlist = new arraylist<> ; string changehdpath = "m/44'/0'/0'/0/0"; string inputhdpath1 = "m/44'/0'/0'/0/0"; string inputhdpath2 = "m/44'/0'/0'/0/1"; utxos add getunspentoutputs inputhdpath1 ; utxos add getunspentoutputs inputhdpath2 ; transactionextended unsignedtx = makeunsignedtransaction networkparams, utxos, to, value, fee ; for int i = 0; i < unsignedtx getinputs size ; i++ { string inputhdpath = unsignedtx getinputs gethdpath i ; inputhdpathlist add inputhdpath ; } private transaction makeunsignedtransaction networkparameters networkparams, list<utxo> utxos, string to, long value, long fee { //make unsigned transaction among unspent outputs to spend value with fee //implement your code here } scwservice getinstance signbtctransaction callback, transaction, inputhdpathlist, changehdpath ; the parameters to take note are as follows transaction a byte array of a serialized unsigned bitcoin transaction to be signed by samsung blockchain keystore inputhdpathlist a list of hd path that corresponds to the addresses linked to the transaction inputs in transaction this list also corresponds to the private key which is used for signing bip-44, 49, 84 are supported and coin type “1” in hd path can be used for bitcoin test network parameter check samsung blockchain keystore will verify the requested transaction using transactioninput in transaction and inputhdpathlist each transactioninput should correspond to an hd path in inputhdpathlist if there are multiple transactioninput, then corresponding inputhdpathlist and transactioninputs should be listed in the same order changehdpath if there is a return change, then include the hd path that corresponds to the change address if the change address is not needed, then this value should be null how to handle the returned value the signed transaction will be returned in a byte array type 4 signklaytransaction api signklaytransaction api can be used to request to samsung blockchain keystore to sign a klaytn transaction scwservice scwsignklaytransactioncallback will need to be implemented scwservice scwsignklaytransactioncallback callback = new scwservice scwsignklaytransactioncallback { @override public void onsuccess byte[] signedklaytransaction { } @override public void onfailure int errorcode, string errormessage { //handle error } }; string hdpath = scwservice gethdpath scwcointype klay, 0 ; byte[] unsignedtransaction = getunsignedtx ; int klaytnchainid = 1001; scwservice getinstance signklaytransaction callback, unsignedtransaction, hdpath, klaytnchainid ; the parameters to take note are as follows unsignedtransaction a byte array of raw transaction to be signed by samsung blockchain keystore it is same as the sigrlp value mentioned in klaytn official document hdpath - hd path that corresponds to the public key linked to your android app that also corresponds to the private key which is used for signing klaytnchainid – the klaytn network id or the integer to identify the network "8217" is klaytn cypress mainnet and "1001" is klaytn baobab testnet how to handle the returned value the signed transaction will be returned in a byte array type in a rlp-encoded format 5 signtrxtransaction api signtrxtransaction api can be used to request to samsung blockchain keystore to sign a tron transaction scwservice scwsigntrxtransactioncallback will need to be implemented scwservice scwsigntrxtransactioncallback callback = new scwservice scwsigntrxtransactioncallback { @override public void onsuccess byte[] signedtrxtransaction { //handle signed tron transaction } @override public void onfailure int errorcode, string errormessage { //handle error } }; string hdpath = scwservice gethdpath scwcointype tron, 0 ; string from = “tdcmwosbafcegqqnuarnjghy4tabdcmdwi” string to = “tq6pm81jdc2ghruonytzgvpc7svyqcemeu”; int amount = 2; byte[] unsignedtransaction = createunsignedtransaction hdpath from, to, amount ; private byte[] createunsignedtransaction param1, param2, … { //implement your code here } scwservice getinstance signtrxtransaction callback, unsignedtransaction, hdpath ; the parameters to take note are as follows unsignedtransaction a byte array of raw tron transaction to be signed by samsung blockchain keystore hdpath - hd path that corresponds to the public key linked to your android app that also corresponds to the private key which is used for signing how to handle the returned value signed transaction will be returned in a byte array 6 signtrxpersonalmessage api signtrxpersonalmessage api can be used to request to the samsung blockchain keystore to sign a message in tron the scwservice scwsigntrxpersonalmessagecallback will need to be implemented scwservice scwsigntrxpersonalmessagecallback callback = new scwservice scwsigntrxpersonalmessagecallback { @override public void onsuccess byte[] signedpersonalmessage { } @override public void onfailure int errorcode, string errormessage { //handle error } }; string hdpath = scwservice gethdpath scwcointype tron, 0 ; byte[] unsignedmsg = "to sign up, please sign this message " getbytes ; scwservice getinstance signtrxpersonalmessage callback, unsignedmsg, hdpath ; the parameters to take note are as follows unsignedmsg a byte array of raw message to be signed by samsung blockchain keystore a "\u0019tron signed message \n32" prefix will be added by samsung blockchain keystore, so your android app should not include the prefix in the message hdpath hd path that corresponds to the address linked to your android app that also corresponds to the private key which is used for signing how to handle the returned value the type of return is a byte array of signed message based on values for a transaction’s signature - r, s, v respectively 7 signxlmtransaction api signxlmtransaction api can be used to request to the samsung blockchain keystore to sign a stellar transaction the scwservice scwsignxlmtransactioncallback will be needed to be implemented scwservice scwsignxlmtransactioncallback callback = new scwservice scwsignxlmtransactioncallback { @override public void onsuccess byte[] signedxlmtransaction { //handle signed stellar transaction } @override public void onfailure int errorcode, string errormessage { //handle error } }; string recipientaccount = “gay5dorarbd5l3fbbwuhxkciv7vcmqicsllj7gyr4664av4mxtx2fh4o”; string amount = “100”; paymentoperation operation = new paymentoperation builder recipientaccount, asset, amount build ; string hdpath = scwservice gethdpath scwcointype xlm, 0 ; arraylist<string> hdpathlist = new arraylist<> ; hdpathlist add hdpath ; string sourceaccount = “gb7zviydvsww3ctfj2v3oproahgbuomebwib55xieii3aq6523pg4lm5”; string memo = "hello12347"; byte[] unsignedtransaction = createunsignedtransaction sourceaccount, operation, memo, networkid ; private byte[] createunsignedtransaction param1, param2, … { //implement your code here // include networkid, envelopetype envelopte_type_tx , and xdr-encoded transaction } scwservice getinstance signxlmtransaction callback, unsignedtransaction, hdpathlist ; the parameters to take note are as follows unsignedtransaction – a byte array of raw transaction to be signed by samsung blockchain keystore it is the same as the signature base, which includes networkid, envelopetype, and xdr-encoded transaction hdpathlist a list of hd path that corresponds to the addresses linked to your android app that also corresponds to the private key which is used for signing how to handle the returned value the signed transaction will be returned in a byte array developers can use base64 encoding to implement this result into envelopexdr, which can derive the transaction that can be submitted to the network is reboot authentication required the isrebootauthenticationrequired api allows you to check whether pin authentication is required after reboot some keystore api calls can require pin authentication after device reboot these calls are successful only after the user enters their blockchain keystore pin at the prompt the isrebootauthenticationrequired method allows you to determine whether accessing the keystore api requires pin authentication boolean isrebootauthenticationrequired = scwservice getinstance isrebootauthenticationrequired ; if isrebootauthenticationrequired { // user prompted for pin authentication } else { // user not prompted for pin authentication } • handling the returned value the isrebootauthenticationrequired method returns a boolean value go to samsung blockchain keystore settings samsung blockchain keystore provides a user-friendly setup page for the first time users and a settings page for existing users developers can easily jump to samsung blockchain keystore settings by using a deeplink, scwdeeplink main there are two purposes of calling the samsung blockchain keystore main activity setup samsung blockchain keystore for first time users after calling getseedhash api, if the wallet is not created, a zero length value will be returned this is when your android app should call samsung blockchain keystore settings via a deep link as shown below samsung blockchain keystore will check if a user needs to set up a new wallet and if needed, will lead to a setup page after the activity is finished, your android app should call the getseedhash api, once more, to make sure that the wallet has been created and the corresponding seed hash value is returned samsung blockchain keystore settings for existing users for existing users, when samsung blockchain keystore settings is called, a user will see a list of menu related to samsung blockchain keystore management features include changing the pin, removing the wallet, checking a recovery phrase to back up the wallet, enabling/disabling fingerprint as an authentication method, or managing notification preferences more information about the samsung blockchain keystore, such as notices, terms and conditions, and app information can be also found here a sample code for calling samsung blockchain keystore via a deeplink is as follows uri uri = uri parse scwdeeplink main ; intent intent = new intent intent action_view ; intent setdata uri ; intent setflags intent flag_activity_new_task ; mcontext startactivity intent ; *do not call startactivityforresult intent as no results will be returned make sure to use startactivity intent instead handling error codes in addition to general error codes, the following are some special cases that developers may want to look out for mandatory update is needed samsung blockchain keystore was removed due to user entering wrong pin more than n times api key is invalid the popups above will be shown from samsung blockchain keystore app, though the samsung blockchain keystore will still return corresponding error codes in the mandatory update error case, the user will see a popup with a link to galaxy apps store page to update samsung blockchain keystore if it was reset, due to entering a wrong pin more than n times, then the user will need to create or import the wallet via samsung blockchain keystore service again it is recommended that developers call checkformandatoryappupdate api before calling other apis, to check whether a mandatory app update is needed for this api, no ui or popup will be shown from samsung blockchain keystore upon integration, developers may receive an “error_package_signature_verification_failed” error in this case, developers can turn on developer mode to skip the app verification stage yet, developers will need to implement proper app id, officially issued by the samsung blockchain keystore team before launching your android app in the market public interface scwerrorcode { int error_mandatory_app_update_needed = -8; int error_package_signature_verification_failed = -11; int error_wallet_reset = -12; int error_check_app_version_failed = -15; int error_tnc_not_agreed = -6; } please refer to the scwerrorcode class in javadoc for more details on error codes samsung blockchain keystore deeplinks deep links to samsung blockchain keystore and deep link to update samsung blockchain keystore app in galaxy store are provided developers can implement the links below to direct users to go to the main page and back up root seed page in samsung blockchain keystore settings directly deep link to galaxy store can be used when user needs to update samsung blockchain keystore app features deeplink main page scwdeeplink main galaxy apps store scwdeeplink galaxy_store backup wallet scwdeeplink backup_wallet

https://developer.samsung.com/blockchain/keystore/programing-guide/api-implementation.html

Didn’t find what you were looking for?

FAQ

Search frequently asked
questions
by keywords.

Join the Forum

Visit the Forum to ask
questions and exchange
ideas with other developers.

Get Support

Submit a 1:1 Support request
and receive a response
within 2 business days.

Manage Your Cookies

We use cookies to improve your experience on our website and to show you relevant advertising. Manage you settings for our cookies below.

Essential Cookies

These cookies are essential as they enable you to move around the website. This category cannot be disabled.

Analytical/Performance Cookies

These cookies collect information about how you use our website. for example which pages you visit most often. All information these cookies collect is used to improve how the website works.

Functionality Cookies

These cookies allow our website to remember choices you make (such as your user name, language or the region your are in) and tailor the website to provide enhanced features and content for you.

Advertising Cookies

These cookies gather information about your browser habits. They remember that you've visited our website and share this information with other organizations such as advertisers.

Integrate Samsung Pay Web Checkout with merchant sites

Key Management

ScwService

Getting Started

SamsungPay

API Guidelines

Web Checkout SDK

WatchManager

Save To Pay

API Implementation