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.
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. 
