Руководство по аутентификации

Узнайте, как аутентифицироваться в 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 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"

Пример на 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 поддерживает Authorization Code flow для веб-приложений:

Пользователь нажимает кнопку «Connect with 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

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. Создайте аккаунт и получите учетные данные для аутентификации за считанные минуты.

Перейти в консоль