API Summary


Market overview and general information.

Matching Engine


The matching engine is explained in this section based on the following criteria:

  • Fill Price
  • Order Life Cycle
  • Price Limit Rules For Token Trading
Filled Price

Beldex’s matching engine executes orders on a first-come, first-serve basis, that is the price/order that is registered first is matched first.

Example: Consider that the following 3 orders are placed in the order book respectively: a) 8900USDT for 1BTC, b) 9000USDT for 1.5BTC, and c) 9050USDT for 2BTC. They will be matched first based on price then based on placement time, which is c > b > a.

Instead of the taker price, orders are matched and executed at the maker price.

Example: User X places an order to buy 1.5BTC at 8900USDT, and then user Y places an order to sell 1BTC at 9000USDT. Because the order created by the user X was placed into the order book prior to the order created by the user Y, the maker in this transaction will be user X and 8900USDT for 1.5BTC will be the fill price.

Order Life Cycle

When an order is placed, it is sent to the matching engine in the unfilled state. The order is considered filled if the order fully executed against another order. Partially filled orders remain in the order matching queue awaiting execution. When an open order is cancelled, its status will change from unfilled to cancelled. The matching queue only holds unfilled orders. Cancelled or filled orders are removed from it.

Token Trading Price Limit Rules

To prevent execution errors that lead to unnecessary loss when placing orders, the Fill-or-kill feature is available.

The order would be entirely cancelled regardless of its fill quantity if it is filled at a price that is more or less than 5% from the best bid & offer price by the time it is executed in the order book. If not, then as expected, the order would be matched and executed.

Example: A user placed a market order to buy 50BTC in XRP/BTC. The best offer price at the time was 0.00003. The market price would be driven up to 0.000039 had the order fully executed in the market.

Based on the calculation [(0.000039-0.00003)/0.00003]*100=30%. This is > 5%. In this case, the market order would be cancelled entirely, since the potential fill price deviates more than 30% from the current best offer.

Fees


The public data is limited based on the IP and similarly, the individual/private data is limited based on the User ID.

  • Trading Fees
  • Deposit/Withdrawal Fees
Trading Fees

Beldex levies a maker fee and a taker fee. This maker-taker fee structure is used to enhance the liquidity of the market and user participation. The maker fee is usually lower than the taker fee. The fee schedule classified into tiers based on the volume. A user is eligible for a tier if their trading volume that meets the requirement of the specified tier. The trading volume is calculated on the basis of a 30 day rolling period. Higher tier corresponds to lower trading fees. The market makers who offer liquidity and maintain a compact bid-ask spread will be rewarded with lower fees.

Please see here for details (https://www.beldex.io/fee-schedule)

Deposit/Withdrawal Fees

Beldex does not charge any deposit fee. The withdrawal fee is based on the selected cryptocurrency.

Requests


This section lays out the details of a request based on the following three criteria:

  • Introduction
  • Errors
  • Success
Introduction

Access account management, market data, and trading via REST API.

The Terminal URL of REST API: (https://api.beldex.io/)

To push real-time market data through streaming, Beldex provides WebSocket API (https://ws.beldex.io/).

All requests are HTTPS-based. The contentType in the request header should be set as ßapplication/json

Errors

HTTP 4xx status codes will be returned in case of Bad requests, unless otherwise stated. Information about the error can be found in the body of the error returned.

Configure message bodies for non-2xx requests in your HTTP library. This allows you to read the message field from the body

Common Error Codes

400 Bad Request — Invalid request format

401 Unauthorized — Invalid API Key

403 Forbidden — You do not have access to the requested resource

404 Not Found

500 Internal Server Error — We had a problem with our server

Success

The HTTP status code 200 indicates a successful response to your request. The response may or may not contain a body. In case it does, the message that the body returns will be included under the resource below.

Rules


Standard specifications for the following attributes are explained in this section:

  • Timestamps
  • Numbers
Timestamps

EPOCH Unix timestamp is the timestamp returned from the API. It has a millisecond resolution. Cases where it is not returned will have another format specified. You should be able to parse the EPOCH format with the example shown below. Parsing the format can be easily done using most of the programming languages and libraries available today.

Example

1574516866

Numbers

To maintain the precision of decimal numbers, they are returned as “Strings”. To avoid the loss of precision due to truncation of decimal points, we suggest the conversion of decimal numbers to “Strings”.

However, integer numbers like for example, trade ID and sequences, are unquoted.

Endpoints


The details of the endpoints are explained in this section:

  • Public Endpoints
  • Private Endpoints
Public Endpoints

You can access the market data and other market information via the public APIs. Authentication is not required for requests to access public endpoints.

Private Endpoints

You can manage your account and orders using private endpoints. You must sign with a valid authentication scheme using your API key for all requests to access private endpoints. You can generate API keys here

Rate Limits


The rate limit details for the following are explained in this section:

  • REST API
  • WebSocket Beldex imposes rate limits on incoming requests to prevent API abuse. The status code, ‘429: Too Many Requests’ will be returned whenever the rate limit is exceeded.
REST API

If you use a valid API Key in your request, then your User ID will be used for rate limiting. Likewise, requests made via the public API will be rate limited by the public IP addresses.

Further in the documentation, you can find a specified rate limit for each endpoint. If unspecified, then by default the limit is 6 requests per second.

Authentication


The details about authentication is explained in this section:

  • Generating an API Key
  • Making Requests
  • Signing Messages
  • Timestamps
  • Getting Server Time
Generating an API Key

You must create an API key on Beldex before you can sign any requests. Once you create a key, you will be provided with 2 pieces of information which you should safeguard and remember.

API Key

Secret

Passphrase

The first two, that is, the API Key and Secret will be provided by Beldex; They are randomly generated. You will be providing a Passphrase of your choice to further secure your API access. To authenticate your requests, Beldex stores the salted hash of your passphrase but does not store the actual hash. Therefore, you cannot recover the passphrase if you lose it. We recommend that you maintain a written copy of your Passphrase at all times.

Making Requests

The following headers must be provided for all private REST requests:

BDX-ACCESS-KEY The API key as a String.

BDX-ACCESS-SIGN The base64-encoded signature (see Signing Messages subsection for details).

BDX-ACCESS-TIMESTAMP The timestamp of your request.

BDX-ACCESS-PASSPHRASE The passphrase you specified when creating the API key.

Request bodies are expected to have content type application/json and are in valid JSON format.

Signing Messages

The BDX-ACCESS-SIGN header is generated as follows:

  • create a prehash string of timestamp + method + requestPath + body (where + represents String concatenation)
  • prepare the Secret
  • sign the prehash string with the Secret using the HMAC SHA256
  • encode the signature in the base64 format

Example:

const crypto = require('crypto');

createSignature(requestString, api_secret) {       
        const hmac = crypto.createHmac('sha256', api_secret);
        const signature = hmac.update(timestamp+'GET'+'/user/self/verify').digest('base64');
        return signature;
    }

The timestamp value is the same as the BDX-ACCESS-TIMESTAMP header with nanosecond precision.

The request method should be UPPER CASE, i.e. GET and POST.

The requestPath is the path of requesting an endpoint.

Example: /api/v1/orders/put-limit

The body refers to the String of the request body. It can be omitted if there is no request body (frequently the case for GET requests).

Example: {"pair":"BTCUSD","order_id":"377454671037440"}

The Secretkey is generated when you create an API Key.

Example: 92d2b2c0475bd0bb89f016a4ac5d488bb3b5c3cec3

Timestamp

The BDX-ACCESS-TIMESTAMP request header must be in the Unix EPOCH timestamp decimal seconds format. It needs to be accurate down to milliseconds.

The requests will be considered expired or rejected if there is a 30+ second difference between the timestamp of your request and the API service time. We recommend using the time endpoint to query for the API server time if you believe there may be time skew between your server and the API servers.

Getting Server Time

API server time. This is a public endpoint, no verification is required.

HTTP Requests

GET /api/v1/time

Rate limit:6/2s

Response data
Parameters Description
epoch Unix Epoch in UTC
Example Response
{
  "result":  {
    "epoch": 1420674445.201 
  }
}

results matching ""

    No results matching ""