데이터 모델 및 스키마 참조
Smart Money API 데이터 모델에 대한 완벽한 참조 문서입니다. 고래 포지션, 펀딩 비율, 청산, AI 확인 점수를 포함한 모든 응답 객체의 구조와 필드 정의를 확인하세요.
개요
API 응답 구조를 이해하는 것은 통합 구축에 필수적입니다. 이 참조 문서는 모든 데이터 모델 정의, 필드 유형, 제약 조건 및 예시를 설명합니다. 모든 타임스탬프는 ISO 8601 UTC 형식입니다. 모든 가격과 금액은 부동 소수점 정밀도 손실을 방지하기 위해 문자열로 반환됩니다.
고래 포지션 객체
레버리지 거래소에서 모니터링되는 고래 지갑이 보유한 대규모 포지션을 나타냅니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| id | string | 고유 포지션 식별자 |
| wallet_address | string | 고래 지갑 주소 (0x... 형식) |
| exchange | string | bybit, binance 또는 hyperliquid |
| symbol | string | 거래 쌍 (BTCUSDT, ETHUSDT 등) |
| position_type | string | 롱 또는 숏 |
| position_size | string | 기초 자산 단위 크기 (예: BTC) |
| entry_price | string | USDT 기준 평균 진입 가격 |
| current_price | string | USDT 기준 현재 마크 가격 |
| liquidation_price | string | 포지션이 청산되는 가격 |
| pnl | string | USDT 기준 미실현 손익 |
| pnl_percent | number | 미실현 손익 백분율 |
| leverage | integer | 레버리지 배수 (1-20배) |
| margin_balance | string | USDT 기준 총 마진 잔고 |
| used_margin | string | USDT 기준 사용된 마진 |
| available_margin | string | USDT 기준 사용 가능한 마진 |
| margin_ratio | number | 사용 가능한 마진 / 사용된 마진 비율 |
| funding_rate | string | 현재 펀딩 비율 (시간당 %) |
| time_opened | string | 포지션 개시 시점의 ISO 8601 타임스탬프 |
| last_updated | string | 마지막 업데이트 시점의 ISO 8601 타임스탬프 |
고래 포지션 예시
JSON
{
"id": "pos_1a2b3c4d5e6f7g8h",
"wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
"exchange": "bybit",
"symbol": "BTCUSDT",
"position_type": "long",
"position_size": "15.5",
"entry_price": "42150.00",
"current_price": "43200.50",
"liquidation_price": "34560.00",
"pnl": "16577.75",
"pnl_percent": 3.91,
"leverage": 5,
"margin_balance": "129000.00",
"used_margin": "126225.00",
"available_margin": "2775.00",
"margin_ratio": 0.022,
"funding_rate": "0.00012",
"time_opened": "2026-03-15T08:30:00Z",
"last_updated": "2026-03-21T14:35:45Z"
}
펀딩 비율 객체
단일 심볼과 기간에 대한 여러 거래소의 펀딩 비율을 나타냅니다.
JSON
{
"timestamp": "2026-03-21T14:00:00Z",
"symbol": "BTCUSDT",
"bybit": {
"rate": "0.000120",
"next_funding_time": "2026-03-21T16:00:00Z",
"next_rate": "0.000145"
},
"binance": {
"rate": "0.000098",
"next_funding_time": "2026-03-21T16:00:00Z",
"next_rate": "0.000115"
},
"hyperliquid": {
"rate": "0.000140",
"next_funding_time": "2026-03-21T16:00:00Z",
"next_rate": "0.000160"
},
"aggregated": {
"mean": "0.000119",
"median": "0.000120",
"highest": "0.000160",
"lowest": "0.000098",
"spread": "0.000062"
}
}
청산 객체
레버리지 포지션의 강제 청산을 나타냅니다.
JSON
{
"id": "liq_1a2b3c4d5e6f7g8h",
"exchange": "binance",
"symbol": "BTCUSDT",
"direction": "long",
"position_size": "12.5",
"liquidation_price": "41000.00",
"size_usd": "512500.00",
"timestamp": "2026-03-21T14:35:12Z"
}
미결제약정 객체
모든 레버리지 트레이더의 총 미결제약정을 나타냅니다.
JSON
{
"symbol": "BTCUSDT",
"timestamp": "2026-03-21T14:00:00Z",
"total_oi_usd": "12456000000.00",
"long_oi_usd": "7234000000.00",
"short_oi_usd": "5222000000.00",
"long_short_ratio": 1.385,
"oi_change_percent": 2.34,
"exchanges": {
"bybit": {
"long": "3456000000.00",
"short": "2123000000.00"
},
"binance": {
"long": "2567000000.00",
"short": "2234000000.00"
},
"hyperliquid": {
"long": "1211000000.00",
"short": "865000000.00"
}
}
}
확인 점수 객체
고래 포지션, 온체인 데이터, 펀딩 비율 및 시장 심리를 결합한 AI 생성 트레이딩 신호입니다.
JSON
{
"symbol": "BTCUSDT",
"overall_score": 78,
"signal": "bullish",
"confidence": 0.85,
"timestamp": "2026-03-21T14:30:00Z",
"components": {
"whale_score": 82,
"on_chain_score": 75,
"funding_score": 68,
"liquidation_score": 72,
"sentiment_score": 85
},
"reasoning": "대규모 고래 축적과 긍정적인 온체인 신호",
"next_update": "2026-03-21T14:45:00Z"
}
온체인 지표 객체
비트코인과 이더리움에 대한 온체인 분석 데이터입니다.
JSON
{
"asset": "bitcoin",
"timestamp": "2026-03-21T00:00:00Z",
"exchange_flow": {
"inflow_btc": "245.67",
"outflow_btc": "812.34",
"net_flow_btc": "-566.67"
},
"whale_wallets": {
"count": 412,
"total_btc": "1243567.89",
"change_24h": 15.23
},
"mvrv_ratio": 1.42,
"nupl": 0.68,
"realized_price": "42156.50"
}
오류 응답 객체
모든 엔드포인트에 대한 표준 오류 응답 형식입니다.
JSON
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "요청 유효성 검사 실패",
"details": [
{
"field": "symbol",
"error": "잘못된 거래 쌍 형식"
}
],
"resolution": "BTCUSDT와 같은 형식 사용"
},
"timestamp": "2026-03-21T14:35:22Z"
}