HomeDocumentationAPI Reference
Log In

Authentication

There two authentication types, both sign-able via the owner or registered session key wallets.

Private Endpoints

All private endpoints and messages starting with private/ in both REST and Websocket require authentication.

Scheme

ParamDescription
X-LYRA_WALLETEthereum wallet address of the account owner
X-LYRA-TIMESTAMPCurrent UTC timestamp in ms
X-LYRA-SIGNATUREKeccak-256 signature (standard ETH signing) of X-LYRA-TIMESTAMP usingX-LYRA_WALLET or registered session_key private key

The authentication scheme uses Ethereum signatures to validate that the sender of the request is either the owner of the account or a registered session key.

REST

Add the authentication scheme as headers into any private/ REST request:


let wallet = new ethers.Wallet(process.env.OWNER_PRIVATE_KEY as string, provider);
let timestamp = Date.now() // ensure UTC
let signature = (await wallet.signMessage(timestamp)).toString()

const response = await axios.request<R>({
  "POST",
  "https://api-demo.lyra.finance/private/get_subaccounts",
  {wallet: wallet.address},
  {
  	"X-LyraWallet": wallet.address,
  	"X-LyraTimestamp": timestamp,
  	"X-LyraSignature": signature
  }
});

Websocket

Authenticate your websocket session by sending the below public/login message:

let wallet = new ethers.Wallet(process.env.OWNER_PRIVATE_KEY as string, provider);
let timestamp = Date.now() // ensure UTC
let signature = await wallet.signMessage(timestamp)).toString()

wsc.send(JSON.stringify({
  method: 'public/login',
  params: {
    "wallet": wallet.address,
    "timestamp": timestamp,
    "signature": signature
  },
  id: 1,
}));

Private channels require the above login method to be called before they can be subscribed to. Channels are considered private when they reference {subaccount_id} or {wallet} parameter.

Self-custodial Requests

Due to the self-custodial nature of the API, the orderbook cannot force the below user actions without an explicit signature by the user:

  1. Post Orders
  2. Deposit / Withdrawal
  3. Transfer

As part of the request, the owner or a registered session key must explicitly sign a payload using the private key of the wallet - which is verified via the respective "module" in Matching.sol.

Thus, each self-custodial request requires two auth steps:

  • pass endpoint authentication (via REST headers or WS login)
  • include a sign of the specific payload as one of the API params

Note refer to the docs for each request to check the exact param scheme.

👍

See Onboard via Interface or Submit Order guides for example "self-custodial" requests.

Session Keys

Session keys can be used to sign private requests instead of the owner wallet. See the Session Keys section