Quick Start Guide

Overview

This guide provides a comprehensive overview of how to use the SynFutures API endpoints. It covers the essential steps from authentication to making your first API call.

Important: All API endpoints require authentication.

Prerequisites

Before you begin, ensure you have:

• A SynFutures account

• API credentials (API Key and Secret Key)

• Basic understanding of REST APIs

• Your preferred programming language environment set up

Authentication

All API endpoints require authentication using API keys. Here's how to authenticate your requests:

Required Headers

X-BAPI-API-KEY: [your_api_key]
X-BAPI-SIGN: [signature]
X-BAPI-TIMESTAMP: [timestamp]
X-BAPI-RECV-WINDOW: 5000

Signature Generation

The signature is generated using HMAC SHA256:

import hmac
import hashlib
import time

def generate_signature(api_secret, timestamp, method, endpoint, params=None):
    if params:
        query_string = '&'.join([f"{k}={v}" for k, v in sorted(params.items())])
        message = f"{timestamp}{api_key}{5000}{query_string}"
    else:
        message = f"{timestamp}{api_key}{5000}"

    signature = hmac.new(
        api_secret.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return signature

Base URL

All API requests should be made to:

https://api.synfutures.com

Common Request Patterns

All API endpoints require authentication. Here are examples of authenticated requests:

Example 1: Get Server Time

curl -X GET "https://api.synfutures.com/v5/market/time" \
  -H "X-BAPI-API-KEY: [your_api_key]" \
  -H "X-BAPI-SIGN: [signature]" \
  -H "X-BAPI-TIMESTAMP: [timestamp]" \
  -H "X-BAPI-RECV-WINDOW: 5000"

Example 2: Get Account Balance

curl -X GET "https://api.synfutures.com/v5/account/balance" \
  -H "X-BAPI-API-KEY: [your_api_key]" \
  -H "X-BAPI-SIGN: [signature]" \
  -H "X-BAPI-TIMESTAMP: [timestamp]" \
  -H "X-BAPI-RECV-WINDOW: 5000"

Step-by-Step Examples

Step 1: Get Server Time

First, synchronize with the server time:

const timestamp = Date.now().toString();
const signature = generateSignature(
    apiSecret,
    timestamp,
    "GET",
    "/v5/market/time"
);

const response = await fetch("https://api.synfutures.com/v5/market/time", {
    headers: {
        "X-BAPI-API-KEY": apiKey,
        "X-BAPI-SIGN": signature,
        "X-BAPI-TIMESTAMP": timestamp,
        "X-BAPI-RECV-WINDOW": "5000",
    },
});
const data = await response.json();
console.log("Server time:", data.data);

Step 2: Get Market Data

Retrieve current market information:

const timestamp = Date.now().toString();
const signature = generateSignature(
    apiSecret,
    timestamp,
    "GET",
    "/v5/market/tickers"
);

const response = await fetch(
    "https://api.synfutures.com/v5/market/tickers?category=linear&symbol=BTCUSDT",
    {
        headers: {
            "X-BAPI-API-KEY": apiKey,
            "X-BAPI-SIGN": signature,
            "X-BAPI-TIMESTAMP": timestamp,
            "X-BAPI-RECV-WINDOW": "5000",
        },
    }
);
const data = await response.json();
console.log("Ticker data:", data.data[0]);

Step 3: Get Account Balance

Retrieve your account balance:

const timestamp = Date.now().toString();
const signature = generateSignature(
    apiSecret,
    timestamp,
    "GET",
    "/v5/account/wallet-balance"
);

const response = await fetch("https://api.synfutures.com/v5/account/balance", {
    method: "GET",
    headers: {
        "X-BAPI-API-KEY": apiKey,
        "X-BAPI-SIGN": signature,
        "X-BAPI-TIMESTAMP": timestamp,
        "X-BAPI-RECV-WINDOW": "5000",
    },
});
const data = await response.json();
console.log("Account balance:", data.data[0]);

Error Handling

Always implement proper error handling:

try {
    const response = await fetch(apiUrl, options);
    const data = await response.json();

    if (data.code !== 200) {
        console.error("API Error:", data.msg);
        return;
    }

    // Process successful response
    console.log("Success:", data.data);
} catch (error) {
    console.error("Request failed:", error);
}

Rate Limits

Be aware of rate limits:

• All Endpoints: 120 requests per minute

Implement rate limiting in your application to avoid hitting these limits.

Best Practices

1. Use HTTPS

Always use HTTPS for API requests to ensure data security.

2. Handle Timestamps

• Use server time for synchronization

• Include proper timestamp in requests

• Account for network latency

3. Implement Retry Logic

async function apiCallWithRetry(url, options, maxRetries = 3) {
    for (let i = 0; i < maxRetries; i++) {
        try {
            const response = await fetch(url, options);
            if (response.ok) {
                return await response.json();
            }
        } catch (error) {
            if (i === maxRetries - 1) throw error;
            await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1)));
        }
    }
}

4. Validate Responses

Always validate API responses before processing:

function validateResponse(data) {
    if (!data || typeof data.code === "undefined") {
        throw new Error("Invalid response format");
    }

    if (data.code !== 200) {
        throw new Error(`API Error: ${data.msg}`);
    }

    return data.data;
}

5. Use Pagination

For endpoints that return large datasets, use pagination:

async function getAllData(endpoint, params = {}) {
    let allData = [];
    let cursor = null;

    do {
        const response = await fetch(
            `${endpoint}?${new URLSearchParams({
                ...params,
                limit: 50,
                ...(cursor && { cursor }),
            })}`
        );

        const data = await response.json();
        allData = allData.concat(data.data);
        cursor = data.data.nextPageCursor;
    } while (cursor);

    return allData;
}

Testing Your Setup

Test your API setup with this simple script:

async function testApiSetup() {
    try {
        const timestamp = Date.now().toString();
        const signature = generateSignature(
            apiSecret,
            timestamp,
            "GET",
            "/v5/market/time"
        );

        // Test 1: Get server time
        const timeResponse = await fetch(
            "https://api.synfutures.com/v5/market/time",
            {
                headers: {
                    "X-BAPI-API-KEY": apiKey,
                    "X-BAPI-SIGN": signature,
                    "X-BAPI-TIMESTAMP": timestamp,
                    "X-BAPI-RECV-WINDOW": "5000",
                },
            }
        );
        const timeData = await timeResponse.json();
        console.log("✓ Server time:", timeData.data);

        // Test 2: Get market data
        const tickerTimestamp = Date.now().toString();
        const tickerSignature = generateSignature(
            apiSecret,
            tickerTimestamp,
            "GET",
            "/v5/market/tickers"
        );
        const tickerResponse = await fetch(
            "https://api.synfutures.com/v5/market/tickers?category=linear&symbol=BTCUSDT",
            {
                headers: {
                    "X-BAPI-API-KEY": apiKey,
                    "X-BAPI-SIGN": tickerSignature,
                    "X-BAPI-TIMESTAMP": tickerTimestamp,
                    "X-BAPI-RECV-WINDOW": "5000",
                },
            }
        );
        const tickerData = await tickerResponse.json();
        console.log("✓ Market data:", tickerData.data[0].symbol);

        // Test 3: Get account balance
        if (apiKey && apiSecret) {
            const balanceResponse = await getAccountBalance();
            console.log("✓ Account balance retrieved");
        }

        console.log("✓ All tests passed!");
    } catch (error) {
        console.error("✗ Test failed:", error.message);
    }
}

Next Steps

1. Set Up Authentication: Ensure your API credentials are properly configured

2. Test Basic Endpoints: Start with simple endpoints like server time

3. Explore Market Data: Access market data endpoints to understand available instruments

4. Check Account Status: Verify your account balance and permissions

5. Monitor Positions: Use position endpoints to track your current positions

6. Review Order History: Analyze your trading history and performance

7. Implement Trading Logic: Build your trading strategies using the API

Support

For additional help:

• Check the individual API documentation files

• Review error codes and messages

• Ensure your API keys have the correct permissions

• Verify your request format matches the documentation

Security Notes

• Never expose your API secret key in client-side code

• Use environment variables for API credentials

• Implement proper access controls

• Monitor your API usage regularly

• Rotate your API keys periodically