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:
- 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 beGET
and the endpoint would be/api/v1/ws"
. using the message to the right, this gives us"1587654321GET/api/v1/ws"
. - 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 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:
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.
Major Upcoming Changes: Unified Margin
Globe will soon be launching a Unified Margin model for derivatives trading and will offer linear perpetual contracts instead of the inverse and quanto contracts currently available. This will result in breaking changes to the API:
- Where
quantity
in the API currently refers to the number of contracts, it will instead refer to the size of the position. For example, to trade 100 contracts of a derivative product, you must specify the value of this position (100 contracts * contract size) instead of the number of contracts directly. The contract size for each product can be obtained via theproduct-details
channel. Similarly,quantity
reported by the API for open orders, recent trades and orderbook will be the size of the position instead of the number of contracts. - Where
volume
in the API currently refers to the number of contracts traded, it will instead refer to the value of the traded contracts. For example, 100,000 contracts traded of XBTUSD (inverse, $1 contract size) will be reported as a volume of $100,000.00, while 100,000 contracts traded of a linear Bitcoin-USD perpetual with 0.0001 BTC contract size will be reported as a volume of 10.0 BTC. - Derivatives trading currency change will to US Dollars. Once Unified
Margin trading is enabled, all balances reported by the
my-account-overview
WS channel andaccount-overview
HTTP endpoint will be in units of US Dollars. The same applies for the insurance fund.
The documentation below describes the API as it will function post-Unified Margin launch. The following endpoints will be affected:
HTTP API:
- Get Ticker
- Get Ticker Contracts
- Get Ticker Orderbook
- Get Trades
- Get Positions
- Get Account Overview
Websocket API:
- Market Depth
- Product Detail
- Recent Trades
- Market Overview
- Price History
- Insurance Fund
- My Market Events
- Place Order
- My Orders
- My Positions
Please carefully review the changes to these endpoints and any other changes below.
Differences between Spot and Derivative markets
We have a unified API for both Spot and Derivatives trading, but there are a few differences.
You can hold a long or short position in our derivatives contracts, which you
can subscribe to using the my-positions
channel. For spot trading, you need
your balances, which can be retrieved using the my-balances
API. The response
for the product-details
channel See the HTTP API and Websocket API sections
for more information.
Types
Timestamps
Unless explicitly specified, all timestamps from API are returned in Unix Millisecond Timestamp. Make sure you can parse the Unix Millisecond Timestamp format. Most modern languages and libraries will handle this without issues.
Instruments
Instruments are the products that the exchange offers. for instrument parameters in the API you must specify the symbol. Examples are below:
Derivative Instruments
Instrument | Symbol |
---|---|
Bitcoin / US Dollar | XBTUSD |
Ethereum / US Dollar | ETHUSD |
Bitcoin Vix | VXBT |
Spot Instruments
Instrument | Symbol |
---|---|
Globe Derivative Token / Tether | GDT/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.
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
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 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. The maximum number of candles that can be retrieved in one request is 1000.
Response Items
Each candle is an object with the following fields:
- time candle start time
- open opening price (first trade) in the candle interval
- high highest price during the candle interval
- low lowest price during the candle interval
- close closing price (last trade) in the candle interval
- volume volume of trading activity during the candle interval
Get Historic Index Price Rates
curl "https://globedx.com/api/v1/history/index-price/XBTUSD/candles/1m"
The above command returns JSON structured like this:
[
{
"time": 1625055060000,
"open": 34918.0,
"high": 34988.5,
"low": 34918.0,
"close": 34988.5,
"volume": 342420
},
{
"time": 1625055000000,
"open": 34911.0,
"high": 34918.0,
"low": 34903.0,
"close": 34918.0,
"volume": 613723
}
]
Historic index price rates for a product. Rates are returned in grouped buckets based on requested resolution.
HTTP Request
GET /api/v1/history/index-price/<instrument>/candles/<resolution>
Parameters
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
curl "https://globedx.com/api/v1/orders/open-orders" <authentication headers>
Response:
[
{
"type": "order",
"filled_quantity": 0,
"order_id": "3fe0a762-0b53-4eda-ba93-c391427871ff",
"order_type": "limit",
"price": 59000.0,
"quantity": 10000.0,
"side": "buy",
"timestamp": 1617212555193
}
]
Your open orders for an product.
HTTP Request
GET /api/v1/orders/open-orders
Parameters
Parameter Name | Required | Description |
---|---|---|
instrument | Yes | Globe product ticker (e.g. XBTUSD) |
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
orsell
- timestamp Unix Millisecond Timestamp when limit order was submitted
Get Ticker
curl "https://globedx.com/api/v1/ticker"
Response:
{
"product_type": "Perpetual",
"name": "Bitcoin/USD Perpetual",
"instrument": "XBTUSD",
"best_bid": {
"price": 39076.0,
"volume": 707.0
},
"best_ask": {
"price": 39078.0,
"volume": 30888.0
},
"volume": 5517441.0,
"quote_volume": 5517441.0,
"base_volume": 5517441.0,
"price_change_percent": 0.5,
"funding_rate": 0.023,
"mark_price": 35000.78,
"index_price": 35010.12,
"contract_price_currency": "USD",
"contract_price": 1.0,
"contract_type": "Inverse"
}
Ticker data for a specified instrument.
HTTP Request
GET /api/v1/ticker
Parameters
Parameter Name | Required | Description |
---|---|---|
instrument | Yes | Globe product ticker (e.g. XBTUSD) |
Response Items
The response is different for spot and perpetual products. For spot products response items, see Get Ticker Pairs. For perpetual products response items, see Get Ticker Contracts.
Get Ticker Contracts
curl "https://globedx.com/api/v1/ticker/contracts"
Response:
[
{
"product_type": "Perpetual",
"name": "Bitcoin/USD Perpetual",
"instrument": "XBTUSD",
"best_bid": {
"price": 39076.0,
"volume": 707.0
},
"best_ask": {
"price": 39078.0,
"volume": 30888.0
},
"volume": 5517441.0,
"quote_volume": 5517441.0,
"base_volume": 5517441.0,
"price_change_percent": 0.5,
"funding_rate": 0.023,
"mark_price": 35000.78,
"index_price": 35010.12,
"contract_price_currency": "USD",
"contract_price": 1.0,
"contract_type": "Inverse"
},
{
"product_type": "Perpetual",
"name": "Ethereum/USD Perpetual",
"instrument": "ETHUSD",
"best_bid": {
"price": 2000.0,
"volume": 707.0
},
"best_ask": {
"price": 2010.0,
"volume": 30888.0
},
"volume": 5517441.0,
"quote_volume": 5517441.0,
"base_volume": 5517441.0,
"price_change_percent": 0.5,
"funding_rate": 0.023,
"mark_price": 2005.78,
"index_price": 2000.12,
"contract_price_currency": "USD",
"contract_price": 1.0,
"contract_type": "Inverse"
}
]
Ticker contracts for all instruments in an array.
HTTP Request
GET /api/v1/ticker/contracts
Parameters
No parameters needed
Response Items
Each ticker is an object with the following fields:
- product_type Instrument type (Perpetual or Spot)
- name Product name
- instrument Globe product instrument
- best_bid Best bid level object with price and market size
- best_ask Best ask level object with price and market size
- base_volume Total amount traded over the last 24 hours, in base currency
- quote_volume Total amount traded over the last 24 hours, in quote currency
- volume Same as quote_volume, used for backwards-compatibility
- price_change_percent Percentage change of the price over the last 24 hours
- funding_rate Current funding rate percentage
- mark_price Current mark price
- index_price Current index price
- contract_price_currency Currency of the contract price field
- contract_price The amount a single contract is worth
- contract_type The type of contract: Inverse, Quanto or Vanilla
Get Ticker Pairs
curl "https://globedx.com/api/v1/ticker/pairs"
Response:
[
{
"product_type": "spot",
"name": "Globe Derivative Token / Tether",
"instrument": "GDT/USDT",
"best_bid": {
"price": 0.2096,
"volume": 44244498248.0
},
"best_ask": {
"price": 0.2098,
"volume": 99106486052.0
},
"volume": 500000000.0,
"quote_volume": 500000000.0,
"base_volume": 104800000.0,
"price_change_percent": 2.9513034923757995,
"mid_market_price": 0.2097,
"last_trade_price": 0.2093
},
{
"product_type": "spot",
"name": "Bitcoin / Tether",
"instrument": "BTC/USDT",
"best_bid": {
"price": 40920.24,
"volume": 1049139.0
},
"best_ask": {
"price": 41026.78,
"volume": 443822.0
},
"volume": 0.0,
"quote_volume": 0.0,
"base_volume": 13.7,
"price_change_percent": 0,
"mid_market_price": 40973.51,
"last_trade_price": 41569.78
}
]
Ticker data for all spot pairs.
HTTP Request
GET /api/v1/ticker/pairs
Parameters
No parameters needed
Response Items
Each ticker is an object with the following fields:
- product_type Instrument type (Perpetual or Spot)
- name Product name
- instrument Globe product instrument
- best_bid Best bid level object with price and market size
- best_ask Best ask level object with price and market size
- base_volume Total amount traded over the last 24 hours, in base currency
- quote_volume Total amount traded over the last 24 hours, in quote currency
- volume Same as quote_volume, used for backwards-compatibility
- price_change_percent Percentage change of the price over the last 24 hours
- index_price Current index price
- last_trade_price Last trade price
Get Ticker Orderbook
curl "https://globedx.com/api/v1/ticker/orderbook"
Response:
{
"bids": [[34772.0, 18327.0]],
"asks": [[34776.5, 14102.0]]
}
The top 25 bid and ask levels of the order book for the ticker instrument.
HTTP Request
GET /api/v1/ticker/orderbook
Parameters
Parameter Name | Required | Description |
---|---|---|
instrument | Yes | Globe product ticker (e.g. XBTUSD) |
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 ) |
Get Trades
curl "https://globedx.com/api/v1/history/my-trades?instrument=XBTUSD&page=1" <authentication headers>
Response:
[
{
"price": 59000.0,
"quantity": 10000.0,
"role": "maker",
"side": "buy",
"timestamp": 1617212555193,
"trade_no": "8157636791"
}
]
Your executed trades for an product.
HTTP Request
GET /api/v1/history/my-trades?instrument=<instrument>&page=<page_no>
Parameters
Parameter Name | Required | Description |
---|---|---|
instrument | Yes | Globe product ticker (e.g. XBTUSD) |
page_no | No | page_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:
- price price at which the order traded
- quantity trade size
- side side of the trade, either
buy
orsell
- timestamp Unix Millisecond Timestamp when the trade occurred
Get Positions (Derivatives)
curl "https://globedx.com/api/v1/positions" <authentication headers>
Response:
{
"UNIUSD": {
"quantity": 10.0,
"avg_price": 22.906,
"cost": 0.0003054,
"long_open_contracts": 0,
"short_open_contracts": 0
},
"XBTUSD": {
"quantity": 10000.0,
"avg_price": 32732.5,
"cost": 0.0000229,
"long_open_contracts": 0,
"short_open_contracts": 0
}
}
Your current active positions.
HTTP Request
GET /api/v1/positions
Details
Note that to use this endpoint you need to pass the authentication headers, see authentication.
Response Items
Object response, with each position accessed by the symbol key for that product. Each position has the following fields:
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
curl "https://globedx.com/api/v1/spot/balances" <authentication headers>
Response:
{
"GDT": {
"reserved": 0.0,
"available": 1.0,
"total": 1.0,
"reserved_usd": 0.0,
"available_usd": 0.3,
"total_usd": 0.3
},
"USDT": {
"reserved": 0.0,
"available": 1000.0,
"total": 1000.0,
"reserved_usd": 0.0,
"available_usd": 1000.0,
"total_usd": 1000.0
}
}
Balances for each coin in your spot account.
HTTP Request
GET /api/v1/spot/balances
Details
Note that to use this endpoint you need to pass the authentication headers. See authentication.
Response Items
Each balance object has the following fields:
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
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:
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 |
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:
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
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:
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” |
WebSocket Public Channels
Public channels do not require authentication.
Index Price
Subscription message:
{
"command": "subscribe",
"channel": "index-price",
"instrument": "XBTUSD"
}
Example response:
{
"subscription": {
"channel": "index-price",
"instrument": "XBTUSD"
},
"data": {
"price": 32000.0
}
}
Get the current index price for a particular instrument.
Arguments
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
Subscription message:
{
"command": "subscribe",
"channel": "depth",
"instrument": "XBTUSD"
}
Example response:
{
"subscription": {
"channel": "depth",
"instrument": "XBTUSD"
},
"data": {
"bids": [
{
"price": 34772.0,
"volume": 18327.0
}
],
"asks": [
{
"price": 34776.5,
"volume": 14102.0
}
]
}
}
The top 25 bid and ask levels of the order book for the given instrument. Updates are sent at a fixed frequency of twice a second and not necessarily for every change.
Response
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
Subscription message:
{
"command": "subscribe",
"channel": "product-list"
}
Example response:
{
"subscription": {
"channel": "product-list"
},
"data": [
{
"name": "Globe Derivative Token / Tether",
"symbol": "GDT/USDT",
"base_symbol": "GDT",
"quote_symbol": "USDT",
"category": "Spot"
},
{
"name": "Bitcoin/USD",
"symbol": "XBTUSD",
"base_symbol": "USD",
"quote_symbol": "USD",
"category": "Perp"
},
{
"name": "Ethereum/USD",
"symbol": "ETHUSD",
"base_symbol": "USD",
"quote_symbol": "USD",
"category": "Perp"
},
{
"name": "Bitcoin Vix",
"symbol": "VXBT",
"base_symbol": "USD",
"quote_symbol": "USD",
"category": "Perp"
},
{
"name": "Uni/USD",
"symbol": "UNIUSD",
"base_symbol": "USD",
"quote_symbol": "USD",
"category": "Perp"
},
{
"name": "Doge/USD",
"symbol": "DOGEUSD",
"base_symbol": "USD",
"quote_symbol": "USD",
"category": "Perp"
}
]
}
A list of all available products, including the instrument symbol, base symbol, quote symbol, and display name.
Response
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
Subscription message:
{
"command": "subscribe",
"channel": "product-detail",
"instrument": "XBTUSD"
}
Example response for a perpetual product:
{
"subscription": {
"channel": "product-detail",
"instrument": "XBTUSD"
},
"data": {
"base_symbol": "BTC",
"category": "Perp",
"contract_size": 1.0,
"contract_type": "Inverse",
"funding_period": 28800,
"maker_fee": 0.0025,
"max_leverage": 100,
"min_qty": 1.0,
"next_funding_time": 1564164110000,
"price_precision": 2,
"qty_increment": 1.0,
"qty_precision": 0,
"quote_symbol": "USD",
"taker_fee": 0.0075,
"tick_size": 500.0
}
}
Example response for a spot product:
{
"subscription": {
"channel": "product-detail",
"instrument": "GDT/USDT"
},
"data": {
"maker_fee": 0.0,
"taker_fee": 0.0075,
"tick_size": 1.0,
"category": "Spot",
"price_precision": 2,
"qty_precision": 8,
"base_symbol": "USD",
"quote_symbol": "USD"
}
}
Full information about a product, including contract and funding information, fees and tick sizes.
Response
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 |
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) |
Recent Trades
Subscription message:
{
"command": "subscribe",
"channel": "trades",
"instrument": "XBTUSD"
}
Example response:
{
"subscription": {
"channel": "trades",
"instrument": "XBTUSD"
},
"data": [
{
"price": 34630.5,
"quantity": 22806.0,
"side": "sell",
"timestamp": 1617119257074
},
{
"price": 34632,
"quantity": 4677.0,
"side": "sell",
"timestamp": 1617119257073
},
{
"price": 34632,
"quantity": 1870.0,
"side": "sell",
"timestamp": 1617119257072
}
]
}
The 100 most recent trades, including the price, side and quantity. Updates are sent at a fixed frequency of twice a second and not necessarily for every trade.
Upon the first subscription the 100 most recent trades will be sent as a snapshot followed by delta updates of new recent orders if there are any.
Response
Field | Description |
---|---|
price | Price of order |
quantity | Amount traded |
side | Side type, can be either sell or buy |
timestamp | Timestamp of the order in milliseconds |
Market Overview
Subscription message:
{
"command": "subscribe",
"channel": "market-overview",
"instrument": "XBTUSD"
}
Example response for a perpetuals product:
{
"subscription": {
"channel": "market-overview",
"instrument": "XBTUSD"
},
"data": {
"price_change_percent": -1.83,
"volume": 408523.0,
"mid_market_price": 34910.13,
"last_trade_price": 34911.37,
"funding_rate": 0.003,
"mark_price": 34908.07,
"index_price": 34978.38
}
}
Example response for a spot product:
{
"subscription": {
"channel": "market-overview",
"instrument": "BTC/USDT"
},
"data": {
"price_change_percent": -1.83,
"volume": 408523.0,
"mid_market_price": 34910.13,
"last_trade_price": 34911.37
}
}
Summary statistics for the daily market activity for the requested requested instrument, including percentage price change, total volume traded over the preceding 24 hours, current funding rate percentage, mark price and index price. Each response message will contain at least one field.
Response
Field | Description |
---|---|
price_change_percent | Percentage change of the price over the last 24 hours |
volume | Total amount traded over the last 24 hours |
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
Subscription message:
{
"command": "subscribe",
"channel": "price-history",
"instrument": "XBTUSD",
"resolution": "5m"
}
Example response:
{
"subscription": {
"channel": "price-history",
"instrument": "XBTUSD",
"resolution": "5m",
"index": false
},
"data": {
"high": 34864,
"low": 34765.5,
"open": 34831.5,
"close": 34755.5,
"time": 1625049000000,
"volume": 177600.0
}
}
Subscribe to receive the latest price olhc candle for a given resolution.
The index
boolean field is optional and false
by default, and if true
the
index price ohlcv updates will be returned as an additional object, otherwise
only the instrument price ohlcv updates will be returned.
Response
Field | Description |
---|---|
num_contracts | Current number of contracts open in an instrument market |
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
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
Field | Description |
---|---|
num_contracts | Current number of contracts open for a derivatives product |
Insurance Fund
Subscription message:
{
"command": "subscribe",
"channel": "insurance-fund"
}
Example response:
{
"subscription": {
"channel": "insurance-fund"
},
"data": {
"balance": 0.5
}
}
Current insurance fund balance in Bitcoin (pre-unified margin) or USD (post-unified margin).
Response
Field | Description |
---|---|
balance | Current insurance fund balance |
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
Event | Description |
---|---|
order-received | Order was received |
order-added | Order was added to the book |
cancelled | Order was cancelled |
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": "XBTUSD"
},
"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": "XBTUSD"
},
"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": "XBTUSD"
},
"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 ) |
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
Field | Description |
---|---|
event | Event type, i.e. rejected |
reason | Reason for rejection |
timestamp | Timestamp time of event |
Traded Event response
{
"subscription": {
"channel": "my-market-events",
"instrument": "XBTUSD"
},
"data": {
"event": "traded",
"price": 54284.5,
"quantity": 12000.0,
"side": "buy",
"order_id": "36f9b461-9335-4df3-a3ec-fdcecd9df318",
"timestamp": 1593000000000,
"role": "taker",
"trade_no": "8157636791"
}
}
Traded Event response
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 |
liquidation | If the trade occured due to a liquidation (field ommitted if false ) |
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
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": "XBTUSD"
},
"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
Input message:
{
"command": "place-order",
"instrument": "XBTUSD",
"price": 34950.0,
"quantity": 0.6,
"order_type": "limit",
"side": "sell",
"reduce_only": false,
"order_id": "1279a5ef-ceca-423a-9eb9-caee5e3d85d0"
}
{
"command": "place-order",
"instrument": "XBTUSD",
"quantity": 1.14,
"order_type": "market",
"side": "buy",
"reduce_only": false,
"order_id": "1279a5ef-ceca-423a-9eb9-caee5e3d85d0"
}
Place an order for a particular instrument.
Note that you do not get a confirmation of the order on this channel. Instead,
subscribe to the my market events channel to get the
order-received
event.
Arguments
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 |
Cancel Order
Input message:
{
"command": "cancel-order",
"instrument": "XBTUSD",
"order_id": "1279a5ef-ceca-423a-9eb9-caee5e3d85d0",
"cancel_id": "c66ce3ec-cf26-4673-a8ac-58a3b2fc3384",
"new_quantity": 0.02
}
Place a request to cancel an order with given order_id
.
Arguments
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
Input message:
{
"command": "cancel-all-orders",
"instrument": "XBTUSD",
"cancel_id": "c66ce3ec-cf26-4673-a8ac-58a3b2fc3384",
"side": "buy"
}
Place a request to cancel all orders for a given instrument
.
Arguments
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
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
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
Subscription message:
{
"command": "subscribe",
"channel": "my-orders",
"instrument": "XBTUSD"
}
Example response:
{
"subscription": {
"channel": "my-orders",
"instrument": "XBTUSD"
},
"data": {
"79361d02-3f1d-4892-943a-3460f3e457d1": {
"type": "order",
"price": 50000.0,
"quantity": 2.47,
"filled_quantity": 1.11,
"order_type": "limit",
"side": "buy",
"timestamp": 1593000000000,
"order_id": "79361d02-3f1d-4892-943a-3460f3e457d1"
},
"0368315e-be48-4dcc-aaa2-0c30403c48ff": {
"type": "order",
"price": 47000.0,
"quantity": 1.645,
"filled_quantity": 0.688,
"order_type": "limit",
"side": "sell",
"timestamp": 1593000010000,
"order_id": "0368315e-be48-4dcc-aaa2-0c30403c48ff"
}
}
}
Receive a map of your open orders for a given instrument, with the order ID as the key. Responses are sent on subscription and on orders change.
My Open Orders response
Field | Description |
---|---|
type | order , stop or take-profit |
price | Price at which the order is to be executed |
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 |
My Account Overview (Derivatives)
Subscription message:
{
"command": "subscribe",
"channel": "my-account-overview"
}
Subscribe to account overview messages, responses are periodically every second.
My Account Overview response
{
"subscription": {
"channel": "my-account-overview"
},
"data": {
"available_balance": 80.0,
"account_balance": 100.0,
"unrealized_pnl": 5.0,
"maintenance_margin": 10.0,
"initial_margin": 20.0,
"margin_balance": 105.0,
"liquidation_in_progress": false
}
}
If your margin balance falls below maintenance margin requirements, you can only place orders that reduce your position.
My Account Overview response
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 |
My Positions (Derivatives)
Subscription message:
{
"command": "subscribe",
"channel": "my-positions"
}
Subscribe to your positions, messages are sent on every change to your position.
My Positions response
{
"subscription": {
"channel": "my-positions"
},
"data": {
"XBTUSD": {
"quantity": 10.0,
"avg_price": 30572.0,
"cost": 11.0,
"long_open_contracts": 42,
"short_open_contracts": 69
}
}
}
My Positions response
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 |
Request your open orders for a given instrument.
My Balances (Spot)
Subscription message:
{
"command": "subscribe",
"channel": "my-balances"
}
Subscribe to balance messages. Updates are sent upon every change.
My Balances response
{
"subscription": {
"channel": "my-balances"
},
"data": {
"balances": {
"GDT": {
"reserved": 0,
"available": 1,
"total": 1,
"reserved_usd": 0.0,
"available_usd": 0.3,
"total_usd": 0.3
},
"USDT": {
"reserved": 0,
"available": 1000,
"total": 1000,
"reserved_usd": 0.0,
"available_usd": 1000.0,
"total_usd": 1000.0
}
}
}
}
My Balances response
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 (Unified Margin - Coming Soon)
Subscription message:
{
"command": "subscribe",
"channel": "my-margin-account-overview"
}
Subscribe to margin account overview messages. A response is sent on subscribe and on change.
My Margin Account Overview response
{
"subscription": {
"channel": "my-margin-account-overview"
},
"data": {
"balances": {
"BTC": {
"allocated": 0.74,
"value": 57121.55,
"contribution": 42269.95,
"value_factor": 1.0
},
"USDT": {
"allocated": 3654.73,
"value": 3654.73,
"contribution": 3654.73,
"value_factor": 1.0
}
},
"collateral": 45924.68,
"profit": 1738.32
}
My Margin Account Overview response
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 balance and total collateral available |
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 Name | Endpoint URL | Description |
---|---|---|
Authentication | https://globedx.com/oauth2/auth | Initiate the oauth2 flow |
Token | https://globedx.com/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://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.
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://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.
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://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.