دليل المصادقة

تعلم كيفية المصادقة مع Smart Money API باستخدام مفاتيح API، رموز JWT، و OAuth 2.0. قم بتأمين تكاملاتك باستخدام طرق المصادقة القياسية وأفضل الممارسات.

نظرة عامة

يدعم Smart Money API طرقًا متعددة للمصادقة لحالات استخدام مختلفة. اختر الطريقة التي تناسب تكاملك بشكل أفضل:

مفاتيح API (الأساسية): أرسل مفتاحك في X-API-Key رأس الطلب لجميع استدعاءات REST API. هذه هي الطريقة الموصى بها للروبوتات واستخدام الخادم إلى الخادم.

جلسة JWT (الاحتياطية): جلسات المتصفح/لوحة التحكم تتم المصادقة باستخدام جلسة JWT عبر Authorization: Bearer، صالحة لمدة 24 ساعة. يجب أن تفضل العملاء البرمجية X-API-Key.

OAuth 2.0: مصادقة على مستوى المؤسسة للتطبيقات متعددة المستخدمين والتكاملات الخارجية. يقوم المستخدمون بتفويض تطبيقك للوصول إلى بياناتهم.

يجب أن تتم جميع طلبات API عبر HTTPS. سيتم رفض الطلبات غير المشفرة عبر HTTP. بالإضافة إلى ذلك، لا تقم أبدًا بإدراج مفاتيح API في التحكم بالإصدار أو مشاركتها علنًا.

مفاتيح API

مفاتيح API هي بيانات اعتماد فريدة يتم إصدارها لحسابك. يمثل كل مفتاح مجموعة واحدة من الصلاحيات والحصص. يمكنك إنشاء مفاتيح متعددة لتطبيقات أو بيئات مختلفة (التطوير، الاختبار، الإنتاج).

إنشاء مفتاح API

قم بإنشاء مفاتيح API من وحدة التحكم الخاصة بحسابك:

انتقل إلى Smart Money Console
اختر "مفاتيح API" من الشريط الجانبي
انقر على "إنشاء مفتاح جديد"
اختر نوع المفتاح (التطوير، الاختبار، الإنتاج)
قم بتعيين حد المعدل والميزات
انسخ المفتاح واحفظه بأمان

احفظ مفتاح API الخاص بك على الفور! لن تتمكن من رؤيته مرة أخرى. إذا فقدته، ستحتاج إلى إنشاء مفتاح جديد.

تنسيق المفتاح

تتبع مفاتيح API تنسيقًا قياسيًا:

تنسيق المفتاح

sk_live_4e3e4d0f1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z
sk_test_8f4g5h6i7j8k9l0m1n2o3p4q5r6s7t8u9v0w1x2y3z4a5b6c7d8e9f
sk_dev_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b

بادئات المفاتيح تشير إلى البيئة:

sk_live_ — مفاتيح الإنتاج مع الحصة الكاملة

sk_test_ — مفاتيح الاختبار مع الحصة المخفضة وبيانات التطوير

sk_dev_ — مفاتيح التطوير الشخصية مع بيانات الساندبوكس

رأس X-API-Key (الأساسي)

أرسل مفتاح API الخاص بك في X-API-Key رأس الطلب لجميع طلبات API. لا تضع مفتاحك في عنوان URL.

رأس HTTP

HTTP

GET /v1/whales/events HTTP/1.1
Host: api.smartmoneyapi.com
X-API-Key: sm_your_key
Content-Type: application/json

مثال cURL

Shell

curl -X GET https://api.smartmoneyapi.com/v1/whales/events \
  -H "X-API-Key: sm_your_key" \
  -H "Content-Type: application/json"

مثال Python

Python

import requests

api_key = "sm_your_key"
headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.smartmoneyapi.com/v1/whales/events",
    headers=headers
)

data = response.json()

مصادقة رمز JWT

لجلسات طويلة الأمد والاتصال من الخادم إلى الخادم، قم بتبادل مفتاح API الخاص بك للحصول على رمز JWT. تستمر رموز JWT لمدة 24 ساعة وتقلل من الحاجة إلى تخزين مفتاح API في كود التطبيق.

الحصول على رمز JWT

أرسل مفتاح API الخاص بك إلى نقطة نهاية JWT للحصول على رمز:

cURL

curl -X POST https://api.smartmoneyapi.com/auth/jwt \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "sk_live_4e3e4d0f1b2c3d4e5f6g7h8i9j0k1l2m"
  }'

استجابة JWT

JSON

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "expires_in": 86400,
  "token_type": "Bearer"
}

استخدام رمز JWT

استخدم رمز JWT في رأس Authorization تمامًا مثل مفاتيح API:

Python

import requests
import json
from datetime import datetime, timedelta

class JWTAuth:
    def __init__(self, api_key):
        self.api_key = api_key
        self.token = None
        self.token_expires = None

    def get_valid_token(self):
        # تحقق مما إذا كان الرمز الحالي لا يزال صالحًا
        if self.token and self.token_expires > datetime.now():
            return self.token

        # الحصول على رمز جديد
        response = requests.post(
            "https://api.smartmoneyapi.com/auth/jwt",
            json={"api_key": self.api_key}
        )

        data = response.json()
        self.token = data["token"]
        self.token_expires = datetime.now() + timedelta(seconds=data["expires_in"])

        return self.token

    def request(self, method, url, **kwargs):
        token = self.get_valid_token()
        headers = kwargs.get("headers", {})
        headers["Authorization"] = f"Bearer {token}"
        kwargs["headers"] = headers

        return requests.request(method, url, **kwargs)

# الاستخدام
auth = JWTAuth("sk_live_4e3e4d0f1b2c3d4e5f6g7h8i9j0k1l2m")
response = auth.request(
    "GET",
    "https://api.smartmoneyapi.com/v1/whales/events"
)
print(response.json())

OAuth 2.0

OAuth 2.0 مخصص للتطبيقات التي تحتاج إلى الوصول إلى حسابات مستخدمين متعددة. يقوم المستخدمون بمنح تطبيقك الإذن للوصول إلى بياناتهم دون مشاركة مفاتيح API الخاصة بهم.

تدفق OAuth 2.0

يدعم Smart Money API تدفق رمز التفويض للتطبيقات الويب:

يقوم المستخدم بالنقر على زر "الاتصال بـ Smart Money"
يقوم المتصفح بإعادة التوجيه إلى صفحة التفويض
يقوم المستخدم بمنح الإذن لتطبيقك
يقوم المتصفح بإعادة التوجيه مع رمز التفويض
يقوم خادمك الخلفي بتبادل الرمز للحصول على رمز الوصول
يمكنك الآن الوصول إلى بيانات المستخدم نيابة عنه

الخطوة 1: طلب التفويض

قم بإعادة توجيه المستخدم إلى نقطة نهاية التفويض:

URL

https://auth.smartmoneyapi.com/authorize?
client_id=YOUR_CLIENT_ID&
redirect_uri=https://yourapp.com/callback&
response_type=code&
scope=whale_positions+funding_rates+liquidations&
state=random_state_string

الخطوة 2: تبادل الرمز

بعد منح المستخدم الإذن، قم بتبادل الرمز للحصول على رمز الوصول:

cURL

curl -X POST https://auth.smartmoneyapi.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=AUTH_CODE&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&redirect_uri=https://yourapp.com/callback"

استجابة رمز OAuth

JSON

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p",
  "scope": "whale_positions funding_rates liquidations"
}

أفضل ممارسات الأمان

قم بتخزين المفاتيح بأمان

لا تقم أبدًا بإدراج مفاتيح API في التحكم بالإصدار أو ترميزها في التطبيقات أو مشاركتها في الوثائق. استخدم متغيرات البيئة أو خدمات إدارة المفاتيح الآمنة مثل AWS Secrets Manager، HashiCorp Vault، أو ما شابه.

استخدم HTTPS فقط

يجب أن تستخدم جميع طلبات API HTTPS (TLS 1.2 أو أعلى). سيتم رفض الطلبات عبر HTTP. هذا يضمن أن مفتاح API وبياناتك مشفرة أثناء النقل.

حدد صلاحيات المفاتيح

قم بإنشاء مفاتيح API منفصلة لتطبيقات وبيئات مختلفة. استخدم النطاقات للحد مما يمكن لكل مفتاح الوصول إليه. لا تستخدم مفاتيح الإنتاج في التطوير.

راقب استخدام المفاتيح

قم بمراجعة استخدام API بانتظام في وحدة التحكم الخاصة بك. قم بإعداد تنبيهات للنشاط غير المعتاد أو اقتراب الحصة من الحدود. احذف المفاتيح التي لم تعد تستخدمها.

تدوير المفاتيح

قم بتدوير مفاتيح API بانتظام لتقليل خطر الاختراق. نوصي بتدوير المفاتيح كل 90 يومًا:

قم بإنشاء مفتاح API جديد في وحدة التحكم الخاصة بك
قم بتحديث تطبيقاتك لاستخدام المفتاح الجديد
اختبر أن كل شيء يعمل بشكل صحيح
احذف المفتاح القديم من لوحة التحكم الخاصة بك

النطاقات والأذونات

عند إنشاء مفاتيح API أو استخدام OAuth، حدد الموارد التي يمكن لمفتاحك الوصول إليها:

النطاق	الوصف	المستوى
whale_positions	قراءة أوضاع محافظ الحيتان	Trader+
funding_rates	قراءة بيانات معدلات التمويل	Free+
liquidations	قراءة تغذية التصفيات	Free+
open_interest	قراءة بيانات الفائدة المفتوحة	Trader+
confirmation_scores	قراءة درجات التأكيد الذكية	Pro+
on_chain	قراءة المقاييس على السلسلة	Pro+

أمثلة رمز المصادقة

تكامل بايثون الكامل

Python

import requests
from typing import Optional, Dict
from datetime import datetime, timedelta

class SmartMoneyAuth:
    """يدير جميع طرق المصادقة لـ Smart Money API"""

    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.smartmoneyapi.com"
        self.jwt_token = None
        self.jwt_expires = None

    def get_jwt_token(self) -> str:
        """الحصول على أو تحديث رمز JWT"""
        if self.jwt_token and self.jwt_expires > datetime.now():
            return self.jwt_token

        response = requests.post(
            f"{self.base_url}/auth/jwt",
            json={"api_key": self.api_key}
        )
        data = response.json()
        self.jwt_token = data["token"]
        self.jwt_expires = datetime.now() + timedelta(seconds=data["expires_in"] - 300)
        return self.jwt_token

    def headers_bearer(self) -> Dict:
        """الحصول على رؤوس لاستخدام رمز Bearer"""
        return {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

    def headers_jwt(self) -> Dict:
        """الحصول على رؤوس لاستخدام رمز JWT"""
        token = self.get_jwt_token()
        return {
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json"
        }

    def request(self, method: str, endpoint: str, use_jwt: bool = False, **kwargs) -> Dict:
        """إجراء طلب مصادقة"""
        headers = self.headers_jwt() if use_jwt else self.headers_bearer()
        response = requests.request(
            method,
            f"{self.base_url}{endpoint}",
            headers=headers,
            **kwargs
        )
        return response.json()

# الاستخدام
auth = SmartMoneyAuth("sk_live_abc123xyz789")

# طريقة رمز Bearer
whales = auth.request("GET", "/v1/whales/events?symbol=BTCUSDT")

# طريقة JWT (تحديث تلقائي)
whales_jwt = auth.request("GET", "/v1/whales/events?symbol=BTCUSDT", use_jwt=True)

print(f"تم العثور على {whales['data']['total']} أوضاع حيتان")

هل تحتاج إلى مساعدة؟

راجع وثائق API الخاصة بنا أو اتصل بالدعم إذا كنت بحاجة إلى مساعدة في المصادقة.

مرجع API

قم بإنشاء أول مفتاح API لك

ابدأ مع Smart Money API. أنشئ حسابك وقم بإنشاء بيانات الاعتماد للمصادقة في دقائق.

انتقل إلى لوحة التحكم