Authentication

SIWE bearer + session key

The wallet signs once with SIWE to authorise a scoped session key. From then on, the session key signs every order — no MetaMask prompt per trade, no private-key exposure to the gateway.

Step 1 — SIWE

Wallet signs an EIP-4361 message. Message includes the session-key pubkey and its scope (expiry, max notional, symbols).

Step 2 — Bearer

Gateway returns a bearer token bound to the session key. Token expires with the session (max 24 h).

Step 3 — Trade

Every trading call includes the bearer and an Ed25519 signature from the session key over the JSON payload.

SIWE request body

{
  "message": "liberx.xyz wants you to sign in with your Ethereum account:\n0xAb…F9\n\nAuthorize trading session for LiberX L1.\n\nURI: https://app.liberx.xyz\nVersion: 1\nChain ID: 1\nNonce: 9b21d8...\nIssued At: 2026-04-19T22:00:00Z\nExpiration Time: 2026-04-20T22:00:00Z",
  "signature": "0x32ef…",
  "sessionKey": "04f1d3e9…"
}

Signing a trade

// Client
const payload = JSON.stringify({ symbol: 'BTCUSD', side: 'long', type: 'market',
                                 margin: 1000, leverage: 10, nonce: 17 });
const digest = sha256(utf8(payload));
const sig    = ed25519.sign(digest, sessionKeyPriv);

fetch('/v1/orders', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type':  'application/json',
    'X-Liberx-Sig':  base64(sig),
  },
  body: payload,
});