Primitive Types

Both our REST and WebSocket APIs use standard JSON encoded objects, so they support all standard JSON primitives.

We represent higher-order fields, like prices, with these primitives. This page outlines how these higher-order fields are represented.

Dates

A date field will always be a number in the format of YYYYMMDD, e.g. 20240101 for January 1st, 2024.

Timestamps

A timestamp field will always be a number that represents the number of milliseconds since the Unix epoch. Generally, these fields are suffixed with a _at, e.g. created_at. You can use conversion sites to help you convert between Unix timestamps and human readable strings.

Prices

A price field will always be represented as a string, if the price field is not the result of a calculation. For example, when submitting an order, the limit price is represented as a string to prevent the loss of fidelity. Likewise, when returning an order to you, the API returns the limit price of an order as a string.

However, a price field that is the result of a calculation will be represented as a standard number primitive. For example, a field that represents fair-market-value for an instrument would be represented as a number.

Since calculations are done using floating-point arithmetic, preserving 100% fidelity on the wire isn't required, given that the calculations are approximations.

Quantities

A quantity field will always be represented as a string, if the quantity represents an amount that trades on a market. For example, when specifying the number of shares to buy in an order, the share amount is represented as a string. Or, when representing the amount of cash you have in your account, it will be represented as a string to prevent the loss of fidelity.

While this typically is always an integer value for basic U.S. equities and options, it's not universally true for all assets classes or scenarios, e.g. crypto and fractional shares. Therefore, to maximize forward compatibility, quantities are represented as a string.