How to Generate and Use a Session Key

Generate and use a session key

Use this when you want to sign requests from a key that is not your funded trader wallet, such as a trading process that should never hold the funded wallet’s key. A session key is a separate wallet the trader authorizes to sign a bounded set of trading actions until a chosen expiry. The trader wallet signs that authorization once; the session key then signs each request, so the funded wallet stays out of the per-request loop. You need the trader wallet key that controls the account, a separate session key wallet, an expiry as a Unix timestamp, and the set of actions the session key may take. Two keys play two roles. The trader wallet authorizes the session key once by signing a delegated-session payload. The session key signs each request it is scoped for, and that authorization travels inside the request as the sessionKeySignature. Signed Private Requests covers where that field sits in request content. Use the network values you are authorizing for:

Network	`chainId`	DerivaDEX verifying smart contract address
Testnet (Sepolia)	`11155111`	`0x5d1a3b4181d3cad422f404f28e9e972d0ba4dad6`
Mainnet	`1`	`0x6fb8aa6fc6f27e591423009194529ae126660027`

Follow the session-key procedure

Obtain the trader wallet key material. This is the funded account that authorizes the session and that the operator already recognizes.
Generate a separate session key wallet. This key signs trading requests and never holds collateral.
Choose an expiry as a Unix timestamp in seconds. The operator rejects the session key once that time passes.
Choose the action scope: the actions the session key is allowed to sign. Scope codes are 0 unrestricted, 1 order, 2 modify-order, 3 cancel-order, 4 cancel-all.
Sign the delegated-session payload — the expiry, the action scope, and the session public key — with the trader wallet to produce the sessionKeySignature.
Include the sessionKeySignature in each request, and sign the request hash with the session key instead of the trader wallet.
Recover both signers locally before submission.

A session key authorizes only the actions in its scope, and only until its expiry. To revoke one earlier, add it to the trader’s delegated-session deny list through a profile update; see Signed Private Requests.

Worked example

This example authorizes a session key for Order and CancelOrder, then signs an order with it. The sample keys and expiry are fixed only so the result is reproducible. In production, load your own trader and session wallets and set the expiry relative to the current time.

import time
from enum import IntEnum

from eth_account import Account

# Sample key material for this worked example only. In production, load the
# funded trader wallet and a separate session key wallet from your own store.
trader_private_key = "0x9c0257114eb9399a2985f8e75dad7600c5d89fe3824ffa99ec1c3eb8bf3b0501"
session_private_key = "0x6f1e3c1d2b9a8f7e6d5c4b3a29180706f5e4d3c2b1a09f8e7d6c5b4a39281706"

trader_account = Account.from_key(trader_private_key)
session_account = Account.from_key(session_private_key)
trader_address_with_prefix = f"0x00{trader_account.address[2:]}"

# In production: session_expiry = int(time.time()) + 60 * 60  # one hour out
session_expiry = 1770878619  # fixed here so the example is reproducible


class SessionActionNames(IntEnum):
    UNRESTRICTED = 0
    ORDER = 1
    MODIFY_ORDER = 2
    CANCEL_ORDER = 3
    CANCEL_ALL = 4


acl_scope = [SessionActionNames.ORDER, SessionActionNames.CANCEL_ORDER]

Example: authorize the session key

Authorizing session keys can be implemented in two ways here:

Direct implementation builds and signs the delegated-session payload directly.
DDX client library shows the shortest path if you already use ddx-python.

Both approaches produce the same sessionKeySignature for the same input.

Direct implementation

The domain helpers are the same ones used in How to Sign DerivaDEX Requests with EIP-712. The session-key payload adds its own struct hash on top:

from collections import OrderedDict
import cbor2
from dataclasses import dataclass

from eth_abi import encode
from eth_utils.crypto import keccak

EIP191_HEADER = b"\x19\x01"


def compute_eip712_domain_separator(chain_id: int, verifying_contract: str) -> bytes:
    domain_type_hash = keccak(
        b"EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"
    )
    return keccak(
        domain_type_hash
        + keccak(b"DerivaDEX")
        + keccak(b"1")
        + encode(["uint256"], [chain_id])
        + encode(["address"], [verifying_contract])
    )


def compute_eip712_hash(
    chain_id: int,
    verifying_contract: str,
    message_struct_hash: bytes,
) -> str:
    domain_separator = compute_eip712_domain_separator(chain_id, verifying_contract)
    digest = keccak(EIP191_HEADER + domain_separator + message_struct_hash)
    return "0x" + digest.hex()


@dataclass
class SessionKeyPayload:
    expiry: int
    acl_scope: list[int]
    session_public_key: bytes


def compute_message_struct_hash(session_key_payload: SessionKeyPayload) -> bytes:
    session_key_payload_type_hash = keccak(
        b"SessionDelegatedPayload(uint256 expiry,uint256[] aclScope,bytes sessionPublicKey)"
    )
    acl_hash = keccak(
        b"".join(encode(["uint256"], [scope]) for scope in session_key_payload.acl_scope)
    )
    session_public_key_hash = keccak(session_key_payload.session_public_key)

    return keccak(
        session_key_payload_type_hash
        + encode(["uint256"], [session_key_payload.expiry])
        + acl_hash
        + session_public_key_hash
    )

Assemble the payload, sign it with the trader wallet, and encode the result. The encoded aclScope carries the action names, not the numeric codes:

acl_names = [scope.name.title().replace("_", "") for scope in acl_scope]

session_key_payload = SessionKeyPayload(
    expiry=session_expiry,
    acl_scope=acl_scope,
    session_public_key=session_account._key_obj.public_key.to_compressed_bytes(),
)

message_struct_hash = compute_message_struct_hash(session_key_payload)
eip712_hash = compute_eip712_hash(
    chain_id=11155111,
    verifying_contract="0x5d1a3b4181d3cad422f404f28e9e972d0ba4dad6",
    message_struct_hash=message_struct_hash,
)

session_key_payload_signature = trader_account.unsafe_sign_hash(eip712_hash)

payload = OrderedDict(
    [
        ("sessionSignature", session_key_payload_signature.signature),
        ("expiry", session_key_payload.expiry),
        ("aclScope", acl_names),
        ("sessionPublicKey", session_key_payload.session_public_key),
    ]
)
session_key_signature = "0x" + (b"\x02" + cbor2.dumps(payload, canonical=False)).hex()

For this input, the target result is:

"0x02a47073657373696f6e5369676e61747572655841b06bc3939bce39053fd07a76237fe66a3e8090b264eb7b37e8696c21f241204e08bf28d338b3578d15437582864fcf431e527a3877a20f05787396046311109e1c666578706972791a698d769b6861636c53636f706582654f726465726b43616e63656c4f726465727073657373696f6e5075626c69634b6579582103a070640574b7543181f04eb1846e42967eb38e506b647c0ee0c03d07524e9b30"

DDX client library

If you already use ddx-python, one call signs and encodes the same payload and returns the session signer address alongside it:

from ddx._rust.common import make_session_key_signature
# Only run the following two load_testnet() lines if using testnet; can omit otherwise
from ddx import load_testnet
load_testnet()

session_key_signature, session_signer_address = make_session_key_signature(
    trader_private_key,
    session_private_key,
    session_expiry,
    acl_scope,
)

session_key_signature matches the direct result above, and session_signer_address matches session_account.address.

Use the session key in a request

Build the request as you would in How to Sign DerivaDEX Requests with EIP-712, with two changes: set session_key_signature on the request, and sign the request hash with the session key rather than the trader wallet.

from ddx._rust.common.enums import OrderSide, OrderType
from ddx._rust.common.requests.intents import OrderIntent
from ddx._rust.decimal import Decimal
from ddx.rest_client.clients.signed_client import sign_eip712_hash

order_intent = OrderIntent(
    symbol="ETHP",
    strategy="main",
    side=OrderSide.Bid,
    order_type=OrderType.Limit,
    amount=Decimal("0.1"),
    price=Decimal("1800"),
    stop_price=Decimal("0"),
    nonce="0x3137373038373530313938323238333436363300000000000000000000000000",
    client_timestamp_ms=1770875019823,
    recv_window_ms=5000,
    session_key_signature=session_key_signature,
)
order_hash = order_intent.hash_eip712()
order_intent.signature = sign_eip712_hash(session_account, order_hash)

The order hash is the same OrderParams hash from the EIP-712 signing guide, because the sessionKeySignature rides in the request content rather than being folded into OrderParams. For these order fields that hash is 0x8d5950c5691e5c4054c537f8a7b14e33dee9222f34e98fe8120624d636e37ba5. For live submission with a session key tied to a funded trader wallet, hand the session account to the client as the local signer:

# receipt = await client.signed.place_order(
#     order_intent,
#     local_account=session_account,
# )

Check your result before you submit

Recover the request signer from the order signature and confirm it is the session key, not the trader wallet.
Recover the trader signer from the sessionKeySignature payload and confirm it is the trader wallet that authorized the session.
Confirm the requested action is within the session key’s scope and that the expiry is still in the future.

from eth_account import Account

recovered_session_address = Account._recover_hash(
    bytes.fromhex(order_hash.removeprefix("0x")),
    signature=bytes.fromhex(order_intent.signature.removeprefix("0x")),
)
recovered_order_hash, recovered_trader_address = order_intent.recover_signer()

assert recovered_session_address.lower() == session_account.address.lower()
assert recovered_trader_address.lower() == trader_address_with_prefix.lower()

print(f"Session signer:   {session_account.address}")
print(f"Recovered session:{recovered_session_address}")
print(f"Trader wallet:    {trader_address_with_prefix}")
print(f"Recovered trader: {recovered_trader_address}")

A decode failure, an expired payload, or an action outside the scope returns SignedRequestAuthenticationFailed. A denied session signer returns Forbidden. See Error Reference for the exact rejection path.

Appendix

The sessionKeySignature is a CBOR-encoded map with a one-byte version prefix:

Part	What it contains
`sessionSignature`	Trader wallet’s EIP-712 signature over `SessionDelegatedPayload(expiry, aclScope, sessionPublicKey)`
`expiry`	Unix timestamp in seconds after which the session key is rejected
`aclScope`	Action names the session key may sign, such as `Order` and `CancelOrder`
`sessionPublicKey`	Compressed secp256k1 public key of the session wallet
Final value	`0x02` version byte followed by the CBOR-encoded payload, hex-encoded with a `0x` prefix

Continue with submission

Once the session key has signed the request hash and the sessionKeySignature is in the request content, encrypt and submit the request the same way as any signed request. Use How to Encrypt Requests for the Operator for encryption and submission to POST /v2/request. If the operator rejects a session-key request after local recovery matches, use Error Reference for the failure code.

​Generate and use a session key

​Follow the session-key procedure

​Worked example

​Example: authorize the session key

​Direct implementation

​DDX client library

​Use the session key in a request

​Check your result before you submit

​Appendix

​Continue with submission