Apifiny One Note

The base URL for the following API is: https://api.apifiny.com/gx/openApi/v1
ALL API messages are in the JSON format.
All time and timestamps are UNIX epoch time, in milliseconds.

Quick Start

Apply for an account and get accountID, API_Key_ID and API_Secret_Key
Use JWT to sign every request.
Send new orders or a new order through order.insertOrder
Use Websocket client to get order status.
The {VENUE} refers to exchange name. For example: GBBO, VENUE2. Please replace it with the real name of the exchange when coding. The list of real exchange names has been summarized on "Base Info API - Query List Venues".

Make Request

HTTP:

POST /gx/openApi/v1 HTTP/1.1
Host: api.apifiny.com
Content-Type: application/json
cache-control: no-cache
{
    "accountId": "ST-00000001"
}

Use HTTP POST to make a request:

POST https://api.apifiny.com/gx/openApi/v1?signature={signature}

The request end point is embedded in the signature.

Signature

Signature:

// js
signature = JWT(payload={
    "accountId": "accountID",
    "secretKeyId": "API_Key_ID",
    "digest": hash256(RequestBody),
    "method": "module.methodName",
    "exp": 1535526941
}, key='API_Secret_Key', algorithm='HS256')

# python3
import hashlib
import jwt
import json

digest = hashlib.sha256(json.dumps(RequestBody).encode()).hexdigest()
signature = jwt.encode({
    'accountId': "accountID",
    'secretKeyId': "API_Key_ID",
    'digest': digest,
    'method': "module.methodName",
    'exp': 1535526941,
}, "API_Secret_Key", algorithm='HS256')

Please use JWT to generate Signature for each request. Please refer to jwt.io on how to use JWT.

For every request, please use JWT and secretKey to generate Signature and use Signature in HTTP post parameter.

Payload in Signature includes the following content:

Parameter	Description
accountId	Account ID
secretKeyId	API Access Key
key	API Secret Key
digest	hash value of the request body using sha256 hash
method	api method
exp	expiration time of signature

Standard response

The structure of the response:

{
  "result": null,
  "error": {
    "code": 131114,
    "message": "account not found"
  }
}

After making an API request, the server will send back a response in JSON format. The response includes:

Parameter	Description
result	when the request is successful, this key will include the result of the request. When the request is not successful, its value is null.
error	when the request is not successful, the key will give the error message. Its value is null when the request is successful.
code	Error code. Please refer to the error code explanation section.
message	Error message.

Rate Limits

When a rate limit is exceeded, an error message "rate limit is exceeded" will be returned. If exceeded, please reduce frequency.

We throttle all endpoints requests(query included) by Account ID, 20 requests per second.

The rate limit is applied on Account ID basis, which means, the overall access rate, from all API keys under same Account ID.

Trading API

Note：The response in the following API is the result part of the standard response.

Create New Order

Request: (limit order)

{
  "accountId": "ST-00000001",
  "venue":"GBBO",
  "orderId": "000000011584603011942221",
  "orderInfo": {
    "symbol": "BTCUSDT",
    "orderType": "LIMIT",
    "timeInForce": 1,
    "orderSide": "BUY",
    "limitPrice": "100",
    "quantity": "1.12"
  }
}

Request: (market buy order)

{
  "accountId": "ST-00000001",
  "venue":"GBBO",
  "orderId": "000000011584603011942221",
  "orderInfo": {
    "symbol": "BTCUSDT",
    "orderType": "MARKET",
    "orderSide": "BUY",
    "total": "1000"
  }
}

Response:

{
  "accountId": "ST-GBBO_00000001",
  "venue":"GBBO",
  "orderId": "000000011584603011942221",
  "symbol": "BTCUSDT",
  "orderType": "MARKET",
  "orderSide": "BUY",
  "limitPrice": 0,
  "quantity": 0,
  "total": 1000,
  "filledAveragePrice": 0,
  "filledCumulativeQuantity": 0,
  "openQuantity": 1.12,
  "orderStatus": "PENDING_SUBMIT",
  "createdAt": 1584603012164,
  "updatedAt":  1584603012164,
  "cancelledUpdatedAt": null,
  "filledUpdatedAt": null
}

Make a new order request：

Method:

method: order.insertOrderLite

Request:

Parameter	Description
accountId	account ID
venue	GBBO
orderId	order ID
symbol	symbol
orderType	order type
timeInForce	specifies how long the order remains in effect
orderSide	order side
limitPrice	limit price
quantity	quantity
total	Amount of quote asset to spend, Required when orderSide is BUY, orderType = MARKET

Order ID needs to be in the following format: account id plus 13 digit of timestamp + 3 digit of random number.

Response:

Parameter	Description
accountId	sub account ID
venue	GBBO
orderId	order ID
symbol	symbol
orderType	order type
orderSide	order side
limitPrice	limit price
quantity	quantity
total	Amount to spend
filledAveragePrice	average fill price
filledCumulativeQuantity	accumulated fill quantity
openQuantity	open quantity to be filled
orderStatus	order status
createdAt	order creation timestamp
updatedAt	order update timestamp
cancelledUpdatedAt	if it is cancelled, cancellation timestamp
filledUpdatedAt	last filled timestamp

Order Type:

Order Type	Description
LIMIT	Limit Order
MARKET	Market Order
MAKER	Maker Only Order
TAKER	Taker Only Order

Time In Force:

Time In Force	Description
1	GTC (Good Till Canceled Order)
2	GTD (Good Till Date Order), temporarily not supported
3	IOC (Immediate Or Cancel Order)

Order Side:

Order Side	Description
BUY	buy order
SELL	sell order

Order Status:

Order Status	Explanation
PENDING_SUBMIT	order has been sent but not confirmed
SUBMITTED	and has been accepted and acknowledged or partially filled
FILLED	completely filled
CANCELLED	order is cancelled
REJECTED	order is rejected

Cancel Order

Request:

{
  "accountId": "ST-00000001",
  "venue":"GBBO",
  "orderId": "000000011584603011942221"
}

Response:

{
  //Same as new order response
}

Request Cancel Order，cancelledUpdatedAt in Order will be updated.

Note：Order can only be cancelled when order status is not PENDING_SUBMIT，and cancelledUpdatedAt is null.

Method:

method: order.cancelOrderLite

Request:

Parameter	Description
accountId	Account ID
venue	GBBO
orderId	Order ID

Response:

Same as new order response.

Query Single Order Info

Request:

{
  "accountId": "ST-00000001",
  "venue":"GBBO",
  "orderId": "000000011584603011942221"
}

Response:

{
  //Same as new order response
}

Method:

method: order.queryOrderInfoLite

Request:

Parameter	Description
accountId	account ID
venue	GBBO
orderId	order ID

Response:

Same as new order response.

Query Multiple Order Info

Request:

{
  "accountId": "ST-0000001",
  "orderIdList": ["000000121574697605570321","000000121574697754664817"]
}

Response:

[
  {
     //Same as new order response
  }，
  {
     //Same as new order response
  }
]

Method:

method: order.listOrderInfoLite

Request:

Parameter	Description
accountId	account ID
orderIdList	the total number of order ID cannot exceed 500

Response:

Same as new order response.

Query All Open Order

Request:

{
  "accountId": "ST-00000001"
}

Response:

[
  {
     //Same as new order response
  }，
  {
     //Same as new order response
  }
]

Method:

method: order.listOpenOrderLite

Request:

Parameter	Description
accountId	account ID

Response:

Same as new order response.

Query All Completed Order

Request:

{
  "accountId": "ST-00000001",
  "venue":"GBBO",
  "startTime": 1537857271784,
  "endTime": 1537857271784,
  "limit": 100,
  "forward": True,
  "baseAsset": null,
  "quoteAsset": null,
  "orderSide": null,
  "orderStatus": null
}

Response:

[
  {
     //Same as new order response
  }，
  {
     //Same as new order response
  }
]

Query all filled orders, cancelled orders, and rejected orders.

Method:

method: order.listCompletedOrderLite

Request:

Parameter	Description
accountId	account ID
venue	GBBO (optional)
startTime	start time
endTime	end time
limit	total number of orders, max is 500
forward	true for forward, false for backward. (optional)
baseAsset	base asset. for example, for BTCUSDT，it is BTC. (optional)
quoteAsset	quote asset，For BTCUSDT，it is USD. (optional)
orderSide	order side: BUY, SELL. (optional)
orderStatus	order status: FILLED, CANCELLED. (optional)

Response:

Same as new order response.

Query Order Fills

Request:

{
  "accountId": "ST-00000001",
  "venue":"GBBO",
  "startDateTime": 1537857271784
}

Response:


[
  {   
    "accountId": "ST-GBBO_00000001",   
    "venue":"GBBO",   
    "orderId": "000000011584603011942221",   
    "symbol": "BTCUSDT",   
    "orderType": "LIMIT",   
    "timeInForce": 3,   
    "orderSide": "BUY",   
    "limitPrice": 9000,   
    "quantity": 0.01,   
    "filledAveragePrice": 0,   
    "filledCumulativeQuantity": 0,   
    "openQuantity": 0,   
    "orderStatus": "FILLED",   
    "createdAt": 1584603012164,   
    "updatedAt":  1584603012164,   
    "cancelledUpdatedAt": null,   
    "filledUpdatedAt": null ,
    "lastCommission": 0.0450,
    "lastCommissionCurrency": "USD",
    "lastFilledQuantity": 0.01,
    "lastFilledPrice": 9000,
    "isTaker": true
  }
]

Method:

method: order.listDetailLite (within 2minutes, 1000 records)

Request:

Parameter	Description
accountId	account ID
venue	GBBO
startDateTime	start time

Response:

Same as new order response.

Request:

{   
  "accountId": "ST-00000001",   
  "venue":"GBBO",   
  "orderId": "000000011584603011942221"
}

Response


[
  {   
    "accountId": "ST-GBBO_00000001",   
    "venue":"GBBO",   
    "orderId": "000000011584603011942221",   
    "symbol": "BTCUSDT",   
    "orderType": "LIMIT",   
    "timeInForce": 3,   
    "orderSide": "BUY",   
    "limitPrice": 9000,   
    "quantity": 0.01,   
    "filledAveragePrice": 0,   
    "filledCumulativeQuantity": 0,   
    "openQuantity": 0,   
    "orderStatus": "FILLED",  
    "createdAt": 1584603012164,   
    "updatedAt":  1584603012164,   
    "cancelledUpdatedAt": null,   
    "filledUpdatedAt": null ,
    "lastCommission": 0.0450,
    "lastCommissionCurrency": "USD",
    "lastFilledQuantity": 0.01,
    "lastFilledPrice": 9000,
    "isTaker": true
  }
]

Method:

method: order.readerOrderDetail

Request:

Parameter	Description
accountId	account ID
venue	GBBO
orderId	order ID

Response:

Same as new order response.

Query CommissionRate

Request:

{
  "accountId": "ST-00000001",
  "venue": "GBBO",
  "symbol": "BTCUSDT"
}

Response:

{
    "accountId": "STA-GBBO_00000001",
    "tradingVolume": 121.1001,
    "takeFee": 0,
    "makeFee": 0,
    "specialRate": 0
}

Method:

method: order.getCommissionRate

Request:

Parameter	Description
accountId	account ID
venue	GBBO
symbol	symbol

Response:

Parameter	Description
accountId	account ID
tradingVolume	transactions
takeFee	takeFee
makeFee	makeFee
specialRate	specialRate

Account API

Query Account Info

Request:

{
  "accountId": "ST-00000001",
  "venue": "GBBO"
}

Response:

{
  "accountId": "ST-00000001",
  "accountStatus": "OPENED",
  "createdAt": 1537857271784,
  "updatedAt": 1551956476878,
    "subAccountInfo": [
    {
      "accountId": "ST-GBBO_00000001",
      "venue": "GBBO",
      "accountStatus": "OPENED",
      "createdAt": 1584611383104,
      "updatedAt": 1584611383104
    }
  ]
}

Method:

method: account.queryAccountInfoLite

Request:

Parameter	Description
accountId	account ID
venue	GBBO (optional)

Response:

Parameter	Description
accountId	account ID
venue	GBBO
accountStatus	account status
createdAt	creation time
updatedAt	update time

Account Status:

Account Status	Explanation
OPENED	normal
RESTRICTED	restricted. Cannot submit order or cancel order, but can query order.
SUSPENDED	suspended, no operations are allowed

Query Account Asset

Request:

{
  "accountId": "ST-00000001",
  "venue":"GBBO"
}

Response:

[
  {
    "accountId": "ST-GBBO_00000001",
    "venue":"GBBO",
    "currency": "BTC",
    "amount": 51.95,
    "available": 51.95,
    "frozen": 0,
    "updatedAt": 1547208404061
  }
]

Method:

method: asset.listBalanceByLite

Request:

Parameter	Description
accountId	account ID
venue	GBBO (optional)

Response:

Parameter	Description
accountId	account ID
venue	GBBO
currency	symbol of asset
amount	amount
available	available quantity
frozen	frozen value
updatedAt	update time

Get Deposits Address

Request:

{
  "accountId": "ST-00000001",
  "venue":"GBBO",
  "currency": "BTC"
}

Response:

{
  "venue":"GBBO",
  "currency": "BTC",
  "address": "3Nxwena****************fp8v",
  "expiredAt": 1584606409507
}

{
  "venue":"GBBO",
  "currency": "EOS",
  "address": "acc******bnw",
  "memo": "10230001",
  "expiredAt": 1584606409507
}

Method:

method: asset.queryAddressLite

Request:

Parameter	Description
accountId	Account ID
venue	GBBO
currency	currency name

Response:

Parameter	Description
venue	GBBO
currency	currency name
address	deposits address
memo	memo information, some currencies are necessary, e.g. EOS
expiredAt	expiration time

Create Withdrawal Ticket

Request:

{
  "accountId": "ST-00000001",
  "venue":"GBBO"
}

Response:

{
  "ticket": "b215282*************bbe436f",
  "expiredAt": 1584633883235
}

You need to get a ticket before you can withdraw.

Method:

method: asset.createWithdrawTicketLite

Request:

Parameter	Description
accountId	account ID
venue	GBBO

Response:

Parameter	Description
ticket	withdraw ticket
expiredAt	expired time

Withdrawals

Request:

{
  "accountId": "ST-0000001",
  "venue":"GBBO",
  "currency": "BTC",
  "amount": 10.0021,
  "memo": "",
  "address": "3Nxwena****************fp8v",
  "ticket": "b2152827079******793d4bbe436f"
}

Response:

{
  "accountId": "ST-GBBO_00000001",
  "venue":"GBBO",
  "currency": "BTC",
  "coin": "BTC",
  "amount": 10.0021,
  "fee": 0.02,
  "fromAddress": null,
  "targetAddress": "3Nxwena****************fp8v",
  "type": "OUTGOING",
  "actionType": "ACCOUNT_CLIENT_WITHDRAW",
  "id": "ST-GBBO_00000001.a93cdec7f3544ad89e2dd2a1515a7cba",
  "txId":"6af5256d5d3dd**********************************e1c31de",
  "status": "SUBMITTED",
  "createdAt": 1584613315735,
  "updatedAt": 1584613839359
}

Method:

method: asset.withdrawLite

Request:

Parameter	Description
accountId	Account ID
venue	GBBO
currency	currency name
amount	the amount to withdraw
address	a crypto address of the recipient
memo	memo(Optional), It is usually necessary for EOS
ticket	withdraw ticket

Response:

Parameter	Description
accountId	Account ID
venue	GBBO
currency	currency name
coin	internal coin name
amount	the amount to withdraw
fee	fee of withdrawal
fromAddress	from address
targetAddress	a crypto address of the recipient
type	OUTGOING, INCOMING
actionType	source of request
id	internal transfer ID
txId	transaction ID
status	SUBMITTED, COMPLETED, CANCELLED
createdAt	creation time
updatedAt	updated time

Query Asset Records

Request:

{
  "accountId": "ST-00000001",
  "startTimeDate": "1584355090628",
  "endTimeDate": "1584614290628",
  "limit": "10",  
  "page": "1"
}

Response:

{
  "data": [
    {
      // Same as withdrawal response
    },
    {
      // Same as withdrawal response
    }
  ],
  "count": 1,
  "limit": 10,
  "page": 1,
  "pages": 1
}

Method:

method: asset.queryAssetActivityListLite

Request:

Parameter	Description
accountId	Account ID
startTimeDate	start time
endTimeDate	end time
limit	records per page
page	page number

Response:

Parameter	Description
count	total number of records
limit	records per page
page	page number
pages	page count

Base Info API

Query List Currency

Request:

{
  "accountId": "ST-00000001",
  "venue":"GBBO"
}

Response:

[
  {
    "currency": "BTC",
    "currencyPrecision": 9,
    "status": "NOT_DEPOSIT_WITHDRAW",
    "withdrawMaxAmount": 1000000,
    "withdrawMinAmount": 0.004,
    "withdrawMinFee": 0.0005,
    "nextStatus": null,
    "nextStatusAt": null,
    "coin": "BTC"
  },
  {
    "currency": "USDT",
    "currencyPrecision": 8,
    "status": "NOT_DEPOSIT_WITHDRAW",
    "withdrawMaxAmount": 10000,
    "withdrawMinAmount": 2,
    "withdrawMinFee": 5,
    "nextStatus": null,
    "nextStatusAt": null,
    "coin": "USDT.ETH"
  }
]

Method:

method: utils.listCurrencyLite

Request:

Parameter	Description
accountId	account ID
venue	GBBO

Response:

Parameter	Description
currency	currency
currencyPrecision	currency precision
status	current status
withdrawMaxAmount	max withdraw amount
withdrawMinAmount	min withdraw amount
withdrawMinFee	min withdraw fee
nextStatus	next status
nextStatusAt	next status time

currency status:

status	explanation
DEPOSIT_WITHDRAW	deposit and withdrawal are both allowed
NOT_DEPOSIT_WITHDRAW	deposit is not allowed, withdrawal is allowed
DEPOSIT_NOT_WITHDRAW	deposit is allowed, but withdrawal is not allowed
NOT_DEPOSIT_NOT_WITHDRAW	deposit and withdrawal are both not allowed

Query List Symbol

Request:

{
  "accountId": "ST-00000001",
  "venue":"GBBO"
}

Response:

[
  {
    "symbol":"BTCUSDT",
    "baseAsset":"BTC",
    "baseAssetPrecision": 8,
    "quoteAsset":"USDT",
    "quotePrecision": 8,
    "minPrice":0.01,
    "maxPrice":99999,
    "minQuantity":0.01,
    "maxQuantity":99999,
    "tickSize":0.01,
    "stepSize":0.0001,
    "minNotional": 1,
    "maxNotional": 1000,
    "status": "enabled"
  }
]

Method:

method: utils.listSymbolInfoLite

Request:

Parameter	Description
accountId	account ID
venue	GBBO

Response:

Parameter	Description
symbol	symbol
baseAsset	base asset
baseAssetPrecision	baseAsset precision
quoteAsset	quote asset，the right side of the symbol
quotePrecision	quote precision
minPrice	min price for the symbol
maxPrice	max price for the symbol
minQuantity	min quantity for the symbol
maxQuantity	max quantity for the symbol
tickSize	min price increment for the symbol
stepSize	min quantity increment for the symbol
minNotional	minimum notional value allowed for an order on a symbol. An order's notional value is the price * quantity
maxNotional	maximum notional value allowed for an order on a symbol. An order's notional value is the price * quantity
status	enabled or disabled

Query Current Timestamp of Server

Request:

{}

Response:

1552112542263

Method:

method: utils.currentTimeMillis

Request:

None

Response:

The server timestamp

Order Status Push Notice

Order status change notice obtained through HTTP and Websocket.

HTTP API

Request:

{
  "accountId": "ST-0000001",
  "startDateTime": null
}

Response:

[
  {
    "logTimestamp" : 1552116459512,
    "payload" : {
      "accountId" : "ST-00000001",
      "venue":"GBBO",
      "orderId" : "000000121574697605570321",
      "symbol" : "BTCUSDT",
      "orderType" : "LIMIT",
      "timeInForce": 1,
      "orderSide" : "BUY",
      "limitPrice" : 100.0,
      "quantity" : 1.12,
      "filledAveragePrice" : 0,
      "filledCumulativeQuantity" : 0,
      "openQuantity" : 0.001,
      "orderStatus" : "PENDING_SUBMIT",
      "createdAt" : 1537857271784,
      "updatedAt" : 1537857271784,
      "cancelledUpdatedAt" : null,
      "filledUpdatedAt" : null,
      "lastFilledQuantity" : null,
      "lastFilledPrice" : null,
      "lastFilledCreatedAt" : null
    }
  },
    {
   "logTimestamp" : 1552116459536,
   "payload" : {
     "accountId" : "ST-00000001",
     "venue":"GBBO",
     "orderId" : "000000121574697605570321",
     "symbol" : "BTCUSDT",
     "orderType" : "LIMIT",
     "timeInForce": 1,
     "orderSide" : "BUY",
     "limitPrice" : 100.0,
     "quantity" : 1.12,
     "filledAveragePrice" : 100.0,
     "filledCumulativeQuantity" : 1.12,
     "openQuantity" : 0,
     "orderStatus" : "FILLED",
     "createdAt" : 1537857271784,
     "updatedAt" : 1537857271784,
     "cancelledUpdatedAt" : null,
     "filledUpdatedAt" : 1552116459467,
     "lastFilledQuantity" : 1.12,
     "lastFilledPrice" : 100.0,
     "lastFilledCreatedAt" : 1537857271784
  }
]

Method:

method: order.streamDetail

Request:

Parameter	Description
accountId	account ID
startDateTime	order start time

Response:

Parameter	Description
lastFilledQuantity	last filled quantity
lastFilledPrice	last filled price
lastFilledCreatedAt	last filled time

WebSocket API

Response:

{
  {
   "logTimestamp" : 1552116459536,
   "payload" : {
     "accountId" : "ST-00000001",
     "venue":"GBBO",
     "orderId" : "000000121574697605570321",
     "symbol" : "BTCUSDT",
     "orderType" : "LIMIT",
     "orderSide" : "BUY",
     "limitPrice" : 100.0,
     "quantity" : 1.12,
     "filledAveragePrice" : 100.0,
     "filledCumulativeQuantity" : 1.12,
     "openQuantity" : 0,
     "orderStatus" : "FILLED",
     "createdAt" : 1552116459467,
     "updatedAt" : 1552116459467,
     "cancelledUpdatedAt" : null,
     "filledUpdatedAt" : 1552116459467,
     "lastFilledQuantity" : 1.12,
     "lastFilledPrice" : 100.0,
     "lastFilledCreatedAt" : 1552116459467
  }
}

Order update notice can be obtained through WebSocket：

Method:

wss://api.apifiny.com/gx/openApi/v1?signature={signature}&body={body}&p=webSocket

Note: Need to add one parameter in url：&p=webSocket

Method:

method: order.streamDetail

Market Data

Market data is obtained through the Websocket or RESTful interface.

Rate Limit: We throttle public endpoints by Access Key 1 request per second

Signature

Signature:

// js
signature = JWT(payload={
    "accessKey": "API_Key_ID"
}, key="API_Secret_Key", algorithm='HS256')

# python3
import jwt
signature = jwt.encode({'accessKey': "API_Key_ID"}, "API_Secret_Key", algorithm='HS256')
headers = {'signature': str(signature, encoding='utf-8')}

Request:

curl -X GET -H "signature: eyJhbI1NiJ9.eyJhY**************lY1TyJ9.RrWnyheQs" "https://api.apifiny.com/gx/orderbook/v1/BTCUSDT/GBBO"

Please use JWT to generate Signature and add the parameter signature to each request header.

For every request, please use JWT and secretKey to generate Signature and use Signature in request header parameter.

Parameter	Description
accessKey	API Key ID
key	API Key secret

Websocket Inteface

Request (subscription):

{
  "channel":"orderbook",
  "symbol":"BTCUSDT",
  "venues":["GBBO"],
  "action":"sub"
}

Request (unsubscribing):

{
  "channel":"orderbook",
  "symbol":"BTCUSDT",
  "venues":["GBBO"],
  "action":"unsub"
}

Response:

{
  "venues":["GBBO"],
  "channel":"orderbook",
  "orderbook":{
    "symbol":"BTCUSDT",
    "updatedAt":1584523325000,
    "asks": [
        [10000.0, 0.004]
        // [price, size]
        // ……
    ],
    "bids": [
        [7000.0, 0.04],
        [6980.0, 0.0048]
    ]
  }
}
// ....
{
  "venues":["GBBO"],
  "channel":"orderbook",
  "orderbook":{
    "symbol":"BTCUSDT",
    "updatedAt":1584523325000,
    "asks": [
        [8010.0, 1.02],
        [8000.0, 0.05]
    ],
    "bids": [
        [7001.0, 0.04],
        [6980.0, 0.048]
    ]
  }
}

The websocket end point is

URL:

wss://api.apifiny.com/gx/orderbook/v1

Request:

The request for subscription/unsubscribing must be in JSON format.

Parameter	Description
channel	channel is orderbook
symbol	symbol
venues	GBBO list
action	subscription or unsubscribing

Response:

The response of the websocket request is also in the JSON format.

It will return the market data of one venue at a time.

RESTful Interface

Response:

{
    "symbol":"BTCUSDT",
    "updatedAt":1584523325000,
    "asks": [
        [10000.0, 0.004]
        // [price, size]
        // ……
    ],
    "bids": [
        [7000.0, 0.04],
        [6980.0, 0.0048]
    ]
}

The RESTFul interface endpoint is:

URL:

GET https://api.apifiny.com/gx/orderbook/v1/{SYMBOL}/{VENUE}

The {SYMBOL} is the pair to be subscribed. For example, ETHBTC.

The {VENUE} is the exchange to be subscribed. For example, GBBO.

Response:

Same as the websocket orderbook response.

FIX Protocol Specification

FIX Protocol can be implemented using QuickFIX open source engine，please refer to ：QuickFIX

The following language is supported ：

Configuration for quickfix

quickfix configuration ：

[default]
ConnectionType=initiator
SenderCompID=ST-00000001
TargetCompID=APIFINY
SocketConnectHost=fix.api.apifiny.com
StartTime=00:00:00
EndTime=00:00:00
HeartBtInt=30
ReconnectInterval=5
UseDataDictionary=Y
ResetSeqNumFlag=Y
ResetOnLogon=Y
ResetOnLogout=Y
ResetOnDisconnect=Y

[session]
BeginString=FIX.4.2
SocketConnectPort=1443

There has an optional sample configuration for login using quickfix. Fix endpoint is: fix.api.apifiny.com:1443

Below is an example using Python.

Logon

 def toAdmin(self, message, sessionID):
        if message.getHeader().getField(35) is "A":
            key = 'XXXX'
            signature = get_signature('new_gbbo_order', 'ST-00000015', 'STA-00000015','STA-00000015', key)
            message.setField(fix.RawDataLength(len(signature)))
            message.setField(fix.RawData(signature))
        ...

get_signature is as following：

def get_signature(method, account_id, secret_key_id, params, secret_key):
    now = datetime.datetime.now()
    expect_time = now + datetime.timedelta(seconds=30)
    params_json_string = json.dumps(params) if isinstance(params, dict) else params
    digest = hashlib.sha256(params_json_string.encode()).hexdigest()
    signature = jwt.encode({
        'accountId': account_id,
        'secretKeyId': secret_key_id,
        'digest': digest,
        'method': method,
        'exp': int(expect_time.timestamp()),
    }
        , secret_key)
    # print(str(signature, encoding='utf-8'))
    return str(signature, encoding='utf-8')

Add JWT encrypted token in toAdmin.

Users of the FIX API will have to apply a seperate set of API Access Key, please contact BD team to apply, our team will get back to you within 1 working day.

New Order

    msg = quickfix42.NewOrderSingle()
    msg.setField(fix.ClOrdID(order_id)) # generated order id：00000015+13digt time stamp + 3 digit random number
    msg.setField(fix.Symbol(symbol)) # symbol:BTCUSDT
    msg.setField(fix.HandlInst('1'))
    msg.setField(fix.OrdType(fix.OrdType_LIMIT)) # OrdType：limit
    msg.setField(fix.TransactTime())
    msg.setField(fix.Side(side))
    msg.setField(fix.Price(price))
    msg.setField(fix.Account(account_id))
    msg.setField(fix.OrderQty(qty))
    msg.setField(fix.SecurityExchange("GBBO"))
    msg.setField(fix.Text("new Order"))
    quickfix.Session.sendToTarget(msg, application.sessionID)

New Order message is following in ：

Cancel Order

    msg = quickfix42.OrderCancelRequest()
    msg.setField(fix.OrigClOrdID(order_id))
    msg.setField(fix.ClOrdID(order_id))
    msg.setField(fix.Symbol(symbol))
    msg.setField(fix.TransactTime())
    msg.setField(fix.Side(side))
    msg.setField(fix.Account(account_id))
    msg.setField(fix.Text("Cancel Order"))
    msg.setField(fix.SecurityExchange("GBBO"))

Cancel ordermessage：

Execution Report

Execution Report message Sent by the broker/gateway when an order is accepted, rejected, filled, or canceled.

Tag	Name	Description
11	ClOrdID	Only present on order acknowledgements, ExecType=New (150=0)
37	OrderID	OrderID from the ExecutionReport with ExecType=New (150=0)
17	ExecId	Unique identifier of execution message
55	Symbol	Symbol of the original order
54	Side	Must be 1 to buy or 2 to sell
32	LastShares	Amount filled (if ExecType=1). Also called LastQty as of FIX 4.3
44	Price	Price of the fill if ExecType indicates a fill, otherwise the order price
38	OrderQty	OrderQty as accepted
60	TransactTime	Time the event occurred
150	ExecType	May be 1 (Partial fill) for fills
39	OrdStatus	Order status as of the current message

ExecType VALUES

ExecType	Description
0	Ack
1	Fill
4	Canceled
8	Rejected

Query order status

    msg = quickfix42.OrderStatusRequest()
    msg.setField(fix.ClOrdID(order_id))
    msg.setField(fix.Symbol(symbol))
    msg.setField(fix.Side(side))
    msg.setField(fix.Account(account_id))
    msg.setField(fix.SecurityExchange("GBBO"))

query order message is as following：

Others

HTTP Error code

HTTP 200 Normal response, if there is an error it will be in the response body
HTTP 4XX Error code for bad request
HTTP 403 Error code for too many errors and IP is blocked
HTTP 5XX Error code for server side errors
HTTP 502 Error code for when the service is not available

Response Error code

The error code in the response is a integer number。

Last number is A means client side error, B means server side error.

Please don't do frequent requests when errors occur. If it is a client side error, please correct the error and resubmit the request. If it is a server side error, it can be retried but in low frequency. If it still has an error, please contact customer support.

If too many errors occur or there are frequent requests, the IP will be banned.

Error Code	Explanation	HEX Error Code
65548	common error	0x01000C
65562	general request error, please check if the parameters in request are correct.	0x01001A
65579	general server side error, retry or contact customer service.	0x01002B
65595	server busy please wait	0x01003B
65658	IP is not in the whitelist	0x01007A
131098	Account_SessionStopped	0x02001A
131099	create account error	0x02001B
131114	Request too often, please try later	0x02002A
131114	Account doesn't exist, please verify account ID.	0x02002B
131162	Account status doesn't satisfy request, please verify account status.	0x02005A
131178	SQL execution error, duplicate primary key	0x02006A
196634	token error	0x03001A
196650	session error	0x03002A
196666	session extension validation Error	0x03003A
196682	sso token error	0x03004A
196698	session type error	0x03005A
262170	withdraw address not exist	0x04001A
262186	the number of withdraw addresses rearches limit	0x04002A
262202	Util_Unknown_Symbol	0x04003A
262218	Util_Unknown_Currency	0x04004A
262250	Util_Unknown_CoinType	0x04006A
262266	Util_Unknown_Coin	0x04007A
262299	Util_Create_Withdraw_Address_Error	0x04009B
262427	A connection issue encountered, please try again	0x04011B
262443	You have reach your daily withdrawal limit, please try next day	0x04012B
5243242	Order doesn't exist, please change order ID, Execute Fail	0x050016A
327706	Order ID doesn't exist, please recreate order id.	0x05001A
327722	Order_OriginalOrderIdDuplicate	0x05002A
327723	New order failure，retry or contact customer service.	0x05002B
327738	Order_OpenOrderNotExist	0x05003B
327738	Order doesn't exist, please change order ID.	0x05003A
327741	This exchange is currently under maitenance or not supported yet.	0x05003D
327754	Order_CancelPendingSubmitWait	0x05004A
327755	cancel order error, need to contact customer service.	0x05004B
327786	timeout for new order or other request, please wait and retry.	0x05005A
327786	orderSide parameter error	0x05006B
327786	too many open orders, cannot create new order, need to delete some orders and retry.	0x05006A
327802	order id repeat	0x05007B
327802	cannot cancel order under current order status, need confirm order status and retry or abandon request.	0x05007A
327818	Order create failed, incorrect timestamp format	0x05008A
327818	timeout for cancel order operation, need wait and retry.	0x05008A
327834	Order create failed, timestamp error	0x05009A
327836	Order_Detail_Not_Exist	0x05009C
327946	Order_Status_Not_Pending_Submit_Cancel	0x05010A
327948	Order_Log_Not_Exist order	0x05010C
327962	the number of new order within 24 hours exceed limit, please contact customer service.	0x05011A
327978	order id rule error	0x05012A
328010	the order is being cancelled, please verify order status.	0x05014A
328026	order cannot be cancelled when in Pending_Submit status，please wait for status changed to submitted to cancel order.( if order status is still pending submit after 10 minutes, please contact customer service. ）	0x05015A
328042	Order_GBBO_Error	0x05016A
328058	SOM_Request_Error	0x05017A
328074	Your account has reached the trade amount limitation	0x05018A
393242	Asset_AvailableNotEnough.	0x06001A
393242	withdraw ticket error, please check or create a withdraw ticket first.	0x06001B
393258	Not enough asset available. Please verify if there is enough asset in account.	0x06002A
393274	asset free frozen not enough	0x06003A
393290	asset reduce frozen not enough	0x06004A
393306	Order_Cancel_TimeOut_Error	0x06005A
393322	Asset_Activity_Submitted_Not_Exist	0x06006A
393338	Asset_Query_Deposit_Address_Error	0x06007A
393354	Assets in this currency are insufficient or non-existent	0x06008A
393355	Asset_Activity_Completed_TxId_Error	0x06008B
393372	Asset_Log_Not_Exist	0x06009C
393482	Order_Create_TimeOut_Error	0x06010A
393514	Asset_Activity_Id_Exist	0x06012A
393530	Conversion between two currencies is not supported	0x06013A
2097162	Signature Error	0x20000A
2097163	Permission denied. Invalid API-key or permissions for action. key	0x20000B
2097178	No matching market	0x20001A