NAV Navigation
JSON

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

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

Login

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"
			},
		"close": 3100002,
		"open": 2988812
        }
    },
    "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)
close number Most recent close price of trading pair (only provided with bearer token of user with market data permissions)
open number Most recent open price of trading pair (only provided with bearer token of user with market data 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

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.

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

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

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": "udpate",
  "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)

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.

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

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

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

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

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": "1623217157444399",
      "commission": "10",
      "currency": "GBP",
      "decimals": 2,
      "executions": {
        "2310130020000000003": {
		  "commission": "10",
          "created": "1623217158966910",
          "grossExecutionAmount": "17000",
		  "id": "2310130020000000003",
		  "orderId": "1623217157444399",
          "price": "1000",
          "quantity": "17",
		  "referenceId": "1623217158966156",
		  "tax": "0"
        }
      },
      "filledPercent": "100.00",
      "filledQty": "17",
      "filledStatus": "filled",
      "id": "1623217157444399",
      "limitPrice": "1000",
	  "lastUpdated": "162321715896612",
      "orderStatus": "completed",
	  "organisationId": 1,
      "quantity": "17",
      "side": "buy",
	  "tax": "0",
	  "tradingPairId": 24,
      "type": "limit",
      "userId": 2,
	  "userReference": "user_reference_1243"
    },
    "1623217157504910": {
      "averagePrice": "1000",
      "created": "1623217157504910",
      "commission": "20",
      "currency": "GBX",
      "decimals": 2,
      "executions": {
        "2310130020000000004": {
          "commission": "20",
          "created": "1623217159226910",
          "grossExecutionAmount": "14000",
          "id": "2310130020000000004",
		  "orderId": "1623217157504910",
          "price": "1000",
          "quantity": "14",
		  "referenceId": "623217159226194"
          "tax": "10"
        }
      },
      "filledPercent": "100.00",
      "filledQty": "14",
      "filledStatus": "filled",
      "id": "1623217157504910",
      "limitPrice": "1000",
 	  "lastUpdated": "162321715896612",
      "orderStatus": "completed",
	  "organisationId": 1,
      "quantity": "14",
      "side": "sell",
	  "tax": "10",
	  "tradingPairId": 7,
      "type": "limit",
      "userId": 2,
	  "userReference": "user_reference 121"
    }
  },
  "responseType": "snapshot",
  "type": "orders",
  "timestamp": "2021-07-06T08:04:40.837Z"
}

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 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 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

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

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 Trade History

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

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

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

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.

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 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 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 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 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 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

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.

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.

Login

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"
}

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 Instruments

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

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)

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.

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 instrument with the following state:

"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:

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

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

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

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

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

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"
}

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 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.

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
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

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

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 Trade History

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

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

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"
}

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 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

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"
}

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.

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 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"
}

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
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"
}

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
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"
}

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 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"
}

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 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

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.

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

Login

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

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 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

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

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 (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)

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.

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 instrument with the following state:

"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:

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

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

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"
}

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

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

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

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:

{ "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"
  }
}

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.

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
actionRef string Optional field for client to include a unique identifier
orderId string Unique identifier for the order

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

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 Trade History

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

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

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"
}

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.

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

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"
}

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.

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"
}

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
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"
}

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
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"
}

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 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"
}

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 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"
}

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

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

Versioning

Major versions (X.0)

Minor versions (0.X)

Other changes

Deprecation Stages

Announcement

Deprecated Phase

Sunset Phase

Communication

Migration Support

Exceptional Cases

Review and Update

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

V2.0

May 2023