Subaccounts
private/get_subaccount
Returns the complete portfolio for a single subaccount: its label, manager and risk-universe identifiers, margin type and liquidation status, aggregate valuation and margin figures (positions, collaterals, initial and maintenance margin, open-order margin) as decimal strings, plus the full lists of open orders, positions, and collateral balances. Margin, mark price, and Greek values are computed from live feed data at request time.
POST
/
private
/
get_subaccount
private/get_subaccount
curl --request POST \
--url https://api.derive.xyz/v3/private/get_subaccount \
--header 'Content-Type: application/json' \
--header 'X-DeriveSignature: <api-key>' \
--header 'X-DeriveTimestamp: <api-key>' \
--header 'X-DeriveWallet: <api-key>' \
--data '
{
"subaccount_id": 1
}
'import requests
url = "https://api.derive.xyz/v3/private/get_subaccount"
payload = { "subaccount_id": 1 }
headers = {
"X-DeriveWallet": "<api-key>",
"X-DeriveTimestamp": "<api-key>",
"X-DeriveSignature": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-DeriveWallet': '<api-key>',
'X-DeriveTimestamp': '<api-key>',
'X-DeriveSignature': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({subaccount_id: 1})
};
fetch('https://api.derive.xyz/v3/private/get_subaccount', 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/get_subaccount",
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([
'subaccount_id' => 1
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-DeriveSignature: <api-key>",
"X-DeriveTimestamp: <api-key>",
"X-DeriveWallet: <api-key>"
],
]);
$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/get_subaccount"
payload := strings.NewReader("{\n \"subaccount_id\": 1\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-DeriveWallet", "<api-key>")
req.Header.Add("X-DeriveTimestamp", "<api-key>")
req.Header.Add("X-DeriveSignature", "<api-key>")
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/get_subaccount")
.header("X-DeriveWallet", "<api-key>")
.header("X-DeriveTimestamp", "<api-key>")
.header("X-DeriveSignature", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"subaccount_id\": 1\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.derive.xyz/v3/private/get_subaccount")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-DeriveWallet"] = '<api-key>'
request["X-DeriveTimestamp"] = '<api-key>'
request["X-DeriveSignature"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"subaccount_id\": 1\n}"
response = http.request(request)
puts response.read_body{
"collaterals": [
{
"amount": "<string>",
"amount_step": "<string>",
"asset_name": "<string>",
"asset_type": "<string>",
"average_price": "<string>",
"average_price_excl_fees": "<string>",
"creation_timestamp": 123,
"cumulative_interest": "<string>",
"currency": "<string>",
"delta": "<string>",
"delta_currency": "<string>",
"initial_margin": "<string>",
"maintenance_margin": "<string>",
"mark_price": "<string>",
"mark_value": "<string>",
"open_orders_margin": "<string>",
"pending_interest": "<string>",
"realized_pnl": "<string>",
"realized_pnl_excl_fees": "<string>",
"total_fees": "<string>",
"unrealized_pnl": "<string>",
"unrealized_pnl_excl_fees": "<string>"
}
],
"collaterals_initial_margin": "<string>",
"collaterals_maintenance_margin": "<string>",
"collaterals_value": "<string>",
"currency": [
"<string>"
],
"failed_to_fetch": true,
"initial_margin": "<string>",
"is_under_liquidation": true,
"label": "<string>",
"maintenance_margin": "<string>",
"manager_id": 1,
"margin_type": "<string>",
"mm_credits": "<string>",
"open_orders": [
{
"amount": "<string>",
"average_price": "<string>",
"creation_timestamp": 123,
"direction": "buy",
"extra_fee": "<string>",
"filled_amount": "<string>",
"instrument_name": "<string>",
"is_transfer": true,
"last_update_timestamp": 123,
"limit_price": "<string>",
"max_fee": "<string>",
"mmp": true,
"nonce": "<string>",
"order_fee": "<string>",
"order_id": "<string>",
"order_status": "open",
"order_type": "limit",
"quote_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"replaced_order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"signature": "<string>",
"signature_expiry_sec": 123,
"signed_limit_price": "<string>",
"signer": "<string>",
"subaccount_id": 123,
"time_in_force": "gtc",
"trigger_price": "<string>",
"algo_duration_sec": 123,
"algo_num_slices": 123,
"algo_slices_completed": 123,
"algo_type": "twap",
"cancel_reason": "",
"label": "",
"trigger_price_type": "mark",
"trigger_reject_message": "<string>",
"trigger_type": "stoploss"
}
],
"open_orders_margin": "<string>",
"positions": [
{
"amount": "<string>",
"amount_step": "<string>",
"average_price": "<string>",
"average_price_excl_fees": "<string>",
"creation_timestamp": 123,
"cumulative_funding": "<string>",
"delta": "<string>",
"gamma": "<string>",
"index_price": "<string>",
"initial_margin": "<string>",
"instrument_name": "<string>",
"instrument_type": "option",
"maintenance_margin": "<string>",
"mark_price": "<string>",
"mark_value": "<string>",
"net_settlements": "<string>",
"open_orders_margin": "<string>",
"pending_funding": "<string>",
"realized_pnl": "<string>",
"realized_pnl_excl_fees": "<string>",
"theta": "<string>",
"total_fees": "<string>",
"unrealized_pnl": "<string>",
"unrealized_pnl_excl_fees": "<string>",
"vega": "<string>",
"leverage": "<string>",
"liquidation_price": "<string>"
}
],
"positions_initial_margin": "<string>",
"positions_maintenance_margin": "<string>",
"positions_value": "<string>",
"projected_margin_change": "<string>",
"risk_universe_id": 1,
"subaccount_id": 1,
"subaccount_value": "<string>",
"vault_deposit_holds": [
{
"amount": "<string>",
"asset_name": "<string>",
"currency": "<string>",
"vault_id": 1
}
]
}{
"error": {
"code": 123,
"message": "<string>",
"data": "<string>"
}
}Authorizations
The wallet the request acts for.
The current time in milliseconds, as a decimal string.
EIP-191 signature of the timestamp, by the wallet or one of its session keys.
Body
application/json
Required range:
x >= 0Response
Success
Show child attributes
Show child attributes
true if this subaccount's portfolio could not be loaded; such subaccounts are returned as placeholders by get_all_portfolios.
Required range:
x >= 0MM credit from universe loss-socialization events: the socialized USDC debit lands on cash in full, and debit × (1 − write_down) is added back to maintenance margin while the 15-minute write-down runs. Events this subaccount has not yet realized contribute their expected credit, with the current subaccount value standing in for the MtM at realization. Zero while under auction — the credit is cleared when liquidation starts.
Show child attributes
Show child attributes
Uses the manager's params, as initial_margin does, even for a subaccount with a delayed-liquidation override. Order checks use the override, so the two can differ. This is rare: an override usually loosens maintenance margin only, and this is an initial-margin figure.
Show child attributes
Show child attributes
Change in maintenance_margin a minute past the account's next option expiry, once the options expiring by then settle into cash at today's forward. maintenance_margin + projected_margin_change < 0 signals liquidation right after that expiry. Excludes open orders; "0" for an account without an unexpired option.
Required range:
x >= 0Required range:
x >= 0Show child attributes
Show child attributes
private/get_subaccount
curl --request POST \
--url https://api.derive.xyz/v3/private/get_subaccount \
--header 'Content-Type: application/json' \
--header 'X-DeriveSignature: <api-key>' \
--header 'X-DeriveTimestamp: <api-key>' \
--header 'X-DeriveWallet: <api-key>' \
--data '
{
"subaccount_id": 1
}
'import requests
url = "https://api.derive.xyz/v3/private/get_subaccount"
payload = { "subaccount_id": 1 }
headers = {
"X-DeriveWallet": "<api-key>",
"X-DeriveTimestamp": "<api-key>",
"X-DeriveSignature": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-DeriveWallet': '<api-key>',
'X-DeriveTimestamp': '<api-key>',
'X-DeriveSignature': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({subaccount_id: 1})
};
fetch('https://api.derive.xyz/v3/private/get_subaccount', 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/get_subaccount",
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([
'subaccount_id' => 1
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-DeriveSignature: <api-key>",
"X-DeriveTimestamp: <api-key>",
"X-DeriveWallet: <api-key>"
],
]);
$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/get_subaccount"
payload := strings.NewReader("{\n \"subaccount_id\": 1\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-DeriveWallet", "<api-key>")
req.Header.Add("X-DeriveTimestamp", "<api-key>")
req.Header.Add("X-DeriveSignature", "<api-key>")
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/get_subaccount")
.header("X-DeriveWallet", "<api-key>")
.header("X-DeriveTimestamp", "<api-key>")
.header("X-DeriveSignature", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"subaccount_id\": 1\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.derive.xyz/v3/private/get_subaccount")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-DeriveWallet"] = '<api-key>'
request["X-DeriveTimestamp"] = '<api-key>'
request["X-DeriveSignature"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"subaccount_id\": 1\n}"
response = http.request(request)
puts response.read_body{
"collaterals": [
{
"amount": "<string>",
"amount_step": "<string>",
"asset_name": "<string>",
"asset_type": "<string>",
"average_price": "<string>",
"average_price_excl_fees": "<string>",
"creation_timestamp": 123,
"cumulative_interest": "<string>",
"currency": "<string>",
"delta": "<string>",
"delta_currency": "<string>",
"initial_margin": "<string>",
"maintenance_margin": "<string>",
"mark_price": "<string>",
"mark_value": "<string>",
"open_orders_margin": "<string>",
"pending_interest": "<string>",
"realized_pnl": "<string>",
"realized_pnl_excl_fees": "<string>",
"total_fees": "<string>",
"unrealized_pnl": "<string>",
"unrealized_pnl_excl_fees": "<string>"
}
],
"collaterals_initial_margin": "<string>",
"collaterals_maintenance_margin": "<string>",
"collaterals_value": "<string>",
"currency": [
"<string>"
],
"failed_to_fetch": true,
"initial_margin": "<string>",
"is_under_liquidation": true,
"label": "<string>",
"maintenance_margin": "<string>",
"manager_id": 1,
"margin_type": "<string>",
"mm_credits": "<string>",
"open_orders": [
{
"amount": "<string>",
"average_price": "<string>",
"creation_timestamp": 123,
"direction": "buy",
"extra_fee": "<string>",
"filled_amount": "<string>",
"instrument_name": "<string>",
"is_transfer": true,
"last_update_timestamp": 123,
"limit_price": "<string>",
"max_fee": "<string>",
"mmp": true,
"nonce": "<string>",
"order_fee": "<string>",
"order_id": "<string>",
"order_status": "open",
"order_type": "limit",
"quote_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"replaced_order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"signature": "<string>",
"signature_expiry_sec": 123,
"signed_limit_price": "<string>",
"signer": "<string>",
"subaccount_id": 123,
"time_in_force": "gtc",
"trigger_price": "<string>",
"algo_duration_sec": 123,
"algo_num_slices": 123,
"algo_slices_completed": 123,
"algo_type": "twap",
"cancel_reason": "",
"label": "",
"trigger_price_type": "mark",
"trigger_reject_message": "<string>",
"trigger_type": "stoploss"
}
],
"open_orders_margin": "<string>",
"positions": [
{
"amount": "<string>",
"amount_step": "<string>",
"average_price": "<string>",
"average_price_excl_fees": "<string>",
"creation_timestamp": 123,
"cumulative_funding": "<string>",
"delta": "<string>",
"gamma": "<string>",
"index_price": "<string>",
"initial_margin": "<string>",
"instrument_name": "<string>",
"instrument_type": "option",
"maintenance_margin": "<string>",
"mark_price": "<string>",
"mark_value": "<string>",
"net_settlements": "<string>",
"open_orders_margin": "<string>",
"pending_funding": "<string>",
"realized_pnl": "<string>",
"realized_pnl_excl_fees": "<string>",
"theta": "<string>",
"total_fees": "<string>",
"unrealized_pnl": "<string>",
"unrealized_pnl_excl_fees": "<string>",
"vega": "<string>",
"leverage": "<string>",
"liquidation_price": "<string>"
}
],
"positions_initial_margin": "<string>",
"positions_maintenance_margin": "<string>",
"positions_value": "<string>",
"projected_margin_change": "<string>",
"risk_universe_id": 1,
"subaccount_id": 1,
"subaccount_value": "<string>",
"vault_deposit_holds": [
{
"amount": "<string>",
"asset_name": "<string>",
"currency": "<string>",
"vault_id": 1
}
]
}{
"error": {
"code": 123,
"message": "<string>",
"data": "<string>"
}
}