Skip to main content

HMAC Key Sharing SDK

As part of the Exchange API Vault, we provide the HMAC Key Sharing SDK that allows you to securely import your API keys from the end-user's browser to the Vertex cluster's secure storage.

Overview​

The HMAC Key Sharing SDK is a JavaScript library that exposes a simple API for splitting an HMAC key (i.e. API Key) into three shares that may be imported by each of the three Vertex nodes set up in the cluster.
Each key share is encrypted using the public key of a specific Vertex node, ensuring that only that node can decrypt it. Once encrypted, the key shards can be passed to the Vertex cluster in whatever way is easiest for you, such as via a backend service.

Installation​

The SDK is published to the Sodot JFrog Artifactory repository.

npm registry being retired on 2026-08-01

The @sodot/* packages will be removed from the public npm registry on 2026-08-01. Use the Sodot JFrog Artifactory option below — the legacy npm option is kept for reference and will stop working on that date.

To use it in an existing project:

  1. Obtain an Artifactory access token (or, until 2026-08-01, an NPM auth token) and an API_KEY from the Sodot team.

  2. Create a .npmrc file in your project's root directory (the same directory as your package.json file), and pick one of the following options:

First, generate an Artifactory access token:

  1. Sign in to the Sodot JFrog Artifactory using the sodot-auth option.
  2. From the user menu in the top right corner, click Set Me Up → npm → select the sodot-npm repository.
  3. Click the Generate Token & Create Instructions button and copy the generated token. (The token is valid for one year — regenerate it before it expires to avoid service disruptions.)

Then paste the following into your .npmrc:

@sodot:registry=https://repo.sodot.dev/artifactory/api/npm/sodot-npm/
//repo.sodot.dev/artifactory/api/npm/sodot-npm/:_authToken=${ARTIFACTORY_TOKEN}

And export the token you generated:

export ARTIFACTORY_TOKEN="<YOUR_TOKEN>"
  1. Add it to your project:
$ npm install @sodot/sodot-hmac-key-sharing

Usage​

Importing the SDK​

import { splitHmacSha256KeyIntoEncryptedShares } from "@sodot/sodot-hmac-key-sharing";

Fetching the Vertices' Public Keys​

The key shares are encrypted using the public keys of the Vertex nodes. You can fetch these keys using the Vertex API:

const VERTEX_NODES = [
  "https://vertex1.example.com",
  "https://vertex2.example.com",
  "https://vertex3.example.com",
];

const verticesPubkeys = await Promise.all(
  VERTEX_NODES.map(async (vertex) => {
    const response = await fetch(`${vertex}/cluster/persistent-keygen-id`);
    const data = await response.json();
    return data["keygen_id"];
  })
);
Fetching the Public Keys

It's important to fetch the public keys of the Vertices from a trusted source. It may be directly from the Vertices themselves or embedded in your frontend code.

Splitting the HMAC Key​

// Assuming apiSecret is the string value shown on the UI of the CEX
const apiSecretBytes = Uint8Array.from(apiSecret, (c) => c.charCodeAt(0));
const splitSecret = await splitHmacSha256KeyIntoEncryptedShares(
  apiSecretBytes,
  verticesPubkeys[0],
  verticesPubkeys[1],
  verticesPubkeys[2]
);

/*
    splitSecret is an array of three Uint8Array objects, each containing a share of the HMAC key.
    The shares can be imported into a vertex cluster's secure storage via the backend.
*/
for (vertex of VERTEX_NODES) {
  const share = splitSecret.pop();
  // send the shareBase64 to the vertex node
  importShareToVertex(vertex, share);
}

Example Usage​

An example for using the HMAC Key Sharing SDK can be found in the demo trading platform.