PhoenixPerpetualsDocs API v1
Get an API key

API reference ยท Orders

POST/v1/accounts/{account_id}/orders/test

Preview an order⁠.

Read

What an order would do now, sent nowhere: whether it would fill, rest or be refused (and why), its price, fee, margin, the position after it and the room under the exposure cap. Any key may call it.

Path parameters#

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#

200OK
  • resultstringrequired

    What the order would do now: fill at once, rest, or be refused (reject says why).

    One ofwould_fillwould_restwould_reject

  • rejectobject or nullrequired
    Show 3 fields
    • codestringrequired

      The error code it would get.

    • messagestring or nullrequired

      What it means.

    • detailsobject

      More about it.

  • marketstringrequired

    A market id: the asset and USD.

  • sidestringrequired

    The order's side.

    One ofbuysell

  • typestringrequired

    The order's type.

    One ofmarketlimitstop_marketstop_limit

  • sizedecimal string or nullrequired

    Its size (after a notional_usd is rounded to the size step).

  • executionobject or nullrequired
    Show 3 fields
    • marketablebooleanrequired

      It would fill at once.

    • expected_pricedecimal stringrequired

      The price it would fill at (at once) or rest at.

    • worst_pricedecimal string or nullrequired

      A market order's worst price.

  • notionaldecimal string or nullrequired

    Its value in USD.

  • feedecimal string or nullrequired

    The fee its fill would pay.

  • marginobject or nullrequired
    Show 5 fields
    • modestringrequired

      The margin mode the position would use.

      One ofisolatedcross

    • leverageintegerrequired

      The leverage it would use.

    • requireddecimal stringrequired

      The margin the order needs.

    • available_beforedecimal string or nullrequired

      The margin available now.

    • available_afterdecimal string or nullrequired

      What would remain available.

  • position_afterobject or nullrequired
    Show 3 fields
    • sizedecimal stringrequired

      The position's size after the fill.

    • sidestring or nullrequired

      Its side; null when flat.

      One oflongshort

    • average_pricedecimal string or nullrequired

      Its average price.

  • exposureobject or nullrequired
    Show 3 fields
    • capdecimal stringrequired

      The market's exposure cap across your accounts of this product.

    • open_beforedecimal stringrequired

      Your open value on the market now.

    • room_afterdecimal stringrequired

      What would remain under the cap.

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"
  }
}
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.