PhoenixPerpetualsDocs API v1
Get an API key

API reference ยท Orders

POST/v1/accounts/{account_id}/orders

Place an order⁠.

Read and tradeIdempotency-Key

Places an order on the account. A market order waits a moment for its fill. When the engine's answer is lost on the way, the answer is 202 with status unconfirmed: read the order again (Location) rather than placing it again.

Path parameters#

Headers#

  • Idempotency-Keystringrequired

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

Request body#

  • marketstringrequired

    A market id: the asset and USD.

  • sidestringrequired

    The order's side.

    One ofbuysell

  • typestringrequired

    market: now, at the best price within your worst price. limit: at your price or better. stop_market: a market order once the last price reaches the stop. stop_limit: a limit once the last price reaches the stop.

    One ofmarketlimitstop_marketstop_limit

  • sizedecimal string

    The size, in the base asset: a multiple of the market's size step. Give size or notional_usd.

  • notional_usddecimal string

    The size as a value in USD, rounded down to the size step.

  • limit_pricedecimal string

    The limit price (limit and stop_limit): a multiple of the tick size.

  • stop_pricedecimal string

    The trigger price (stop_market and stop_limit).

  • worst_pricedecimal string

    Market orders: the worst price you accept. Give worst_price or max_slippage_pct.

  • max_slippage_pctdecimal string

    Market orders: how far from the best price you accept, in percent (the default and bounds are in GET /v1/markets).

  • reduce_onlyboolean

    It may only reduce or close your position, never open or add to one.

  • post_onlyboolean

    Limit orders: refused if it would fill at once.

  • time_in_forcestring

    gtc: until canceled. gtd: until expires_at. ioc and fok: fill now or end (a fill is always the whole order). Default: ioc for market orders, gtc otherwise.

    One ofgtcgtdiocfok

  • expires_atinteger, Unix ms

    With gtd: when it ends.

  • client_order_idstring

    Your own id for the order: unique in this environment, 1 to 64 letters, digits and . _ : -

Responses#

201Created
  • 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.

  • 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

  • sourcestringrequired

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

    One ofapiplatformstrategytradingviewsystem

  • 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.

202Sent, but the engine's answer was lost on the way: read the order again (Location).
  • 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.

  • 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

  • sourcestringrequired

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

    One ofapiplatformstrategytradingviewsystem

  • 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.

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.