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:

  1. Construct the signing text, by concatenating the decimal string representation of the nonce with the verb of the http request, and the url, for example for a websocket request the verb would be GET and the endpoint would be /api/v1/ws". using the message to the right, this gives us "1587654321GET/api/v1/ws".

  2. Create an HMAC signature from the signing text, using a SHA-256 hashing function and the secret you were given when you created your API key.

  3. Base64-encode the HMAC signature.

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

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)

Get Trades

Your executed trades for an product.

curl "https://globe.exchange/api/v1/history/my-trades?instrument=BTC-PERP&page=1" <authentication headers>

Response:

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

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. BTC-PERP)
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 or sell
  • timestamp Unix Millisecond Timestamp when the trade occurred

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

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

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.

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

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.