API

Protocol:

HTTP REST

All endpoints are POST (unless otherwise specified) with both request and response of type “application/json”

Financial numbers are often formatted as a string as JSON does not have a decimal type

HTTP 400 responses:

The body of the response describes the error:

• "expired": The request has expired
• "authentication failed": The authentication failed
• "old nonce": An old nonce was used
• "internal error": An internal error occurred
• "kyc service not available": There is no service available to process KYC upgrade requests
• "fiat payment service not available": There is no service available to process fiat payments
• "fiat payments of '{ASSET}' not enabled": The fiat payment service does not support the required asset
• "invalid market": The market does not exist
• "Market does not exist": The market does not exist
• "Amount not present": The amount parameter is required
• "Amount is less then {X}": The amount parameter must be equal or greater then X
• "Amount is not a multiple of {X}": The amount parameter must be a multiple of X
• "Price not present": The price parameter is required
• "Price is less then {X}": The price parameter must be equal or greater then X
• "Price is not a multiple of {X}": The price parameter must be a multiple of X
• "Invalid side '{X}'": The order side is not valid ('buy' or 'sell')
• "insufficient balance": Insufficient balance to create the order
• "insufficient liquidity": Insufficient market liquidity to create the order
• "invalid order": The parameters (market, order id) do not specify a valid order
• "amount too low (minimum is {MIN_AMOUNT})": The amount provided is below the minimum required
• "invalid recipient": The recipient (cryptocurrency address or bank account number) is not valid
• "invalid amount": The amount parameter was not a valid decimal
• "Your withdrawal limit is {AMOUNT} {ASSET} equivalent, your current withdrawal total this period ({WITHDRAWAL_PERIOD}) is {TOTAL_THIS_PERIOD} {WITHDRAWAL_ASSET}": The order would exeed your withdrawal limit

API Authorization

Certain API endpoints require signing with the API secret.

Authorization is achieved with an HMAC SHA256 signature.

1. Use the ASCII bytes representation of the request body as the message
2. Compute the HMAC SHA256 of the message using the ASCII bytes representation of the api secret signature = HmacSha256(api_secret, message)
3. Convert the signature into a base64 string signature = base64.b64encode(signature)
4. Provide the signature as a header (X-Signature) in the request

Account/API KEY creation

Public API Endpoints

Endpoint: “api/v1/AccountCreate”

Used by an application to create an account for a user.

Request fields:

• “email” (string): The email address of the account to create
• “deviceName” (string): The device name of the API KEY to attach to the account

Response fields:

• "token" (string): The token to use for checking the status of the account creation request.

Endpoint: “api/v1/AccountCreateStatus”

Used to check the status of an account creation request. Returns the API KEY details once the request has been confirmed by the user.

Request fields:

• “token” (string): The account creation request token

Response fields:

• "completed" (bool): True if the user has confirmed the request, false otherwise.
• "key" (string): If the user has confirmed the request this will have the API KEY (first time only), otherwise nil
• "secret" (string): If the user has confirmed the request this will have the API secret (first time only, otherwise nil

Endpoint: “api/v1/AccountCreateCancel”

Used to cancel an account creation request

Request fields:

• “token” (string): The account creation request token

Response:

• HttpOk on success

Endpoint: “api/v1/ApiKeyCreate”

Used to create an API KEY for the user

Request fields:

• “email” (string): The email address of the account to create an API KEY for
• “deviceName” (string): The device name of the API KEY to attach to the account

Response fields:

• "token" (string): The token to use for checking the status of the API KEY creation request.

Endpoint: “api/v1/ApiKeyCreateStatus”

Used to check the status of an API KEY creation request. Returns the API KEY details once the request has been confirmed by the user.

Request fields:

• “token” (string): The API KEY creation request token

Response fields:

• "completed" (bool): True if the user has confirmed the request, false otherwise.
• "key" (string): If the user has confirmed the request this will have the API KEY key (first time only), otherwise nil
• "secret" (string): If the user has confirmed the request this will have the API KEY secret (first time only, otherwise nil

Endpoint: “api/v1/ApiKeyCreateCancel”

Used to cancel an API KEY creation request

Request fields:

• “token” (string): The API KEY creation request token

Response:

• HttpOk on success

Private API Endpoints

Endpoint: “api/v1/ApiKeyDestroy”

Used to delete an API Key

Requires authorisation

Request fields:

• “key” (string): The API KEY
• “nonce” (int): The request nonce

Response:

• HttpOk on success

Endpoint: “api/v1/ApiKeyValidate”

Used to check if API KEY details are correct, or to check if an implementation is working

Requires authorisation

Request fields:

• “key” (string): The API KEY key
• “nonce” (int): The request nonce

Response:

• HttpOk on success

Market Info

Endpoint: GET | POST “api/v1/MarketList”

Used to get a list of all the market trading pair names

Response fields:

• "markets" (array): An array of all the market names

Endpoint: “api/v1/MarketStatus”

Get a summary of the market status

Request fields:

• “market” (string): The market to query
• “period” (int): The time period to query in seconds (default 86400 - one day)

Response fields:

• "period" (int): The time period in seconds
• “open” (string): The price of the asset when the time period opened
• “close” (string): The price of the asset when the time period closed
• “high” (string): The highest price of the asset during the time period
• “low” (string): The lowest price of the asset during the time period
• “volume” (string): The amount of traded units of the asset during the time period
• “last” (string): The last price traded

Endpoint: “api/v1/MarketDetail”

Get details of a market

Request fields:

• “market” (string): The market to query

Response fields:

• "takerFee" (string): The taker fee rate
• “makerFee” (string): The maker fee rate
• “minAmount” (string): The minimum amount to trade
• “tradeAsset” (string): The name of the trading asset
• “priceAsset” (string): The name of the pricing asset
• “tradeDecimals” (int): The amount of decimals in the trading asset
• “priceDecimals” (int): The amount of decimals in the pricing asset

Endpoint: “api/v1/MarketDepth”

Get the current market depth

Request fields:

• “market” (string): The market to query
• “merge” (string): The smallest unit to merge (0.1, 0.01, 0.001 etc)
• “limit” (int): The maximum number of records to return (default 20, maximum: 50)

Response fields:

• "asks" (array): Seller depth
  • “ask[0]” (string): Order price
  • “ask[1]” (string): Order amount
• “bids” (array): Buyer depth
  • “bid[0]” (string): Order price
  • “bid[1]” (string): Order amount

Endpoint: “api/v1/MarketHistory”

Get the historical trades for a market

Request fields:

• “market” (string): The market to query
• “limit” (int): The maximum number of records to return (default 100, maximum 1000)

Response fields:

• "trades" (array): Array of trade objects
  • “date” (int): Date as a unix timestamp
  • “price” (string): Price of trade
  • “amount” (string): Amount traded
  • “type” (string): Buy or sell

Endpoint: “api/v1/MarketChart”

Get the candlestick chart data for a market

Request fields:

• “market” (string): The market to query
• “start” (int): The start date (unix timestamp)
• “end” (int): The end date (unix timestamp)
• “interval” (int): The time period of one candlestick in seconds (must be a multiple of 3600)

Response fields:

• "candlesticks" (array): Array of candlestick objects
  • “date” (int): Date as a unix timestamp
  • “open” (string): Price at market open
  • “close” (string): Price at market close
  • “high” (string): Highest price during market period
  • “low” (string): Lowest price during market period
  • “volume” (string): Volume of trades during market period

Account

Endpoint: “api/v1/AccountBalance”

Used to show the balances of all assets for the user

Requires authorisation

Request fields:

• “key” (string): The API KEY
• “nonce” (int): The request nonce

Response fields:

• "assets" (object): Dictionary of asset balances
  • “available” (string): Amount of the asset available for trading or withdrawals
  • “frozen” (string): Amount of the asset frozen in pending trades

Endpoint: “api/v1/AccountKyc”

Used to show the KYC level of the user

Requires authorisation

Request fields:

• “key” (string): The API KEY
• “nonce” (int): The request nonce

Response fields:

• "kyc" (object):
  • “level” (string): The kyc level of the user
  • “withdrawalLimit” (string): The total amount of withdrawals (as converted to the withdrawal asset value) allowed within the withdrawal period
  • “withdrawalAsset” (string): The denomination of the withdrawal limit
  • “withdrawalPeriod” (string): The withdrawal period
  • “withdrawalTotal” (string): The current total of the users pending and completed withdrawals during the current period

Endpoint: “api/v1/AccountKycUpgrade”

Used initiate a KYC level upgrade request

Requires authorisation

Request fields:

• “key” (string): The API KEY
• “nonce” (int): The request nonce

Response fields:

• "kyc_request" (object):
  • “token” (string): The kyc upgrade token
  • “serviceUrl” (string): The kyc service url
  • “status” (string): ...

Endpoint: “api/v1/AccountKycUpgradeStatus”

Used to check the status of a KYC level upgrade request

Requires authorisation

Request fields:

• “key” (string): The API KEY
• “nonce” (int): The request nonce
• “token” (string): The kyc upgrade token

Response fields:

• The same as AccountKycUpgrade

Trading

Order object description

Here is a description of all the fields in an order object:

• “id” (int): Order ID
• “market” (string):
• “type” (string): ‘limit’ or ‘market’
• “side” (string): ‘sell’ or ‘buy’
• "amount" (string): Order amount
• “price” (string): Order price
• “status” (string): ‘not executed’, ‘partially executed’, ‘executed’
• “dateCreated” (int): Date when order was created
• “dateModified” (int): Date of most recent update to order
• “amountTraded” (string): amount of order completed (in units of the trade asset for this market)
• “executedValue” (string): Executed value (in units of the price asset for this market)
• “feePaid” (string): Fee paid (‘buy’: in units of the price asset, ‘sell’: in units of the trade asset)
• “makerFeeRate” (string): Maker fee tate
• “takerFeeRate” (string): Taker fee rate
• “active” (bool): If this is false that means the order is no longer active (cancelled, fully executed etc)

Endpoint: “api/v1/OrderLimit”

Create a limit order

Requires authorisation

Request fields_

• “key” (string): The API KEY
• “nonce” (int): The request nonce
• “market” (string): The market to trade in
• “side” (string): ‘buy’ or ‘sell’
• “amount” (string): Order amount
• “price” (string): Price of order

Response:

• An order object

Endpoint: “api/v1/OrderMarket”

Create a market order

Requires authorisation

Request fields:

• “key” (string): The API KEY
• “nonce” (int): The request nonce
• “market” (string): The market to trade in
• “side” (string): ‘buy’ or ‘sell’
• “amount” (string): Order amount

Response:

• An order object

Endpoint: “api/v1/OrdersPending”

Return your list of pending orders

Requires authorisation

Request fields:

• “key” (string): The API KEY
• “nonce” (int): The request nonce
• “market” (string): The market to trade in
• “offset” (int): The offset
• “limit” (int): The limit (max 100)

Response fields:

• “offset” (int): The offset
• “limit” (int): The limit
• “orders” (array): An array of order objects

Endpoint: “api/v1/OrdersExecuted”

Return your list of executed orders

Requires authorisation

Request fields:

• “key” (string): The API KEY
• “nonce” (int): The request nonce
• “market” (string): The market to trade in
• “offset” (int): The offset
• “limit” (int): The limit (max 100)

Response fields:

• “offset” (int): The offset
• “limit” (int): The limit
• “orders” (array): An array of order objects

Endpoint: “api/v1/OrderPendingStatus”

Return the status of a pending order

Requires authorisation

Request fields:

• “key” (string): The API KEY
• “nonce” (int): The request nonce
• “market” (string): The market of the order
• “id” (int): The order id

Response:

• An order object

Endpoint: “api/v1/OrderExecutedStatus”

Return the status of an executed order

Requires authorisation

Request fields:

• “key” (string): The API KEY
• “nonce” (int): The request nonce
• “id” (int): The order id

Response:

• An order object

Endpoint: “api/v1/OrderStatus”

Return the status of an order (pending or executed), a convenience function that wraps OrderPendingStatus and OrderExecutedStatus

Requires authorisation

Request fields:

• “key” (string): The API KEY
• “nonce” (int): The request nonce
• “market” (string): The market of the order
• “id” (int): The order id

Response:

• An order object

Endpoint: “api/v1/OrderCancel”

Cancel a pending order

Requires authorisation

Request fields:

• “key” (string): The API KEY
• “nonce” (int): The request nonce
• “market” (string): The market of the order
• “id” (int): The order id Response:
• An order object

Endpoint: “api/v1/TradesExecuted”

View completed trades

Requires authorisation

Request fields:

• “key” (string): The API KEY
• “nonce” (int): The request nonce
• “market” (string): The market of the order
• “offset” (int): The offset
• “limit” (int): The limit (max 100)

Response fields:

• “trades” (array): An array of trade objects
  • “id” (int):
  • “market” (string):
  • “role” (string): ‘taker’ or ‘maker’
  • “amount” (string):
  • “price” (string):
  • “executedValue” (string):
  • “fee” (string):
  • “feeAsset” (string):
  • “date” (int):
  • “orderId” (int):

Websocket

Todo…

Brokerage

Endpoint: GET | POST “api/v1/BrokerMarkets”

Get a list of open broker markets

Response fields:

• "sellMarkets" (array): An array of all the open sell markets
• "buyMarkets" (array): An array of all the open buy markets

Endpoint: “api/v1/BrokerQuote”

Get a broker quote for buying or selling an amount of an asset

Requires authorisation

Request fields:

• “key” (string): The API KEY
• “nonce” (int): The request nonce
• “market” (string): The market to trade in
• “side” (string): ‘buy’ or ‘sell’
• “amount” (string): The amount of the asset to trade
• “amountAsQuoteCurrency” (bool): If set the "amount" parameter refers to the quote currency of the market (eg for the market "ZAPNZD" it would now refer to the amount of NZD, default: False)

Response fields:

• "assetSend" (string): The asset being sold
• “amountSend” (string): The amount of asset being sold
• “assetReceive” (string): The asset to receive in exchange
• “amountReceive” (string): The amount of the receiving asset
• “timeLimit” (int): The amount of time (in minutes) that the option will be held open for. The option will expire after this time.

Endpoint: “api/v1/BrokerCreate”

Create a brokered order for buying or selling.

Requires authorisation

Request fields:

• “key” (string): The API KEY
• “nonce” (int): The request nonce
• “market” (string): The market to trade in
• “side” (string): ‘buy’ or ‘sell’
• “amount” (string): The amount of the asset to trade
• “amountAsQuoteCurrency” (bool): If set the "amount" parameter refers to the quote currency of the market (eg for the market "ZAPNZD" it would now refer to the amount of NZD, default: False)
• “recipient” (string): A cryptocurrency address or bank account number

Response fields:

• "assetSend" (string): The asset being sent to the broker
• “amountSend” (string): The amount of asset being sent
• “assetReceive” (string): The asset the customer will receive in exchange
• “amountReceive” (string): The amount of the receiving asset
• “expiry” (int): Unix timestamp of the order expiry time
• “token” (string): Token to identify order
• “invoiceId” (string): Id to associate payment
• “paymentAddress” (string): The cryptocurrency payment address, used when sending blockchain assets. If the ‘invoiceId’ field is not nil, then the invoiceId must be included as a json formatted field as an attachment to the transaction
  • Eg. ‘{“invoiceId”: “234873”}’
• “paymentUrl” (string): If the user needs to send fiat to complete the order a url where they can do so will be displayed here
• “txIdPayment” (string): The transaction id of the incoming payment to the broker
• “recipient” (string): A cryptocurrency address or bank account number
• “txIdRecipient” (string): The transaction id of the payment to the customer
• “status” (string): ‘created’, ‘ready’, ‘incoming’, ‘confirmed’, ‘payoutwait’, ‘sent’, ‘expired’
  • ‘created’ - the order has been created, awaiting acceptance from client
  • ‘ready’ - the order has been accepted, the broker is ready to receive payment
  • ‘incoming’ - the broker has seen an incoming payment
  • ‘confirmed’ - the broker has confirmed the payment, is ready to send the funds to the client
  • ‘payoutwait’ - the broker has created the payout, and it is awaiting action
  • ‘sent’ - the broker has sent the funds to the client
  • ‘expired’ - the order has expired
  • ‘error’ - the order is in a error state (underpaid?), requires manual intervention

Endpoint: “api/v1/BrokerAccept”

Accept an order. Once the order is in the ready state you can proceed with payment.

Requires authorisation

Request fields:

• “key” (string): The API KEY
• “nonce” (int): The request nonce
• “token” (string): The the order token

Response fields:

• The same as BrokerCreate

Endpoint: “api/v1/BrokerStatus”

Check the status of an order

Requires authorisation

Request fields:

• “key” (string): The API KEY
• “nonce” (int): The request nonce
• “token” (string): The the order token

Response fields:

• The same as BrokerCreate

Endpoint: “api/v1/BrokerOrders”

Get the users list of orders

Requires authorisation

Request fields:

• “key” (string): The API KEY
• “nonce” (int): The request nonce
• “offset” (int): The offset (how many items to skip) of the query
• “limit” (int): The limit (max items to return) of the query
• “status” (string): Only return items with this status (optional)

Response fields:

• “offset” (int): The offset of the query
• “limit” (int): The limit of the query
• "orders" (array): The broker order objects (same as response from BrokerCreate)