ACE API Spec v3.0.0

This document provides specifications for connecting to the Archax Complete Ecosystem (ACE) API endpoints. We provide two APIs - HTTP REST and WebSockets. For detailed information about each API visit the REST API and WebSocket API sections.

Handling Decimal Place Values

Most responses provide an integer number for prices, quantities and amounts that need to be converted to a decimal value.

For example, if a set-order response has an execution with a price of 12345 and the trading pair for that order has a price decimal place value of 2 then the corrected price is 123.45. If the price decimal place value is 3 then the corrected price would be 12.345.

The same is true for quantity values where quantity decimal value is used to correct a quantity. So if a set-order response has an execution quantity of 123456 and a quantity decimal place value of 6 then the corrected quantity is 0.123456.

For amounts (found in transaction, balance and custody responses), the decimalValue field from the Asset endpoint (REST and Websocket) is used to correct the value. If a set balances response includes an available balance of 123456 and the decimalValue of the asset associated with that balance is 4 then the corrected balance would be 12.3456.

REST API

The Archax REST API allows developers to retrieve authentication tokens and instrument information. All resources are defined under the following URL:

https://ace-auth.archax.com/api/3.0

All responses from the REST API are wrapped inside this response wrapper

Sample Request

{
  "email": "user@archax.com",
  "password": "password"
}

200 Response

{
  "status": "OK",
  "data": {
    "status": "OK",
    "jwt": "valid-token",
    "mfa": false,
    "timestamp": "2021-05-25T04:21:38.057Z"
  },
  "timestamp": "2021-05-25T04:21:38.058Z"
}

401 Response

{
  "status": "ERROR",
  "error": [
    {
      "msg": "Email and password combination are incorrect"
    }
  ],
  "timestamp": "2021-06-07T06:39:21.413Z"
}

POST /login

An endpoint that allows developers to submit an email and a password in exchange for a JWT.

Request Schema

Name	Type	Required	Description
email	string	true	Email address registered in the system
password	string	true	Password registered with email address

Response Schema

Name	Type	Description
status	status	OK for success, ERROR otherwise
jwt	string	A JSON web token that expires after 30 minutes
mfa	bool	A flag indicating whether multi-factor authentication is enabled
timestamp	timestamp	The response timestamp

Renew-jwt

Request to

https://ace-auth.archax.com/api/3.0/renew-jwt

200 Response

{
  "status": "OK",
  "data": {
    "jwt": "valid-token"
  },
  "timestamp": "2021-05-25T04:21:38.058Z"
}

401 Response

{
  "status": "ERROR",
  "error": [
    {
      "msg": "Too many requests"
    }
  ],
  "timestamp": "2021-06-07T06:39:21.413Z"
}

POST /renew-jwt

An endpoint that provides an updated JWT. Old JWT must be included as bearer token.

Response Schema

Name	Type	Description
jwt	string	A JSON web token that expires after 30 minutes

Payment Provider details

Request to

https://ace-auth.archax.com/api/3.0/rest-gateway/account/fiat-account/1/regulated

200 Response

{
  "status": "OK",
  "data": {
    "accountId": 1,
    "accountName": "Archax Client Money C",
    "accountNumber": "00000058",
    "paymentProvider": {
      "address1": "4th Floor, Prologue Works",
      "address2": "25 Marsh Street",
      "address3": "Bristol, BS1 4AX",
      "name": "ClearBank Limited"
    },
    "sortCode": "04-05-78"
  },
  "timestamp": "2023-03-10T10:02:09.398Z"
}

401 Response

{
  "status": "ERROR",
  "error": [
    {
      "msg": "Fiat account is not available for currencyId 5"
    }
  ],
  "timestamp": "2023-03-10T10:04:57.392Z"
}

GET https://ace-auth.archax.com/api/3.0/rest-gateway/account/fiat-account/:currencyId/:regType

An endpoint that provides account details for use when depositing cash with Archax. Must include bearer token with JWT that has appropriate permissions.

Url path parameters

Name	Type	Description
currencyId	number	Asset id of cash to be deposited
regType	string	Indicates if payment is to CASS protected accounts (for regulated activity) or the non-CASS account (for unregulated activity). Value is either `regulated` or `unregulated`

Response Schema

Name	Type	Description
accountId	number	Internal identifier for Archax
accountName	string	Name to be used as beneficiary in payment
accountNumber	string	Account number to be used for beneficiary in payment
paymentProvider	Payment Provider	Beneficiary bank name and address
sortCode	string	Payment routing code for beneficiary bank. This field can include either a sort code, a bank identifier code or a FEDABA depending on the currency of the account

Payment Provider Schema

Name	Type	Description
name	string	Beneficiary bank name
address1	string	1st line of address for beneficiary bank
address2	string	2nd line of address for beneficiary bank
address3	string	3rd line of address for beneficiary bank

Asset Details

Request to

https://ace-auth.archax.com/api/3.0/rest-gateway/reporting/asset/6

200 Response

{
  "status": "OK",
  "data": {
    "id": 5,
    "name": "Apple Inc",
    "symbol": "APPa",
    "status": "active",
    "type": "security",
    "decimalValue": 0,
    "created": "2023-10-13T09:39:10.000Z",
    "updated": "2023-10-13T09:39:10.000Z",
    "meta": {
      "address": "Old Jewery",
      "approvalDate": "2020-09-02",
      "blockchainProtocol": "Ethereum",
      "bondBasePointSpread": "",
      "bondFixedRate": "",
      "bondIndex": "",
      "bondIdentifier": "",
      "bondMaturityDate": "",
      "bondName": "",
      "bondSeniority": "",
      "bondTermUnit": "",
      "bondTermValue": "",
      "bondTotalIssued": "",
      "bondType": "",
      "category": "Class A shares",
      "cfiCode": "ESVUFR",
      "contactInfo": "",
      "contractAddress": "0x23830c173a1b84D6d69A54dc2f4581e49eDF14Df",
      "currency": "USD",
      "envRating": "",
      "esgDescription": "",
      "esgLogo": "",
      "firstIssuanceDate": "2020-01-01",
      "firstTradeDate": "2023-04-04",
      "fullName": "Apple Inc",
      "governanceRating": "",
      "incorporationDate": "",
      "isin": "US0378331005",
      "issuanceSize": "",
      "lei": "HWUPKR0MPOU8FGXBT394",
      "mic": "ARCH",
      "nominalValueUnit": "",
      "platform": "Ethereum",
      "priceMultiplier": "",
      "relatedIsin": "",
      "requestDate": "2020-09-02",
      "settlementDate": "",
      "shareClass": "",
      "shareNumber": "10000",
      "shareNumberExceeding": "1000",
      "shortName": "Apple Inc",
      "socialMedia": "",
      "socialRating": "",
      "terminationDate": "2029-04-04",
      "tokeniser": "",
      "tradingVenueMic": "",
      "underlyingInstrumentId": "",
      "website": ""
    }
  },
  "timestamp": "2023-10-20T14:02:49.064Z"
}

401 Response

{
  "status": "ERROR",
  "error": [
    {
      "msg": "Asset not found"
    }
  ],
  "timestamp": "2021-06-07T06:39:21.413Z"
}

GET https://ace-auth.archax.com/api/3.0/rest-gateway/reporting/asset/:assetId

An endpoint that provides details of an asset. Must include bearer token with JWT that has appropriate permissions.

Url path parameters

Name	Type	Description
assetId	number	Unique identifier of the asset

Response Schema

Name	Type	Description
id	number	Unique identifier of the asset
name	string	Name of the asset
symbol	string	Ticker symbol of the asset
status	string	Current status of the asset with regards to trading
type	string	Asset type (can be `security`, `crypto` or `cash`)
decimalValue	number	Number of decimal places used by the system for the asset
created	string	Internal use only
updated	string	Internal use only
meta	Meta	Additional static data about the asset

Meta Schema

Name	Type	Description
address	string	Address of the issuer
approvalDate	string	Date and time the issuer has approved admission to trading or trading in its financial instruments on the Archax exchange
blockchainProtocol	string	Blockchain on which the asset was issued as a token or equivalent
bondBasePointSpread	string	Number of basis points above or below the index used to calculate accrued interest
bondFixedRate	string	The fixed rate percentage of a return on a debt instrument when held until maturity date expressed as a percentage (i.e. 7.0 means 7%)
bondIdentifier	string	ISIN of the index/benchmark used to set the floating rate of a return on a debt instrument
bondIndex	string	Alias name of the index/benchmark used to set the floating rate of a return on a debt instrument
bondMaturityDate	string	The maturity date of a debt instrument
bondName	string	Name of the index/benchmark used to set the floating rate of a return on a debt instrument
bondSeniority	string	Identifies the type of bond
bondTermUnit	string	The unit used for the term of the index or benchmark or a floating rate debt instrument (DAYS, WEEK, MNTH or YEAR)
bondTermValue	string	3 digit integer indicating the number of units of the term of the index or benchmark of a floating rate debt instrument
bondTotalIssued	string	Total issued nominal amount in monetary value (expressed in currency reported in currency field)
bondType	string	The type of bond: senior, debt, mezzanine, subordinated debt or junior debt
category	string	Category of the asset
cfiCode	string	The instrument classification expressed using the full (6 character) ISO 10962 CFI code that defines the type of instrument
contactInfo	string	Contact information of the issuer of the asset
contractAddress	string	Address on the blockchain of the smart contract that manages the asset
currency	string	Symbol of the currency in which the asset is priced for trading (default currency used for cryptocurrency market data)
envRating	string	Environmental rating provided as part of ESG rating
esgDescription	string	Details of the ESG rating provided
esgLogo	string	Logo of the provider of the ESG rating
firstIssuanceDate	string	Date on which a debt instrument was issued and began to accrue interest
firstTradeDate	string	Date and time of the admission to trading on the trading venue or the date and time when the instrument was first traded or an order/quote was first received by Archax exchange
fullName	string	Full name of the instrument as registered to the ISIN
governanceRating	string	Governance rating provided as part of ESG rating
incorporationDate	string	Date of incorporation of the issuer of the asset
isin	string	International securities identification number as provided by a national numbering agency
issuanceSize	string	Issuance size of the certificate expressed in Euros. Also used for bonds to show total bond size
lei	string	Legal entity identifier registered with the issuer of the asset
mic	string	Market identifier code of the exchange on which the asset is traded
nominalValueUnit	string	Nominal value of each unit of debt instrument as priced in the associated currency
platform	string	Internal use only
priceMultiplier	string	Not in use
relatedIsin	string	Not in use
requestDate	string	Date and time of the request for admission to trading on the trading venue
settlementDate	string	Date expressed in T+n value of when settlement occurs n days after a trade (Same Day (T) for most assets on Archax exchange)
shareClass	string	Unique identifier if there are different types of stock
shareNumber	string	For shares and depositary receipts: The total number of outstanding instruments. For ETFs: Number of units issued for trading
shareNumberExceeding	string	The total number of shares corresponding to holdings exceeding 5% of total voting rights of the issuer
shortName	string	Short name registered to the ISIN in accordance with ISO 18774 (Financial Instrument Short Name)
socialMedia	string	Links or handles on social media sites associated with the asset issuer
socialRating	string	Social rating provided as part of ESG rating
terminationDate	string	Date and time of when asset will cease to trade on Archax exchange
tokeniser	string	Entity that created the token smart contract used to issue the asset
tradingVenueMic	string	Will be deprecated
underlyingInstrumentId	string	Not in use
website	string	Website associated with the asset and/or issuer

Trading Pair Details

Request to

https://ace-auth.archax.com/api/3.0/rest-gateway/reporting/trading-pair/6

200 Response (without bearer token)

{
  "status": "OK",
  "data": {
    "tradingPairId": 6,
    "ticker": "BTCUSD",
    "baseAssetId": 6,
    "quoteAssetId": 2,
    "priceInCents": 0,
    "description": "BTC USD trading pair",
    "status": "trading",
    "priceDecimalPlaces": 2,
    "productId": 1,
    "externalId": 4
  },
  "timestamp": "2023-10-20T14:02:49.064Z"
}

200 Response (with bearer token)

{
  "status": "OK",
  "data": {
    "tradingPairId": 6,
    "ticker": "BTCUSD",
    "baseAssetId": 6,
    "quoteAssetId": 2,
    "priceInCents": 0,
    "description": "BTC USD trading pair",
    "status": "trading",
    "productId": 1,
    "priceDecimalPlaces": 2,
    "externalId": 4,
    "meta": {
      "initialPrice": "30000.00",
      "minimuOrderValue": "20.00",
      "tickSize": "0.01"
    }
  },
  "timestamp": "2023-10-20T14:02:49.064Z"
}

401 Response

{
  "status": "ERROR",
  "error": [
    {
      "msg": "Trading pair not found"
    }
  ],
  "timestamp": "2021-06-07T06:39:21.413Z"
}

GET https://ace-auth.archax.com/api/3.0/rest-gateway/reporting/trading-pair/:tradingPairId

An endpoint that provides details of an trading pair. Response depends on presence of bearer token with JWT that has appropriate permissions.

Url path parameters

Name	Type	Description
tradingPairId	number	Unique identifier of the trading pair

Response Schema

Name	Type	Description
tradingPairid	number	Unique identifier of the trading pair
ticker	string	Name of the asset
baseAssetId	number	Unique identifier of the asset for which prices are quoted
quoteAssetId	number	Unique identifier of the asset in which prices are quoted
priceInCents	number	Used to flag instruments priced in GBX (pennies), if `priceInCents = 1` and the quote asset is GBP then the price is in GBX
description	string	Description of the trading pair
status	string	Trading status can be `Pre-Live`, `Trading`, `Halted`, `Suspended` or `Terminated`
productId	number	Unique identifier for the product type subject to the fetch balance request. An endpoint will become available soon but until then 1 = `SME Growth Market` and 2 = `Alternative Trading Facility`
priceDecimalPlaces	number	Number of decimal places used by the system when accepting a price for the base asset of the trading pair
externalId	number	For internal use only
meta	Meta	Additional static data about the asset (only provided with bearer token with appropriate permissions)

Meta Schema

Name	Type	Description
initialPrice	string	For internal use only
minimumOrderValue	string	Smallest value allowed for an order ticket
tickSize	string	Smallest price variation allowed when submitting an order for the trading pair

Open Orders

Request to

https://ace-auth.archax.com/api/3.0/open-orders

200 Response

{
  "status": "OK",

  "data": [
    {
      "quantity": "1",
      "untradedQuantity": "1",
      "limitPrice": "27185",
      "created": "1681456445562335",
      "tradingPairId": 5,
      "executions": [],
      "id": "1681456445562335",
      "side": "sell",
      "userReference": "user_reference_1234"
    },
    {
      "quantity": "1",
      "untradedQuantity": "1",
      "limitPrice": "24185",
      "created": "1681456418146386",
      "tradingPairId": 5,
      "executions": [],
      "id": "1681456418146386",
      "side": "buy",
      "userReference": "user_reference_12345"
    }
  ],

  "timestamp": "2023-04-14T07:14:10.666Z"
}

GET /open-orders/:organisationId

An endpoint that returns a list of all open orders for the user’s organisation. JWT must be included as bearer token.

Url path parameters

Name	Type	Description
organisationId	number	Unique identifier of the client organisation subject to the open-orders query

Response Schema

Name	Type	Description
id	string	Unique order identifier
quantity	string	Order quantity without consideration of decimal places values (decimal places defined in `quantityDecimalPlaces` from Trading Pairs Schema)
untradedQuantity	string	Quantity of unfilled portion of order without consideration of decimal places values (decimal places defined in `quantityDecimalPlaces` from Trading Pairs Schema)
limitPrice	string	Order limit price without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)
created	string	Timestamp on when the trade was executed (µs)
tradingPairId	number	Unique identifier of the trading pair
executions	empty array	Not used
side	string	Order side, possible values: `buy`, `sell`
userReference	string	Value provided as `userReference` in original submission of order

Market History

Request to

https://ace-auth.archax.com/api/3.0/rest-gateway/core/market-history?tradingPairId=6&interval=5m&startDate=2023-11-28

200 Response

{
  "status": "OK",
  "data": [
    {
      "id": 1079,
      "tradingPairId": 6,
      "date": "2023-11-29T09:50:00.000Z",
      "open": "100000.000000000",
      "close": "99982.000000000",
      "high": "100000.000000000",
      "low": "99982.000000000",
      "volume": "1.044008000",
      "lastTradeId": 97693,
      "trades": 33,
      "firstTradeId": 97661,
      "rawVolume": 1044008
    },
    {
      "id": 1085,
      "tradingPairId": 6,
      "date": "2023-12-01T11:50:00.000Z",
      "open": "99982.000000000",
      "close": "99982.000000000",
      "high": "99982.000000000",
      "low": "99982.000000000",
      "volume": "23.000000000",
      "lastTradeId": 97926,
      "trades": 230,
      "firstTradeId": 97697,
      "rawVolume": 23000000
    }
  ],
  "timestamp": "2024-02-14T09:56:21.947Z"
}

GET /market-history?tradingPairId=:tradingPairId&interval=:interval&startDate=:startDate

An endpoint that returns a list of market data for a trading pair within the given start date and interval.

Url query parameters

Name	Type	Description
tradingPairId	number	Unique identifier of the trading pair
interval	string	Interval between market data (i.e. 30s, 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w, 1mo)
startDate	string	Date in yyyy-mm-dd format

Response Schema

Name	Type	Description
id	number	Unique identifier of the market data segment
tradingPairId	number	Unique identifier of the trading pair
date	string	Timestamp of the open of the market data segment
open	string	Price of the first trade within the market data segment
close	string	Price of the last trade within the market data segment
high	string	Highest trade price within the market data segment
low	string	Lowest trade price within the market data segment
volume	string	Total number of units traded during market data segment
lastTradeId	number	Unique identifier of the latest trade
trades	number	Number of trades executed within the interval
firstTradeId	number	Unique identifier of the first trade
rawVolume	number	Raw value of the trade volume without consideration of decimal places values (decimal places defined in `quantityDecimalPlaces` from Trading Pairs Schema)

WebSocket API

The Archax WebSocket API allows developers to subscribe to real-time market data feeds.

Additionally, the API accepts commands for the creation and cancellation of orders.

Connection

Login command

{
  "action": "login",
  "service": "core",
  "token": "valid-token"
}

Successful login event

{
  "action": "user-login-success",
  "data": [],
  "description": "Authorisation successful",
  "status": "OK",
  "type": "user-login"
}

Failed login event

{
  "action": "user-login-failed",
  "data": [],
  "description": "Authorisation failed",
  "status": "ERROR",
  "type": "user-login"
}

The public WebSocket endpoint is wss://ace-auth.archax.com/api/3.0/gateway.

To login to the API you must obtain a JWT token from API v3 REST login endpoint. In combination with the JWT, you must specify the login action and the core service.

Once your login credentials have been verified, you will receive a user-login-success event. Otherwise you will receive a user-login-failed event and you will then be disconnected.

As of version 3.0, the response events for all subscriptions include a new field responseType that will have a value of snapshot on the first response and update on all subsequent responses.

Renew JWT

Renewal command

{
  "action": "renew-jwt"
}

Successful renewal event

{
  "status": "OK",
  "action": "renew-jwt-response",
  "data": {
    "jwt": "your-token"
  },
  "type": "notifications",
  "timestamp": "2023-11-09T10:56:56.545Z"
}

Send a renew-jwt command to refresh the jwt token. When maintaining a websocket connection for long periods of time, it is recommended to use this command every 25-28 minutes. There is no need to provide the old token. The new token can also be used for the REST endpoints.

Market Data

Subscribe to Trading Pairs command

{
  "action": "subscribe-trading-pairs"
}

Set Trading Pairs event

{
  "status": "OK",
  "action": "set-trading-pairs",
  "data": {
      "24": {
        "baseAsset": "HSBb",
		"baseAssetId": 24,
        "description": "HSBC Bank PLC",
        "marketStatus": "open",
        "priceDecimalPlaces": 2,
        "quantityDecimalPlaces": 0,
        "quoteAsset": "USD",
		"quoteAssetId": 2,
        "regulatedStatus": "eligible",
        "ticker": "HSBb",
        "tickSize": "0.01",
        "id": 24,
        "tradingStatus": "Trading",
        "productId": 1
      },
      "25": {
        "baseAsset": "BTC",
		"baseAssetId": 26
        "description": "BTC USD trading pair",
        "marketStatus": "open",
        "priceDecimalPlaces": 2,
        "quantityDecimalPlaces": 6,
        "quoteAsset": "USD",
		"quoteAssetId": 2,
        "regulatedStatus": "ineligible",
        "ticker": "BTCUSD",
        "tickSize": "0.01",
        "id": 25,
        "tradingStatus": "Trading",
        "productId": 2
      },
	},
	"responseType": "snapshot",
    "type": "tradingPairs",
    "timestamp": "2023-04-12T07:30:00.069Z"
}

Send a subscribe-trading-pairs command to subscribe to trading pair updates. It will initially return a set-trading-pairs event that contains all assets available on the exchange while subsequent set-trading-pairs events will only include products and properties that have since been updated. The data property is an object keyed by tradingPairId, with the following details:

Set Trading Pairs Event Schema

Name	Type	Description
[key]		Identifier of the trading pair
baseAsset	string	Symbol for the first listed asset in the trading pair
baseAssetId	number	Asset identifier for the first listed asset in the trading pair
description	string	The full name of the asset
marketStatus	string	Current market status for the asset. Possible values are: `open`, `closed` and `closing auction`
priceDecimalPlaces	number	Number of decimal places used by the system when accepting a price for the asset
quantityDecimalPlaces	number	Number of decimal places used by the system when accepting a quantity for the asset
quoteAsset	string	Symbol for the second listed asset in the trading pair in which the first listed asset is priced
quoteAssetId	number	Asset identifier for the second listed asset in the trading pair in which the first listed asset is priced
regulatedStatus	string	The regulated status of the asset. Possible values are: `eligible` and `ineligible`
ticker	string	Ticker symbol for the trading pair
tickSize	string	Smallest price variation allowed when submitting an order for the trading pair
id	string	Unique identifier of the trading pair
tradingStatus	string	Current trading status for the trading pair. Possible values are: `Created`, `Pre-Live`, `Trading`, `Suspended` and `Terminated`
productId	number	Unique identifier for the product type associated with the trading pair. An endpoint will become available soon but until then 1 = `SME Growth Market` and 2 = `Alternative Trading Facility`

Subscribe to Market Quotes command

{
  "action": "subscribe-market-quotes"
}

Subscribe to Market Quotes for a single trading pair

{
  "action": "subscribe-market-quotes/53"
}

Unsubscribe to Market Quotes command

{
  "action": "unsubscribe-market-quotes"
}

Unsubscribe to Market Quotes for a single trading pair

{
  "action": "unsubscribe-market-quotes/53"
}

Set Market Quotes event (initial)

{
  "status": "OK",
  "action": "set-market-quotes/1",
  "data": {
    "1": {
      "askPrice": "",
      "askQty": "",
      "bidPrice": "",
      "bidQty": "",
      "changePercent": "-38.60",
      "changePrice": "-6408",
      "closePrice": "16600",
      "cumulativeUnits": "",
      "cumulativeValue": "",
      "highPrice": "10192",
      "tradingPairId": 1,
      "lastPrice": "10192",
      "lastQty": "1",
      "lowPrice": "10192",
      "openPrice": "10192",
      "sevenDayChange": "1068",
      "sevenDayChangePercentage": "11.71",
      "sevenDayClosePrice": "9124"
    }
  },
  "responseType": "snapshot",
  "type": "market-quotes",
  "timestamp": "2021-10-05T10:53:59.201Z"
}

Set Market Quotes event (update)

{
  "status": "OK",
  "action": "set-market-quotes/3",
  "data": {
    "3": {
      "askPrice": "36555",
      "askQty": "250"
    }
  },
  "responseType": "update",
  "type": "market-quotes",
  "timestamp": "2023-12-13T12:48:51.397Z"
}

Set Market Quotes event (reset specified properties)

{
  "status": "OK",
  "action": "set-market-quotes/3",
  "data": {
    "3": {
      "bidPrice": "",
      "bidQty": "",
      "openPrice": ""
    }
  },
  "responseType": "update",
  "type": "market-quotes",
  "timestamp": "2023-12-13T12:48:51.397Z"
}

Send a subscribe-market-quotes command to subscribe to real-time pricing updates for all available trading pairs in the market. To subscribe to market quotes for a specific trading pair id, send a subscribe-market-quotes/[tradingPairId] command. The response is a set-market-quotes event for each subscribed trading pair. Subsequent events only contain updates for the included fields. Send an unsubscribe-market-quotes/[tradingPairId] command to unsubscribe for an individual trading pair or an unsubscribe-market-quotes command to unsubscribe from all market quotes.

Each value in the data property is keyed by tradingPairId.

Set Market Quotes Event Schema

Name	Type	Description
[key]		Identifier of the trading pair
askPrice	string	Best asking price for the trading pair without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)
askQty	string	Number of units on offer at the `askPrice` without consideration of decimal places values (decimal places defined in `quantityDecimalPlaces` from Trading Pairs Schema)
bidPrice	string	Best bid price for the trading pair without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)
bidQty	string	Number of units requested at the `bidPrice` without consideration of decimal places values (decimal places defined in `quantityDecimalPlaces` from Trading Pairs Schema)
changePercent	string	The percentage difference between the `lastPrice` and `closePrice`
changePrice	string	The difference between the `lastPrice` and `closePrice` without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)
closePrice	string	The trading pair’s last traded price from the previous trading session without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)
cumulativeUnits	string	The cumulative volume of units traded within the current trading session
cumulativeValue	string	The cumulative value of all trades on the trading pair for the current trading session without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)
tradingPairId	number	Unique identifier of the trading pair
lastPrice	string	Last traded price for the trading pair without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)
highPrice	string	Highest trade price for the trading pair during the current trading session without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)
lowPrice	string	Lowest trade price for the trading pair during the current trading session without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)
lastQty	string	Last traded quantity for the trading pair without consideration of decimal places values (decimal places defined in `quantityDecimalPlaces` from Trading Pairs Schema)
openPrice	string	Price at which the first execution of the day for the trading pair occurred without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)
sevenDayChange	string	The difference between `closePrice` and `sevenDayClosePrice` without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)
sevenDayChangePercentage	string	The percentage difference between the `closePrice` and `sevenDayClosePrice`
sevenDayClosePrice	string	The trading pair’s close price 7 days prior without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)

askPrice, bidPrice, changePrice, closePrice, cumulativeValue, highPrice, lastPrice, lowPrice, openPrice, sevenDayChange and sevenDayClosePrice would always be returned as a whole number. The number of decimal places for each asset then determines how these price values are formatted. Use the priceDecimalPlaces property returned by the set-trading-pairs event to determine the number of decimal places for the value in these fields.

If the value returned for askPrice is 2356 and the trading pair’s priceDecimalPlaces property is 3. The actual askPrice is then obtained by evaluating: 2356 / (10 ^ 3) which gives 2.356. The same goes for all properties that end with Price.

askQty, bidQty, cumulativeUnits and lastQty would also always be returned as a whole number. To determine the number of decimal places, use the quantityDecimalPlaces property returned by the set-trading-pairs event.

The set-market-quotes event would be returned each time there’s a change on any of the fields listed in the preceding table. The data property would only contain the fields that have changed. So, if you have an trading pair with the following state:

"2": { "askPrice": "", "askQty": "", "bidPrice": "", "bidQty": "", "changePercent": "-24.19", "changePrice": "-4112.00", "closePrice": "17000", "cumulativeUnits": "", "cumulativeValue": "", "highPrice": "12888", "tradingPairId": 2, "lastPrice": "12888", "lastQty": "3", "lowPrice": "12888", "openPrice": "", "sevenDayChange": "867.00", "sevenDayChangePercentage": "7.21", "sevenDayClosePrice": "12021" }

and you receive an update with following data:

{ "2": { "askQty": "35", } }

the expected state of tradingPairId 2 is:

"2": { "askPrice": "", "askQty": "35", "bidPrice": "", "bidQty": "", "changePercent": "-24.19", "changePrice": "-4112.00", "closePrice": "17000", "cumulativeUnits": "", "cumulativeValue": "", "highPrice": "12888", "tradingPairId": 2, "lastPrice": "12888", "lastQty": "3", "lowPrice": "12888", "openPrice": "", "sevenDayChange": "867.00", "sevenDayChangePercentage": "7.21", "sevenDayClosePrice": "12021" }

At the start of a trading session, a set-market-quotes event would be returned and the content of its data property would be similar to:

"2": { "askPrice": "", "askQty": "", "bidPrice": "", "bidQty": "", "changePercent": "0.00", "changePrice": "0", "cumulativeUnits": "", "cumulativeValue": "", "highPrice": "", "lowPrice": "", "openPrice": "" }

the expected state of tradingPairId 2 would then be:

"2": { "askPrice": "", "askQty": "", "bidPrice": "", "bidQty": "", "changePercent": "0.00", "changePrice": "0", "closePrice": "17000", "cumulativeUnits": "", "cumulativeValue": "", "highPrice": "", "tradingPairId": 2, "lastPrice": "12888", "lastQty": "3", "lowPrice": "", "openPrice": "", "sevenDayChange": "867.00", "sevenDayChangePercentage": "7.21", "sevenDayClosePrice": "12021" }

Subscribe to Assets command

{
  "action": "subscribe-assets"
}

Set Cash event

{
  "status": "OK",
  "action": "set-assets",
  "data": {
    "1": {
      "id": 1,
      "decimalValue": 2,
      "name": "GBP",
      "status": "active",
      "symbol": "GBP",
      "type": "cash"
    },
    "2": {
      "id": 2,
      "decimalValue": 2,
      "name": "USD",
      "status": "active",
      "symbol": "USD",
      "type": "cash"
    },
    "3": {
      "id": 3,
      "decimalValue": 0,
      "name": "Apple Inc",
      "status": "active",
      "symbol": "APPa",
      "type": "security"
    },
    "4": {
      "id": 4,
      "decimalValue": 4,
      "name": "Bitcoin",
      "status": "active",
      "symbol": "BTC",
      "type": "crypto"
    }
  },
  "responseType": "snapshot",
  "type": "asets",
  "timestamp": "2023-03-10T07:28:31.028Z"
}

Send a subscribe-assets command to subscribe to asset details. It will initially return a set-assets event that contains all assets available in ACE. Subsequent set-assets events will only include assets and properties that have since been updated

Set Assets Event Schema

Name	Type	Description
[key]		Identifier of the asset
id	number	Unique identifier of the asset
decimalValue	string	Decimal value used by the system when trading quantity of the asset
name	string	The short name for the asset
status	string	The status of the asset. Possible values are: `active` and `inactive`
symbol	string	Symbol or currency code for the asset
type	string	The asset type. Possible values are: `security`, `cash` and `crypto`

Balances

Fetch Balances

Fetch Balances command

{
  "action": "fetch-balances",
  "data": {
    "organisationId": 1,
    "productId": 1
  }
}

Fetch Balances event

{
  "action": "fetch-balances",
  "organisationId": 1,
  "data": {
    "2786123094": {
      "accountId": 2786123094,
      "accountType": "accountSecurity",
      "available": "1000000400",
      "regulatoryEligibility": "eligible",
      "productId": 1,
      "assetId": 1,
      "total": "1000000400"
    },
    "2786123904": {
      "accountId": 2786123904,
      "accountType": "accountSecurity",
      "available": "1000000400",
      "regulatoryEligibility": "eligible",
      "productId": 1,
      "assetId": 2,
      "total": "1000000400"
    },
    "2786123095": {
      "accountId": 2786123095,
      "accountType": "accountCrypto",
      "available": "1000000400",
      "regulatoryEligibility": "ineligible",
      "productId": 2,
      "assetId": 3,
      "total": "1000000400"
    },
    "2786123398": {
      "accountId": 2786123398,
      "accountType": "accountCash",
      "available": "1000000400",
      "regulatoryEligibility": "eligible",
      "productId": 1,
      "assetId": 4,
      "total": "1000000400"
    },
    "2786122842": {
      "accountId": 2786122842,
      "accountType": "accountUnregulatedCash",
      "available": "1000000400",
      "regulatoryEligibility": "ineligible",
      "productId": 2,
      "assetId": 5,
      "total": "1000000400"
    },
    "2786122894": {
      "accountId": 2786122894,
      "accountType": "accountCash",
      "available": "1000000400",
      "regulatoryEligibility": "eligible",
      "productId": 1,
      "assetId": 6,
      "total": "1000000400"
    }
  },
  "timestamp": "2021-07-01T04:30:06.127Z"
}

Send a fetch-balances command to retrieve all account balances for all of the organisations to which you belong. The command can include optional data propertie to filter the response to a single organisation and/or product type. The response is a fetch-balances event that includes a data property where the object is keyed by accountId.

Fetch Balance Command Schema (optional)

Name	Type	Description
organisationId	number	Unique identifier for the organisation subject to the fetch balance request
productId	number	Unique identifier for the product type subject to the fetch balance request. An endpoint will become available soon but until then 1 = `SME Growth Market` and 2 = `Alternative Trading Facility`

Fetch Balances Event Schema

Name	Type	Description
[key]		Identifier of the account
accountId	number	Unique identifier for the account
accountType	string	Type of account. The possible values are: `accountCash`, `accountUnregulatedCash`, `accountSecurity` and `accountCrypto`
available	string	Available balance of account without consideration of decimal place values (decimal places defined in `decimalValue` from Assets Schema)
regulatoryEligibility	string	Indicates regulatory eligibility. Possible values are: `eligible` and `ineligible`
productId	number	Identifier of the product type using the ledger account. An endpoint will become available soon but until then 1 = `SME Growth Market` and 2 = `Alternative Trading Facility`
assetId	number	Identifier of the account asset
total	string	Total balance of account without consideration of decimal place values (decimal places defined in `decimalValue` from Assets Schema)

Subscribe to Balances command

{
  "action": "subscribe-balances",
  "data": {
    "organisationId": 3,
    "productId": 2
  }
}

Set Balances event

{
  "status": "OK",
  "action": "set-balances",
  "organisationId": 3,
  "data": {
    "2786123094": {
      "accountId": 2786123094,
      "accountType": "accountCash",
      "available": "1000000400",
      "productId": 1,
      "assetId": 1,
      "regulatoryEligibility": "eligible",
      "total": "1000000400"
    },
    "2786123095": {
      "accountId": 2786123095,
      "accountType": "accountSecurity",
      "available": "1000000400",
      "productId": 1,
      "assetId": 2,
      "regulatoryEligibility": "eligible",
      "total": "1000000400"
    },
    "2786122842": {
      "accountId": 2786122842,
      "accountType": "accountCrypto",
      "available": "1000180131",
      "productId": 2,
      "assetId": 3,
      "regulatoryEligibility": "ineligible",
      "total": "1000180207"
    }
  },
  "responseType": "snapshot",
  "type": "balances",
  "timestamp": "2021-07-01T04:30:06.408Z"
}

Send a subscribe-balances command to subscribe to account balance updates for all of the organisations to which you belong. It will initially return a set-balances event that contains all account balances while subsequent set-balances events will only include account balances that have since been updated. The command can include optional data propertie to filter the response to a single organisation and/or product type. The response is a set-balances event that includes a data property where the object is keyed by accountId.

Subscribe Balance Command Schema (optional)

Name	Type	Description
organisationId	number	Unique identifier for the organisation subject to the subscribe balance request
productId	number	Unique identifier for the product type subject to the subscribe balance request. An endpoint will become available soon but until then 1 = `SME Growth Market` and 2 = `Alternative Trading Facility`

Set Balances Event Schema

Name	Type	Description
[key]		Identifier of the account
accountId	number	Unique identifier for the account
accountType	string	Type of account. The possible values are: `accountCash`, `accountUnregulatedCash`, `accountSecurity` and `accountCrypto`
available	string	Available balance of account without consideration of decimal place values (decimal places defined in `decimalValue` from Assets Schema)
productId	number	Identifier of the product type using the ledger account. An endpoint will become available soon but until then 1 = `SME Growth Market` and 2 = `Alternative Trading Facility`
assetId	number	Unique identifier of the asset
regulatoryEligibility	string	Indicates regulatory eligibility. Possible values are: `eligible` and `ineligible`
total	string	Total balance of account without consideration of decimal place values (decimal places defined in `decimalValue` from Assets Schema)

Orders

Submit an Order

Submit Order command

{
  "action": "order-submit",
  "data": {
    "userReference": "user_reference_1234",
    "tradingPairId": 3,
    "limitPrice": "356.99",
    "orderType": 0,
    "quantity": "100.5",
    "side": 0,
    "organisationId": 1
  }
}

Order Updated event

{
  "status": "OK",
  "action": "order-updated",
  "data": {
    "userReference": "user_reference_1234",
    "orderId": "1625642744032536",
    "organisationId": 1,
    "status": "open"
  },
  "type": "notifications",
  "timestamp": "2021-07-07T07:25:45.140Z"
}

Order Updated event with status ERROR (order rejected)

{
  "status": "ERROR",
  "action": "order-updated",
  "data": {
    "userReference": "user_reference_1234",
    "error": "Dynamic Price Collar",
    "orderId": "1626062904341855",
    "organisationId": 1,
    "status": "rejected"
  },
  "type": "notifications",
  "timestamp": "2021-07-07T07:25:45.140Z"
}

Order Submitted event with status ERROR

{
  "status": "ERROR",
  "action": "order-submitted",
  "data": {
    "error": "No trading pair selected",
    "userReference": "user_reference_1234"
  },
  "type": "notifications",
  "timestamp": "2021-07-07T07:45:04.231Z"
}

Send an order-submit command to submit an order. The response is either an order-updated event for a successfully received order or an order-submitted event with a status of ERROR.

Order Submit Command Schema

Name	Type	Description
userReference	string	User-specified identifier; it will be included the response
tradingPairId	number	Unique identifier of the trading pair
limitPrice	string	Limit Price for the order (supports decimal values)
orderType	number	Type of order, possible values: `0` = Limit Order
quantity	string	Quantity for order (supports decimal values)
side	number	Market side of order, possible values: `0` = Buy, `1` = Sell
organisationId	number	Unique identifier for the organisation subject to the order submission

When an userReference is provided, it must be unique across all commands.

Order Updated Event Schema

Name	Type	Description
userReference	string	If the order `status` is `open` or `rejected`, it will be the `userReference` that was included in the submitted order. If the order `status` is `cancelled`, it will be the `orderId`. Otherwise it will not be included for other `status` values.
error	string	Description of error that was identified, will not be included if there is no error.
orderId	string	Unique identifier for the order
organisationId	number	Unique identifier for the organisation that placed the order
status	string	Status of order, possible values: `pending`, `open`, `cancelled`, `expired`, `rejected`, `completed`

Order Submitted (Error) Event Schema

Name	Type	Description
error	string	Description of error that was identified
userReference	string	User-specified identifier that was included in the submitted order

Subscribe to Orders command

{
  "action": "subscribe-orders",
  "data": {
    "organisationId": 164
  }
}

Set Orders event (initial)

{
  "status": "OK",
  "organisationId": 164,
  "action": "set-orders",
  "data": {
    "1706847869414282": {
      "averagePrice": "0",
      "commission": "0",
      "created": "1706847869414282",
      "currency": "USD",
      "decimals": 2,
      "executions": {},
      "filledPercent": "0.00",
      "filledQty": "0",
      "filledStatus": "unfilled",
      "id": "1706847869414282",
      "lastUpdated": "1706847869414282",
      "limitPrice": "40800",
      "orderStatus": "rejected",
      "organisationId": 164,
      "quantity": "12",
      "side": "buy",
      "tax": "0",
      "tradingPairId": 5,
      "type": "limit",
      "userId": 198,
      "userReference": "hXpIb_siyQSwt1b9q7-BE"
    },
    "1704438113575594": {
      "averagePrice": "11000",
      "commission": "20",
      "created": "1704438113575594",
      "currency": "USD",
      "decimals": 2,
      "executions": {
        "1704438113576312": {
          "commission": "20",
          "created": "1704438113575000",
          "grossExecutionAmount": "1078000000",
          "id": "2401050030000000058",
          "orderId": "1704438113575594",
          "price": "11000",
          "quantity": "98000",
          "referenceId": "1704438113576312",
          "tax": "0"
        }
      },
      "filledPercent": "100.00",
      "filledQty": "98000",
      "filledStatus": "filled",
      "id": "1704438113575594",
      "lastUpdated": "1704438113576749",
      "limitPrice": "11000",
      "orderStatus": "completed",
      "organisationId": 164,
      "quantity": "98000",
      "side": "buy",
      "tax": "0",
      "tradingPairId": 8,
      "type": "limit",
      "userId": 198,
      "userReference": "aB4pN4BZU-CF2YlkRJy81"
    }
  },
  "type": "orders",
  "responseType": "snapshot",
  "timestamp": "2024-02-16T11:28:59.822Z"
}

Set Orders event (update)

{
  "status": "OK",
  "action": "set-orders",
  "data": {
    "1626077181607120": {
      "orderStatus": "open"
    }
  },
  "responseType": "update"
  "type": "orders",
  "timestamp": "2021-07-12T08:06:21.613Z"
}

Send a subscribe-orders command to subscribe to order updates for all of the organisations you belong to. It initially returns a set-orders event that includes all orders. Subsequent set-orders events will only contain orders that have since been updated. The command can include an optional data property to filter the response to a single organisation. A response will be send for each subscribed organisation and will include an organisationId property to indicate to which organisation the response is relevant while the data property will be an object keyed by order id.

Subscribe Orders Command Schema (optional)

Name	Type	Description
organisationId	number	Unique identifier for the organisation subject to the order subscription request

Set Orders Event Schema

Name	Type	Description
[key]		Unique order identifier
averagePrice	string	Average execution price for the order without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)
created	string	Timestamp of when the order was placed (µs)
currency	string	Currency code
commission	string	Total commission value of the order
decimals	number	Number of decimal places required to correct commission, grossExecutionAmount and tax values
executions	Execution	Details of executed trades, keyed by `referenceId` (where `referenceId` is a unique reference to the execution)
filledPercent	string	Filled percent
filledQty	string	Filled quantity without consideration of decimal places value (decimal places defined in `quantityDecimalPlaces` from Trading Pairs Schema)
filledStatus	string	Fill status, possible values: `unfilled`, `partiallyFilled`, `filled`
id	string	Unique order identifier
limitPrice	string	Order limit price without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)
lastUpdated	string	Timestamp of when the order was last updated (µs)
organisationId	number	Unique identifier for the organisation that placed the order
orderStatus	string	Order status, possible values: `pending`, `open`, `cancelled`, `expired`, `rejected`, `completed`
quantity	string	Order quantity without consideration of decimal places value (decimal places defined in `quantityDecimalPlaces` from Trading Pairs Schema)
side	string	Order side, possible values: `buy`, `sell`
type	string	Order type, possible values: `limit`
tax	string	Total tax value of the order
tradingPairId	number	Unique identifier of the trading pair
userId	number	Unique identifier of the user
userReference	number	User-specified identifier provided with the order

Execution Schema

Name	Type	Description
commission	string	Total commission value of the execution
created	string	Timestamp on when the trade was executed (µs)
grossExecutionAmount	string	Product of executed price and quantity (needs to be corrected for decimal places using the combination of decimals in the set-order schema and `quantityDecimalPlaces` from Trading Pairs Schema)
orderId	string	Unique identifier of the order associated with the execution
price	string	Executed price without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)
id	string	Unique identifier to execution at the trade level (i.e. same id provided to both sides of the trade)
quantity	string	Executed quantity without consideration of decimal places value (decimal places defined in `quantityDecimalPlaces` from Trading Pairs Schema)
referenceId	string	Unique identifier to the execution and order.
tax	string	Total tax value of the order

set-orders updates must be deeply merged from the previous state. For example, if an order has the following state:

{ "1626077181607120": { "orderStatus": "pending", "decimals": 2, "tradingPairId": 3, "filledPercent": "0.00", "created": 1626077181607.12, "quantity": 100, "averagePrice": 0, "limitPrice": "35699", "currency": "USD", "filledQty": "0", "filledStatus": "unfilled", "side": "buy", "type": "limit", "executions": {}, "id": "1626077181607120", "userId": 24, "userReference": "user_ref_3030" } }

and you receive an update with following data:

{ "1626077181607120": { "orderStatus": "open" } }

the expected state of order 1626077181607120 is:

{ "1626077181607120": { "orderStatus": "open", "decimals": 2, "tradingPairId": 3, "filledPercent": "0.00", "created": 1626077181607.12, "quantity": 100, "averagePrice": 0, "limitPrice": "35699", "currency": "USD", "filledQty": "0", "filledStatus": "unfilled", "side": "buy", "type": "limit", "executions": {}, "id": "1626077181607120", "userId": 24, "userReference": "user_ref_3030" } }

Cancel an Order

Cancel Order Command

{
  "action": "order-cancel",
  "data": {
    "userReference": "user_reference_1234",
    "orderId": "1625642744032536",
    "organisationId": 1
  }
}

Order Cancelled Event

{
  "status": "OK",
  "action": "order-cancelled",
  "data": {
    "userReference": "user_ref_4040",
    "orderId": "1625642744032536",
    "organisationId": 1,
    "status": "cancelled"
  },
  "type": "notifications",
  "timestamp": "2021-07-07T18:57:04.231Z"
}

Cancellation Rejected Event

{
  "status": "ERROR",
  "action": "cancel-rejected",
  "data": {
    "userReference": "user_ref_5050",
    "error": "Order cannot be cancelled",
    "orderId": "1625642744032536",
    "organisationId": 1,
    "reason": "marketClosed",
    "status": "completed",
    "userId": 12
  },
  "type": "notifications",
  "timestamp": "2021-07-07T18:57:04.231Z"
}

Cancel Failed Event with ERROR status

{
  "status": "ERROR",
  "action": "cancel-failed",
  "data": {
    "error": "No order id provided",
    "userReference": "user_reference_1234"
  },
  "type": "notifications",
  "timestamp": "2021-07-07T18:57:04.231Z"
}

Send an order-cancel command to cancel an order.

Order cancellation is only available for orders submitted by users within that organisation with a status of open. If the status of an order is one of cancelled, completed, expired or rejected, sending the order-cancel command would result in a cancel-rejected event being returned.

The successful cancellation of an order would cause an order-cancelled event to be returned while a cancel-failed event is returned when there are errors in the submitted order-cancel command.

Cancel Order Command Schema

Name	Type	Description
userReference	string	Optional field for client to include a unique identifier
orderId	string	Unique identifier for the order
organisationId	number	Unique identifier for the organisation subject to the order cancellation

When an userReference is provided, it must be unique across all commands.

Order Cancelled Event Schema

Name	Type	Description
userReference	string	Unique identifier provided by client
orderId	string	Unique identifier for the order
organisationId	number	Unique identifier for the organisation that placed the order
status	string	The status of the order

Cancellation Rejected Event Schema

Name	Type	Description
userReference	string	Unique identifier provided by client
error	string	Error message
orderId	string	Unique identifier for the order
organisationId	number	Unique identifier for the organisation that placed the order
reason	string	The reason for the rejection
status	string	The status of the order
userId	string	Unique identifier of the user that requested the cancellation

Cancellation Failed Event Schema

Name	Type	Description
userReference	string	User-specified identifier
error	string	Error message; would contain the reason for the failure

Order Book

Subscribe to Market Depths command

{
  "action": "subscribe-market-depths"
}

Subscribe to Market Depths for a single trading pair command

{
  "action": "subscribe-market-depths/52"
}

Unsubscribe to Market Depths command

{
  "action": "unsubscribe-market-depths"
}

Unsubscribe to Market Depths for a single trading pair command

{
  "action": "unsubscribe-market-depths/52"
}

Set Market Depths event (initial)

{
  "status": "OK",
  "action": "set-market-depths/1",
  "data": {
    "1": {
      "buy": {
        "1200": 100,
        "1300": 50
      },
      "indicativePrice": "",
      "indicativeVolume": "",
      "tradingPairId": 1,
      "sell": {
        "1310": 20,
        "1320": 50
      }
    }
  },
  "responseType": "snapshot",
  "type": "market-depths",
  "timestamp": "2021-07-01T05:17:00.691Z"
}

Set Market Depths event (update)

{
  "status": "OK",
  "action": "set-market-depths/1",
  "data": {
    "1": {
      "tradingPairId": 1,
      "buy": {
        "1200": 120
      },
      "sell": {}
    }
  },
  "responseType": "update"
  "type": "market-depths",
  "timestamp": "2021-07-01T05:17:00.691Z"
}

Set Market Depths event (update, depth removed from Order Book)

{
  "status": "OK",
  "action": "set-market-depths/1",
  "data": {
    "1": {
      "tradingPairId": 1,
      "buy": {
        "1200": 0
      },
      "sell": {
        "1199": 0
      }
    }
  },
  "responseType": "update",
  "type": "market-depths",
  "timestamp": "2021-07-01T05:17:00.691Z"
}

Send a subscribe-market-depths command to subscribe to Order Book updates for all trading pairs available in the market. To subscribe to market depths for a specific trading pair id, send a subscribe-market-depths/[tradingPairId] command. The response is a set-market-depths event for each subscribed trading pair. Subsequent events only contain updates for the included fields. Send an unsubscribe-market-depths/[tradingPairId] command to unsubscribe for an individual trading pair or an unsubscribe-market-depths command to unsubscribe from all market depths.

Set Market Depths Event Schema

Name	Type	Description
[key]		Identifier of the trading pair
buy	string	Market depth (price) for the buy side of the market (price without consideration of decimal places value, decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)
indicativePrice	string	(Provided during auction phase) The price at which the most executions would occur if the auction ended at the current time. Also referred to as the uncrossing price (price without consideration of decimal places value, decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)
indicativeVolume	string	(Provided during auction phase) The number of units that would exchange hands if the auction ended at the current time (quantity without consideration of decimal places value, decimal places defined in `quantityDecimalPlaces` from Trading Pairs Schema)
tradingPairId	number	Identifier of the trading pair
sell	string	Market depth (price) for the sell side of the market (price without consideration of decimal places value, decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)

Market Depth Schema (Buy or Sell)

Name	Type	Description
[key]		Market depth (price without consideration of decimal places value, decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)
[value]	number	Volume (quantity without consideration of decimal places value, decimal places defined in `quantityDecimalPlaces` from Trading Pairs Schema)

set-market-depths updates must be deeply merged from the previous state. For example, if an instrument has the following state:

{ "1": { "buy": { "1200": 100, "1300": 50 }, "indicativePrice": "", "indicativeVolume": "", "tradingPairId": 1, "sell": { "1310": 20, "1320": 50 } } }

and you receive an update with following data:

{ "1": { "buy": { "1100": 500 }, "tradingPairId": 1, "sell": {} } }

the expected state of tradingPairId 1 is:

{ "1": { "buy": { "1100": 500, "1200": 100, "1300": 50 }, "indicativePrice": "", "indicativeVolume": "", "tradingPairId": 1, "sell": { "1310": 20, "1320": 50 } } }

set-market-depths updates with a quantity value of 0 are sent to clear a particular depth. For example, if an trading pair has the following state:

{ "1": { "buy": { "1200": 100, "1300": 50 }, "indicativePrice": "", "indicativeVolume": "", "tradngPairId": 1, "sell": { "1310": 20, "1320": 50 } } }

and you receive an update with following data:

{ "1": { "buy": { "1300": 0 }, "tradingPairId": 1, "sell": {} } }

the expected state of tradingPairId 1 is:

{ "1": { "buy": { "1200": 100 }, "indicativePrice": "", "indicativeVolume": "", "tradingPairId": 1, "sell": { "1310": 20, "1320": 50 } } }

Trades

Subscribe to a single instruments Trade History command. Where 1 denotes an example tradingPairId.

{
  "action": "subscribe-trade-histories/1"
}

Subscribe to all Trade History.

{
  "action": "subscribe-trade-histories"
}

Response JSON returned example -

Initial Set Trade History event

{
  "status": "OK",
  "action": "set-trade-histories/1",
  "data": {
    "1": [
      {
        "amount": "81",
        "created": "1619080206756725504",
        "price": "9124",
        "side": "sell",
        "tradeRef": "1"
      },
      {
        "amount": "4",
        "created": "1619080141466397184",
        "price": "10875",
        "side": "buy",
        "tradeRef": "2"
      },
      {
        "amount": "48",
        "created": "1619080099647654400",
        "price": "9059",
        "side": "buy",
        "tradeRef": "3"
      }
    ]
  },
  "responseType": "snapshot",
  "type": "trade-histories",
  "timestamp": "2021-08-27T14:39:46.820Z"
}

Set Trade History event (update)

{
  "status": "OK",
  "action": "append-trade-histories/1",
  "data": {
    "1": [
      {
        "amount": 45,
        "created": 1619080206756725534,
        "price": 9127,
        "side": "sell",
        "tradeRef": "4"
      }
    ]
  },
  "responseType": "update",
  "type": "trade-histories",
  "timestamp": "2021-08-27T15:35:59.147Z"
}

To subscribe to all trade histories, send a subscribe-trade-histories command. To subscribe to trade history for a specific tradingPairId send a subscribe-trade-histories/[tradingPairId] command to subscribe to trade history updates. It will initially return a set-trade-histories/[tradingPairId] event that contains the most recently executed trades for the requested tradingPairId. An append-trade-histories/[tradingPairId] event will then be returned for each additional trade executes while the subscription is active.

Note that a maximum of the latest twenty orders only is returned for the requested tradingPairId or the latest 20 for all trade history.

The data property is an object keyed by tradingPairId, with the following details:

Set trade history Event Schema

Name	Type	Description
[key]		Unique identifier of the trading pair
amount	string	Quantity traded (quantity without consideration of decimal places value, decimal places defined in `quantityDecimalPlaces` from Trading Pairs Schema)
created	string	Time of trade
price	string	Executed price without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Trading Pairs Schema)
side	string	Aggressive side of order (`buy` or `sell`). `auction` is returned as value when trade is a result of an auction
tradeRef	string	Unique identifier of trade

Transactions

Subscribe to Transactions command

{
  "action": "subscribe-transactions"
}

Set Transaction event

{
  "status": "OK",
  "action": "set-transactions",
  "data": {
    "entries": [
      {
        "id": "1631023590277781",
        "organisationId": 3,
        "userId": 12,
        "accountId": 2786122875,
        "amount": "10",
        "referenceId": "1631023590277580",
        "created": "1631023590272836",
        "ledgerType": "debit",
        "reportType": "execution",
        "commissionReference": "0",
        "assetId": 3
      },
      {
        "id": "1631023590278240",
        "organisationId": 3,
        "userId": 12,
        "accountId": 2786122905,
        "amount": "409500",
        "referenceId": "1631023590277580",
        "created": "1631023590272872",
        "ledgerType": "credit",
        "reportType": "execution",
        "commissionReference": "0",
        "assetId": 33
      },
      {
        "id": "1631016154737596",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123148,
        "amount": "109",
        "referenceId": "1631016154736971",
        "created": "1631016154725876",
        "ledgerType": "debit",
        "reportType": "commission",
        "commissionReference": "1631016099181019",
        "assetId": 7
      },
      {
        "id": "1631016154737159",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123148,
        "amount": "1090",
        "referenceId": "1631016154736971",
        "created": "1631016154725882",
        "ledgerType": "debit",
        "reportType": "execution",
        "commissionReference": "0",
        "assetId": 32
      },
      {
        "id": "1631016154738149",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123124,
        "amount": "109",
        "referenceId": "1631016154736971",
        "created": "1631016154725886",
        "ledgerType": "credit",
        "reportType": "execution",
        "commissionReference": "0",
        "assetId": 7
      },
      {
        "id": "1631014364506141",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123148,
        "amount": "109",
        "referenceId": "1631014364505500",
        "created": "1631014364499891",
        "ledgerType": "debit",
        "reportType": "commission",
        "commissionReference": "1631014308958295",
        "assetId": 7
      },
      {
        "id": "1631014364505723",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123148,
        "amount": "1090",
        "referenceId": "1631014364505500",
        "created": "1631014364499895",
        "ledgerType": "debit",
        "reportType": "execution",
        "commissionReference": "0",
        "assetId": 32
      },
      {
        "id": "1631014364507061",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123124,
        "amount": "109",
        "referenceId": "1631014364505500",
        "created": "1631014364499900",
        "ledgerType": "credit",
        "reportType": "execution",
        "commissionReference": "0",
        "assetId": 7
      },
      {
        "id": "1631014099470021",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123124,
        "amount": "1234",
        "referenceId": "1631014099467372",
        "created": "1631014099463903",
        "ledgerType": "credit",
        "reportType": "execution",
        "commissionReference": "0",
        "assetId": 7
      },
      {
        "id": "1631014099468016",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123148,
        "amount": "121",
        "referenceId": "1631014099467372",
        "created": "1631014099463907",
        "ledgerType": "debit",
        "reportType": "commission",
        "commissionReference": "1631014043667348",
        "assetId": 7
      }
    ]
  },
  "responseType": "snapshot",
  "type": "transactions",
  "timestamp": "2021-09-08T00:46:23.587Z"
}

Send a subscribe-transactions command to subscribe to transaction updates. It will return a set-transactions event that contains the last 1000 transactions for each organisation you belong to. Subsequent transactions would also cause a set-transactions event to be returned which will maintain the same data structure where the list of entries would include the new transactions and the responseType value will be snapshot. The command can include an optional data property to filter the responses to a single organisation. A response will be send for each subscribed organisation and will include an organisationId property to indicate to which organisation the response is relevant. The response includes a data property which is an object with a single key entries which in turn is an array of transaction objects.

Subscribe Orders Command Schema (optional)

Name	Type	Description
organisationId	number	Unique identifier for the organisation subject to the transaction subscription request

Set Transaction Event Schema

Name	Type	Description
id	string	Unique identifier of the transaction
organisationId	number	Unique identifier for the organisation associated with the transaction
userId	number	Unique identifier of the user associated with the transaction
accountId	number	Unique identifier for the account
amount	string	Quantity of asset in transaction without consideration of decimal places values (decimal places defined in `decimalPlaces` from Assets Schema)
referenceId	string	Unique reference to event (where event can be an execution or a notification for a deposit etc.)
created	string	Time of transaction
ledgerType	string	Value is one of `credit` or `debit`
reportType	string	Value can be one of - `commission`, `execution`, `deposit`, `fee`, `coupon`, `manualCorrection`, `interest`, `dividend`, `withdrawal` or `tax`
commissionReference	string	Unique identifier of the commission if applicable
assetId	number	Unique identifier of the asset

set-transactions event updates must completely replace the previous state. For example, if your transactions list has the following state:

[ { "id": "1631014099470021", "organisationId": 3, "userId": 5, "accountId": 2786123124, "amount": "1234", "referenceId": "1631014099467372", "created": "1631014099463903", "ledgerType": "credit", "reportType": "execution", "commissionReference": "0", "assetId": 7 }, { "id": "1631014099468016", "organisationId": 3, "userId": 5, "accountId": 2786123148, "amount": "121", "referenceId": "1631014099467372", "created": "1631014099463907", "ledgerType": "debit", "reportType": "commission", "commissionReference": "1631014043667348", "assetId": 7 } ]

an event to update the list of transactions you have would be in the form:

{ "status": "OK", "action": "set-transactions", "data": { "entries": [ { "id": "1631014364507061", "organisationId": 3, "userId": 5, "accountId": 2786123124, "amount": "109", "referenceId": "1631014364505500", "created": "1631014364499900", "ledgerType": "credit", "reportType": "execution", "commissionReference": "0", "assetId": 7 }, { "id": "1631014099470021", "organisationId": 3, "userId": 5, "accountId": 2786123124, "amount": "1234", "referenceId": "1631014099467372", "created": "1631014099463903", "ledgerType": "credit", "reportType": "execution", "commissionReference": "0", "assetId": 7 }, { "id": "1631014099468016", "organisationId": 3, "userId": 5, "accountId": 2786123148, "amount": "121", "referenceId": "1631014099467372", "created": "1631014099463907", "ledgerType": "debit", "reportType": "commission", "commissionReference": "1631014043667348", "assetId": 7 } ] } }

and the resulting transactions state will be:

[ { "id": "1631014364507061", "organisationId": 3, "userId": 5, "accountId": 2786123124, "amount": "109", "referenceId": "1631014364505500", "created": "1631014364499900", "ledgerType": "credit", "reportType": "execution", "commissionReference": "0", "assetId": 7 }, { "id": "1631014099470021", "organisationId": 3, "userId": 5, "accountId": 2786123124, "amount": "1234", "referenceId": "1631014099467372", "created": "1631014099463903", "ledgerType": "credit", "reportType": "execution", "commissionReference": "0", "assetId": 7 }, { "id": "1631014099468016", "organisationId": 3, "userId": 5, "accountId": 2786123148, "amount": "121", "referenceId": "1631014099467372", "created": "1631014099463907", "ledgerType": "debit", "reportType": "commission", "commissionReference": "1631014043667348", "assetId": 7 } ]

Custody

Subscribe To Deposits command

{
  "action": "subscribe-deposits",
  "data": {
    "organisationId": 1
  }
}

Set Deposits event

{
  "status": "OK",
  "action": "set-deposits",
  "data": {
    "1658732301686225": {
      "accountId": 118,
      "amount": "300000",
      "created": "1658732301000000",
      "id": "1658732301686225",
      "assetId": 1,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658732301544438",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658732301000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658730084256007": {
      "accountId": 118,
      "amount": "300000",
      "created": "1658730084000000",
      "id": "1658730084256007",
      "assetId": 1,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658730084120637",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658730084000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658730034966343": {
      "accountId": 118,
      "amount": "300000",
      "created": "1658730034000000",
      "id": "1658730034966343",
      "assetId": 1,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658730034833466",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658730034000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658729853582198": {
      "accountId": 120,
      "amount": "300000",
      "created": "1658729853000000",
      "id": "1658729853582198",
      "assetId": 2,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658729853446574",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658729853000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658729762673091": {
      "accountId": 120,
      "amount": "300000",
      "created": "1658729762000000",
      "id": "1658729762673091",
      "assetId": 2,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658729762538762",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658729762000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658729594686221": {
      "accountId": 120,
      "amount": "300000",
      "created": "1658729594000000",
      "id": "1658729594686221",
      "assetId": 2,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658729594553480",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658729594000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658728733406117": {
      "accountId": 120,
      "amount": "300000",
      "created": "1658728733000000",
      "id": "1658728733406117",
      "assetId": 2,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658728733271718",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658728733000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658728201164503": {
      "accountId": 120,
      "amount": "300000",
      "created": "1658728201000000",
      "id": "1658728201164503",
      "assetId": 2,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658728201033042",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658728201000000",
      "userId": 13,
      "walletAddress": ""
    }
  },
  "responseType": "snapshot",
  "type": "deposits",
  "timestamp": "2023-03-10T07:31:20.908Z"
}

Send a subscribe-deposits command to subscribe to deposit updates. It will return a set-deposits event that contains the 1000 most recent deposit notifications for the organisation(s) of which you are permissioned. Subsequent deposits or updates to deposits will also cause a set-deposits event to be returned with only updated values; these updates must be deeply merged from the previous state. An optional data property can be included in the command to filter the responses to a single organisation.

A response will be send for each subscribed organisation and will include an organisationId property to indicate to which organisation the response is relevant. The response includes a data property which is an object with a single key entries which in turn is an array of transaction objects.

Subscribe Deposits Command Schema

Name	Type	Description
organisationId	number	Unique identifier for the organisation subject to the deposit submission

Set Deposit Event Schema

Name	Type	Description
[key]		Unique identifier of the deposit
accountId	number	Unique identifier of the ledger account
amount	string	Amount of the deposit without consideration of decimal places values (decimal places defined in `decimalPlaces` from Assets Schema)
created	string	Time of transaction
id	string	Unique identifier of the deposit
assetId	number	Unique identifier of the asset
organisationId	number	Unique identifier of the client
reason	string	Additional details for deposits that do not successfully complete
referenceId	string	For cash - unique identifier that needs to be included in the reference field of the payment. For security assets- wallet address assigned as recipient address for transfer
status	string	Current state of the transaction, can be submitted, pending, cancelled, rejected or completed
type	string	Only `Deposit` returned as value
updated	string	Time stamp of the last time an action occurred on the deposit notification
userId	number	Unique identifier of the user who submitted the deposit notification
walletAddress	string	Deprecated field that returns empty string

Subscribe to Withdrawals command

{
  "action": "subscribe-withdrawals",
  "data": {
    "organisationId": 1
  }
}

Set Withdrawals event

{
  "status": "OK",
  "action": "set-withdrawals",
  "data": {
    "1660545047277119": {
      "accountId": 118,
      "amount": "100",
      "created": "1660545047000000",
      "id": "1660545047277119",
      "assetId": 1,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "123456",
      "status": "Pending",
      "type": "Withdrawal",
      "updated": "1660545047000000",
      "userId": 27,
      "walletAddress": ""
    },
    "1660542988806807": {
      "accountId": 118,
      "amount": "1000",
      "created": "1660542988000000",
      "id": "1660542988806807",
      "assetId": 1,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "12345",
      "status": "Pending",
      "type": "Withdrawal",
      "updated": "1660542988000000",
      "userId": 27,
      "walletAddress": ""
    }
  },
  "responseType": "snapshot",
  "type": "withdrawals",
  "timestamp": "2023-03-10T07:36:31.616Z"
}

Send a subscribe-withdrawals command to subscribe to withdrawal updates. It will return a set-withdrawals event that contains the 1000 most recent withdrawal notifications for the organisation(s) of which you are permissioned. Subsequent withdrawals or updates to withdrawals will also cause a set-withdrawals event to be returned with only updated values; these updates must be deeply merged from the previous state. An optional data property can be included in the command to filter the responses to a single organisation.

Subscribe Withdrawals Command Schema

Name	Type	Description
organisationId	number	Unique identifier for the organisation subject to the withdrawal submission

Set Withdrawal Event Schema

Name	Type	Description
[key]		Unique identifier of the withdrawal
accountId	number	Unique identifier of the ledger account
amount	string	Amount of the withdrawal without consideration of decimal places values (decimal places defined in `decimalPlaces` from Assets Schema)
created	string	Time of transaction
id	string	Unique identifier of the withdrawal
assetId	number	Unique identifier of the asset
organisationId	number	Unique identifier of the client
reason	string	Additional details for withdrawals that do not successfully complete
referenceId	string	Unique reference for withdrawal
status	string	Current state of the transaction, can be submitted, pending, cancelled, rejected or completed
type	string	Only `Withdrawal` returned as value
updated	string	Time stamp of the last time an action occurred on the withdrawal notification
userId	number	Unique identifier of the user who submitted the withdrawal notification
walletAddress	string	Deprecated field that returns empty string

Submit Deposit

Submit Deposit command

{
  "action": "submit-deposit",
  "data": {
    "accountId": 114,
    "amount": "10000",
    "assetId": 5,
    "organisationId": 27,
    "referenceId": "1676615598286"
  }
}

Submit Deposit Response event

{
  "status": "OK",
  "action": "submit-deposit-response",
  "data": {
    "accountId": 114,
    "reference": "0x7b87864f860c84f811dc4cd197de7468edd93267",
    "userId": 72,
    "requestId": "1676615627210920",
    "created": "1676615627210921",
    "walletAddress": "0x7b87864f860c84f811dc4cd197de7468edd93267",
    "whitelistedWalletAddress": ""
  },
  "type": "notifications",
  "timestamp": "2023-02-17T06:33:50.253Z"
}

Send a submit-deposit command to submit a deposit notification. The response will be a submit-deposit-response event that will either return an error with an error reason or return an “OK” with the schema described below.

Submit Deposit Schema

Name	Type	Description
data	Data	Deposit details

Submit Deposit Data Schema

Name	Type	Description
accountId	number	Unique identifier of the ledger account
amount	string	Amount of the deposit (supports decimal values)
assetId	number	Unique identifier of the asset to be deposited
organisationId	number	Unique identifier for the organisation subject to the deposit submission
referenceId	string	Not in use

Submit Deposit Response Event Schema

Name	Type	Description
accountId	number	Unique identifier of the ledger account
referenceId	string	For cash - unique identifier that needs to be included in the reference field of the payment. For security assets- wallet address assigned as recipient address for transfer
userId	number	Unique identifier of the user who submitted the deposit notification
requestId	string	Unique system identifier of the deposit (corresponds to id field in Set Deposits Schema)
created	string	Time of transaction submission
walletAddress	string	Internal use only
whitelistedWalletAddress	string	Not in use

Submit Withdrawal

Submit Withdrawal command

{
  "action": "submit-withdrawal",
  "data": {
    "accountId": 108,
    "amount": "100.00",
    "assetId": 5,
    "organisationId": 27,
    "referenceId": "1676615598286"
  }
}

Submit Withdrawal Response event

{
  "status": "OK",
  "action": "submit-withdrawal-response",
  "data": {
    "accountId": 108,
    "userId": 72,
    "referenceId": "1676616969568760",
    "requestId": "1676616969570956",
    "created": "1676616969570957"
  },
  "type": "notifications",
  "timestamp": "2023-02-17T06:56:10.613Z"
}

Send a submit-withdrawal command to submit a withdrawal notification. The response will be a submit-withdrawal-response event that will either return an error with an error reason or return an “OK” with the schema described below.

Submit Withdrawal Schema

Name	Type	Description
data	Data	Withdrawal details

Submit Withdrawal Data Schema

Name	Type	Description
accountId	number	Unique identifier of the ledger account
amount	string	Amount of the withdrawal (supports decimal values)
assetId	number	Unique identifier of the asset to be withdrawn
organisationId	number	Unique identifier for the organisation subject to the withdrawal submission
referenceId	string	Not in use

Submit Withdrawal Response Event Schema

Name	Type	Description
accountId	number	Unique identifier of the ledger account
referenceId	string	Unique reference for withdrawal
userId	number	Unique identifier of the user who submitted the withdrawal notification
requestId	string	Unique system identifier of the withdrawal (corresponds to id field in Set Withdrawals Schema)
created	string	Time of transaction submission

Cancel Deposit

Cancel Deposit command

{
  "action": "cancel-deposit",
  "data": {
    "organisationId": 27,
    "requestId": "1676615627210920"
  }
}

Cancel Deposit Response event

{
  "status": "OK",
  "action": "cancel-deposit-response",
  "data": {
    "userId": 72,
    "status": "creditCancelled",
    "reason": "creditUserCancelled",
    "requestId": "1676615627210920",
    "created": "1676616709917337"
  },
  "type": "notifications",
  "timestamp": "2023-02-17T06:51:50.994Z"
}

Send a cancel-deposit command to cancel a deposit notification. The response will be a cancel-deposit-response event that will either return an error with an error reason or return an “OK” with the schema described below.

Cancel Deposit Schema

Name	Type	Description
requestId	string	Unique system identifier of the deposit ((corresponds to id field in Set Deposits Schema)
organisationId	number	Unique identifier for the organisation subject to the deposit cancellation

Cancel Deposit Response Event Schema

Name	Type	Description
userId	number	Unique identifier of the user who submitted the deposit notification
status	string	Current status of the deposit notification, only value is `creditCancelled`
reason	string	Reason for cancellation, only value is `creditUserCancelled`
requestId	string	Unique system identifier of the deposit (corresponds to id field in Set Deposits Schema)
created	string	Time of transaction

Cancel Withdrawal

Cancel Withdrawal command

{
  "action": "cancel-withdrawal",
  "data": {
    "organisationId": 27,
    "requestId": "1676616969570956"
  }
}

Cancel Withdrawal Response event

{
  "status": "OK",
  "action": "cancel-withdrawal-response",
  "data": {
    "userId": 72,
    "status": "debitCancelled",
    "reason": "debitUserCancelled",
    "requestId": "1676616969570956",
    "created": "1676618856703258"
  },
  "type": "notifications",
  "timestamp": "2023-02-17T07:27:37.623Z"
}

Send a cancel-withdrawal command to cancel a withdrawal notification. The response will be a cancel-withdrawal-response event that will either return an error with an error reason or return an “OK” with the schema described below.

Cancel Withdrawal Schema

Name	Type	Description
requestId	string	Unique system identifier of the withdrawal (corresponds to id field in Set Withdrawals Schema)
organisationId	number	Unique identifier for the organisation subject to the withdrawal cancellation

Cancel Withdrawal Response Event Schema

Name	Type	Description
userId	number	Unique identifier of the user who submitted the withdrawal notification
status	string	Current status of the withdrawal notification, only value is `debitCancelled`
reason	string	Reason for cancellation, only value is `debitUserCancelled`
requestId	string	Unique system identifier of the withdrawal (corresponds to id field in Set Withdrawals Schema)
created	string	Time of transaction

Submit Transfer

Submit Transfer command

{
  "action": "submit-transfer",
  "data": {
    "amount": "10.00",
    "organisationId": 27,
    "sourceAccountId": 105,
    "targetAccountId": 106,
    "referenceId": "1676619797797"
  }
}

Submit Transfer Response event

{
  "status": "OK",
  "action": "submit-transfer-response",
  "data": {
    "requestId": "1676623261301525"
  },
  "type": "notifications",
  "timestamp": "2023-02-17T07:43:42.769Z"
}

Send a submit-transfer command to transfer funds between two accounts. The system will reject a transfer if the two accounts provided do not share the same asset id. The system will also reject a transfer if the two accounts provided are not for the same client. The response will be a submit-transfer-response event that will either return an error with an error reason or an “OK” with the schema described below.

Submit Transfer Schema

Name	Type	Description
amount	string	Amount of the transfer without consideration of decimal places values (supports decimal values)
sourceAccountId	number	Unique identifier of the ledger account sending the amount
targetAccountId	number	Unique identifier of the ledger account receiving the amount
referenceId	string	Unique reference for the transfer
organisationId	number	Unique identifier for the organisation subject to the transfer. Must match the organisation id associated with both target and source account ids.

Submit Transfer Response Event Schema

Name	Type	Description
requestId	string	Unique system identifier of the transfer (currently a known issue that this is sent as two numbers and a boolean instead of a string)

ACE API Spec v2.0.0

REST API

The Archax REST API allows developers to retrieve authentication tokens and instrument information. All resources are defined under the following URL:

https://ace-auth.archax.com/api/2.0

All responses from the REST API are wrapped inside this response wrapper. JWT tokens must be obtained through the /api/2.0/ endpoints.

Sample Request

{
  "email": "user@archax.com",
  "password": "password"
}

200 Response

{
  "status": "OK",
  "data": {
    "status": "OK",
    "jwt": "valid-token",
    "mfa": false,
    "timestamp": "2021-05-25T04:21:38.057Z"
  },
  "timestamp": "2021-05-25T04:21:38.058Z"
}

401 Response

{
  "status": "ERROR",
  "error": [
    {
      "msg": "Email and password combination are incorrect"
    }
  ],
  "timestamp": "2021-06-07T06:39:21.413Z"
}

POST /login

An endpoint that allows developers to submit an email and a password in exchange for a JWT.

Request Schema

Name	Type	Required	Description
email	string	true	Email address registered in the system
password	string	true	Password registered with email address

Response Schema

Name	Type	Description
status	status	OK for success, ERROR otherwise
jwt	string	A JSON web token that expires after 30 minutes
mfa	bool	A flag indicating whether multi-factor authentication is enabled
timestamp	timestamp	The response timestamp

Renew-jwt

Request to

https://ace-auth.archax.com/api/2.0/renew-jwt

200 Response

{
  "status": "OK",
  "data": {
    "jwt": "valid-token"
  },
  "timestamp": "2021-05-25T04:21:38.058Z"
}

401 Response

{
  "status": "ERROR",
  "error": [
    {
      "msg": "Too many requests"
    }
  ],
  "timestamp": "2021-06-07T06:39:21.413Z"
}

POST /renew-jwt

An endpoint that provides an updated JWT. Old JWT must be included as bearer token.

Response Schema

Name	Type	Description
jwt	string	A JSON web token that expires after 30 minutes

Payment Provider details

Request to

https://ace-auth.archax.com/api/2.0/rest-gateway/account/fiat-account/1/regulated

200 Response

{
  "status": "OK",
  "data": {
    "accountId": 1,
    "accountName": "Archax Client Money C",
    "accountNumber": "00000058",
    "paymentProvider": {
      "address1": "4th Floor, Prologue Works",
      "address2": "25 Marsh Street",
      "address3": "Bristol, BS1 4AX",
      "name": "ClearBank Limited"
    },
    "sortCode": "04-05-78"
  },
  "timestamp": "2023-03-10T10:02:09.398Z"
}

401 Response

{
  "status": "ERROR",
  "error": [
    {
      "msg": "Fiat account is not available for currencyId 5"
    }
  ],
  "timestamp": "2023-03-10T10:04:57.392Z"
}

GET https://ace-auth.archax.com/api/2.0/rest-gateway/account/fiat-account/:currencyId/:regType

An endpoint that provides account details for use when depositing cash with Archax. Must include bearer token with JWT that has appropriate permissions.

Url path parameters

Name	Type	Description
currencyId	number	Instrument id of cash to be deposited
regType	string	Indicates if payment is to CASS protected accounts (for regulated activity) or the non-CASS account (for unregulated activity). Value is either `regulated` or `unregulated`

Response Schema

Name	Type	Description
accountId	number	Internal identifier for Archax
accountName	string	Name to be used as beneficiary in payment
accountNumber	string	Account number to be used for beneficiary in payment
paymentProvider	Payment Provider	Beneficiary bank name and address
sortCode	string	Payment routing code for beneficiary bank. This field can include either a sort code, a bank identifier code or a FEDABA depending on the currency of the account

Payment Provider Schema

Name	Type	Description
name	string	Beneficiary bank name
address1	string	1st line of address for beneficiary bank
address2	string	2nd line of address for beneficiary bank
address3	string	3rd line of address for beneficiary bank

Instrument Details

Request to

https://ace-auth.archax.com/api/2.0/rest-gateway/reporting/instrument/6

200 Response

{
  "status": "OK",
  "data": {
    "id": 6,
    "name": "Apple inc.",
    "symbol": "APPa",
    "currency": "USD",
    "description": "Apple inc.",
    "status": "Trading",
    "type": "security",
    "quantityDecimalPlaces": 0,
    "priceDecimalPlaces": 2,
    "externalId": 3
  },
  "meta": {
    "category": "Exchange",
    "firstTradeDate": "2020-09-02",
    "fullName": "APPLE INC COM STK NPV (CDI)",
    "initialPrice": "680.25",
    "isin": "US0378331005",
    "lei": "HWUPKR0MPOU8FGXBT394",
    "mic": "ARCH",
    "minimumOrderValue": "0.01",
    "tickSize": "0.01",
    "tokeniser": "Securitize",
    "website": "www.apple.com"
  },
  "timestamp": "2023-03-09T13:08:34.282Z"
}

401 Response

{
  "status": "ERROR",
  "error": [
    {
      "msg": "Instrument not found"
    }
  ],
  "timestamp": "2021-06-07T06:39:21.413Z"
}

GET https://ace-auth.archax.com/api/2.0/rest-gateway/reporting/instrument/:instrumentId

An endpoint that provides details of an asset. Must include bearer token with JWT that has appropriate permissions to get all fields. Submitting a request with no bearer token will result in a response with a subset of the below listed fields.

Url path parameters

Name	Type	Description
instrumentId	number	Unique identifier of the asset

Response Schema

Name	Type	Description
id	number	Unique identifier of the asset
name	string	Name of the asset
symbol	string	Ticker symbol of the asset
currency	string	Symbol of the currency in which the asset is priced for trading
description	string	Additional details about the asset
status	string	Current status of the asset with regards to trading
type	string	Asset type (can be `security`, `crypto` or `cash`)
quantityDecimalPlaces	number	Number of decimal places available for use with any field that accepts a quantity for the asset
priceDecimalPlaces	number	Number of decimal places used by the system when accepting a price for the asset
externalId	number	Internal use only
created	string	Internal use only
updated	string	Internal use only
meta	Meta	Additional static data about the asset
close	number	Close price of the asset without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
open	number	Open price of the asset without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)

Meta Schema

Name	Type	Description
accidents	string	Not in use
address	string	Address of the issuer
advisers	string	Not in use
affiliations	string	Not in use
approvalDate	string	Date and time the issuer has approved admission to trading or trading in its financial instruments on the Archax exchange
archaxMarket	string	Not in use
associationArticles	string	Not in use
auditReports	string	Not in use
availabilityOfCapital	string	Not in use
availabilityOfPersonnel	string	Not in use
benefitsOnTermination	string	Not in use
blockchainProtocol	string	Blockchain on which the asset was issued as a token or equivalent
bondBasePointSpread	string	Number of basis points above or below the index used to calculate accrued interest
bondFixedRate	string	The fixed rate percentage of a return on a debt instrument when held until maturity date expressed as a percentage (i.e. 7.0 means 7%)
bondIdentifier	string	ISIN of the index/benchmark used to set the floating rate of a return on a debt instrument
bondIndex	string	Alias name of the index/benchmark used to set the floating rate of a return on a debt instrument
bondMaturityDate	string	The maturity date of a debt instrument
bondName	string	Name of the index/benchmark used to set the floating rate of a return on a debt instrument
bondSeniority	string	Identifies the type of bond
bondTermUnit	string	The unit used for the term of the index or benchmark or a floating rate debt instrument (DAYS, WEEK, MNTH or YEAR)
bondTermValue	string	3 digit integer indicating the number of units of the term of the index or benchmark of a floating rate debt instrument
bondTotalIssued	string	Total issued nominal amount in monetary value (expressed in currency reported in currency field)
bondType	string	The type of bond: senior, debt, mezzanine, subordinated debt or junior debt
brexitImpact	string	Not in use
category	string	Category of the asset
cfiCode		The instrument classification expressed using the full (6 character) ISO 10962 CFI code that defines the type of instrument
companyRisks	string	Not in use
competition	string	Not in use
contactInfo	string	Contact information of the issuer of the asset
contractAddress	string	Address on the blockchain of the smart contract that manages the asset
corporateAdviser	string	Not in use
dependencies	string	Not in use
directors	string	Not in use
dividends	string	Not in use
domicile	string	Not in use
environmental	string	Not in use
envRating	string	Environmental rating provided as part of ESG rating
eps	string	Not in use
esgDescription	string	Details of the ESG rating provided
esgLogo	string	Logo of the provider of the ESG rating
estimatednetAmountPrincipalUse	string	Not in use
excessPayment	string	Not in use
exchangeRate	string	Not in use
financialInformation	string	Not in use
financialInformationStatement	string	Not in use
firstIssuanceDate	string	Date on which a debt instrument was issued and began to accrue interest
firstTradeDate	string	Date and time of the admission to trading on the trading venue or the date and time when the instrument was first traded or an order/quote was first received by Archax exchange
fullName	string	Full name of the instrument as registered to the ISIN
fullNameAndFunction	string	Not in use
generalMeetings	string	Not in use
governanceRating	string	Governance rating provided as part of ESG rating
highlights	string	Not in use
historyOfIssue	string	Not in use
incomeTaxParticulars	string	Not in use
incorporationDate	string	Date of incorporation of the issuer of the asset
initialPrice	string	Initial price of the asset when first admitted to the exchange
instrumentNews	string	Not in use
interestRates	string	Not in use
introVideoUrl	string	Not in use
investors	string	Not in use
isin	string	International securities identification number as provided by a national numbering agency
issuanceSize	string	Issuance size of the certificate expressed in Euros. Also used for bonds to show total bond size
jurisdictions	string	Not in use
lastYearRumunerationPaid	string	Not in use
lei	string	Legal entity identifier registered with the issuer of the asset
liquidityRisks	string	Not in use
litigation	string	Not in use
locationsDenied	string	Not in use
lockIn	string	Not in use
management	string	Not in use
marketOverview	string	Not in use
marketRisks	string	Not in use
mic	string	Market identifier code of the exchange on which the asset is traded
minimumOrderValue	string	Lowest value (price * quantity) the exchange will accept for an order to buy or sell the asset
mission	string	Not in use
nominalValueUnit	string	Nominal value of each unit of debt instrument as priced in the associated currency
oldInstrumentId	string	Not in use
ongoingPrincipalInvestments	string	Not in use
operational	string	Not in use
operationalRisks	string	Not in use
partners	string	Not in use
personalBankruptcies	string	Not in use
personsResponsible	string	Not in use
placeOfRegistration	string	Not in use
platform	string	Internal use only
priceMultiplier	string	Not in use
pricipalActivity	string	Not in use
primaryIssuancePlatform	string	Not in use
proceedsOfOffer	string	Not in use
profitForecasts	string	Not in use
projectDescription	string	Not in use
publicSanctions	string	Not in use
recentInsolvencies	string	Not in use
recentPartnerships	string	Not in use
regulation	string	Not in use
regulatoryBodies	string	Not in use
relatedIsin	string	Not in use
relatedPartyTransactions	string	Not in use
requestDate	string	Date and time of the request for admission to trading on the trading venue
researchPolicy	string	Not in use
securitiesClassAndTypes	string	Not in use
securitiesLegislation	string	Not in use
securitiesTradeRestrictions	string	Not in use
sedol	string	Not in use
segment	string	Not in use
settlementDate	string	Date expressed in T+n value of when settlement occurs n days after a trade (Same Day (T) for most assets in Archax exchange)
shareClass	string	Not in use
shareholderRights	string	Not in use
shareholdings	string	Not in use
shareNumber	string	For shares and depositary receipts: The total number of outstanding instruments. For ETFs: Number of units issued for trading
shareNumberExceeding	string	The total number of shares corresponding to holdings exceeding 5% of total voting rights of the issuer
shareRegisterCountry	string	Not in use
shortDescription	string	Not in use
shortName	string	Short name registered to the ISIN in accordance with ISO 18774 (Financial Instrument Short Name)
significantDates	string	Not in use
socialMedia	string	Not in use
socialRating	string	Social rating provided as part of ESG rating
statementOfCompliance	string	Not in use
statutoryAuditor	string	Not in use
taxation	string	Not in use
technology	string	Not in use
terminationDate	string	Date and time of when asset will cease to trade on Archax exchange
terms	string	Not in use
termsAndConditions	string	Not in use
terrorism	string	Not in use
tickSize	string	Smallest price variation allowed when submitting an order for the asset
tokeniser	string	Entity that created the token smart contract used to issue the asset
transferStatus	string	Not in use
trendInformation	string	Not in use
underlyingInstrumentId	string	Not in use
unpriSignatory	string	Indicator if issuer of asset is a signatory to the United Nations Principles for Responsible Investment
unspentConvictions	string	Not in use
useOfProceeds	string	Not in use
vwap	string	Not in use
website	string	Website associated with the asset and/or issuer
yield	string	Not in use

Open Orders

Request to

https://ace-auth.archax.com/api/2.0/open-orders/1

200 Response

{
  "status": "OK",

  "data": [
    {
      "quantity": "1",
      "untradedQuantity": "1",
      "limitPrice": "27185",
      "created": "1681456445562335",
      "instrumentId": 5,
      "executions": [],
      "id": "1681456445562335",
      "side": "sell",
      "userReference": "user_reference_1234"
    },
    {
      "quantity": "1",
      "untradedQuantity": "1",
      "limitPrice": "24185",
      "created": "1681456418146386",
      "instrumentId": 5,
      "executions": [],
      "id": "1681456418146386",
      "side": "buy",
      "userReference": "user_reference_12345"
    }
  ],

  "timestamp": "2023-04-14T07:14:10.666Z"
}

GET /open-orders/:organisationId

An endpoint that returns a list of all open orders for the user’s organisation. JWT must be included as bearer token.

Url path parameters

Name	Type	Description
organisationId	number	Unique identifier of the client organisation subject to the open-order query

Response Schema

Name	Type	Description
id	string	Unique order identifier
quantity	string	Order quantity without consideration of decimal places values (decimal places defined in `quantityDecimalPlaces` from Instruments Schema)
untradedQuantity	string	Quantity of unfilled portion of order without consideration of decimal places values (decimal places defined in `quantityDecimalPlaces` from Instruments Schema)
limitPrice	string	Order limit price without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
created	string	Timestamp on when the trade was executed (ms)
instrumentId	number	Unique identifier of the asset
executions	empty array	Not used
side	string	Order side, possible values: `buy`, `sell`
userReference	string	Value provided as `actionRef` in original submission of order

WebSocket API

The Archax WebSocket API allows developers to subscribe to real-time market data feeds.

Additionally, the API accepts commands for the creation and cancellation of orders.

Connection

Login command

{
  "action": "login",
  "service": "core",
  "token": "valid-token"
}

Successful login event

{
  "action": "user-login-success",
  "data": [],
  "description": "Authorisation successful",
  "status": "OK",
  "type": "user-login"
}

Failed login event

{
  "action": "user-login-failed",
  "data": [],
  "description": "Authorisation failed",
  "status": "ERROR",
  "type": "user-login"
}

The public WebSocket endpoint is wss://ace-auth.archax.com/api/2.0/gateway.

To login to the API you must obtain a JWT token from API v2 REST login endpoint. In combination with the JWT, you must specify the login action and the core service.

Once your login credentials have been verified, you will receive a user-login-success event. Otherwise you will receive a user-login-failed event and you will then be disconnected.

Renew JWT

Renewal command

{
  "action": "renew-jwt"
}

Successful renewal event

{
  "status": "OK",
  "action": "renew-jwt-response",
  "data": {
    "jwt": "your-token"
  },
  "type": "notifications",
  "timestamp": "2023-11-09T10:56:56.545Z"
}

Market Data

Subscribe to Instruments command

{
  "action": "subscribe-instruments"
}

Set Instruments event

{
  "status": "OK",
  "action": "set-instruments",
  "data": {
    "4": {
      "currency": "EUR",
      "decimals": 2,
      "description": "Fake AG SHRS",
      "id": 4,
      "marketStatus": "open",
      "name": "FAKE SHRS",
      "priceDecimalPlaces": 2,
      "quantityDecimalPlaces": 0,
      "regulatedStatus": "eligible",
      "symbol": "FAKe",
      "tradingStatus": "Trading",
      "type": "security",
      "venueId": "ARCHAX",
      "tickSize": "0.01"
    },
    "5": {
      "currency": "EUR",
      "decimals": 2,
      "description": "Fake Swiss Property",
      "id": 5,
      "marketStatus": "open",
      "name": "FKE Swiss Property",
      "priceDecimalPlaces": 2,
      "quantityDecimalPlaces": 0,
      "regulatedStatus": "eligible",
      "symbol": "FAKa",
      "tradingStatus": "Trading",
      "type": "security",
      "venueId": "ARCHAX",
      "tickSize": "1.00"
    },
    "9": {
      "currency": "USD",
      "decimals": 4,
      "description": "Fake BTC Ticker",
      "id": 9,
      "marketStatus": "closed",
      "name": "FKE BTC",
      "priceDecimalPlaces": 2,
      "quantityDecimalPlaces": 8,
      "regulatedStatus": "eligible",
      "symbol": "FBTC",
      "tradingStatus": "Suspended",
      "type": "crypto",
      "venueId": "ARCHAX",
      "tickSize": "0.1"
    }
  },
  "type": "instruments",
  "timestamp": "2021-07-08T07:00:20.190Z"
}

Send a subscribe-instruments command to subscribe to instrument updates. It will initially return a set-instruments event that contains all assets available on the exchange while subsequent set-instruments events will only include assets and properties that have since been updated. The data property is an object keyed by instrumentId, with the following details:

Set Instruments Event Schema

Name	Type	Description
[key]		Identifier of the asset
currency	string	3-letter currency code for the asset
decimals	number	The number of significant decimal places for the asset’s price
description	string	The full name of the asset
id	number	Unique identifier of the asset
marketStatus	string	Current market status for the asset. Possible values are: `open`, `closed` and `closing auction`
name	string	The short name for the asset
priceDecimalPlaces	number	Number of decimal places used by the system when accepting a price for the asset
quantityDecimalPlaces	number	Number of decimal places used by the system when accepting a quantity for the asset
regulatedStatus	string	The regulated status of the asset. Possible values are: `eligible` and `ineligible`
symbol	string	Ticker symbol for the asset
tradingStatus	string	Current trading status for the asset. Possible values are: `Created`, `Pre-Live`, `Trading`, `Suspended` and `Terminated`
type	string	The asset type. Possible values are: `security` and `crypto`
venueId	string	Default value: `ARCHAX`
tickSize	string	Minimum price amount an instrument can move

Subscribe to Market Quotes command

{
  "action": "subscribe-market-quotes"
}

Set Market Quotes event (initial)

{
  "status": "OK",
  "action": "set-market-quotes",
  "data": {
    "1": {
      "askPrice": "",
      "askQty": "",
      "bidPrice": "",
      "bidQty": "",
      "changePercent": "-38.60",
      "changePrice": "-6408",
      "closePrice": "16600",
      "cumulativeUnits": "",
      "cumulativeValue": "",
      "highPrice": "10192",
      "instrumentId": 1,
      "lastPrice": "10192",
      "lastQty": "1",
      "lowPrice": "10192",
      "openPrice": "10192",
      "sevenDayChange": "1068",
      "sevenDayChangePercentage": "11.71",
      "sevenDayClosePrice": "9124"
    },
    "2": {
      "askPrice": "",
      "askQty": "",
      "bidPrice": "",
      "bidQty": "",
      "changePercent": "-24.19",
      "changePrice": "-4112",
      "closePrice": "17000",
      "cumulativeUnits": "",
      "cumulativeValue": "",
      "highPrice": "13809",
      "instrumentId": 2,
      "lastPrice": "12888",
      "lastQty": "1",
      "lowPrice": "12967",
      "openPrice": "12888",
      "sevenDayChange": "867",
      "sevenDayChangePercentage": "7.21",
      "sevenDayClosePrice": "12021"
    },
    "3": {
      "askPrice": "",
      "askQty": "",
      "bidPrice": "",
      "bidQty": "",
      "changePercent": "0.00",
      "changePrice": "",
      "closePrice": "36900",
      "cumulativeUnits": "178",
      "cumulativeValue": "6723900",
      "highPrice": "39740",
      "instrumentId": 3,
      "lastPrice": "36900",
      "lastQty": "1287",
      "lowPrice": "36500",
      "openPrice": "36000",
      "sevenDayChange": "-3100",
      "sevenDayChangePercentage": "-7.75",
      "sevenDayClosePrice": "40000"
    }
  },
  "type": "market-quotes",
  "timestamp": "2021-10-05T10:53:59.201Z"
}

Set Market Quotes event (update)

{
  "status": "OK",
  "action": "set-market-quotes",
  "data": {
    "3": {
      "askPrice": "36555",
      "askQty": "250"
    }
  }
}

Set Market Quotes event (reset specified properties)

{
  "status": "OK",
  "action": "set-market-quotes",
  "data": {
    "3": {
      "bidPrice": "",
      "bidQty": "",
      "openPrice": ""
    }
  }
}

Send a subscribe-market-quotes command to subscribe to real-time pricing updates for all instruments available in the market. It initially returns a set-market-quotes event that includes the market quotes for each instrument. Subsequent events only contain updates for the included fields.

Each value in the data property is keyed by instrumentId.

Set Market Quotes Event Schema

Name	Type	Description
[key]		Identifier of the asset
askPrice	string	Best asking price for the asset without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
askQty	string	Number of units on offer at the `askPrice`
bidPrice	string	Best bid price for the asset without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
bidQty	string	Number of units requested at the `bidPrice`
changePercent	string	The percentage difference between the `lastPrice` and `closePrice`
changePrice	string	The difference between the `lastPrice` and `closePrice` without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
closePrice	string	The asset’s last traded price from the previous trading session without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
cumulativeUnits	string	The cumulative volume of units traded within the current trading session
cumulativeValue	string	The cumulative value of all trades on the asset for the current trading session without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
instrumentId	number	Unique identifier of the asset
lastPrice	string	Last traded price for the asset without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
highPrice	string	Highest trade price for the asset during the current trading session without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
lowPrice	string	Lowest trade price for the asset during the current trading session without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
lastQty	string	Last traded quantity for the asset
openPrice	string	Price at which the first execution of the day for the asset occurred without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
sevenDayChange	string	The difference between `closePrice` and `sevenDayClosePrice` without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
sevenDayChangePercentage	string	The percentage difference between the `closePrice` and `sevenDayClosePrice`
sevenDayClosePrice	string	The asset’s close price 7 days prior without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Instruments Schema)

askPrice, bidPrice, changePrice, closePrice, cumulativeValue, highPrice, lastPrice, lowPrice, openPrice, sevenDayChange and sevenDayClosePrice would always be returned as a whole number. The number of decimal places for each asset then determines how these price values are formatted. Use the priceDecimalPlaces property returned by the set-instruments event to determine the number of decimal places for the value in these fields.

If the value returned for askPrice is 2356 and the asset’s priceDecimalPlaces property is 3. The actual askPrice is then obtained by evaluating: 2356 / (10 ^ 3) which gives 2.356. The same goes for all properties that end with Price.

"2": { "askPrice": "", "askQty": "", "bidPrice": "", "bidQty": "", "changePercent": "-24.19", "changePrice": "-4112.00", "closePrice": "17000", "cumulativeUnits": "", "cumulativeValue": "", "highPrice": "12888", "instrumentId": 2, "lastPrice": "12888", "lastQty": "3", "lowPrice": "12888", "openPrice": "", "sevenDayChange": "867.00", "sevenDayChangePercentage": "7.21", "sevenDayClosePrice": "12021" }

and you receive an update with following data:

{ "2": { "askQty": "35", } }

the expected state of instrumentId 2 is:

"2": { "askPrice": "", "askQty": "35", "bidPrice": "", "bidQty": "", "changePercent": "-24.19", "changePrice": "-4112.00", "closePrice": "17000", "cumulativeUnits": "", "cumulativeValue": "", "highPrice": "12888", "instrumentId": 2, "lastPrice": "12888", "lastQty": "3", "lowPrice": "12888", "openPrice": "", "sevenDayChange": "867.00", "sevenDayChangePercentage": "7.21", "sevenDayClosePrice": "12021" }

At the start of a trading session, a set-market-quotes event would be returned and the content of its data property would be similar to:

the expected state of instrumentId 2 would then be:

"2": { "askPrice": "", "askQty": "", "bidPrice": "", "bidQty": "", "changePercent": "0.00", "changePrice": "0", "closePrice": "17000", "cumulativeUnits": "", "cumulativeValue": "", "highPrice": "", "instrumentId": 2, "lastPrice": "12888", "lastQty": "3", "lowPrice": "", "openPrice": "", "sevenDayChange": "867.00", "sevenDayChangePercentage": "7.21", "sevenDayClosePrice": "12021" }

Subscribe to Cash command

{
  "action": "subscribe-cash"
}

Set Cash event

{
  "status": "OK",
  "action": "set-cash",
  "data": {
    "1": {
      "currency": "GBP",
      "decimals": 2,
      "description": "British pound sterling",
      "id": 1,
      "marketStatus": "closed",
      "name": "GBP",
      "priceDecimalPlaces": 2,
      "quantityDecimalPlaces": 2,
      "regulatedStatus": "eligible",
      "symbol": "GBP",
      "tickSize": "",
      "tradingStatus": "Created",
      "type": "cash",
      "venueId": "ARCHAX"
    },
    "2": {
      "currency": "USD",
      "decimals": 2,
      "description": "U.S. Dollar",
      "id": 2,
      "marketStatus": "closed",
      "name": "USD",
      "priceDecimalPlaces": 2,
      "quantityDecimalPlaces": 2,
      "regulatedStatus": "eligible",
      "symbol": "USD",
      "tickSize": "",
      "tradingStatus": "Created",
      "type": "cash",
      "venueId": "ARCHAX"
    },
    "27": {
      "currency": "NGN",
      "decimals": 2,
      "description": "Electronic Naira",
      "id": 27,
      "marketStatus": "closed",
      "name": "eNaira",
      "priceDecimalPlaces": 2,
      "quantityDecimalPlaces": 2,
      "regulatedStatus": "eligible",
      "symbol": "eNGN",
      "tickSize": "",
      "tradingStatus": "Created",
      "type": "cash",
      "venueId": "ARCHAX"
    },
    "28": {
      "currency": "MNY",
      "decimals": 2,
      "description": "MONEY",
      "id": 28,
      "marketStatus": "closed",
      "name": "MONEY",
      "priceDecimalPlaces": 2,
      "quantityDecimalPlaces": 2,
      "regulatedStatus": "eligible",
      "symbol": "MNY",
      "tickSize": "",
      "tradingStatus": "Created",
      "type": "cash",
      "venueId": "ARCHAX"
    },
    "29": {
      "currency": "PHP",
      "decimals": 2,
      "description": "Philippine Fiat Currency",
      "id": 29,
      "marketStatus": "closed",
      "name": "Philippine Peso",
      "priceDecimalPlaces": 2,
      "quantityDecimalPlaces": 2,
      "regulatedStatus": "eligible",
      "symbol": "PHP",
      "tickSize": "",
      "tradingStatus": "Created",
      "type": "cash",
      "venueId": "ARCHAX"
    }
  },
  "type": "cash",
  "timestamp": "2023-03-10T07:28:31.028Z"
}

Send a subscribe-cash command to subscribe to cash details. It will initially return a set-cash event that contains all cash assets available on the exchange as quote currencies. Subsequent set-cash events will only include assets and properties that have since been updated

Set Cash Event Schema

Name	Type	Description
[key]		Identifier of the asset
currency	string	3-letter currency code for the asset
decimals	number	The number of significant decimal places for the asset’s price
description	string	The full name of the asset
id	number	Unique identifier of the asset
marketStatus	string	Current market status for the asset. Possible values are: `open`, `closed` and `closing auction`
name	string	The short name for the asset
priceDecimalPlaces	number	Number of decimal places used by the system when accepting a price for the asset
quantityDecimalPlaces	number	Number of decimal places used by the system when accepting a quantity for the asset
regulatedStatus	string	The regulated status of the asset. Possible values are: `eligible` and `ineligible`
symbol	string	Ticker symbol for the asset
tickSize	string	Minimum price amount an instrument can move
tradingStatus	string	Current trading status for the asset. Possible values are: `Created`, `Pre-Live`, `Trading`, `Suspended` and `Terminated`
type	string	The asset type. Possible values are: `security` and `crypto`
venueId	string	Default value: `ARCHAX`

Balances

Fetch Balances

Fetch Balances command

{
  "action": "fetch-balances",
  "data": {
    "organisationId": 1
  }
}

Fetch Balances event

{
  "action": "fetch-balances",
  "organisationId": 1,
  "data": {
    "2786123094": {
      "accountId": 2786123094,
      "accountType": "accountSecurity",
      "available": "1000000400",
      "instrumentId": 1,
      "regulatoryEligibility": "eligible",
      "total": "1000000400"
    },
    "2786123904": {
      "accountId": 2786123904,
      "accountType": "accountSecurity",
      "available": "1000000400",
      "regulatoryEligibility": "eligible",
      "instrumentId": 2,
      "total": "1000000400"
    },
    "2786123095": {
      "accountId": 2786123095,
      "accountType": "accountCrypto",
      "available": "1000000400",
      "regulatoryEligibility": "ineligible",
      "instrumentId": 3,
      "total": "1000000400"
    },
    "2786123398": {
      "accountId": 2786123398,
      "accountType": "accountCash",
      "available": "1000000400",
      "regulatoryEligibility": "eligible",
      "instrumentId": 4,
      "total": "1000000400"
    },
    "2786122842": {
      "accountId": 2786122842,
      "accountType": "accountUnregulatedCash",
      "available": "1000000400",
      "regulatoryEligibility": "ineligible",
      "instrumentId": 5,
      "total": "1000000400"
    },
    "2786122894": {
      "accountId": 2786122894,
      "accountType": "accountCash",
      "available": "1000000400",
      "regulatoryEligibility": "eligible",
      "instrumentId": 6,
      "total": "1000000400"
    }
  },
  "timestamp": "2021-07-01T04:30:06.127Z"
}

Send a fetch-balances command to retrieve all account balances for all of the organisations to which you belong. The command can include an optional data property to filter the response to a single organisation. The response is a fetch-balances event that includes a data property where the object is keyed by accountId.

Fetch Balance Command Schema (optional)

Name	Type	Description
organisationId	number	Unique identifier for the organisation subject to the fetch balance request

Fetch Balances Event Schema

Name	Type	Description
[key]		Identifier of the account
accountId	number	Unique identifier for the account
accountType	string	Type of account. The possible values are: `accountCash`, `accountUnregulatedCash`, `accountSecurity` and `accountCrypto`
available	string	Available balance of account (for cash accounts, the last two digits are decimal places)
regulatoryEligibility	string	Indicates regulatory eligibility. Possible values are: `eligible` and `ineligible`
instrumentId	number	Identifier of the account asset
total	string	Total balance of account (for cash accounts, the last two digits are decimal places)

Subscribe to Balances command

{
  "action": "subscribe-balances",
  "data": {
    "organisationId": 3
  }
}

Set Balances event

{
  "status": "OK",
  "action": "set-balances",
  "organisationId": 3,
  "data": {
    "2786123094": {
      "accountId": 2786123094,
      "accountType": "accountCash",
      "available": "1000000400",
      "instrumentId": 1,
      "regulatoryEligibility": "eligible",
      "total": "1000000400"
    },
    "2786123095": {
      "accountId": 2786123095,
      "accountType": "accountSecurity",
      "available": "1000000400",
      "instrumentId": 2,
      "regulatoryEligibility": "eligible",
      "total": "1000000400"
    },
    "2786122842": {
      "accountId": 2786122842,
      "accountType": "accountCrypto",
      "available": "1000180131",
      "instrumentId": 3,
      "regulatoryEligibility": "ineligible",
      "total": "1000180207"
    }
  },
  "type": "balances",
  "timestamp": "2021-07-01T04:30:06.408Z"
}

Send a subscribe-balances command to subscribe to account balance updates for all of the organisations to which you belong. It will initially return a set-balances event that contains all account balances while subsequent set-balances events will only include account balances that have since been updated. The command can include an optional data property to filter the response to a single organisation. The response is a set-balances event that includes a data property where the object is keyed by accountId.

Subscribe Balance Command Schema (optional)

Name	Type	Description
organisationId	number	Unique identifier for the organisation subject to the subscribe balance request

Set Balances Event Schema

Name	Type	Description
[key]		Identifier of the account
accountId	number	Unique identifier for the account
accountType	string	Type of account. The possible values are: `accountCash`, `accountUnregulatedCash`, `accountSecurity` and `accountCrypto`
available	string	Available balance of account (for cash accounts, the last two digits are decimal places)
instrumentId	number	Unique identifier of the asset
regulatoryEligibility	string	Indicates regulatory eligibility. Possible values are: `eligible` and `ineligible`
total	string	Total balance of account (for cash accounts, the last two digits are decimal places)

Orders

Submit an Order

Submit Order command

{
  "action": "order-submit",
  "data": {
    "actionRef": "user_reference_1234",
    "instrumentId": "3",
    "limitPrice": "356.99",
    "orderType": 0,
    "quantity": "100.5",
    "side": 0,
    "organisationId": 1
  }
}

Order Updated event

{
  "status": "OK",
  "action": "order-updated",
  "data": {
    "actionRef": "user_reference_1234",
    "orderId": "1625642744032536",
    "organisationId": 1,
    "status": "open"
  },
  "type": "notifications",
  "timestamp": "2021-07-07T07:25:45.140Z"
}

Order Updated event with status ERROR (order rejected)

{
  "status": "ERROR",
  "action": "order-updated",
  "data": {
    "actionRef": "user_reference_1234",
    "error": "Dynamic Price Collar",
    "orderId": "1626062904341855",
    "organisationId": 1,
    "status": "rejected"
  },
  "type": "notifications",
  "timestamp": "2021-07-07T07:25:45.140Z"
}

Order Submitted event with status ERROR

{
  "status": "ERROR",
  "action": "order-submitted",
  "data": {
    "error": "No instrument selected",
    "actionRef": "user_reference_1234"
  },
  "type": "notifications",
  "timestamp": "2021-07-07T07:45:04.231Z"
}

Send an order-submit command to submit an order. The response is either an order-updated event for a successfully received order or an order-submitted event with a status of ERROR.

Order Submit Command Schema

Name	Type	Description
actionRef	string	User-specified identifier; it will be included the response
instrumentId	number	Unique identifier of the asset
limitPrice	string	Limit Price for the order
orderType	number	Type of order, possible values: `0` = Limit Order
quantity	string	Quantity of asset for the order
side	number	Market side of order, possible values: `0` = Buy, `1` = Sell
organisationId	number	Unique identifier for the organisation subject to the order submission

When an actionRef is provided, it must be unique across all commands.

Order Updated Event Schema

Name	Type	Description
actionRef	string	If the order `status` is `open` or `rejected`, it will be the `actionRef` that was included in the submitted order. If the order `status` is `cancelled`, it will be the `orderId`. Otherwise it will not be included for other `status` values.
error	string	Description of error that was identified, will not be included if there is no error.
orderId	string	Unique identifier for the order
organisationId	number	Unique identifier for the organisation that placed the order
status	string	Status of order, possible values: `pending`, `open`, `cancelled`, `expired`, `rejected`, `completed`

Order Submitted (Error) Event Schema

Name	Type	Description
error	string	Description of error that was identified
actionRef	string	User-specified identifier that was included in the submitted order

Subscribe to Orders command

{
  "action": "subscribe-orders",
  "data": {
    "organisationId": 1
  }
}

Set Orders event (initial)

{
  "status": "OK",
  "action": "set-orders",
  "organisationId": 1,
  "data": {
    "1623217157444399": {
      "averagePrice": "1000",
      "created": "1623217157444",
      "commission": "10",
      "currency": "EUR",
      "decimals": 2,
      "executions": {
        "1623217158966156": {
          "created": "1623217158966",
          "commission": "10",
          "grossExecutionAmount": "17000",
          "price": "1000",
          "id": "1623217158966156",
          "quantity": "17",
          "tax": "0"
        }
      },
      "filledPercent": "100.00",
      "filledQty": "17",
      "filledStatus": "filled",
      "id": "1623217157444399",
      "instrumentId": 24,
      "limitPrice": "1000",
      "orderStatus": "completed",
      "quantity": "17",
      "side": "buy",
      "symbol": "OASa",
      "type": "limit",
      "tax": "0",
      "userId": 2
    },
    "1623217157504910": {
      "averagePrice": "1000",
      "created": "1623217157504",
      "commission": "20",
      "currency": "GBX",
      "decimals": 2,
      "executions": {
        "1623217159226194": {
          "created": "1623217159226",
          "commission": "20",
          "grossExecutionAmount": "14000",
          "price": "1000",
          "id": "1623217159226194",
          "quantity": "14",
          "tax": "0"
        }
      },
      "filledPercent": "100.00",
      "filledQty": "14",
      "filledStatus": "filled",
      "id": "1623217157504910",
      "instrumentId": 25,
      "limitPrice": "1000",
      "orderStatus": "completed",
      "quantity": "14",
      "side": "sell",
      "symbol": "OADa",
      "type": "limit",
      "tax": "0",
      "userId": 2
    }
  },
  "type": "orders",
  "timestamp": "2021-07-06T08:04:40.837Z"
}

Set Orders event (update)

{
  "status": "OK",
  "action": "set-orders",
  "data": {
    "1626077181607120": {
      "orderStatus": "open"
    }
  },
  "type": "orders",
  "timestamp": "2021-07-12T08:06:21.613Z"
}

Subscribe Orders Command Schema (optional)

Name	Type	Description
organisationId	number	Unique identifier for the organisation subject to the order subscription request

Set Orders Event Schema

Name	Type	Description
[key]		Unique order identifier
averagePrice	string	Average execution price for the order without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
created	string	Timestamp on when the order was placed (ms)
currency	string	Currency code
commission	string	Total commission value of the order
decimals	number	Number of decimal places of price figures of order instrument
executions	Execution	Details of executed trades, keyed by `id` (where `id` is a unique reference to the execution)
filledPercent	string	Filled percent
filledQty	string	Filled quantity without consideration of decimal places value (decimal places defined in `quantityDecimalPlaces` from Instruments Schema)
filledStatus	string	Fill status, possible values: `unfilled`, `partiallyFilled`, `filled`
id	string	Unique order identifier
instrumentId	number	Unique identifier of the asset
limitPrice	string	Order limit price without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
organisationId	number	Unique identifier for the organisation that placed the order
orderStatus	string	Order status, possible values: `pending`, `open`, `cancelled`, `expired`, `rejected`, `completed`
quantity	string	Order quantity without consideration of decimal places value (decimal places defined in `quantityDecimalPlaces` from Instruments Schema)
side	string	Order side, possible values: `buy`, `sell`
symbol	string	Ticker symbol of instrument
type	string	Order type, possible values: `limit`
tax	string	Total tax value of the order
userId	number	Unique identifier of the user

Execution Schema

Name	Type	Description
commission	string	Total commission value of the execution
created	string	Timestamp on when the trade was executed (ms)
grossExecutionAmount	string	Product of executed price and quantity
price	string	Executed price without consideration of decimal places values (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
id	string	Unique identifier to execution
quantity	string	Executed quantity without consideration of decimal places value (decimal places defined in `quantityDecimalPlaces` from Instruments Schema)
tax	string	Total tax value of the order

set-orders updates must be deeply merged from the previous state. For example, if an order has the following state:

{ "1626077181607120": { "orderStatus": "pending", "decimals": 2, "instrumentId": 3, "filledPercent": "0.00", "created": 1626077181607.12, "quantity": 100, "averagePrice": 0, "limitPrice": "35699", "currency": "USD", "filledQty": "0", "filledStatus": "unfilled", "side": "buy", "symbol": "FAKe", "type": "limit", "executions": {}, "id": "1626077181607120" } }

and you receive an update with following data:

{ "1626077181607120": { "orderStatus": "open" } }

the expected state of order 1626077181607120 is:

{ "1626077181607120": { "orderStatus": "open", "decimals": 2, "instrumentId": 3, "filledPercent": "0.00", "created": 1626077181607.12, "quantity": 100, "averagePrice": 0, "limitPrice": "35699", "currency": "USD", "filledQty": 0, "filledStatus": "unfilled", "side": "buy", "symbol": "FAKe", "type": "limit", "executions": {}, "id": "1626077181607120" } }

Cancel an Order

Cancel Order Command

{
  "action": "order-cancel",
  "data": {
    "actionRef": "user_reference_1234",
    "orderId": "1625642744032536",
    "organisationId": 1
  }
}

Order Cancelled Event

{
  "status": "OK",
  "action": "order-cancelled",
  "data": {
    "actionRef": "1625642744032536",
    "orderId": "1625642744032536",
    "organisationId": 1,
    "status": "cancelled"
  },
  "type": "notifications",
  "timestamp": "2021-07-07T18:57:04.231Z"
}

Cancellation Rejected Event

{
  "status": "ERROR",
  "action": "cancel-rejected",
  "data": {
    "actionRef": "1625642744032536",
    "error": "Order cannot be cancelled",
    "orderId": "1625642744032536",
    "organisationId": 1,
    "reason": "marketClosed",
    "status": "completed",
    "userId": 12
  },
  "type": "notifications",
  "timestamp": "2021-07-07T18:57:04.231Z"
}

Cancel Failed Event with ERROR status

{
  "status": "ERROR",
  "action": "cancel-failed",
  "data": {
    "error": "No order id provided",
    "actionRef": "user_reference_1234"
  },
  "type": "notifications",
  "timestamp": "2021-07-07T18:57:04.231Z"
}

Send an order-cancel command to cancel an order.

The successful cancellation of an order would cause an order-cancelled event to be returned while a cancel-failed event is returned when there are errors in the submitted order-cancel command.

Cancel Order Command Schema

Name	Type	Description
actionRef	string	Optional field for client to include a unique identifier
orderId	string	Unique identifier for the order
organisationId	number	Unique identifier for the organisation subject to the order cancellation

When an actionRef is provided, it must be unique across all commands.

Order Cancelled Event Schema

Name	Type	Description
actionRef	string	Unique identifier provided by client
orderId	string	Unique identifier for the order
organisationId	number	Unique identifier for the organisation that placed the order
status	string	The status of the order

Cancellation Rejected Event Schema

Name	Type	Description
actionRef	string	Unique identifier provided by client
error	string	Error message
orderId	string	Unique identifier for the order
organisationId	number	Unique identifier for the organisation that placed the order
reason	string	The reason for the rejection
status	string	The status of the order
userId	string	Unique identifier of the user that requested the cancellation

Cancellation Failed Event Schema

Name	Type	Description
actionRef	string	User-specified identifier
error	string	Error message; would contain the reason for the failure

Order Book

Subscribe to Market Depths command

{
  "action": "subscribe-market-depths"
}

Set Market Depths event (initial)

{
  "status": "OK",
  "action": "set-market-depths",
  "data": {
    "1": {
      "buy": {
        "1200": 100,
        "1300": 50
      },
      "indicativePrice": "",
      "indicativeVolume": "",
      "instrumentId": 1,
      "sell": {
        "1310": 20,
        "1320": 50
      }
    },
    "2": {
      "buy": {
        "2300": 10,
        "2400": 10
      },
      "indicativePrice": "",
      "indicativeVolume": "",
      "instrumentId": 2,
      "sell": {
        "2500": 15,
        "2510": 100
      }
    },
    "3": {
      "buy": {
        "10000": 20,
        "9900": 30
      },
      "indicativePrice": "",
      "indicativeVolume": "",
      "instrumentId": 1,
      "sell": {
        "10100": 30,
        "10110": 50
      }
    }
  },
  "type": "market-depths",
  "timestamp": "2021-07-01T05:17:00.691Z"
}

Set Market Depths event (update)

{
  "status": "OK",
  "action": "set-market-depths",
  "data": {
    "1": {
      "instrumentId": 1,
      "buy": {
        "1200": 120
      },
      "sell": {}
    }
  },
  "type": "market-depths",
  "timestamp": "2021-07-01T05:17:00.691Z"
}

Set Market Depths event (update, depth removed from Order Book)

{
  "status": "OK",
  "action": "set-market-depths",
  "data": {
    "1": {
      "instrumentId": 1,
      "buy": {
        "1200": 0
      },
      "sell": {
        "1199": 0
      }
    }
  },
  "type": "market-depths",
  "timestamp": "2021-07-01T05:17:00.691Z"
}

Send a subscribe-market-depths command to subscribe to Order Book updates for all instruments available in the market. It initially returns a set-market-depths event that includes Order Book information for each instrument available in the market. Subsequent events only contain updates for affected sides and depths of an instrument. Each value in the data property is keyed by instrumentId, and values under each side of the market (buy or sell) are keyed by market depth (prices). Note that the two right most digits in all prices represent decimal places.

Set Market Depths Event Schema

Name	Type	Description
[key]		Identifier of the asset
buy	string	Market depth (price) for the buy side of the market
indicativePrice	string	(Provided during auction phase) The price at which the most executions would occur if the auction ended at the current time. Also referred to as the uncrossing price
indicativeVolume	string	(Provided during auction phase) The number of units that would exchange hands if the auction ended at the current time
instrumentId	number	Identifier of the asset
sell	string	Market depth (price) for the sell side of the market

Market Depth Schema (Buy or Sell)

Name	Type	Description
[key]		Market depth (price without consideration of decimal places value, decimal places defined in `priceDecimalPlaces` from Instruments Schema)
[value]	number	Volume (quantity without consideration of decimal places value, decimal places defined in `quantityDecimalPlaces` from Instruments Schema)

set-market-depths updates must be deeply merged from the previous state. For example, if an instrument has the following state:

{ "1": { "buy": { "1200": 100, "1300": 50 }, "indicativePrice": "", "indicativeVolume": "", "instrumentId": 1, "sell": { "1310": 20, "1320": 50 } } }

and you receive an update with following data:

{ "1": { "buy": { "1100": 500 }, "instrumentId": 1, "sell": {} } }

the expected state of instrumentId 1 is:

{ "1": { "buy": { "1100": 500, "1200": 100, "1300": 50 }, "indicativePrice": "", "indicativeVolume": "", "instrumentId": 1, "sell": { "1310": 20, "1320": 50 } } }

set-market-depths updates with a quantity value of 0 are sent to clear a particular depth. For example, if an instrument has the following state:

{ "1": { "buy": { "1200": 100, "1300": 50 }, "indicativePrice": "", "indicativeVolume": "", "instrumentId": 1, "sell": { "1310": 20, "1320": 50 } } }

and you receive an update with following data:

{ "1": { "buy": { "1300": 0 }, "instrumentId": 1, "sell": {} } }

the expected state of instrumentId 1 is:

{ "1": { "buy": { "1200": 100 }, "indicativePrice": "", "indicativeVolume": "", "instrumentId": 1, "sell": { "1310": 20, "1320": 50 } } }

Trades

Subscribe to a single instruments Trade History command. Where 1 denotes an example instrumentId.

{
  "action": "subscribe-trade-histories/1"
}

Subscribe to all Trade History.

{
  "action": "subscribe-trade-histories"
}

Response JSON returned example -

Initial Set Trade History event

{
  "status": "OK",
  "action": "set-trade-histories/1",
  "data": {
    "1": [
      {
        "amount": "81",
        "created": "1619080206756725504",
        "price": "9124",
        "side": "sell",
        "tradeRef": "1"
      },
      {
        "amount": "4",
        "created": "1619080141466397184",
        "price": "10875",
        "side": "buy",
        "tradeRef": "2"
      },
      {
        "amount": "48",
        "created": "1619080099647654400",
        "price": "9059",
        "side": "buy",
        "tradeRef": "3"
      }
    ]
  },
  "type": "trade-histories",
  "timestamp": "2021-08-27T14:39:46.820Z"
}

Set Trade History event (update)

{
  "status": "OK",
  "action": "append-trade-histories/1",
  "data": {
    "1": [
      {
        "amount": 45,
        "created": 1619080206756725534,
        "price": 9127,
        "side": "sell",
        "tradeRef": "4"
      }
    ]
  },
  "type": "trade-histories",
  "timestamp": "2021-08-27T15:35:59.147Z"
}

To subscribe to all trade histories, send a subscribe-trade-histories command. To subscribe to trade history for a specific instrumentId send a subscribe-trade-histories/[instrumentId] command to subscribe to trade history updates. It will initially return a set-trade-histories/[instrumentId] event that contains the most recently executed trades for the requested instrumentId. An append-trade-histories/[instrumentId] event will then be returned for each additional trade executes while the subscription is active.

Note that a maximum of the latest twenty orders only is returned for the requested instrumentId or the latest 20 for all trade history.

The data property is an object keyed by instrumentId, with the following details:

Set trade history Event Schema

Name	Type	Description
[key]		Unique identifier of the instrument
amount	string	Quantity traded
created	string	Time of trade
price	string	Executed price without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
side	string	Aggressive side of order (`buy` or `sell`). `auction` is returned as value when trade is a result of an auction
tradeRef	string	Unique identifier of trade

Transactions

Subscribe to Transactions command

{
  "action": "subscribe-transactions"
}

Set Transaction event

{
  "status": "OK",
  "action": "set-transactions",
  "data": {
    "entries": [
      {
        "id": "1631023590277781",
        "organisationId": 3,
        "userId": 12,
        "accountId": 2786122875,
        "amount": "10",
        "referenceId": "1631023590277580",
        "created": "1631023590272836",
        "ledgerType": "debit",
        "reportType": "execution",
        "commissionReference": "0",
        "instrumentId": "3"
      },
      {
        "id": "1631023590278240",
        "organisationId": 3,
        "userId": 12,
        "accountId": 2786122905,
        "amount": "409500",
        "referenceId": "1631023590277580",
        "created": "1631023590272872",
        "ledgerType": "credit",
        "reportType": "execution",
        "commissionReference": "0",
        "instrumentId": "33"
      },
      {
        "id": "1631016154737596",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123148,
        "amount": "109",
        "referenceId": "1631016154736971",
        "created": "1631016154725876",
        "ledgerType": "debit",
        "reportType": "commission",
        "commissionReference": "1631016099181019",
        "instrumentId": "7"
      },
      {
        "id": "1631016154737159",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123148,
        "amount": "1090",
        "referenceId": "1631016154736971",
        "created": "1631016154725882",
        "ledgerType": "debit",
        "reportType": "execution",
        "commissionReference": "0",
        "instrumentId": "32"
      },
      {
        "id": "1631016154738149",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123124,
        "amount": "109",
        "referenceId": "1631016154736971",
        "created": "1631016154725886",
        "ledgerType": "credit",
        "reportType": "execution",
        "commissionReference": "0",
        "instrumentId": "7"
      },
      {
        "id": "1631014364506141",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123148,
        "amount": "109",
        "referenceId": "1631014364505500",
        "created": "1631014364499891",
        "ledgerType": "debit",
        "reportType": "commission",
        "commissionReference": "1631014308958295",
        "instrumentId": "7"
      },
      {
        "id": "1631014364505723",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123148,
        "amount": "1090",
        "referenceId": "1631014364505500",
        "created": "1631014364499895",
        "ledgerType": "debit",
        "reportType": "execution",
        "commissionReference": "0",
        "instrumentId": "32"
      },
      {
        "id": "1631014364507061",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123124,
        "amount": "109",
        "referenceId": "1631014364505500",
        "created": "1631014364499900",
        "ledgerType": "credit",
        "reportType": "execution",
        "commissionReference": "0",
        "instrumentId": "7"
      },
      {
        "id": "1631014099470021",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123124,
        "amount": "1234",
        "referenceId": "1631014099467372",
        "created": "1631014099463903",
        "ledgerType": "credit",
        "reportType": "execution",
        "commissionReference": "0",
        "instrumentId": "7"
      },
      {
        "id": "1631014099468016",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123148,
        "amount": "121",
        "referenceId": "1631014099467372",
        "created": "1631014099463907",
        "ledgerType": "debit",
        "reportType": "commission",
        "commissionReference": "1631014043667348",
        "instrumentId": "7"
      }
    ]
  },
  "type": "transactions",
  "timestamp": "2021-09-08T00:46:23.587Z"
}

Send a subscribe-transactions command to subscribe to transaction updates. It will return a set-transactions event that contains the last 1000 transactions for each organisation you belong to. Subsequent transactions would also cause a set-transactions event to be returned which will maintain the same data structure and the list of entries would include the new transactions. The command can include an optional data property to filter the responses to a single organisation. A response will be send for each subscribed organisation and will include an organisationId property to indicate to which organisation the response is relevant. The response includes a data property which is an object with a single key entries which in turn is an array of transaction objects.

Subscribe Orders Command Schema (optional)

Name	Type	Description
organisationId	number	Unique identifier for the organisation subject to the transaction subscription request

Set Transaction Event Schema

Name	Type	Description
id	string	Unique identifier of the transaction
organisationId	number	Unique identifier for the organisation associated with the transaction
userId	number	Unique identifier of the user associated with the transaction
accountId	number	Unique identifier for the account
amount	string	For cash accounts - actual monetary value of the transaction where the last two digits are decimal places
		For security accounts - quantity involved in the transaction
referenceId	string	Unique reference to event (where event can be an execution or a notification for a deposit etc.)
created	string	Time of transaction
ledgerType	string	Value is one of `credit` or `debit`
reportType	string	Value can be one of - `commission`, `execution`, `deposit`, `fee`, `coupon`, `manualCorrection`, `interest`, `dividend`, `withdrawal` or `tax`
commissionReference	string	Unique identifier of the commission if applicable
instrumentId	string	Unique identifier of the asset

set-transactions event updates must completely replace the previous state. For example, if your transactions list has the following state:

[ { "id": "1631014099470021", "organisationId": 3, "userId": 5, "accountId": 2786123124, "amount": "1234", "referenceId": "1631014099467372", "created": "1631014099463903", "ledgerType": "credit", "reportType": "execution", "commissionReference": "0", "instrumentId": "7" }, { "id": "1631014099468016", "organisationId": 3, "userId": 5, "accountId": 2786123148, "amount": "121", "referenceId": "1631014099467372", "created": "1631014099463907", "ledgerType": "debit", "reportType": "commission", "commissionReference": "1631014043667348", "instrumentId": "7" } ]

an event to update the list of transactions you have would be in the form:

{ "status": "OK", "action": "set-transactions", "data": { "entries": [ { "id": "1631014364507061", "organisationId": 3, "userId": 5, "accountId": 2786123124, "amount": "109", "referenceId": "1631014364505500", "created": "1631014364499900", "ledgerType": "credit", "reportType": "execution", "commissionReference": "0", "instrumentId": "7" }, { "id": "1631014099470021", "organisationId": 3, "userId": 5, "accountId": 2786123124, "amount": "1234", "referenceId": "1631014099467372", "created": "1631014099463903", "ledgerType": "credit", "reportType": "execution", "commissionReference": "0", "instrumentId": "7" }, { "id": "1631014099468016", "organisationId": 3, "userId": 5, "accountId": 2786123148, "amount": "121", "referenceId": "1631014099467372", "created": "1631014099463907", "ledgerType": "debit", "reportType": "commission", "commissionReference": "1631014043667348", "instrumentId": "7" } ] } }

and the resulting transactions state will be:

[ { "id": "1631014364507061", "organisationId": 3, "userId": 5, "accountId": 2786123124, "amount": "109", "referenceId": "1631014364505500", "created": "1631014364499900", "ledgerType": "credit", "reportType": "execution", "commissionReference": "0", "instrumentId": "7" }, { "id": "1631014099470021", "organisationId": 3, "userId": 5, "accountId": 2786123124, "amount": "1234", "referenceId": "1631014099467372", "created": "1631014099463903", "ledgerType": "credit", "reportType": "execution", "commissionReference": "0", "instrumentId": "7" }, { "id": "1631014099468016", "organisationId": 3, "userId": 5, "accountId": 2786123148, "amount": "121", "referenceId": "1631014099467372", "created": "1631014099463907", "ledgerType": "debit", "reportType": "commission", "commissionReference": "1631014043667348", "instrumentId": "7" } ]

Custody

Subscribe To Deposits command

{
  "action": "subscribe-deposits",
  "data": {
    "organisationId": 1
  }
}

Set Deposits event

{
  "status": "OK",
  "action": "set-deposits",
  "data": {
    "1658732301686225": {
      "accountId": "118",
      "amount": "300000",
      "created": "1658732301000000",
      "id": "1658732301686225",
      "instrumentId": 1,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658732301544438",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658732301000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658730084256007": {
      "accountId": "118",
      "amount": "300000",
      "created": "1658730084000000",
      "id": "1658730084256007",
      "instrumentId": 1,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658730084120637",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658730084000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658730034966343": {
      "accountId": "118",
      "amount": "300000",
      "created": "1658730034000000",
      "id": "1658730034966343",
      "instrumentId": 1,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658730034833466",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658730034000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658729853582198": {
      "accountId": "120",
      "amount": "300000",
      "created": "1658729853000000",
      "id": "1658729853582198",
      "instrumentId": 2,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658729853446574",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658729853000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658729762673091": {
      "accountId": "120",
      "amount": "300000",
      "created": "1658729762000000",
      "id": "1658729762673091",
      "instrumentId": 2,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658729762538762",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658729762000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658729594686221": {
      "accountId": "120",
      "amount": "300000",
      "created": "1658729594000000",
      "id": "1658729594686221",
      "instrumentId": 2,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658729594553480",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658729594000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658728733406117": {
      "accountId": "120",
      "amount": "300000",
      "created": "1658728733000000",
      "id": "1658728733406117",
      "instrumentId": 2,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658728733271718",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658728733000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658728201164503": {
      "accountId": "120",
      "amount": "300000",
      "created": "1658728201000000",
      "id": "1658728201164503",
      "instrumentId": 2,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658728201033042",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658728201000000",
      "userId": 13,
      "walletAddress": ""
    }
  },
  "type": "deposits",
  "timestamp": "2023-03-10T07:31:20.908Z"
}

Subscribe Deposits Command Schema

Name	Type	Description
organisationId	number	Unique identifier for the organisation subject to the deposit submission

Set Deposit Event Schema

Name	Type	Description
[key]		Unique identifier of the deposit
accountId	string	Unique identifier of the ledger account
amount	string	Amount of the deposit where the last n digits are decimal places corresponding to the quantity decimal place value assigned to the asset (ex. GBP has 2 decimal place value so an amount of “1000” would equate to £10.00)
created	string	Time of transaction
id	string	Unique identifier of the deposit
instrumentId	number	Unique identifier of the asset deposited
organisationId	number	Unique identifier of the client
reason	string	Additional details for deposits that do not successfully complete
referenceId	string	For cash - unique identifier that needs to be included in the reference field of the payment. For security assets- wallet address assigned as recipient address for transfer
status	string	Current state of the transaction, can be submitted, pending, cancelled, rejected or completed
type	string	Only `Deposit` returned as value
updated	string	Time stamp of the last time an action occurred on the deposit notification
userId	number	Unique identifier of the user who submitted the deposit notification
walletAddress	string	Depreciated field that returns empty string

Subscribe to Withdrawals command

{
  "action": "subscribe-withdrawals",
  "data": {
    "organisationId": 1
  }
}

Set Withdrawals event

{
  "status": "OK",
  "action": "set-withdrawals",
  "data": {
    "1660545047277119": {
      "accountId": 118,
      "amount": "100",
      "created": "1660545047000000",
      "id": "1660545047277119",
      "instrumentId": 1,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "123456",
      "status": "Pending",
      "type": "Withdrawal",
      "updated": "1660545047000000",
      "userId": 27,
      "walletAddress": ""
    },
    "1660542988806807": {
      "accountId": 118,
      "amount": "1000",
      "created": "1660542988000000",
      "id": "1660542988806807",
      "instrumentId": 1,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "12345",
      "status": "Pending",
      "type": "Withdrawal",
      "updated": "1660542988000000",
      "userId": 27,
      "walletAddress": ""
    }
  },
  "type": "withdrawals",
  "timestamp": "2023-03-10T07:36:31.616Z"
}

Subscribe Withdrawals Command Schema

Name	Type	Description
organisationId	number	Unique identifier for the organisation subject to the withdrawal submission

Set Withdrawal Event Schema

Name	Type	Description
[key]		Unique identifier of the withdrawal
accountId	string	Unique identifier of the ledger account
amount	string	Amount of the withdrawal where the last n digits are decimal places corresponding to the quantity decimal place value assigned to the asset (ex. GBP has 2 decimal place value so an amount of “1000” would equate to £10.00)
created	string	Time of transaction
id	string	Unique identifier of the withdrawal
instrumentId	number	Unique identifier of the asset to be withdrawn
organisationId	number	Unique identifier of the client
reason	string	Additional details for withdrawals that do not successfully complete
referenceId	string	Unique reference for withdrawal
status	string	Current state of the transaction, can be submitted, pending, cancelled, rejected or completed
type	string	Only `Withdrawal` returned as value
updated	string	Time stamp of the last time an action occurred on the withdrawal notification
userId	number	Unique identifier of the user who submitted the withdrawal notification
walletAddress	string	Depreciated field that returns empty string

Submit Deposit

Submit Deposit command

{
  "action": "submit-deposit",
  "data": {
    "amount": "10000",
    "instrumentId": 5,
    "organisationId": 27,
    "referenceId": "1676615598286"
  }
}

Submit Deposit Response event

{
  "status": "OK",
  "action": "submit-deposit-response",
  "data": {
    "accountId": 114,
    "reference": "0x7b87864f860c84f811dc4cd197de7468edd93267",
    "userId": 72,
    "requestId": "1676615627210920",
    "created": "1676615627210921",
    "walletAddress": "0x7b87864f860c84f811dc4cd197de7468edd93267",
    "whitelistedWalletAddress": ""
  },
  "type": "notifications",
  "timestamp": "2023-02-17T06:33:50.253Z"
}

Submit Deposit Schema

Name	Type	Description
data	Data	Deposit details

Submit Deposit Data Schema

Name	Type	Description
amount	string	Amount of the deposit where the last n digits are decimal places corresponding to the quantity decimal place value assigned to the asset (ex. GBP has 2 decimal place value so an amount of “1000” would equate to £10.00)
instrumentId	number	Unique identifier of the asset to be deposited
organisationId	number	Unique identifier for the organisation subject to the deposit submission
referenceId	string	Unique user reference for deposit

Submit Deposit Response Event Schema

Name	Type	Description
accountId	number	Unique identifier of the ledger account
referenceId	string	For cash - unique identifier that needs to be included in the reference field of the payment. For security assets- wallet address assigned as recipient address for transfer
userId	number	Unique identifier of the user who submitted the deposit notification
requestId	string	Unique system identifier of the deposit (corresponds to id field in `set-deposits` events schema)
created	string	Time of transaction
walletAddress	string	Internal use only
whitelistedWalletAddress	string	Not in use

Submit Withdrawal

Submit Withdrawal command

{
  "action": "submit-withdrawal",
  "data": {
    "amount": "10000",
    "instrumentId": 5,
    "organisationId": 27,
    "referenceId": "1676615598286"
  }
}

Submit Withdrawal Response event

{
  "status": "OK",
  "action": "submit-withdrawal-response",
  "data": {
    "accountId": 108,
    "userId": 72,
    "referenceId": "1676616969568760",
    "requestId": "1676616969570956",
    "created": "1676616969570957"
  },
  "type": "notifications",
  "timestamp": "2023-02-17T06:56:10.613Z"
}

Submit Withdrawal Schema

Name	Type	Description
data	Data	Withdrawal details

Submit Withdrawal Data Schema

Name	Type	Description
amount	string	Amount of the withdrawal where the last n digits are decimal places corresponding to the quantity decimal place value assigned to the asset (ex. GBP has 2 decimal place value so an amount of “1000” would equate to £10.00)
instrumentId	number	Unique identifier of the asset to be withdrawn
organisationId	number	Unique identifier for the organisation subject to the deposit submission
referenceId	string	Unique user reference for withdrawal

Submit Withdrawal Response Event Schema

Name	Type	Description
accountId	number	Unique identifier of the ledger account
referenceId	string	Unique reference for withdrawal
userId	number	Unique identifier of the user who submitted the withdrawal notification
requestId	string	Unique system identifier of the withdrawal (corresponds to id field in `set-withdrawals` events schema)
created	string	Time of transaction

Cancel Deposit

Cancel Deposit command

{
  "action": "cancel-deposit",
  "data": {
    "organisationId": 27,
    "requestId": "1676615627210920"
  }
}

Cancel Deposit Response event

{
  "status": "OK",
  "action": "cancel-deposit-response",
  "data": {
    "userId": 72,
    "status": "creditCancelled",
    "reason": "creditUserCancelled",
    "requestId": "1676615627210920",
    "created": "1676616709917337"
  },
  "type": "notifications",
  "timestamp": "2023-02-17T06:51:50.994Z"
}

Cancel Deposit Schema

Name	Type	Description
requestId	string	Unique system identifier of the deposit (corresponds to id field in `set-deposits` events schema)
organisationId	number	Unique identifier for the organisation subject to the deposit cancellation

Cancel Deposit Response Event Schema

Name	Type	Description
userId	number	Unique identifier of the user who submitted the deposit notification
status	string	Current status of the deposit notification, only value is `creditCancelled`
reason	string	Reason for cancellation, only value is `creditUserCancelled`
requestId	string	Unique system identifier of the deposit (corresponds to id field in `set-deposits` events schema)
created	string	Time of transaction

Cancel Withdrawal

Cancel Withdrawal command

{
  "action": "cancel-withdrawal",
  "data": {
    "organisationId": 27,
    "requestId": "1676616969570956"
  }
}

Cancel Withdrawal Response event

{
  "status": "OK",
  "action": "cancel-withdrawal-response",
  "data": {
    "userId": 72,
    "status": "debitCancelled",
    "reason": "debitUserCancelled",
    "requestId": "1676616969570956",
    "created": "1676618856703258"
  },
  "type": "notifications",
  "timestamp": "2023-02-17T07:27:37.623Z"
}

Cancel Withdrawal Schema

Name	Type	Description
requestId	string	Unique system identifier of the withdrawal (corresponds to id field in `set-withdrawals` events schema)
organisationId	number	Unique identifier for the organisation subject to the withdrawal cancellation

Cancel Withdrawal Response Event Schema

Name	Type	Description
userId	number	Unique identifier of the user who submitted the withdrawal notification
status	string	Current status of the withdrawal notification, only value is `debitCancelled`
reason	string	Reason for cancellation, only value is `debitUserCancelled`
requestId	string	Unique system identifier of the withdrawal (corresponds to id field in `set-withdrawals` events schema)
created	string	Time of transaction

Submit Transfer

Submit Transfer command

{
  "action": "submit-transfer",
  "data": {
    "amount": "1",
    "organisationId": 27,
    "sourceAccountId": 105,
    "targetAccountId": 106,
    "referenceId": "1676619797797"
  }
}

Submit Transfer Response event

{
  "status": "OK",
  "action": "submit-transfer-response",
  "data": {
    "requestId": "1676623261301525"
  },
  "type": "notifications",
  "timestamp": "2023-02-17T07:43:42.769Z"
}

Send a submit-transfer command to transfer funds between two accounts. The system will reject a transfer if the two accounts provided do not share the same instrument id. The system will also reject a transfer if the two accounts provided are not for the same client. The response will be a submit-transfer-response event that will either return an error with an error reason or an “OK” with the schema described below.

Submit Transfer Schema

Name	Type	Description
amount	number	Amount of the transfer where the last n digits are decimal places corresponding to the quantity decimal place value assigned to the asset (ex. GBP has 2 decimal place value so an amount of “1000” would equate to £10.00)
sourceAccountId	number	Unique identifier of the ledger account sending the amount
targetAccountId	number	Unique identifier of the ledger account receiving the amount
referenceId	string	Unique reference for the transfer
organisationId	number	Unique identifier for the organisation subject to the transfer. Must match the organisation id associated with both target and source account ids.

Submit Transfer Response Event Schema

Name	Type	Description
requestId	string	Unique system identifier of the transfer (currently a known issue that this is sent as two numbers and a boolean instead of a string)

ACE API Spec v1.0.5

REST API

The Archax REST API allows developers to retrieve authentication tokens and instrument information. All resources are defined under the following URL:

https://ace-auth.archax.com/api/1.0

All responses from the REST API are wrapped inside this response wrapper

Sample Request

{
  "email": "user@archax.com",
  "password": "password"
}

200 Response

{
  "status": "OK",
  "data": {
    "status": "OK",
    "jwt": "valid-token",
    "mfa": false,
    "timestamp": "2021-05-25T04:21:38.057Z"
  },
  "timestamp": "2021-05-25T04:21:38.058Z"
}

401 Response

{
  "status": "ERROR",
  "error": [
    {
      "msg": "Email and password combination are incorrect"
    }
  ],
  "timestamp": "2021-06-07T06:39:21.413Z"
}

POST /login

An endpoint that allows developers to submit an email and a password in exchange for a JWT.

Request Schema

Name	Type	Required	Description
email	string	true	Email address registered in the system
password	string	true	Password registered with email address

Response Schema

Name	Type	Description
status	status	OK for success, ERROR otherwise
jwt	string	A JSON web token that expires after 30 minutes
mfa	bool	A flag indicating whether multi-factor authentication is enabled
timestamp	timestamp	The response timestamp

Renew-jwt

Request to

https://ace-auth.archax.com/api/1.0/renew-jwt

200 Response

{
  "status": "OK",
  "data": {
    "jwt": "valid-token"
  },
  "timestamp": "2021-05-25T04:21:38.058Z"
}

401 Response

{
  "status": "ERROR",
  "error": [
    {
      "msg": "Too many requests"
    }
  ],
  "timestamp": "2021-06-07T06:39:21.413Z"
}

POST /renew-jwt

An endpoint that provides an updated JWT. Old JWT must be included as bearer token.

Response Schema

Name	Type	Description
jwt	string	A JSON web token that expires after 30 minutes

Payment Provider details

Request to

https://ace-auth.archax.com/api/1.0/rest-gateway/account/fiat-account/1/regulated

200 Response

{
  "status": "OK",
  "data": {
    "accountId": 1,
    "accountName": "Archax Client Money C",
    "accountNumber": "00000058",
    "paymentProvider": {
      "address1": "4th Floor, Prologue Works",
      "address2": "25 Marsh Street",
      "address3": "Bristol, BS1 4AX",
      "name": "ClearBank Limited"
    },
    "sortCode": "04-05-78"
  },
  "timestamp": "2023-03-10T10:02:09.398Z"
}

401 Response

{
  "status": "ERROR",
  "error": [
    {
      "msg": "Fiat account is not available for currencyId 5"
    }
  ],
  "timestamp": "2023-03-10T10:04:57.392Z"
}

GET https://ace-auth.archax.com/api/1.0/rest-gateway/account/fiat-account/:currencyId/:regType

An endpoint that provides account details for use when depositing cash with Archax. Must include bearer token with JWT that has appropriate permissions.

Url path parameters

Name	Type	Description
currencyId	number	Instrument id of cash to be deposited
regType	string	Indicates if payment is to CASS protected accounts (for regulated activity) or the non-CASS account (for unregulated activity). Value is either `regulated` or `unregulated`

Response Schema

Name	Type	Description
accountId	number	Internal identifier for Archax
accountName	string	Name to be used as beneficiary in payment
accountNumber	string	Account number to be used for beneficiary in payment
paymentProvider	Payment Provider	Beneficiary bank name and address
sortCode	string	Payment routing code for beneficiary bank. This field can include either a sort code, a bank identifier code or a FEDABA depending on the currency of the account

Payment Provider Schema

Name	Type	Description
name	string	Beneficiary bank name
address1	string	1st line of address for beneficiary bank
address2	string	2nd line of address for beneficiary bank
address3	string	3rd line of address for beneficiary bank

Instrument Details

Request to

https://ace-auth.archax.com/api/1.0/rest-gateway/reporting/instrument/6

200 Response

{
  "status": "OK",
  "data": {
    "id": 6,
    "name": "Apple inc.",
    "symbol": "APPa",
    "currency": "USD",
    "description": "Apple inc.",
    "status": "Trading",
    "type": "security",
    "quantityDecimalPlaces": 0,
    "priceDecimalPlaces": 2,
    "externalId": 3
  },
  "meta": {
    "category": "Exchange",
    "firstTradeDate": "2020-09-02",
    "fullName": "APPLE INC COM STK NPV (CDI)",
    "initialPrice": "680.25",
    "isin": "US0378331005",
    "lei": "HWUPKR0MPOU8FGXBT394",
    "mic": "ARCH",
    "minimumOrderValue": "0.01",
    "tickSize": "0.01",
    "tokeniser": "Securitize",
    "website": "www.apple.com"
  },
  "timestamp": "2023-03-09T13:08:34.282Z"
}

401 Response

{
  "status": "ERROR",
  "error": [
    {
      "msg": "Instrument not found"
    }
  ],
  "timestamp": "2021-06-07T06:39:21.413Z"
}

GET https://ace-auth.archax.com/api/1.0/rest-gateway/reporting/instrument/:instrumentId

Url path parameters

Name	Type	Description
instrumentId	number	Unique identifier of the asset

Response Schema

Name	Type	Description
id	number	Unique identifier of the asset
name	string	Name of the asset
symbol	string	Ticker symbol of the asset
currency	string	Symbol of the currency in which the asset is priced for trading
description	string	Additional details about the asset
status	string	Current status of the asset with regards to trading
type	string	Asset type (can be `security`, `crypto` or `cash`)
quantityDecimalPlaces	number	Number of decimal places available for use with any field that accepts a quantity for the asset
priceDecimalPlaces	number	Number of decimal places used by the system when accepting a price for the asset
externalId	number	Internal use only
created	string	Internal use only
updated	string	Internal use only
meta	Meta	Additional static data about the asset
close	number	Close price of the asset without consideration of decimal places value, decimal places defined in `priceDecimalPlaces` from Instruments Schema
open	number	Open price of the asset without consideration of decimal places value, decimal places defined in `priceDecimalPlaces` from Instruments Schema

Meta Schema

Name	Type	Description
accidents	string	Not in use
address	string	Address of the issuer
advisers	string	Not in use
affiliations	string	Not in use
approvalDate	string	Date and time the issuer has approved admission to trading or trading in its financial instruments on the Archax exchange
archaxMarket	string	Not in use
associationArticles	string	Not in use
auditReports	string	Not in use
availabilityOfCapital	string	Not in use
availabilityOfPersonnel	string	Not in use
benefitsOnTermination	string	Not in use
blockchainProtocol	string	Blockchain on which the asset was issued as a token or equivalent
bondBasePointSpread	string	Number of basis points above or below the index used to calculate accrued interest
bondFixedRate	string	The fixed rate percentage of a return on a debt instrument when held until maturity date expressed as a percentage (i.e. 7.0 means 7%)
bondIdentifier	string	ISIN of the index/benchmark used to set the floating rate of a return on a debt instrument
bondIndex	string	Alias name of the index/benchmark used to set the floating rate of a return on a debt instrument
bondMaturityDate	string	The maturity date of a debt instrument
bondName	string	Name of the index/benchmark used to set the floating rate of a return on a debt instrument
bondSeniority	string	Identifies the type of bond
bondTermUnit	string	The unit used for the term of the index or benchmark or a floating rate debt instrument (DAYS, WEEK, MNTH or YEAR)
bondTermValue	string	3 digit integer indicating the number of units of the term of the index or benchmark of a floating rate debt instrument
bondTotalIssued	string	Total issued nominal amount in monetary value (expressed in currency reported in currency field)
bondType	string	The type of bond: senior, debt, mezzanine, subordinated debt or junior debt
brexitImpact	string	Not in use
category	string	Category of the asset
cfiCode		The instrument classification expressed using the full (6 character) ISO 10962 CFI code that defines the type of instrument
companyRisks	string	Not in use
competition	string	Not in use
contactInfo	string	Contact information of the issuer of the asset
contractAddress	string	Address on the blockchain of the smart contract that manages the asset
corporateAdviser	string	Not in use
dependencies	string	Not in use
directors	string	Not in use
dividends	string	Not in use
domicile	string	Not in use
environmental	string	Not in use
envRating	string	Environmental rating provided as part of ESG rating
eps	string	Not in use
esgDescription	string	Details of the ESG rating provided
esgLogo	string	Logo of the provider of the ESG rating
estimatednetAmountPrincipalUse	string	Not in use
excessPayment	string	Not in use
exchangeRate	string	Not in use
financialInformation	string	Not in use
financialInformationStatement	string	Not in use
firstIssuanceDate	string	Date on which a debt instrument was issued and began to accrue interest
firstTradeDate	string	Date and time of the admission to trading on the trading venue or the date and time when the instrument was first traded or an order/quote was first received by Archax exchange
fullName	string	Full name of the instrument as registered to the ISIN
fullNameAndFunction	string	Not in use
generalMeetings	string	Not in use
governanceRating	string	Governance rating provided as part of ESG rating
highlights	string	Not in use
historyOfIssue	string	Not in use
incomeTaxParticulars	string	Not in use
incorporationDate	string	Date of incorporation of the issuer of the asset
initialPrice	string	Initial price of the asset when first admitted to the exchange
instrumentNews	string	Not in use
interestRates	string	Not in use
introVideoUrl	string	Not in use
investors	string	Not in use
isin	string	International securities identification number as provided by a national numbering agency
issuanceSize	string	Issuance size of the certificate expressed in Euros. Also used for bonds to show total bond size
jurisdictions	string	Not in use
lastYearRumunerationPaid	string	Not in use
lei	string	Legal entity identifier registered with the issuer of the asset
liquidityRisks	string	Not in use
litigation	string	Not in use
locationsDenied	string	Not in use
lockIn	string	Not in use
management	string	Not in use
marketOverview	string	Not in use
marketRisks	string	Not in use
mic	string	Market identifier code of the exchange on which the asset is traded
minimumOrderValue	string	Lowest value (price * quantity) the exchange will accept for an order to buy or sell the asset
mission	string	Not in use
nominalValueUnit	string	Nominal value of each unit of debt instrument as priced in the associated currency
oldInstrumentId	string	Not in use
ongoingPrincipalInvestments	string	Not in use
operational	string	Not in use
operationalRisks	string	Not in use
partners	string	Not in use
personalBankruptcies	string	Not in use
personsResponsible	string	Not in use
placeOfRegistration	string	Not in use
platform	string	Internal use only
priceMultiplier	string	Not in use
pricipalActivity	string	Not in use
primaryIssuancePlatform	string	Not in use
proceedsOfOffer	string	Not in use
profitForecasts	string	Not in use
projectDescription	string	Not in use
publicSanctions	string	Not in use
recentInsolvencies	string	Not in use
recentPartnerships	string	Not in use
regulation	string	Not in use
regulatoryBodies	string	Not in use
relatedIsin	string	Not in use
relatedPartyTransactions	string	Not in use
requestDate	string	Date and time of the request for admission to trading on the trading venue
researchPolicy	string	Not in use
securitiesClassAndTypes	string	Not in use
securitiesLegislation	string	Not in use
securitiesTradeRestrictions	string	Not in use
sedol	string	Not in use
segment	string	Not in use
settlementDate	string	Date expressed in T+n value of when settlement occurs n days after a trade (Same Day (T) for most assets in Archax exchange)
shareClass	string	Not in use
shareholderRights	string	Not in use
shareholdings	string	Not in use
shareNumber	string	For shares and depositary receipts: The total number of outstanding instruments. For ETFs: Number of units issued for trading
shareNumberExceeding	string	The total number of shares corresponding to holdings exceeding 5% of total voting rights of the issuer
shareRegisterCountry	string	Not in use
shortDescription	string	Not in use
shortName	string	Short name registered to the ISIN in accordance with ISO 18774 (Financial Instrument Short Name)
significantDates	string	Not in use
socialMedia	string	Not in use
socialRating	string	Social rating provided as part of ESG rating
statementOfCompliance	string	Not in use
statutoryAuditor	string	Not in use
taxation	string	Not in use
technology	string	Not in use
terminationDate	string	Date and time of when asset will cease to trade on Archax exchange
terms	string	Not in use
termsAndConditions	string	Not in use
terrorism	string	Not in use
tickSize	string	Smallest price variation allowed when submitting an order for the asset
tokeniser	string	Entity that created the token smart contract used to issue the asset
transferStatus	string	Not in use
trendInformation	string	Not in use
underlyingInstrumentId	string	Not in use
unpriSignatory	string	Indicator if issuer of asset is a signatory to the United Nations Principles for Responsible Investment
unspentConvictions	string	Not in use
useOfProceeds	string	Not in use
vwap	string	Not in use
website	string	Website associated with the asset and/or issuer
yield	string	Not in use

Open Orders

Request to

https://ace-auth.archax.com/api/1.0/open-orders

200 Response

{
  "status": "OK",

  "data": [
    {
      "quantity": "1",
      "untradedQuantity": "1",
      "limitPrice": "27185",
      "created": "1681456445562335",
      "instrumentId": 5,
      "executions": [],
      "id": "1681456445562335",
      "side": "sell",
      "userReference": "user_reference_1234"
    },
    {
      "quantity": "1",
      "untradedQuantity": "1",
      "limitPrice": "24185",
      "created": "1681456418146386",
      "instrumentId": 5,
      "executions": [],
      "id": "1681456418146386",
      "side": "buy",
      "userReference": "user_reference_12345"
    }
  ],

  "timestamp": "2023-04-14T07:14:10.666Z"
}

GET /open-orders

An endpoint that returns a list of all open orders for the user’s organisation. JWT must be included as bearer token.

Response Schema

Name	Type	Description
id	string	Unique order identifier
quantity	string	Order quantity without consideration of decimal places values (decimal places defined in `quantityDecimalPlaces` from Instruments Schema)
untradedQuantity	string	Quantity of unfilled portion of order without consideration of decimal places values (decimal places defined in `quantityDecimalPlaces` from Instruments Schema)
limitPrice	string	Order limit price without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
created	string	Timestamp on when the trade was executed (ms)
instrumentId	number	Unique identifier of the asset
executions	empty array	Not used
side	string	Order side, possible values: `buy`, `sell`
userReference	string	Value provided as `actionRef` in original submission of order

WebSocket API

The Archax WebSocket API allows developers to subscribe to real-time market data feeds.

Additionally, the API accepts commands for the creation and cancellation of orders.

Connection

Login command

{
  "action": "login",
  "service": "core",
  "token": "valid-token"
}

Successful login event

{
  "action": "user-login-success",
  "data": [],
  "description": "Authorisation successful",
  "status": "OK",
  "type": "user-login"
}

Failed login event

{
  "action": "user-login-failed",
  "data": [],
  "description": "Authorisation failed",
  "status": "ERROR",
  "type": "user-login"
}

The public WebSocket endpoint is wss://ace-auth.archax.com/api/1.0/gateway.

To login to the API you must obtain a JWT token from the REST login endpoint. In combination with the JWT, you must specify the login action and the core service.

Once your login credentials have been verified, you will receive a user-login-success event. Otherwise you will receive a user-login-failed event and you will then be disconnected.

Market Data

Subscribe to Instruments command

{
  "action": "subscribe-instruments"
}

Set Instruments event

{
  "status": "OK",
  "action": "set-instruments",
  "data": {
    "4": {
      "currency": "EUR",
      "decimals": 2,
      "description": "Fake AG SHRS",
      "id": 4,
      "marketStatus": "open",
      "name": "FAKE SHRS",
      "priceDecimalPlaces": 2,
      "quantityDecimalPlaces": 0,
      "regulatedStatus": "eligible",
      "symbol": "FAKe",
      "tradingStatus": "Trading",
      "type": "security",
      "venueId": "ARCHAX",
      "tickSize": "0.01"
    },
    "5": {
      "currency": "EUR",
      "decimals": 2,
      "description": "Fake Swiss Property",
      "id": 5,
      "marketStatus": "open",
      "name": "FKE Swiss Property",
      "priceDecimalPlaces": 2,
      "quantityDecimalPlaces": 0,
      "regulatedStatus": "eligible",
      "symbol": "FAKa",
      "tradingStatus": "Trading",
      "type": "security",
      "venueId": "ARCHAX",
      "tickSize": "1.00"
    },
    "9": {
      "currency": "USD",
      "decimals": 4,
      "description": "Fake BTC Ticker",
      "id": 9,
      "marketStatus": "closed",
      "name": "FKE BTC",
      "priceDecimalPlaces": 2,
      "quantityDecimalPlaces": 8,
      "regulatedStatus": "eligible",
      "symbol": "FBTC",
      "tradingStatus": "Suspended",
      "type": "crypto",
      "venueId": "ARCHAX",
      "tickSize": "0.1"
    }
  },
  "type": "instruments",
  "timestamp": "2021-07-08T07:00:20.190Z"
}

Set Instruments Event Schema

Name	Type	Description
[key]		Identifier of the asset
currency	string	3-letter currency code for the asset
decimals	number	The number of significant decimal places for the asset’s price
description	string	The full name of the asset
id	number	Unique identifier of the asset
marketStatus	string	Current market status for the asset. Possible values are: `open`, `closed` and `closing auction`
name	string	The short name for the asset
priceDecimalPlaces	number	Number of decimal places used by the system when accepting a price for the asset
quantityDecimalPlaces	number	Number of decimal places used by the system when accepting a quantity for the asset
regulatedStatus	string	The regulated status of the asset. Possible values are: `eligible` and `ineligible`
symbol	string	Ticker symbol for the asset
tradingStatus	string	Current trading status for the asset. Possible values are: `Created`, `Pre-Live`, `Trading`, `Suspended` and `Terminated`
type	string	The asset type. Possible values are: `security` and `crypto`
venueId	string	Default value: `ARCHAX`
tickSize	string	Minimum price amount an instrument can move

Subscribe to Market Quotes command

{
  "action": "subscribe-market-quotes"
}

Set Market Quotes event (initial)

{
  "status": "OK",
  "action": "set-market-quotes",
  "data": {
    "1": {
      "askPrice": "",
      "askQty": "",
      "bidPrice": "",
      "bidQty": "",
      "changePercent": "-38.60",
      "changePrice": "-6408",
      "closePrice": "16600",
      "cumulativeUnits": "",
      "cumulativeValue": "",
      "highPrice": "10192",
      "instrumentId": 1,
      "lastPrice": "10192",
      "lastQty": "1",
      "lowPrice": "10192",
      "openPrice": "10192",
      "sevenDayChange": "1068",
      "sevenDayChangePercentage": "11.71",
      "sevenDayClosePrice": "9124"
    },
    "2": {
      "askPrice": "",
      "askQty": "",
      "bidPrice": "",
      "bidQty": "",
      "changePercent": "-24.19",
      "changePrice": "-4112",
      "closePrice": "17000",
      "cumulativeUnits": "",
      "cumulativeValue": "",
      "highPrice": "13809",
      "instrumentId": 2,
      "lastPrice": "12888",
      "lastQty": "1",
      "lowPrice": "12967",
      "openPrice": "12888",
      "sevenDayChange": "867",
      "sevenDayChangePercentage": "7.21",
      "sevenDayClosePrice": "12021"
    },
    "3": {
      "askPrice": "",
      "askQty": "",
      "bidPrice": "",
      "bidQty": "",
      "changePercent": "0.00",
      "changePrice": "",
      "closePrice": "36900",
      "cumulativeUnits": "178",
      "cumulativeValue": "6723900",
      "highPrice": "39740",
      "instrumentId": 3,
      "lastPrice": "36900",
      "lastQty": "1287",
      "lowPrice": "36500",
      "openPrice": "36000",
      "sevenDayChange": "-3100",
      "sevenDayChangePercentage": "-7.75",
      "sevenDayClosePrice": "40000"
    }
  },
  "type": "market-quotes",
  "timestamp": "2021-10-05T10:53:59.201Z"
}

Set Market Quotes event (update)

{
  "status": "OK",
  "action": "set-market-quotes",
  "data": {
    "3": {
      "askPrice": "36555",
      "askQty": "250"
    }
  }
}

Set Market Quotes event (reset specified properties)

{
  "status": "OK",
  "action": "set-market-quotes",
  "data": {
    "3": {
      "bidPrice": "",
      "bidQty": "",
      "openPrice": ""
    }
  }
}

Each value in the data property is keyed by instrumentId.

Set Market Quotes Event Schema

Name	Type	Description
[key]		Identifier of the asset
askPrice	string	Best asking price for the asset without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
askQty	string	Number of units on offer at the `askPrice`
bidPrice	string	Best bid price for the asset without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
bidQty	string	Number of units requested at the `bidPrice`
changePercent	string	The percentage difference between the `lastPrice` and `closePrice`
changePrice	string	The difference between the `lastPrice` and `closePrice` without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
closePrice	string	The asset’s last traded price from the previous trading session without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
cumulativeUnits	string	The cumulative volume of units traded within the current trading session
cumulativeValue	string	The cumulative value of all trades on the asset for the current trading session without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
instrumentId	number	Unique identifier of the asset
lastPrice	string	Last traded price for the asset without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
highPrice	string	Highest trade price for the asset during the current trading session without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
lowPrice	string	Lowest trade price for the asset during the current trading session without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
lastQty	string	Last traded quantity for the asset
openPrice	string	Price at which the first execution of the day for the asset occurred without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
sevenDayChange	string	The difference between `closePrice` and `sevenDayClosePrice` without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
sevenDayChangePercentage	string	The percentage difference between the `closePrice` and `sevenDayClosePrice`
sevenDayClosePrice	string	The asset’s close price 7 days prior without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)

askPrice, bidPrice, changePrice, closePrice, cumulativeValue, highPrice, lastPrice, lowPrice, openPrice, sevenDayChange and sevenDayClosePrice would always be returned as a whole number. The number of decimal places for each asset then determines how these price values are formatted. Use the priceDecimalPlaces property returned by the set-instruments event to determine the number of decimal places for the value in these fields.

"2": { "askPrice": "", "askQty": "", "bidPrice": "", "bidQty": "", "changePercent": "-24.19", "changePrice": "-4112.00", "closePrice": "17000", "cumulativeUnits": "", "cumulativeValue": "", "highPrice": "12888", "instrumentId": 2, "lastPrice": "12888", "lastQty": "3", "lowPrice": "12888", "openPrice": "", "sevenDayChange": "867.00", "sevenDayChangePercentage": "7.21", "sevenDayClosePrice": "12021" }

and you receive an update with following data:

{ "2": { "askQty": "35", } }

the expected state of instrumentId 2 is:

"2": { "askPrice": "", "askQty": "35", "bidPrice": "", "bidQty": "", "changePercent": "-24.19", "changePrice": "-4112.00", "closePrice": "17000", "cumulativeUnits": "", "cumulativeValue": "", "highPrice": "12888", "instrumentId": 2, "lastPrice": "12888", "lastQty": "3", "lowPrice": "12888", "openPrice": "", "sevenDayChange": "867.00", "sevenDayChangePercentage": "7.21", "sevenDayClosePrice": "12021" }

At the start of a trading session, a set-market-quotes event would be returned and the content of its data property would be similar to:

the expected state of instrumentId 2 would then be:

"2": { "askPrice": "", "askQty": "", "bidPrice": "", "bidQty": "", "changePercent": "0.00", "changePrice": "0", "closePrice": "17000", "cumulativeUnits": "", "cumulativeValue": "", "highPrice": "", "instrumentId": 2, "lastPrice": "12888", "lastQty": "3", "lowPrice": "", "openPrice": "", "sevenDayChange": "867.00", "sevenDayChangePercentage": "7.21", "sevenDayClosePrice": "12021" }

Subscribe to Cash command

{
  "action": "subscribe-cash"
}

Set Cash event

{
  "status": "OK",
  "action": "set-cash",
  "data": {
    "1": {
      "currency": "GBP",
      "decimals": 2,
      "description": "British pound sterling",
      "id": 1,
      "marketStatus": "closed",
      "name": "GBP",
      "priceDecimalPlaces": 2,
      "quantityDecimalPlaces": 2,
      "regulatedStatus": "eligible",
      "symbol": "GBP",
      "tickSize": "",
      "tradingStatus": "Created",
      "type": "cash",
      "venueId": "ARCHAX",
      ""
    },
    "2": {
      "currency": "USD",
      "decimals": 2,
      "description": "U.S. Dollar",
      "id": 2,
      "marketStatus": "closed",
      "name": "USD",
      "priceDecimalPlaces": 2,
      "quantityDecimalPlaces": 2,
      "regulatedStatus": "eligible",
      "symbol": "USD",
      "tickSize": "",
      "tradingStatus": "Created",
      "type": "cash",
      "venueId": "ARCHAX"
    },
    "27": {
      "currency": "NGN",
      "decimals": 2,
      "description": "Electronic Naira",
      "id": 27,
      "marketStatus": "closed",
      "name": "eNaira",
      "priceDecimalPlaces": 2,
      "quantityDecimalPlaces": 2,
      "regulatedStatus": "eligible",
      "symbol": "eNGN",
      "tickSize": "",
      "tradingStatus": "Created",
      "type": "cash",
      "venueId": "ARCHAX"
    },
    "28": {
      "currency": "MNY",
      "decimals": 2,
      "description": "MONEY",
      "id": 28,
      "marketStatus": "closed",
      "name": "MONEY",
      "priceDecimalPlaces": 2,
      "quantityDecimalPlaces": 2,
      "regulatedStatus": "eligible",
      "symbol": "MNY",
      "tickSize": "",
      "tradingStatus": "Created",
      "type": "cash",
      "venueId": "ARCHAX"
    },
    "29": {
      "currency": "PHP",
      "decimals": 2,
      "description": "Philippine Fiat Currency",
      "id": 29,
      "marketStatus": "closed",
      "name": "Philippine Peso",
      "priceDecimalPlaces": 2,
      "quantityDecimalPlaces": 2,
      "regulatedStatus": "eligible",
      "symbol": "PHP",
      "tickSize": "",
      "tradingStatus": "Created",
      "type": "cash",
      "venueId": "ARCHAX"
    }
  },
  "type": "cash",
  "timestamp": "2023-03-10T07:28:31.028Z"
}

Set Cash Event Schema

Name	Type	Description
[key]		Identifier of the asset
currency	string	3-letter currency code for the asset
decimals	number	The number of significant decimal places for the asset’s price
description	string	The full name of the asset
id	number	Unique identifier of the asset
marketStatus	string	Current market status for the asset. Possible values are: `open`, `closed` and `closing auction`
name	string	The short name for the asset
priceDecimalPlaces	number	Number of decimal places used by the system when accepting a price for the asset
quantityDecimalPlaces	number	Number of decimal places used by the system when accepting a quantity for the asset
regulatedStatus	string	The regulated status of the asset. Possible values are: `eligible` and `ineligible`
symbol	string	Ticker symbol for the asset
tickSize	string	Minimum price amount an instrument can move
tradingStatus	string	Current trading status for the asset. Possible values are: `Created`, `Pre-Live`, `Trading`, `Suspended` and `Terminated`
type	string	The asset type. Possible values are: `security` and `crypto`
venueId	string	Default value: `ARCHAX`

Balances

Fetch Balances

Fetch Balances command

{
  "action": "fetch-balances"
}

Fetch Balances event

{
  "action": "fetch-balances",
  "data": {
    "2786123094": {
      "accountId": 2786123094,
      "accountType": "accountSecurity",
      "available": "1000000400",
      "instrumentId": 1,
      "regulatoryEligibility": "eligible",
      "total": "1000000400"
    },
    "2786123904": {
      "accountId": 2786123904,
      "accountType": "accountSecurity",
      "available": "1000000400",
      "regulatoryEligibility": "eligible",
      "instrumentId": 2,
      "total": "1000000400"
    },
    "2786123095": {
      "accountId": 2786123095,
      "accountType": "accountCrypto",
      "available": "1000000400",
      "regulatoryEligibility": "ineligible",
      "instrumentId": 3,
      "total": "1000000400"
    },
    "2786123398": {
      "accountId": 2786123398,
      "accountType": "accountCash",
      "available": "1000000400",
      "regulatoryEligibility": "eligible",
      "instrumentId": 4,
      "total": "1000000400"
    },
    "2786122842": {
      "accountId": 2786122842,
      "accountType": "accountUnregulatedCash",
      "available": "1000000400",
      "regulatoryEligibility": "ineligible",
      "instrumentId": 5,
      "total": "1000000400"
    },
    "2786122894": {
      "accountId": 2786122894,
      "accountType": "accountCash",
      "available": "1000000400",
      "regulatoryEligibility": "eligible",
      "instrumentId": 6,
      "total": "1000000400"
    }
  },
  "timestamp": "2021-07-01T04:30:06.127Z"
}

Send a fetch-balances command to retrieve all account balances for the organisation to which you belong. The response is a fetch-balances event that includes a data property where the object is keyed by accountId. The fetch-balances event includes the following details:

Fetch Balances Event Schema

Name	Type	Description
[key]		Identifier of the account
accountId	number	Unique identifier for the account
accountType	string	Type of account. The possible values are: `accountCash`, `accountUnregulatedCash`, `accountSecurity` and `accountCrypto`
available	string	Available balance of account (for cash accounts, the last two digits are decimal places)
regulatoryEligibility	string	Indicates regulatory eligibility. Possible values are: `eligible` and `ineligible`
instrumentId	number	Identifier of the account asset
total	string	Total balance of account (for cash accounts, the last two digits are decimal places)

Subscribe to Balances command

{
  "action": "subscribe-balances"
}

Set Balances event

{
  "status": "OK",
  "action": "set-balances",
  "data": {
    "2786123094": {
      "accountId": 2786123094,
      "accountType": "accountCash",
      "available": "1000000400",
      "instrumentId": 1,
      "regulatoryEligibility": "eligible",
      "total": "1000000400"
    },
    "2786123095": {
      "accountId": 2786123095,
      "accountType": "accountSecurity",
      "available": "1000000400",
      "instrumentId": 2,
      "regulatoryEligibility": "eligible",
      "total": "1000000400"
    },
    "2786122842": {
      "accountId": 2786122842,
      "accountType": "accountCrypto",
      "available": "1000180131",
      "instrumentId": 3,
      "regulatoryEligibility": "ineligible",
      "total": "1000180207"
    }
  },
  "type": "balances",
  "timestamp": "2021-07-01T04:30:06.408Z"
}

Send a subscribe-balances command to subscribe to account balance updates. It will initially return a set-balances event that contains all account balances while subsequent set-balances events will only include account balances that have since been updated. The data property is an object keyed by accountId, with the following details:

Set Balances Event Schema

Name	Type	Description
[key]		Identifier of the account
accountId	number	Unique identifier for the account
accountType	string	Type of account. The possible values are: `accountCash`, `accountUnregulatedCash`, `accountSecurity` and `accountCrypto`
available	string	Available balance of account (for cash accounts, the last two digits are decimal places)
instrumentId	number	Unique identifier of the asset
regulatoryEligibility	string	Indicates regulatory eligibility. Possible values are: `eligible` and `ineligible`
total	string	Total balance of account (for cash accounts, the last two digits are decimal places)

Orders

Submit an Order

Submit Order command

{
  "action": "order-submit",
  "data": {
    "actionRef": "user_reference_1234",
    "instrumentId": 3,
    "limitPrice": "356.99",
    "orderType": 0,
    "quantity": 100,
    "side": 0
  }
}

Order Updated event

{
  "status": "OK",
  "action": "order-updated",
  "data": {
    "actionRef": "user_reference_1234",
    "orderId": "1625642744032536",
    "organisationId": 1,
    "status": "open"
  },
  "type": "notifications",
  "timestamp": "2021-07-07T07:25:45.140Z"
}

Order Updated event with status ERROR (order rejected)

{
  "status": "ERROR",
  "action": "order-updated",
  "data": {
    "actionRef": "user_reference_1234",
    "error": "Dynamic Price Collar",
    "orderId": "1626062904341855",
    "organisationId": 1,
    "status": "rejected"
  },
  "type": "notifications",
  "timestamp": "2021-07-07T07:25:45.140Z"
}

Order Submitted event with status ERROR

{
  "status": "ERROR",
  "action": "order-submitted",
  "data": {
    "error": "No instrument selected",
    "actionRef": "user_reference_1234"
  },
  "type": "notifications",
  "timestamp": "2021-07-07T07:45:04.231Z"
}

Send an order-submit command to submit an order. The response is either an order-updated event for a successfully received order or an order-submitted event with a status of ERROR.

Order Submit Command Schema

Name	Type	Description
actionRef	string	User-specified identifier; it will be included the response
instrumentId	number	Unique identifier of the asset
limitPrice	string	Limit Price for the order
orderType	number	Type of order, possible values: `0` = Limit Order
quantity	string	Quantity for the order
side	number	Market side of order, possible values: `0` = Buy, `1` = Sell

When an actionRef is provided, it must be unique across all commands.

Order Updated Event Schema

Name	Type	Description
actionRef	string	If the order `status` is `open` or `rejected`, it will be the `actionRef` that was included in the submitted order. If the order `status` is `cancelled`, it will be the `orderId`. Otherwise it will not be included for other `status` values.
error	string	Description of error that was identified, will not be included if there is no error.
orderId	string	Unique identifier for the order
organisationId	number	Unique identifier for the organisation that placed the order
status	string	Status of order, possible values: `pending`, `open`, `cancelled`, `expired`, `rejected`, `completed`

Order Submitted (Error) Event Schema

Name	Type	Description
error	string	Description of error that was identified
actionRef	string	User-specified identifier that was included in the submitted order

Subscribe to Orders command

{
  "action": "subscribe-orders"
}

Set Orders event (initial)

{
  "status": "OK",
  "action": "set-orders",
  "data": {
    "1623217157444399": {
      "averagePrice": "1000",
      "created": "1623217157444",
      "commission": "10",
      "currency": "EUR",
      "decimals": 2,
      "executions": {
        "1623217158966156": {
          "created": "1623217158966",
          "commission": "10",
          "grossExecutionAmount": "17000",
          "price": "1000",
          "id": "1623217158966156",
          "quantity": "17",
          "tax": "0"
        }
      },
      "filledPercent": "100.00",
      "filledQty": "17",
      "filledStatus": "filled",
      "id": "1623217157444399",
      "instrumentId": 24,
      "limitPrice": "1000",
      "orderStatus": "completed",
      "quantity": "17",
      "side": "buy",
      "symbol": "OASa",
      "type": "limit",
      "tax": "0",
      "userId": 1
    },
    "1623217157504910": {
      "averagePrice": "1000",
      "created": "1623217157504",
      "commission": "20",
      "currency": "GBX",
      "decimals": 2,
      "executions": {
        "1623217159226194": {
          "created": "1623217159226",
          "commission": "20",
          "grossExecutionAmount": "14000",
          "price": "1000",
          "id": "1623217159226194",
          "quantity": "14",
          "tax": "0"
        }
      },
      "filledPercent": "100.00",
      "filledQty": "14",
      "filledStatus": "filled",
      "id": "1623217157504910",
      "instrumentId": 25,
      "limitPrice": "1000",
      "orderStatus": "completed",
      "quantity": "14",
      "side": "sell",
      "symbol": "OADa",
      "type": "limit",
      "tax": "0",
      "userId": 2
    }
  },
  "type": "orders",
  "timestamp": "2021-07-06T08:04:40.837Z"
}

Set Orders event (update)

{
  "status": "OK",
  "action": "set-orders",
  "data": {
    "1626077181607120": {
      "orderStatus": "open"
    }
  },
  "type": "orders",
  "timestamp": "2021-07-12T08:06:21.613Z"
}

Send a subscribe-orders command to subscribe to order updates for the organisation you belong to. It initially returns a set-orders event that includes all orders. Subsequent set-orders events will only contain orders that have since been updated. The data property will be an object keyed by order id, with the following details:

Set Orders Event Schema

Name	Type	Description
[key]		Unique order identifier
averagePrice	string	Average execution price for the order without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
created	string	Timestamp on when the order was placed (ms)
currency	string	Currency code
commission	string	Total commission value of the order
decimals	number	Number of decimal places of price figures of order instrument
executions	Execution	Details of executed trades, keyed by `id` (where `id` is a unique reference to the execution)
filledPercent	string	Filled percent
filledQty	string	Filled quantity without consideration of decimal places value (decimal places defined in `quantityDecimalPlaces` from Instruments Schema)
filledStatus	string	Fill status, possible values: `unfilled`, `partiallyFilled`, `filled`
id	string	Unique order identifier
instrumentId	number	Unique identifier of the asset
limitPrice	string	Order limit price without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
orderStatus	string	Order status, possible values: `pending`, `open`, `cancelled`, `expired`, `rejected`, `completed`
quantity	string	Order quantity without consideration of decimal places value (decimal places defined in `quantityDecimalPlaces` from Instruments Schema)
side	string	Order side, possible values: `buy`, `sell`
symbol	string	Ticker symbol of instrument
type	string	Order type, possible values: `limit`
tax	string	Total tax value of the order
userId	number	Unique identifier of the user

Execution Schema

Name	Type	Description
commission	string	Total commission value of the execution
created	string	Timestamp on when the trade was executed (ms)
grossExecutionAmount	string	Product of executed price and quantity
price	string	Executed price without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
id	string	Unique identifier to execution
quantity	string	Executed quantity without consideration of decimal places value (decimal places defined in `quantityDecimalPlaces` from Instruments Schema)
tax	string	Total tax value of the order

set-orders updates must be deeply merged from the previous state. For example, if an order has the following state:

and you receive an update with following data:

{ "1626077181607120": { "orderStatus": "open" } }

the expected state of order 1626077181607120 is:

Cancel an Order

Cancel Order Command

{
  "action": "order-cancel",
  "data": {
    "actionRef": "user_reference_1234",
    "orderId": "1625642744032536"
  }
}

Order Cancelled Event

{
  "status": "OK",
  "action": "order-cancelled",
  "data": {
    "actionRef": "1625642744032536",
    "orderId": "1625642744032536",
    "organisationId": 1,
    "status": "cancelled"
  },
  "type": "notifications",
  "timestamp": "2021-07-07T18:57:04.231Z"
}

Cancellation Rejected Event

{
  "status": "ERROR",
  "action": "cancel-rejected",
  "data": {
    "actionRef": "1625642744032536",
    "error": "Order cannot be cancelled",
    "orderId": "1625642744032536",
    "organisationId": 1,
    "reason": "marketClosed",
    "status": "completed",
    "userId": 12
  },
  "type": "notifications",
  "timestamp": "2021-07-07T18:57:04.231Z"
}

Cancel Failed Event with ERROR status

{
  "status": "ERROR",
  "action": "cancel-failed",
  "data": {
    "error": "No order id provided",
    "actionRef": "user_reference_1234"
  },
  "type": "notifications",
  "timestamp": "2021-07-07T18:57:04.231Z"
}

Send an order-cancel command to cancel an order.

The successful cancellation of an order would cause an order-cancelled event to be returned while a cancel-failed event is returned when there are errors in the submitted order-cancel command.

Cancel Order Command Schema

Name	Type	Description
actionRef	string	Optional field for client to include a unique identifier
orderId	string	Unique identifier for the order

When an actionRef is provided, it must be unique across all commands.

Order Cancelled Event Schema

Name	Type	Description
actionRef	string	Unique identifier provided by client
orderId	string	Unique identifier for the order
organisationId	number	Unique identifier for the organisation that placed the order
status	string	The status of the order

Cancellation Rejected Event Schema

Name	Type	Description
actionRef	string	Unique identifier provided by client
error	string	Error message
orderId	string	Unique identifier for the order
organisationId	number	Unique identifier for the organisation that placed the order
reason	string	The reason for the rejection
status	string	The status of the order
userId	string	Unique identifier of the user that requested the cancellation

Cancellation Failed Event Schema

Name	Type	Description
actionRef	string	User-specified identifier
error	string	Error message; would contain the reason for the failure

Order Book

Subscribe to Market Depths command

{
  "action": "subscribe-market-depths"
}

Set Market Depths event (initial)

{
  "status": "OK",
  "action": "set-market-depths",
  "data": {
    "1": {
      "buy": {
        "1200": 100,
        "1300": 50
      },
      "indicativePrice": "",
      "indicativeVolume": "",
      "instrumentId": 1,
      "sell": {
        "1310": 20,
        "1320": 50
      }
    },
    "2": {
      "buy": {
        "2300": 10,
        "2400": 10
      },
      "indicativePrice": "",
      "indicativeVolume": "",
      "instrumentId": 2,
      "sell": {
        "2500": 15,
        "2510": 100
      }
    },
    "3": {
      "buy": {
        "10000": 20,
        "9900": 30
      },
      "indicativePrice": "",
      "indicativeVolume": "",
      "instrumentId": 1,
      "sell": {
        "10100": 30,
        "10110": 50
      }
    }
  },
  "type": "market-depths",
  "timestamp": "2021-07-01T05:17:00.691Z"
}

Set Market Depths event (update)

{
  "status": "OK",
  "action": "set-market-depths",
  "data": {
    "1": {
      "instrumentId": 1,
      "buy": {
        "1200": 120
      },
      "sell": {}
    }
  },
  "type": "market-depths",
  "timestamp": "2021-07-01T05:17:00.691Z"
}

Set Market Depths event (update, depth removed from Order Book)

{
  "status": "OK",
  "action": "set-market-depths",
  "data": {
    "1": {
      "instrumentId": 1,
      "buy": {
        "1200": 0
      },
      "sell": {
        "1199": 0
      }
    }
  },
  "type": "market-depths",
  "timestamp": "2021-07-01T05:17:00.691Z"
}

Set Market Depths Event Schema

Name	Type	Description
[key]		Identifier of the asset
buy	string	Market depth (price) for the buy side of the market
indicativePrice	string	(Provided during auction phase) The price at which the most executions would occur if the auction ended at the current time. Also referred to as the uncrossing price
indicativeVolume	string	(Provided during auction phase) The number of units that would exchange hands if the auction ended at the current time
instrumentId	number	Identifier of the asset
sell	string	Market depth (price) for the sell side of the market

Market Depth Schema (Buy or Sell)

Name	Type	Description
[key]		Market depth (price without consideration of decimal places value, decimal places defined in `priceDecimalPlaces` from Instruments Schema)
[value]	number	Volume (quantity without consideration of decimal places value, decimal places defined in `quantityDecimalPlaces` from Instruments Schema)

set-market-depths updates must be deeply merged from the previous state. For example, if an instrument has the following state:

{ "1": { "buy": { "1200": 100, "1300": 50 }, "indicativePrice": "", "indicativeVolume": "", "instrumentId": 1, "sell": { "1310": 20, "1320": 50 } } }

and you receive an update with following data:

{ "1": { "buy": { "1100": 500 }, "instrumentId": 1, "sell": {} } }

the expected state of instrumentId 1 is:

{ "1": { "buy": { "1100": 500, "1200": 100, "1300": 50 }, "indicativePrice": "", "indicativeVolume": "", "instrumentId": 1, "sell": { "1310": 20, "1320": 50 } } }

set-market-depths updates with a quantity value of 0 are sent to clear a particular depth. For example, if an instrument has the following state:

{ "1": { "buy": { "1200": 100, "1300": 50 }, "indicativePrice": "", "indicativeVolume": "", "instrumentId": 1, "sell": { "1310": 20, "1320": 50 } } }

and you receive an update with following data:

{ "1": { "buy": { "1300": 0 }, "instrumentId": 1, "sell": {} } }

the expected state of instrumentId 1 is:

{ "1": { "buy": { "1200": 100 }, "indicativePrice": "", "indicativeVolume": "", "instrumentId": 1, "sell": { "1310": 20, "1320": 50 } } }

Trades

Subscribe to a single instruments Trade History command. Where 1 denotes an example instrumentId.

{
  "action": "subscribe-trade-histories/1"
}

Subscribe to all Trade History.

{
  "action": "subscribe-trade-histories"
}

Response JSON returned example -

Initial Set Trade History event

{
  "status": "OK",
  "action": "set-trade-histories/1",
  "data": {
    "1": [
      {
        "amount": "81",
        "created": "1619080206756725504",
        "price": "9124",
        "side": "sell",
        "tradeRef": "1"
      },
      {
        "amount": "4",
        "created": "1619080141466397184",
        "price": "10875",
        "side": "buy",
        "tradeRef": "2"
      },
      {
        "amount": "48",
        "created": "1619080099647654400",
        "price": "9059",
        "side": "buy",
        "tradeRef": "3"
      }
    ]
  },
  "type": "trade-histories",
  "timestamp": "2021-08-27T14:39:46.820Z"
}

Set Trade History event (update)

{
  "status": "OK",
  "action": "append-trade-histories/1",
  "data": {
    "1": [
      {
        "amount": "45",
        "created": "1619080206756725534",
        "price": "9127",
        "side": "sell",
        "tradeRef": "4"
      }
    ]
  },
  "type": "trade-histories",
  "timestamp": "2021-08-27T15:35:59.147Z"
}

Note that a maximum of the latest twenty orders only is returned for the requested instrumentId or the latest 20 for all trade history.

The data property is an object keyed by instrumentId, with the following details:

Set trade history Event Schema

Name	Type	Description
[key]		Unique identifier of the instrument
amount	string	Quantity traded
created	string	Time of trade
price	string	Executed price without consideration of decimal places (decimal places defined in `priceDecimalPlaces` from Instruments Schema)
side	string	Aggressive side of order (`buy` or `sell`). `auction` is returned as value when trade is a result of an auction
tradeRef	string	Unique identifier of trade

Transactions

Subscribe to Transactions command

{
  "action": "subscribe-transactions"
}

Set Transaction event

{
  "status": "OK",
  "action": "set-transactions",
  "data": {
    "entries": [
      {
        "id": "1631023590277781",
        "organisationId": 3,
        "userId": 12,
        "accountId": 2786122875,
        "amount": "10",
        "referenceId": "1631023590277580",
        "created": "1631023590272836",
        "ledgerType": "debit",
        "reportType": "execution",
        "commissionReference": "0",
        "instrumentId": "3"
      },
      {
        "id": "1631023590278240",
        "organisationId": 3,
        "userId": 12,
        "accountId": 2786122905,
        "amount": "409500",
        "referenceId": "1631023590277580",
        "created": "1631023590272872",
        "ledgerType": "credit",
        "reportType": "execution",
        "commissionReference": "0",
        "instrumentId": "33"
      },
      {
        "id": "1631016154737596",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123148,
        "amount": "109",
        "referenceId": "1631016154736971",
        "created": "1631016154725876",
        "ledgerType": "debit",
        "reportType": "commission",
        "commissionReference": "1631016099181019",
        "instrumentId": "7"
      },
      {
        "id": "1631016154737159",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123148,
        "amount": "1090",
        "referenceId": "1631016154736971",
        "created": "1631016154725882",
        "ledgerType": "debit",
        "reportType": "execution",
        "commissionReference": "0",
        "instrumentId": "32"
      },
      {
        "id": "1631016154738149",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123124,
        "amount": "109",
        "referenceId": "1631016154736971",
        "created": "1631016154725886",
        "ledgerType": "credit",
        "reportType": "execution",
        "commissionReference": "0",
        "instrumentId": "7"
      },
      {
        "id": "1631014364506141",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123148,
        "amount": "109",
        "referenceId": "1631014364505500",
        "created": "1631014364499891",
        "ledgerType": "debit",
        "reportType": "commission",
        "commissionReference": "1631014308958295",
        "instrumentId": "7"
      },
      {
        "id": "1631014364505723",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123148,
        "amount": "1090",
        "referenceId": "1631014364505500",
        "created": "1631014364499895",
        "ledgerType": "debit",
        "reportType": "execution",
        "commissionReference": "0",
        "instrumentId": "32"
      },
      {
        "id": "1631014364507061",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123124,
        "amount": "109",
        "referenceId": "1631014364505500",
        "created": "1631014364499900",
        "ledgerType": "credit",
        "reportType": "execution",
        "commissionReference": "0",
        "instrumentId": "7"
      },
      {
        "id": "1631014099470021",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123124,
        "amount": "1234",
        "referenceId": "1631014099467372",
        "created": "1631014099463903",
        "ledgerType": "credit",
        "reportType": "execution",
        "commissionReference": "0",
        "instrumentId": "7"
      },
      {
        "id": "1631014099468016",
        "organisationId": 3,
        "userId": 5,
        "accountId": 2786123148,
        "amount": "121",
        "referenceId": "1631014099467372",
        "created": "1631014099463907",
        "ledgerType": "debit",
        "reportType": "commission",
        "commissionReference": "1631014043667348",
        "instrumentId": "7"
      }
    ]
  },
  "type": "transactions",
  "timestamp": "2021-09-08T00:46:23.587Z"
}

Send a subscribe-transactions command to subscribe to transaction updates. It will return a set-transactions event that contains the last 1000 transactions for the organisation you belong to. Subsequent transactions would also cause a set-transactions event to be returned which will maintain the same data structure and the list of entries would include the new transactions.

The data property is an object with a single key entries which in turn is an array of transaction objects. Each transaction object has the following details:

Set Transaction Event Schema

Name	Type	Description
id	string	Unique identifier of the transaction
organisationId	number	Unique identifier for the organisation associated with the transaction
userId	number	Unique identifier of the user associated with the transaction
accountId	number	Unique identifier for the account
amount	string	For cash accounts - actual monetary value of the transaction where the last two digits are decimal places
		For security accounts - quantity involved in the transaction
referenceId	string	Unique reference to event (where event can be an execution or a notification for a deposit etc.)
created	string	Time of transaction
ledgerType	string	Value is one of `credit` or `debit`
reportType	string	Value can be one of - `commission`, `execution`, `deposit`, `fee`, `coupon`, `manualCorrection`, `interest`, `dividend`, `withdrawal` or `tax`
commissionReference	string	Unique identifier of the commission if applicable
instrumentId	string	Unique identifier of the asset

set-transactions event updates must completely replace the previous state. For example, if your transactions list has the following state:

[ { "id": "1631014099470021", "organisationId": 3, "userId": 5, "accountId": 2786123124, "amount": "1234", "referenceId": "1631014099467372", "created": "1631014099463903", "ledgerType": "credit", "reportType": "execution", "commissionReference": "0", "instrumentId": "7" }, { "id": "1631014099468016", "organisationId": 3, "userId": 5, "accountId": 2786123148, "amount": "121", "referenceId": "1631014099467372", "created": "1631014099463907", "ledgerType": "debit", "reportType": "commission", "commissionReference": "1631014043667348", "instrumentId": "7" } ]

an event to update the list of transactions you have would be in the form:

{ "status": "OK", "action": "set-transactions", "data": { "entries": [ { "id": "1631014364507061", "organisationId": 3, "userId": 5, "accountId": 2786123124, "amount": "109", "referenceId": "1631014364505500", "created": "1631014364499900", "ledgerType": "credit", "reportType": "execution", "commissionReference": "0", "instrumentId": "7" }, { "id": "1631014099470021", "organisationId": 3, "userId": 5, "accountId": 2786123124, "amount": "1234", "referenceId": "1631014099467372", "created": "1631014099463903", "ledgerType": "credit", "reportType": "execution", "commissionReference": "0", "instrumentId": "7" }, { "id": "1631014099468016", "organisationId": 3, "userId": 5, "accountId": 2786123148, "amount": "121", "referenceId": "1631014099467372", "created": "1631014099463907", "ledgerType": "debit", "reportType": "commission", "commissionReference": "1631014043667348", "instrumentId": "7" } ] } }

and the resulting transactions state will be:

[ { "id": "1631014364507061", "organisationId": 3, "userId": 5, "accountId": 2786123124, "amount": "109", "referenceId": "1631014364505500", "created": "1631014364499900", "ledgerType": "credit", "reportType": "execution", "commissionReference": "0", "instrumentId": "7" }, { "id": "1631014099470021", "organisationId": 3, "userId": 5, "accountId": 2786123124, "amount": "1234", "referenceId": "1631014099467372", "created": "1631014099463903", "ledgerType": "credit", "reportType": "execution", "commissionReference": "0", "instrumentId": "7" }, { "id": "1631014099468016", "organisationId": 3, "userId": 5, "accountId": 2786123148, "amount": "121", "referenceId": "1631014099467372", "created": "1631014099463907", "ledgerType": "debit", "reportType": "commission", "commissionReference": "1631014043667348", "instrumentId": "7" } ]

Custody

Subscribe To Deposits command

{
  "action": "subscribe-deposits"
}

Set Deposits event

{
  "status": "OK",
  "action": "set-deposits",
  "data": {
    "1658732301686225": {
      "accountId": "118",
      "amount": "300000",
      "created": "1658732301000000",
      "id": "1658732301686225",
      "instrumentId": 1,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658732301544438",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658732301000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658730084256007": {
      "accountId": "118",
      "amount": "300000",
      "created": "1658730084000000",
      "id": "1658730084256007",
      "instrumentId": 1,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658730084120637",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658730084000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658730034966343": {
      "accountId": "118",
      "amount": "300000",
      "created": "1658730034000000",
      "id": "1658730034966343",
      "instrumentId": 1,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658730034833466",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658730034000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658729853582198": {
      "accountId": "120",
      "amount": "300000",
      "created": "1658729853000000",
      "id": "1658729853582198",
      "instrumentId": 2,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658729853446574",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658729853000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658729762673091": {
      "accountId": "120",
      "amount": "300000",
      "created": "1658729762000000",
      "id": "1658729762673091",
      "instrumentId": 2,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658729762538762",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658729762000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658729594686221": {
      "accountId": "120",
      "amount": "300000",
      "created": "1658729594000000",
      "id": "1658729594686221",
      "instrumentId": 2,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658729594553480",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658729594000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658728733406117": {
      "accountId": "120",
      "amount": "300000",
      "created": "1658728733000000",
      "id": "1658728733406117",
      "instrumentId": 2,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658728733271718",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658728733000000",
      "userId": 13,
      "walletAddress": ""
    },
    "1658728201164503": {
      "accountId": "120",
      "amount": "300000",
      "created": "1658728201000000",
      "id": "1658728201164503",
      "instrumentId": 2,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "1658728201033042",
      "status": "Pending",
      "type": "Deposit",
      "updated": "1658728201000000",
      "userId": 13,
      "walletAddress": ""
    }
  },
  "type": "deposits",
  "timestamp": "2023-03-10T07:31:20.908Z"
}

The data property is an object with a single key entries which in turn is an array of deposit objects. Each deposit object has the following details:

Set Deposit Event Schema

Name	Type	Description
[key]		Unique identifier of the deposit
accountId	string	Unique identifier of the ledger account
amount	string	Amount of the deposit where the last n digits are decimal places corresponding to the quantity decimal place value assigned to the asset (ex. GBP has 2 decimal place value so an amount of “1000” would equate to £10.00)
created	string	Time of transaction
id	string	Unique identifier of the deposit
instrumentId	number	Unique identifier of the asset deposited
organisationId	number	Unique identifier of the client
reason	string	Additional details for deposits that do not successfully complete
referenceId	string	For cash - unique identifier that needs to be included in the reference field of the payment. For security assets- wallet address assigned as recipient address for transfer
status	string	Current state of the transaction, can be submitted, pending, cancelled, rejected or completed
type	string	Only `Deposit` returned as value
updated	string	Time stamp of the last time an action occurred on the deposit notification
userId	number	Unique identifier of the user who submitted the deposit notification
walletAddress	string	Depreciated field that returns empty string

Subscribe to Withdrawals command

{
  "action": "subscribe-withdrawals"
}

Set Withdrawals event

{
  "status": "OK",
  "action": "set-withdrawals",
  "data": {
    "1660545047277119": {
      "accountId": 118,
      "amount": "100",
      "created": "1660545047000000",
      "id": "1660545047277119",
      "instrumentId": 1,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "123456",
      "status": "Pending",
      "type": "Withdrawal",
      "updated": "1660545047000000",
      "userId": 27,
      "walletAddress": ""
    },
    "1660542988806807": {
      "accountId": 118,
      "amount": "1000",
      "created": "1660542988000000",
      "id": "1660542988806807",
      "instrumentId": 1,
      "organisationId": 1,
      "reason": "None",
      "referenceId": "12345",
      "status": "Pending",
      "type": "Withdrawal",
      "updated": "1660542988000000",
      "userId": 27,
      "walletAddress": ""
    }
  },
  "type": "withdrawals",
  "timestamp": "2023-03-10T07:36:31.616Z"
}

The data property is an object with a single key entries which in turn is an array of withdrawal objects. Each withdrawal object has the following details:

Set Withdrawal Event Schema

Name	Type	Description
[key]		Unique identifier of the withdrawal
accountId	string	Unique identifier of the ledger account
amount	string	Amount of the withdrawal where the last n digits are decimal places corresponding to the quantity decimal place value assigned to the asset (ex. GBP has 2 decimal place value so an amount of “1000” would equate to £10.00)
created	string	Time of transaction
id	string	Unique identifier of the withdrawal
instrumentId	number	Unique identifier of the asset to be withdrawn
organisationId	number	Unique identifier of the client
reason	string	Additional details for withdrawals that do not successfully complete
referenceId	string	Unique reference for withdrawal
status	string	Current state of the transaction, can be submitted, pending, cancelled, rejected or completed
type	string	Only `Withdrawal` returned as value
updated	string	Time stamp of the last time an action occurred on the withdrawal notification
userId	number	Unique identifier of the user who submitted the withdrawal notification
walletAddress	string	Depreciated field that returns empty string

Submit Deposit

Submit Deposit command

{
  "action": "submit-deposit",
  "data": {
    "amount": "10000",
    "instrumentId": 5,
    "referenceId": "1676615598286"
  }
}

Submit Deposit Response event

{
  "status": "OK",
  "action": "submit-deposit-response",
  "data": {
    "accountId": 114,
    "reference": "0x7b87864f860c84f811dc4cd197de7468edd93267",
    "userId": 72,
    "requestId": "1676615627210920",
    "created": "1676615627210921",
    "walletAddress": "0x7b87864f860c84f811dc4cd197de7468edd93267",
    "whitelistedWalletAddress": ""
  },
  "type": "notifications",
  "timestamp": "2023-02-17T06:33:50.253Z"
}

Submit Deposit Schema

Name	Type	Description
amount	string	Amount of the deposit where the last n digits are decimal places corresponding to the quantity decimal place value assigned to the asset (ex. GBP has 2 decimal place value so an amount of “1000” would equate to £10.00)
instrumentId	number	Unique identifier of the asset to be deposited
referenceId	string	Unique user reference for deposit

Submit Deposit Response Event Schema

Name	Type	Description
accountId	number	Unique identifier of the ledger account
referenceId	string	For cash - unique identifier that needs to be included in the reference field of the payment. For security assets- wallet address assigned as recipient address for transfer
userId	number	Unique identifier of the user who submitted the deposit notification
requestId	string	Unique system identifier of the deposit (corresponds to id field in `set-deposits` events schema)
created	string	Time of transaction
walletAddress	string	Internal use only
whitelistedWalletAddress	string	Not in use

Submit Withdrawal

Submit Withdrawal command

{
  "action": "submit-withdrawal",
  "data": {
    "amount": "10000",
    "instrumentId": 5,
    "referenceId": "1676615598286"
  }
}

Submit Withdrawal Response event

{
  "status": "OK",
  "action": "submit-withdrawal-response",
  "data": {
    "accountId": 108,
    "userId": 72,
    "referenceId": "1676616969568760",
    "requestId": "1676616969570956",
    "created": "1676616969570957"
  },
  "type": "notifications",
  "timestamp": "2023-02-17T06:56:10.613Z"
}

Submit Withdrawal Schema

Name	Type	Description
amount	string	Amount of the withdrawal where the last n digits are decimal places corresponding to the quantity decimal place value assigned to the asset (ex. GBP has 2 decimal place value so an amount of “1000” would equate to £10.00)
instrumentId	number	Unique identifier of the asset to be withdrawn
referenceId	string	Unique user reference for withdrawal

Submit Withdrawal Response Event Schema

Name	Type	Description
accountId	number	Unique identifier of the ledger account
referenceId	string	Unique reference for withdrawal
userId	number	Unique identifier of the user who submitted the withdrawal notification
requestId	string	Unique system identifier of the withdrawal (corresponds to id field in `set-withdrawals` events schema)
created	string	Time of transaction

Cancel Deposit

Cancel Deposit command

{
  "action": "cancel-deposit",
  "data": {
    "requestId": "1676615627210920"
  }
}

Cancel Deposit Response event

{
  "status": "OK",
  "action": "cancel-deposit-response",
  "data": {
    "userId": 72,
    "status": "creditCancelled",
    "reason": "creditUserCancelled",
    "requestId": "1676615627210920",
    "created": "1676616709917337"
  },
  "type": "notifications",
  "timestamp": "2023-02-17T06:51:50.994Z"
}

Cancel Deposit Schema

Name	Type	Description
requestId	string	Unique system identifier of the deposit (corresponds to id field in `set-deposits` events schema)

Cancel Deposit Response Event Schema

Name	Type	Description
userId	number	Unique identifier of the user who submitted the deposit notification
status	string	Current status of the deposit notification, only value is `creditCancelled`
reason	string	Reason for cancellation, only value is `creditUserCancelled`
requestId	string	Unique system identifier of the deposit (corresponds to id field in `set-deposits` events schema)
created	string	Time of transaction

Cancel Withdrawal

Cancel Withdrawal command

{
  "action": "cancel-withdrawal",
  "data": {
    "requestId": "1676616969570956"
  }
}

Cancel Withdrawal Response event

{
  "status": "OK",
  "action": "cancel-withdrawal-response",
  "data": {
    "userId": 72,
    "status": "debitCancelled",
    "reason": "debitUserCancelled",
    "requestId": "1676616969570956",
    "created": "1676618856703258"
  },
  "type": "notifications",
  "timestamp": "2023-02-17T07:27:37.623Z"
}

Cancel Withdrawal Schema

Name	Type	Description
requestId	string	Unique system identifier of the withdrawal (corresponds to id field in `set-withdrawals` events schema)

Cancel Withdrawal Response Event Schema

Name	Type	Description
userId	number	Unique identifier of the user who submitted the withdrawal notification
status	string	Current status of the withdrawal notification, only value is `debitCancelled`
reason	string	Reason for cancellation, only value is `debitUserCancelled`
requestId	string	Unique system identifier of the withdrawal (corresponds to id field in `set-withdrawals` events schema)
created	string	Time of transaction

Submit Transfer

Submit Transfer command

{
  "action": "submit-transfer",
  "data": {
    "amount": "1",
    "sourceAccountId": 105,
    "targetAccountId": 106,
    "referenceId": "1676619797797"
  }
}

Submit Transfer Response event

{
  "status": "OK",
  "action": "submit-transfer-response",
  "data": {
    "requestId": "1676623261301525"
  },
  "type": "notifications",
  "timestamp": "2023-02-17T07:43:42.769Z"
}

Submit Transfer Schema

Name	Type	Description
amount	number	Amount of the transfer where the last n digits are decimal places corresponding to the quantity decimal place value assigned to the asset (ex. GBP has 2 decimal place value so an amount of “1000” would equate to £10.00)
sourceAccountId	number	Unique identifier of the ledger account sending the amount
targetAccountId	number	Unique identifier of the ledger account receiving the amount
referenceId	string	Unique reference for the transfer

Submit Transfer Response Event Schema

Name	Type	Description
requestId	string	Unique system identifier of the transfer (currently a known issue that this is sent as two numbers and a boolean instead of a string)

Schemas

Response Wrapper

Name	Type
status	status
data	data
timestamp	timestamp
errors	errors

Status

Name	Type	Description
status	string	Returns OK if the request succeeded. Otherwise returns ERROR.

Data

Name	Type	Description
data	object	Wrapper for response data.

Timestamp

Name	Type	Description
timestamp	date	ISO date/time the request completed.

Errors

Name	Type	Description
errors	array	Contains all error messages from processing a request.

Order Rejection Errors

Error text	Reason	Resolution
None	None	Contact support
System Failure	Internal Archax issue	Contact support
Invalid Price	The price is not formatted correctly and likely has too many decimal places	Ensure price submitted does not exceed the priceDecimalPlace value for the trading pair
Market Closed	Market is closed	Check market hours (MTF only)
Market Suspended	Market has been suspended	Contact support for ETA on restoring market
An error was encountered. Please try again later or contact Support Team	Internal Archax issue	Contact support
Invalid Position	Sell ticket submitted exceed available position	Reduce quantity on sell ticket to less than available position and resubmit
Insufficient Balance	Buy ticket submitted exceeds available balance	Reduce value (price * quantity + tax + commission) on buy ticket to less than available balance and resubmit
Dynamic Price Collar	Price submitted exceeds the last traded price by 10% (security) or 25% (crypto).	The price submitted less the last traded price and then expressed as a percentage of last trade price (absolute value) should be under 10% for security instruments and under 25% for crypto
Ticket Limit Reached	Ticket risk limit for client has been exceeded (for either cash based on value or asset based on quantity)	Reduce the price and or quantity of the ticket or contact Archax to change your assigned ticket limit
Daily Limit Reached	Daily risk limit for client has been exceeded (for either cash based on value or asset based on quantity)	Contact Archax to change your assigned daily limit or wait until the next day (currently only applied to securities trading)
Auction not in call phase	Auction order submitted when the auction is not running	Check instrument status, order was likely submitted just as the closing auction ended (only securities)
Static Price Collar	An aggressive order has a price that is either 25% greater or less than the close price or a passive order has a price that is either 35% greater or less than the close price.	Check RNS or document library bulletins for instrument updates. This is only applied to security instruments and not crypto.
Max Value Exceeded	The value of the order exceeds the maximum value allowed.	Contact Archax. This only applies to securities trading and not crypto.
Halted Instrument	Instrument trading has been halted.	Check RNS or document library bulletins for instrument updates.
Suspended Instrument	Instrument trading has been suspended.	Check RNS or document library bulletins for instrument updates.
Invalid Tick Size	Price submitted has incremented less than the defined tick size relative to last traded price.	The price submitted divided by the tick size should have 0 remainder.
Order rejected as possible duplicate	The order parameters are identical to another order.	Check that the action reference is unique.
Order value is below minimum	The value of the order is less than the minimumOrderValue for the instrument trading pair.	Check the value for minimumOrderValue and ensure the submitted order is greater than this.
Instrument Not Found	The instrument does not exist	Confirm the instrument id otherwise contact Archax support
Invalid Quantity	The quantity is not formatted correctly and likely has too many decimal places	Ensure quantity submitted does not exceed the quantityDecimalPlace value for the trading pair
No daily limit assigned	The client is missing a daily risk limit for the fiat currency or the instrument	Contact Archax support
No ticket limit assigned	The client is missing a ticket risk limit for the fiat currency or the instrument	Contact Archax support
Inactive Instrument	Instrument is not in an active state	Check instrument id otherwise contact Archax support
Terminated Instrument	Instrument is in terminated and no longer trading on the exchange	Check instrument id otherwise contact Archax support
Instrument Status Not Found	Internal Archax issue	Contact support
Order failed, please contact support	Internal Archax issue	Contact support

API Deprecation Policy

Introduction

This API Deprecation Policy outlines the guidelines and procedures for deprecating and sunsetting APIs offered by Archax. Deprecating an API is a strategic decision made to manage technical debt, improve system efficiency, and provide users with a seamless transition to newer versions or alternatives. This policy aims to ensure that the process of API deprecation is transparent, well-communicated, and minimizes disruption for API consumers.

Definitions

API: Application Programming Interface, which provides a set of rules and protocols for building and interacting with software applications
Deprecation: The process of officially declaring that an API or a specific API version will be phased out and eventually discontinued
Sunsetting: The final phase of an API deprecation, where the API is completely shut down and removed from service
Consumers: Developers, applications, or services that use the API to access specific functionalities

Versioning

Major versions (X.0)

Backwards-incompatible changes that will require significant work by end user clients
Criteria for a major version change:
- Removal or deprecation of existing functionalities
- Changes that break existing integrations or require code modifications
- Fundamental architectural changes that impact the entire system
- Changes that introduce new, non-backward-compatible dependencies

Minor versions (0.X)

New features or functionality that is backwards-compatible
Criteria for a minor version change:
- Introduction of new features or enhancements
- Additions to existing functionalities that do not break existing integrations
- New endpoints or parameters that are optional
- Performance improvements that do not affect the existing API contract

Other changes

Some changes may not result in an increment in major or minor version and will be communicated through a change log available on the website
These changes can include:
- Bug fixes that do not alter the existing behavior of the API
- Security patches or minor security-related updates
- Non-functional changes that improve the internal implementation without affecting the API contract
- Corrections to documentation or metadata

Deprecation Stages

Announcement

Prior to deprecating an API, Archax will provide advance notice to API consumers. This notice will include the reasons for deprecation, the timeline for each stage, and suggested migration paths
A minimum notice period of 3 months will be given before initiating the deprecation process

Deprecated Phase

During this phase, the API will still be functional and accessible, but Archax will no longer actively develop new features or improvements for the deprecated API version
Archax will continue to provide bug fixes and security updates for critical issues during the deprecated phase
The documentation will clearly label the API version as deprecated and encourage users to migrate to the recommended alternatives

Sunset Phase

At the end of the deprecation timeline, the API will be completely shut down and removed from service
Archax will no longer provide support, bug fixes, or security updates for the deprecated API version
API consumers must have migrated to the suggested alternative versions or replacements before the sunset phase to avoid disruptions in their services

Communication

Archax will use multiple communication channels to inform API consumers about the deprecation process. These channels may include email notifications, blog posts, social media announcements, and updates on the Archax API documentation webpage
Clear documentation will be provided to guide users through the migration process, including code examples and best practices

Migration Support

Archax will offer technical support and resources to assist API consumers in migrating to alternative API versions or solutions
A dedicated support channel will be available for API consumers facing challenges during the migration process

Exceptional Cases

In exceptional cases where extending the deprecation timeline is necessary, Archax reserves the right to adjust the timeline based on technical constraints or specific user needs
Such adjustments will be communicated transparently to API consumers

Review and Update

This API Deprecation Policy will be periodically reviewed and updated as needed to align with the evolving needs of Archax and its API consumers
Updates to the policy will be communicated to API consumers through appropriate channels

Deprecation Schedule

API Version	Reason	Suggested Migration Path	Deprecation Date	Sunset Date
V1.0	Does not support the addition of new products nor multiple currency pairs.	V3.0	Jan 2024	Apr 2024
V2.0	Does not support the addition of new products nor multiple currency pairs.	V3.0	Jan 2024	Apr 2024

Change Log

V3.0

December 2023

Instruments split into assets and trading pairs
- Subscribe instruments request replaced with subscribe trading pairs and subscribe assets
- Subscribe cash is no longer included, use subscribe assets instead and filter for cash type
- Instrument id is no longer used and has been replaced by trading pair id for trading related endpoints or asset id for treasury/custody related endpoints
Submit order, cancel order, submit deposit, cancel deposit, submit withdrawal, cancel withdrawal and submit transfer have each had actionRef replaced with userReference
Created timestamp for subscribe orders responses are now in µs instead of ms
Submission of deposits and withdrawals now requires an accountId
Responses to fetch balances and subscribe balances include product id
Subscribe market quotes and market depths can be sent for an individual trading pair rather than all trading pairs
- The responses no longer include instruments in bulk but instead have a response for each subscribed trading pair
Market quotes and market depths can be unsubscribed
Append trading history responses will be sent as an array of 1 object (to match the set-trade-histories response format)
New field responseType for all subscriptions that indicates if the response is the initial snapshot or a subsequent update

V2.0

May 2023

Improved permissions model to enable custody only users and permissions to multiple client accounts
Added organisation id field to most websocket commands to support users with access to multiple client accounts

ACE API Spec v3.0.0

Handling Decimal Place Values

REST API

Login

Renew-jwt

Payment Provider details

Asset Details

Trading Pair Details

Open Orders

Market History

WebSocket API

Connection

Renew JWT

Market Data

Subscribe to Trading Pairs

Subscribe to Market Quotes

Subscribe to Assets

Balances

Fetch Balances

Subscribe to Balances

Orders

Submit an Order

Subscribe to Orders

Cancel an Order

Order Book

Subscribe to Market Depths

Trades

Subscribe to Trade History

Transactions

Subscribe to Transactions

Custody

Subscribe to Deposits

Subscribe to Withdrawals

Submit Deposit

Submit Withdrawal

Cancel Deposit

Cancel Withdrawal

Submit Transfer

ACE API Spec v2.0.0

REST API

Login

Renew-jwt

Payment Provider details

Instrument Details

Open Orders

WebSocket API

Connection

Renew JWT

Market Data

Subscribe to Instruments

Subscribe to Market Quotes

Subscribe to Cash

Balances

Fetch Balances

Subscribe to Balances

Orders

Submit an Order

Subscribe to Orders

Cancel an Order

Order Book

Subscribe to Market Depths

Trades

Subscribe to Trade History

Transactions

Subscribe to Transactions

Custody

Subscribe to Deposits

Subscribe to Withdrawals

Submit Deposit

Submit Withdrawal

Cancel Deposit

Cancel Withdrawal

Submit Transfer

ACE API Spec v1.0.5

REST API

Login

Renew-jwt

Payment Provider details

Instrument Details

Open Orders