Strails Payload Encryption with X25519 and libsodium

Strails supports X25519 payload encryption using libsodium’s sealed-box (crypto_box_seal) construction. Encryption is optional on some endpoints, but you should enable it for any production integration that handles PII, wallet addresses, or financial data - an intercepted transport layer will not expose your payload contents.

Security Model

Every encrypted exchange involves two X25519 key pairs. Both parties generate their own pair; each shares only their public key.

Party	Key pair	Purpose
Fintech (you)	Your X25519 key pair	Decrypt responses and webhooks that Strails seals to your public key
Strails	Strails X25519 key pair	Encrypt requests you send - seal them to Strails’ public key

Strails exposes its public key via GET /getplatformpublickey. You generate your own X25519 key pair and register the 64-character hex public key with Strails via POST /storepublickey so it can encrypt responses and webhooks back to you. The stored key is a raw X25519 public key (not an Ed25519 signing key). It is used only for crypto_box_seal.

Request Encryption Flow

To send an encrypted request:

Build your JSON payload

Construct the request body as documented for the endpoint - a plain JSON object.

Seal the payload

Use the Strails X25519 public key to seal the payload with libsodium crypto_box_seal. This produces an opaque byte array that only Strails can unseal.

Base64-encode and send

Base64-encode the sealed bytes and send the resulting string in the payload field of your request body.

Your JSON payload
      +
Strails public key
      v
libsodium crypto_box_seal
      v
Base64-encoded ciphertext  ->  sent as "payload" in request body

const sodium = require('libsodium-wrappers');

await sodium.ready;

// Strails public key - received during onboarding
const strailsPublicKey = sodium.from_hex(process.env.STRAILS_PUBLIC_KEY_HEX);

const payload = JSON.stringify({
  bvn: '12345678901',
  userId: 'user_uniqueID',
  email: 'user@example.com',
  phoneNumber: '+2348012345678',
});

const encrypted = sodium.crypto_box_seal(
  sodium.from_string(payload),
  strailsPublicKey
);

const base64Payload = sodium.to_base64(encrypted);

// Include base64Payload as the "payload" field in your request body
const response = await fetch('https://api.strails.io/v1/onboarduser', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.STRAILS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ payload: base64Payload }),
});

Response Decryption Flow

To decrypt an encrypted response:

Extract the payload field

Pull the payload string from the response body.

Base64-decode it

Convert the string back to raw bytes.

Unseal with your private key

Use libsodium crypto_box_seal_open with your public and private keys to recover the original JSON.

Encrypted base64 string  (from response body)
      v
Base64-decode
      v
libsodium crypto_box_seal_open  (your public key + your private key)
      v
Original JSON payload

const sodium = require('libsodium-wrappers');

await sodium.ready;

const yourPublicKey  = sodium.from_hex(process.env.MY_PUBLIC_KEY_HEX);
const yourPrivateKey = sodium.from_hex(process.env.MY_PRIVATE_KEY_HEX);

// `responseBody` is the parsed JSON response from Strails
const encryptedBytes = sodium.from_base64(responseBody.payload);

const decryptedBytes = sodium.crypto_box_seal_open(
  encryptedBytes,
  yourPublicKey,
  yourPrivateKey
);

const data = JSON.parse(sodium.to_string(decryptedBytes));
console.log(data);

Generate Your Key Pair

Node.js
Python

const sodium = require('libsodium-wrappers');

await sodium.ready;

const keyPair = sodium.crypto_box_keypair();

console.log('Public key (hex):', sodium.to_hex(keyPair.publicKey));
console.log('Private key (hex):', sodium.to_hex(keyPair.privateKey));

// Store the private key in your secrets manager immediately.
// Share only the public key with Strails via POST /storepublickey.

import nacl.public

keypair = nacl.public.PrivateKey.generate()

print("Public key (hex):", keypair.public_key.encode().hex())
print("Private key (hex):", keypair.encode().hex())

# Store the private key in your secrets manager immediately.
# Share only the public key with Strails via POST /storepublickey.

Storing Your Public Key

Register your public key with Strails by calling POST /storepublickey. /storepublickey accepts { "data": "<64-hex-character X25519 public key>" } or the AES-encrypted legacy envelope whose decrypted data is the same 64-hex key. Strails will use this key to encrypt all responses and webhooks sent back to your integration.

POST /storepublickey
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "data": "<64-hex-character X25519 public key>"
}

A successful registration returns 200 OK. After this, Strails will seal response payloads and webhook bodies to your public key so only you can decrypt them.

Platform Public Key

Retrieve the Strails X25519 public key via GET /getplatformpublickey. Use it to seal requests to Strails with libsodium crypto_box_seal.

AES Key (Legacy)

Call GET /getaeskey to retrieve your raw, unmasked AES key. You can use it to decrypt legacy AES-GCM payloads and to verify webhook signatures when no dedicated webhook secret is configured.

Best Practices

Never expose your private key. Keep it out of client-side code, logs, environment files committed to source control, and any network call.
Use a dedicated secrets manager. Store your private key in AWS Secrets Manager, HashiCorp Vault, or an equivalent service - not in a plain .env file.
Rotate keys periodically. Generate a new key pair on a regular schedule, register the new public key with Strails, and retire the old private key from your secrets manager.
Test encryption in staging first. Validate your encrypt/decrypt round-trip against https://beta.stablesrail.io/v1/ before enabling it in production.

Contact support@strails.io to receive the current Strails public key, register your own public key, or get help troubleshooting encryption issues.

​Security Model

​Request Encryption Flow

​Response Decryption Flow

​Generate Your Key Pair

​Storing Your Public Key

​Platform Public Key

​AES Key (Legacy)

​Best Practices

Security Model

Request Encryption Flow

Response Decryption Flow

Generate Your Key Pair

Storing Your Public Key

Platform Public Key

AES Key (Legacy)

Best Practices