Belgeyên API

Nêrînek giştî

API ya Rojbitê REST API ye ku JSON bi kar tîne. Bernameya te her daxwazê bi mifteyeke API îmze dike ku tu li ser malperê diafirînî. Gaveke têketinê tune ye û danişîneke ku pêdivî bi nûkirinê hebe jî tune ye.

Navnîşana tevahî navnîşana bingehîn e û dû re rêya endpointê ye, û rêya her endpointê bi /api/ dest pê dike. Mînak, lîsteya cotên bazirganiyê ev e: GET https://api.rojbit.io/api/spot/exchange-info

API ji bo bikaranîna server ber bi server e. Ew ji bo malperên din headerên CORS napêşkêş dike, ji ber vê yekê rûpeleke webê di gerokê de nikare wê bi kar bîne. Ji back end a xwe bi kar bîne.

Mifteyên API tenê li ser REST API dixebitin. Streama taybet a WebSocket wan qebûl nake, ji ber vê yekê daxwazên xwe bi endpointên daxwazan bişopîne.

Daxwaz û bersiv JSON in (UTF-8). Gava laşekî dişînî, Content-Type: application/json jî bişîne.

Gava tu daxwazekê datînî, mîqdar û bihaya wê wekî hejmarên JSON têne şandin. Cureyên bersivan tevlihev in: pêkhatin û daxwazên vekirî rêzenivîsên rast vedigerînin, lê bîlançoya spot balance wekî hejmar û locked wekî rêzenivîs vedigerîne. Rêzenivîsan bi cureyê decimal bixwîne, tu carî wekî float.

Afirandin û birêvebirina mifteyên API

Tu mifteyan li ser malperê, di hesabê xwe de diafirînî. Her mifte nav, destûr û lîsteyeke spî ya IP ya bijarte dihewîne.

Afirandina miftekê

1. 1Sepana piştrastkirinê (2FA) ji bo hesabê xwe çalak bike. Afirandina miftekê koda wê sepanê dixwaze.
2. 2Hesab → Mifteyên API veke û Mifteya API biafirîne hilbijêre.
3. 3Navekî bide miftê û destûrên wê hilbijêre. Xwendin bîlanço, daxwaz û dîrokê dihewîne. Bazirganî danîn û betalkirina daxwazên spot zêde dike û her dem Xwendinê jî dihewîne. Vekişandin wekî ne berdest tê nîşandan.
4. 4Lîsteyeke spî ya IP zêde bike (pêşniyarkirî): navnîşanên giştî yên serverên ku tu daxwazan ji wan dişînî, bi komayê veqetandî (heta 20 navnîşan). Mifteyeke bi Bazirganî û bê lîsteya spî 90 roj piştî afirandinê diqede. Mifteyên tenê-Xwendinê û mifteyên bi lîsteya spî nediqedin.
5. 5Koda sepana xwe ya piştrastkirinê binivîse. Piştî guhertina şîfre, e-name an 2FA, afirandina miftê ji bo demekê radiweste.
6. 6Mifte û sirrê kopî bike. Sir carekê tê nîşandan û careke din nayê nîşandan. Heke te winda kir, miftê betal bike û ya nû biafirîne.

Tiştê ku tu distînî

Mifteya API nasnameya giştî ya miftê ye. Bi rjk_live_ dest pê dike û 22 karakter li pey wê tên. Tu wê di headera X-ROJ-APIKEY de dişînî.

Sir bi rjs_live_ dest pê dike û 49 karakter li pey wê tên. Ew tu carî nayê şandin: tu tenê ji bo hesabkirina îmzeyan wê bi kar tînî. Wê wekî şîfreyê biparêze.

Birêvebirina mifteyan

• Tu dikarî navê miftekê biguherînî. Destûr, lîsteya spî ya IP û dema qedandinê nayên guhertin: mifteyeke nû biafirîne û ya kevin betal bike.
• Tu dikarî her gav, bê kod, mifteyekê betal bikî. Mifteya betalkirî di daxwaza piştî wê de êdî naxebite.
• Guhertina şîfre, e-name an 2FA piştî demeke kurt hemû mifteyên te yên heyî betal dike. Piştî guhertinê mifteyên nû biafirîne.
• Hesabek dikare hejmareke sînorkirî ya mifteyên çalak bihewîne. Rûpela Mifteyên API sînor nîşan dide.

Daxwazên xwe îmze bike

Her daxwazek ji bo endpointeke ku mifteyê dixwaze çar headeran digire. Rojbit îmzeyê bi sira te dîsa hesab dike û heke li hev neyê daxwazê red dike.

Headera Authorization bi wan re neşîne: daxwazeke ku her duyan dihewîne bi 400 API_KEY_MALFORMED tê redkirin. X-Device-Id ne pêwîst e.

Rêzenivîsa kanonîk (canonical string)

Îmze HMAC-SHA256 a rêzenivîsa kanonîk e, û hemû rêzenivîsa sirrê (UTF-8, bi pêşgira rjs_ û checksuma wê re) wekî mifte tê bikaranîn. Rêzenivîsa kanonîk heft qadan dihewîne ku bi yek rêza nû (LF) bi hev ve hatine girêdan, û di dawiyê de rêzeke nû tune.

1. 1ROJ1nîşana sabît
2. 2METHODrêbaza HTTP bi herfên mezin
3. 3PATHrêya tam wekî ku tu dişînî, bi /api re, heta ? a yekem, bê decodekirin
4. 4QUERYher tişt piştî ? a yekem, tam wekî ku tu dişînî, bê rêzkirin an dîsa encodekirin; heke tune be vala
5. 5TIMESTAMPnirxa X-ROJ-TIMESTAMP
6. 6RECV_WINDOWnirxa X-ROJ-RECV-WINDOW
7. 7BODY_SHA256hash a SHA-256 ya laşê xav ê daxwazê, bi hexadecimal a herfên biçûk; ji bo daxwaza bê laş, hash a rêzenivîsa vala

Tiştên ku divê rast bin

• Laşê JSON tenê carekê serialize bike, hash a wan baytan çêke û heman baytan bişîne. Tenê application/json bi UTF-8 tê qebûlkirin; her laşekî din tê redkirin.
• Saeta xwe rast bihêle. Demek li derveyî pencereyê 401 API_KEY_TIMESTAMP_INVALID distîne, û bersiv server_time_ms dihewîne da ku tu cudahiyê rast bikî.
• Ji bo ceribandina dîsa, dîsa îmze bike. Daxwazeke îmzekirî ya ku ne GET e û bi heman îmzeyê dîsa tê şandin bi 401 API_KEY_REPLAYED tê redkirin. Ev ceribandina te ya xwe jî di nav xwe de dihewîne piştî timeoutekê, ji ber ku dibe ku daxwaza yekem hatibe sepandin. Pêşî daxwazên vekirî û pêkhatinên xwe bixwîne, paşê daxwazeke nû bi demeke nû îmze bike. Daxwazên GET qet ji bo dubarebûnê nayên kontrolkirin.
• Mifteya şaş, sir an îmzeya şaş, mifteya betalkirî an qediyayî, û laşekî ku nikare were îmzekirin, hemû bi mebest heman bersiva 401 API_KEY_INVALID distînin. Heke te ev stand, mifte, sir û baytên ku te îmze kirine kontrol bike.

Mînak

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 }),
);

Endpoint

Ev endpointên ku mifteyeke API dikare bang bike û yên giştî yên ku mifte naxwazin in. Rêya her yekê piştî navnîşana bingehîn https://api.rojbit.io bi /api dest pê dike.

Ji bo mifteyên API ne berdest e

Her endpointeke din bi 403 API_KEY_NOT_PERMITTED bersiv dide: vekişandin, veguhastin, navnîşanên tomarkirî, navnîşanên danînê, dîroka danîn û vekişandinê, mîhengên ewlehiyê, piştrastkirina nasnameyê, profîl, hişyariyên bihayê, tîketên piştgiriyê, vexwendin û birêvebirina mifteyan. Van li ser malperê bike.

Referansên hesabê

Mifteya API ya yek hesabî ye û hesab ji miftê tê zanîn. Tu endpoint ne hejmara hesabê, ne user id û ne jî UID digire, û userId di laş an query string de tê paşguhkirin.

Sînor û headerên bersivê

Her miftê sê budçe hene: giraniya daxwazan di deqeyekê de, û danîna daxwazan di 10 çirkeyan de û di rojekê de. Her daxwaz giranî dixwe: xwendineke tenê kêm dixwe û rûpelek dîrokê zêdetir. Sînor dikarin biguherin, û yên te her dem di headerên bersivê de ne.

Her bersivek ji bo daxwazeke bi miftê îmzekirî van headeran digire (hemû hejmarên tam in).

Gava budçeyek diqede, bersiv 429 e bi headera Retry-After (bi çirkeyan) û laşekî ku tê de code RATE_LIMITED e û bucket sînorê derbasbûyî destnîşan dike. Ji daxwaza redkirî tiştek nayê hesabkirin. Betalkirina daxwazekê tê hesabkirin lê tu carî ji ber derbasbûna sînorekî nayê redkirin.

Piştrastkirina têkçûyî jî tê sînorkirin. Piştî têkçûnên dubare ji yek navnîşana IP an ji bo yek miftê, daxwazên din ên miftê ji bo çend deqeyan 429 bi Retry-After distînin. Îmzekerê xwe rast bike û bisekine: dubarekirina îmzeyeke şaş tenê li bendê dirêj dike.

Çewtî û kodên redkirinê

Daxwazeke têkçûyî laşekî JSON vedigerîne: ok false ye û code kodeke sabît e. Li gorî ok û code biryar bide, ne li gorî nivîsa peyamê ya ku dikare biguhere. Peyam di msg an error de ye. Laşê 429 qada ok nahewîne, ji ber vê yekê ji bo wê koda rewşê kontrol bike.

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

Daxwaz pêşî tê qebûlkirin û paşê tê pêkanîn. Heke daxwazek neyê pêkanîn, endpointa rewşa daxwazê bersiv dide ku tê de kind rejected e û code yek ji wan e, mînak SPOT_INSUFFICIENT_FUNDS, SPOT_SLIPPAGE_EXCEEDED an SPOT_HALTED.

Endpointên daxwazan dikarin bi 403 û koda rewşa hesabê jî bersiv bidin, mînak ACCOUNT_FROZEN, GEO_RESTRICTED_IP an LEGAL_ACCEPTANCE_REQUIRED. Ev li ser malperê têne çareserkirin, ne bi riya API.

Heke kodeke ku tu nas nakî bigihîje te, li gorî rewşa wê ya HTTP tevbigere: 4xx tê wateya ku daxwazê rast bike, 5xx tê wateya ku paşê dîsa biceribîne.