Gabay sa Pagpapatunay

Alamin kung paano mag-authenticate gamit ang Smart Money API sa pamamagitan ng API keys, JWT tokens, at OAuth 2.0. Siguraduhin ang iyong mga integrasyon gamit ang mga pamantayan sa industriya at pinakamahusay na pamamaraan.

Pangkalahatang-ideya

Ang Smart Money API ay sumusuporta sa maraming paraan ng pagpapatunay para sa iba't ibang kaso ng paggamit. Piliin ang paraan na pinakaangkop sa iyong integrasyon:

Mga API Key (pangunahin): Ipadala ang iyong key sa X-API-Key request header para sa lahat ng REST API calls. Ito ang inirerekomendang paraan para sa mga bot at server-to-server na paggamit.

Session JWT (fallback): Ang mga session sa browser/dashboard ay nagpapatunay gamit ang session JWT sa pamamagitan ng Authorization: Bearer, na may bisa sa loob ng 24 na oras. Ang mga programmatic client ay dapat gumamit ng X-API-Key.

OAuth 2.0: Enterprise-grade na pagpapatunay para sa mga multi-user application at third-party integrations. Pinapayagan ng mga user ang iyong app na ma-access ang kanilang data.

Lahat ng API request ay dapat gawin sa pamamagitan ng HTTPS. Ang mga unencrypted HTTP request ay tatanggihan. Bukod dito, huwag kailanman i-commit ang API keys sa version control o ibahagi ito nang publiko.

Mga API Key

Ang mga API key ay mga natatanging credential na ibinibigay sa iyong account. Ang bawat key ay kumakatawan sa isang set ng mga pahintulot at quota. Maaari kang gumawa ng maraming key para sa iba't ibang application o environment (development, staging, production).

Pag-generate ng API Key

Mag-generate ng API key mula sa iyong account console:

Pumunta sa Smart Money Console
Piliin ang "API Keys" mula sa sidebar
I-click ang "Generate New Key"
Pumili ng uri ng key (Development, Staging, Production)
Itakda ang rate limit at mga feature
Kopyahin at itago ang key nang ligtas

I-save agad ang iyong API key! Hindi mo na ito makikita muli. Kung mawala ito, kailangan mong gumawa ng bagong key.

Format ng Key

Ang mga API key ay sumusunod sa standard na format:

Format ng Key

sk_live_4e3e4d0f1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z
sk_test_8f4g5h6i7j8k9l0m1n2o3p4q5r6s7t8u9v0w1x2y3z4a5b6c7d8e9f
sk_dev_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b

Ang mga prefix ng key ay nagpapahiwatig ng environment:

sk_live_ — Mga production key na may buong quota

sk_test_ — Mga testing key na may reduced quota at development data

sk_dev_ — Mga personal development key na may sandbox data

X-API-Key Header (pangunahin)

Ipadala ang iyong API key sa X-API-Key request header para sa lahat ng API request. Huwag kailanman ilagay ang iyong key sa isang URL.

HTTP Header

HTTP

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

cURL Halimbawa

Shell

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

Python Halimbawa

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 Token Authentication

Para sa long-lived sessions at server-to-server communication, ipagpalit ang iyong API key para sa JWT token. Ang mga JWT token ay may bisa sa 24 na oras at binabawasan ang pangangailangan na itago ang iyong API key sa application code.

Pagkuha ng JWT Token

I-POST ang iyong API key sa JWT endpoint para makakuha ng token:

cURL

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

JWT Response

JSON

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

Paggamit ng JWT Token

Gamitin ang JWT token sa Authorization header tulad ng API keys:

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):
        # 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

Ang OAuth 2.0 ay para sa mga application na nangangailangang ma-access ang multiple user accounts. Pinapayagan ng mga user ang iyong application na ma-access ang kanilang data nang hindi ibinabahagi ang kanilang API keys.

OAuth 2.0 Flow

Ang Smart Money API ay sumusuporta sa Authorization Code flow para sa web applications:

Ang user ay nag-click sa "Connect with Smart Money" button
Ang browser ay nag-redirect sa authorization page
Ang user ay nagbibigay ng pahintulot sa iyong application
Ang browser ay nag-redirect pabalik na may authorization code
Ang iyong backend ay nagpapalit ng code para sa access token
Maaari mo nang ma-access ang user data sa kanilang ngalan

Step 1: Authorization Request

I-redirect ang user sa authorization endpoint:

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

Step 2: Token Exchange

Pagkatapos magbigay ng pahintulot ang user, ipagpalit ang code para sa access token:

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 Token Response

JSON

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

Mga Pinakamahusay na Pamamaraan sa Seguridad

Itago nang Ligtas ang mga Key

Huwag kailanman i-commit ang API keys sa version control, i-hardcode sa mga application, o ibahagi sa documentation. Gamitin ang environment variables o secure key management services tulad ng AWS Secrets Manager, HashiCorp Vault, o katulad.

Gumamit Lamang ng HTTPS

Lahat ng API request ay dapat gumamit ng HTTPS (TLS 1.2 o mas mataas). Ang mga HTTP request ay tatanggihan. Tinitiyak nito na ang iyong API key at data ay naka-encrypt sa transit.

Limitahan ang Mga Pahintulot ng Key

Gumawa ng hiwalay na API key para sa iba't ibang application at environment. Gamitin ang scopes para limitahan kung ano ang maa-access ng bawat key. Huwag gumamit ng production key sa development.

Subaybayan ang Paggamit ng Key

Regular na suriin ang API usage sa iyong console. Mag-set up ng mga alert para sa hindi karaniwang aktibidad o quota na malapit sa limit. Tanggalin ang mga key na hindi mo na ginagamit.

Pag-ikot ng Key

Regular na i-rotate ang iyong API key para mabawasan ang panganib ng compromise. Inirerekomenda naming i-rotate ang key tuwing 90 araw:

Gumawa ng bagong API key sa iyong console
I-update ang iyong mga application para gamitin ang bagong key
I-test na tama ang lahat ng gumagana
I-delete ang lumang key mula sa iyong console

Mga Scope at Permissions

Kapag gumagawa ng API keys o gumagamit ng OAuth, tukuyin kung aling resources ang maa-access ng iyong key:

Scope	Deskripsyon	Tier
whale_positions	Basahin ang mga posisyon ng whale wallet	Trader+
funding_rates	Basahin ang funding rate data	Free+
liquidations	Basahin ang liquidation feeds	Free+
open_interest	Basahin ang open interest data	Trader+
confirmation_scores	Basahin ang AI confirmation scores	Pro+
on_chain	Basahin ang on-chain metrics	Pro+

Mga Halimbawa ng Authentication Code

Kumpletong Python Integration

Python

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

class SmartMoneyAuth:
    """Humahawak ng lahat ng authentication methods para sa 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:
        """Kumuha o i-refresh ang 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:
        """Kumuha ng headers para sa Bearer token auth"""
        return {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

    def headers_jwt(self) -> Dict:
        """Kumuha ng headers para sa 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:
        """Gumawa ng 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()

# Paggamit
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")

Kailangan ng Tulong?

I-review ang aming API documentation o makipag-ugnayan sa support kung kailangan mo ng tulong sa authentication.

API Reference

I-generate ang Iyong Unang API Key

Magsimula sa Smart Money API. Gumawa ng iyong account at gumawa ng authentication credentials sa loob ng ilang minuto.

Pumunta sa Console