PhoenixPerpetualsDocs API v1
Get an API key

API reference ยท Exits and strategies

PUT/v1/accounts/{account_id}/positions/{market}/exits

Change a position's exits⁠.

Read and trade

Places, changes and cancels take-profit and stop-loss legs together, against the state you read: when the position or a leg changed since, nothing is done (409 exits_changed, with the state now). The legs are reduce-only and never larger than the position.

Path parameters#

Request body#

  • expected_positionobject or nullrequired

    The position you saw: { side, size }, or null.

    Show 2 fields
    • sidestringrequired

      Long or short.

      One oflongshort

    • sizedecimal stringrequired

      Its size.

  • expected_exitsarray of objectrequired

    Every leg you saw (an empty list when there were none): if anything differs now, nothing is done and the answer is 409 exits_changed with the state now.

    Show 3 fields
    • idstringrequired

      A leg.

    • sizedecimal stringrequired

      Its size.

    • pricedecimal string or nullrequired

      Its price; null for a stop-loss that waits (as GET exits shows it).

  • operationsarray of objectrequired

    Applied in this order: cancels, changes, then new legs (stop-losses first). An engine refusal stops the batch: 422 exit_operation_failed says what each operation did.

    Show 10 fields
    • opstringrequired

      What to do.

      One ofplacemodifycancel

    • idstring

      modify, cancel: the leg.

    • groupstring

      place: the group of the new leg.

      One oftake_profitstop_loss

    • typestring

      place: limit for a take-profit (the default); stop_market (the default) or stop_limit for a stop-loss.

      One oflimitstop_marketstop_limit

    • pricedecimal string

      The take-profit price, or the stop price.

    • limit_pricedecimal string

      The limit of a stop_limit leg.

    • sizedecimal string

      The size; absent on a place: what the group leaves of the position.

    • trailobject or null

      A stop-loss that follows the price: { distance } (a price difference) or { percent }, with activation_price to start only once the price reaches it. Without a price and an activation price it starts from the price now. null removes it.

      Show 3 fields
      • distancedecimal string

        How far behind the best price.

      • percentdecimal string

        How far behind, in percent of the best price.

      • activation_pricedecimal string

        Start once the price reaches this.

    • break_evenobject or null

      Move the stop-loss to the entry price (plus offset_ticks) once the price has gone your way by trigger_distance, trigger_percent or to trigger_price. Without a price, the stop is placed only then. null removes it.

      Show 4 fields
    • cleararray of string

      modify: the settings to remove from a stop-loss (the same as sending them null).

  • The legs grow with the position (default true).

Responses#

200OK
  • account_idstringrequired

    The account number.

  • marketstringrequired

    A market id: the asset and USD; an option adds its venue or hours after a dot.

  • strategy_idstring or nullrequired

    The strategy that keeps these exits (type exits); null when there are none.

  • positionobject or nullrequired

    The open position; null when flat.

    Show 2 fields
    • sidestringrequired

      Long or short.

      One oflongshort

    • sizedecimal stringrequired

      Its size.

  • take_profitarray of ExitsLegrequired

    The take-profit legs: together at most the position.

    Show 9 fields
    • idstringrequired

      The leg: an order of this API, also listed under the account's orders.

    • groupstringrequired

      take_profit: a limit on the profit side. stop_loss: a stop on the loss side.

      One oftake_profitstop_loss

    • typestringrequired

      take_profit legs are limits; stop_loss legs are stop_market or stop_limit.

      One oflimitstop_marketstop_limit

    • statusstringrequired

      The order's status; waiting: a stop-loss not placed yet (it waits for its activation price or its break-even).

      One ofpendingworkingfilledcanceledrejectedexpiredunconfirmedwaiting

    • sizedecimal stringrequired

      Its size.

    • pricedecimal string or nullrequired

      The take-profit price, or the stop price.

    • limit_pricedecimal string or nullrequired

      The limit of a stop_limit leg.

    • trailobject or nullrequired

      A trailing stop-loss: how it follows the price.

      Show 5 fields
      • distancedecimal string or nullrequired

        How far behind the best price (or null: percent).

      • percentdecimal string or nullrequired

        How far behind, in percent of the best price (or null: distance).

      • activation_pricedecimal string or nullrequired

        It starts once the price reaches this; null: from the start.

      • activebooleanrequired

        It follows the price now (its activation price was reached, or it had none).

      • best_pricedecimal string or nullrequired

        The best price since it started, which the stop follows.

    • break_evenobject or nullrequired

      A stop-loss moved to the entry price once the price has gone your way far enough.

      Show 5 fields
      • trigger_distancedecimal string or nullrequired

        How far from the entry the price must go (or null: another trigger).

      • trigger_percentdecimal string or nullrequired

        The same, in percent of the entry.

      • trigger_pricedecimal string or nullrequired

        Or once the price reaches this.

      • offset_ticksintegerrequired

        Ticks beyond the entry, on the profit side.

      • donebooleanrequired

        The stop-loss was moved to the entry already.

  • stop_lossarray of ExitsLegrequired

    The stop-loss legs: together at most the position.

    Show 9 fields
    • idstringrequired

      The leg: an order of this API, also listed under the account's orders.

    • groupstringrequired

      take_profit: a limit on the profit side. stop_loss: a stop on the loss side.

      One oftake_profitstop_loss

    • typestringrequired

      take_profit legs are limits; stop_loss legs are stop_market or stop_limit.

      One oflimitstop_marketstop_limit

    • statusstringrequired

      The order's status; waiting: a stop-loss not placed yet (it waits for its activation price or its break-even).

      One ofpendingworkingfilledcanceledrejectedexpiredunconfirmedwaiting

    • sizedecimal stringrequired

      Its size.

    • pricedecimal string or nullrequired

      The take-profit price, or the stop price.

    • limit_pricedecimal string or nullrequired

      The limit of a stop_limit leg.

    • trailobject or nullrequired

      A trailing stop-loss: how it follows the price.

      Show 5 fields
      • distancedecimal string or nullrequired

        How far behind the best price (or null: percent).

      • percentdecimal string or nullrequired

        How far behind, in percent of the best price (or null: distance).

      • activation_pricedecimal string or nullrequired

        It starts once the price reaches this; null: from the start.

      • activebooleanrequired

        It follows the price now (its activation price was reached, or it had none).

      • best_pricedecimal string or nullrequired

        The best price since it started, which the stop follows.

    • break_evenobject or nullrequired

      A stop-loss moved to the entry price once the price has gone your way far enough.

      Show 5 fields
      • trigger_distancedecimal string or nullrequired

        How far from the entry the price must go (or null: another trigger).

      • trigger_percentdecimal string or nullrequired

        The same, in percent of the entry.

      • trigger_pricedecimal string or nullrequired

        Or once the price reaches this.

      • offset_ticksintegerrequired

        Ticks beyond the entry, on the profit side.

      • donebooleanrequired

        The stop-loss was moved to the entry already.

  • resize_with_positionbooleanrequired

    The legs grow with the position, keeping their share of it (rounded down to the size step).

400The request is malformed.
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "The request is not valid.",
    "request_id": "req_0f9c2a7d8e1b4c6a9f3e5d7b1a2c4e6f",
    "retryable": false,
    "doc_url": "https://docs.phoenixperpsfunding.com/reference/errors#invalid_request"
  }
}
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"
  }
}
422The account passed, failed, or was closed (details.reason).
{
  "error": {
    "type": "rule_rejection",
    "code": "account_not_tradable",
    "message": "This account cannot trade.",
    "request_id": "req_0f9c2a7d8e1b4c6a9f3e5d7b1a2c4e6f",
    "retryable": false,
    "doc_url": "https://docs.phoenixperpsfunding.com/reference/errors#account_not_tradable"
  }
}
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.