Blockstream Enterprise

Install the Blockstream ECS JS SDK and set up the credentials needed to connect to a Custody Engine instance.

Requirements

Node.js 18 or later
Access to a running Blockstream Custody Engine instance
An admin user with permission to create and invite new users

Install the package

npm install @blockstream/ecs-js-sdk

Credentials you will need

The SDK constructor requires five values. Here is where each one comes from:

Value	Source
`clientRsaPrivateKeyPem`	Generated locally — never leaves your environment
`clientEcdsaPrivateKey`	Generated locally — never leaves your environment
`deviceUuid`	Returned by the server after user creation
`serverRsaPublicKeyPem`	Provided by your ECS administrator
`serverEcdsaPublicKey`	Provided by your ECS administrator or returned on registration

Generate your key pairs

Before registering with the server you must generate your ECDSA and RSA key pairs locally. The SDK ships a generateUserKeyPairs helper for this:

import { generateUserKeyPairs } from '@blockstream/ecs-js-sdk/helpers'

const keys = await generateUserKeyPairs()
// keys.ecdsa.privateKey     → Uint8Array (32 bytes)
// keys.ecdsa.publicKeyHex   → string (66 hex chars, compressed P-256)
// keys.rsa.privateKeyPem    → string (PKCS#8 PEM)
// keys.rsa.publicKeyPem     → string (SPKI PEM)

Store private keys securely. They cannot be recovered from the server. Use a secrets manager or encrypted vault in production.

Get your device UUID

The deviceUuid is issued by the server when an admin creates your user account. Follow the API User Onboarding guide to complete this step and obtain your UUID.

Initialize the SDK

Once you have all five values, create a Blockstream instance:

import { Blockstream } from '@blockstream/ecs-js-sdk'

const client = new Blockstream(
  keys.rsa.privateKeyPem, // clientRsaPrivateKeyPem
  keys.ecdsa.privateKey, // clientEcdsaPrivateKey
  deviceUuid, // from user creation response
  serverRsaPublicKeyPem, // from your ECS admin
  serverEcdsaPublicKey, // from your ECS admin
)

This instance is stateless and safe to reuse across requests.

Verify the setup

Make a simple authenticated request to confirm everything is wired up correctly:

const request = await client.request({
  action: 'get',
  resource: '/users/me',
})

const response = await fetch(`${ECS_BASE_URL}/request`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/octet-stream' },
  body: Buffer.from(request),
})

const result = await client.parse(new Uint8Array(await response.arrayBuffer()))
console.log(result.payload) // your user profile

If you see your user profile, the SDK is correctly installed and authenticated.

Next steps

See Making Requests to learn how to structure and send authenticated requests with the SDK.

Installation