Session Keys

A session key is a delegated EVM address (an EOA your client controls) that your wallet authorizes to sign actions on its behalf. Instead of exposing your wallet’s private key to a trading service, you mint a scoped, expiring key that can sign only the actions you permit, on only the subaccounts you allow. Every session key carries two independent scope sets on one record:

Protocol scopes — on-chain authority (trade, transfer, withdraw, …). Signed into each action and re-validated by the protocol.
Off-chain scopes — server-side capabilities (account_info, delete_session_key). Never signed; enforced by the server.

See Access scopes for the full scope catalog and per-route gating.

How session keys are used

Diagram showing the two distinct ways a session key signs. First, signed actions: the key produces EIP-712 typed-data signatures over an Action struct for state-changing operations such as trading, RFQs, withdrawals, and transfers, and the protocol re-validates the key's protocol scopes against each action. Second, login headers: the key produces EIP-191 signatures over the login payload to authenticate HTTP and WebSocket sessions, and the server enforces the key's off-chain scopes, IP whitelist, and expiry. The wallet delegates authority to the session key, which then performs both signing roles on the wallet's behalf without ever exposing the wallet's own private key.

Delegated attenuation

The key you create can never exceed the authority of the key that signs the creation action. A child key’s scopes, expiry, and subaccounts must each be a subset of its parent’s. A key without admin cannot mint an admin child; a key expiring next week cannot mint a child expiring next month. The protocol enforces this when the create action is applied. The signing parent must itself hold the create_session_key protocol scope.

Create a session key

private/create_session_key is a signed action: your wallet (or a parent session key with create_session_key scope) EIP-712-signs a create-session-key action, which you then submit to the API. See Action signing for how to build the nonce, signature, and signature_expiry_sec fields.

wallet

string

required

Wallet the session key is registered for (0x-prefixed).

public_session_key

string

required

The delegated EVM address being authorized (0x-prefixed).

expiry_sec

integer

required

Unix seconds (UTC) after which the key is expired. Must not exceed the parent’s expiry.

subaccount_ids

integer[]

Subaccounts this key may act on. Omit or empty ⇒ all current and future subaccounts. Must be a subset of the parent’s subaccounts.

protocol_scopes

string[]

required

Wire-string protocol scopes signed into the action (e.g. "trade:orderbook:all", "withdraw"). Validated and attenuated in-protocol. See Access scopes.

offchain_scopes

string[]

required

Off-chain scopes (account_info, delete_session_key). Backend-only, not signed.

label

string

Human-readable label.

ip_whitelist

string[]

If non-empty, the key may only authenticate from these IPs.

nonce

string

required

Strictly-increasing anti-replay nonce (see Action signing).

signer

string

required

Address that produced signature — the wallet or a parent session key.

signature

string

required

0x-prefixed 65-byte r||s||v EIP-712 signature over the create action.

signature_expiry_sec

integer

required

Unix seconds after which the signed action is rejected. A typical client default is now + 600 (10 min).

module

string

required

EIP-712 action module address (the CREATE_SESSION_KEY_MODULE). Part of the signed struct hash — client and server must agree. A fixed protocol constant, identical across deployments; see Action signing.

import {
  DeriveClient,
  ProtocolScopeCode,
  OffchainScope,
} from '@derivexyz/derive-ts';
import { Wallet } from 'ethers';

const client = new DeriveClient({
  network: 'mainnet',
  wallet: process.env.PRIVATE_KEY!,
});
await client.connect();
await client.login();

// A fresh keypair for the delegated key; persist its private key for the bot.
const sessionWallet = Wallet.createRandom();

// The SDK builds and EIP-712-signs the create action for you (nonce, signature,
// signature_expiry_sec, module) using the client's signer.
const created = await client.sessionKeys.create({
  publicSessionKey: sessionWallet,
  expirySec: 1793491200,
  protocolScopes: [
    ProtocolScopeCode.TradeOrderbookAll,
    ProtocolScopeCode.TransferExistingSubaccount,
  ],
  offchainScopes: [OffchainScope.AccountInfo],
  subaccountIds: [9],
  label: 'market-maker-1',
});

console.log(created.public_session_key, created.subaccount_ids);
await client.close();

# Coming soon.

// Coming soon.

# Signed action: build nonce/signature/signature_expiry_sec per /authentication/action-signing.
# X-Derive* headers authenticate the HTTP session (see /json-rpc).
curl -X POST https://api.derive.xyz/v3/private/create_session_key \
  -H "Content-Type: application/json" \
  -H "X-DeriveWallet: $WALLET_ADDRESS" \
  -H "X-DeriveTimestamp: $TS" \
  -H "X-DeriveSignature: $SIG" \
  -d '{
    "wallet": "0x1234...abcd",
    "public_session_key": "0x9f00...beef",
    "expiry_sec": 1793491200,
    "subaccount_ids": [9],
    "protocol_scopes": ["trade:orderbook:all", "transfer:existing_subaccount"],
    "offchain_scopes": ["account_info"],
    "label": "market-maker-1",
    "ip_whitelist": [],
    "nonce": "1710000000000123000",
    "signer": "0x1234...abcd",
    "signature": "0xabcd...1b",
    "signature_expiry_sec": 1710000600,
    "module": "0x0000000000000000000000000000000000000000"
  }'

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "private/create_session_key",
  "params": {
    "wallet": "0x1234...abcd",
    "public_session_key": "0x9f00...beef",
    "expiry_sec": 1793491200,
    "subaccount_ids": [9],
    "protocol_scopes": ["trade:orderbook:all", "transfer:existing_subaccount"],
    "offchain_scopes": ["account_info"],
    "label": "market-maker-1",
    "ip_whitelist": [],
    "nonce": "1710000000000123000",
    "signer": "0x1234...abcd",
    "signature": "0xabcd...1b",
    "signature_expiry_sec": 1710000600,
    "module": "0x0000000000000000000000000000000000000000"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "public_session_key": "0x9f00...beef",
    "protocol_scopes": ["trade:orderbook:all", "transfer:existing_subaccount"],
    "offchain_scopes": ["account_info"],
    "label": "market-maker-1",
    "ip_whitelist": [],
    "expiry_sec": 1793491200,
    "subaccount_ids": [9]
  }
}

module is a fixed protocol constant (identical across deployments), but it must still match exactly or the signature will be rejected. Verify your encoding with the signing-preview helpers described in Action signing.

Edit a session key

private/edit_session_key updates off-chain fields only: label, ip_whitelist, and offchain_scopes. It requires no re-signing.

Protocol scopes are not editable. To change a key’s on-chain authority, mint a new key with create_session_key. This edit method only touches off-chain metadata.

Authorization depends on what you change:

Label only → requires the off-chain account_info scope.
IP whitelist or off-chain scopes → requires protocol admin (or the owning wallet).

wallet

string

required

Wallet the key belongs to.

public_session_key

string

required

The session key address to edit.

label

string

New label.

ip_whitelist

string[]

Replacement IP whitelist. Empty ⇒ no IP restriction.

offchain_scopes

string[]

Replacement off-chain scopes.

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

const client = new DeriveClient({
  network: 'mainnet',
  wallet: process.env.PRIVATE_KEY!,
});
await client.connect();
await client.login();

// Off-chain patch: omitted fields are left unchanged. Editing ip_whitelist or
// offchain_scopes requires the owner or an admin-scoped key.
const updated = await client.sessionKeys.edit({
  publicSessionKey: '0x9f00...beef',
  label: 'market-maker-primary',
  ipWhitelist: ['203.0.113.7'],
});

console.log(updated.label, updated.ip_whitelist);
await client.close();

# Coming soon.

// Coming soon.

# Off-chain patch (no signed action); X-Derive* headers: session auth (see /json-rpc).
curl -X POST https://api.derive.xyz/v3/private/edit_session_key \
  -H "Content-Type: application/json" \
  -H "X-DeriveWallet: $WALLET_ADDRESS" \
  -H "X-DeriveTimestamp: $TS" \
  -H "X-DeriveSignature: $SIG" \
  -d '{
    "wallet": "0x1234...abcd",
    "public_session_key": "0x9f00...beef",
    "label": "market-maker-primary",
    "ip_whitelist": ["203.0.113.7"]
  }'

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "private/edit_session_key",
  "params": {
    "wallet": "0x1234...abcd",
    "public_session_key": "0x9f00...beef",
    "label": "market-maker-primary",
    "ip_whitelist": ["203.0.113.7"]
  }
}

IP whitelist

If a key’s whitelist is non-empty, login from any other IP is rejected. An empty whitelist imposes no IP restriction.

Lifecycle at a glance

Create

Wallet (or a parent key with create_session_key scope) signs a create action granting a subset of its own scopes, expiry, and subaccounts.

Authenticate

The session key logs in via EIP-191 session login; its IP whitelist and expiry are enforced at this step.

Sign actions

The key EIP-712-signs each action; the protocol re-checks that the key’s scopes cover the action (see Action signing).

Edit metadata

Adjust label, IP whitelist, or off-chain scopes with edit_session_key. Protocol scopes require a fresh create_session_key.

Expire

The key stops working once expiry_sec passes.

Access scopes

The full protocol and off-chain scope catalog and per-route gating.

Action signing

How the create action (and every trading action) is signed with EIP-712.

Get Started

Authentication & Keys

Trading Concepts

Permissionless Vaults

WebSocket

Reference

How session keys are used

Delegated attenuation

Create a session key

Edit a session key

IP whitelist

Lifecycle at a glance

Access scopes

Action signing

​How session keys are used

​Delegated attenuation

​Create a session key

​Edit a session key

​IP whitelist

​Lifecycle at a glance

​Related

Access scopes

Action signing

How session keys are used

Delegated attenuation

Create a session key

Edit a session key

IP whitelist

Lifecycle at a glance

Related