Introduction

Welcome to Globe developer application programming interface (API). The API allows our customers to interface with their accounts using custom written software.

API Client Libraries

We support Python and Typescript client libraries at present, you can find these libraries here.

Request limits

Do not make more than 10 requests per second or we may block your IP. For real time data please refer to the WebSocket API, or FIX API.

Request types

Our HTTP REST endpoints are all application/json content type and follow typical HTTP response status codes for success and failure.

A successful request will result in an HTTP 200 response and may contain an optional body. If the response has a body it will be documented under each resource below.

Errors

HTTP REST and WebSocket services may produce a JSON error response in the following form:

{ "error": "invalid-instrument", "detail": "LTCXBT" }

The following error types may be encountered:

Types

Timestamps

Unless explicitly specified, all timestamps from API are returned in Unix Millisecond Timestamp. Make sure you can parse the Unix Millisecond Timestamp format. Most modern languages and libraries will handle this without issues.

Numbers

Decimal numbers are returned as strings to preserve full precision across platforms. When making a request, it is recommended that you also convert your numbers to strings to avoid truncation and precision errors.

Integer numbers are unquoted.

Instruments

The instruments, are specified as a string parameter and can take one of the following supported instruments:

Resolutions

The price history endpoints take a resolution parameter, which can be one of the following values:

HTTP API

The HTTP API is presently only used for market data and is an unauthenticated set of endpoints for retrieving market data. These endpoints provide snapshots of market data.

Errors

Unless otherwise stated, any errors will result in HTTP 4xx or 5xx status codes.

Common error codes:

Most errors will also carry a JSON body, with further information about the error.

Get Historic Market Rates

curl "https://dev.globedx.com/api/v1/history/XBTUSD/candles/1m"

The above command returns JSON structured like this:

[
  {
    "time": 1572266460000,
    "open": 9365500,
    "high": 9366000,
    "low": 9364500,
    "close": 9364500,
    "volume": 3424204
  },
  {
    "time": 1572266400000,
    "open": 9370000,
    "high": 9370500,
    "low": 9365500,
    "close": 9365500,
    "volume": 6137236
  }
]

Historic rates for a product. Rates are returned in grouped buckets based on requested resolution.

HTTP Request

GET /api/v1/history/<instrument>/candles/<resolution>

Parameters

Details

The above parameters are optional.

If only the from field is specified, the maximum number of historical candles will be returned from that timestamp.

If only the to field is specified, the maximum number of historical candles will be returned up to that timestamp.

If both from and to fields are specified, the maximum number of historical candles will be returned within the specified range, starting at the from timestamp. The maximum number of candles that can be retrieved in one request is 1000.

Response Items

Each candle is an object with the following fields:

• time candle start time
• open opening price (first trade) in the candle interval
• high highest price during the candle interval
• low lowest price during the candle interval
• close closing price (last trade) in the candle interval
• volume volume of trading activity during the candle interval

Get Historic Index Price Rates

curl "https://dev.globedx.com/api/v1/history/index-price/XBTUSD/candles/1m"

The above command returns JSON structured like this:

[
  {
    "time": 1572266460000,
    "open": 9365500,
    "high": 9366000,
    "low": 9364500,
    "close": 9364500,
    "volume": 0
  },
  {
    "time": 1572266400000,
    "open": 9370000,
    "high": 9370500,
    "low": 9365500,
    "close": 9365500,
    "volume": 0
  }
]

Historic index price rates for a product. Rates are returned in grouped buckets based on requested resolution.

HTTP Request

GET /api/v1/history/index-price/<instrument>/candles/<resolution>

Parameters

Details

The above parameters are optional.

If only the from field is specified, the maximum number of historical candles will be returned from that timestamp.

If only the to field is specified, the maximum number of historical candles will be returned up to that timestamp.

If both from and to fields are specified, the maximum number of historical candles will be returned within the specified range, starting at the from timestamp.

Response Items

Each candle is an object with the following fields:

• time candle start time

• open opening price (first trade) in the candle interval

• high highest price during the candle interval

• low lowest price during the candle interval

• close closing price (last trade) in the candle interval

• volume volume of trading activity during the candle interval, for index

  prices this is 0 by default

WebSocket API

The WebSocket API provides near real-time market data updates for orders, trades and user account functions.

wss://globedx.com/api/v1/ws Near real-time market data updates provide the fastest insight into order flow and trades. This however means that you are responsible for reading the message stream and using the message relevant for your needs which can include building real-time order books or tracking real-time trades.

Overview

The WebSocket API uses a bidirectional protocol, which encodes all messages as JSON objects.

Please note that new message types can be added at any point in time. Clients are expected to ignore messages they do not support.

The WebSocket API support several commands, for placing and cancelling orders, as well as for subscribing to data channels. The following commands are supported:

Login

See authentication documentation for instructions on constructing an authenticated websocket connection. Private websocket endpoints cannot be used unless a connection is authenticated.

Subscribe

A typical subscription request message:

{
  "command": "subscribe",
  "channel": "index-price",
  "instrument": "XBTUSD"
}

Subscribe to a channel. All subscription requests require a channel parameter, but some subscriptions have additional required parameters. See the documentation on individual channels for more information.

You may simultaneously subscribe to any number of channels, including the same channel with different parameters. The details of the original subscription are included with each message, so that you can correlate them.

Unsubscribe

A typical unsubscribe request message:

{
  "command": "unsubscribe",
  "channel": "index-price",
  "instrument": "XBTUSD"
}

Unsubscribe from an existing channel subscription. A subscription is identified by the channel and by all other parameters; a subscription to index-price for instrument XBTUSD is a different subscription than index-price for ETHUSD , and each must be unsubscribed separately.

Authentication

To authenticate a connection, construct headers as follows:

{
  "X-Access-Passphrase": "XXXXXXXXXXXXXX",
  "X-Access-Key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "X-Access-Nonce": 1587654321,
  "X-Access-Signature": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Connections to the WebSocket are not initially authenticated, and may only access public data. To authenticate a connection, in order to place trades and access private account information, you must first obtain an API key from the your user account page.

During the process of creating a new API key, you will provide a passphrase and will be given a secret. You will need to keep these details safe as they are not otherwise retrievable later, but are needed for authenticating a connection.

In JavaScript, the headers may be generated as follows:

const crypto = require('crypto');

const secret = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const api_key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const passphrase = 'XXXXXXXXXXXXXX';
const nonce = new Date().getTime();

const hmac = crypto.createHmac('sha256', Buffer(secret, 'base64'));
const signature = hmac.update( `${nonce}GET/api/v1/ws}` ).digest('base64');

const login_headers = {
    'X-Access-Passphrase': passphrase,
    'X-Access-Key': api_key,
    'X-Access-Nonce': nonce,
    'X-Access-Signature': signature
};

The api_key is the key that you wish to use and passphrase is the passphrase you chose when creating it. nonce is an integer, which must be strictly greater than the previous value you used. For simplicity, we recommend using an integer derived from the current date and time.

The signature value is constructed using the following steps:

1. Construct the signing text, by concatenating the decimal string representation of the nonce with the string "GET/api/v1/ws". For example, using the message to the right, the message is "1587654321GET/api/v1/ws".
2. Create an HMAC signature from the signing text, using a SHA-256 hashing function and the secret.
3. Base64-encode the HMAC signature.

Include these headers when connecting to the websocket endpoint. Invalid authentication headers will result in a HTTP 400 (Bad Request) error.

Errors

Example error response for invalid parameters in request:

{
  "error": "invalid-request"
}

If there is an error in processing a websocket request, the websocket responds directly with a body containing one of the following errors types:

Rate limit

Each websocket connection is rate limited to only allow 50 requests per second (using a token bucket algorithm with a burst size window of 1 second). If the requests per second goes over this, your requests will not be processed and you will see an above error code of over-rate-limit per request as described above. We recommend to ensure your requests per second are under this rate limit, to ensure your requests get processed.

WebSocket Public Channels

Public channels do not require authentication.

Authentication

Messages related to authentication status. Authentication is subscribed automatically, so you will always receive authentication error messages.

Index Price

Subscription message:

{
  "command": "subscribe",
  "channel": "index-price",
  "instrument": "XBTUSD"
}

Example response:

{
  "subscription": {
    "channel": "index-price",
    "instrument": "XBTUSD"
  },
  "data": {
    "price": 12000.0
  }
}

Get the current index price for a particular instrument.

Arguments

Response

Market Depth

Subscription message:

{
  "command": "subscribe",
  "channel": "depth",
  "instrument": "XBTUSD"
}

Example response:

{
  "subscription": {
    "channel": "depth",
    "instrument": "XBTUSD"
  },
  "data": {
    "bids": [
      {
        "price": 100.0,
        "volume": 89
      }
    ],
    "asks": [
      {
        "price": 105.0,
        "volume": 12
      }
    ]
  }
}

The top 25 bid and ask levels of the order book for the given instrument. Updates are sent at a fixed frequency of twice a second and not necessarily for every change.

Response

Product List

Subscription message:

{
  "command": "subscribe",
  "channel": "product-list"
}

Example response:

{
  "subscription": {
    "channel": "product-list"
  },
  "data": [
    {
      "name": "Bitcoin",
      "symbol": "XBTUSD"
    },
    {
      "name": "Ethereum",
      "symbol": "ETHUSD"
    }
  ]
}

A list of all available products, including the instrument symbol and display name.

Response

Product Detail

Subscription message:

{
  "command": "subscribe",
  "channel": "product-detail",
  "instrument": "XBTUSD"
}

Example response:

{
  "subscription": {
    "channel": "product-detail",
    "instrument": "XBTUSD"
  },
  "data": {
    "funding_period": 28800,
    "next_funding_time": 1572266400000,
    "max_leverage": 100,
    "maker_fee": 0.0025,
    "taker_fee": 0.0075,
    "tick_size": 1.0
  }
}

Full information about a product, including funding information and fees.

Response

Recent Trades

Subscription message:

{
  "command": "subscribe",
  "channel": "trades",
  "instrument": "XBTUSD"
}

Example response:

{
  "subscription": {
    "channel": "trades",
    "instrument": "XBTUSD"
  },
  "data": [
    {
      "price": 9355,
      "quantity": 22806,
      "side": "sell"
    },
    {
      "price": 9355,
      "quantity": 4677,
      "side": "sell"
    },
    {
      "price": 9355,
      "quantity": 1870,
      "side": "sell"
    }
  ]
}

The 100 most recent trades, including the price, side and quantity. Updates are sent at a fixed frequency of twice a second and not necessarily for every trade.

Response

Market Overview

Subscription message:

{
  "command": "subscribe",
  "channel": "market-overview",
  "instrument": "XBTUSD"
}

Example response:

{
  "subscription": {
    "channel": "market-overview",
    "instrument": "XBTUSD"
  },
  "data": {
    "price_change_percent": 65.25,
    "volume": 150,
    "funding_rate": -0.01
  }
}

Summary statistics for the daily market activity for the requested requested instrument, including percentage price change, total volume traded over the preceding 24 hours and the current funding rate percentage. Each response message will contain at least one field.

Response

Open Interest

Subscription message:

{
  "command": "subscribe",
  "channel": "open-interest",
  "instrument": "XBTUSD"
}

Example response:

{
  "subscription": {
    "channel": "open-interest",
    "instrument": "XBTUSD"
  },
  "data": {
    "num_contracts": 1002
  }
}

Current number of contracts open in an instrument market

Response

Insurance Fund

Subscription message:

{
  "command": "subscribe",
  "channel": "insurance-fund"
}

Example response:

{
  "subscription": {
    "channel": "open-interest"
  },
  "data": {
    "balance": 0.5
  }
}

Current insurance fund balance in bitcoin

Response

WebSocket Private Channels

The following channels require authentication, please make sure you have authenticated correctly before attempting to communicate on the following channels.

It would be advised to subscribe to the My Market Events channel first, to receive the responses when placing orders and cancelling orders.

My Market Events

Subscription message:

{
  "command": "subscribe",
  "channel": "my-market-events",
  "instrument": "XBTUSD"
}

Subscribe to the my-market-events channel to listen to all of your associated market events. These form acknowledgments, and market event information in response to the private account requests, such as placing an order, cancelling an order. You can expect to see these market event response types:

Market Event responses

Order response

{
  "subscription": {
    "channel": "my-market-events",
    "instrument": "XBTUSD"
  },
  "data": {
    "event": "order-received",
    "request_id": 99,
    "side": "sell",
    "price": 87,
    "quantity": 255,
    "order_type": "market"
  }
}

Order Received response

Order Added response

{
  "subscription": {
    "channel": "my-market-events",
    "instrument": "XBTUSD"
  },
  "data": {
    "event": "order-added",
    "request_id": 99,
    "side": "buy",
    "price": 87,
    "quantity": 255,
    "order_type": "post-only"
  }
}

Order Added response

Order Cancelled response

{
  "subscription": {
    "channel": "my-market-events",
    "instrument": "XBTUSD"
  },
  "data": {
    "event": "order-cancelled",
    "request_id": 105
  }
}

Order Cancelled response

Order Rejected response

{
  "subscription": {
    "channel": "my-market-events",
    "instrument": "XBTUSD"
  },
  "data": {
    "event": "request-rejected",
    "reason": "NotEnoughMargin"
  }
}

Order Rejected response

Traded Event response

{
  "subscription": {
    "channel": "my-market-events",
    "instrument": "XBTUSD"
  },
  "data": {
    "event": "traded",
    "price": 888,
    "quantity": 1001,
    "side": "buy",
    "order_request_id": 7
  }
}

Traded Event response

Place Order

Input message:

{
  "command": "place-order",
  "instrument": "XBTUSD",
  "price": 100,
  "quantity": 250,
  "order_type": "limit",
  "side": "sell"
}

{
  "command": "place-order",
  "instrument": "XBTUSD",
  "quantity": 425,
  "order_type": "market",
  "side": "buy"
}

Place an order for a particular instrument and get a response on the my market events channel to indicate the order status.

Arguments

Cancel Order

Input message:

{
  "command": "cancel-order",
  "instrument": "XBTUSD",
  "order_id": "77"
}

Place a request to cancel an order with given order_id.

Arguments

Stop Order

Input message:

{
  "command": "stop-order",
  "trigger": 99,
  "order": {
    "instrument": "XBTUSD",
    "price": 100,
    "quantity": 250,
    "order_type": "market",
    "side": "sell"
  }
}

Stop Order, execute a place order when the instrument price reaches the set trigger value.

Arguments

My Open Orders

Subscription message:

{
  "command": "subscribe",
  "channel": "my-orders",
  "instrument": "XBTUSD"
}

Example response:

{
  "subscription": {
    "channel": "my-orders",
    "instrument": "XBTUSD"
  },
  "data": {
    "3": {
      "type": "order",
      "price": 123,
      "quantity": 500,
      "filled_quantity": 0,
      "order_type": "limit",
      "side": "buy",
      "timestamp": 1593000000
    },
    "4": {
      "type": "order",
      "price": 456,
      "quantity": 600,
      "filled_quantity": 0,
      "order_type": "limit",
      "side": "sell",
      "timestamp": 1593000010
    }
  }
}

Request your open orders for a given instrument.

My Account Overview

Subscription message:

{
  "command": "subscribe",
  "channel": "my-account-overview"
}

Subscribe to account overview messages, responses are periodically every second.

My Account Overview response

{
  "subscription": {
    "channel": "my-account-overview"
  },
  "data": {
    "available_balance": 85,
    "account_balance": 100,
    "unrealized_pnl": 5,
    "maintenance_margin": 10,
    "initial_margin": 20,
    "margin_balance": 105
  }
}

If your margin balance falls below maintenance margin requirements, you can only place orders that reduce your position.

My Account Overview response

My Positions

Subscription message:

{
  "command": "subscribe",
  "channel": "my-positions"
}

Subscribe to positions messages, responses are periodically upon every change.

My Positions response

{
  "subscription": {
    "channel": "my-positions"
  },
  "data": {
    "XBTUSD": {
      "quantity": 10,
      "avg_price": 8000.0
    }
  }
}

My Positions response

FIX API

FIX (Financial Information eXchange) is a standard protocol which can be used to enter orders, submit cancel requests, and receive fills. Users of the FIX API will typically have existing software using FIX for order management. Users who are not familiar with FIX should first consider using the websocket API. Currently FIX is only offered in colocation with the exchange.

Access

For information about FIX colocation access, please contact support@globedx.com.

Message Format

All FIX messages must consist of a header, body followed by a trailer. The fields required in the header and trailer are fixed, whilst the fields required for the message’s body depend on its MsgType which is specified in the header.

Sample FIX message to Globe’s FIX gateway:

8=FIX.4.4|9=131|35=D|34=2|49=CLIENT1|52=20190621-14:41:31.597000|56=globeDX|11=654321|38=10|40=2|44=10000|54=1|55=XBTUSD|59=1|60=20190621-14:41:31|10=204|

Required fields

Each message field is marked by one of the following characteristics:

Header

The header identifies the message type, length, destination, sequence number, origination point and time.

Trailer

Each message, administrative or application, is terminated by a standard trailer. The trailer is used to segregate messages and contains the three-digit character representation of the checksum value.

Always unencrypted. Always last field in message.

Logon (A)

In order to establish a FIX session, each FIX Client must initiate a TCP/IP socket connection to the Globe FIX Gateway and subsequently submit a Logon (MsgType = ‘A’) FIX message equipped with Username (553) and Password (554).

Logout (5)

The Logout (5) message initiates or confirms the termination of a FIX session. Disconnection without the exchange of Logout (5) messages should be interpreted as an abnormal condition.

Heartbeat (0)

Sent by both sides if no messages have been sent for HeartBtInt seconds as agreed during logon. May also be sent in response to a Test Request.

Test Request (1)

May be sent at any time by either side.

New Order Single (D)

Sent by the client to enter an order.

Execution Report (8)

FIX message “Execution Report (8)” is used to:

Confirm the receipt of an order; confirm changes to an existing order (i.e. accept cancel request); relay order status information; relay fill information on working orders; reject orders.

1. ExecId can in certain cases be zero where the FIX standard does not normally allow it: for rejections to to Duplicate ClOrdID or Cancellations where OrigClOrdID is unknown.

Order Cancel Request (F)

Sent by the client to completely cancel an order. To partially cancel an order, please use Order Cancel/Replace request (G).

Order Cancel/Replace Request (G)

Sent by the client to change the parameters of an existing order. To completely cancel an order, please use Order Cancel Request (F). Order cancel/replace will change any valid attribute of an open order (i.e. reduce/increase quantity, change limit price, etc.)

Reject (3)

Sent by either side upon receipt of a message which cannot be processed due to message formatting issues, e.g. due to missing fields or an invalid message type.

Order Cancel Reject (9)

Sent by the exchange to indicate that it cannot honour an Order Cancel Request (F) or Order Cancel/Replace Request (G).

In some cases Order Cancel Request can be rejected using a Business Message Reject(j) rather than an Order Cancel Reject. You’ll need to check for both messages.

Business Message Reject (j)

Sent by the server upon receipt of a message that cannot be processed due to business logic reasons, e.g. unknown instrument, trading suspended or unknown order ID. A business message reject message can be returned if an order cancel is rejected, with the reason specified.