# Data Types and Formats

## Numbers

The Sway Charts APIs expect (and return) numeric values formatted according to W3C XML schema rules for “double” and “integer” types (see [double](http://www.w3.org/TR/xmlschema-2/#double) and [integer](http://www.w3.org/TR/xmlschema-2/#integer)). The format is portable and country-independent. Dot (“.”) is used as a decimal separator; other separators (such as thousands) are not supported. Samples are: `123.456`, `+1234.456`, `-1234.456`, `-.456`, `123`, `-1E4`, `+INF`.

## Booleans

Boolean values are encoded as "true" or "false" strings. Absence of value (where appropriate) is interpreted as "false".

## Times and Dates

All times and dates in the API are encoded according to [RFC 3339](http://www.ietf.org/rfc/rfc3339.txt). This is a standard convention which is supported by most of the programming languages and frameworks.

RFC 3339-formatted dates and times have the following characteristics:

* This format is human readable.
* Two values can be compared using lexicographical comparison (i.e. sort values as strings)

Times and dates are either in UTC coordinated time or include timezone offset information.

The following formats are supported:

| Format Sample           | When used                                                                               |
| ----------------------- | --------------------------------------------------------------------------------------- |
| 2013-01-24T23:05:08.52Z | UTC timestamp with milliseconds precision used everywhere when a timestamp is expected. |
| 2013-01-24Z             | UTC date, used everywhere when a date is expected.                                      |
| Monday, 23:00:00Z       | UTC week date, used everywhere when a week-relative date is expected.                   |
| 23:05:08.52Z            | UTC time                                                                                |
| 01:05:08                | Time interval                                                                           |
| 1464264688310           | UNIX milliseconds since epoch                                                           |

## Currencies

Currency information is encoded according to [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217). This is an international standard which specifies three-letter currency codes.

## Languages

Language information is encoded according to BCP 47 (<http://tools.ietf.org/html/bcp47>). This is a document which concatenates two RFCs (5646 and 5645) and defines values of language tags to be used. Examples include `en` for English, `en-CA` for Canadian English, and `ja-JP` for Japanese as used in Japan.

## Client-originated Identifiers

The system allows clients to submit arbitrary identifiers during trading (so that the client can distinguish orders on its side). Client-originated identifiers can comprise any latin alphanumeric characters (A..Z,a..z,0..9) and any of the following special characters:

`~ , . - _ / \ : ; ! @ ‘ “ # $ % ^ & ? * ( ) [ ] = + \`

Length of a client-originated identifier should not exceed 64 characters.

Identifiers are case-sensitive (so that `Aa` and `AA` are two different identifiers).

The API rejects requests if an identifier contains any characters other than listed above or its length exceeds 64 characters.

Client-originated identifiers must be URL-encoded when used in queries (see <https://en.wikipedia.org/wiki/Percent-encoding>).

## Account Code

Accounts in the system are addressed with a two-component account code that uniquely corresponds to a single account in the system. Account code is assigned by the system and is of `clearing:account` format (two strings separated with a colon).

Account code should be URL-encoded when used in HTTP queries (see <https://en.wikipedia.org/wiki/Percent-encoding>).

## Order Statuses

An order can be in one of the following statuses:

| Status        | Details                                                                                                                     |
| ------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **ACCEPTED**  | Order has been accepted by the system                                                                                       |
| **WORKING**   | An order is working in the system: either pending execution or (in case of limit or stop order) waiting for a trigger quote |
| **CANCELED**  | Order has been cancelled in its entirety. This is a final state.                                                            |
| **COMPLETED** | Order has been filled (either completely or partially). This is a final state.                                              |
| **EXPIRED**   | Order has been expired. This is a final state.                                                                              |
| **REJECTED**  | Order has been rejected. This is a final state.                                                                             |