Session Login

Session login proves that a connection (WebSocket) or a request (HTTP) may act on behalf of a wallet. It works over both transports and returns the list of subaccount IDs the caller is authenticated for.

Logging in does not authorize trading. Every state-changing action carries its own EIP-712 signature that the protocol re-verifies independently — see Action signing.

What you sign

The signed message is the current time in milliseconds as a decimal string (Date.now().toString()), signed with EIP-191 personal_sign. There is no separate challenge or login nonce — the timestamp is the anti-replay token. The signer may be the wallet itself or a delegated session key. The three values — wallet, timestamp, signature — are the same on both transports. WebSocket sends them as public/login params; HTTP sends them as X-Derive* headers. The server reads each value from the header or the request params interchangeably.

WebSocket

Open the socket, then call public/login with {wallet, timestamp, signature}. The result is the array of subaccount IDs the connection is now authenticated for (an empty session-key subaccount list resolves to all of the wallet’s current subaccounts).

import { DeriveClient } from '@derivexyz/derive-ts';

const client = new DeriveClient({
  network: 'mainnet',
  wallet: process.env.PRIVATE_KEY!,
});
await client.connect(); // open the websocket
const subaccountIds = await client.login(); // EIP-191 login over public/login
// The client re-logs in automatically after a reconnect.

# Coming soon.

// Coming soon.

The raw frame and response:

{
  "id": "1",
  "jsonrpc": "2.0",
  "method": "public/login",
  "params": {
    "wallet": "0xYourWalletAddress",
    "timestamp": "1720512000000",
    "signature": "0x…65-byte personal_sign over the timestamp string"
  }
}

{
  "id": "1",
  "jsonrpc": "2.0",
  "result": [9, 42]
}

HTTP

REST requests authenticate per request — there is no separate login call. Attach the same three values as headers to each private request: X-DeriveWallet, X-DeriveTimestamp, X-DeriveSignature.

import { DeriveClient } from '@derivexyz/derive-ts';

// No connect()/login(): the client signs and attaches X-Derive\* headers on
// every private REST call automatically.
const client = new DeriveClient({
  network: 'mainnet',
  wallet: process.env.PRIVATE_KEY!,
});
const subaccountIds = await client.subaccounts.list(); // authenticated over HTTP

# Coming soon.

// Coming soon.

# timestamp = current time in milliseconds
TS=$(($(date +%s) * 1000))
# SIG = EIP-191 personal_sign over "$TS" (wallet or session key)
SIG="0x…65-byte signature"

curl -X POST https://api.derive.xyz/v3/private/get_subaccounts \
  -H "Content-Type: application/json" \
  -H "X-DeriveWallet: 0xYourWalletAddress" \
  -H "X-DeriveTimestamp: $TS" \
  -H "X-DeriveSignature: $SIG" \
  -d '{ "wallet": "0xYourWalletAddress" }'

The signature may come from the wallet itself or from a session key the wallet has delegated:

Direct-wallet auth

The recovered signer equals wallet. The connection receives full authority, and the timestamp freshness window is enforced — sign immediately before connecting.

Session-key auth

The recovered signer is a registered session-key address whose wallet matches and which is not expired. The key’s authority is bounded by its access scopes, and if it declares an IP whitelist the request IP must be on it. Freshness is not enforced on this path.

The exact timestamp validity window for direct-wallet auth is deployment-specific; allow for it (and a little clock skew) when signing the login timestamp.

Re-authentication

Long-lived WebSocket sessions periodically re-verify the stored login signature as part of the heartbeat, so a connection stays authenticated without a fresh public/login. See Connecting over WebSocket for heartbeat and reconnection guidance.

Get Started

Authentication & Keys

Trading Concepts

Permissionless Vaults

WebSocket

Reference

What you sign

WebSocket

HTTP

Re-authentication

​What you sign

​WebSocket

​HTTP

​Who may sign the login

​Re-authentication

What you sign

WebSocket

HTTP

Who may sign the login

Re-authentication