Authentication Guide

Learn how to authenticate with Smart Money API using API keys, JWT tokens, and OAuth 2.0. Secure your integrations with industry-standard authentication methods and best practices.

Overview

The Smart Money API supports multiple authentication methods for different use cases. Choose the method that best fits your integration:

API Keys (primary): Send your key in the X-API-Key request header for all REST API calls. This is the recommended method for bots and server-to-server use.

Session JWT (fallback): Browser/dashboard sessions authenticate with a session JWT via Authorization: Bearer, valid for 24 hours. Programmatic clients should prefer X-API-Key.

OAuth 2.0: Enterprise-grade authentication for multi-user applications and third-party integrations. Users authorize your app to access their data.

All API requests must be made over HTTPS. Unencrypted HTTP requests will be rejected. Additionally, never commit API keys to version control or share them publicly.

API Keys

API keys are unique credentials issued to your account. Each key represents a single set of permissions and quotas. You can generate multiple keys for different applications or environments (development, staging, production).

Generating an API Key

Generate API keys from your account console:

Navigate to Smart Money Console
Select "API Keys" from the sidebar
Click "Generate New Key"
Choose key type (Development, Staging, Production)
Set rate limit and features
Copy and store the key securely

Save your API key immediately! You won't be able to view it again. If you lose it, you'll need to generate a new key.

Key Format

API keys follow a standard format:

Key Format

sk_live_4e3e4d0f1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z
sk_test_8f4g5h6i7j8k9l0m1n2o3p4q5r6s7t8u9v0w1x2y3z4a5b6c7d8e9f
sk_dev_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b

Key prefixes indicate environment:

sk_live_ — Production keys with full quota

sk_test_ — Testing keys with reduced quota and development data

sk_dev_ — Personal development keys with sandbox data

X-API-Key Header (primary)

Send your API key in the X-API-Key request header for all API requests. Never place your key in a 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 Example

Shell

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

Python Example

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

For long-lived sessions and server-to-server communication, exchange your API key for a JWT token. JWT tokens last 24 hours and reduce the need to store your API key in application code.

Getting a JWT Token

POST your API key to the JWT endpoint to get a 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"
}

Using JWT Token

Use the JWT token in the Authorization header just like 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

OAuth 2.0 is for applications that need to access multiple user accounts. Users grant your application permission to access their data without sharing their API keys.

OAuth 2.0 Flow

Smart Money API supports the Authorization Code flow for web applications:

User clicks "Connect with Smart Money" button
Browser redirects to authorization page
User grants permission to your application
Browser redirects back with authorization code
Your backend exchanges code for access token
You can now access user data on their behalf

Step 1: Authorization Request

Redirect user to the 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

After user grants permission, exchange the code for an 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"
}

Security Best Practices

Store Keys Securely

Never commit API keys to version control, hardcode them in applications, or share them in documentation. Use environment variables or secure key management services like AWS Secrets Manager, HashiCorp Vault, or similar.

Use HTTPS Only

All API requests must use HTTPS (TLS 1.2 or higher). HTTP requests will be rejected. This ensures your API key and data are encrypted in transit.

Limit Key Permissions

Create separate API keys for different applications and environments. Use scopes to limit what each key can access. Don't use production keys in development.

Monitor Key Usage

Regularly review API usage in your console. Set up alerts for unusual activity or quota approaching limits. Delete keys you're no longer using.

Key Rotation

Regularly rotate your API keys to reduce the risk of compromise. We recommend rotating keys every 90 days:

Generate a new API key in your console
Update your applications to use the new key
Test that everything works correctly
Delete the old key from your console

Scopes & Permissions

When creating API keys or using OAuth, specify which resources your key can access:

Scope	Description	Tier
whale_positions	Read whale wallet positions	Trader+
funding_rates	Read funding rate data	Free+
liquidations	Read liquidation feeds	Free+
open_interest	Read open interest data	Trader+
confirmation_scores	Read AI confirmation scores	Pro+
on_chain	Read on-chain metrics	Pro+

Authentication Code Examples

Complete Python Integration

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

Need Help?

Review our API documentation or contact support if you need assistance with authentication.

API Reference

Generate Your First API Key

Get started with Smart Money API. Create your account and generate authentication credentials in minutes.

Go to Console