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

بیاموزید چگونه با استفاده از کلیدهای API، توکن‌های JWT و OAuth 2.0 با Smart Money API احراز هویت کنید. یکپارچه‌سازی‌های خود را با روش‌های احراز هویت استاندارد صنعتی و بهترین روش‌ها ایمن کنید.

مرور کلی

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 Keys" را انتخاب کنید
روی "Generate New Key" کلیک کنید
نوع کلید را انتخاب کنید (Development, Staging, Production)
تعیین محدودیت نرخ و ویژگی‌ها
کلید را کپی کرده و به‌صورت ایمن ذخیره کنید

کلید 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"

مثال پایتون

پایتون

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 استفاده کنید:

پایتون

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):
        # Check if current token is still valid
        if self.token and self.token_expires > datetime.now():
            return self.token

        # Get new 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)

# Usage
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 از جریان Authorization Code برای برنامه‌های وب پشتیبانی می‌کند:

کاربر روی دکمه "اتصال با 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:
    """Handles all authentication methods for 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:
        """Get or refresh JWT token"""
        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:
        """Get headers for Bearer token auth"""
        return {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

    def headers_jwt(self) -> Dict:
        """Get headers for JWT auth"""
        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:
        """Make authenticated request"""
        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()

# Usage
auth = SmartMoneyAuth("sk_live_abc123xyz789")

# Bearer token method
whales = auth.request("GET", "/v1/whales/events?symbol=BTCUSDT")

# JWT method (auto-refreshing)
whales_jwt = auth.request("GET", "/v1/whales/events?symbol=BTCUSDT", use_jwt=True)

print(f"Found {whales['data']['total']} whale positions")

نیاز به کمک دارید؟

مستندات API ما را مرور کنید یا اگر به کمک در احراز هویت نیاز دارید، با پشتیبانی تماس بگیرید.

مرجع API

اولین کلید API خود را ایجاد کنید

با Smart Money API شروع کنید. حساب کاربری خود را ایجاد کنید و اعتبارنامه‌های احراز هویت را در عرض چند دقیقه ایجاد کنید.

به کنسول بروید