NAV
Example

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:

TypeDescription
missing-headerA required HTTP header is missing
invalid-headerAn HTTP header has invalid content
needs-authenticationThis service or channel requires authentication
token-expiredA verification token has expired or is invalid
invalid-base64A base 64 encoded field could not be decoded
non-increasing-nonceHMAC nonce must be larger than the previous value
invalid-signatureHMAC signature was not valid
invalid-api-keyThe provided API key is invalid or was deleted
rate-limit-exceededToo many requests received from this connection
exchange-busyThe exchange currently cannot accept new orders due to high load
unsupported-messageThis message type is not supported by the API. For example binary websocket messages are not supported
invalid-requestThe request has missing fields or fields with the wrong data types
invalid-jsonThe request contained JSON syntax errors
invalid-instrumentThe provided instrument is not a valid product
internalAn internal error occurred

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

TypeDescription
NotEnoughMarginnot enough margin in account to place trade
TradingSuspendedtrading suspended for that market
TraderSuspendedyou are suspended from trading (contact support)
UnknownInstrumentyou have used an invalid instrument, check supported instruments
UnknownOrderorder specified is unknown
PriceTickSizeprice must be an integer multiple of that markets tick size
DuplicateIdhave specified an already existing id
WouldMatchwhen placing reduce only order, would match rather than being a maker order
NotFoundorder or cancel not found
AlreadyTradedopen order has already been traded
PriceZeroplease specify a valid price, as zero price is not valid
QuantityTooBigquantity is too big if order size is larger than
PriceOutsideBandwidthprice must be within the 10% of the market price (mark price for derivatives)
PositionTooLargeonly allowed a maximum position of 10,000,000 for a derivative market
QuantityZeroquantity of order must be non zero and positive
NotEnoughFundsnot enough spot funds to place the trade
NotSupportedif trying to use a feature not yet released or supported fully
NonReducingif order placed with reduce only parameter of true and it doesn’t reduce your position
TooManyOpenOrdersspot only supports a maximum of 32,768 open orders for a given market

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.

Request TypeRate Limit
HTTP/REST1 request per second
Websocket50 messages per second

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.

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.

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

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

Derivative Instruments

InstrumentSymbol
Bitcoin / US DollarXBTUSD
Ethereum / US DollarETHUSD
Bitcoin VixVXBT

Spot Instruments (Coming Soon)

InstrumentSymbol
Globe Derivative Token / TetherGDT/USDT

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:

ResolutionResolution parameter
1 minute“1m”
3 minutes“3m”
5 minutes“5m”
15 minutes“15m”
30 minutes“30m”
1 hour“1h”
2 hours“2h”
4 hours“4h”
6 hours“6h”
12 hours“12h”
1 day“1d”
3 days“3d”
1 week“1w”

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:

Status CodeReason
400Bad Request – Invalid request format
401Unauthorized – Invalid API Key
403Forbidden – You do not have access to the requested resource
404Not Found
500Internal Server Error

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

Parameter NameDescription
fromStart time in Unix Millisecond Timestamp
toEnd time in Unix Millisecond Timestamp
maxMaximum amount of historical candles, note the maximum is 1440 candles

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:

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

Parameter NameDescription
fromStart time in Unix Millisecond Timestamp
toEnd time in Unix Millisecond Timestamp
maxMaximum amount of historical candles, note the maximum is 1440 candles

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:

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,
    "quantity": 10000,
    "side": "buy",
    "timestamp": 1617212555193
  }
]

Your open orders for an product.

HTTP Request

GET /api/v1/orders/open-orders

Parameters

Parameter NameRequiredDescription
instrumentYesGlobe product ticker (e.g. XBTUSD)
upto_timestampYesUnix Millisecond Timestamp to return open orders up to (see below)
page_sizeNoAmount of open orders to return per page (default is 100)

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:

Get Ticker

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

Response:

{
  "instrument": "XBTUSD",
  "best_bid": {
    "price": 39076,
    "volume": 707
  },
  "best_ask": {
    "price": 39078,
    "volume": 30888
  },
  "volume": 5517441,
  "price_change_percent": 0.5,
  "funding_rate": 0.023,
  "mark_price": 35000.78,
  "index_price": 35010.12
}

Ticker for a specified instrument.

HTTP Request

GET /api/v1/ticker

Parameters

Parameter NameRequiredDescription
instrumentYesGlobe product ticker (e.g. XBTUSD)

Response Items

Each ticker is an object with the following fields:

Get Ticker Contracts

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

Response:

[
  {
    "product_type": "Perpetual",
    "instrument": "XBTUSD",
    "best_bid": {
      "price": 39076,
      "volume": 707
    },
    "best_ask": {
      "price": 39078,
      "volume": 30888
    },
    "volume": 5517441,
    "price_change_percent": 0.5,
    "funding_rate": 0.023,
    "mark_price": 35000.78,
    "index_price": 35010.12,
    "price_currency": "USD"
  },
  {
    "product_type": "Perpetual",
    "instrument": "ETHUSD",
    "best_bid": {
      "price": 2000,
      "volume": 707
    },
    "best_ask": {
      "price": 2010,
      "volume": 30888
    },
    "volume": 5517441,
    "price_change_percent": 0.5,
    "funding_rate": 0.023,
    "mark_price": 2005.78,
    "index_price": 2000.12,
    "price_currency": "USD"
  }
]

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:

Get Ticker Orderbook

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

Response:

{
  "bids": [[34772, 18327]],
  "asks": [[34776.5, 14102]]
}

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

HTTP Request

GET /api/v1/ticker/orderbook

Parameters

Parameter NameRequiredDescription
instrumentYesGlobe product ticker (e.g. XBTUSD)

Response

FieldDescription
bidsAn array of bids, where each bid is a tuple, with the first element is price and second is volume
asksAn array of asks, where each bid is a tuple, with the first element is price and second is volume

Get Trades

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

Response:

[
  {
    "price": 59000,
    "quantity": 10000,
    "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

Parameter NameRequiredDescription
instrumentYesGlobe product ticker (e.g. XBTUSD)
page_noNopage_no to return (there are 50 orders per page)

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:

Get Positions (Derivatives Only)

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

Response:

{
  "UNIUSD": {
    "quantity": -10,
    "avg_price": 22.906,
    "cost": 0.0003054,
    "long_open_qty": 0,
    "short_open_qty": 0
  },
  "XBTUSD": {
    "quantity": 10000,
    "avg_price": 32732.5,
    "cost": 0.0000229,
    "long_open_qty": 0,
    "short_open_qty": 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:

FieldDescription
quantityQuantity of contracts for that position
avg_priceAverage price of contracts for that position
costCost paid to purchase all the contracts for that position
long_open_qtyLong open quantity of contracts
short_open_qtyShort open quantity of contracts

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:

FieldDescription
available_balanceBalance available for withdrawal or placing new orders
account_balanceCurrent balance, excluding unrealized profit and margin allowance
margin_balanceSum of account balance and unrealized profit and losses
unrealized_pnlProfit or loss on your open positions if you were to close them at the current mark price
initial_marginThe amount of margin_balance required to place orders
maintenance_marginIf your margin balance falls below the maintenance_margin, your account will be liquidated
liquidation_in_progressWill be true if your account is currently being liquidated

Get Deposit Address

Get a deposit address for bitcoin or ERC-20 tokens.

HTTP Request

For Bitcoin:

curl "https://globedx.com/api/v1/deposit/bitcoin/address" <authentication headers>

Response:

{ "bitcoin_address": "3Jbi9j7LnFUhYtDy3Q1PonjnEgZDieG95E" }

For ERC-20:

curl "https://globedx.com/api/v1/deposit/erc20/address" <authentication headers>

Response:

{ "erc20_address": "0xe425855304be204a6e07799f0748950c82cc7029" }

GET /api/v1/deposit/<type>/address

TypeDescription
bitcoinBitcoin deposit address
erc20ERC-20 token deposit address

Details

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

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:

CommandArgumentsDescription
subscribeChannel name, other channel-specific argumentsSubscribe to a channel
unsubscribeChannel name, other channel-specific argumentsUnsubscribe from a channel. Provide the exact arguments as in the original subscription request
place-orderPlace a new order
cancel-orderCancel an existing order
cancel-stop-orderCancel an existing stop order
cancel-take-profit-orderCancel an existing take-profit order

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:

ErrorError Body
Need to be authenticated to subscribe or perform this function“not-authenticated”
Message body was invalid, check parameters and channel name“invalid-request”
Request is over the rate limit, please try reducing the frequency of requests to be within our specified rate limit“over-rate-limit”
Request was not received, as the exchange was temporarily busy, try again at a later time“exchange-busy”
When placing an order, the order type was incorrect for the fields given, in particular the existence of price and/or trigger price“wrong-order-type”

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

Get the current index price for a particular instrument.

Arguments

ArgumentRequiredDescription
instrumentYesThe symbol for the instrument

Response

FieldDescription
priceThe latest value of the index price for the given instrument

Market Depth

Subscription message:

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

Example response:

{
  "subscription": {
    "channel": "depth",
    "instrument": "XBTUSD"
  },
  "data": {
    "bids": [
      {
        "price": 34772,
        "volume": 18327
      }
    ],
    "asks": [
      {
        "price": 34776.5,
        "volume": 14102
      }
    ]
  }
}

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

FieldDescription
bidsAn array of bids, each with a price and volume field
asksAn array of asks, each with a price and volume field

Product List

Subscription message:

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

Example response:

{
  "subscription": {
    "channel": "product-list"
  },
  "data": [
    {
      "name": "Globe Derivative Token / Tether",
      "symbol": "GDT/USDT",
      "category": "Spot"
    },
    {
      "name": "Bitcoin/USD",
      "symbol": "XBTUSD",
      "category": "Perp"
    },
    {
      "name": "Ethereum/USD",
      "symbol": "ETHUSD",
      "category": "Perp"
    },
    {
      "name": "Bitcoin Vix",
      "symbol": "VXBT",
      "category": "Perp"
    },
    {
      "name": "Uni/USD",
      "symbol": "UNIUSD",
      "category": "Perp"
    },
    {
      "name": "Doge/USD",
      "symbol": "DOGEUSD",
      "category": "Perp"
    }
  ]
}

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

Response

FieldDescription
nameDisplay name of the instrument
symbolTrading symbol of the instrument
categoryEither Perp (perpetual future) or Spot

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.0,
    "taker_fee": 0.0075,
    "tick_size": 1.0,
    "category": "Perp",
    "price_precision": 2,
    "qty_precision": 8,
    "quote_symbol": "USD"
  }
}

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 funding information and fees.

Response

FieldDescription
funding_periodFunding period for the contract
next_funding_timeUnix Millisecond Timestamp of the next funding time
max_leverageMaximum leverage allowed for that instrument
maker_feeMaker fee percentage, providing orders to the book that are not instantly traded
taker_feeTaker fee percentage, for providing orders to the book that are instantly traded
tick_sizeTick size in the market
categoryEither Perp (perpetual future) or Spot

Recent Trades

Subscription message:

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

Example response:

{
  "subscription": {
    "channel": "trades",
    "instrument": "XBTUSD"
  },
  "data": [
    {
      "price": 34630.5,
      "quantity": 22806,
      "side": "sell",
      "timestamp": 1617119257074
    },
    {
      "price": 34632,
      "quantity": 4677,
      "side": "sell",
      "timestamp": 1617119257073
    },
    {
      "price": 34632,
      "quantity": 1870,
      "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

FieldDescription
pricePrice of order
quantityQuantity of order
sideSide type, can be either sell or buy
timestampTimestamp of the order in milliseconds

Market Overview

Subscription message:

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

Example response:

{
  "subscription": {
    "channel": "market-overview",
    "instrument": "XBTUSD"
  },
  "data": {
    "price_change_percent": -1.83,
    "volume": 408523,
    "funding_rate": 0.003,
    "mark_price": 34908.07,
    "index_price": 34978.38
  }
}

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

FieldDescription
price_change_percentPercentage change of the price over the last 24 hours
volumeTotal volume traded over the last 24 hours
funding_rateCurrent funding rate percentage
mark_priceCurrent mark price
index_priceCurrent index price

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

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

FieldDescription
num_contractsCurrent number of contracts open in an instrument market
timecandle start time
openopening price (first trade) in the candle interval
highhighest price during the candle interval
lowlowest price during the candle interval
closeclosing price (last trade) in the candle interval
volumevolume of trading activity during the candle interval

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

FieldDescription
num_contractsCurrent number of contracts open in an instrument market

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

Response

FieldDescription
balanceCurrent insurance fund balance in bitcoin

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

EventDescription
order-receivedOrder was received
order-addedOrder was added to the book
cancelledOrder was cancelled
rejectedOrder was rejected
tradedOrder was traded
stop-order-receivedStop order was received
stop-order-triggeredStop order was triggered
take-profit-order-receivedTake profit order was received
take-profit-order-triggeredTake profit order was triggered

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

FieldDescription
eventEvent type, i.e. order-received
order_idorder_id of the order
timestampTimestamp time of event

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

FieldDescription
eventEvent type, i.e. order-added
order_idorder_id of the order
timestampTimestamp time of event

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

FieldDescription
eventEvent type, i.e. cancelled
order_id
cancel_idID of the cancel request
timestampTimestamp time of event

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

FieldDescription
eventEvent type, i.e. rejected
reasonReason for rejection
timestampTimestamp time of event

Traded Event response

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

Traded Event response

FieldDescription
eventEvent type, i.e. traded
pricePrice purchased at
quantityNumber of contracts purchased
sideCan be either sell (for short purchases) or buy (for long purchases)
rolethis order’s role in the trade, either taker or maker
order_idThe ID for the traded order.
timestampTimestamp time of event

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

FieldDescription
eventEvent type, i.e. stop-order-triggered
order_idID of the order
timestampTimestamp time of event

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

FieldDescription
eventEvent type, i.e. stop-order-triggered
order_idID of the order
timestampTimestamp time of event

Place Order

Input message:

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

{
  "command": "place-order",
  "instrument": "XBTUSD",
  "quantity": 425,
  "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

ArgumentRequiredDescription
instrumentYesThe symbol for the instrument
priceOnly for non-market order typesPrice of the instrument for a limit order. Must be omitted for a market order
quantityYesNumber of contracts to purchase
order_typeYesOrder type, can be either market, limit, post-only, stop-market,stop-limit, take-profit-market or take-profit-limit
sideYesSide can be either sell or buy
order_idNoYour ID for the order. We recommend a v4 UUID for most applications, but all valid UUIDs are supported.
reduce_onlyNoBoolean, to indicate whether the order is to reduce a current position held only. Default is false
trigger_priceOnly if order_type is stop-market, stop-limit, take-profit-market or take-profit-limitPrice on which to submit the order to the matching engine, which can be a stop-market, stop-limit, take-profit-market or take-profit-limit order

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

Place a request to cancel an order with given order_id.

Arguments

ArgumentRequiredDescription
instrumentYesThe symbol for the instrument
order_idYesorder_id of the order to cancel
cancel_idNoYour ID for the cancellation request. We recommend a v4 UUID for most applications, but all valid UUIDs are supported.
new_quantityNoNew quantity to reduce order to (this must be less than the original quantity, if specified), this will make the order have the same matching engine queue order as the original order placed

Cancel All Orders

Input message:

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

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

Arguments

ArgumentRequiredDescription
instrumentYesThe symbol for the instrument
cancel_idNoYour ID for the cancellation request. We recommend a v4 UUID for most applications, but all valid UUIDs are supported.

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

ArgumentRequiredDescription
instrumentYesThe symbol for the instrument
order_idYesorder_id of the order to cancel
cancel_idNoYour ID for the cancellation request. We recommend a v4 UUID for most applications, but all valid UUIDs are supported.

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,
      "quantity": 500,
      "filled_quantity": 230,
      "order_type": "limit",
      "side": "buy",
      "timestamp": 1593000000000,
      "order_id": "79361d02-3f1d-4892-943a-3460f3e457d1"
    },
    "0368315e-be48-4dcc-aaa2-0c30403c48ff": {
      "type": "order",
      "price": 47000,
      "quantity": 600,
      "filled_quantity": 300,
      "order_type": "limit",
      "side": "sell",
      "timestamp": 1593000010000,
      "order_id": "0368315e-be48-4dcc-aaa2-0c30403c48ff"
    }
  }
}

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": 80,
    "account_balance": 100,
    "unrealized_pnl": 5,
    "maintenance_margin": 10,
    "initial_margin": 20,
    "margin_balance": 105,
    "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

FieldDescription
available_balanceBalance available for withdrawal or placing new orders
account_balanceCurrent balance, excluding unrealized profit and margin allowance
margin_balanceSum of account balance and unrealized profit and losses
unrealized_pnlProfit or loss on your open positions if you were to close them at the current mark price
initial_marginThe amount of margin_balance required to place orders
maintenance_marginIf your margin balance falls below the maintenance_margin, your account will be liquidated
liquidation_in_progressWill be true if your account is currently being liquidated

My Positions (Derivatives Only)

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,
      "avg_price": 30572,
      "cost": 11.0,
      "long_open_qty": 42,
      "short_open_qty": 69
    }
  }
}

My Positions response

FieldDescription
quantityQuantity of contracts for that position
avg_priceAverage price of contracts for that position
costCost paid to purchase all the contracts for that position
long_open_qtyLong open quantity of contracts
short_open_qtyShort open quantity of contracts

Request your open orders for a given instrument.

My Balances (Spot Only - Coming Soon)

Subscription message:

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

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

My Balances response

{
  "subscription": {
    "channel": "my-balances"
  },
  "data": {
    "balances": {
      "GDT": {
        "reserved": 0,
        "available": 1
      },
      "USDT": {
        "reserved": 0,
        "available": 1000
      }
    }
  }
}

My Balances response

FieldDescription
reservedQuantity reserved for orders placed
availableQuantity available for withdrawal or new orders

Note reserved + available = total balance for that currency.

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.

Endpoint NameEndpoint URLDescription
Authenticationhttps://globedx.com/oauth2/authInitiate the oauth2 flow
Tokenhttps://globedx.com/oauth2/tokenRetrieve the oauth2 access token, refresh token and id token

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

ScopeDescription
openidreturns an id_token in which the sub is the user’s user_id
offlinereturns a refresh_token that can be used to request a new access_token when it expires
globe/readaccess API endpoints that allow you to read account information for the user
globe/tradeaccess API endpoints that allow you to trade on the user’s behalf
globe/depositaccess API endpoints that allow you to retrieve a deposit address for the user’s account

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.

ParameterDescription
audience""
client_idProvided by us during setup
max_age“0”
nonceRandom string to prevent replay attacks
prompt""
redirect_uriThe URL that you want to be called back on once the authentication is successful
scopeThe list of space separated scopes that you want the access token to grant
response_type“code”
stateOpaque string that will be passed back, this can be used for CSRF prevention

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.

ParametersDescription
codeThe grant code that can be used by your backend code to complete the flow
scopeThe scope that was granted by the user
stateOpaque string provided in the original URL

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.