Guia de Autenticação

Aprenda a autenticar com a Smart Money API usando chaves de API, tokens JWT e OAuth 2.0. Proteja suas integrações com métodos de autenticação padrão do setor e melhores práticas.

Visão Geral

A Smart Money API suporta múltiplos métodos de autenticação para diferentes casos de uso. Escolha o método que melhor se adapta à sua integração:

Chaves de API (primário): Envie sua chave no X-API-Key cabeçalho da requisição para todas as chamadas da API REST. Este é o método recomendado para bots e uso servidor-para-servidor.

JWT de Sessão (alternativo): Sessões de navegador/dashboard autenticam com um JWT de sessão via Authorization: Bearer, válido por 24 horas. Clientes programáticos devem preferir X-API-Key.

OAuth 2.0: Autenticação de nível empresarial para aplicativos multi-usuário e integrações de terceiros. Os usuários autorizam seu aplicativo a acessar seus dados.

Todas as requisições à API devem ser feitas via HTTPS. Requisições HTTP não criptografadas serão rejeitadas. Além disso, nunca armazene chaves de API em controle de versão ou as compartilhe publicamente.

Chaves de API

Chaves de API são credenciais únicas emitidas para sua conta. Cada chave representa um conjunto único de permissões e cotas. Você pode gerar múltiplas chaves para diferentes aplicações ou ambientes (desenvolvimento, staging, produção).

Gerando uma Chave de API

Gere chaves de API a partir do seu console de conta:

Navegue até Smart Money Console
Selecione "Chaves de API" na barra lateral
Clique em "Gerar Nova Chave"
Escolha o tipo de chave (Desenvolvimento, Staging, Produção)
Defina o limite de taxa e recursos
Copie e armazene a chave com segurança

Salve sua chave de API imediatamente! Você não poderá visualizá-la novamente. Se perdê-la, precisará gerar uma nova chave.

Formato da Chave

As chaves de API seguem um formato padrão:

Formato da Chave

sk_live_4e3e4d0f1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z
sk_test_8f4g5h6i7j8k9l0m1n2o3p4q5r6s7t8u9v0w1x2y3z4a5b6c7d8e9f
sk_dev_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b

Os prefixos das chaves indicam o ambiente:

sk_live_ — Chaves de produção com cota total

sk_test_ — Chaves de teste com cota reduzida e dados de desenvolvimento

sk_dev_ — Chaves de desenvolvimento pessoal com dados de sandbox

Cabeçalho X-API-Key (primário)

Envie sua chave de API no X-API-Key cabeçalho da requisição para todas as chamadas à API. Nunca coloque sua chave em uma URL.

Cabeçalho HTTP

HTTP

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

Exemplo cURL

Shell

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

Exemplo 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()

Autenticação com Token JWT

Para sessões de longa duração e comunicação servidor-para-servidor, troque sua chave de API por um token JWT. Tokens JWT duram 24 horas e reduzem a necessidade de armazenar sua chave de API no código do aplicativo.

Obtendo um Token JWT

Envie sua chave de API via POST para o endpoint JWT para obter um token:

cURL

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

Resposta JWT

JSON

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

Usando o Token JWT

Use o token JWT no cabeçalho Authorization, assim como as chaves de 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):
        # Verifica se o token atual ainda é válido
        if self.token and self.token_expires > datetime.now():
            return self.token

        # Obtém um novo 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)

# Uso
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 é para aplicativos que precisam acessar múltiplas contas de usuário. Os usuários concedem permissão ao seu aplicativo para acessar seus dados sem compartilhar suas chaves de API.

Fluxo OAuth 2.0

A Smart Money API suporta o fluxo Authorization Code para aplicativos web:

Usuário clica no botão "Conectar com Smart Money"
Navegador redireciona para a página de autorização
Usuário concede permissão ao seu aplicativo
Navegador redireciona de volta com um código de autorização
Seu backend troca o código por um token de acesso
Agora você pode acessar os dados do usuário em seu nome

Passo 1: Requisição de Autorização

Redirecione o usuário para o endpoint de autorização:

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

Passo 2: Troca de Token

Após o usuário conceder permissão, troque o código por um token de acesso:

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"

Resposta do Token OAuth

JSON

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

Melhores Práticas de Segurança

Armazene Chaves com Segurança

Nunca armazene chaves de API em controle de versão, as codifique diretamente em aplicativos ou as compartilhe em documentação. Use variáveis de ambiente ou serviços de gerenciamento de chaves seguros como AWS Secrets Manager, HashiCorp Vault ou similares.

Use Apenas HTTPS

Todas as requisições à API devem usar HTTPS (TLS 1.2 ou superior). Requisições HTTP serão rejeitadas. Isso garante que sua chave de API e dados sejam criptografados em trânsito.

Limite Permissões das Chaves

Crie chaves de API separadas para diferentes aplicativos e ambientes. Use escopos para limitar o que cada chave pode acessar. Não use chaves de produção em desenvolvimento.

Monitore o Uso das Chaves

Revise regularmente o uso da API no seu console. Configure alertas para atividades incomuns ou cotas próximas aos limites. Exclua chaves que não estiver mais usando.

Rotação de Chaves

Gire suas chaves de API regularmente para reduzir o risco de comprometimento. Recomendamos girar as chaves a cada 90 dias:

Gere uma nova chave de API no seu console
Atualize seus aplicativos para usar a nova chave
Teste se tudo está funcionando corretamente
Exclua a chave antiga do seu console

Escopos e Permissões

Ao criar chaves de API ou usar OAuth, especifique quais recursos sua chave pode acessar:

Escopo	Descrição	Nível
whale_positions	Ler posições de carteiras de baleias	Trader+
funding_rates	Ler dados de taxas de financiamento	Free+
liquidations	Ler feeds de liquidações	Free+
open_interest	Ler dados de interesse aberto	Trader+
confirmation_scores	Ler pontuações de confirmação de IA	Pro+
on_chain	Ler métricas on-chain	Pro+

Exemplos de Código de Autenticação

Integração Completa em Python

Python

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

class SmartMoneyAuth:
    """Manipula todos os métodos de autenticação para a 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:
        """Obter ou atualizar 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:
        """Obter cabeçalhos para autenticação Bearer token"""
        return {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

    def headers_jwt(self) -> Dict:
        """Obter cabeçalhos para autenticação 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:
        """Fazer requisição autenticada"""
        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()

# Uso
auth = SmartMoneyAuth("sk_live_abc123xyz789")

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

# Método JWT (atualização automática)
whales_jwt = auth.request("GET", "/v1/whales/events?symbol=BTCUSDT", use_jwt=True)

print(f"Encontradas {whales['data']['total']} posições de baleias")

Precisa de ajuda?

Revise nossa documentação da API ou entre em contato com o suporte se precisar de assistência com autenticação.

Referência da API

Gere Sua Primeira Chave de API

Comece com a Smart Money API. Crie sua conta e gere credenciais de autenticação em minutos.

Ir para o Console