globe | Exchange everything

Documentation

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

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.

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:

Construct the signing text. This is a concatenation (without spaces) of:
- the decimal representation of the nonce
- the verb of the http request, for example GET or POST
- the path part of the URL, including the query string
For example, in a request for trade history, with verb GET and the url path /api/v1/history/my-trades?instrument=BTC-PERP&page=1. If the nonce is 1667563915, this gives us "1667563915GET/api/v1/history/my-trades?instrument=BTC-PERP&page=1".
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.
Base64-encode the HMAC signature.

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

To authenticate a connection, construct headers as follows:

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

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.from(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
};

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:

Type	Description
missing-header	A required HTTP header is missing
invalid-header	An HTTP header has invalid content
needs-authentication	This service or channel requires authentication
token-expired	A verification token has expired or is invalid
invalid-base64	A base 64 encoded field could not be decoded
non-increasing-nonce	HMAC nonce must be larger than the previous value
invalid-signature	HMAC signature was not valid
invalid-api-key	The provided API key is invalid or was deleted
rate-limit-exceeded	Too many requests received from this connection
exchange-busy	The exchange currently cannot accept new orders due to high load
unsupported-message	This message type is not supported by the API. For example binary websocket messages are not supported
invalid-request	The request has missing fields or fields with the wrong data types
invalid-json	The request contained JSON syntax errors
invalid-instrument	The provided instrument is not a valid product
internal	An internal error occurred

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

Type	Description
NotEnoughMargin	not enough margin in account to place trade
TradingSuspended	trading suspended for that market
TraderSuspended	you are suspended from trading (contact support)
UnknownInstrument	you have used an invalid instrument, check supported instruments
UnknownOrder	order specified is unknown
PriceTickSize	price must be an integer multiple of that markets tick size
DuplicateId	have specified an already existing id
WouldMatch	when placing reduce only order, would match rather than being a maker order
NotFound	order or cancel not found
AlreadyTraded	open order has already been traded
PriceZero	please specify a valid price, as zero price is not valid
QuantityTooBig	quantity is too big if order size is larger than
PriceOutsideBandwidth	price must be within the 10% of the market price (mark price for derivatives)
PositionTooLarge	only allowed a maximum position of 10,000,000 for a derivative market
QuantityZero	quantity of order must be non zero and positive
NotEnoughFunds	not enough spot funds to place the trade
NotSupported	if trying to use a feature not yet released or supported fully
NonReducing	if order placed with reduce only parameter of true and it doesn’t reduce your position
TooManyOpenOrders	spot 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 Type	Rate Limit
HTTP/REST	1 request per second
Websocket	50 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 API

We have a single 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, details of 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 varies for spot vs derivatives products. See the HTTP API and Websocket API sections for more information.

Types

Timestamps

Unless explicitly specified, all timestamps from API are returned as 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

Instrument	Symbol
Bitcoin / US Dollar Linear Perpetual	BTC-PERP
Ethereum / US Dollar Linear Perpetual	ETH-PERP
Bitcoin Vix Linear Perpetual	BTC-VIX

Spot Instruments

Instrument	Symbol
Globe Derivative Token / Tether	GDT/USDT
Bitcoin / Tether	BTC/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:

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

For real-time market data updates, see the WebSocket Feed documentation for connecting and re-creating a perfect real-time copy of the order book and trades.

Errors

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

Common error codes:

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

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

Get Historic Market Rates

Historic rates for a product. Rates are returned in for the timespan specified

by the requested resolution, starting at the "time".

curl "https://globe.exchange/api/v1/history/BTC-PERP/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
  }
]

HTTP Request

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

Parameters

Parameter Name	Description
from	Start time in Unix Millisecond Timestamp
to	End time in Unix Millisecond Timestamp
max	Maximum amount of historical candles, note the maximum is 1440 candles

Details

The above parameters are optional. The maximum number of candles that can be retrieved in one request is 1000.

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

Get Historic Index Price Rates

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

curl "https://globe.exchange/api/v1/history/index-price/BTC-PERP/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
  }
]

HTTP Request

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

Parameters

Parameter Name	Description
from	Start time in Unix Millisecond Timestamp
to	End time in Unix Millisecond Timestamp
max	Maximum 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:

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

Your open orders for an product.

curl "https://globe.exchange/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
  }
]

HTTP Request

GET /api/v1/orders/open-orders

Parameters

Parameter Name	Required	Description
instrument	Yes	Globe product ticker (e.g. BTC-PERP)
upto_timestamp	Yes	Unix Millisecond Timestamp to return open orders up to (see below)
page_size	No	Amount 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:

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

Ticker data for a specified instrument.

curl "https://globe.exchange/api/v1/ticker"

Response:

{
  "product_type": "Perpetual",
  "name": "Bitcoin/USD Perpetual",
  "instrument": "BTC-PERP",
  "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"
}

HTTP Request

GET /api/v1/ticker

Parameters

Parameter Name	Required	Description
instrument	Yes	Globe product ticker (e.g. BTC-PERP)

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

Ticker contracts for all instruments in an array.

curl "https://globe.exchange/api/v1/ticker/contracts"

Response:

[
  {
    "product_type": "Perpetual",
    "name": "Bitcoin/USD Perpetual",
    "instrument": "BTC-PERP",
    "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"
  }
]

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

Ticker data for all spot pairs.

curl "https://globe.exchange/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
  }
]

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

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

curl "https://globe.exchange/api/v1/ticker/orderbook"

Response:

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

HTTP Request

GET /api/v1/ticker/orderbook

Parameters

Parameter Name	Required	Description
instrument	Yes	Globe product ticker (e.g. BTC-PERP)

Response

Field	Description
`bids`	An array of bids, where each bid is a tuple (`price`, `market size`)
`asks`	An array of asks, where each bid is a tuple, (`price`, `market size`)

Recent Trades

Your recent executed trades for a given product.

curl "https://globe.exchange/api/v1/history/trades/recent/BTC-PERP" <authentication headers>

Response:

[
  {
    "trade_no": 8157636791
    "side": "buy",
    "role": "maker",
    "price": 59000.0,
    "quantity": 0.1,
    "timestamp": 1617212555193,
    "order_id": "c73d57a2-adc4-4646-9e45-4f96c086bb9c"
  },
    ...
]

HTTP Request

GET /api/v1/history/trades/recent/<instrument>

Parameters

Parameter Name	Required	Description
instrument	Yes	Globe product ticker (e.g. BTC-PERP)

Details

This endpoint will return the most recent 100 trades for the last 7 days.

If you need a full list of trades over a longer time period please use the trades export page on the website.

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:

trade_no a unique identifier for this trade
price price at which the order traded
quantity trade size
side side of the trade, either buy or sell
role whether this trade was a taker or maker
timestamp Unix Millisecond Timestamp when the trade occurred
order_id the unique idenfier used when placing the order that resulted in this trade

Get Positions (Derivatives)

Your current active positions.

curl "https://globe.exchange/api/v1/positions" <authentication headers>

Response:

{
  "UNI-PERP": {
    "quantity": 10.0,
    "avg_price": 22.906,
    "cost": 0.0003054,
    "long_open_contracts": 0,
    "short_open_contracts": 0
  },
  "BTC-PERP": {
    "quantity": 10000.0,
    "avg_price": 32732.5,
    "cost": 0.0000229,
    "long_open_contracts": 0,
    "short_open_contracts": 0
  }
}

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:

Field	Description
`quantity`	Value of the position (number of contracts * contract size)
`avg_price`	Average price of contracts for that position
`cost`	Amount paid to purchase all the contracts for that position
`long_open_contracts`	Long open number of contracts
`short_open_contracts`	Short open number of contracts

Get Spot Balances

Balances for each coin in your spot account.

curl "https://globe.exchange/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
  }
}

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:

Field	Description
`reserved`	Quantity reserved for orders placed
`available`	Quantity available for withdrawal or new orders
`total`	Quantity total (reserved + available)
`reserved_usd`	Estimated USD value of reserved balance. Currently always `null`.
`available_usd`	Estimated USD value of available balance. Currently always `null`.
`total_usd`	Estimated USD value of total balance. Currently always `null`.

Get Account Overview

Your account overview.

curl "https://globe.exchange/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
}

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:

Field	Description
`available_balance`	Balance available for withdrawal or placing new orders
`account_balance`	Current balance, excluding unrealized profit and margin allowance
`margin_balance`	Sum of account balance and unrealized profit and losses
`unrealized_pnl`	Profit or loss on your open positions if you were to close them at the current mark price
`initial_margin`	The amount of margin_balance required to place orders
`maintenance_margin`	If your margin balance falls below the maintenance_margin, your account will be liquidated
`liquidation_in_progress`	Will be true if your account is currently being liquidated

Get Margin Account Overview

Your margin account overview.

curl "https://globe.exchange/api/v1/margin-account-overview" <authentication headers>

Response:

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

HTTP Request

GET /api/v1/margin-account-overview

Details

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

Response Items

The margin account overview object has the following fields:

Field	Description
`balances`	Contains the amount allocated, the market value, the value factor and the contribution to collateral for each coin
`collateral`	Total collateral (sum of contribution to collateral of each coin)
`profit`	Difference between derivatives exchange cash balance and total collateral available

WebSocket API

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

wss://globe.exchange/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:

Command	Arguments	Description
`subscribe`	Channel name, other channel-specific arguments	Subscribe to a channel
`unsubscribe`	Channel name, other channel-specific arguments	Unsubscribe from a channel. Provide the exact arguments as in the original subscription request
`place-order`		Place a new order
`cancel-order`		Cancel an existing order
`cancel-stop-order`		Cancel an existing stop order
`cancel-take-profit-order`		Cancel an existing take-profit order

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.

A typical subscription request message:

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

Unsubscribe

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 BTC-PERP is a different subscription than index-price for ETH-PERP

A typical unsubscribe request message:

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

Errors

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

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

Example error response for invalid parameters in request:

{
  "error": "invalid-request"
}

WebSocket Public Channels

Public channels do not require authentication.

Index Price

Get the current index price for a particular instrument.

Subscription message:

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

Example response:

{
  "subscription": {
    "channel": "index-price",
    "instrument": "BTC-PERP"
  },
  "data": {
    "price": 32000.0
  }
}

Arguments

Argument	Required	Description
`instrument`	Yes	The symbol for the instrument

Response

Field	Description
`price`	The latest value of the index price for the given instrument

Market Depth

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.

Subscription message:

{
  "command": "subscribe",
  "channel": "depth",
  "instrument": "BTC-PERP"
}

Example response:

{
  "subscription": {
    "channel": "depth",
    "instrument": "BTC-PERP"
  },
  "data": {
    "bids": [
      {
        "price": 34772.0,
        "volume": 18327.0
      }
    ],
    "asks": [
      {
        "price": 34776.5,
        "volume": 14102.0
      }
    ]
  }
}

Arguments

Argument	Required	Description
`instrument`	Yes	The symbol for the instrument
`grouping`	No	Group orders by this multiple of the tick size. Eg: If the tick size is $0.1, a grouping of 50 will gather orders into groups of $5 width. Valid options are 1, 2, 5, 10, 50, 100, 500, 1000.

Response

Field	Description
`bids`	An array of bids, each with a `price` and `volume` field. The volume field specifies market size.
`asks`	An array of asks, each with a `price` and `volume` field. The volume field specifies market size.

Product List

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

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 Perpetual",
      "symbol": "BTC-PERP",
      "base_symbol": "BTC",
      "quote_symbol": "USD",
      "category": "Perp"
    },
    ...
  ]
}

Response

Field	Description
`name`	Display name of the instrument
`symbol`	Trading symbol of the instrument
`base_symbol`	The currency in which an order size is specified
`quote_symbol`	The currency in which an order price is specified
`category`	Either `Perp` (perpetual future) or `Spot`

Product Detail

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

Subscription message:

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

Example response for a perpetual product:

{
  "subscription": {
    "channel": "product-detail",
    "instrument": "BTC-PERP"
  },
  "data": {
    "base_symbol": "BTC",
    "category": "Perp",
    "contract_size": 0.0001
    "contract_type": "Linear",
    "funding_period": 28800,
    "maker_fee": 0.0,
    "max_leverage": 100,
    "min_qty": 0.0001,
    "next_funding_time": 1658160000000,
    "price_precision": 3,
    "qty_increment": 0.0001,
    "qty_precision": 4,
    "quote_symbol": "USD",
    "taker_fee": 0.0001,
    "tick_size": 1.0,
    "status": "Active"
  }
}

Example response for a spot product:

{
  "subscription": {
    "channel": "product-detail",
    "instrument": "GDT/USDT"
  },
  "data": {
    "maker_fee": 0.0,
    "taker_fee": 0.0005,
    "tick_size": 0.0001,
    "category": "Spot",
    "price_precision": 6,
    "qty_precision": 8,
    "base_symbol": "GDT",
    "quote_symbol": "USDT",
    "qty_increment": 1e-8,
    "status": "Active"
  }
}

Response

Field	Description
`base_symbol`	The currency in which an order size is specified
`category`	Either `Perp` (perpetual future) or `Spot`
`contract_size`	(Perp only) The amount a single contract is worth
`contract_type`	(Perp only) Either `Inverse` or `Linear`
`funding_period`	(Perp only) Funding period for the product, in seconds.
`maker_fee`	Maker fee percentage (orders to the book that are not instantly traded)
`max_leverage`	(Perp only) Maximum leverage allowed for that product
`min_qty`	Minimum amount for an order
`next_funding_time`	`Unix Millisecond Timestamp` of the next funding time
`price_precision`	Maximum number of decimal places supported for product price
`qty_increment`	Product quantity step size
`qty_precision`	Maximum number of decimal places supported for product quantity
`quote_symbol`	The currency in which an order price is specified
`taker_fee`	Taker fee percentage (orders to the book that are instantly traded)
`tick_size`	Tick size in the market (product price step size)
`status`	One of `Active`, `Suspended`, `Configuring`, `NoMatching` or `Closed`.

Recent Trades

The 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 trades if there are any.

Subscription message:

{
  "command": "subscribe",
  "channel": "trades",
  "instrument": "BTC-PERP"
}

Example response:

{
  "subscription": {
    "channel": "trades",
    "instrument": "BTC-PERP"
  },
  "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
    }
  ]
}

Response

Field	Description
`price`	Price of order
`quantity`	Amount traded
`side`	Side of trade, from the taker's perspective. Can be either `sell` or `buy`.
`timestamp`	Timestamp of the order in milliseconds

Market Overview

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. Be aware that not all fields may be included in a given message.

Subscription message:

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

Example response for a perpetuals product:

{
  "subscription": {
    "channel": "market-overview",
    "instrument": "BTC-PERP"
  },
  "data": {
    "price_change_percent": 4.475,
    "volume": 1058.3343,
    "volume_usd": 22932462.6379,
    "mid_market_price": 22208.5,
    "last_trade_price": 22179.0,
    "funding_rate": 0.0,
    "mark_price": 22204.724,
    "index_price": 22211.293
  }
}

Example response for a spot product:

{
  "subscription": {
    "channel": "market-overview",
    "instrument": "GDT/USDT"
  },
  "data": {
    "price_change_percent": -1.83,
    "volume": 523.0,
    "mid_market_price": 20.13,
    "last_trade_price": 21.37
  }
}

Response

Field	Description
`price_change_percent`	Percentage change of the price over the last 24 hours
`volume`	Total amount traded over the last 24 hours, in base currency units
`volume_usd`	Total amount traded over the last 24 hours, valued in USD
`mid_market_price`	Current mid-market price according to the order book
`last_trade_price`	Price of the last executed trade
`funding_rate`	(Derivatives Only) Current funding rate percentage
`mark_price`	(Derivatives Only) Current mark price
`index_price`	(Derivatives Only) Current index price

Price History

Subscribe to receive the latest price OHLC 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.

Subscription message:

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

Example response:

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

Response

Field	Description
`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`	amount traded during the candle interval

Open Interest

Current number of contracts open in an instrument market

Subscription message:

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

Example response:

{
  "subscription": {
    "channel": "open-interest",
    "instrument": "BTC-PERP"
  },
  "data": {
    "num_contracts": 1002,
    "qty": 1002
  }
}

Response

Field	Description
`num_contracts`	Current number of contracts open for a derivatives product
`qty`	Total open interest in the base currency of the contract

Insurance Fund

Current insurance fund balance in USD.

Subscription message:

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

Example response:

{
  "subscription": {
    "channel": "insurance-fund"
  },
  "data": {
    "balance": 104705.2832
  }
}

Response

Field	Description
`balance`	Current insurance fund balance in USD

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

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:

Subscription message:

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

Market Event responses

Event	Description
`order-received`	Order was received
`order-added`	Order was added to the book
`cancelled`	Order was cancelled
`cancel-rejected`	Cancel request was rejected
`rejected`	Order was rejected
`traded`	Order was traded
`stop-order-received`	Stop order was received
`stop-order-triggered`	Stop order was triggered
`take-profit-order-received`	Take profit order was received
`take-profit-order-triggered`	Take profit order was triggered

Order response

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

Order Received response

Field	Description
`event`	Event type, i.e. `order-received`
`order_id`	`order_id` of the order
`timestamp`	Timestamp time of event
`liquidation`	If the order was triggered due to a liquidation (field ommitted if `false`)

Order Added response

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

Order Added response

Field	Description
`event`	Event type, i.e. `order-added`
`order_id`	`order_id` of the order
`timestamp`	Timestamp time of event
`liquidation`	If the order was triggered due to a liquidation (field ommitted if `false`)

Order Cancelled response

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

Cancelled response

Field	Description
`event`	Event type, i.e. `cancelled`
`order_id`
`cancel_id`	ID of the cancel request
`timestamp`	Timestamp time of event
`liquidation`	If the event was canceled due to a liquidation (field ommitted if `false`)

Cancellation Rejected response

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

Cancellation Rejected response

Field	Description
`event`	Event type, i.e. `rejected`
`reason`	Reason for rejection
`request_id`	ID of the rejected request
`timestamp`	Timestamp time of event

Rejected response

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

Rejected response

Field	Description
`event`	Event type, i.e. `rejected`
`reason`	Reason for rejection
`request_id`	ID of the rejected request
`timestamp`	Timestamp time of event

Traded Event response

{
  "subscription": {
    "channel": "my-market-events",
    "instrument": "BTC-PERP"
  },
  "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

Field	Description
`event`	Event type, i.e. `traded`
`price`	Price purchased at
`quantity`	Order size
`side`	Can be either `sell` (for short purchases) or `buy` (for long purchases)
`role`	this order's role in the trade, either `taker` or `maker`
`order_id`	The ID for the traded order.
`timestamp`	Timestamp time of event
`trade_no`	Sequence number of the trade, unique per product
`liquidation`	If the trade occured due to a liquidation (field ommitted if `false`)

Stop Order Received response

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

Stop/Take Profit Order Received response

Field	Description
`event`	Event type, i.e. `stop-order-triggered`
`order_id`	ID of the order
`timestamp`	Timestamp time of event

Stop/Take Profit Order Triggered response

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

Stop/Take Profit Order Triggered response

Field	Description
`event`	Event type, i.e. `stop-order-triggered`
`order_id`	ID of the order
`timestamp`	Timestamp time of event

Place Order

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.

Replacing an order

You can cancel and place an order in a single operation by specifying the id of the order you wish to cancel in the order_id_to_replace field.

If you specify the order_id_to_replace, this will return 2 events on the my market events channel: A cancelled event for the order being replaced and an order-received event for the new order. Note that if the order cannot be cancelled, because it's already been cancelled or traded, then you will receive a cancel-rejected event for the order being replaced, however the new order will still be placed (and you will still receive the order-received event.

Input message:

{
  "command": "place-order",
  "instrument": "BTC-PERP",
  "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": "BTC-PERP",
  "quantity": 1.14,
  "order_type": "market",
  "side": "buy",
  "reduce_only": false,
  "order_id": "1279a5ef-ceca-423a-9eb9-caee5e3d85d0"
}

Arguments

Argument	Required	Description
`instrument`	Yes	The symbol for the instrument
`price`	Only for non-market order types	Price of the instrument for a limit order. Must be omitted for a market order
`quantity`	Yes	Order size
`order_type`	Yes	Order type, can be either `market`, `limit`, `post-only`, `stop-market`,`stop-limit`, `take-profit-market` or `take-profit-limit`
`side`	Yes	Side can be either `sell` or `buy`
`order_id`	No	Your ID for the order. We recommend a v4 UUID for most applications, but all valid UUIDs are supported.
`reduce_only`	No	Boolean, to indicate whether the order is to reduce a current position held only. Default is `false`
`trigger_price`	Only if `order_type` is `stop-market`, `stop-limit`, `take-profit-market` or `take-profit-limit`	Price 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
`immediate_or_cancel`	No	Boolean, to indicate whether, after being placed, this order should immediately cancel any remainder of itself which did not match an existing order. Default is `false`
`order_id_to_replace`	No	The id of the order to replace with this one

Cancel Order

Place a request to cancel an order with given order_id.

Input message:

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

Arguments

Argument	Required	Description
`instrument`	Yes	The symbol for the instrument
`order_id`	Yes	`order_id` of the order to cancel
`cancel_id`	No	Your ID for the cancellation request. We recommend a v4 UUID for most applications, but all valid UUIDs are supported.
`new_quantity`	No	New quantity to reduce order to. (If specified, this must be less than the original quantity. This will make the order have the same matching engine queue order as the original order placed.)

Cancel All Orders

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

Input message:

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

Arguments

Argument	Required	Description
`instrument`	Yes	The symbol for the instrument
`cancel_id`	No	Your ID for the cancellation request. We recommend a v4 UUID for most applications, but all valid UUIDs are supported.
`side`	No	Whether to cancel all buy orders, all sell orders, or all orders. A value of "buy" = cancel all buy orders, "sell" = cancel all sell orders, and no value = cancel all orders (including all buy orders and all sell orders).

Cancel Stop/Take Profit Order

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

Input message:

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

Arguments

Argument	Required	Description
`instrument`	Yes	The symbol for the instrument
`order_id`	Yes	`order_id` of the order to cancel
`cancel_id`	No	Your ID for the cancellation request. We recommend a v4 UUID for most applications, but all valid UUIDs are supported.

My Open Orders

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.

Subscription message:

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

Example response:

{
  "subscription": {
    "channel": "my-orders",
    "instrument": "BTC-PERP"
  },
  "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"
    }
  }
}

My Open Orders response

Field	Description
`type`	`order`, `stop` or `take-profit`
`price`	Price at which the order is to be executed. Discluded for market orders.
`quantity`	Size of the order
`filled_quantity`	Size of the order that has already been filled
`order_type`	`market`, `limit` or `post-only`
`side`	`buy` or `sell`
`timestamp`	Millisecond timestamp time of event
`order_id`	The unique ID you provided for this order
`reduce_only`	Boolean, to indicate whether the order is to reduce a current position held only.
`liquidation`	Boolean, to indicate whether the order was triggered by a liquidation.
`trigger_type`	Only for an `order` type which was triggered by a Stop or Take Profit order, indicating the source type.
`trigger_price`	For a `stop` or `take-profit` type, the price the order will trigger at. For an `order` type which was triggered by one of those, the price which triggered it. Discluded for orders not related to `stop` or `take-profit`.

My Account Overview (Derivatives)

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

Subscription message:

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

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

Field	Description
`available_balance`	Balance available for withdrawal or placing new orders
`account_balance`	Current balance, excluding unrealized profit and margin allowance
`margin_balance`	Sum of account balance and unrealized profit and losses
`unrealized_pnl`	Profit or loss on your open positions if you were to close them at the current mark price
`initial_margin`	The amount of margin_balance required to place orders
`maintenance_margin`	The minimum required margin. If your margin balance falls below the maintenance_margin, your account will be liquidated
`liquidation_in_progress`	Boolean, will be true if your account is currently being liquidated

My Positions (Derivatives)

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

Subscription message:

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

My Positions response

{
  "subscription": {
    "channel": "my-positions"
  },
  "data": {
    "BTC-PERP": {
      "quantity": 10.0,
      "avg_price": 30572.0,
      "cost": 11.0,
      "long_open_qty": 42.0,
      "short_open_cqty": 69.0
    }
  }
}

My Positions response

Field	Description
`quantity`	Value of the position (number of contracts * contract size)
`avg_price`	Average price of contracts for that position
`cost`	Amount paid to purchase all the contracts for that position
`long_open_qty`	Long open quantity, in base currency
`short_open_cqty`	Short open quantity, in base currency

My Balances (Spot)

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

Subscription message:

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

My Balances response

{
  "subscription": {
    "channel": "my-balances"
  },
  "data": {
    "balances": {
      "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
      }
    }
  }
}

My Balances response

Field	Description
`reserved`	Quantity reserved for orders placed
`available`	Quantity available for withdrawal or new orders
`total`	Quantity total (reserved + available)
`reserved_usd`	Estimated USD value of reserved balance
`available_usd`	Estimated USD value of available balance
`total_usd`	Estimated USD value of total balance

My Margin Account Overview

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

Subscription message:

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

My Margin Account Overview response

{
  "subscription": {
    "channel": "my-margin-account-overview"
  },
  "data": {
    "balances": {
      "BTC": {
        "allocated": 0.74,
        "transferable": 0.74,
        "valuation": 17121.55,
        "multiplier": 1.0,
        "contribution": 17121.55
      },
      "GDT": {
        "allocated": 500.0,
        "transferable": 500.0,
        "valuation": 100.0,
        "multiplier": 1.2,
        "contribution": 120.0
      }
    },
    "collateral": 17241.55,
    "profit": 1738.32
}

My Margin Account Overview response

Field	Description
`balances`	Contains the amount allocated, how much can be transferred (based on your open positions), the market value, the collateral multiplier and the contribution to collateral for each coin
`collateral`	Total collateral (sum of contribution to collateral of each coin)
`profit`	Difference between derivatives exchange balance and total collateral available

OAuth2 Integrations

Endpoints

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 Name	Endpoint URL	Description
Authentication	https://globe.exchange/oauth2/auth	Initiate the oauth2 flow
Token	https://globe.exchange/oauth2/token	Retrieve 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

Scope	Description
openid	returns an `id_token` in which the `sub` is the user's `user_id`
offline	returns a `refresh_token` that can be used to request a new `access_token` when it expires
globe/read	access API endpoints that allow you to read account information for the user
globe/trade	access API endpoints that allow you to trade on the user's behalf
globe/deposit	access API endpoints that allow you to retrieve a deposit address for the user's account

Initiating the Authentication Flow

Example URL

https://globe.exchange/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.

Parameter	Description
audience	""
client_id	Provided by us during setup
max_age	"0"
nonce	Random string to prevent replay attacks
prompt	""
redirect_uri	The URL that you want to be called back on once the authentication is successful
scope	The list of space separated scopes that you want the access token to grant
response_type	"code"
state	Opaque 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://globe.exchange/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://globe.exchange/",
  "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.

Parameters	Description
code	The grant code that can be used by your backend code to complete the flow
scope	The scope that was granted by the user
state	Opaque 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://globe.exchange/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 accesstoken for a user you can then use the above API endpoints (HTTP and websocket) on behalf of that user by providing the accesstoken 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.