Session Keys

Register a scoped session key

Authorizes a new session key for a wallet from a signed action, granting it a set of on-chain (protocol) scopes and off-chain scopes with an expiry, an optional label, an optional IP allowlist, and an optional list of subaccounts it may act on (defaults to all of the wallet’s subaccounts). Send the signed action fields (nonce, signer, signature, signature expiry, and module) alongside the requested scopes; the endpoint returns the registered key’s public address and its granted scopes, expiry, allowlist, label, and subaccounts.

POST

private

create_session_key

curl --request POST \
  --url https://api.derive.xyz/v3/private/create_session_key \
  --header 'Content-Type: application/json' \
  --data '
{
  "expiry_sec": 1,
  "nonce": "<string>",
  "offchain_scopes": [
    "<string>"
  ],
  "protocol_scopes": [
    "<string>"
  ],
  "public_session_key": "<string>",
  "signature": "<string>",
  "signature_expiry_sec": 1,
  "signer": "<string>",
  "wallet": "<string>",
  "ip_whitelist": [
    "<string>"
  ],
  "label": "<string>",
  "subaccount_ids": [
    1
  ]
}
'

import requests

url = "https://api.derive.xyz/v3/private/create_session_key"

payload = {
    "expiry_sec": 1,
    "nonce": "<string>",
    "offchain_scopes": ["<string>"],
    "protocol_scopes": ["<string>"],
    "public_session_key": "<string>",
    "signature": "<string>",
    "signature_expiry_sec": 1,
    "signer": "<string>",
    "wallet": "<string>",
    "ip_whitelist": ["<string>"],
    "label": "<string>",
    "subaccount_ids": [1]
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    expiry_sec: 1,
    nonce: '<string>',
    offchain_scopes: ['<string>'],
    protocol_scopes: ['<string>'],
    public_session_key: '<string>',
    signature: '<string>',
    signature_expiry_sec: 1,
    signer: '<string>',
    wallet: '<string>',
    ip_whitelist: ['<string>'],
    label: '<string>',
    subaccount_ids: [1]
  })
};

fetch('https://api.derive.xyz/v3/private/create_session_key', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.derive.xyz/v3/private/create_session_key",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'expiry_sec' => 1,
    'nonce' => '<string>',
    'offchain_scopes' => [
        '<string>'
    ],
    'protocol_scopes' => [
        '<string>'
    ],
    'public_session_key' => '<string>',
    'signature' => '<string>',
    'signature_expiry_sec' => 1,
    'signer' => '<string>',
    'wallet' => '<string>',
    'ip_whitelist' => [
        '<string>'
    ],
    'label' => '<string>',
    'subaccount_ids' => [
        1
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.derive.xyz/v3/private/create_session_key"

	payload := strings.NewReader("{\n  \"expiry_sec\": 1,\n  \"nonce\": \"<string>\",\n  \"offchain_scopes\": [\n    \"<string>\"\n  ],\n  \"protocol_scopes\": [\n    \"<string>\"\n  ],\n  \"public_session_key\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"signature_expiry_sec\": 1,\n  \"signer\": \"<string>\",\n  \"wallet\": \"<string>\",\n  \"ip_whitelist\": [\n    \"<string>\"\n  ],\n  \"label\": \"<string>\",\n  \"subaccount_ids\": [\n    1\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.derive.xyz/v3/private/create_session_key")
  .header("Content-Type", "application/json")
  .body("{\n  \"expiry_sec\": 1,\n  \"nonce\": \"<string>\",\n  \"offchain_scopes\": [\n    \"<string>\"\n  ],\n  \"protocol_scopes\": [\n    \"<string>\"\n  ],\n  \"public_session_key\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"signature_expiry_sec\": 1,\n  \"signer\": \"<string>\",\n  \"wallet\": \"<string>\",\n  \"ip_whitelist\": [\n    \"<string>\"\n  ],\n  \"label\": \"<string>\",\n  \"subaccount_ids\": [\n    1\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.derive.xyz/v3/private/create_session_key")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expiry_sec\": 1,\n  \"nonce\": \"<string>\",\n  \"offchain_scopes\": [\n    \"<string>\"\n  ],\n  \"protocol_scopes\": [\n    \"<string>\"\n  ],\n  \"public_session_key\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"signature_expiry_sec\": 1,\n  \"signer\": \"<string>\",\n  \"wallet\": \"<string>\",\n  \"ip_whitelist\": [\n    \"<string>\"\n  ],\n  \"label\": \"<string>\",\n  \"subaccount_ids\": [\n    1\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "expiry_sec": 1,
  "ip_whitelist": [
    "<string>"
  ],
  "offchain_scopes": [
    "<string>"
  ],
  "protocol_scopes": [
    "<string>"
  ],
  "public_session_key": "<string>",
  "subaccount_ids": [
    1
  ],
  "label": "<string>"
}

Body

application/json

Request parameters for registering a scoped session key. Address fields are 0x-prefixed hex strings.

expiry_sec

integer<uint64>

required

Required range: x >= 0

nonce

string

required

offchain_scopes

string[]

required

Off-chain scopes which are validated in backend only

protocol_scopes

string[]

required

Scopes granted to the session key, validated by the protocol. Each is a string like "trade:orderbook:all".

public_session_key

string

required

Session key address being authorized.

signature

string

required

0x-prefixed hex, 65-byte r||s||v.

signature_expiry_sec

integer<uint64>

required

Required range: x >= 0

signer

string

required

wallet

string

required

Wallet the session key is being registered for.

ip_whitelist

string[] | null

label

string | null

subaccount_ids

integer<uint64>[] | null

Required range: x >= 0

Response

Success

expiry_sec

integer<uint64>

required

Required range: x >= 0

ip_whitelist

string[]

required

offchain_scopes

string[]

required

protocol_scopes

string[]

required

public_session_key

string

required

subaccount_ids

integer<uint64>[]

required

Subaccounts the key may act on. Empty/omitted request (all subaccounts) is expanded to the wallet's current subaccount list.

Required range: x >= 0

label

string | null

List subaccount IDs for a wallet

Edit a session key's off-chain settings

⌘I

curl --request POST \
  --url https://api.derive.xyz/v3/private/create_session_key \
  --header 'Content-Type: application/json' \
  --data '
{
  "expiry_sec": 1,
  "nonce": "<string>",
  "offchain_scopes": [
    "<string>"
  ],
  "protocol_scopes": [
    "<string>"
  ],
  "public_session_key": "<string>",
  "signature": "<string>",
  "signature_expiry_sec": 1,
  "signer": "<string>",
  "wallet": "<string>",
  "ip_whitelist": [
    "<string>"
  ],
  "label": "<string>",
  "subaccount_ids": [
    1
  ]
}
'

import requests

url = "https://api.derive.xyz/v3/private/create_session_key"

payload = {
    "expiry_sec": 1,
    "nonce": "<string>",
    "offchain_scopes": ["<string>"],
    "protocol_scopes": ["<string>"],
    "public_session_key": "<string>",
    "signature": "<string>",
    "signature_expiry_sec": 1,
    "signer": "<string>",
    "wallet": "<string>",
    "ip_whitelist": ["<string>"],
    "label": "<string>",
    "subaccount_ids": [1]
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    expiry_sec: 1,
    nonce: '<string>',
    offchain_scopes: ['<string>'],
    protocol_scopes: ['<string>'],
    public_session_key: '<string>',
    signature: '<string>',
    signature_expiry_sec: 1,
    signer: '<string>',
    wallet: '<string>',
    ip_whitelist: ['<string>'],
    label: '<string>',
    subaccount_ids: [1]
  })
};

fetch('https://api.derive.xyz/v3/private/create_session_key', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.derive.xyz/v3/private/create_session_key",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'expiry_sec' => 1,
    'nonce' => '<string>',
    'offchain_scopes' => [
        '<string>'
    ],
    'protocol_scopes' => [
        '<string>'
    ],
    'public_session_key' => '<string>',
    'signature' => '<string>',
    'signature_expiry_sec' => 1,
    'signer' => '<string>',
    'wallet' => '<string>',
    'ip_whitelist' => [
        '<string>'
    ],
    'label' => '<string>',
    'subaccount_ids' => [
        1
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.derive.xyz/v3/private/create_session_key"

	payload := strings.NewReader("{\n  \"expiry_sec\": 1,\n  \"nonce\": \"<string>\",\n  \"offchain_scopes\": [\n    \"<string>\"\n  ],\n  \"protocol_scopes\": [\n    \"<string>\"\n  ],\n  \"public_session_key\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"signature_expiry_sec\": 1,\n  \"signer\": \"<string>\",\n  \"wallet\": \"<string>\",\n  \"ip_whitelist\": [\n    \"<string>\"\n  ],\n  \"label\": \"<string>\",\n  \"subaccount_ids\": [\n    1\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.derive.xyz/v3/private/create_session_key")
  .header("Content-Type", "application/json")
  .body("{\n  \"expiry_sec\": 1,\n  \"nonce\": \"<string>\",\n  \"offchain_scopes\": [\n    \"<string>\"\n  ],\n  \"protocol_scopes\": [\n    \"<string>\"\n  ],\n  \"public_session_key\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"signature_expiry_sec\": 1,\n  \"signer\": \"<string>\",\n  \"wallet\": \"<string>\",\n  \"ip_whitelist\": [\n    \"<string>\"\n  ],\n  \"label\": \"<string>\",\n  \"subaccount_ids\": [\n    1\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.derive.xyz/v3/private/create_session_key")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expiry_sec\": 1,\n  \"nonce\": \"<string>\",\n  \"offchain_scopes\": [\n    \"<string>\"\n  ],\n  \"protocol_scopes\": [\n    \"<string>\"\n  ],\n  \"public_session_key\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"signature_expiry_sec\": 1,\n  \"signer\": \"<string>\",\n  \"wallet\": \"<string>\",\n  \"ip_whitelist\": [\n    \"<string>\"\n  ],\n  \"label\": \"<string>\",\n  \"subaccount_ids\": [\n    1\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "expiry_sec": 1,
  "ip_whitelist": [
    "<string>"
  ],
  "offchain_scopes": [
    "<string>"
  ],
  "protocol_scopes": [
    "<string>"
  ],
  "public_session_key": "<string>",
  "subaccount_ids": [
    1
  ],
  "label": "<string>"
}

HTTP & WS Methods

WS-only Methods

WS Subscriptions

Register a scoped session key

Body

Response