Authentication

We support API Key Authentication for API endpoints. To use authentication, you need to create a new API key on your API endpoint account page.

Each HTTP Request must include these headers:

• x-apikey : Public API Key (Get Your API Key)
• x-sign : Signature
• x-time : Timestamp in milliseconds
• x-nonce : Timestamp tolerance in milliseconds

Example Request:

curl https://api.ziontrader.com/api/users/me
--header "x-apikey: "
--header "x-sign: "
--header "x-time: "
--header "x-nonce: " \

Public API Key

The public key you created in your account page.

Signature

Signature is an HMAC-SHA256 encoded message. The HMAC-SHA256 code must be generated using a private key that contains a timestamp as nonce and your API key.

Timestamp

Timestamp is an integer value. It must be current timestamp in millliseconds.

Nonce

Nonce is a tolerance for timestamp value. If you application's time is different from the server time. Maximum allowed value is 60 seconds (60000 in milliseconds). For example, if your nonce value is 15000, your signature will be valid for 15 seconds.

Creating Signature

Here are some examples in some programming languages about creating signature.

JavaScript

const nonce = 60 * 1000;
const time = Math.floor(Date.now() / 1000) * 1000;
const apiKey = 'YOUR_API_PUBLIC_KEY';
const apiSecret = 'YOUR_API_SECRET_KEY';
const timestamp = Math.floor(Date.now() / 1000) * 1000;
const signature = crypto.createHmac('sha256', apiSecret).update(apiKey + timestamp).digest().toString('base64');

PHP

$apiKey = 'YOUR_API_PUBLIC_KEY';
$apiSecret = 'YOUR_API_SECRET_KEY';
$timestamp = floor(microtime(true) / 1000) * 1000;
$signature = base64_encode(hash_hmac('sha256', $apiKey . $timestamp, $apiSecret, true));

Python

api_key = 'YOUR_API_PUBLIC_KEY'
api_secret = 'YOUR_API_SECRET_KEY'
timestamp = int(time.time() // 1000) * 1000
message = f"{api_key}{timestamp}".encode()
secret = api_secret.encode()
signature = base64.b64encode(hmac.new(secret, message, hashlib.sha256).digest()).decode()

C#

string apiKey = "YOUR_API_PUBLIC_KEY";
string apiSecret = "YOUR_API_SECRET_KEY";
long timestamp = (DateTimeOffset.UtcNow.ToUnixTimeSeconds() / 1000) * 1000;

string message = apiKey + timestamp;
byte[] keyByte = Encoding.UTF8.GetBytes(apiSecret);
byte[] messageBytes = Encoding.UTF8.GetBytes(message);

using (var hmacsha256 = new HMACSHA256(keyByte))
{
    byte[] hashmessage = hmacsha256.ComputeHash(messageBytes);
    string signature = Convert.ToBase64String(hashmessage);
}

Callbacks

• Callbacks are of two types. They work when the related process ends or completes.
• You can set the callback URL on the ApiKey you have added under the “Profile->Api Keys” tab.
• With which api key you come to the API, the URL you entered there will be forwarded as HTTP->POST.
• Deposit Callback: Runs when the deposit request is closed (when it expires).
• Withdraw Callback: Runs when the Withdraw request is completed.

Deposit Callback Request Body:

{
  "status": boolen, // true|false
  "method": string, // deposit
  "balance": number, // float
  "amount": number, // float
  "toAmount": number, // float
  "currency": string, // TRY|USD|EURO
  "toCurrency": string, // BTC|ETH|TRX|USDT|SOLANA
  "transactionId":  number, // integer
  "clientTxId": string, // Your transaction id
  "clientUniqueId": string, // Your user id
}

Withdraw Callback Request Body:

{
  "status": boolen, // true|false
  "method": string, // withdraw
  "amount": number, // float
  "transactionId": number, // integer
  "toAddress": string,
  "fromAddress": string,
  "currency": string, // TRY|USD|EURO
  "walletCurrency": string, // BTC|ETH|TRX|USDT|SOLANA
  "walletNetwork":  string, // TRC20|ERC20|SOLANA
  "clientTxId": string, // Your transaction id
  "clientUniqueId": string, // Your user id
}

Status Codes

Successful Status Codes

• 200 OK Request proceed successfuly
• 201 Created New object is created successfuly
• 204 No Content The object is deleted

Client Side Errors

• 400 Bad Request Request has invalid or missing parameters.
• 401 Unauthorized Authentication is invalid.
• 403 Forbidden You do not have permission to reach that endpoint.
• 404 Not Found The data is not found.
• 422 Unprocessable Entity The operation could not completed because of some reasons detailed in response body.
• 429 Too Many Requests You requests are being rate limited

Server Side Errors

• 500 Internal Server Error Something went wrong in server.
• 503 Service Unavailable Your connection is lost or the server is unavailable because of some reasons.

Fields

All Responses are in JSON Format

Asset

Crypto currencies are represented as asset. The fields in JSON models with name asset, assetSymbol etc, corresponds to a crypto currency such as BTC, ETH

Quantity

The fields represent money are named as quantity. Quantity values are represented in string format. You should be careful about decimals and precisions. Quantity values never includes thousand seperators. And only dot (.) is used as seperator. You should not use comma for decimal seperators.

Here are some examples:

{
    "quantity1": 0.0374024,
    "quantity2": 24.4024,
    "quantity3": 12,
    "quantity4": 72642.027836,
}

Timestamp

All times in API endpoints are in unix milliseconds format. You should send time values in unix time milliseconds in your requests. And be aware, all responses includes time values in unix milliseconds formats.

Errors

When something went wrong in your request, server sends 4xx HTTP Response message.

400 Bad Request responses are returned if your request model is invalid or missing some parameters. Details are included in body as JSON error model.

422 Unprossable Entity responses are returned if a condition blocks your operation. For example, when you send a valid model for placing an order to a cancel only market. Details are included in body as JSON error model.

Other 4xx responses does not include JSON model in their bodies.

Error Model Example:

{
    "code": "market_disabled",
    "message": "BTCUSDT market is in Cancel Only mode"
}

Error Message Table

Code	Message
EXAMPLE_CODE	Example Message

Rate Limits

Base API URL : https://api.ziontrader.com

• Action: Specifices action of the endpoint
• Method: HttpVerb (GET, POST, DELETE)
• Period: Specifies the period of requests.
• Limit: Speficies request limit of the rule.
• Rejected: Rejecting period if you are getting 429 HTTP status code.
• Policy: IP or IP and Account reject policies in the rejecting period.

Action	URI	Method	Period (sec)	Limit (req)	Rejected (sec)	Policy
Create Deposit	/api/deposits	POST	60	300	60	IP, Account
Get Deposit Detail	/api/deposit?token={token}	GET	60	300	60	IP, Account

Please contact us to get more information about rate limiting rules.

Deposit Request

POST: /api/deposits

Request body must be in JSON Format. Fields of JSON object are described below:

Request JSON Model Fields

Name	Optional	Description
amount	No	Amount to be deposited.
currency	No	Currency to be deposited.
toCurrency	No	Cryptocurrency to be purchased.
clientTxId	No	Client transaction id.
clientUniqueId	No	Client userId. It can be the user's unique ID or primary key.

If deposit order is successful returns 200 OK. Response body is in JSON format and includes order status and trade information.

Response model fields are described below:

Field Name	Field Type	Description
status	string	Order status; "success", "failed", "error".
message	string	Response message.
id	integer	Unique order id.
apiUrl	string	API endpoint where you can view the details of the order.
popupUrl	string	Popup url to be shown to the user.

Example Request

{
    "amount": 100.25,
    "currency": "TRY",
    "toCurrency": "BTC",
    "clientTxId": "YOUR_TX_ID",
    "clientUniqueId": "YOUR_USER_ID",
}

Example Response

{
    "status": "success",
    "message": "message",
    "data": {
        "id": 123,
        "token": "deposit_token",
        "apiUrl": "https://api.ziontrader.com/api/deposit?token=${token}",
        "popupUrl": "https://ziontrader.com/deposit?token=${token}",
    },
}

Get Deposit Request

GET: /api/deposit

Querystrings

Name	Optional	Description
token	No	API endpoint where you can view the details of the order.

Response is in JSON format.

Example Response

{
    "status": "success",
	"data": {
        "id": 123,
        "createdAt": "2024-03-03T10:57:58.148Z",
        "updatedAt": "2024-03-03T10:57:58.148Z",
        "currency": "TRY", // TRY, USD, EURO
        "toCurrency": "USDT", // BTC, ETH, TRX, USDT
        "price": 32.17, // transaction unit price
        "amount": 100, // amount to be deposited
        "toAmount": 3.10, // amount in cryptocurrency to deposit
        "balance": 0, // total deposited cryptocurrency amount
        "clientTxId": "123",
        "timeLeft": 111, // remaining time in seconds
        "dueDate": "2024-03-03T10:59:58.148Z", // last trading date
        "status": "PENDING", // Deposit status, [PENDING,PROCESSING,SUCCESS,CANCELED,FAILED,ERROR]
        "apiStatus": "IDLE", // Deposit sweep status, [IDLE,PENDING,PROCESSING,SUCCESS,CANCELED,FAILED,ERROR]
        "apiAttempt": 0, // Deposit sweep attempt, [0,1,2,3] 
        "wallet": {
            "id": 123,
            "balance": 0,
            "address": "TAmKhPDpJtPUeghqg3azPkuZZRrEBEWhAQ:Test:62160",
            "clientUniqueId": "123",
        },
        "deposits": [], // all deposits made by the user within the allowed period.
    }
}