Skip to main content
Last updated

Kadena SpireKey technical specifications

To enable an application to use Kadena SpireKey, the application must be able to do the following:

  • Connect to the SpireKey URL to register a new account or access an existing account.
  • Request a signature from a SpireKey account and handle the value returned from the SpireKey URL.

Connect to Kadena SpireKey

From your application, initiate a GET request to the Kadena SpireKey /connect endpoint:

The GET request expects you to provide the following search parameters:

returnUrlstringSpecifies the application URL that SpireKey should return users to after connecting to register or access a SpireKey account.
networkIdstringSpecifies the network identifier for the transaction to be submitted on. For example, use the network identifier testnet04 for transactions to be submitted on the Kadena test network.
chainIdstringSpecifies the chain identifier for the transaction to be submitted on.
reasonstring?Specifies the reason you want application users to connect to a SpireKey account.
optimisticboolean?Determines whether SpireKey returns optimistically to your application before an account is confirmed on the blockchain. You can set this parameter to false to disable optimistic mode.

Registration and onboarding

After your application redirects users to, they are prompted to create a passkey if they don't already have a SpireKey account. In most cases, applications don't need to wait for the account to be created before preparing transactions. Therefore, by default, SpireKey uses optimistic mode to redirect users back to the application as soon as the transaction to create an account has been submitted.

If you want to require an account to be created before users can interact with your application, you can either make use of the pendingTxIds parameter returned in the user object or set the optimistic parameter to false.

Return value

After connecting to an account in SpireKey, users are redirected to the returnUrl you specify for your application. As part of the redirection, SpireKey appends a user object in the searchParameters. This object contains information you can use to address the user or to prepare a transaction.


aliasstringSpecifies an alias to use for the account as a display name.
accountNamestringSpecifies the c:account a user has connected to the application.
pendingTxIdsstring[]Specifies an array of pending transactions related to account creation or maintenance.
credentialsCredential[]Specifies the credential for the account. See Credential.


Every SpireKey account can return one or more credentials when connected. The number of credentials does not have to match the number of credentials available on the blockchain. The credentials returned are the credentials the user wants to use to submit transactions in your application. When multiple credentials are returned, you should prepare the transaction with all credentials signing for the same relevant capabilities.

typestringSpecifies the credential type. This parameter can specify WebAuthn or ED25519 as the signature scheme.
publicKeystringSpecifies the public key for the account returned.
idstringSpecifies the credential identifier for the account returned.

Request a signature

When you prepare a transaction for the user to sign, you use the public keys from the credentials included in the response from the Kadena SpireKey /connect endpoint to construct the transaction. When your transaction is ready to be signed, you need to base64 encode the stringified JSON of the transaction.

Transactions can grow in size well beyond what is accepted in searchParameters. To enable users to sign these transactions, you should send the transaction parameters to the SpireKey /sign endpoint using the anchor hashtag (#) instead of the searchParameter question mark (?). For example, a signature request might look like this:

transactionstringSpecifies the base64 encoded JSON stringified transaction object.
returnUrlstringSpecifies the URL the user needs to be redirected to after signing.

Signature requests can include an explanation of what the user is signing for. If the explanation is accepted and the user consents by signing the transaction, the signed transaction is returned to the application as a parameter in the return URL following an anchor hashtag (#).

You can then collect or combine additional signatures, as required, to finalize the transaction for execution.

transactionstringSpecifies the base64 encoded JSON stringified transaction object.