Getting Started
Get up and running with the Blockstream ECS JavaScript SDK — a TypeScript library for secure, encrypted communication with Blockstream Custody Engine services.
What is the ECS JS SDK?
The @blockstream/ecs-js-sdk is a TypeScript SDK that handles all cryptographic communication between your application and the Blockstream Custody Engine (ECS). It abstracts away:
- COSE encoding — CBOR Object Signing and Encryption (RFC 8152)
- Request signing — ECDSA P-256 digital signatures on every request
- Payload encryption — RSA-OAEP encryption for sensitive transaction data
- Response verification — automatic decryption and signature validation on all responses
You work with plain JavaScript objects; the SDK handles the binary protocol underneath.
How it works
Every request goes through a three-step lifecycle:
Your Code → [Sign + Encrypt] → ECS Server → [Verify + Decrypt] → Your CodeThe SDK uses a dual-key system:
| Key | Algorithm | Purpose |
|---|---|---|
| ECDSA (P-256) | ES256 | Signing requests, verifying server responses |
| RSA (2048-bit) | RSA-OAEP | Encrypting payloads, decrypting server responses |
Quick example
import { Blockstream } from '@blockstream/ecs-js-sdk'
const client = new Blockstream(
clientRsaPrivateKeyPem, // your RSA private key (PEM)
clientEcdsaPrivateKey, // your ECDSA private key (32-byte Uint8Array)
deviceUuid, // your device UUID
serverRsaPublicKeyPem, // server RSA public key (PEM)
serverEcdsaPublicKey, // server ECDSA public key (33-byte Uint8Array)
)
const request = await client.request({
action: 'get',
resource: '/wallets',
})
const response = await fetch(`${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)