Introduction

Welcome to Globe developer application programming interface (API). Our API allows you to interact with our exchange using the programming tools of your choice.

API Client Libraries

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

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.

Authentication

Certain private REST endpoints and websocket endpoints require authentication to use. The steps to authenticate are the same for both.

To authenticate a connection, construct headers as follows:

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

Unauthenticated WebSocket connections may only access the public API. To access private data from your account, including balances, orders and trades, you must use an API key to authenticate the HTTP request that establishes the WebSocket connection.

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 for websocket 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 verb = "GET";
const endpoint = "/api/v1/ws";

const hmac = crypto.createHmac('sha256', Buffer(secret, 'base64'));
const signature = hmac.update( `${nonce}${verb}${endpoint}` ).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 setting the nonce to an integer derived from the current date and time. If you accidentally send a nonce that is too high, you will need to delete the key and create a new one.

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 verb of the http request, and the url, for example for a websocket request the verb would be GET and the endpoint would be /api/v1/ws". using the message to the right, this gives us "1587654321GET/api/v1/ws".
2. Create an HMAC signature from the signing text, using a SHA-256 hashing function and the secret you were given when you created your API key.
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

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:

If an order or trade is not able to be processed it is rejected with one of the following reasons:

Rate limits

In order to protect the exchange from abuse we enforce limits on how frequently you may send messages to our API. The limits are different according to how the messages are sent.

If you exceed these limits, requests may be rejected. If you persistently exceed these limits we may block your IP address or deactivate your trading account.

Major Upcoming Changes: Unified Margin

Globe will soon be launching a Unified Margin model for derivatives trading and will offer linear perpetual contracts instead of the inverse and quanto contracts currently available. This will result in breaking changes to the API:

• Where quantity in the API currently refers to the number of contracts, it will instead refer to the size of the position. For example, to trade 100 contracts of a derivative product, you must specify the value of this position (100 contracts * contract size) instead of the number of contracts directly. The contract size for each product can be obtained via the product-details channel. Similarly, quantity reported by the API for open orders, recent trades and orderbook will be the size of the position instead of the number of contracts.
• Where volume in the API currently refers to the number of contracts traded, it will instead refer to the value of the traded contracts. For example, 100,000 contracts traded of XBTUSD (inverse, $1 contract size) will be reported as a volume of $100,000.00, while 100,000 contracts traded of a linear Bitcoin-USD perpetual with 0.0001 BTC contract size will be reported as a volume of 10.0 BTC.
• Derivatives trading currency change will to US Dollars. Once Unified Margin trading is enabled, all balances reported by the my-account-overview WS channel and account-overview HTTP endpoint will be in units of US Dollars. The same applies for the insurance fund.

The documentation below describes the API as it will function post-Unified Margin launch. The following endpoints will be affected:

• HTTP API:

  • Get Ticker
  • Get Ticker Contracts
  • Get Ticker Orderbook
  • Get Trades
  • Get Positions
  • Get Account Overview

• Websocket API:

  • Market Depth
  • Product Detail
  • Recent Trades
  • Market Overview
  • Price History
  • Insurance Fund
  • My Market Events
  • Place Order
  • My Orders
  • My Positions

Please carefully review the changes to these endpoints and any other changes below.

Differences between Spot and Derivative markets

We have a unified API for both Spot and Derivatives trading, but there are a few differences.

You can hold a long or short position in our derivatives contracts, which you can subscribe to using the my-positions channel. For spot trading, you need your balances, which can be retrieved using the my-balances API. The response for the product-details channel See the HTTP API and Websocket API sections for more information.

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.

Instruments

Instruments are the products that the exchange offers. for instrument parameters in the API you must specify the symbol. Examples are below:

Derivative Instruments

Spot Instruments

Note when instruments are embedded into URLs they should be put through encodeURIComponent() so e.g. slashes become %2F.

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://globedx.com/api/v1/history/XBTUSD/candles/1m"

Response:

[
  {
    "time": 1625055060000,
    "open": 34918.0,
    "high": 34988.5,
    "low": 34918.0,
    "close": 34988.5,
    "volume": 342420
  },
  {
    "time": 1625055000000,
    "open": 34911.0,
    "high": 34918.0,
    "low": 34903.0,
    "close": 34918.0,
    "volume": 613723
  }
]

Historic rates for a product. Rates are returned in for the timespan specified by the requested resolution, starting at the “time”.

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://globedx.com/api/v1/history/index-price/XBTUSD/candles/1m"

The above command returns JSON structured like this:

[
  {
    "time": 1625055060000,
    "open": 34918.0,
    "high": 34988.5,
    "low": 34918.0,
    "close": 34988.5,
    "volume": 342420
  },
  {
    "time": 1625055000000,
    "open": 34911.0,
    "high": 34918.0,
    "low": 34903.0,
    "close": 34918.0,
    "volume": 613723
  }
]

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

Get Open Orders

curl "https://globedx.com/api/v1/orders/open-orders" <authentication headers>

Response:

[
  {
    "type": "order",
    "filled_quantity": 0,
    "order_id": "3fe0a762-0b53-4eda-ba93-c391427871ff",
    "order_type": "limit",
    "price": 59000.0,
    "quantity": 10000.0,
    "side": "buy",
    "timestamp": 1617212555193
  }
]

Your open orders for an product.

HTTP Request

GET /api/v1/orders/open-orders

Parameters

Details

Note that to use this endpoint you need to pass the authentication headers, see authentication.

This endpoint is paginated and you received pages of orders. The pages are not numbered, instead You specify a point in time (using the upto_timestamp parameter), and a page_size. The response will return the most recent orders that are before or on that specified timestamp, up to the limit set by the page_size.

Response Items

Each open order is an object with the following fields:

• type an order
• filled_quantity size that has been filled of this open order
• order_id unique order id for this order
• price price of the limit order
• quantity size of the entire order originally submitted
• side side of the order, either buy or sell
• timestamp Unix Millisecond Timestamp when limit order was submitted

Get Ticker

curl "https://globedx.com/api/v1/ticker"

Response:

{
  "product_type": "Perpetual",
  "name": "Bitcoin/USD Perpetual",
  "instrument": "XBTUSD",
  "best_bid": {
    "price": 39076.0,
    "volume": 707.0
  },
  "best_ask": {
    "price": 39078.0,
    "volume": 30888.0
  },
  "volume": 5517441.0,
  "quote_volume": 5517441.0,
  "base_volume": 5517441.0,
  "price_change_percent": 0.5,
  "funding_rate": 0.023,
  "mark_price": 35000.78,
  "index_price": 35010.12,
  "contract_price_currency": "USD",
  "contract_price": 1.0,
  "contract_type": "Inverse"
}

Ticker data for a specified instrument.

HTTP Request

GET /api/v1/ticker

Parameters

Response Items

The response is different for spot and perpetual products. For spot products response items, see Get Ticker Pairs. For perpetual products response items, see Get Ticker Contracts.

Get Ticker Contracts

curl "https://globedx.com/api/v1/ticker/contracts"

Response:

[
  {
    "product_type": "Perpetual",
    "name": "Bitcoin/USD Perpetual",
    "instrument": "XBTUSD",
    "best_bid": {
      "price": 39076.0,
      "volume": 707.0
    },
    "best_ask": {
      "price": 39078.0,
      "volume": 30888.0
    },
    "volume": 5517441.0,
    "quote_volume": 5517441.0,
    "base_volume": 5517441.0,
    "price_change_percent": 0.5,
    "funding_rate": 0.023,
    "mark_price": 35000.78,
    "index_price": 35010.12,
    "contract_price_currency": "USD",
    "contract_price": 1.0,
    "contract_type": "Inverse"
  },
  {
    "product_type": "Perpetual",
    "name": "Ethereum/USD Perpetual",
    "instrument": "ETHUSD",
    "best_bid": {
      "price": 2000.0,
      "volume": 707.0
    },
    "best_ask": {
      "price": 2010.0,
      "volume": 30888.0
    },
    "volume": 5517441.0,
    "quote_volume": 5517441.0,
    "base_volume": 5517441.0,
    "price_change_percent": 0.5,
    "funding_rate": 0.023,
    "mark_price": 2005.78,
    "index_price": 2000.12,
    "contract_price_currency": "USD",
    "contract_price": 1.0,
    "contract_type": "Inverse"
  }
]

Ticker contracts for all instruments in an array.

HTTP Request

GET /api/v1/ticker/contracts

Parameters

No parameters needed

Response Items

Each ticker is an object with the following fields:

• product_type Instrument type (Perpetual or Spot)
• name Product name
• instrument Globe product instrument
• best_bid Best bid level object with price and market size
• best_ask Best ask level object with price and market size
• base_volume Total amount traded over the last 24 hours, in base currency
• quote_volume Total amount traded over the last 24 hours, in quote currency
• volume Same as quote_volume, used for backwards-compatibility
• price_change_percent Percentage change of the price over the last 24 hours
• funding_rate Current funding rate percentage
• mark_price Current mark price
• index_price Current index price
• contract_price_currency Currency of the contract price field
• contract_price The amount a single contract is worth
• contract_type The type of contract: Inverse, Quanto or Vanilla

Get Ticker Pairs

curl "https://globedx.com/api/v1/ticker/pairs"

Response:

[
  {
    "product_type": "spot",
    "name": "Globe Derivative Token / Tether",
    "instrument": "GDT/USDT",
    "best_bid": {
      "price": 0.2096,
      "volume": 44244498248.0
    },
    "best_ask": {
      "price": 0.2098,
      "volume": 99106486052.0
    },
    "volume": 500000000.0,
    "quote_volume": 500000000.0,
    "base_volume": 104800000.0,
    "price_change_percent": 2.9513034923757995,
    "mid_market_price": 0.2097,
    "last_trade_price": 0.2093
  },
  {
    "product_type": "spot",
    "name": "Bitcoin / Tether",
    "instrument": "BTC/USDT",
    "best_bid": {
      "price": 40920.24,
      "volume": 1049139.0
    },
    "best_ask": {
      "price": 41026.78,
      "volume": 443822.0
    },
    "volume": 0.0,
    "quote_volume": 0.0,
    "base_volume": 13.7,
    "price_change_percent": 0,
    "mid_market_price": 40973.51,
    "last_trade_price": 41569.78
  }
]

Ticker data for all spot pairs.

HTTP Request

GET /api/v1/ticker/pairs

Parameters

No parameters needed

Response Items

Each ticker is an object with the following fields:

• product_type Instrument type (Perpetual or Spot)
• name Product name
• instrument Globe product instrument
• best_bid Best bid level object with price and market size
• best_ask Best ask level object with price and market size
• base_volume Total amount traded over the last 24 hours, in base currency
• quote_volume Total amount traded over the last 24 hours, in quote currency
• volume Same as quote_volume, used for backwards-compatibility
• price_change_percent Percentage change of the price over the last 24 hours
• index_price Current index price
• last_trade_price Last trade price

Get Ticker Orderbook

curl "https://globedx.com/api/v1/ticker/orderbook"

Response:

{
  "bids": [[34772.0, 18327.0]],
  "asks": [[34776.5, 14102.0]]
}

The top 25 bid and ask levels of the order book for the ticker instrument.

HTTP Request

GET /api/v1/ticker/orderbook

Parameters

Response

Get Trades

curl "https://globedx.com/api/v1/history/my-trades?instrument=XBTUSD&page=1" <authentication headers>

Response:

[
  {
    "price": 59000.0,
    "quantity": 10000.0,
    "role": "maker",
    "side": "buy",
    "timestamp": 1617212555193,
    "trade_no": "8157636791"
  }
]

Your executed trades for an product.

HTTP Request

GET /api/v1/history/my-trades?instrument=<instrument>&page=<page_no>

Parameters

Details

Note that to use this endpoint you need to pass the authentication headers, see authentication.

Response Items

Each trade is an object with the following fields:

• price price at which the order traded
• quantity trade size
• side side of the trade, either buy or sell
• timestamp Unix Millisecond Timestamp when the trade occurred

Get Positions (Derivatives)

curl "https://globedx.com/api/v1/positions" <authentication headers>

Response:

{
  "UNIUSD": {
    "quantity": 10.0,
    "avg_price": 22.906,
    "cost": 0.0003054,
    "long_open_contracts": 0,
    "short_open_contracts": 0
  },
  "XBTUSD": {
    "quantity": 10000.0,
    "avg_price": 32732.5,
    "cost": 0.0000229,
    "long_open_contracts": 0,
    "short_open_contracts": 0
  }
}

Your current active positions.

HTTP Request

GET /api/v1/positions

Details

Note that to use this endpoint you need to pass the authentication headers, see authentication.

Response Items

Object response, with each position accessed by the symbol key for that product. Each position has the following fields:

Get Spot Balances

curl "https://globedx.com/api/v1/spot/balances" <authentication headers>

Response:

{
  "GDT": {
    "reserved": 0.0,
    "available": 1.0,
    "total": 1.0,
    "reserved_usd": 0.0,
    "available_usd": 0.3,
    "total_usd": 0.3
  },
  "USDT": {
    "reserved": 0.0,
    "available": 1000.0,
    "total": 1000.0,
    "reserved_usd": 0.0,
    "available_usd": 1000.0,
    "total_usd": 1000.0
  }
}

Balances for each coin in your spot account.

HTTP Request

GET /api/v1/spot/balances

Details

Note that to use this endpoint you need to pass the authentication headers. See authentication.

Response Items

Each balance object has the following fields:

Get Account Overview

curl "https://globedx.com/api/v1/account-overview" <authentication headers>

Response:

{
  "available_balance": 10.0000012,
  "account_balance": 10.0000012,
  "unrealized_pnl": 0,
  "maintenance_margin": 0,
  "initial_margin": 0,
  "margin_balance": 10.0000012,
  "liquidation_in_progress": false
}

Your account overview.

HTTP Request

GET /api/v1/account-overview

Details

Note that to use this endpoint you need to pass the authentication headers, see authentication.

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

Response Items

The account overview object has the following fields:

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:

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.

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:

WebSocket Public Channels

Public channels do not require authentication.

Index Price

Subscription message:

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

Example response:

{
  "subscription": {
    "channel": "index-price",
    "instrument": "XBTUSD"
  },
  "data": {
    "price": 32000.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": 34772.0,
        "volume": 18327.0
      }
    ],
    "asks": [
      {
        "price": 34776.5,
        "volume": 14102.0
      }
    ]
  }
}

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": "Globe Derivative Token / Tether",
      "symbol": "GDT/USDT",
      "base_symbol": "GDT",
      "quote_symbol": "USDT",
      "category": "Spot"
    },
    {
      "name": "Bitcoin/USD",
      "symbol": "XBTUSD",
      "base_symbol": "USD",
      "quote_symbol": "USD",
      "category": "Perp"
    },
    {
      "name": "Ethereum/USD",
      "symbol": "ETHUSD",
      "base_symbol": "USD",
      "quote_symbol": "USD",
      "category": "Perp"
    },
    {
      "name": "Bitcoin Vix",
      "symbol": "VXBT",
      "base_symbol": "USD",
      "quote_symbol": "USD",
      "category": "Perp"
    },
    {
      "name": "Uni/USD",
      "symbol": "UNIUSD",
      "base_symbol": "USD",
      "quote_symbol": "USD",
      "category": "Perp"
    },
    {
      "name": "Doge/USD",
      "symbol": "DOGEUSD",
      "base_symbol": "USD",
      "quote_symbol": "USD",
      "category": "Perp"
    }
  ]
}

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

Response

Product Detail

Subscription message:

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

Example response for a perpetual product:

{
  "subscription": {
    "channel": "product-detail",
    "instrument": "XBTUSD"
  },
  "data": {
    "base_symbol": "BTC",
    "category": "Perp",
    "contract_size": 1.0,
    "contract_type": "Inverse",
    "funding_period": 28800,
    "maker_fee": 0.0025,
    "max_leverage": 100,
    "min_qty": 1.0,
    "next_funding_time": 1564164110000,
    "price_precision": 2,
    "qty_increment": 1.0,
    "qty_precision": 0,
    "quote_symbol": "USD",
    "taker_fee": 0.0075,
    "tick_size": 500.0
  }
}

Example response for a spot product:

{
  "subscription": {
    "channel": "product-detail",
    "instrument": "GDT/USDT"
  },
  "data": {
    "maker_fee": 0.0,
    "taker_fee": 0.0075,
    "tick_size": 1.0,
    "category": "Spot",
    "price_precision": 2,
    "qty_precision": 8,
    "base_symbol": "USD",
    "quote_symbol": "USD"
  }
}

Full information about a product, including contract and funding information, fees and tick sizes.

Response

Recent Trades

Subscription message:

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

Example response:

{
  "subscription": {
    "channel": "trades",
    "instrument": "XBTUSD"
  },
  "data": [
    {
      "price": 34630.5,
      "quantity": 22806.0,
      "side": "sell",
      "timestamp": 1617119257074
    },
    {
      "price": 34632,
      "quantity": 4677.0,
      "side": "sell",
      "timestamp": 1617119257073
    },
    {
      "price": 34632,
      "quantity": 1870.0,
      "side": "sell",
      "timestamp": 1617119257072
    }
  ]
}

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.

Upon the first subscription the 100 most recent trades will be sent as a snapshot followed by delta updates of new recent orders if there are any.

Response

Market Overview

Subscription message:

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

Example response for a perpetuals product:

{
  "subscription": {
    "channel": "market-overview",
    "instrument": "XBTUSD"
  },
  "data": {
    "price_change_percent": -1.83,
    "volume": 408523.0,
    "mid_market_price": 34910.13,
    "last_trade_price": 34911.37,
    "funding_rate": 0.003,
    "mark_price": 34908.07,
    "index_price": 34978.38
  }
}

Example response for a spot product:

{
  "subscription": {
    "channel": "market-overview",
    "instrument": "BTC/USDT"
  },
  "data": {
    "price_change_percent": -1.83,
    "volume": 408523.0,
    "mid_market_price": 34910.13,
    "last_trade_price": 34911.37
  }
}

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

Response

Price History

Subscription message:

{
  "command": "subscribe",
  "channel": "price-history",
  "instrument": "XBTUSD",
  "resolution": "5m"
}

Example response:

{
  "subscription": {
    "channel": "price-history",
    "instrument": "XBTUSD",
    "resolution": "5m",
    "index": false
  },
  "data": {
    "high": 34864,
    "low": 34765.5,
    "open": 34831.5,
    "close": 34755.5,
    "time": 1625049000000,
    "volume": 177600.0
  }
}

Subscribe to receive the latest price olhc candle for a given resolution. The index boolean field is optional and false by default, and if true the index price ohlcv updates will be returned as an additional object, otherwise only the instrument price ohlcv updates will be returned.

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": "insurance-fund"
  },
  "data": {
    "balance": 0.5
  }
}

Current insurance fund balance in Bitcoin (pre-unified margin) or USD (post-unified margin).

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",
    "order_id": "7a48189d-3d5d-4b1e-a6ae-17b14cee33aa",
    "timestamp": 1593000000000
  }
}

Order Received response

Order Added response

{
  "subscription": {
    "channel": "my-market-events",
    "instrument": "XBTUSD"
  },
  "data": {
    "event": "order-added",
    "order_id": "7a48189d-3d5d-4b1e-a6ae-17b14cee33aa",
    "timestamp": 1593000000000
  }
}

Order Added response

Order Cancelled response

{
  "subscription": {
    "channel": "my-market-events",
    "instrument": "XBTUSD"
  },
  "data": {
    "event": "cancelled",
    "order_id": "1f76d399-bbaa-474b-ae85-032f026e3625",
    "cancel_id": "6a897c4b-65c5-42e1-84a4-816534a3a955",
    "timestamp": 1593000000000
  }
}

Cancelled response

Rejected response

{
  "subscription": {
    "channel": "my-market-events",
    "instrument": "XBTUSD"
  },
  "data": {
    "event": "rejected",
    "reason": "NotEnoughMargin",
    "request_id": "36f9b461-9335-4df3-a3ec-fdcecd9df318",
    "timestamp": 1593000000000
  }
}

Rejected response

Traded Event response

{
  "subscription": {
    "channel": "my-market-events",
    "instrument": "XBTUSD"
  },
  "data": {
    "event": "traded",
    "price": 54284.5,
    "quantity": 12000.0,
    "side": "buy",
    "order_id": "36f9b461-9335-4df3-a3ec-fdcecd9df318",
    "timestamp": 1593000000000,
    "role": "taker",
    "trade_no": "8157636791"
  }
}

Traded Event response

Stop Order Received response

{
  "subscription": {
    "channel": "my-market-events",
    "instrument": "XBTUSD"
  },
  "data": {
    "event": "stop-order-received",
    "order_id": "7a48189d-3d5d-4b1e-a6ae-17b14cee33aa",
    "timestamp": 1593000000000
  }
}

Stop/Take Profit Order Received response

Stop/Take Profit Order Triggered response

{
  "subscription": {
    "channel": "my-market-events",
    "instrument": "XBTUSD"
  },
  "data": {
    "event": "stop-order-triggered",
    "order_id": "7a48189d-3d5d-4b1e-a6ae-17b14cee33aa",
    "timestamp": 1593000000000
  }
}

Stop/Take Profit Order Triggered response

Place Order

Input message:

{
  "command": "place-order",
  "instrument": "XBTUSD",
  "price": 34950.0,
  "quantity": 0.6,
  "order_type": "limit",
  "side": "sell",
  "reduce_only": false,
  "order_id": "1279a5ef-ceca-423a-9eb9-caee5e3d85d0"
}

{
  "command": "place-order",
  "instrument": "XBTUSD",
  "quantity": 1.14,
  "order_type": "market",
  "side": "buy",
  "reduce_only": false,
  "order_id": "1279a5ef-ceca-423a-9eb9-caee5e3d85d0"
}

Place an order for a particular instrument.

Note that you do not get a confirmation of the order on this channel. Instead, subscribe to the my market events channel to get the order-received event.

Arguments

Cancel Order

Input message:

{
  "command": "cancel-order",
  "instrument": "XBTUSD",
  "order_id": "1279a5ef-ceca-423a-9eb9-caee5e3d85d0",
  "cancel_id": "c66ce3ec-cf26-4673-a8ac-58a3b2fc3384",
  "new_quantity": 0.02
}

Place a request to cancel an order with given order_id.

Arguments

Cancel All Orders

Input message:

{
  "command": "cancel-all-orders",
  "instrument": "XBTUSD",
  "cancel_id": "c66ce3ec-cf26-4673-a8ac-58a3b2fc3384",
  "side": "buy"
}

Place a request to cancel all orders for a given instrument.

Arguments

Cancel Stop/Take Profit Order

Input message:

{
  "command": "cancel-stop-order",
  "instrument": "XBTUSD",
  "order_id": "1279a5ef-ceca-423a-9eb9-caee5e3d85d0",
  "cancel_id": "c66ce3ec-cf26-4673-a8ac-58a3b2fc3384"
}

Place a request to cancel an stop order or a take profit order with given order_id.

Arguments

My Open Orders

Subscription message:

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

Example response:

{
  "subscription": {
    "channel": "my-orders",
    "instrument": "XBTUSD"
  },
  "data": {
    "79361d02-3f1d-4892-943a-3460f3e457d1": {
      "type": "order",
      "price": 50000.0,
      "quantity": 2.47,
      "filled_quantity": 1.11,
      "order_type": "limit",
      "side": "buy",
      "timestamp": 1593000000000,
      "order_id": "79361d02-3f1d-4892-943a-3460f3e457d1"
    },
    "0368315e-be48-4dcc-aaa2-0c30403c48ff": {
      "type": "order",
      "price": 47000.0,
      "quantity": 1.645,
      "filled_quantity": 0.688,
      "order_type": "limit",
      "side": "sell",
      "timestamp": 1593000010000,
      "order_id": "0368315e-be48-4dcc-aaa2-0c30403c48ff"
    }
  }
}

Receive a map of your open orders for a given instrument, with the order ID as the key. Responses are sent on subscription and on orders change.

My Open Orders response

My Account Overview (Derivatives)

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": 80.0,
    "account_balance": 100.0,
    "unrealized_pnl": 5.0,
    "maintenance_margin": 10.0,
    "initial_margin": 20.0,
    "margin_balance": 105.0,
    "liquidation_in_progress": false
  }
}

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

My Account Overview response

My Positions (Derivatives)

Subscription message:

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

Subscribe to your positions, messages are sent on every change to your position.

My Positions response

{
  "subscription": {
    "channel": "my-positions"
  },
  "data": {
    "XBTUSD": {
      "quantity": 10.0,
      "avg_price": 30572.0,
      "cost": 11.0,
      "long_open_contracts": 42,
      "short_open_contracts": 69
    }
  }
}

My Positions response

Request your open orders for a given instrument.

My Balances (Spot)

Subscription message:

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

Subscribe to balance messages. Updates are sent upon every change.

My Balances response

{
  "subscription": {
    "channel": "my-balances"
  },
  "data": {
    "balances": {
      "GDT": {
        "reserved": 0,
        "available": 1,
        "total": 1,
        "reserved_usd": 0.0,
        "available_usd": 0.3,
        "total_usd": 0.3
      },
      "USDT": {
        "reserved": 0,
        "available": 1000,
        "total": 1000,
        "reserved_usd": 0.0,
        "available_usd": 1000.0,
        "total_usd": 1000.0
      }
    }
  }
}

My Balances response

My Margin Account Overview (Unified Margin - Coming Soon)

Subscription message:

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

Subscribe to margin account overview messages. A response is sent on subscribe and on change.

My Margin Account Overview response

{
  "subscription": {
    "channel": "my-margin-account-overview"
  },
  "data": {
    "balances": {
      "BTC": {
        "allocated": 0.74,
        "value": 57121.55,
        "contribution": 42269.95,
        "value_factor": 1.0
      },
      "USDT": {
        "allocated": 3654.73,
        "value": 3654.73,
        "contribution": 3654.73,
        "value_factor": 1.0
      }
    },
    "collateral": 45924.68,
    "profit": 1738.32
}

My Margin Account Overview response

OAuth2 Integrations

We use and adhere to the OAuth2 specification to allow third parties to authenticate with us and use api endpoints authenticating specifically as indicated below. We strongly recommend using an OAuth2 library for implementation.

We support the authorization_code and refresh_token grant types as per the OAuth2 specification.

You should contact us if you wish to use globe as a third party through OAuth2. You will have to provide us with a redirection_url as per the OAuth2 specification.

We will provide a client_id and client_secret as per the OAuth2 specifications that you need to provide to your chosen OAuth2 library.

Supported Scopes

Initiating the Authentication Flow

Example URL

https://globedx.com/oauth2/auth?audience=&client_id=myClientId&max_age=0&nonce=yssjkdywopyorzsplvyuhgte&prompt=&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&response_type=code&scope=openid+offline+globe%2Fread+globe%2Ftrade+globe%2Fdeposit&state=zgtdldvqrgrvgqnpgurdkikx

The OAuth2 authentication flow requires that you send the user to the authentication endpoint with additional get parameters.

Please refer to the OAuth2 and OpenID specifications for a detailed explanation of these parameters.

Your chosen OAuth2 library should automatically generate this URL for you.

Handling the Callback

Once the user has authenticated themselves they will be redirected to

https://example.com/callback?code=grantCode&scope=openid+offline+globe%2Fread+globe%2Ftrade+globe%2Fdeposit&state=zgtdldvqrgrvgqnpgurdkikx

Example using curl

curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code&code=grantCode&redirect_uri=https://example.com/callback&client_id=myClientId&client_secret=myClientSecret" \
     https://globedx.com/oauth2/token

You will get a response like this

{
  "access_token": "dmR0n6dYAzLsuGJ6-ginYvTTFuXrueRqUuLOdlT_DRA.IUBu6F7s9NNXzpdTDnIRSbelfNztMecDZC5SL2QiUHc",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InB1YmxpYzo2ZGQzZjI3Zi1lMGJjLTQ4OTktOTdjNi05M2QwMGVjNGQ4OWEifQ.eyJhdF9oYXNoIjoiUl9aRjM0SG9jcmc4cG54dTBQd1g3QSIsImF1ZCI6WyI0ODY3MjJkMi0wOGIxLTQ1NGQtOGMyMy02ZGM2NWNkZWQ0YzEiXSwiYXV0aF90aW1lIjoxNjI4Njg4NTg4LCJleHAiOjE2Mjg2OTIxOTAsImlhdCI6MTYyODY4ODU5MCwiaXNzIjoiaHR0cHM6Ly9nbG9iZWR4Lm9yZy8iLCJqdGkiOiJhMzZlODAxNy1lZDZjLTQ1MTktYWRiZC0wYzI5MmE1MjMxMTIiLCJub25jZSI6Im1sd3ZydWpqeXFmZnZ5aHVkcGh2cndkYSIsInJhdCI6MTYyODY4ODU3OCwic2lkIjoiYzBjYjY2OTQtZWViOC00NTBkLTgyOTEtOGQwOGFhOWU2N2E3Iiwic3ViIjoiMTEyMTM3In0.ZdktQEXcKStSe92awnKHh-KLp_-CdhGcCDVVag85-az5BkjiLUSHnGs8yE2PaOybzqMQpv6alVf2wVDmnRARh_5ivzP120bZEhVD5rdc2Fnz2EqJaPWOYlwI7G-NjnjgtynL_xSBH9--LgSA4VP2uLEX_zE5Kt_VmvjtHTyGTEXe7E9Do0yLpQ1daJNoxHhYUEymg_j13nymrF-HtCazZtuzoPzZtAfnaDuS6iYfALxsajkpKHb6THQIgI6Kn4lzqpC6Pq2hiI4PKpkyROKP4oJZuJJKbhrhezbn9zZVxrEyNUAMiF1l4zRsjMJSrDuu6Tr2Wpfu2rUD1_L3x5ivh1uLaccp0pJIrOdCJafYUVC9I92yh8ayVVdhi0j5NuNphOgv-ywUO1YCw7kOkjdN-HrW85s2fLgP9az6iKeUPYxkWCk8J_mgKm13o5WR2kj1GTUVfqqIZxSsADcD57RxcaFuJOBgFjvyt1NyuvCqMeu6Hq3a9l44Vmh-Mi-ZFUCirJvP6iqm_8ruAyfi4LCwOTFm2bvND58vhaKGDHrUoPYQfIuv7l5NffiGdAhg9fJPGMQvBlqkoydOdkp9tPSP13pzd_yOy2yMQIkYxRCIEZcOlbpOjbKIDJZ3KHKvY_HogneBBAIg8VqKDTWjo9Z430xhbMW1mQ3SOxuXVTw-QQQ",
  "refresh_token": "b7nqmRmG5RZyDzry_FsX2FXeSXtbKYfy9oBncl-p3z0.qDyZiHozuyyAuDPJDfTivUydO9EuxnoMm0Lrd2ZM5Sw",
  "scope": "openid offline globe/read globe/trade globe/deposit",
  "token_type": "bearer"
}

The id_token is a JWT that looks like this

{
  "at_hash": "R_ZF34Hocrg8pnxu0PwX7A",
  "aud": ["myClientId"],
  "auth_time": 1628688588,
  "exp": 1628692190,
  "iat": 1628688590,
  "iss": "https://globedx.com/",
  "jti": "a36e8017-ed6c-4519-adbd-0c292a523112",
  "nonce": "mlwvrujjyqffvyhudphvrwda",
  "rat": 1628688578,
  "sid": "c0cb6694-eeb8-450d-8291-8d08aa9e67a7",
  "sub": "112137"
}

After the user has authenticated themselves with us and consented to the integration they will be redirected to your redirection_url with additional parameters.

You will then need to call the token endpoint from your backend server with the grant code in order to complete the flow.

You will receive a JSON response containing an access_token can be used to make API requests, a refresh_token that can be used to request a new acccess_token when the original one expires and an id_token is a JWT containing the user_id in the sub field.

Additional Setup

We will also generate a api_secret key for you to sign each request with as detailed below. This is not part of the OAuth2 specification.

Making API Requests on behalf of the user

Required API Headers

X-Access-OAuth2-Token: <access_token>
X-Access-Nonce: <nonce>
X-Access-Signature: <signature>

Here is some sample code to generate the signature

const crypto = require("crypto");

const user_id = 112137;
const api_secret = "F7MQ2eKQ4imXF22VnhgQREPoFiYsim1h";
const nonce = 1;
const verb = "GET";
const endpoint = "/api/v1/account-overview";

const hmac = crypto.createHmac("sha256", api_secret);
const signature = hmac
  .update(`${nonce}${user_id}${verb}${endpoint}`)
  .digest("base64");

Here is an example API call using OAuth2 tokens

curl 'https://globedx.com/api/v1/account-overview' \
     -H 'X-Access-OAuth2-Token: dmR0n6dYAzLsuGJ6-ginYvTTFuXrueRqUuLOdlT_DRA.IUBu6F7s9NNXzpdTDnIRSbelfNztMecDZC5SL2QiUHc' \
     -H 'X-Access-Nonce: 1' \
     -H 'X-Access-Signature: 45a0hNa+b6007i3J3nlLPUL+2XLQ8JU5/zHWUVcrKtY='

Once you have acquired an access_token for a user you can then use the above API endpoints (HTTP and websocket) on behalf of that user by providing the access_token as well as a nonce and signature as HTTP headers.

The nonce needs to be a monotonically increasing number and the same nonce cannot be used for more than one API request.

The signature is calculated using HMAC-SHA256 with the api_secret used as the secret and a concatenation of the nonce, user_id, verb and endpoint URL as the content.

All other aspects of the API remain the same.