بەڵگەنامەی API

تێڕوانینی گشتی

ڕۆژبیت APIیەکی REST دابین دەکات کە JSON بەکاردەهێنێت. بەرنامەکەت هەموو داواکارییەک بە کلیلێکی API واژۆ دەکات کە لە ماڵپەڕ دروستی دەکەیت. هیچ هەنگاوێکی چوونەژوورەوە و هیچ دانیشتنێک بۆ نوێکردنەوە نییە.

ناونیشانی تەواو بریتییە لە ناونیشانی بنەڕەتی و دوای ئەوە ڕێگای ئێندپۆینتەکە، و ڕێگای هەموو ئێندپۆینتێک بە /api/ دەست پێدەکات. بۆ نموونە، لیستی جووتەکانی بازرگانی ئەمەیە: GET https://api.rojbit.io/api/spot/exchange-info

API بۆ بەکارهێنانی سێرڤەر بۆ سێرڤەرە. هێدەری CORS بۆ ماڵپەڕەکانی تر نانێرێت، بۆیە پەڕەیەکی وێب لە وێبگەڕدا ناتوانێت بەکاری بهێنێت. لە بەشی پشتەوەی (back end) خۆتەوە بەکاری بهێنە.

کلیلەکانی API تەنها لەسەر REST API کار دەکەن. ستریمی تایبەتی WebSocket وەریان ناگرێت، بۆیە بەدواداچوونی داواکارییەکانت بە ئێندپۆینتەکانی داواکاری بکە.

داواکاری و وەڵامەکان بە JSON دەنێردرێن، بە UTF-8. کاتێک لەشێک دەنێریت، Content-Type: application/json بنێرە.

کاتێک داواکارییەک دادەنێیت، بڕ و نرخەکان وەک ژمارەی JSON دەنێردرێن. جۆری وەڵامەکان تێکەڵن: جێبەجێکردنەکان و داواکارییە کراوەکان دەقی ورد (string) دەگەڕێننەوە، لە کاتێکدا باڵانسی سپۆت balance وەک ژمارە و locked وەک دەق دەگەڕێنێتەوە. دەقەکان بە جۆری decimal بخوێنەوە، هەرگیز وەک float.

دروستکردن و بەڕێوەبردنی کلیلەکانی API

کلیلەکان لە ماڵپەڕ، لە هەژمارەکەتدا دروست دەکەیت. هەر کلیلێک ناو، دەسەڵات و لیستێکی سپی IPی دڵخواز تێدایە.

دروستکردنی کلیل

1. 1ئەپی پشتڕاستکەرەوە (2FA) بۆ هەژمارەکەت چالاک بکە. دروستکردنی کلیل کۆدێک لەو ئەپە دەخوازێت.
2. 2هەژمار ← کلیلەکانی API بکەرەوە و دروستکردنی کلیلی API هەڵبژێرە.
3. 3ناوێک بە کلیلەکە بدە و دەسەڵاتەکانی هەڵبژێرە. خوێندنەوە باڵانس، داواکاری و مێژوو دەگرێتەوە. بازرگانی دانان و هەڵوەشاندنەوەی داواکاریی سپۆت زیاد دەکات و هەمیشە خوێندنەوەی لەخۆ دەگرێت. دەرهێنان وەک بەردەست نییە پیشان دەدرێت.
4. 4لیستی سپی IP زیاد بکە (پێشنیارکراوە): ناونیشانە گشتییەکانی ئەو سێرڤەرانەی داواکارییەکانت لێوە دەنێریت، بە کۆما جیاکراوە (تا 20 ناونیشان). کلیلێک کە بازرگانی هەبێت و لیستی سپی نەبێت 90 ڕۆژ دوای دروستکردنی بەسەردەچێت. کلیلەکانی تەنها-خوێندنەوە و ئەوانەی لیستی سپییان هەیە بەسەرناچن.
5. 5کۆدی ئەپی پشتڕاستکەرەوەکەت بنووسە. دوای گۆڕینی وشەی نهێنی، ئیمەیڵ یان 2FA، دروستکردنی کلیل بۆ ماوەیەک دەوەستێت.
6. 6کلیل و نهێنییەکە کۆپی بکە. نهێنییەکە تەنها جارێک پیشان دەدرێت و جارێکی تر نابینرێتەوە. ئەگەر لەدەستت دا، کلیلەکە هەڵبوەشێنەوە و یەکێکی نوێ دروست بکە.

ئەوەی وەریدەگریت

کلیلی API ناسنامەی گشتیی کلیلەکەیە. بە rjk_live_ دەست پێدەکات و 22 کاراکتەری لەدوایە. لە هێدەری X-ROJ-APIKEY دەینێریت.

نهێنییەکە بە rjs_live_ دەست پێدەکات و 49 کاراکتەری لەدوایە. هەرگیز ناینێردرێت: تەنها بۆ ژماردنی واژۆکان بەکاری دەهێنیت. وەک وشەی نهێنی بیپارێزە.

بەڕێوەبردنی کلیلەکان

• دەتوانیت ناوی کلیلێک بگۆڕیت. دەسەڵاتەکان، لیستی سپی IP و کاتی بەسەرچوونی ناگۆڕدرێن: کلیلێکی نوێ دروست بکە و کۆنەکە هەڵبوەشێنەوە.
• دەتوانیت لە هەر کاتێکدا، بێ کۆد، کلیلێک هەڵبوەشێنیتەوە. کلیلی هەڵوەشێنراو لە یەکەم داواکاریی دواتردا ڕادەوەستێت.
• گۆڕینی وشەی نهێنی، ئیمەیڵ یان 2FA بە ماوەیەکی کەم دواتر هەموو کلیلە بەردەستەکانت هەڵدەوەشێنێتەوە. دوای گۆڕینەکە کلیلی نوێ دروست بکە.
• هەر هەژمارێک دەتوانێت ژمارەیەکی سنووردار کلیلی چالاک هەبێت. پەڕەی کلیلەکانی API سنوورەکە پیشان دەدات.

واژۆکردنی داواکارییەکانت

هەر داواکارییەک بۆ ئێندپۆینتێک کە کلیلی دەوێت چوار هێدەر هەڵدەگرێت. ڕۆژبیت واژۆکە بە نهێنییەکەت دووبارە دەژمێرێتەوە و ئەگەر یەکی نەگرتەوە داواکارییەکە ڕەت دەکاتەوە.

هێدەری Authorization لەگەڵیان مەنێرە: داواکارییەک کە هەردووکی تێدابێت بە 400 API_KEY_MALFORMED ڕەت دەکرێتەوە. X-Device-Id پێویست نییە.

دەقی کانۆنی (canonical string)

واژۆکە بریتییە لە HMAC-SHA256ی دەقی کانۆنی، و هەموو دەقی نهێنییەکە (UTF-8، لەگەڵ پێشگری rjs_ و checksumەکەی) وەک کلیل بەکاردێت. دەقی کانۆنی حەوت خانەی هەیە کە بە یەک هێڵی نوێ (LF) بەیەکەوە بەستراون، و لە کۆتاییدا هێڵی نوێ نییە.

1. 1ROJ1نیشانەی جێگیر
2. 2METHODشێوازی HTTP بە پیتی گەورە
3. 3PATHڕێگاکە ڕێک وەک ئەوەی دەینێریت، لەگەڵ /api، تا یەکەم ?، بێ decodeکردن
4. 4QUERYهەموو شتێک دوای یەکەم ?، ڕێک وەک ئەوەی دەینێریت، بێ ڕیزکردن یان دووبارە encodeکردن؛ ئەگەر نییە بەتاڵ
5. 5TIMESTAMPبەهای X-ROJ-TIMESTAMP
6. 6RECV_WINDOWبەهای X-ROJ-RECV-WINDOW
7. 7BODY_SHA256هاشی SHA-256ی لەشی خاوی داواکارییەکە، بە هێکسادێسیماڵی پیتی بچووک؛ بۆ داواکاریی بێ لەش، هاشی دەقی بەتاڵ

ئەو شتانەی دەبێت ڕاست بن

• لەشی JSON تەنها یەک جار بکە بە دەق (serialize)، هاشی ئەو بایتانە بکە و هەمان بایتەکان بنێرە. تەنها application/json بە UTF-8 وەردەگیرێت؛ هەر لەشێکی تر ڕەت دەکرێتەوە.
• کاتژمێری سێرڤەرەکەت ورد بهێڵەرەوە. کاتێک کاتەکە لە دەرەوەی ماوەکە بێت 401 API_KEY_TIMESTAMP_INVALID وەردەگریت و وەڵامەکە server_time_ms لەخۆ دەگرێت تاکو جیاوازییەکە ڕاست بکەیتەوە.
• بۆ دووبارە هەوڵدانەوە، دووبارە واژۆ بکە. داواکارییەکی واژۆکراو کە GET نییە و بە هەمان واژۆ جارێکی تر دەنێردرێتەوە، بە 401 API_KEY_REPLAYED ڕەت دەکرێتەوە. ئەمە هەوڵدانەوەی خۆتیشت دەگرێتەوە دوای timeout، چونکە لەوانەیە داواکاریی یەکەم جێبەجێ کرابێت. سەرەتا داواکارییە کراوەکان و جێبەجێکردنەکانت بخوێنەوە، پاشان داواکارییەکی نوێ بە کاتێکی نوێ واژۆ بکە. داواکاریی GET هەرگیز بۆ دووبارەبوونەوە ناپشکنرێت.
• کلیلی هەڵە، نهێنی یان واژۆی هەڵە، کلیلی هەڵوەشێنراو یان بەسەرچوو، و لەشێک کە ناتوانرێت واژۆ بکرێت، هەموویان بە ئەنقەست یەک وەڵامی 401 API_KEY_INVALID وەردەگرن. ئەگەر ئەمەت بۆ هات، کلیل، نهێنی و ئەو بایتانە بپشکنە کە واژۆت کردوون.

نموونەکان

Key:        rjk_live_xxxxxxxxxxxxxxxxxxxxxx
Secret:     rjs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Request:    GET /api/spot/open-orders?symbol=BTCUSDT (no body)
Timestamp:  1792000000000
Window:     5000

Canonical string (seven lines, no line feed after the last):
ROJ1
GET
/api/spot/open-orders
symbol=BTCUSDT
1792000000000
5000
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

X-ROJ-SIGNATURE:
88899c6f71568fdc593230e617c3f28b84091ce9d22e71961690db1348c9bd70

KEY="rjk_live_…"
SECRET="rjs_live_…"

TARGET="/api/spot/open-orders?symbol=BTCUSDT"   # path and query, exactly as you send them
TS=$(( $(date +%s) * 1000 ))                      # milliseconds since the epoch
RW=5000

REQ_PATH=$(printf '%s' "$TARGET" | cut -d'?' -f1)    # up to the first ?
QUERY=$(printf '%s' "$TARGET" | cut -s -d'?' -f2-)   # after the first ?, empty if none
BODY_SHA=$(printf '' | openssl dgst -sha256 | awk '{print $NF}')   # no body

CANON=$(printf 'ROJ1\nGET\n%s\n%s\n%s\n%s\n%s' "$REQ_PATH" "$QUERY" "$TS" "$RW" "$BODY_SHA")
SIG=$(printf '%s' "$CANON" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')

curl -sS "https://api.rojbit.io$TARGET" \
  -H "X-ROJ-APIKEY: $KEY" \
  -H "X-ROJ-TIMESTAMP: $TS" \
  -H "X-ROJ-RECV-WINDOW: $RW" \
  -H "X-ROJ-SIGNATURE: $SIG"

// roj.mjs · Node.js 18 or later
// run: ROJ_API_KEY=… ROJ_API_SECRET=… node roj.mjs
import { createHash, createHmac } from "node:crypto";

const BASE = "https://api.rojbit.io";
const API_KEY = process.env.ROJ_API_KEY; // rjk_live_…
const API_SECRET = process.env.ROJ_API_SECRET; // rjs_live_…

async function call(method, target, body) {
  const m = method.toUpperCase();
  const raw = body === undefined ? "" : JSON.stringify(body); // serialize once
  const q = target.indexOf("?");
  const path = q === -1 ? target : target.slice(0, q);
  const query = q === -1 ? "" : target.slice(q + 1);
  const timestamp = String(Date.now());
  const recvWindow = "5000";
  const bodyHash = createHash("sha256").update(raw, "utf8").digest("hex");
  const canonical = ["ROJ1", m, path, query, timestamp, recvWindow, bodyHash].join("\n");
  const signature = createHmac("sha256", API_SECRET).update(canonical, "utf8").digest("hex");

  const res = await fetch(BASE + target, {
    method: m,
    headers: {
      "X-ROJ-APIKEY": API_KEY,
      "X-ROJ-TIMESTAMP": timestamp,
      "X-ROJ-RECV-WINDOW": recvWindow,
      "X-ROJ-SIGNATURE": signature,
      ...(raw && { "Content-Type": "application/json" }),
    },
    body: raw || undefined, // the same bytes that were hashed
  });
  console.log("weight", res.headers.get("x-roj-used-weight-1m"), "of", res.headers.get("x-roj-weight-limit-1m"));
  return res.json();
}

console.log(await call("GET", "/api/wallets/spot"));
console.log(
  await call("POST", "/api/spot/limit", { symbol: "BTCUSDT", side: "buy", baseQty: 0.002, limitPrice: 50000 }),
);

ئێندپۆینتەکان

ئەمانە ئەو ئێندپۆینتانەن کە کلیلی API دەتوانێت داواکارییان بۆ بنێرێت، لەگەڵ ئەوانەی گشتین و کلیلیان ناوێت. ڕێگای هەموویان لە دوای ناونیشانی بنەڕەتی https://api.rojbit.io بە /api دەست پێدەکات.

بۆ کلیلەکانی API بەردەست نییە

هەموو ئێندپۆینتێکی تر بە 403 API_KEY_NOT_PERMITTED وەڵام دەداتەوە: دەرهێنان، گواستنەوە، ناونیشانە پاشەکەوتکراوەکان، ناونیشانی دانان، مێژووی دانان و دەرهێنان، ڕێکخستنەکانی ئاسایش، پشتڕاستکردنەوەی ناسنامە، پرۆفایل، ئاگاداری نرخ، تیکێتی پشتگیری، بانگهێشت و بەڕێوەبردنی کلیلەکان. ئەمانە لە ماڵپەڕ بکە.

ئاماژەکانی هەژمار

کلیلی API هی یەک هەژمارە، و هەژمارەکە لە کلیلەکەوە دیاری دەکرێت. هیچ ئێندپۆینتێک ژمارەی هەژمار، ناسنامەی بەکارهێنەر یان UID وەرناگرێت، و userId لە لەش یان query string دا پشتگوێ دەخرێت.

سنوورەکان و هێدەرەکانی وەڵام

هەر کلیلێک سێ بودجەی هەیە: کێشی داواکاری لە خولەکێکدا، و دانانی داواکاری لە 10 چرکەدا و لە ڕۆژێکدا. هەر داواکارییەک کێشێک دەخوات: خوێندنەوەیەکی تاک کەم دەخوات و لاپەڕەیەکی مێژوو زیاتر. سنوورەکان دەگۆڕدرێن، و هی تۆ هەمیشە لە هێدەرەکانی وەڵامدایە.

هەر وەڵامێک بۆ داواکارییەکی بە کلیل واژۆکراو ئەم هێدەرانە هەڵدەگرێت (هەموویان ژمارەی تەواون).

کاتێک بودجەیەک تەواو دەبێت، وەڵامەکە 429 دەبێت، لەگەڵ هێدەری Retry-After (بە چرکە) و لەشێک کە تێیدا code بریتییە لە RATE_LIMITED و bucket ئەو سنوورە دەستنیشان دەکات کە تێپەڕێنراوە. داواکاریی ڕەتکراوە کێشی لێ ناکرێتەوە. هەڵوەشاندنەوەی داواکاری دەژمێردرێت، بەڵام هەرگیز بە هۆی تێپەڕاندنی سنوورەوە ڕەت ناکرێتەوە.

سەلماندنی شکستخواردووش سنووردار دەکرێت. دوای شکستی دووبارە لە یەک ناونیشانی IP یان بۆ یەک کلیل، داواکاریی دواتری کلیل بۆ چەند خولەکێک 429 لەگەڵ Retry-After وەردەگرێت. واژۆکەرەکەت چاک بکە و چاوەڕێ بکە: دووبارەکردنەوەی واژۆیەکی هەڵە تەنها چاوەڕێکردنەکە درێژ دەکاتەوە.

هەڵەکان و کۆدەکانی ڕەتکردنەوە

داواکاریی شکستخواردوو لەشێکی JSON دەگەڕێنێتەوە: ok بریتییە لە false و code کۆدێکی جێگیرە. بەپێی ok و code بڕیار بدە، نەک دەقی نامەکە کە دەگۆڕدرێت. نامەکە لە msg یان error دایە. لەشی 429 خانەی ok لەخۆ ناگرێت، بۆیە بۆ ئەو دۆخی کۆدەکە (status code) بپشکنە.

{
  "ok": false,
  "msg": "Unauthorized — request timestamp outside the accepted window",
  "reason": "api_key_ts_stale",
  "server_time_ms": 1792000000123,
  "code": "API_KEY_TIMESTAMP_INVALID"
}

داواکاری سەرەتا وەردەگیرێت و دواتر جێبەجێ دەکرێت. ئەگەر داواکارییەک نەتوانرێت جێبەجێ بکرێت، ئێندپۆینتی دۆخی داواکاری وەڵام دەداتەوە کە تێیدا kind بریتییە لە rejected و code یەکێکە وەک SPOT_INSUFFICIENT_FUNDS، SPOT_SLIPPAGE_EXCEEDED یان SPOT_HALTED.

ئێندپۆینتەکانی داواکاری دەتوانن بە 403 و کۆدێکی دۆخی هەژمار وەڵام بدەنەوە، بۆ نموونە ACCOUNT_FROZEN، GEO_RESTRICTED_IP یان LEGAL_ACCEPTANCE_REQUIRED. ئەمانە لە ماڵپەڕ چارەسەر دەکرێن، نەک لە ڕێگەی API.

کۆدێکی نەزانراو بە دۆخی HTTPەکەی مامەڵە لەگەڵ بکە: 4xxی نەناسراو واتە داواکارییەکە چاک بکە، 5xx واتە دواتر دووبارە هەوڵ بدەرەوە.