NAV Navbar

Apifiny Connect Note

Quick Start

  1. Apply for an account and get accountID, API_Key_ID and API_Secret_Key
  2. Use JWT to sign every request.
  3. Send new orders or a new order through order.insertOrder
  4. Use Websocket client to get order status.
  5. The {VENUE} refers to exchange name. For example: VENUE1, 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 Key ID
key API Key secret
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.

Trading API

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

Create New Order

Request:

{
  "accountId": "ST-00000001",
  "venue":"VENUE1",
  "orderId": "000000011584603011942221",
  "orderInfo": {
    "symbol": "BTCUSD",
    "orderType": "LIMIT",
    "timeInForce": 3,
    "orderSide": "BUY",
    "limitPrice": "100",
    "quantity": "1.12"
  }
}

Response:

{
  "accountId": "ST-VENUE1_00000001",
  "venue":"VENUE1",
  "orderId": "000000011584603011942221",
  "symbol": "BTCUSD",
  "orderType": "LIMIT",
  "timeInForce": 3,
  "orderSide": "BUY",
  "limitPrice": 100,
  "quantity": 1.12,
  "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 venue name
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

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 venue name
orderId order ID
exchOrdId exchange order ID - reserved for a future enhancement
symbol symbol
orderType order type
timeInForce specifies how long the order remains in effect
orderSide order side
limitPrice limit price
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

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":"VENUE1",
  "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 venue name
orderId Order ID

Response:

Same as new order response.

Query Single Order Info

Request:

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

Response:

{
  //Same as new order response
}

Method:

method: order.queryOrderInfoLite

Request:

Parameter Description
accountId account ID
venue venue name
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":"VENUE1",
  "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 venue name (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 BTCUSD,it is BTC. (optional)
quoteAsset quote asset,For BTCUSD,it is USD. (optional)
orderSide order side: BUY, SELL. (optional)
orderStatus order status: FILLED, CANCELLED. (optional)

Response:

Same as new order response.

Account API

Query Account Info

Request:

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

Response:

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

Method:

method: account.queryAccountInfoLite

Request:

Parameter Description
accountId account ID
venue venue name (optional)

Response:

Parameter Description
accountId account ID
venue venue name
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":"VENUE1"
}

Response:

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

Method:

method: asset.listBalanceByLite

Request:

Parameter Description
accountId account ID
venue venue name (optional)

Response:

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

Get Deposits Address

Request:

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

Response:

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

Method:

method: asset.queryAddressLite

Request:

Parameter Description
accountId Account ID
venue venue name
currency currency name

Response:

Parameter Description
venue venue name
currency currency name
address deposits address
expiredAt expiration time

Create Withdrawal Ticket

Request:

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

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 venue name

Response:

Parameter Description
ticket withdraw ticket
expiredAt expired time

Withdrawals

Request:

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

Response:

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

Method:

method: asset.withdrawLite

Request:

Parameter Description
accountId Account ID
venue venue name
currency currency name
amount the amount to withdraw
address a crypto address of the recipient
ticket withdraw ticket

Response:

Parameter Description
accountId Account ID
venue venue name
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

Transfer Between Venues

Request:

{
  "accountId": "ST-0000001",
  "venue":"VENUE1",
  "currency": "BTC",
  "amount": 10.0,
  "targetVenue": "VENUE2"
}

Response:

{
  "accountId": "ST-0000001",
  "venue":"VENUE1",
  "currency": "BTC",
  "amount": 10.0,
  "fee": 0.02,
  "targetVenue": "VENUE2",
  "id": "ST-VENUE1_00000001.a93cdec7f3544ad89e2dd2a1515a7cba",
  "status": "SUBMITTED",
  "createdAt": 1584613315735,
  "updatedAt": 1584613839359
}

Method:

method: asset.transferToVenue

Request:

Parameter Description
accountId Account ID
venue venue name
currency currency name
amount the amount to withdraw
targetVenue name of target venue

Response:

Parameter Description
accountId Account ID
venue venue name
currency currency name
amount the amount to withdraw
fee fee of withdrawal
targetVenue name of target venue
id internal transfer ID
status SUBMITTED, COMPLETED, CANCELLED
createdAt creation time
updatedAt updated time

Query Asset Records

Request:

{
  "accountId": "ST-00000001",
  "venue":"VENUE1",
  "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
venue venue name
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 Venues

Request:

{}

Response:

[
  {
    'exchange ': 'VENUE1',
    'status': 'enabled'
  },
  {
    'exchange ': 'VENUE2',
    'status': 'enabled'
  },
  {
    'exchange ': 'VENUE3',
    'status ': 'disabled'
  }
]

Method:

method: utils.listVenueInfoLite

Request:

None

Response:

Parameter Description
exchange name of the exchange
status exchange status

Query List Currency

Request:

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

Response:

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

Method:

method: utils.listCurrency

Request:

Parameter Description
accountId account ID
venue venue name

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":"VENUE1"
}

Response:

[
  {
    "Symbol":"EOSETH",
    "baseAsset":"EOS",
    "quoteAsset":"ETH",
    "minPrice":"0.01",
    "maxPrice":"99999",
    "minQuantity":1,
    "maxQuantity":99999,
    "tickSize":1.0E-8,
    "stepSize":1.0E-8,
    "minNotional": 10,
    "maxNotional": 1000000
  },
  {
    "Symbol":"BCHUSDT",
    "baseAsset":"BCH",
    "quoteAsset":"USDT",
    "minPrice":0.01,
    "maxPrice":99999,
    "minQuantity":0.01,
    "maxQuantity":99999,
    "tickSize":1.0E-8,
    "stepSize":1.0E-8,
    "minNotional": 1,
    "maxNotional": 1000
  }
]

Method:

method: utils.listSymbolInfoLite

Request:

Parameter Description
accountId account ID
venue venue name

Response:

Parameter Description
symbol symbol
baseAsset base asset
quoteAsset quote asset,the right side of the symbol
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

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":"VENUE1",
      "orderId" : "000000121574697605570321",
      "symbol" : "BTCUSD",
      "orderType" : "LIMIT",
      "timeInForce": 3,
      "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":"VENUE1",
     "orderId" : "000000121574697605570321",
     "symbol" : "BTCUSD",
     "orderType" : "LIMIT",
     "timeInForce": 3,
     "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":"VENUE1",
     "orderId" : "000000121574697605570321",
     "symbol" : "BTCUSD",
     "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.

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/BTCUSD/VENUE1"

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":"BTCUSD",
  "venues":["VENUE1","VENUE2"],
  "action":"sub"
}

Request (unsubscribing):

{
  "channel":"orderbook",
  "symbol":"BTCUSD",
  "venues":["VENUE1","VENUE2"],
  "action":"unsub"
}

Response:

{
  "venues":["VENUE1"],
  "channel":"orderbook",
  "orderbook":{
    "symbol":"BTCUSD",
    "updatedAt":1584523325000,
    "asks": [
        [10000.0, 0.004]
        // [price, size]
        // ……
    ],
    "bids": [
        [7000.0, 0.04],
        [6980.0, 0.0048]
    ]
  }
}
// ....
{
  "venues":["VENUE2"],
  "channel":"orderbook",
  "orderbook":{
    "symbol":"BTCUSD",
    "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 venue name 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":"BTCUSD",
    "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, VENUE1.

Response:

Same as the websocket orderbook response.

Others

HTTP Error code

Response Error code

The error code in the response is a hex 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
0x01001A general request error, please check if the parameters in the request are correct.
0x01002B general server side error, retry or contact customer service.
0x02002A account doesn't exist, please verify account ID.
0x02005A account status doesn't match the request, please verify the account status.
0x05001A order ID doesn't exist, please check order id.
0x05002B new order failure, retry or contact customer service.
0x05003A order doesn't exist, please change order ID.
0x05004B cancel order error, need to contact customer service.
0x05005A timeout for new order or other request, please wait and retry.
0x05006A too many open orders, cannot create new order, need to delete some orders and retry.
0x05007A cannot cancel order under current order status, need to confirm order status and retry or abandon the request.
0x05008A timeout for cancel order operation, need to wait and retry.
0x05011A the number of new orders within 24 hours exceeds the limit, please contact customer service.
0x05014A the order is being cancelled, please verify order status.
0x05015A order cannot be cancelled when in Pending_Submit status,please wait for the status to be changed to Submitted to cancel the order. (If the order status is still Pending_Submit after 10 minutes, please contact customer service. )
0x06002A Not enough assets available. Please verify if there are enough assets in the account.