AurumProp Developer Platform

API Documentation

مرجع کامل API نسخهٔ v1 برای کلاینت‌های Native و اتوماسیون، همراه با endpointهای JSON مرورگر. همهٔ معاملات شبیه‌سازی‌شده هستند و هیچ سفارشی نزد کارگزار واقعی اجرا نمی‌شود.

Endpointهای قابل‌مشاهده3
Public3
کاربر احراز هویت‌شده0
Admin / Internal0

مقدمه و Base URL

API برای کلاینت‌های Native و اتوماسیون سمت کاربر؛ برای مرورگر از Session استفاده می‌شود.

API Version v1
Base URL https://app.example.com/api/v1 مسیرها در این صفحه مطلق و نسبت به Host هستند.
Content-Type application/json درخواست بدنه‌دار بدون این هدر 415 می‌گیرد.
Execution mode simulated هیچ اتصال یا ارسال سفارش به کارگزار واقعی وجود ندارد.
Time UTC / ISO 8601 تاریخ فیلترها YYYY-MM-DD است.
شما در حالت مهمان هستید و فقط endpointهای Public را می‌بینید. برای دیدن endpointهای کاربر وارد شوید؛ مستندات عملیاتی فقط برای مدیران مجاز نمایش داده می‌شود.

احراز هویت و مجوز

API نسخهٔ v1 از Bearer Token استفاده می‌کند و هیچ Session Cookie نمی‌سازد. توکن را از POST /api/v1/auth/login بگیرید و در هدر Authorization: Bearer <access_token> بفرستید.

  • توکن دسترسی به‌صورت پیش‌فرض ۹۰۰ ثانیه و توکن تازه‌سازی ۳۰ روز معتبر است.
  • توکن تازه‌سازی در هر استفاده می‌چرخد؛ استفادهٔ دوباره از توکن قدیمی کل خانوادهٔ نشست را باطل می‌کند.
  • مدیران و کاربران دارای require_totp پیش از دریافت توکن باید ۲FA فعال کنند.
  • ۲FA در ورود با totp_code یا recovery_code بررسی می‌شود.
  • نمایش مستندات به معنی مجوز اجرا نیست؛ هر Route مجوز واقعی خود را بررسی می‌کند.

Endpointهای /api/market، /api/candles، /api/crypto/{ref} و /api/chart/* API رسمی Native نیستند و فقط با Session معتبر مرورگر کار می‌کنند؛ نوشتن‌ها CSRF می‌خواهند.

قالب درخواست و پاسخ

پاسخ موفق

{
  "success": true,
  "data": { "...": "..." },
  "meta": {
    "request_id": "req_0123456789abcdef"
  }
}

پاسخ خطا

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": { "symbol": "Unknown trading symbol." }
  },
  "meta": { "request_id": "req_0123456789abcdef" }
}

پاسخ‌ها Cache-Control: no-store هستند. برای همبستگی لاگ، هدر X-Request-Id با فرمت معتبر را می‌توانید بفرستید؛ در غیر این صورت سرور شناسهٔ تازه می‌سازد.

مدیریت خطا

HTTPCodeمعنا
400INVALID_JSON / IDEMPOTENCY_KEY_REQUIREDبدنهٔ JSON نامعتبر یا نبود کلید idempotency.
401UNAUTHENTICATED / INVALID_TOKEN / TOKEN_EXPIRED / TOKEN_REVOKEDمشکل توکن یا عدم احراز هویت.
403TWO_FACTOR_SETUP_REQUIRED / ACCOUNT_SUSPENDED / FORBIDDENدسترسی مجاز نیست.
404NOT_FOUNDمنبع نیست یا به کاربر دیگری تعلق دارد.
409CONFLICT / LIMIT_REACHED / ACCOUNT_NOT_ACTIVEتعارض وضعیت یا قانون معاملاتی.
413PAYLOAD_TOO_LARGEبدنه بیش از ۶۴ کیلوبایت.
415UNSUPPORTED_MEDIA_TYPEContent-Type باید JSON باشد.
422VALIDATION_ERRORورودی نامعتبر؛ جزئیات در error.details.
429RATE_LIMITED / ACCOUNT_LOCKEDمحدودیت نرخ یا قفل ورود.
500INTERNAL_ERRORخطای پیش‌بینی‌نشده؛ جزئیات فقط در لاگ سرور.

محدودیت نرخ

عملیاتسقفپنجره
ورود API20 / IP900s
تازه‌سازی توکن60 / IP900s
خواندن معاملات و پوزیشن180 / user60s
ثبت/بستن سفارش30 / user60s
ویرایش SL/TP60 / user60s
دادهٔ بازار120 / user60s
اعلان‌ها120 / 3060s
گزارش عملکرد30 / user60s

پاسخ 429 شامل Retry-After و error.details.retry_after است.

صفحه‌بندی، زمان و دقت مالی

  • page از ۱ و per_page بین ۱ تا ۱۰۰ (پیش‌فرض ۲۵)؛ نتیجه در meta.pagination.
  • فیلترهای تاریخ UTC با قالب YYYY-MM-DD و مرتب‌سازی معاملات نزولی بر اساس زمان باز شدن است.
  • مبالغ، قیمت‌ها، حجم و درصدهای پولی به‌صورت رشتهٔ اعشاری برمی‌گردند؛ از float برای محاسبه استفاده نکنید.
  • تاریخ‌ها ISO 8601 با منطقهٔ زمانی صریح (+00:00) هستند.
  • لغزش هر پا به‌صورت entry_slippage / exit_slippage با واحد points | pips | percent می‌آید. slippage_effect اثر خالص ریالی بر P&L است؛ مقدار منفی یعنی هزینه.
  • معاملات قدیمی که پیش از فعال‌شدن موتور لغزش ثبت شده‌اند، این فیلدها را null دارند و هیچ مقدار ساختگی برای آن‌ها ساخته نمی‌شود.

WebSocket و Realtime

مستندات کامل کانال Realtime در docs/api/websocket.md نگهداری می‌شود. این صفحه فقط قرارداد REST را مستند می‌کند. دادهٔ Realtime جنبهٔ اطلاع‌رسانی دارد؛ منبع حقیقت برای موجودی، پوزیشن و P&L همان REST و دیتابیس است.

هیچ ادعای اتصال به فید کارگزار واقعی در این مستندات وجود ندارد.

Endpoint Reference

جست‌وجو، فیلتر و بازکردن جزئیات هر endpoint. نمونه‌ها با داده‌های نمایشی و بدون Secret هستند.

3 مورد
POST /api/v1/auth/login ورود و دریافت توکن Public

ورود با ایمیل و رمز عبور. برای حساب دارای ۲FA، کد TOTP یا کد بازیابی الزامی است. توکن دسترسی کوتاه‌عمر و توکن تازه‌سازی چرخشی برمی‌گردد. این endpoint هیچ Session Cookie ایجاد نمی‌کند.

ModuleAuthentication
AuthenticationNone
CSRFNot required
Permission—

Request Headers

نامنوعالزامیتوضیحمحدودیت / پیش‌فرض
Content-Type string (header) بله application/json —
X-Client-Version string (header) خیر نسخهٔ کلاینت، مثلاً 1.4.0 (اختیاری) —
User-Agent string (header) خیر نام و نسخهٔ دستگاه (برای گزارش نشست‌ها) —

Request Body

نامنوعالزامیتوضیحمحدودیت / پیش‌فرض
email string بله ایمیل حساب حداکثر ۱۹۰ نویسه؛ به حروف کوچک تبدیل می‌شود.
password string بله رمز عبور حداکثر ۲۰۰ نویسه.
client_name string خیر نام نمایشی کلاینت در فهرست نشست‌ها حداکثر ۶۰ نویسه.
totp_code string خیر کد ۶ رقمی TOTP فقط وقتی ۲FA فعال است.
recovery_code string خیر کد بازیابی یک‌بارمصرف به‌جای TOTP قابل استفاده است.

نمونهٔ Request

{
    "email": "trader@example.com",
    "password": "Example-Password-123",
    "client_name": "android-1.4.0",
    "totp_code": "123456"
}

نمونهٔ Response

{
    "success": true,
    "data": {
        "token_type": "Bearer",
        "access_token": "at_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
        "expires_in": 900,
        "refresh_token": "rt_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
        "refresh_expires_in": 2592000,
        "user": {
            "id": 7,
            "name": "نمونه کاربر",
            "email": "trader@example.com",
            "role": "trader",
            "status": "active",
            "email_verified": true,
            "kyc_status": "approved",
            "two_factor_enabled": true,
            "wallet_balance": "1250.00",
            "created_at": "2026-01-12T09:00:00+00:00"
        }
    },
    "meta": {
        "execution_mode": "simulated",
        "request_id": "req_0123456789abcdef"
    }
}

خطاها

StatusCodeشرایط
422 VALIDATION_ERROR ایمیل/رمز خالی یا بدنهٔ نامعتبر.
401 INVALID_CREDENTIALS ایمیل یا رمز عبور نادرست است.
401 TWO_FACTOR_REQUIRED حساب ۲FA دارد اما کد ارسال نشده است.
401 INVALID_TWO_FACTOR_CODE کد TOTP یا کد بازیابی نادرست/مصرف‌شده است.
403 TWO_FACTOR_SETUP_REQUIRED مدیر یا کاربر ملزم به ۲FA هنوز ثبت‌نام نکرده است.
403 ACCOUNT_SUSPENDED حساب تعلیق شده است.
429 ACCOUNT_LOCKED تلاش‌های ناموفق ورود بیش از حد مجاز.
  • محدودیت: ۲۰ درخواست در ۱۵ دقیقه به ازای هر IP.
  • توکن دسترسی و توکن تازه‌سازی را فقط در حافظهٔ امن دستگاه نگه دارید.
<?php
$base = getenv('AURUM_API_BASE') ?: 'https://app.example.com';
$url = $base . '/api/v1/auth/login';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
    'Accept: application/json',
    'Content-Type: application/json',
    ],
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'JSON'
{"email":"trader@example.com","password":"Example-Password-123","client_name":"android-1.4.0","totp_code":"123456"}
JSON,
]);

$raw = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($raw === false) {
    throw new RuntimeException(curl_error($ch));
}
curl_close($ch);

$data = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if ($status >= 400 || empty($data['success'])) {
    throw new RuntimeException($data['error']['message'] ?? ('HTTP ' . $status));
}
print_r($data['data'] ?? $data);
POST /api/v1/auth/refresh چرخش توکن تازه‌سازی Public

یک توکن تازه‌سازی معتبر را می‌سوزاند و جفت توکن جدید برمی‌گرداند. استفادهٔ دوباره از توکن قدیمی کل خانوادهٔ نشست را باطل می‌کند.

ModuleAuthentication
AuthenticationNone
CSRFNot required
Permission—

Request Headers

نامنوعالزامیتوضیحمحدودیت / پیش‌فرض
Content-Type string (header) بله application/json —

Request Body

نامنوعالزامیتوضیحمحدودیت / پیش‌فرض
refresh_token string بله توکن تازه‌سازی دریافتی از ورود/چرخش قبلی با پیشوند rt_ و ۶۴ رقم هگز.
client_name string خیر در صورت ارسال، نام کلاینت به‌روزرسانی می‌شود —

نمونهٔ Request

{
    "refresh_token": "rt_<your-refresh-token>"
}

نمونهٔ Response

{
    "success": true,
    "data": {
        "token_type": "Bearer",
        "access_token": "at_fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
        "expires_in": 900,
        "refresh_token": "rt_fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
        "refresh_expires_in": 2592000,
        "family_id": "0123456789abcdef0123456789abcdef",
        "user": {
            "id": 7,
            "name": "نمونه کاربر",
            "email": "trader@example.com",
            "role": "trader",
            "status": "active",
            "email_verified": true,
            "kyc_status": "approved",
            "two_factor_enabled": true,
            "wallet_balance": "1250.00",
            "created_at": "2026-01-12T09:00:00+00:00"
        }
    },
    "meta": {
        "request_id": "req_0123456789abcdef"
    }
}

خطاها

StatusCodeشرایط
422 VALIDATION_ERROR refresh_token ارسال نشده است.
401 INVALID_REFRESH_TOKEN توکن ناموجود یا نامعتبر است.
401 REFRESH_TOKEN_REUSED توکن قبلاً مصرف شده؛ خانوادهٔ نشست باطل شد.
401 REFRESH_TOKEN_EXPIRED توکن تازه‌سازی منقضی شده است.
401 TOKEN_REVOKED رمز عبور پس از صدور توکن تغییر کرده است.
  • محدودیت: ۶۰ درخواست در ۱۵ دقیقه به ازای هر IP.
<?php
$base = getenv('AURUM_API_BASE') ?: 'https://app.example.com';
$url = $base . '/api/v1/auth/refresh';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
    'Accept: application/json',
    'Content-Type: application/json',
    ],
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'JSON'
{"refresh_token":"rt_<your-refresh-token>"}
JSON,
]);

$raw = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($raw === false) {
    throw new RuntimeException(curl_error($ch));
}
curl_close($ch);

$data = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if ($status >= 400 || empty($data['success'])) {
    throw new RuntimeException($data['error']['message'] ?? ('HTTP ' . $status));
}
print_r($data['data'] ?? $data);
GET /api/v1/meta نسخه و قابلیت‌های API Public

نسخهٔ API، حداقل نسخهٔ کلاینت، قابلیت‌ها و سقف‌های عمومی را برمی‌گرداند. کلاینت می‌تواند پیش از ورود از ناسازگاری باخبر شود.

ModuleSystem & Operations
AuthenticationNone
CSRFNot required
Permission—

نمونهٔ Response

{
    "success": true,
    "data": {
        "api_version": "v1",
        "min_client_version": "1.0.0",
        "latest_client_version": "1.4.0",
        "execution_mode": "simulated",
        "capabilities": {
            "market": true,
            "trading": true,
            "websocket": true,
            "notifications": true,
            "reports": true,
            "live_broker": false
        },
        "limits": {
            "max_per_page": 100,
            "max_candles": 600,
            "idempotency_key_header": "Idempotency-Key"
        },
        "server_time": "2026-10-26T08:05:00+00:00"
    },
    "meta": {
        "request_id": "req_0123456789abcdef"
    }
}
  • execution_mode همیشه simulated است؛ این پلتفرم سفارش را به کارگزار واقعی نمی‌فرستد.
<?php
$base = getenv('AURUM_API_BASE') ?: 'https://app.example.com';
$url = $base . '/api/v1/meta';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
    'Accept: application/json',
    ],
]);

$raw = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($raw === false) {
    throw new RuntimeException(curl_error($ch));
}
curl_close($ch);

$data = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if ($status >= 400 || empty($data['success'])) {
    throw new RuntimeException($data['error']['message'] ?? ('HTTP ' . $status));
}
print_r($data['data'] ?? $data);

یادداشت‌های امنیتی

  • نمایش مستندات مجوز اجرای endpoint نیست؛ سرور مستقل توکن، Session، CSRF، RBAC و مالکیت منبع را بررسی می‌کند.
  • هیچ Token، Secret، رمز، کلید یا دادهٔ Production در این صفحه یا فایل مستندات وجود ندارد.
  • نمونه‌ها فقط Placeholder هستند؛ Credential را از Environment Variable یا Secret Manager بخوانید.
  • برای درخواست‌های تغییردهنده از Idempotency-Key یکتا استفاده کنید.
  • در صورت REFRESH_TOKEN_REUSED کل خانوادهٔ نشست باطل شده است؛ دوباره وارد شوید.
  • مدیران بدون ۲FA به هیچ endpoint محافظت‌شده‌ای دسترسی ندارند و این صفحه نیز مستندات عملیاتی را به آن‌ها نشان نمی‌دهد.

نسخهٔ سند ۱.۰ — 1405/08/04 — فایل مرجع: docs/API_REFERENCE.md