# Conventions

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

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

## Hosts and keys

| Environment | REST | Account stream |
|---|---|---|
| Live | `https://api.phoenixperpsfunding.com/v1` | `wss://api.phoenixperpsfunding.com/v1/stream` |
| Sandbox | `https://sandbox-api.phoenixperpsfunding.com/v1` | `wss://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](/guides/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](https://docs.phoenixperpsfunding.com/openapi.json) and the streams in an [AsyncAPI 3.0 document](https://docs.phoenixperpsfunding.com/asyncapi.json). The SDKs, the reference pages and the command line are all built from them, so what they say is what the API does.
