PhoenixPerpetualsDocs API v1
Get an API key

API reference ยท Exits and strategies

POST/v1/accounts/{account_id}/strategies

Create a strategy⁠.

Read and tradeIdempotency-Key

Starts a strategy on the account. trailing_stop and break_even change the position's exits (the answer is the exits strategy). The programs (oco, twap, vwap, scaled, chase, conditional) place orders for you: each one is checked as an order you place yourself, and listed under the strategy. A conditional waits (status waiting, nothing on the engine) until its price is reached, then sends its order (strategy.triggered).

Path parameters#

Headers#

  • Idempotency-Keystringrequired

    A unique value per action: a retry with the same value never does it twice.

Request body#

  • typestringrequired

    trailing_stop: a stop-loss that follows the price. break_even: the stop-losses move to the entry once the price has gone your way far enough. oco: two orders, the first fill cancels the other. twap, vwap: an order in market slices over time (vwap sized by yesterday's volume over the same hours). scaled: a ladder of limits. chase: a limit that follows the bid or ask. conditional: an order sent once a price is reached, on this market (a buy when the price falls to trigger_price, a sell when it rises) or on another one (trigger_market).

    One oftrailing_stopbreak_evenocotwapvwapscaledchaseconditional

  • marketstringrequired

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

  • sidestring

    The order's side.

    One ofbuysell

  • sizedecimal string

    trailing_stop: its size (absent: what the stop-losses leave of the position). twap, vwap, scaled, chase, conditional: the whole size.

  • distancedecimal string

    trailing_stop: how far behind the best price (or percent).

  • percentdecimal string

    trailing_stop: how far behind, in percent of the best price.

  • activation_pricedecimal string

    trailing_stop: start once the price reaches this (until then, initial_stop_price rests, or nothing).

  • initial_stop_pricedecimal string

    trailing_stop: where the stop rests until the trail moves it (absent: from the price now).

  • trailing_stop: cancel the position's other stop-losses first.

  • trigger_distancedecimal string

    break_even: how far from the entry the price must go.

  • trigger_percentdecimal string

    break_even: the same, in percent of the entry.

  • trigger_pricedecimal string

    break_even: or once the price reaches this. conditional: the level that sends the order (the trigger market's price; its tick).

  • conditional: the market whose price is watched (absent: this market). Any market we list.

  • conditional, with another trigger_market: send the order once it trades at or above trigger_price, or at or below it. On this market it is set by the side and not given.

    One ofabovebelow

  • conditional: the order it sends (default market).

    One ofmarketlimit

  • limit_pricedecimal string

    conditional: the limit of its order, with order_type limit.

  • expires_atinteger, Unix ms

    conditional: until when it waits for its price (default and longest: the gtd maximum, see GET /v1/limits). Its order, once sent, stands on its own.

  • break_even: ticks beyond the entry, on the profit side. chase: ticks behind the bid (buy) or ask (sell).

  • ordersarray of object

    oco: the two orders.

    Show 7 fields
    • sidestringrequired

      The order's side.

      One ofbuysell

    • typestringrequired

      Two orders that rest.

      One oflimitstop_marketstop_limit

    • sizedecimal stringrequired

      Its size.

    • limit_pricedecimal string

      Its limit price.

    • stop_pricedecimal string

      Its stop price.

    • post_onlyboolean

      Refused if it would fill at once.

    • It may only reduce your position.

  • exitsOrderExits

    Exits placed when the order fills: the stop-loss for the filled size first, then the take-profits. From then on they are the position's exits. An empty object removes them.

    Show 2 fields
    • take_profitarray of object

      Limit orders on the profit side, each at price, or at distance or percent from the fill.

      Show 4 fields
      • pricedecimal string

        An exact price.

      • distancedecimal string

        A price difference from the fill price.

      • percentdecimal string

        A percent of the fill price.

      • size_pctdecimal string

        Its share of the filled size, in percent (absent: the take-profits split it evenly).

    • stop_lossobject or null

      A stop on the loss side, at price, or at distance or percent from the fill; it may trail and move to break-even (as in a position's exits).

      Show 7 fields
      • pricedecimal string

        An exact price.

      • distancedecimal string

        A price difference from the fill price.

      • percentdecimal string

        A percent of the fill price.

      • typestring

        The stop's type (default stop_market).

        One ofstop_marketstop_limit

      • stop_limit: how many ticks past the stop its limit sits.

      • trailobject

        As a position's exits take it: { distance } or { percent }, with activation_price to start only once the price reaches 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.

      • As a position's exits take it: one of trigger_distance, trigger_percent, trigger_price, and offset_ticks.

        Show 4 fields
  • twap, vwap: how long the schedule runs (bounds in the runner settings, see GET /v1/limits).

  • twap, vwap: time between slices; at most half the duration. Default: 60 (within those bounds).

  • randomizeboolean

    twap, vwap: vary each slice's time and size a little (the sizes still add up to size).

  • twap, vwap, scaled, chase, conditional: only reduce your position (a twap ends when the position is closed).

  • max_pricedecimal string

    twap, vwap (buy): slices wait while the price is above this. chase (buy): its cap.

  • min_pricedecimal string

    twap, vwap (sell): slices wait while the price is below this. chase (sell): its floor.

  • max_slippage_pctdecimal string

    twap, vwap: each slice's slippage budget, in percent. conditional: its market order's.

  • start_pricedecimal string

    scaled: the first rung.

  • end_pricedecimal string

    scaled: the last rung.

  • rungsinteger

    scaled: how many limits (at most the runner setting).

  • scaled: equal sizes, growing toward end_price, or shrinking.

    One offlatascendingdescending

  • post_onlyboolean

    scaled: each rung refused if it would fill at once.

  • scaled: one rung refused cancels the others.

  • scaled: rungs through the price may fill at once (refused otherwise, rung_would_fill).

  • chase: how long it follows the price.

  • on_expirystring

    chase: at max_minutes, cancel it, or send what is left at the market.

    One ofcancelmarket

  • chase: it may rest through the last price (it would then fill at once).

  • Your own id for the strategy (oco, twap, vwap, scaled, chase, conditional): unique in this environment.

Responses#

201Created
  • idstringrequired

    The strategy.

  • client_strategy_idstring or nullrequired

    Your own id for it.

  • account_idstringrequired

    The account number.

  • typestringrequired

    exits: a position's take-profit and stop-loss legs. bracket: an order with exits once it fills. oco: two orders, the first fill cancels the other. twap, vwap: an order in slices over time. scaled: a ladder of limits. chase: a limit that follows the price. conditional: an order sent once a price is reached.

    One ofexitsbracketocotwapvwapscaledchaseconditional

  • marketstringrequired

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

  • sidestring or nullrequired

    The side of its orders (exits: the closing side).

    One ofbuysell

  • statusstringrequired

    waiting: armed, nothing placed yet. working: running. completed: done as asked. canceled: you ended it. ended: it stopped for end_reason.

    One ofwaitingworkingcompletedcanceledended

  • end_reasonstring or nullrequired

    Why it stopped.

    One oftake_profitstop_lossfilledposition_closedposition_reversedcanceled_by_userexternalkey_revokedaccount_closedengine_restartchild_rejectedprice_boundexpired

  • paramsobjectrequired

    What it was created with.

  • progressobjectrequired

    How far it is (by type).

  • ordersarray of Orderrequired

    Every order it placed, oldest first.

    Show 26 fields
    • idstringrequired

      The order.

    • client_order_idstring or nullrequired

      Your own id for it, when it was placed through the API.

    • account_idstringrequired

      The account number.

    • marketstringrequired

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

    • sidestring or nullrequired

      The order's side; null for an order placed elsewhere before the API saw it.

      One ofbuysell

    • typestring or nullrequired

      The order's type.

      One ofmarketlimitstop_marketstop_limittake_markettake_limit

    • statusstringrequired

      unconfirmed: the engine has not confirmed its last state yet.

      One ofpendingworkingfilledcanceledrejectedexpiredunconfirmed

    • sizedecimal string or nullrequired

      The size, in the base asset.

    • filled_sizedecimal string or nullrequired

      How much filled.

    • limit_pricedecimal string or nullrequired

      Its limit price.

    • stop_pricedecimal string or nullrequired

      Its trigger price.

    • average_fill_pricedecimal string or nullrequired

      The average fill price.

    • feedecimal string or nullrequired

      The fee its fill paid.

    • reduce_onlyboolean or nullrequired

      It may only reduce a position; null when not known (placed elsewhere).

    • time_in_forcestringrequired

      How long it rests.

      One ofgtcgtdiocfok

    • expires_atinteger, Unix ms or nullrequired

      A gtd order: when it expires (it ends expired then); null otherwise.

    • post_onlyboolean or nullrequired

      It may only rest, never fill at once; null when not known (placed elsewhere).

    • sourcestringrequired

      Where it was placed: this API, an AI assistant (the MCP server), a trading platform, a strategy, a TradingView alert, or the system (a liquidation).

      One ofapimcpplatformstrategytradingviewsystem

    • strategy_idstring or nullrequired

      The strategy that placed it (source strategy).

    • exitsobject or nullrequired

      Exits attached to it (orders placed through the API).

    • cancel_reasonstring or nullrequired

      Why it was canceled.

      One ofusercancel_allflattenclose_allposition_closedposition_reversedclose_assistocoreplacedstrategykey_loss_stoprisk_rulesystem_restartexternal

    • rejectobject or nullrequired
      Show 2 fields
      • codestringrequired

        The error code.

      • messagestring or nullrequired

        What happened.

    • created_atinteger, Unix ms or nullrequired

      When it was placed.

    • filled_atinteger, Unix ms or nullrequired

      When it filled.

    • canceled_atinteger, Unix ms or nullrequired

      When it was canceled.

    • updated_atinteger, Unix ms or null

      Its latest change.

  • created_atinteger, Unix msrequired

    When it was created.

  • updated_atinteger, Unix msrequired

    Its latest change.

  • ended_atinteger, Unix ms or nullrequired

    When it stopped.

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.