This page introduces how to create and manage a Klaytn account with KAS Wallet API.
Before Getting Started
The x-chain-id value for calling the API is 8217 (Cypress) or 1001 (Baobab).
Essential parameters for calling APIs are described in individual examples.
Values that a user needs to enter for calling APIs will be represented with one pair of braces ({}). A user must enter the following values.
Item
Description
Note
chain-id
8217 or 1001
Cypress(Klaytn mainnet) or Baobab(Klaytn testnet
access-key-id
Auth ID
accessKeyId obtained from KAS Console - Security - Credential
secret-access-key
Auth Password
secretAccessKey obtained from KAS Console - Security - Credential
krn
(optional) ID of Account Pool
Unnecessary when using Default Account Pool
A KAS API Authentication Key (API Auth Key) provides access to all KAS services and all the rights to a Klaytn account which was created by calling Wallet API via this API Auth Key. The rights here include accessing and transferring all the assets (KLAY, etc.) of or sending a transaction from a Klaytn account. If you shared your API Auth Key with any unauthorized personnel, your Klaytn account could be compromised and might cause unwanted transaction execution.
DO NOT share your API Auth Key (Secret AccessKey or Authorization) with any unauthorized personnel.
DO PUT efforts necessary to keep your API Auth Key safe for the security of your KAS/Klaytn account.
For details about KAS SDK (caver-js/caver-java extensions) installation and execution, please visit KAS SDK.
For more details on creating an Account Pool, account, and selecting an account, refer to Getting Started.
Klaytn account
A Klaytn account is a host that owns and trades virtual assets, such as KLAY, token (FT, and NFT), and deploys and executes smart contracts on Klaytn blockchain platform. For details about Klaytn account, please visit here.
Create a Klaytn account
Create Account Pool
KAS provides Account Pool for managing several Klaytn accounts. To use this, a user must first create Account Pool on the KAS Console and then create a new KAS Console account in the Account Pool created using the account creation API. Account Pool must be created first to use and manage the personal Account Pool instead of resorting to the default Account Pool. You can create multiple Account Pools in KAS Console, and if you provided the KRN of each Account Pool as the x-krn in the API Request header that creates a Klaytn account, you can create a Klaytn account inside that specific Account Pool.
Default Account Pool
The default Account Pool is the Account Pool provided to you when you do not choose your own Account Pool in calling KAS API. If you didn't feed the KRN of your own Account Pool into x-krn in API Request header, then the Klaytn account in the default Account Pool is used for calling this API. All the default Account Pools are tagged with DEFAULT as you look at these on KAS Console - Service - Wallet - Accounts menu.
The first Account Pool you create is automatically designated as the default Account Pool. For example, if you have created an Account Pool named "A" in KAS Console and you didn't specify any Account Pool in calling API, the Klaytn account stored in this "A" Account Pool is automatically used in calling API afterwards. When you haven't created any Account Pool and you try to call API that creates a Klaytn account, KAS automatically create the default Account Pool and push this newly created Klaytn account into this default Account Pool for you.
KAS Console - Service - Wallet - Accounts
Click the “Create” button under the KAS Console - Service - Wallet - Accounts menu. Then, click the button to display the screen for creating Klaytn account Pools.
Create Account Pool
Create Klaytn account Pool, and it must have a different name from other Account Pools on the current KAS account.
Check Account Pool
Once the Account Pool is created, check the Account Pool in the Account Pool list.
If you put KRN which is obtained from Account Pool into x-krn in API Request header, you would call this API with the Klaytn account stored in this Account Pool
Call the Klaytn account creation API as follows. You may use the REST API or KAS SDKs (caver-js, caver-java extensions) for this.
//An example of using the default Account Pool of KAS with the x-krn header parameter is omitted. curl --location --request POST"https://wallet-api.klaytnapi.com/v2/account" \-u {access-key-id}:{secret-access-key} \--header "x-chain-id: {chain-id}"//An example of using the Account Pool created above with the x-krn header parameter is included. curl --location --request POST"https://wallet-api.klaytnapi.com/v2/account" \-u {access-key-id}:{secret-access-key} \--header "x-chain-id: {chain-id}"--header "x-krn: krn:8217:wallet:6698d79e-78ee-439a-815d-f293ec6ae736:account-pool:ap1"
Here is the response of the Klaytn account creation API.
//Example of a response when creating an account in the KAS default Account Pool{"address": "0xa809284C83b901eD106Aba4Ccda14628Af128e14","chainId": 1001,"createdAt": 1599187293, "keyId": "krn:1001:wallet:68ec0e4b-0f61-4e6f-ae35-be865ab23187:account-pool:default:0x4cbbcb974e32a7960e1b356edf60087613101919ed83199f12e872cba068a50f",
"krn": "krn:1001:wallet:68ec0e4b-0f61-4e6f-ae35-be865ab23187:account-pool:default", "publicKey": "0x04cdccfb99b2905561e3dd886687b429a004718f11b04914f17ce68fd3a0db46c598a45da85caa61fe84cb78a0f2eaa9983ec7b8805a93ef9428eb1350a8558237",
"updatedAt": 1599187293}//Example of a response when creating an account in the Account Pool that you created. {"address": "0xa809284C83b901eD106Aba4Ccda14628Af128e14","chainId": 1001,"createdAt": 1599187293, "keyId": "krn:8217:wallet:6698d79e-78ee-439a-815d-f293ec6ae736:account-pool:ap1:0x4cbbcb974e32a7960e1b356edf60087613101919ed83199f12e872cba068a50f",
"krn": "krn:8217:wallet:6698d79e-78ee-439a-815d-f293ec6ae736:account-pool:ap1", "publicKey": "0x04cdccfb99b2905561e3dd886687b429a004718f11b04914f17ce68fd3a0db46c598a45da85caa61fe84cb78a0f2eaa9983ec7b8805a93ef9428eb1350a8558237",
"updatedAt": 1599187293}
Here is a response of the Klaytn account deletion API.
{"status": "deleted"}
AccountStatus { status:'deleted' }
classAccountStatus { status: deleted}
For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developer forum.
Deactivate Klaytn account
Klaytn account deactivation API is used for deactivating created Klaytn accounts.
API Request
Enter the EOA to deactivate and call the Klaytn account deactivation API. You may use the REST API or KAS SDKs (caver-js, caver-java extensions) for this.
String address ="0x10Fb446303d019E89c2033C833ceC2e5ae875b5F";AccountSummary status =caver.kas.wallet.disableAccount(address);System.out.println(status);
API Response
Here is a response of the Klaytn account deactivation API.
For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developer forum.
Sign A Transaction with Klaytn account
Sign a transaction with a specific transaction ID using the Klaytn account. This API is used only when a transaction need to be signed with multiple signatures. If this is not the case of multiple signing, normally Wallet API automatically signs a transaction instead of you when you are sending a transaction through Wallet API.
Multiple signing is the case that a Klaytn account who sends a transaction has AccountKeyWeightedMultiSig. For details about multiple signing, please visit here.
For details about the types of AccountKey of a Klaytn account, please visit here.
API Request
Enter the Klaytn EOA and the transaction ID value to sign and receive the signature, respectively. Then, call this API. You may use the REST API or KAS SDKs (caver-js, caver-java extensions) for this.
Here is a response of the transaction signature API. The ECDSA signature information (R, S) and public key restoration information (V) are then returned.
For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developer forum.
Get Klaytn account Information by Public Key
This API searches for the details of a Klaytn account using a specific public key.
API Request
Enter the public key, and call the API to search for information regarding a Klaytn account. You may use the REST API or KAS SDKs (caver-js, caver-java extensions) for this.
For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developer forum.
Update AccountKey: To AccountKeyWeightedMultiSig
A Klaytn account which is able to sign with multiple signatures is an account that has AccountKeyWeightedMultiSig, a type of AccountKey. This type of Klaytn account must be used when sending a transaction that multiple Klaytn accounts need to sign with each one's AccountKey. We can call this special kind of transaction as multisig transactions.
Similar to Klaytn, KAS also supports multisig transactions. For sending multisig transactions using KAS, AccountKey must be the multisig key (AccountKeyWeightedMultiSig).
A Klaytn account that owns AccountKeyWeightedMultiSig has several keys (private-public key pairs) for multisig transactions, and different Klaytn accounts owns these keys, each. And, the weight can be set for individual keys.
For example, if Klaytn account A has a AccountKeyWeightedMultiSig consisting of 2 AccountKeys (AccountKey of accounts B and C each), and the weights of these keys can be weight1 and weight2, respectively. When the account B signs this transaction, the sum of signed weight is weight1, and if account C also signs it, the sum will be weight1 + weight2. A transaction can be sent only if the sum of signed weights is the same with or higher than the threshold. The threshold value is given as a input parameter when you create AccountKeyWeightedMultiSig for your Klaytn account.
For details about AccountKeyWeightedMultiSig, please visit here.
Creating Klaytn account must be completed before updating your AccountKey to AccountKeyWeightedMultiSig. All Klaytn accounts whose key contributes to form a AccountKeyWeightedMultiSig must be located in the same Account Pool in KAS. Here is an example of updating a Klaytn account with the EOA “0x07DAe1aAb1e1b42A7184E12Ad50CEAc07A890640” to a multisig account (=an account whose AccountKey is AccountKeyWeightedMultiSig) consisting of 2 AccountKeys.
Create Klaytn account
If Klaytn account A is a multisig account with two keys (AccountKeys), then account A can have two keys (keys of account B and C). For account A to have AccountKeyWeightedMultiSig with the keys Account B and C, the Klaytn accounts B and C must have been created in KAS. For more details on creating a Klaytn account in KAS, refer to Create Klaytn account.
The below is the example of created Klaytn accounts.
This API updates your account ("A" in this example) to a multisig account that can send transactions with signatures of other Klaytn accounts ("B", "C" in this example). Here is an example of updating a Klaytn account ("A") with the EOA “0xa809284C83b901eD106Aba4Ccda14628Af128e14” to a multisig account with two keys (of account B and C), key weights (3 and 1, respectively), and a threshold of 4.
To update your Klaytn account, call this API and send account update transaction to Klaytn. The Klaytn account who sends this transaction must have sufficient balance to pay for the transaction fee.
API Request
Call the multisig account update API. You may use the REST API or KAS SDKs (caver-js, caver-java extensions) for this.
For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developer forum.
Migrating Klaytn Accounts into KAS Wallet API
You can safely migrate your Klaytn accounts to KAS Wallet API and safely manage them there.
Migrating with KAS SDK
To migrate your Klaytn accounts to KAS, you can either use KAS SDK or write your own migration code.
The below example demonstrates how you can use KAS SDK.
const keyring = caver.keyringContainer.keyring.generate()
const address = keyring.address
const key = keyring.key.privateKey
// If you do not manually enter the nonce value, it is automatically filled during the migration process.
const ret = await caver.kas.wallet.migrateAccounts([{ address, key, nonce: 0 }])
ArrayList<MigrationAccount> accountsToBeMigrated = new ArrayList<>();
SingleKeyring singleKeyring = KeyringFactory.generate();
String address = singleKeyring.getAddress();
String key = singleKeyring.getKey().getPrivateKey();
String nonce = "0x0";
// If you do not manually enter the nonce value, it is automatically filled during the migration process.
MigrationAccount migrationAccount = new MigrationAccount(address, key, nonce);
accountsToBeMigrated.add(migrationAccount);
RegistrationStatusResponse response = await caver.kas.wallet.migrateAccounts(accountsToBeMigrated)
Migrating with REST API
Creating a Public Key
Calling the API
In order to migrate your Klaytn accounts to KAS, you need to update the accounts using the public key managed by KAS. To generate a public key to be managed by KAS, use Create Key API. You can create up to 100 public keys at a time. Pass the desired number of keys as size parameter.
// Example response for a generated key
{
"items": [
{
"blob": "0x43bfd97caaeacc818cd6b62abccf21de569649f31f644142eb1fcfd5beb69e61",
"keyId": "krn:1001:wallet:test:account-pool:default:0xd80ff4019cfd96f0812adece82dd956c5e781b79ca707cb5e957c97f27593221",
"krn": "krn:1001:wallet:test:account-pool:default",
"publicKey": "0x04a081eaf8603b9be528b86da338ba8051bfc073876dbdf00f5161b393b5735f85a76634ea38c43fbbc5d7a630b76ca2a1d81d446debc937b24a77eb3b352a1b6d"
}
]
}
For more details on this API, please refer to Key Creation. For inquiries regarding this document or KAS in general, please visit Developer Forum.
Creating Account Update Transaction
You have to create an account update transaction with the key from your old account. Make sure to use Fee Delegation Account Update Transaction from Public Key Type. Creating account update transations with key types other than the public key type may prevent you from using your account.
If you wish to use multisig account, first complete the procedures for migration and then make the changes using Wallet API's Multisig Account Update API.
API
// In order to migrate Klaytn account to KAS Wallet API, you have to create a transaction and sign it before sending it to KAS.
// In order to sign the transaction, create a Keyring instance with Klaytn account and add it to KeyringContainer.
// If Klaytn's key is either `AccountKeyWeigthedMultiSig`or `AccountKeyRoleBased`,
// pass the second parameter of `keyringContainer.keyring.create` as array or double-array.
// For more details, please refer to https://docs.klaytn.com/bapp/sdk/caver-js/api-references/caver.wallet/keyring#caver-wallet-keyring-create.
const keyringContainer = new caver.keyringContainer()
const keyring = keyringContainer.keyring.create('0xc756f6809bc34c2458fcb82fb16d5add3dbad9e3', '0x{private key}')
keyringContainer.add(keyring)
// Create key for KAS Wallet API
// `caver.kas.wallet.createKeys` returns the following values.
// {
// items: [
// { blob: '0x06000...', keyId: 'krn:1001:...', krn: 'krn:1001:...', publicKey: '0x0400e...', },
// ],
// }
const createdKeys = await caver.kas.wallet.createKeys(1)
const key = createdKeys.items[0]
// FeeDelegatedAccountUpdate Create transation.
// The value assigned to `account` field can be created using `caver.account.createWithAccountKeyPublic`.
// Address of the account to be migrated, public key (in the form of public key string) and KAS Wallet API must be passed as parameters.
const updateTx = new caver.transaction.feeDelegatedAccountUpdate({
from: keyring.address,
account: caver.account.createWithAccountKeyPublic(keyring.address, key.publicKey),
gas: 1000000,
})
// Sign transaction.
await keyringContainer.sign(keyring.address, updateTx)
const result = {
keyId: key.keyId,
address: keyring.address,
rlp: updateTx.getRLPEncoding(),
}
// In order to migrate Klaytn account to KAS Wallet API, you have to create a transaction and sign it before sending it to KAS.
// In order to sign the transaction, create a Keyring instance with Klaytn account and add it to KeyringContainer.
// If Klaytn's key is either `AccountKeyWeigthedMultiSig`or `AccountKeyRoleBased`,
// pass the second parameter of `keyringContainer.keyring.create` as array or double-array.
// For more details, please refer to https://javadoc.io/doc/com.klaytn.caver/core/latest/com/klaytn/caver/wallet/keyring/KeyringFactory.html.
AbstractKeyring keyring = KeyringFactory.create("0xc756f6809bc34c2458fcb82fb16d5add3dbad9e3", "0x{private key}")
// Create key for KAS Wallet API
// `caver.kas.wallet.createKeys` returns the following values.
// {
// items: [
// { blob: '0x06000...', keyId: 'krn:1001:...', krn: 'krn:1001:...', publicKey: '0x0400e...', },
// ],
// }
KeyCreationResponse keyCreationResponse = caver.kas.wallet.createKeys(1);
List<Key> createdKeys = keyCreationResponse.getItems();
Key key = createdKeys.get(0);
// FeeDelegatedAccountUpdate Create transation.
// The value assigned to `account` field can be created using `caver.account.createWithAccountKeyPublic`.
// Address of the account to be migrated, public key (in the form of public key string) and KAS Wallet API must be passed as parameters.
FeeDelegatedAccountUpdate updateTx = caver.transaction.feeDelegatedAccountUpdate.create(
TxPropertyBuilder.feeDelegatedAccountUpdate()
.setFrom(keyring.getAddress())
.setAccount(
com.klaytn.caver.account.Account.createWithAccountKeyPublic(
keyring.getAddress(),
key.getPublicKey()
)
)
.setGas(BigInteger.valueOf(1000000))
);
// Sign transaction.
updateTx.sign(keyring);
System.out.println("keyId: " + key.getKeyId());
System.out.println("address: " + keyring.getAddress());
System.out.println("rlp: " + updateTx.getRLPEncoding());
Migrate account
You can run the account migration process based on the account update transaction results from the previous section. For a quick reminder before calling the API:
// Failure
{
"failures": {
"0xc756f6809bc34c2458fcb82fb16d5add3dbad9e3": "failed to send a raw transaction to klaytn node; -32000::invalid transaction v, r, s values of the sender"
},
"status": "all failed"
}
For more details regarding this API, please refer to Registration. For any inquiries regarding this document or KAS in general, please visit Developer Forum.
