Introduction

Apifiny GBBO™ discovers the best attainable prices from its entire global network using smart order routing and matching engine technology. Our institutional-grade REST and Websocket API gives Traders, OTC desks, Brokers, and Market Makers faster access to trade using one consistent set of APIs.

There is also a FIX API for order management.

Getting Started

Professional traders can easily execute their strategies across all* crypto-to-crypto and other crypto fiat pairs. With one deposit and KYC process, traders can reallocate assets among exchanges and start trading.

An account must be obtained by clients and will be given an accountID, API_Key_ID and API_Secret_Key.

All requests must be signed with JWT, i.e. they must use JWT to generate a Signature and add the parameter signature to each request header.

General Note

The base URL for the following APIs is: https://api.apifiny.com/gx/openApi/v1
All API messages are in JSON format.
All time related fields are in UNIX epoch time in milliseconds.
JWT is required for every request.

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

All request are made using HTTP Post.

Make Request

HTTP:

POST /gx/openApi/v1 HTTP/1.1
Host: api.apifiny.com
Content-Type: application/json
cache-control: no-cache
{
    "accountId": "STA-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.

All requests will have a standard response consisting of the following:

Standard response

The structure of the response:

{
  "result": null,
  "error": {
    "code": 0x02002B,
    "message": "Account doesn't exist, please verify account ID"
  }
}

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.

There are throttling limits, referred to as rate limits by Account ID. These are set at 20 requests per second and will result in an error message, “rate limit is exceeded”, if breached.
A “venue” is an exchange or a destination. “GBBO” is accessed by setting venue to GBBO: "venue": "GBBO".

Account API

The Account API has a number of calls to enable the user to get information about the account, to deposit and withdraw crypto from the account and interrogate the balances in the account. Only RESTful queries are supported for this set of functions.

Query Account Info

Request:

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

Response:

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

Method:

method: account.queryAccountInfoLite

Request:

Parameter	Description
accountId	account ID
venue	venue name, use `GBBO`

Response:

Parameter	Description
accountId	account ID
venue	venue name, use `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": "STA-00000001",
  "venue":"GBBO"
}

Response:

{
    "result": [{
            "accountId": "STA-GBBO_00000001",
            "venue": "GBBO",
            "currency": "BTC",
            "amount": 51.95,
            "available": 51.95,
            "frozen": 0
        },
        {
            "accountId": "STA-GBBO_00000001",
            "venue": "GBBO",
            "currency": "USDT",
            "amount": 101.95,
            "available": 51.95,
            "frozen": 50
        }
    ],
    "error": null
}

Method:

method: asset.listBalanceByLite

Request:

Parameter	Description
accountId	account ID
venue	venue name, use `GBBO`

Response:

Parameter	Description
accountId	account ID
venue	venue name, use `GBBO`
currency	symbol of asset
coin	currency code in system, different from currency name if multiple chains are supported
amount	amount
available	available quantity
frozen	frozen value
updatedAt	update time

Get Deposit Address

Request:

{
  "accountId": "STA-00000001",
  "venue":"GBBO",
  "coin": "BTC"
}

Response:

{
    "result": [{
        "venue": "GBBO",
        "currency": "BTC",
        "coin": "BTC",
        "address": "3Nxwena****************fp8v",
        "expiredAt": 1584606409507
    }],
    "error": null
}

{
    "result": [{
        "venue": "GBBO",
        "currency": "EOS",
        "coin": "EOS",
        "address": "acc******bnw",
        "memo": "10230001",
        "expiredAt": 1584606409507
    }],
    "error": null
}

Method:

method: asset.queryAddressLite

Request:

Parameter	Description
accountId	Account ID
venue	venue name, use `GBBO`
currency	currency name

Response:

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

Create a Withdraw Ticket

Request:

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

Response:

{
    "result": [{
        "ticket": "b215282*************bbe436f",
        "expiredAt": 1584633883235
    }],
    "error": null
}

You need to get a ticket before you can withdraw. Also if your ID verification has not been approved, you will get rejection error message.

Method:

method: asset.createWithdrawTicketLite

Request:

Parameter	Description
accountId	account ID
venue	venue name, use `GBBO`

Response:

Parameter	Description
ticket	withdraw ticket
expiredAt	expired time

Create a Withdraw Request

Request:

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

Response:

{
    "result": [{
        "accountId": "STA-VENUE1_00000001",
        "venue": "GBBO",
        "currency": "BTC",
        "coin": "BTC",
        "amount": 10.0021,
        "fee": 0.0005,
        "fromAddress": null,
        "targetAddress": "3Nxwena****************fp8v",
        "type": "OUTGOING",
        "actionType": "ACCOUNT_CLIENT_WITHDRAW",
        "actionNote": "ACCOUNT_CLIENT_WITHDRAW",
        "logId": "STA-GBBO_00000001.a93cdec7f3544ad89e2dd2a1515a7cba",
        "txId": "6af5256d5d3dd**********************************e1c31de",
        "status": "SUBMITTED",
        "logCreatedAt": 1584613315735,
        "logUpdatedAt": 1584613839359
    }],
    "error": null
}

Method:

method: asset.withdrawLite

Request:

Parameter	Description
accountId	Account ID
venue	venue name, use `GBBO`
currency	currency name
coin	currency code in system, different from currency name if multiple chains are supported
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	venue name, use `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
logId	internal transfer ID
txId	transaction ID
status	SUBMITTED, COMPLETED, CANCELLED
logCreatedAt	creation time
logUpdatedAt	updated time

Query Account History

Account activity either increases or decreases your account balance.

Request:

{
  "accountId": "STA-GBBO_00000001",
  "startTimeDate": "1584355090628",
  "endTimeDate": "1584614290628",
  "limit": "10",  
  "page": "1"
}

Response:

{
    "result": [{
        "records": [{
            "accountId": "STA-GBBO_00000001",
            "currency": "BTC",
            "status": "SUBMITTED",
            "type": "OUTGOING",
            "amount": 0.01,
            "fee": 0.003,
            "targetAddress": "",
            "coin": "BTC",
            "logId": "STA-GBBO_00000001.8de7fc99b5064f288f8fb9608951fb69",
            "logCreatedAt": "1584355090628",
            "logUpdatedAt": "1584614290628",
            "actionType": "ACCOUNT_CLIENT_TRANSFER_OUTGOING",
            "actionNote": "ACCOUNT_CLIENT_TRANSFER_OUTGOING",
            "fromAccountId": "STA-GBBO_00000001",
            "toAccountId": "STA-ConnectVenue_00000001"
        }, {
            "accountId": "STA-GBBO_00000001",
            "currency": "BTC",
            "status": "SUBMITTED",
            "type": "OUTGOING",
            "amount": 0.01,
            "fee": 0.003,
            "targetAddress": "",
            "coin": "BTC",
            "logId": "STA-GBBO_00000001.fde92d5bf570468e9e6b4a023d8080ce",
            "logCreatedAt": "1584355090628",
            "logUpdatedAt": "1584614290628",
            "actionType": "ACCOUNT_CLIENT_TRANSFER_OUTGOING",
            "actionNote": "ACCOUNT_CLIENT_TRANSFER_OUTGOING",
            "fromAccountId": "STA-GBBO_00000001",
            "toAccountId": "STA-ConnectVenue_00000001"
        }],
        "total": 5,
        "size": 2,
        "current": 1,
        "orders": [],
        "hitCount": false,
        "searchCount": true,
        "pages": 3
    }],
    "error": null
}

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
accountId	Account ID
currency	currency name
status	status of this account activity, SUBMITTED, COMPLETED, CANCELLED
type	IMCOMING for deposits, OUTGOING for withdrawals
amount	amount of currency changed
fee	fee occurs during this activity
fromAddress	from address
targetAddress	a crypto address of the recipient
txId	transaction ID onchain
coin	internal coin name
logId	internal ID
logCreatedAt	create time
logUpdatedAt	update time
actionType	source of request
actionNote	note of request
fromAccountId	the iniate sub-account transfer from
toAccountId	the target sub-account transfer to
count	total number of records
limit	records per page
page	page number
pages	page count

Market Data API

The Market Data API is available in both Websocket and RESTful interfaces.

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/md/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

The Websocket API is as follows:

Websocket API

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",
    "symbol": "BTCUSDT",
    "orderbook": {
        "symbol": "BTCUSDT",
        "updatedAt": 1621839607399,
        "asks": [
            [36179.76000000, 0.01311800],
            // [price, size]
            // ……
        ],
        "bids": [
            [36165.88000000, 0.01426800],
            [36153.40000000, 0.05641000]
        ]
    }
}

The websocket end point is

URL:

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

Request:

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

Parameter	Description
channel	channel is orderbook
symbol	symbol
venues	venue name, use `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.

The RESTful API is as follows:

RESTful API

Response:

{
    "symbol": "BTCUSDT",
    "updatedAt": 1621840045855,
    "asks": [
        [36540.0700, 0.00466900]
        // [price, size]
        // ……
    ],
    "bids": [
        [36538.5700, 0.00000900]
    ]
}

The RESTFul interface endpoint is:

URL:

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

The {SYMBOL} is the trading pairs. For example, BTCUSDT.

The {VENUE} is the exchange, GBBO.

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]
    ]
  }
}

Trading API

Clients will typically be using the Websocket API to subscribe to the market data and RESTful API to submit orders. Clients can use the websocket API to subscribe to the order updates or use RESTful API to get order updates. A typical trade flow would be as follows:

Step 1: Subscribe to market data. The websocket endpoint used to subscribe and unsubscribe for market data is wss://api.apifiny.com/md/orderbook/v1 . Request and reply are in JSON format.

The RESTful endpoint is GET https://api.apifiny.com/md/orderbook/v1/{SYMBOL}/{VENUE}, where {SYMBOL} denotes the currency pair of interest and the {VENUE} denotes the exchange.

Step 2: Create order and send order using the RESTful API.

The method for creating an order is order.insertOrderLite, which enables an order to be created and submitted. Note that the orderID parameter needs to be generated with the following specification: account id plus 13 digit of timestamp + 3 digit of random number.

Step 3: Subscribe to the order updates using websocket. A number of methods enable the querying of order(s) state.

The methods are order.queryOrderInfoLite to find the state of a single submitted order; order.queryListOrderLite to find the state of a max list of 500 submitted orders; order.listOpenOrderLite to get a list of all open orders; and order.listCompleteOrderLite to get a list of all complete orders.

Step 4: Cancel Order (as needed). When an order that was submitted and is open needs to be cancelled, the method used is order.cancelOrderLite. Any order that has a status of PENDING_SUBMIT or has already been cancelled, cannot be cancelled. In addition, cancelledUpdatedAt must be null.

Below is the sample code to demonstrate the workflow.

Sample Python Code

    # Subscribe to market data

    ACCOUNT_ID = "YOUR_ACCOUNT_ID"
    API_KEY_ID = "YOUR_API_KEY_ID"
    SECRET_KEY = "YOUR_API_SECRET_KEY"

    API_HTTP = "https://api.apifiny.com/md/openApi/v1"
    MD_HTTP = "https://api.apifiny.com/md/orderbook/v1"
    MD_WS = "wss://api.apifiny.com/md/orderbook/v1"

    print("get market data using http")
    headers = {'signature': get_md_signature(API_KEY_ID, SECRET_KEY)}
    res = requests.get("/BTCUSDT", headers=headers)
    print(res.json())


    print("get market data using websocket")
    # Specify the name of the exchange, 
    # subscribe to the market can subscribe to multiple exchanges

    VENUES = ["GBBO"]   
    msg = {"channel": "orderbook", 
           "symbol": 'BTCUSDT', 
           "venues": GBBO,
           'collect': True, 
           "action": "sub"}


    def sub_md(message):
        from websocket import create_connection
        import ssl
        sslopt = {"cert_reqs": ssl.CERT_NONE}
        con = create_connection(MD_WS, 
                                sslopt=sslopt, 
                                header=headers)
        con.send(json.dumps(message))
        while True:
            response = con.recv()
            if 'ping' in response:
                pong = response.replace('ping', 'pong')
                con.send(pong)
            print(response)

    # send order

    def new_order(order_id, 
              symbol, 
              order_type, 
              quantity, 
              Limit_price,
             order_side, 
             venue, 
             time_inforce):

        return self.http_request("order.insertOrderLite", {
            "accountId": self.account_id,
            "orderId": order_id,
            "venue": GBBO,
            "orderInfo": {
                "symbol": symbol,
                "orderType": order_type,
                "quantity": quantity,
                "limitPrice": limit_price,
                "orderSide": order_side,
                "timeInForce": time_inforce
             },
         })


    def cancel_order(order_id, GBBO):
        return http_request("order.cancelOrderLite", {
            "accountId": self.account_id,
            "venue": venue,
            "orderId": order_id,
        })



    print(‘Subscribe Market Data’)
    sub_md(msg)

    print('send order')
    order_id = "foo"
    res = new_order(order_id, 
                                 "BTCUSDT", 
                                  "LIMIT", 
                                  "0.02", "9980.00", 
                                  "BUY", 
                                  venue, 
                                  3)
    print(res)

Further technical information and examples for all Trading API methods are as follows:

Create New Order

Request:

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

Response:

{
    "result": [{
        "accountId": "STA-GBBO_00000001",
        "venue": "GBBO",
        "orderId": "000000011584603011942221",
        "symbol": "BTCUSDT",
        "orderType": "LIMIT",
        "orderSide": "BUY",
        "limitPrice": 100,
        "quantity": 1.12,
        "filledAveragePrice": 0,
        "filledCumulativeQuantity": 0,
        "timeInForce": 1,
        "openQuantity": 1.12,
        "orderStatus": "PENDING_SUBMIT",
        "createdAt": 1584603012164,
        "updatedAt": 1584603012164
    }],
    "error": null
}

Make a new order request：

Method:

method: order.insertOrderLite

Request:

Parameter	Description
accountId	account ID
venue	venue name, use `GBBO`
orderId	order ID
symbol	symbol
orderType	order type, LIMIT or MARKET
timeInForce	specifies how long the order remains in effect, GTC, IOC, PostOnly
orderSide	order side, BUY or SELL
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 this format: **account id plus 13 digit of timestamp + 3 digit of random number*, support up to 64 characters.

Response:

Parameter	Description
accountId	sub account ID
venue	venue name, use `GBBO`
orderId	order ID
symbol	symbol
orderType	order type, LIMIT or MARKET or MAKER or TAKER
orderSide	order side, BUY or SELL
limitPrice	limit price, not available for market order
quantity	quantity
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, same as Post Only, only make liquidity
TAKER	Taker Only Order, only take liquidity

Time In Force:

Time In Force	Description
1	GTC (Good Till Canceled)
2	GTD (Good Till Date), temporarily not supported
3	IOC (Immediate Or Cancel)
7	Post Only (The order should only make liquidity)

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	order has been accepted and stay active
PART_FILLED	final status, partially filled order
FILLED	final status, completely filled order
CANCELLED	final status, order has been cancelled
REJECTED	final status, order has been rejected

Cancel an Order

Request:

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

Response:

{
  //Same as new order response
}

Request Cancel an Order via the order ID.

Method:

method: order.cancelOrderLite

Request:

Parameter	Description
accountId	Account ID
venue	venue name, use `GBBO`
orderId	Order ID

Response:

Same as new order response.

Cancel Reject:

If the order could not be canceled (still pending submit, already filled or previously canceled, etc), then an error response will indicate the reason in the message field.

Cancel All

Request:

{
  "accountId": "STA-GBBO_00000001",
  "venue":"GBBO"
}

Response:

{
    "result": [
        "519e f355d9884e1f8e3d3ffc7caf13b5",
        "519e f355d9884e1f8e3d3ffc7caf13b3",
        "519e f355d9884e1f8e3d3ffc7caf14b5",
        "519e f355d9884e1f8e3d3ffc7caf13b6"
    ],
    "error": null
}

With best effort, Cancel all open orders. The response is a list of ids of the canceled orders.

Method:

method: order.cancelAccountVenueAllOrder

Request:

Parameter	Description
accountId	Account ID
venue	`GBBO`

Response:

Parameter	Description
orderId	Order ID, unique identifier of an order.

Get an Order

Request:

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

Response:

{
  //Same as new order response
}

Method:

method: order.queryOrderInfoLite

Request:

Parameter	Description
accountId	account ID
venue	venue name, use `GBBO`
orderId	order ID

Response:

Same as new order response.

Query Multiple Orders by IDs

Request:

{
  "accountId": "STA-GBBO_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 Orders

Request:

{
  "accountId": "STA-GBBO_00000001"
}

Response:

{
    "result": [{
            "accountId": "STA-GBBO_00000001",
            "venue": "GBBO",
            "orderId": "000000011584603011942221",
            "symbol": "BTCUSDT",
            "orderType": "LIMIT",
            "orderSide": "BUY",
            "limitPrice": 100,
            "quantity": 1.12,
            "filledAveragePrice": 0,
            "filledCumulativeQuantity": 0,
            "timeInForce": 1,
            "openQuantity": 1.12,
            "orderStatus": "PENDING_SUBMIT",
            "createdAt": 1584603012164,
            "updatedAt": 1584603012164
        },
        {
            "accountId": "STA-GBBO_00000001",
            "venue": "GBBO",
            "orderId": "000000011584603011942227",
            "symbol": "BTCUSDT",
            "orderType": "LIMIT",
            "orderSide": "SELL",
            "limitPrice": 110,
            "quantity": 1.12,
            "filledAveragePrice": 0,
            "filledCumulativeQuantity": 0,
            "timeInForce": 1,
            "openQuantity": 1.12,
            "orderStatus": "SUBMITTED",
            "createdAt": 1584603012164,
            "updatedAt": 1584603012164
        }
    ],
    "error": null
}

Method:

method: order.listOpenOrderLite

Request:

Parameter	Description
accountId	account ID

Response:

Same as new order response.

Query All Completed Orders

Request:

{
  "accountId": "STA-GBBO_00000001",
  "venue":"GBBO",
  "startTime": 1537857271784,
  "endTime": 1537857271784,
  "limit": 100,
  "orderStatus": null
}

Response:

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

Query all settled orders, including: filled, partially filled, canceled and rejected orders.

Method:

method: order.listCompletedOrderLite

Request:

Parameter	Description
accountId	account ID
venue	venue name, use `GBBO`
startTime	[Optional] Start Time
endTime	[Optional] End Time
limit	total number of orders, default is 500, Max 1000
orderStatus	order status: `PART_FILLED`, `FILLED`, `CANCELLED`. (optional)

Response:

Same as new order response.

Query List Fills

Request:

{
  "accountId": "STA-GBBO_00000001",
  "venue":"GBBO",
  "startTime": 1537857271784
}

Response:

{
    "result": [{
        "accountId": "STA-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
    }],
    "error": null
}

Get a list of recent fills.

Method:

method: order.listFilledOrder

Request:

Parameter	Description
accountId	[Required] Account ID
venue	[Required] Venue Name, use `GBBO`
symbol	[Optional] Limit the list of fills to this symbol
orderId	[Optional] Limit the list of fills to this order ID
limit	Default 500; max 1000
startTime	[Optional] Start Time
endTime	[Optional] End Time

Data time range

The system allows you to retrieve data up to three months (start from the last day by default). If you only specified the start time, the system will automatically calculate the end time (end time = start time + 3 months). On the contrary, if you only specified the end time, the system will calculate the start time (start time= end time - 3 months) the same way.

Response:

Same as new order response.

Parameter	Description
lastCommission	trading fees happen in this fill
lastCommissionCurrency	the currency of the trading fee
isTaker	this field indicates if the fill was the result of a liquidity provider or liquidity taker. `TRUE` indicates Taker and `FALSE` indicates Maker

Query Currenct Fee Rate

Request:

{
  "accountId": "STA-GBBO_00000001",
  "venue": "GBBO",
  "symbol": "BTCUSDT"
}

Response:

{
    "result": [{
        "accountId": "STA-GBBO_00000001",
        "tradingVolume": 121.1001,
        "takeFee": 0.003,
        "makeFee": 0,
        "specialRate": 0
    }],
    "error": null
}

Method:

method: order.getCommissionRate

Request:

Parameter	Description
accountId	account ID
venue	GBBO
symbol	symbol

Response:

Parameter	Description
accountId	account ID
tradingVolume	cumulative trading volume within 30 days
takeFee	taker fee
makeFee	maker fee
specialRate	special discount of trading fee

Order Status Push Notice

Optionally, one can query for order state changes via an HTTP API or Websocket API and will receive a stream of full order state changes back.

The HTTP API is as follows:

HTTP API

Request:

{
  "accountId": "STA-GBBO_00000001",
  "startDateTime": null
}

Response:

{
    "result": [{
            "logTimestamp": 1552116459512,
            "payload": {
                "accountId": "STA-GBBO_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,
                "lastCommission": 0.112,
                "lastCommissionCurrency": "USD",
                "isTaker": true
            }
        },
        {
            "logTimestamp": 1552116459536,
            "payload": {
                "accountId": "STA-GBBO_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,
                "lastCommission": 0.112,
                "lastCommissionCurrency": "USD",
                "isTaker": true
            }
        }
    ],
    "error": null
}

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
lastCommission	trading fees happen in this fill
lastCommissionCurrency	the currency of the trading fee
isTaker	this field indicates if the fill was the result of a liquidity provider or liquidity taker. `TRUE` indicates Taker and `FALSE` indicates Maker

The Websocket API is as follows:

WebSocket API

Payload:

{
    "logTimestamp": 1552116459536,
    "payload": {
        "accountId": "STA-GBBO_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": 1552116459467,
        "updatedAt": 1552116459467,
        "cancelledUpdatedAt": null,
        "filledUpdatedAt": 1552116459467,
        "lastCommission": 0.112,
        "lastCommissionCurrency": "USD",
        "lastFilledQuantity": 1.12,
        "lastFilledPrice": 100.0,
        "lastFilledCreatedAt": 1552116459467,
        "isTaker": true
    }
}

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

Base Information API

There is a further set of API’s to discover basic information about symbols and assets that Apifiny One supports.

Query List Currencies

Request:

{
  "accountId": "STA-GBBO_00000001",
  "venue":"GBBO"
}

Response:

{
    "result": [{
            "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": 4,
            "status": "DEPOSIT_WITHDRAW",
            "withdrawMaxAmount": 10000,
            "withdrawMinAmount": 10,
            "withdrawMinFee": 12,
            "nextStatus": null,
            "nextStatusAt": null,
            "coin": "USDT.BTC"
        },
        {
            "currency": "USDT",
            "currencyPrecision": 4,
            "status": "DEPOSIT_WITHDRAW",
            "withdrawMaxAmount": 10000,
            "withdrawMinAmount": 10,
            "withdrawMinFee": 12,
            "nextStatus": null,
            "nextStatusAt": null,
            "coin": "USDT.ETH"
        }
    ],
    "error": null
}

List known currencies.

Method:

method: utils.listCurrencyLite

Request:

Parameter	Description
accountId	account ID
venue	venue name, use `GBBO`

Response:

Parameter	Description
currency	currency
currencyPrecision	currency precision
status	current status, `DEPOSIT_WITHDRAW` or `NOT_DEPOSIT_WITHDRAW` or `DEPOSIT_NOT_WITHDRAW` or `NOT_DEPOSIT_NOT_WITHDRAW`
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 Symbols

Request:

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

Response:

{
    "result": [{
        "symbol": "BTCUSDT",
        "baseAsset": "BTC",
        "baseAssetPrecision": 8,
        "quoteAsset": "USDT",
        "quotePrecision": 4,
        "minPrice": 0.01,
        "maxPrice": 99999,
        "minQuantity": 0.01,
        "maxQuantity": 99999,
        "tickSize": 0.01,
        "stepSize": 0.000001,
        "minNotional": 10,
        "maxNotional": 100000,
        "status": "enabled"
    }],
    "error": null
}

Get a list of available trading pairs supportted in this venue.

Method:

method: utils.listSymbolInfoLite

Request:

Parameter	Description
accountId	account ID
venue	venue name, use `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:

{
    "result": 1552112542263,
    "error": null
}

Get the API server time.

Method:

method: utils.currentTimeMillis

Request:

None

Response:

The server timestamp

FIX API

FIX (Financial Information eXchange) is a standard protocol which can be used to enter orders, submit cancel requests, and receive fills. Users of the FIX API will typically have existing software using FIX for order management. Users who are not familiar with FIX should first consider using the REST API.

FIX API can be implemented using QuickFIX with the following language support:

Configuration information are as follows：

Configuration for quickfix

FIX API ENDPOINT URL

fix.api.apifiny.com:1443

Quickfix Configuration

Quickfix configuration sample codes：

[default]
ConnectionType=initiator
SenderCompID=STA-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

Here is an optional Python sample codes for login using quickfix:

Logon

 def toAdmin(self, message, sessionID):
        if message.getHeader().getField(35) is "A":
            key = 'XXXX'
            signature = get_signature('new_gbbo_order', 'STA-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.

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：

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("VENUE1"))

Cancel order message：

Execution Report

Execution Report message Sent by the broker/gateway when an order is accepted, rejected, partially filled, 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	1 for Partially fill and 2 for fill
39	OrdStatus	Order status as of the current message

ExecType VALUES

ExecType	Description
0	NEW, Ack
1	PARTIAL_FILL
2	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：

Status/Error Codes

There are two categories of error codes, one set generated by HTTP, typically by a server for a client request, and the other category is a set of Apifiny One application status/error codes.

HTTP Error code

HTTP status codes are divided into 5 ranges as follows:

1xx informational response – the request was received, continuing process
2xx successful – the request was successfully received, understood, and accepted
3xx redirection – further action needs to be taken in order to complete the request
4xx client error – the request contains bad syntax or cannot be fulfilled
5xx server error – the server failed to fulfil an apparently valid request

Some of the most common HTTP error codes include:

HTTP 403 - too many errors and IP is blocked

HTTP 502 - service is not available

Apifiny One Status/Error Codes

Apifiny One status/error codes are returned as a hexadecimal number. The number on the farthest right delineates client side errors (designated by the hexadecimal number A) from server side errors (designated by the hexadecimal number B).

Client side errors should be corrected at the client and the request resubmitted. Server side errors will have a max retry count as well as a resubmit interval of 50 ms. Persistent resubmissions will result in suspension of the submitting IP.

Error Code	Explanation	Hexadecimal 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
131115	Account doesn't exist, please verify account ID.	0x02002B
131130	Sorry, the venue does not match the request url, please check the base url.	0x02003A
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 reaches 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 canceled, please verify order status.	0x05014A
328026	order cannot be canceled 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.	0x20000B
2097178	No matching market	0x20001A

Download Demo

Click Python Sample to download demo Codes.

Change log

06/01/21

Update two endpoints: Query All Completed Order and Query List Fills.
Add a new endpoint: Cancell All.
Update python demo.

04/28/21

Update the response parameter for order status push notice, added lastCommission, lastCommissionCurrency, isTaker.

04/23/21

Update the request parameter currency to coin for get deposit address and Create a Withdraw Request.