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

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-account.archax.com/api/1.0/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-account.archax.com/api/1.0/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-reporting.archax.com/api/1.0/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-reporting.archax.com/api/1.0/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
open	number	Open price of the asset

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
created	string	Timestamp on when the trade was executed (ms)
instrumentId	number	Unique identifier of the asset
executions	empty array	Not used
side	string	Order side, possible values: `buy`, `sell`
userReference	string	Value provided as `actionRef` in original submission of order

WebSocket API

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

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

Connection

Login command

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

Successful login event

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

Failed login event

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

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

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

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

Market Data

Subscribe to Instruments command

{
  "action": "subscribe-instruments"
}

Set Instruments event

{
  "status": "OK",
  "action": "set-instruments",
  "data": {
    "4": {
      "currency": "EUR",
      "decimals": 2,
      "description": "Fake AG SHRS",
      "id": 4,
      "marketStatus": "open",
      "name": "FAKE SHRS",
      "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",
      "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",
      "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
quantityDecimalPlaces	number	The number of significant decimal places for the asset’s quantity
regulatedStatus	string	The regulated status of the asset. Possible values are: `eligible` and `ineligible`
symbol	string	Ticker symbol for the asset
tradingStatus	string	Current trading status for the asset. Possible values are: `Created`, `Pre-Live`, `Trading`, `Suspended` and `Terminated`
type	string	The asset type. Possible values are: `security` and `crypto`
venueId	string	Default value: `ARCHAX`
tickSize	string	Minimum price amount an instrument can move

Subscribe to Market Quotes command

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

Set Market Quotes event (initial)

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

Set Market Quotes event (update)

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

Set Market Quotes event (reset specified properties)

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

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

Each value in the data property is keyed by instrumentId.

Set Market Quotes Event Schema

Name	Type	Description
[key]		Identifier of the asset
askPrice	string	Best asking price for the asset
askQty	string	Number of units on offer at the `askPrice`
bidPrice	string	Best bid price for the asset
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`
closePrice	string	The asset’s last traded price from the previous trading session
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
instrumentId	number	Unique identifier of the asset
lastPrice	string	Last traded price for the asset
highPrice	string	Highest trade price for the asset during the current trading session
lowPrice	string	Lowest trade price for the asset during the current trading session
lastQty	string	Last traded quantity for the asset
openPrice	string	Price at which the first execution of the day for the asset occurred
sevenDayChange	string	The difference between `closePrice` and `sevenDayClosePrice`
sevenDayChangePercentage	string	The percentage difference between the `closePrice` and `sevenDayClosePrice`
sevenDayClosePrice	string	The asset’s close price 7 days prior

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

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

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

The set-market-quotes event would be returned each time there’s a change on any of the fields listed in the preceding table. The data property would only contain the fields that have changed. So, if you have an 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 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
quantityDecimalPlaces	number	The number of significant decimal places for the asset’s quantity
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
priceDecimalPlaces	number	The number of decimal places for the asset’s price

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": "eligible",
      "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": "eligible",
      "instrumentId": 5,
      "total": "1000000400"
    },
    "2786122894": {
      "accountId": 2786122894,
      "accountType": "accountCash",
      "available": "1000000400",
      "regulatoryEligibility": "eligible",
      "instrumentId": 6,
      "total": "1000000400"
    }
  },
  "timestamp": "2021-07-01T04:30:06.127Z"
}

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

Fetch Balances Event Schema

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

Subscribe to Balances command

{
  "action": "subscribe-balances"
}

Set Balances event

{
  "status": "OK",
  "action": "set-balances",
  "data": {
    "2786123094": {
      "accountId": 2786123094,
      "accountType": "accountCash",
      "available": "1000000400",
      "instrumentId": 1,
      "regulatoryEligibility": "eligible",
      "total": "1000000400"
    },
    "2786123095": {
      "accountId": 2786123095,
      "accountType": "accountSecurity",
      "available": "1000000400",
      "instrumentId": 2,
      "regulatoryEligibility": "eligible",
      "total": "1000000400"
    },
    "2786122842": {
      "accountId": 2786122842,
      "accountType": "accountCrypto",
      "available": "1000180131",
      "instrumentId": 3,
      "regulatoryEligibility": "eligible",
      "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 asset
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	number	Quantity
side	number	Market side of order, possible values: `0` = Buy, `1` = Sell

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

Order Updated Event Schema

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

Order Submitted (Error) Event Schema

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

Subscribe to Orders command

{
  "action": "subscribe-orders"
}

Set Orders event (initial)

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

Set Orders event (update)

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

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

Set Orders Event Schema

Name	Type	Description
[key]		Unique order identifier
averagePrice	string	Average execution price for the order
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
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
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

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

Order Cancelled Event Schema

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

Cancellation Rejected Event Schema

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

Cancellation Failed Event Schema

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

Order Book

Subscribe to Market Depths command

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

Set Market Depths event (initial)

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

Set Market Depths event (update)

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

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

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

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

Set Market Depths Event Schema

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

Market Depth Schema (Buy or Sell)

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

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

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

and you receive an update with following data:

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

the expected state of instrumentId 1 is:

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

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

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

and you receive an update with following data:

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

the expected state of instrumentId 1 is:

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

Trades

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

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

Subscribe to all Trade History.

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

Response JSON returned example -

Initial Set Trade History event

{
  "status": "OK",
  "action": "set-trade-histories/1",
  "data": {
    "1": [
      {
        "amount": "81",
        "created": "1619080206756725504",
        "price": "9124",
        "side": "sell"
      },
      {
        "amount": "4",
        "created": "1619080141466397184",
        "price": "10875",
        "side": "buy"
      },
      {
        "amount": "48",
        "created": "1619080099647654400",
        "price": "9059",
        "side": "buy"
      }
    ]
  },
  "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"
      }
    ]
  },
  "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, the last 2 digits are decimal places
side	string	Aggressive side of order (`buy` or `sell`). `auction` is returned as value when trade is a result of an auction

Transactions

Subscribe to Transactions command

{
  "action": "subscribe-transactions"
}

Set Transaction event

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

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

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

Set Transaction Event Schema

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

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

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

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

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

and the resulting transactions state will be:

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

Custody

Subscribe To Deposits command

{
  "action": "subscribe-deposits"
}

Set Deposits event

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

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 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	Unique identifier of the user’s wallet address

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

ACE API Spec v2.0.0

REST API

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

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

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

Sample Request

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

200 Response

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

401 Response

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

POST /login

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

Request Schema

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

Response Schema

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

Renew-jwt

Request to

https://ace-auth.archax.com/api/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-account.archax.com/api/2.0/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-account.archax.com/api/2.0/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-reporting.archax.com/api/2.0/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-reporting.archax.com/api/2.0/instrument/:instrumentId

Url path parameters

Name	Type	Description
instrumentId	number	Unique identifier of the asset

Response Schema

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

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

Market Data

Subscribe to Instruments command

{
  "action": "subscribe-instruments"
}

Set Instruments event

{
  "status": "OK",
  "action": "set-instruments",
  "data": {
    "4": {
      "currency": "EUR",
      "decimals": 2,
      "description": "Fake AG SHRS",
      "id": 4,
      "marketStatus": "open",
      "name": "FAKE SHRS",
      "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",
      "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",
      "quantityDecimalPlaces": 8,
      "regulatedStatus": "eligible",
      "symbol": "FBTC",
      "tradingStatus": "Suspended",
      "type": "crypto",
      "venueId": "ARCHAX",
      "tickSize": "0.1"
    }
  },
  "type": "instruments",
  "timestamp": "2021-07-08T07:00:20.190Z"
}

Set Instruments Event Schema

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

Subscribe to Market Quotes command

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

Set Market Quotes event (initial)

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

Set Market Quotes event (update)

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

Set Market Quotes event (reset specified properties)

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

Each value in the data property is keyed by instrumentId.

Set Market Quotes Event Schema

Name	Type	Description
[key]		Identifier of the asset
askPrice	string	Best asking price for the asset
askQty	string	Number of units on offer at the `askPrice`
bidPrice	string	Best bid price for the asset
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`
closePrice	string	The asset’s last traded price from the previous trading session
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
instrumentId	number	Unique identifier of the asset
lastPrice	string	Last traded price for the asset
highPrice	string	Highest trade price for the asset during the current trading session
lowPrice	string	Lowest trade price for the asset during the current trading session
lastQty	string	Last traded quantity for the asset
openPrice	string	Price at which the first execution of the day for the asset occurred
sevenDayChange	string	The difference between `closePrice` and `sevenDayClosePrice`
sevenDayChangePercentage	string	The percentage difference between the `closePrice` and `sevenDayClosePrice`
sevenDayClosePrice	string	The asset’s close price 7 days prior

and you receive an update with following data:

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

the expected state of instrumentId 2 is:

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

the expected state of instrumentId 2 would then be:

Subscribe to Cash command

{
  "action": "subscribe-cash"
}

Set Cash event

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

Set Cash Event Schema

Name	Type	Description
[key]		Identifier of the asset
currency	string	3-letter currency code for the asset
decimals	number	The number of significant decimal places for the asset’s price
description	string	The full name of the asset
id	number	Unique identifier of the asset
marketStatus	string	Current market status for the asset. Possible values are: `open`, `closed` and `closing auction`
name	string	The short name for the asset
quantityDecimalPlaces	number	The number of significant decimal places for the asset’s quantity
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`
priceDecimalPlaces	number	The number of decimal places for the asset’s price

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": "eligible",
      "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": "eligible",
      "instrumentId": 5,
      "total": "1000000400"
    },
    "2786122894": {
      "accountId": 2786122894,
      "accountType": "accountCash",
      "available": "1000000400",
      "regulatoryEligibility": "eligible",
      "instrumentId": 6,
      "total": "1000000400"
    }
  },
  "timestamp": "2021-07-01T04:30:06.127Z"
}

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

Fetch Balance Command Schema (optional)

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

Fetch Balances Event Schema

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

Subscribe to Balances command

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

Set Balances event

{
  "status": "OK",
  "action": "set-balances",
  "organisationId": 3,
  "data": {
    "2786123094": {
      "accountId": 2786123094,
      "accountType": "accountCash",
      "available": "1000000400",
      "instrumentId": 1,
      "regulatoryEligibility": "eligible",
      "total": "1000000400"
    },
    "2786123095": {
      "accountId": 2786123095,
      "accountType": "accountSecurity",
      "available": "1000000400",
      "instrumentId": 2,
      "regulatoryEligibility": "eligible",
      "total": "1000000400"
    },
    "2786122842": {
      "accountId": 2786122842,
      "accountType": "accountCrypto",
      "available": "1000180131",
      "instrumentId": 3,
      "regulatoryEligibility": "eligible",
      "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 asset
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,
    "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	number	Quantity
side	number	Market side of order, possible values: `0` = Buy, `1` = Sell
organisationId	number	Unique identifier for the organisation subject to the order submission

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

Order Updated Event Schema

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

Order Submitted (Error) Event Schema

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

Subscribe to Orders command

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

Set Orders event (initial)

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

Set Orders event (update)

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

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
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
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
id	string	Unique identifier to execution
quantity	string	Executed quantity without consideration of decimal places value (decimal places defined in `quantityDecimalPlaces` from Instruments Schema)
tax	string	Total tax value of the order

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

and you receive an update with following data:

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

the expected state of order 1626077181607120 is:

Cancel an Order

Cancel Order Command

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

Order Cancelled Event

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

Cancellation Rejected Event

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

Cancel Failed Event with ERROR status

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

Send an order-cancel command to cancel an order.

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

Cancel Order Command Schema

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

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

Order Cancelled Event Schema

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

Cancellation Rejected Event Schema

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

Cancellation Failed Event Schema

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

Order Book

Subscribe to Market Depths command

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

Set Market Depths event (initial)

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

Set Market Depths event (update)

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

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

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

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 `decimals` from Instruments Schema)
[value]	number	Volume (quantity without consideration of decimal places value, decimal places defined in `quantityDecimalPlaces` from Instruments Schema)

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

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

and you receive an update with following data:

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

the expected state of instrumentId 1 is:

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

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

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

and you receive an update with following data:

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

the expected state of instrumentId 1 is:

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

Trades

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

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

Subscribe to all Trade History.

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

Response JSON returned example -

Initial Set Trade History event

{
  "status": "OK",
  "action": "set-trade-histories/1",
  "data": {
    "1": [
      {
        "amount": "81",
        "created": "1619080206756725504",
        "price": "9124",
        "side": "sell"
      },
      {
        "amount": "4",
        "created": "1619080141466397184",
        "price": "10875",
        "side": "buy"
      },
      {
        "amount": "48",
        "created": "1619080099647654400",
        "price": "9059",
        "side": "buy"
      }
    ]
  },
  "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"
      }
    ]
  },
  "type": "trade-histories",
  "timestamp": "2021-08-27T15:35:59.147Z"
}

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

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

Set trade history Event Schema

Name	Type	Description
[key]		Unique identifier of the instrument
amount	string	Quantity traded
created	string	Time of trade
price	string	Executed price, the last 2 digits are decimal places
side	string	Aggressive side of order (`buy` or `sell`). `auction` is returned as value when trade is a result of an auction

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:

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

and the resulting transactions state will be:

Custody

Subscribe To Deposits command

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

Set Deposits event

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

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

Subscribe Withdrawals Command Schema

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

Set Withdrawal Event Schema

Name	Type	Description
[key]		Unique identifier of the withdrawal
accountId	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"
  },
  "organisationId": 27
}

Submit Deposit Response event

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

Submit Deposit Schema

Name	Type	Description
data	Data	Deposit details
organisationId	number	Unique identifier for the organisation subject to the deposit submission

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
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	Unique identifier of the user’s wallet address

Submit Withdrawal

Submit Withdrawal command

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

Submit Withdrawal Response event

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

Submit Withdrawal Schema

Name	Type	Description
data	Data	Withdrawal details
organisationId	number	Unique identifier for the organisation subject to the withdrawal submission

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

Cancel Deposit

Cancel Deposit command

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

Cancel Deposit Response event

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

Cancel Deposit Schema

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

Cancel Deposit Response Event Schema

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

Cancel Withdrawal

Cancel Withdrawal command

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

Cancel Withdrawal Response event

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

Cancel Withdrawal Schema

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

Cancel Withdrawal Response Event Schema

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

Submit Transfer

Submit Transfer command

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

Submit Transfer Response event

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

Submit Transfer Schema

Name	Type	Description
amount	number	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)
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)

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

ACE API Spec v1.0.5

REST API

Login

Renew-jwt

Payment Provider details

Instrument Details

Open Orders

WebSocket API

Connection

Market Data

Subscribe to Instruments

Subscribe to Market Quotes

Subscribe to Cash

Balances

Fetch Balances

Subscribe to Balances

Orders

Submit an Order

Subscribe to Orders

Cancel an Order

Order Book

Subscribe to Market Depths

Trades

Subscribe to Trade History

Transactions

Subscribe to Transactions

Custody

Subscribe to Deposits

Subscribe to Withdrawals

Submit Deposit

Submit Withdrawal

Cancel Deposit

Cancel Withdrawal

Submit Transfer

ACE API Spec v2.0.0

REST API

Login

Renew-jwt

Payment Provider details

Instrument Details

Open Orders

WebSocket API

Connection

Market Data

Subscribe to Instruments

Subscribe to Market Quotes

Subscribe to Cash

Balances

Fetch Balances

Subscribe to Balances

Orders

Submit an Order

Subscribe to Orders

Cancel an Order

Order Book

Subscribe to Market Depths

Trades

Subscribe to Trade History

Transactions

Subscribe to Transactions

Custody

Subscribe to Deposits

Subscribe to Withdrawals

Submit Deposit

Submit Withdrawal

Cancel Deposit

Cancel Withdrawal

Submit Transfer

Schemas

Response Wrapper

Status

Data

Timestamp

Errors

Order Rejection Errors