API authentication - Byzantine Finance

All API requests must be authenticated using ECDSA signature-based authentication. You’ll use your Integrator Private Key to sign each request and include the signature in the request headers.

Authentication Headers

Each API request requires the following headers:

Header	Description
`X-Pubkey`	Your public key derived from your private key (hex format with `0x` prefix)
`X-Timestamp`	Current Unix timestamp in seconds
`X-Signature`	ECDSA signature of the request (DER-encoded hex with `0x` prefix)
`Content-Type`	Must be `application/json`

Use our Integrator SDK
Manual implementation

Our Integrator SDK provides a convenient way to generate the authentication headers for your API requests.The getStamp method returns an object containing the required authentication headers (X-Pubkey, X-Timestamp, X-Signature, and Content-Type) that you can include in your API request.

Installation

npm install @byzantine/integrator-sdk

Initialize the Byzantine Client

import { ByzantineClient } from '@byzantine/integrator-sdk';

const client = new ByzantineClient({
  integratorPrivateKey: 'YOUR_INTEGRATOR_PRIVATE_KEY',
});

Usage example

Use the getStamp method to generate authentication headers for your API requests:

const payload = {
  // Your request payload
};

// Generate the api key stamp
const apiKeyStamp = await client.apiKey.getStamp(
  "POST",
  "/v1/submit/send-transaction-otp",
  payload
);

// Use the apiKeyStamp headers in your API call
const response = await fetch(
  "https://api.byzantine.fi/v1/submit/send-transaction-otp?chain_id=1",
  {
    method: "POST",
    headers: apiKeyStamp,
    body: payload,
  }
);

Signature Generation

The signature is generated by:

Constructing a message string in the format: {timestamp}{method}{path_and_query}{body}

timestamp: Unix timestamp in seconds
method: HTTP method in uppercase (e.g., GET, POST)
path_and_query: Full path including query parameters (e.g., /query/get-deposit?chain_id=1)
body: JSON stringified request body (empty string for GET requests)

Hashing the message using SHA-256
Signing the hash with your private key using ECDSA (secp256k1 curve)
Encoding the signature in DER format and converting to hex

Implementation Example

Here’s a reference implementation in Node.js:

import elliptic from "elliptic";
import { createHash } from "crypto";

const EC = elliptic.ec;
const ec = new EC("p256");

const INTEGRATOR_PRIVATE_KEY = process.env.INTEGRATOR_PRIVATE_KEY;

export function generateHeaders(method, pathAndQuery, body = "") {
  // Get the key pair
  const cleanPrivateKey = INTEGRATOR_PRIVATE_KEY.replace(/^0x/, "");
  const keyPair = ec.keyFromPrivate(cleanPrivateKey, "hex");
  const publicKey = "0x" + keyPair.getPublic(true, "hex");

  // Get the timestamp in seconds since the Unix epoch (UTC)
  const timestamp = Math.floor(Date.now() / 1000).toString();

  // Build the message to sign
  // Format: {timestamp}{method}{path_and_query}{body}
  const bodyStr = typeof body === "object" ? JSON.stringify(body) : body;
  const message = `${timestamp}${method.toUpperCase()}${pathAndQuery}${bodyStr}`;

  // Hash the message and sign it
  const messageHash = createHash("sha256").update(message).digest();
  const signature = keyPair.sign(messageHash);

  // Encode the signature in DER then in hex
  const signatureHex = "0x" + signature.toDER("hex");

  return {
    "X-Pubkey": publicKey,
    "X-Timestamp": timestamp,
    "X-Signature": signatureHex,
    "Content-Type": "application/json",
  };
}

Usage Example

// Example POST request
const body = {
  userId: "user123",
  vaultAddress: "0x...",
};
const headers = generateHeaders("POST", "/submit/deposit", body);

// Make the API call
const response = await fetch("https://api.byzantine.fi/submit/deposit", {
  method: "POST",
  headers: headers,
  body: JSON.stringify(body),
});

Keep your Integrator Private Key secure!

OpenAPI Specification

Explore the full structure and generate your own client using our OpenAPI specification.

​Authentication Headers

​Installation

​Initialize the Byzantine Client

​Usage example

​Signature Generation

​Implementation Example

​Usage Example

​OpenAPI Specification

Authentication Headers

Installation

Initialize the Byzantine Client

Usage example

Signature Generation

Implementation Example

Usage Example

OpenAPI Specification