PhoenixPerpetualsDocs API v1
Get an API key

API reference ยท Positions

GET/v1/accounts/{account_id}/positions

List open positions⁠.

Read

Every open position, valued at the market price, with its liquidation and breach prices and the exits that protect it. The list is complete or the call fails: it is never partial.

Path parameters#

Query parameters#

  • marketstring

    Only this market.

Responses#

200OK
  • idstringrequired

    This position, while it stays open on the same side.

  • marketstringrequired

    A market id: the asset and USD.

  • sidestringrequired

    Long or short.

    One oflongshort

  • sizedecimal stringrequired

    The size, in the base asset.

  • entry_pricedecimal string or nullrequired

    The average entry price.

  • mark_pricedecimal string or nullrequired

    The market price it is valued at.

  • notionaldecimal string or nullrequired

    Its value at that price.

  • unrealized_pnldecimal string or nullrequired

    Its open P&L.

  • leverageintegerrequired

    Its leverage.

  • margin_modestringrequired

    Its margin mode.

    One ofisolatedcross

  • initial_margindecimal string or nullrequired

    The margin it took at entry.

  • added_margindecimal string or nullrequired

    Margin you added to it.

  • margindecimal string or nullrequired

    What it holds of the balance.

  • liquidationobject or nullrequired
    Show 3 fields
    • pricedecimal string or nullrequired

      The price at which it is liquidated; null when there is none or it depends on several positions.

    • distance_pctdecimal string or nullrequired

      How far the market price is from it, in percent.

    • account_widebooleanrequired

      Cross margin on several markets: no single price, every one of them moves it.

  • breach_pricesobjectrequired
    Show 2 fields
    • daily_lossdecimal string or nullrequired

      The price at which this position alone would breach the daily loss limit.

    • max_drawdowndecimal string or nullrequired

      The price at which it alone would breach the max drawdown.

  • exitsobjectrequired
    Show 2 fields
    • take_profitarray of ExitLegrequired

      Limit orders on the closing side.

      Show 4 fields
      • order_idstringrequired

        The working order.

      • typestringrequired

        The order's type.

        One ofmarketlimitstop_marketstop_limittake_markettake_limit

      • pricedecimal string or nullrequired

        Its trigger or limit price.

      • sizedecimal string or nullrequired

        Its size.

    • stop_lossarray of ExitLegrequired

      Stop orders on the closing side.

      Show 4 fields
      • order_idstringrequired

        The working order.

      • typestringrequired

        The order's type.

        One ofmarketlimitstop_marketstop_limittake_markettake_limit

      • pricedecimal string or nullrequired

        Its trigger or limit price.

      • sizedecimal string or nullrequired

        Its size.

  • protectedbooleanrequired

    At least one stop loss rests on it.

  • opened_atinteger, Unix ms or nullrequired

    When it opened.

400A query or path parameter is out of range or the wrong kind.
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_parameter",
    "message": "A parameter has a value this route does not take.",
    "request_id": "req_0f9c2a7d8e1b4c6a9f3e5d7b1a2c4e6f",
    "retryable": false,
    "doc_url": "https://docs.phoenixperpsfunding.com/reference/errors#invalid_parameter"
  }
}
401The request has no Authorization header.
{
  "error": {
    "type": "authentication",
    "code": "missing_api_key",
    "message": "No API key: send it as Authorization: Bearer <key>.",
    "request_id": "req_0f9c2a7d8e1b4c6a9f3e5d7b1a2c4e6f",
    "retryable": false,
    "doc_url": "https://docs.phoenixperpsfunding.com/reference/errors#missing_api_key"
  }
}
403The key only works from the addresses you listed.
{
  "error": {
    "type": "permission",
    "code": "ip_not_allowed",
    "message": "This address is not on the key's allowlist.",
    "request_id": "req_0f9c2a7d8e1b4c6a9f3e5d7b1a2c4e6f",
    "retryable": false,
    "doc_url": "https://docs.phoenixperpsfunding.com/reference/errors#ip_not_allowed"
  }
}
404The account does not exist in this environment, or the key does not reach it.
{
  "error": {
    "type": "not_found",
    "code": "account_not_found",
    "message": "No account with that id is reachable with this key.",
    "request_id": "req_0f9c2a7d8e1b4c6a9f3e5d7b1a2c4e6f",
    "retryable": false,
    "doc_url": "https://docs.phoenixperpsfunding.com/reference/errors#account_not_found"
  }
}
409The account exists but is not open on the trading engine yet.
{
  "error": {
    "type": "conflict",
    "code": "account_not_ready",
    "message": "This account is still being opened.",
    "request_id": "req_0f9c2a7d8e1b4c6a9f3e5d7b1a2c4e6f",
    "retryable": true,
    "doc_url": "https://docs.phoenixperpsfunding.com/reference/errors#account_not_ready"
  }
}
429A request budget is used up (details.scope says which).
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limited",
    "message": "Too many requests: slow down.",
    "request_id": "req_0f9c2a7d8e1b4c6a9f3e5d7b1a2c4e6f",
    "retryable": true,
    "doc_url": "https://docs.phoenixperpsfunding.com/reference/errors#rate_limited"
  }
}
500An error we did not expect.
{
  "error": {
    "type": "server",
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_0f9c2a7d8e1b4c6a9f3e5d7b1a2c4e6f",
    "retryable": true,
    "doc_url": "https://docs.phoenixperpsfunding.com/reference/errors#internal_error"
  }
}
503The trading engine did not give a complete answer in time; nothing partial is returned.
{
  "error": {
    "type": "engine",
    "code": "state_unavailable",
    "message": "The account's figures cannot be read right now.",
    "request_id": "req_0f9c2a7d8e1b4c6a9f3e5d7b1a2c4e6f",
    "retryable": true,
    "doc_url": "https://docs.phoenixperpsfunding.com/reference/errors#state_unavailable"
  }
}

Errors#

Codes this endpoint can return. Match on the code, never on the message.

Guides, endpoints, fields and error codes.