Co-signing API Example

Overview

Having the ability to build and co-sign transactions is a key feature of Levain's Transactions APIs, and enables you to build a digital assets management platform to facilitate withdrawals from your operational hot wallets.

This guide walks you through the process of creating your own API co-signing service to process withdrawals securely from operational hot wallets, while integrating Levain with your crypto platform.

Prerequisites

Before you begin, you will need to:

  • Create a Levain Wallet for your withdrawal hot wallet
  • Ensure your withdrawal hot wallet has sufficient funds to process withdrawals initiated by your users

Creating an account for API co-signing

Access to Levain's GraphQL API is authenticated using a personal access token, meaning that access will be based on the permissions of the user account that is used to generate the token.

Therefore, we recommend you to create an account solely for the purpose of acting as the API co-signer. This way, you are able to track audit logs of all transactions initiated by the account.

We recommend you to create a new email address within your organization's domain for the API co-signer account.

To create an account for API co-signing, you must currently be an org-level Admin, as you will need to invite a new user to your Levain organization with User role, and grant the account access to only the withdrawal hot wallet with the Wallet Approver role.

Next, setup the service account normally by following the onboarding steps outlined in the email invitation. Once you have completed the onboarding process, you will be able to create a personal access token for the account.

How an API co-signing service works

Refer to Levain Wallet's Security Model for more information on how private keys are used in Levain Wallets.

To recap, hot wallets created via Levain's web app are self-custodial in a 2-of-3 multi-signature wallet, meaning that Levain will never have access to your users' funds since you will hold two private keys generated during the wallet creation process.

In our design, you will need to co-sign transactions using only one of your two private key to process withdrawals. Levain holds the other private key, and will co-sign the transaction with you to meet the 2-of-3 multi-signature requirement. You will not need to use the backup private key that is kept by you, unless in wallet recovery scenarios where you need to move funds out of the wallet, independently on your own.

Creating an API co-signing service

An API co-signing service generally has the following logic:

  1. Perform internal checks based on your own business requirements - e.g. user's balance, KYC status, compliance, AML checks etc. when a user's withdrawal request is received.
  2. Initiate the withdrawal request upon passing all your internal checks.
  3. Co-sign the transaction locally with one private key created during wallet creation process, to produce a partially signed transaction.
  4. Send the partially signed transaction to Levain, over the Internet, for Levain to perform co-signing to produce a fully signed transaction meeting the 2-of-3 multi-signature requirement.
  5. Broadcast the fully signed transaction to the blockchain network using Levain's node service.

Most importantly, your private key used for signing never leaves your network and is never sent to Levain. This is how we can ensure Levain acts as your co-signing party, and not a custodian of your digital assets.

Reference Implementation

Please refer the examples below of an API co-signing service written in Node.js with TypeScript and Express, to integrate with Levain: