Getting Started
Globitex API provides different ways to access exchange trading facilities from your own application. Each developer can choose most appropriate API type according to their needs, previous experience and knowledge.
Options:
- RESTful API – exchange functionality available as widely used web services.
- FIX API - the most efficient way to receive current market quotes and place orders via industry standard Financial Information eXchange (FIX) protocol.
- Streaming API – allows to improve web service efficiency for receiving market data using streaming functionality based on WebSocket and Socket.IO protocol.
RESTful API
Basic information
Service endpoints
Production environment:
Endpoint |
Description |
https://api.globitex.com | Service endpoint for RESTful API calls |
Currency symbols
The following currency symbols are traded on the exchange.
Symbol | Price step | Minimum order size | Order size increment |
BTCEUR | 0.01 | 0.002 | 0.00000001 |
The actual list of symbols can be obtained by /api/1/public/symbols method.
Size representation:
- Quantity is represented in natural values (e.g. 1.00000001 for BTCEUR when representing 1 Bitcoin and 1 Satoshi)</li>
- Price is represented in natural values (e.g. 250.01 for BTCEUR)
Error messages
In case of error in client request processing, HTTP error code is returned. Additionally, JSON object containing error description can be returned.
Possible values for HTTP error codes:
HTTP status code | HTTP status code name | When returned |
400 | Bad Request | Client request data has errors |
403 | Forbidden | Missing required fields for signature check or problems with message signature |
404 | Not Found | Request is sent to invalid path |
500 | Internal Server Error | Unexpected server error occurred when processing client request |
Data structure for error description in JSON format:
Field | Required | Type | Description |
errors | Yes | array of object | Error message |
Data structure for errors object
Field | Required | Type | Description |
code | Yes | integer | Error code |
message | Yes | string | Error message |
data | No | string | Additional data about error |
Example responses:
Error codes
API method calls can return the following common errors with HTTP error codes:
HTTP error code | JSON Code | Message | Description |
403 | 10 | Missing API key | API key not exists in HTTP request header |
403 | 20 | Missing nonce | Nonce not exists in HTTP request header |
403 | 30 | Missing signature | Signature not exists in HTTP request header |
403 | 40 | Invalid API key | API key not found or have invalid format. |
403 | 50 | Nonce is not monotonous | Received nonce is smaller than in previous requests |
403 | 60 | Nonce is not valid | Too big number or not a number |
403 | 70 | Wrong signature | Specified signature is not correct |
403 | 80 | No permissions | API key has no permissions to call this method |
403 | 90 | API key is not enabled | Client have not enabled API key |
403 | 100 | API key locked | API key is locked on client action or on exchange side |
403 | 110 | Invalid client state | Client account is closed or is not approved |
403 | 120 | Invalid API key state | API key is deleted |
403 | 130 | Trading suspended | Trading for client is suspended |
403 | 140 | REST API suspended | Trading via REST API suspended |
400 | 200 | Mandatory parameter missing | At least one of the method mandatory parameters are missing |
Authentication
RESTful Trading and Payment API requires HMAC-SHA512 signatures for each request.
To use this API endpoint you should get your API key and Secret key from the web application Settings page.
Each request should include the following parameters in HTTP header:
Signature generation pseudo-code:
Javascript code (example):
Nexpay methods
RESTful API provides access to Nexpay data with the following methods:
- transfer funds to beneficiary account - /api/1/eurowallet/payments
- return account status information - /api/1/eurowallet/status
- return deposit information - /api/1/eurowallet/deposit-details
- return payment history - /api/1/eurowallet/payments/history
- return payment status - /api/1/eurowallet/payments/status
- get transfer commission amount - /api/1/eurowallet/payments/commission
Create new payment
Transfers funds to beneficiary account; returns a transaction ID or an error.
Request: POST /api/1/eurowallet/payments
Parameters:
The following fields are returned:
Error codes:
Code | Message |
30000 | Request error |
20000 | Invalid request time |
20010 | Beneficiary name too long |
20020 | Beneficiary name too short |
20030 | Reference information for beneficiary too long |
20040 | Invalid transaction signature |
-32600 | Bad request |
Example request:
Example response:
Signature generation pseudo-code:
Get Account Status
Returns default (single) or all account status information.
Request: GET /api/1/eurowallet/status
Parameters:
The following fields are returned:
Error codes:
Code | Message |
30000 | Request error |
-32600 | Bad request |
Example request:
Example response:
Get Deposit Details
Returns deposit information, such client full name with bank requisites.
Request: GET /api/1/eurowallet/deposit-details
Parameters: no parameters
The following fields are returned:
Error codes:
Code | Message |
30000 | Request error |
-32600 | Bad request |
Example request:
Example response:
Get Payment History
Returns payment history for provided account.
Request: GET /api/1/eurowallet/payments/history
Parameters:
The following fields are returned:
Payment entry structure:
Error codes:
Code | Message |
30000 | Request error |
30010 | Invalid request parameters |
-32600 | Bad request |
Example request:
Example response:
Get Payment Status
Returns payment status information.
Request: GET /api/1/eurowallet/payments/status
Parameters:
The following fields are returned:
Error codes:
Code | Message |
30000 | Request error |
20000 | paymentId or externalPaymentId parameters was not provided |
20010 | Both paymentId and externalPaymentId parameters was provided |
-32600 | Bad request |
Example request:
Example response:
Get Payment Commission Amount
Returns Payment Commission Amount
Request: GET /api/1/eurowallet/payments/commission
Parameters:
The following fields are returned:
Error codes:
Code | Message |
30000 | Request error |
-32600 | Bad request |
Example request:
Example response:
Market Data methods
RESTful API provides access to market data with the following methods:
- get the timestamp - /api/1/public/time
- get the list of instruments - /api/1/public/symbols
- get the ticker for specified instrument - /api/1/public/ticker/:symbol
- get all tickers - /api/1/public/ticker
- get the order book for specified instrument - /api/1/public/orderbook/:symbol
- get individual trades data for specified instrument - /api/1/public/trades/:symbol
- get recent trades for specified instrument - /api/1/public/trades/recent/:symbol
Get Time
Returns the server time in UNIX timestamp format. Precision – milliseconds. Request: GET /api/1/public/time
Example response:
Get Symbols
Returns the list of instruments traded on exchange with their characteristics:
Request: GET /api/1/public/symbols
The following fields are used in the response object:
Field | Description |
symbol | Instrument symbol |
priceIncrement | Order price minimum increment parameter |
sizeIncrement | Order size minimum increment parameter |
sizeMin | Minimum order size |
currency | Price currency for the instrument |
commodity | Base currency for the instrument |
Example response:
Get Ticker For Symbol
Returns the current data for the instrument.
Request: GET /api/1/public/ticker/:symbol where :symbol is an instrument symbol traded on the exchange
The following fields are used in the response object:
Field | Description |
symbol | Instrument symbol |
ask | Lowest sell order |
bid | Highest buy order |
last | Last trade price |
low | Lowest trade price per last 24h + last incomplete minute |
high | Highest trade price per last 24h + last incomplete minute |
open | Open price for instrument |
volume | Trade volume per last 24h + last incomplete minute |
volumeQuote | Trade volume in second currency per last 24h + last incomplete minute |
timestamp | Server time in UNIX timestamp format |
Error codes returned:
Code | Message | Data |
20000 | Invalid argument | Unknown symbol ABCBTC |
Example response:
Get Ticker
Returns the current data for all instruments traded on the exchange.
Request: GET /api/1/public/ticker
Example response:
Get Order Book for Symbol
Returns an array of open orders for the specified instrument. First value - price, second - size.
Request: GET /api/1/public/orderbook/:symbol where :symbol is an instrument symbol traded on exchange
Error codes returned:
Code | Message | Data |
20000 | Invalid argument | Unknown symbol ABCBTC |
Example response:
Get Trades for Symbol
Returns trade data for the specified instrument.
Request: GET /api/1/public/trades/:symbol where :symbol is an instrument symbol traded on exchange
Parameters:
Error codes returned:
Code | Message | Data |
20000 | Invalid argument | Unknown symbol BTCUSeD |
20100 | Invalid argument | Fields are not valid: [field name(s)] |
Example:
Example response:
Example:
Example response:
Get Recent Trades for Symbol
Returns recent trades for the specified instrument.
Request: /api/1/public/trades/recent/:symbol where :symbol is an instrument symbol traded on exchange
Parameters:
Error codes returned:
Code | Message | Data |
20000 | Invalid argument | Unknown symbol BTCEUR |
20010 | Resource not found | [invalid path] does not exist |
20100 | Invalid argument | Fields are not valid: [field name(s)] |
Example:
Example response:
Trading methods
RESTful API allows to perform trading operations with the following methods:
- get all active orders - /api/2/trading/active
- place a new order - /api/1/trading/new_order
- cancel an order - /api/2/trading/cancel_order
- cancel all orders - /api/1/trading/cancel_orders
- get user’s recent orders - /api/1/trading/recent
- get order state - /api/1/trading/order
- get user’s trading history - /api/1/trading/trades
Trading operations require authentication.
Error codes and reports representing order status changes are described below.
Execution Report
The API uses ExecutionReport as an object that represents change of order status.
The following fields are used in ExecutionReport object:
Example response:
Get Active Orders
Returns all orders in status new, partiallyFilled or suspended.
Request: GET /api/2/trading/orders/active
Parameters:
The following fields are used in order object:
Example response:
Place New Order
Place a new order. Returns a JSON object ExecutionReport that represent a status of the order.
Request: POST /api/1/trading/new_order
Parameters:
The following fields are used in ExecutionReport object:
Example:
Example response:
Cancel Order
Cancels an order. Returns ExecutionReport JSON object or CancelReject JSON object.
Request: POST /api/2/trading/cancel_order
Parameters:
The following fields are used in ExecutionReport object:
The following fields are used in CancelReject object:
Example:
Example response:
CancelReject response:
Cancel All Orders
Cancels all orders. Returns ExecutionReport array of JSON object.
Request: POST /api/1/trading/cancel_orders
Parameters:
The following fields are used in ExecutionReport object:
Example:
Example response:
Get Recent Orders
Returns an array of user’s recent orders (order objects) for the last 24 hours, sorted by order update time.
Request: GET /api/1/trading/orders/recent
Parameters:
The following fields are used in order object:
Example response:
Get Order State
Returns the state of order(s) if order(s) have been placed on the exchange.
Request: GET /api/1/trading/order
Parameters:
The following fields are used in order object:
Example response:
Get My Trades
Returns the trading history - an array of client’s trades (trade objects).
Request: GET /api/1/trading/trades
Parameters:
The following fields are used in trade object:
Example response:
Payment Data methods
RESTful API allows to query data using the following methods:
- Get information about created exchange accounts and their balance - /api/1/payment/accounts
- Initiates fund transfer between client own Globitex accounts - /api/1/payment/internal
- Initiate fund transfer to other beneficiary account in the exchange - /api/1/payment/payout/exchange
- Withdraw funds and create an outgoing crypotocurrency transaction - /api/1/payment/payout/crypto
- Withdraw funds and create an outgoing fiat money transaction to the exchange client’s bank account - /api/1/payment/payout/bank
- Get Bank Outgoing Transaction Fee - /api/1/payment/payout/fee/fiat
- Get Crypto Outgoing Transaction Fee - /api/1/payment/payout/fee/crypto
- Get Bank Deposit Details - /api/1/payment/deposit/fiat
- Get Cryptocurrency Deposit Address - /api/1/payment/deposit/crypto/address
- Create New Cryptocurrency Deposit Address - /api/1/payment/deposit/crypto/address
- Get a list of payment transactions - /api/1/payment/transactions
- Get GBX (Globitex Token) Utilization List - /api/1/gbx-utilization/list
Get Balance
Returns the list of client accounts and their balance.
Request: GET /api/1/payment/accounts
Parameters: no parameters
The following fields are returned:
Data structure for balance object:
Example response:
Internal Transfer
Initiates fund transfer between client own Globitex accounts.
Request: POST /api/1/payment/internal
Parameters:
The following fields are returned:
Example response:
Exchange Transfer
Withdraws funds from client account and transfers to other beneficiary account in the exchange.
Request: POST /api/1/payment/payout/exchange
Parameters:
The following fields are returned:
Example response:
Signature generation pseudo-code:
Create Cryptocurrency Transfer
Withdraws funds and creates an outgoing crypotocurrency transaction.
Request: POST /api/1/payment/payout/crypto
Parameters:
The following fields are returned:
Example response:
Signature generation pseudo-code:
Create Bank Transfer
Withdraw funds and creates an outgoing fiat money transaction to the exchange client’s bank account
Request: POST /api/1/payment/payout/bank
Parameters:
The following fields are returned:
Example response:
Signature generation pseudo-code:
Get Bank Transaction Fee
Returns bank outgoing transaction fee information based on provided parameters
Request: GET /api/1/payment/payout/fee/fiat
Parameters:
The following fields are returned:
Example response:
Get Crypto Transaction Fee
Returns cryptocurrency withdrawal (miner) fee based on the provided parameters.
Request: GET /api/1/payment/payout/fee/crypto
Parameters:
The following fields are returned:
Example response:
Get Bank Deposit Details
Returns bank deposit options based on currency and account.
Request: GET /api/1/payment/deposit/fiat
Parameters:
The following fields are returned:
Data structure for deposit options:
Data structure for payment type:
Data structure for bank:
Example response:
Get Cryptocurrency Deposit Address
Returns the previously created incoming cryptocurrency address that can be used to deposit cryptocurrency to your account.
Request: GET /api/1/payment/deposit/crypto/address
Parameters:
The following fields are returned:
Example response:
New Cryptocurrency Deposit Address
Creates an address that can be used to deposit cryptocurrency to your account. Note: for some currencies new address generation is disabled!
Request: POST /api/1/payment/deposit/crypto/address
Parameters:
The following fields are returned:
Example response:
Get Transaction List
Returns a list of payment transactions and their status (array of transactions).
Request: GET /api/1/payment/transactions
Parameters:
Response:
Data structure for transactions object:
Data structure for commission object:
Data structure for conversion object:
Field | Required | Type | Description |
rate | Yes | string | Currency conversion rate |
currency | Yes | string | Currency symbol, e.g. EUR, for converted funds |
amount | Yes | string | Incoming or outgoing currency amount before or after conversion depending on the transaction direction |
Data structure for depositor object:
Field | Required | Type | Description |
name | No | string | Name of the depositor |
bank | No | string | Depositor bank name |
swift | No | string | Depositor bank swift code |
account | No | string | Depositor account number |
Data structure for beneficiary object:
Field | Required | Type | Description |
name | No | string | Name of the beneficiary |
bank | No | string | Beneficiary bank name |
swift | No | string | Beneficiary bank swift code |
account | No | string | Beneficiary account number |
Data structure for intermediary object:
Field | Required | Type | Description |
bank | Yes | string | Intermediary bank name |
swift | Yes | string | Intermediary bank swift code |
account | Yes | string | Intermediary account number |
Example response:
Get GBX (Globitex Token) Utilization List
Returns a list of GBX utilization transactions (array of transactions).
Request: GET /api/1/gbx-utilization/list
Parameters:
Response:
Data structure for gbxUtilizationList object:
Data structure for discount object:
Example response:
FIX API
Basic information
- The FIX gateway is accessible with an OpenVPN connection.
- There are two interfaces: FIX Market data and FIX Trading.
- FIX Trading requires a valid SenderCompId , login and password specified in the Logon message.
- The protocol is based on FIX protocol 4.4 (http://www.fixtradingcommunity.org/FIXimate/FIXimate3.0/). Refer to FIX 4.4 documentation if there is no tag information specified.
- The FIX gateway supports subset of messages and tags listed in this document.
- Quantity is represented in lots (e.g. 10000001 for BTCEUR when representing 1 bitcoin and 1 satoshi).
- Price is represented in natural value (e.g. 2500.01 for BTCEUR).
Symbols
Document usage
- All tags listed should be treated as required by default. Optional tags will be marked.
- Tags that are not listed are not supported
- Tags are implemented according to FIX protocol 4.4 (http://www.fixtradingcommunity.org/FIXimate/FIXimate3.0/). If some values are not supported the complete list of values is specified.
End points
There are two FIX end-points that use different network addresses (ipv4:port):
- FIX Trading end-point: interface for trading (placing new orders, order status requests, execution reports, order cancellation)
- FIX Market data end-point: interface for market data subscription
Client should use proper endpoint. Behavior in case of receiving wrong message is not specified. Client could possibly be disconnected or receive Reject messages in case of using an incorrect endpoint.
Disaster scenarios
In case of severe fault the FIX session could be forcibly reset. In this case Client will receive ResetSeqNo flag from server and should synchronize its state by MassStatusRequest.
Effective time
There are restrictions on internal order placement timeouts. In case of fault Client will receive Reject with the specific reason “Too late to enter”
Order statuses
There are two pseudo-states that could be returned only by sending OrderStatusRequest or OrderMassStatusRequest:
- Pending New
- Pending Cancel.
Please note:
- First ExecutionReport will be New or Rejected
- Not-filled FOK and IOC orders become Expired
Consider the following diagram:
Session layer
FIX session has no persistence.
Supported messages
FIX Trading
Supports the following application-level messages:
From Client to FIX gateway:
- NewOrderSingle [type ‘D’]
- OrderCancelRequest [type ‘F’]
- OrderStatusRequest [type ‘H’]
- OrderMassStatusRequest [type ‘AF’]
From FIX gateway to Client:
Client will receive ExecutionReports for orders that are placed with the same SenderCompID.
FIX Market data
Supports the following application-level messages:
From Client to FIX gateway:
From FIX gateway to Client:
Message Formats
StandardHeader
StandardTrailer
Tag | Name | Values | Comments |
10 | CheckSum |
Heartbeat [type '0']
Tag | Name | Values | Comments |
112 | TestReqID | this Heartbeat is a response to TestRequest |
TestRequest [type '0']
Tag | Name | Values | Comments |
112 | TestReqID |
ResendRequest [type '2']
Tag | Name | Values | Comments |
7 | BeginSeqNo | ||
16 | EndSeqNo |
Reject [type '3']
Tag | Name | Values | Comments |
45 | RefSeqNum | ||
371 | RefTagID | ||
58 | Text | optional |
SequenceReset [type '4']
Tag | Name | Values | Comments |
123 | GapFillFlag | N (default), Y | |
371 | RefTagID | ||
123 | GapFillFlag | ||
36 | NewSeqNo |
Logout [type '5']
Tag | Name | Values | Comments |
58 | Text | optional | could contain a reason for server-initiated logout |
Logon [type 'A']
Instrument block
Tag | Name | Values | Comments |
55 | Symbol | e.g. "BTCEUR” |
MarketDataRequestReject [type 'Y']
MarketDataSnapshotFullRefresh [type 'W']
MarketDataIncrementalRefresh [type 'X']
MarketDataRequest [type 'V']
Subscribe:
Unsubscribe:
ExecutionReport [type '8']
NewOrderSingle [type 'D']
OrderCancelReject [type '9']
OrderCancelRequest [type 'F']
OrderStatusRequest [type 'H']
Behavior:
- Server sends order status as ExecutionReport
- Account and Side are required
- If order is not found the server doesn’t send any response.
OrderMassStatusRequest [type 'AF']
Streaming API
Market data Streaming API based on WebSocket protocol
Market data streaming URL: wss://stream.globitex.com/market-data
Streaming API provides an access to market data. Streaming API is based on WebSocket protocol. All messages are in JSON format.
Useful links:
- chrome extension Simple WebSocket Client - https://chrome.google.com/webstore/detail/simple-websocket-client/pfdhoblngboilpfeibdedpjgfnlcodoo
Basic information
Once client connects to WebSocket endpoint the session is started.
The server broadcasts the following types of messages:
- MarketDataSnapshotFullRefresh message contains a full snapshot of the order book.
- MarketDataIncrementalRefresh message contains incremental changes
Some recommendations to consider:
- The application could receive the first snapshot and maintain the order book by applying incremental updates.
- It’s recommended to invalidate a state of the application periodically using full snapshots.
- It’s recommended to check sequence numbers and to drop updates with non-monotonous sequence numbers.
MarketDataSnapshotFullRefresh message
Summary: contains a full snapshot of the order book.
The following fields are used in MarketDataSnapshotFullRefresh object:
Field | Description |
snapshotSeqNo | Last price change sequence number included in this market data snapshot. Each symbol has its own sequence |
timestamp | UTC timestamp for market data snapshot, in milliseconds |
symbol | Symbol of instrument traded on exchange |
exchangeStatus | Exchange status: "working" - trading is open; "suspended" - trading is suspended |
ask, bid | Sorted arrays of price levels in the order book. For full snapshot all price levels are provided |
Example message:
MarketDataIncrementalRefresh message
Summary: contains incremental changes of the order book and individual trades.
The following fields are used in MarketDataIncrementalRefresh object:
Field | Description |
seqNo | Monotone increasing number of the snapshot, each symbol has its own sequence |
timestamp | UTC timestamp for market data snapshot, in milliseconds |
symbol | Symbol of Instrument traded on exchange |
exchangeStatus | Exchange status: "working" - trading is open; "suspended" - trading is suspended |
ask, bid | An array of changes in the order book where price is a price, size is new size. size=0 means that the price level has been removed |
trade | Trade data object |
trade->price | Price for the trade |
trade->size | Size of the trade |
trade->tradeId | Trade identifier on the exchange |
trade->timestamp | UTC timestamp for the trade, in milliseconds |
trade->side | Side of the "taker" order |
Example message:
Market Data Streaming API based on Socket.IO protocol
The API provides Socket.IO version 1.0.x protocol for receiving market data. It supports:
- WebSocket and xhr-polling transport</li>
- multiplexing a single connection with Socket.IO namespaces (see namespaces below)
Event data is returned in JSON format.
Socket.IO URL base: https://stream.globitex.com:8080
Trades namespace
Namespace: trades
URL: /trades/:symbol e.g. /trades/BTCEUR
Event: trade
The following fields are used in trade object:
Field | Required | Type | Description |
amount | Yes | decimal as string | Trade amount |
price | Yes | decimal as string | Trade price |
Event example:
Ticker namespace
Namespace: ticker
To receive events for all instruments:
URL: /ticker
To receive events fro specific instrument:
URL: /ticker/:symbol e.g. /ticker/BTCEUR
Event: ticker
The following fields are used in trade object:
Useful links:
- official Socket.IO documentation - http://socket.io/
Event example: