PhoenixPerpetualsDocs API v1
Get an API key

Working with the API

Conventions⁠.

What every call has in common: hosts, keys, JSON, decimal strings, times, ids, request ids and caching.

View as Markdown

On this page
  1. Hosts and keys
  2. JSON in, JSON out
  3. Numbers, times and ids
  4. Request ids
  5. Caching
  6. Everything in the spec

The API is one set of rules applied everywhere. Learn them once and every endpoint reads the same.

Hosts and keys#

EnvironmentRESTAccount stream
Livehttps://api.phoenixperpsfunding.com/v1wss://api.phoenixperpsfunding.com/v1/stream
Sandboxhttps://sandbox-api.phoenixperpsfunding.com/v1wss://sandbox-api.phoenixperpsfunding.com/v1/stream

Market data is one host for both: wss://stream.phoenixperpsfunding.com/v1/market-data.

Send your key as Authorization: Bearer <key>. A key belongs to one environment, and its prefix says which: ppk_live_ or ppk_test_. A key on the other environment's host is refused with wrong_environment. A few calls need no key at all: GET /v1, GET /v1/status, GET /v1/limits, GET /v1/openapi.json and the markets.

JSON in, JSON out#

  • A body is JSON with Content-Type: application/json, at most 16 KiB and 8 levels deep.
  • Field names are snake_case. A field or query parameter the call does not know is refused with unknown_field, every one of them listed in details, so a typo never passes silently.
  • A single object answers as { "data": { ... } }, a list as { "data": [ ... ], "has_more", "next_cursor", "as_of" } (see Pagination).

Numbers, times and ids#

  • Prices, sizes and money are decimal strings: "62500.00", "0.010". You may send numbers, but strings never lose a digit to floating point, so the SDKs always send strings. Read them as decimals, never compare them as text: an answer may drop trailing zeros ("0.01" is "0.010"), never a digit that matters. Counts (minutes, seconds, ticks, rungs) are numbers.
  • Percent fields (..._pct, percent) are in percent: "1.5" means 1.5%.
  • Times are Unix milliseconds, as integers: 1791460800123. The trading day runs from midnight to midnight, New York time.
  • Markets are named by the asset and USD: BTC-USD. A market's price is quoted as its name says: EUR-USD (EUR/USD) in dollars per euro, but JPY-USD (USD/JPY) in yen per dollar, CAD-USD (USD/CAD) in Canadian dollars per dollar and CHF-USD (USD/CHF) in Swiss francs per dollar, as the currency market quotes them.
  • Accounts are named by their account number in every path: /v1/accounts/SANDBOX-00042-001/orders.
  • Ids start with what they name: ord_ orders, pos_ positions, fil_ fills, stg_ strategies, evt_ events, dlv_ webhook deliveries, req_ requests. Treat them as opaque strings.

Request ids#

Every answer carries X-Request-Id: req_..., also inside every error as request_id. Quote it when you write to us: it finds your call in seconds. Send your own X-Client-Request-Id (up to 64 printable characters) and it comes back on the answer, to match calls in your logs.

Caching#

Every GET answers with an ETag. Send it back as If-None-Match (one tag or several, weak or strong, or *) and, if nothing changed, the answer is an empty 304, which is quicker to read. A list's as_of is not part of the tag: the same content is the same tag. The SDKs answer a 304 with nothing, not an error. Answers are never cached by anyone in between (Cache-Control: no-store).

Everything in the spec#

The whole API is described in an OpenAPI 3.1 document and the streams in an AsyncAPI 3.0 document. The SDKs, the reference pages and the command line are all built from them, so what they say is what the API does.

Guides, endpoints, fields and error codes.