PhoenixPerpetualsDocs API v1
Get an API key

Your accounts

Accounts and risk⁠.

Your accounts, the rule each one trades under, live risk with the room left to every loss limit, and progress toward the target.

View as Markdown

On this page
  1. Your accounts
  2. The rule
  3. Live risk
  4. Progress

Everything your dashboard shows about an account, your code can read: the same figures, computed the same way, as fresh as the trading servers have them.

Your accounts#

GET /v1/accounts lists the accounts your key reaches: on the live host your evaluation and funded accounts, on the sandbox host your sandbox accounts. Each one is named by its account number, which every other path takes.

statusMeaning
pendingBeing opened: it trades in a moment
activeTrading
passedIt reached its objectives: no new trades
failedA limit was breached: no new trades
closed, suspendedEnded, or held by us

stage says where it is in the programme (evaluation, funded or sandbox), and payout_eligible whether a payout may be requested now.

The rule#

Each account trades under a rule, in account.rule and in GET .../trading-policy. Rules differ from one account to the next, so read them rather than assume them:

FieldWhat it holds
daily_lossThe most the account may lose in a trading day: amount, pct, what it is measured from (basis) and what happens when it is reached (on_breach: fail_account, flatten, or flatten_and_pause until the next day)
max_drawdownThe most it may fall from its reference: amount, pct, and how the reference moves (mode: static stays at the start; end_of_day and end_of_trade follow the highest balance; intraday_equity follows the highest equity)
weekly_lossA weekly limit, when the rule has one
profit_targetThe profit to reach, and whether positions must be closed when it is (requires_flat)
min_trading_days, min_calendar_daysThe days the account needs
consistencyThe most one day may bring
overnight_holding, weekend_holdingWhether positions may stay open overnight or over the weekend
inactivity_daysDays without a trade after which the account fails

The trading day runs from midnight to midnight, New York time. GET .../trading-policy also answers what decides whether an order goes through: slippage bounds, margin, order limits, the limits set on your key and its budgets.

Live risk#

GET /v1/accounts/{account_id}/risk is the account right now:

  • Money: balance (closed trades and fees), equity (with the open P&L at the market price), unrealized_pnl, pnl_today, realized_today, fees_today.
  • Margin and exposure: margin_used, margin_available, and exposure long, short and per market, with the effective leverage.
  • Each loss limit: daily_loss and max_drawdown, each with its limit, the equity at which it is breached (floor), the room left before it and how much of it is used (used_pct). The daily loss also says when it resets.
  • The target: profit_target with what remains, and trading_days with the count so far.
  • The nearest liquidation, with its distance in percent.
  • Warnings, most serious first: daily_loss_used, max_drawdown_used, liquidation_near, no_stop_loss, margin_used, order_without_position, each with its level (info, warning, critical). order_without_position (info) names a market where an order rests while you hold no position there: an entry that waits, or the exit of a position already closed, which would open a new one if it filled.
import { PhoenixPerps } from "@phoenixperps/sdk";

const client = new PhoenixPerps();
const risk = await client.accounts.risk("SANDBOX-00042-001");
console.log("equity", risk.equity);
if (risk.daily_loss) console.log("room to the daily loss limit", risk.daily_loss.room);
if (risk.max_drawdown) console.log("room to the max drawdown", risk.max_drawdown.room);
for (const w of risk.warnings) console.log(w.level, w.code);
risk = client.accounts.risk("SANDBOX-00042-001")
print("equity", risk["equity"])
if risk["daily_loss"]:
    print("room to the daily loss limit", risk["daily_loss"]["room"])
if risk["max_drawdown"]:
    print("room to the max drawdown", risk["max_drawdown"]["room"])
for w in risk["warnings"]:
    print(w["level"], w["code"])
risk, err := client.Accounts.Risk(ctx, "SANDBOX-00042-001")
if err != nil {
	log.Fatal(err)
}
fmt.Println("equity", risk.Equity)
if risk.DailyLoss != nil {
	fmt.Println("room to the daily loss limit", risk.DailyLoss.Room)
}
if risk.MaxDrawdown != nil {
	fmt.Println("room to the max drawdown", risk.MaxDrawdown.Room)
}
for _, w := range risk.Warnings {
	fmt.Println(w.Level, w.Code)
}
var risk = await client.Accounts.RiskAsync("SANDBOX-00042-001");
Console.WriteLine($"equity {risk.Equity}");
if (risk.DailyLoss is { } daily) Console.WriteLine($"room to the daily loss limit {daily.Room}");
if (risk.MaxDrawdown is { } drawdown) Console.WriteLine($"room to the max drawdown {drawdown.Room}");
foreach (var w in risk.Warnings)
    Console.WriteLine($"{w.Level} {w.Code}");
AccountRisk risk = client.accounts().risk("SANDBOX-00042-001");
System.out.println("equity " + risk.equity());
if (risk.dailyLoss() != null) System.out.println("room to the daily loss limit " + risk.dailyLoss().room());
if (risk.maxDrawdown() != null) System.out.println("room to the max drawdown " + risk.maxDrawdown().room());
for (Warning w : risk.warnings()) {
    System.out.println(w.level() + " " + w.code());
}
let risk = client.accounts().risk("SANDBOX-00042-001").await?;
println!("equity {}", risk.equity);
if let Some(daily) = &risk.daily_loss {
    println!("room to the daily loss limit {:?}", daily.room);
}
if let Some(drawdown) = &risk.max_drawdown {
    println!("room to the max drawdown {:?}", drawdown.room);
}
for w in &risk.warnings {
    println!("{:?} {:?}", w.level, w.code);
}
$risk = $client->accounts->risk('SANDBOX-00042-001');
echo 'equity ', $risk->equity, PHP_EOL;
if ($risk->dailyLoss !== null) echo 'room to the daily loss limit ', $risk->dailyLoss->room, PHP_EOL;
if ($risk->maxDrawdown !== null) echo 'room to the max drawdown ', $risk->maxDrawdown->room, PHP_EOL;
foreach ($risk->warnings as $w) {
    echo $w->level, ' ', $w->code, PHP_EOL;
}

To follow risk as it moves instead of asking, subscribe to the account stream with risk: true.

stale: true means some figures are older than usual because the trading servers were busy; as_of says when the oldest was read.

Progress#

GET .../progress puts each objective (the profit target, the trading days, the calendar days) and each loss limit side by side with where it stands, and, on a funded account, what may be paid out.

Guides, endpoints, fields and error codes.