Przewodnik uwierzytelniania

Dowiedz się, jak uwierzytelniać się w Smart Money API za pomocą kluczy API, tokenów JWT i OAuth 2.0. Zabezpiecz swoje integracje za pomocą standardowych metod uwierzytelniania i najlepszych praktyk.

Przegląd

Smart Money API obsługuje wiele metod uwierzytelniania dla różnych przypadków użycia. Wybierz metodę, która najlepiej pasuje do Twojej integracji:

Klucze API (podstawowe): Wyślij swój klucz w X-API-Key nagłówku żądania dla wszystkich wywołań REST API. Jest to zalecana metoda dla botów i komunikacji serwer-serwer.

Token sesji JWT (zapasowy): Sesje przeglądarki/pulpitu nawigacyjnego uwierzytelniają się za pomocą tokenu sesji JWT poprzez Authorization: Bearer, ważny przez 24 godziny. Klienci programistyczni powinni preferować X-API-Key.

OAuth 2.0: Uwierzytelnianie klasy enterprise dla aplikacji wieloużytkownikowych i integracji zewnętrznych. Użytkownicy autoryzują Twoją aplikację do dostępu do ich danych.

Wszystkie żądania API muszą być wykonywane przez HTTPS. Niezaszyfrowane żądania HTTP zostaną odrzucone. Dodatkowo, nigdy nie umieszczaj kluczy API w kontroli wersji ani nie udostępniaj ich publicznie.

Klucze API

Klucze API to unikalne poświadczenia wydane dla Twojego konta. Każdy klucz reprezentuje jeden zestaw uprawnień i limitów. Możesz generować wiele kluczy dla różnych aplikacji lub środowisk (rozwój, staging, produkcja).

Generowanie klucza API

Generuj klucze API z konsoli swojego konta:

Przejdź do Smart Money Console
Wybierz "Klucze API" z paska bocznego
Kliknij "Generuj nowy klucz"
Wybierz typ klucza (Rozwój, Staging, Produkcja)
Ustaw limit szybkości i funkcje
Skopiuj i przechowuj klucz bezpiecznie

Zapisz swój klucz API natychmiast! Nie będziesz mógł go ponownie zobaczyć. Jeśli go zgubisz, będziesz musiał wygenerować nowy klucz.

Format klucza

Klucze API mają standardowy format:

Format klucza

sk_live_4e3e4d0f1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z
sk_test_8f4g5h6i7j8k9l0m1n2o3p4q5r6s7t8u9v0w1x2y3z4a5b6c7d8e9f
sk_dev_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b

Prefiksy kluczy wskazują środowisko:

sk_live_ — Klucze produkcyjne z pełnym limitem

sk_test_ — Klucze testowe z ograniczonym limitem i danymi rozwojowymi

sk_dev_ — Klucze rozwojowe osobiste z danymi sandbox

Nagłówek X-API-Key (podstawowy)

Wyślij swój klucz API w X-API-Key nagłówku żądania dla wszystkich żądań API. Nigdy nie umieszczaj swojego klucza w URL.

Nagłówek HTTP

HTTP

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

Przykład cURL

Powłoka

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

Przykład 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()

Uwierzytelnianie tokenem JWT

Długotrwałe sesje i komunikacja serwer-serwer wymieniają klucz API na token JWT. Tokeny JWT są ważne przez 24 godziny i zmniejszają potrzebę przechowywania klucza API w kodzie aplikacji.

Pobieranie tokenu JWT

Wyślij swój klucz API metodą POST do punktu końcowego JWT, aby uzyskać token:

cURL

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

Odpowiedź JWT

JSON

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

Używanie tokenu JWT

Użyj tokenu JWT w nagłówku Authorization tak jak kluczy 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):
        # Sprawdź, czy obecny token jest nadal ważny
        if self.token and self.token_expires > datetime.now():
            return self.token

        # Pobierz nowy 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)

# Użycie
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 jest dla aplikacji, które muszą uzyskać dostęp do wielu kont użytkowników. Użytkownicy przyznają Twojej aplikacji dostęp do swoich danych bez udostępniania swoich kluczy API.

Przepływ OAuth 2.0

Smart Money API obsługuje przepływ kodu autoryzacyjnego dla aplikacji internetowych:

Użytkownik kliknął przycisk "Połącz z Smart Money"
Przeglądarka przekierowuje na stronę autoryzacji
Użytkownik przyznaje uprawnienia Twojej aplikacji
Przeglądarka przekierowuje z powrotem z kodem autoryzacji
Twój backend wymienia kod na token dostępu
Teraz możesz uzyskać dostęp do danych użytkownika w jego imieniu

Krok 1: Żądanie autoryzacji

Przekieruj użytkownika do punktu końcowego autoryzacji:

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

Krok 2: Wymiana tokenu

Po przyznaniu uprawnień przez użytkownika, wymień kod na token dostępu:

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"

Odpowiedź tokenu OAuth

JSON

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

Najlepsze praktyki bezpieczeństwa

Przechowuj klucze bezpiecznie

Nigdy nie umieszczaj kluczy API w kontroli wersji, nie koduj ich na stałe w aplikacjach ani nie udostępniaj ich w dokumentacji. Używaj zmiennych środowiskowych lub bezpiecznych usług zarządzania kluczami, takich jak AWS Secrets Manager, HashiCorp Vault lub podobne.

Używaj tylko HTTPS

Wszystkie żądania API muszą używać HTTPS (TLS 1.2 lub wyższe). Żądania HTTP zostaną odrzucone. Zapewnia to, że Twój klucz API i dane są szyfrowane podczas przesyłania.

Ogranicz uprawnienia kluczy

Twórz osobne klucze API dla różnych aplikacji i środowisk. Używaj zakresów, aby ograniczyć, do czego każdy klucz ma dostęp. Nie używaj kluczy produkcyjnych w środowisku rozwojowym.

Monitoruj użycie kluczy

Regularnie przeglądaj użycie API w swojej konsoli. Skonfiguruj alerty dla nietypowej aktywności lub zbliżania się do limitów. Usuwaj klucze, których już nie używasz.

Rotacja kluczy

Regularnie rotuj swoje klucze API, aby zmniejszyć ryzyko naruszenia. Zalecamy rotację kluczy co 90 dni:

Wygeneruj nowy klucz API w swojej konsoli
Zaktualizuj swoje aplikacje, aby używały nowego klucza
Przetestuj, czy wszystko działa poprawnie
Usuń stary klucz z konsoli

Zakresy i uprawnienia

Podczas tworzenia kluczy API lub korzystania z OAuth określ, do jakich zasobów ma dostęp Twój klucz:

Zakres	Opis	Poziom
whale_positions	Odczyt pozycji portfeli wielorybów	Trader+
funding_rates	Odczyt danych o stopach finansowania	Free+
liquidations	Odczyt danych o likwidacjach	Free+
open_interest	Odczyt danych o otwartym zainteresowaniu	Trader+
confirmation_scores	Odczyt wyników potwierdzenia AI	Pro+
on_chain	Odczyt metryk on-chain	Pro+

Przykłady kodu uwierzytelniania

Kompletna integracja w Pythonie

Python

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

class SmartMoneyAuth:
    """Obsługuje wszystkie metody uwierzytelniania dla 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:
        """Pobierz lub odśwież token 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:
        """Pobierz nagłówki dla autoryzacji Bearer token"""
        return {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

    def headers_jwt(self) -> Dict:
        """Pobierz nagłówki dla autoryzacji 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:
        """Wykonaj uwierzytelnione żądanie"""
        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()

# Użycie
auth = SmartMoneyAuth("sk_live_abc123xyz789")

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

# Metoda JWT (automatyczne odświeżanie)
whales_jwt = auth.request("GET", "/v1/whales/events?symbol=BTCUSDT", use_jwt=True)

print(f"Znaleziono {whales['data']['total']} pozycji wielorybów")

Potrzebujesz pomocy?

Zapoznaj się z dokumentacją API lub skontaktuj się z pomocą techniczną, jeśli potrzebujesz wsparcia w zakresie uwierzytelniania.

Dokumentacja API

Wygeneruj swój pierwszy klucz API

Rozpocznij pracę z Smart Money API. Utwórz konto i wygeneruj dane uwierzytelniające w kilka minut.

Przejdź do konsoli