binance - SKILL.md Agent Skill

name: binance description: "Binance 거래소 API 기본 정보. 마이클이 필요시 도구를 직접 생성하여 사용. 키워드: 바이낸스, binance, 포트폴리오, 잔고, 선물, 거래, spot, futures, balance" allowed-tools: Bash(python3:), Bash(curl:), Read, Write

Binance API Reference

Authentication

환경변수: BINANCE_API_KEY, BINANCE_API_SECRET (.env 파일)

HMAC-SHA256 서명:

import hmac, hashlib, time, requests

API_KEY = os.environ['BINANCE_API_KEY']
API_SECRET = os.environ['BINANCE_API_SECRET']
BASE = 'https://api.binance.com'

def signed_request(method, path, params=None):
    params = params or {}
    params['timestamp'] = int(time.time() * 1000)
    query = '&'.join(f'{k}={v}' for k, v in params.items())
    sig = hmac.new(API_SECRET.encode(), query.encode(), hashlib.sha256).hexdigest()
    query += f'&signature={sig}'
    headers = {'X-MBX-APIKEY': API_KEY}
    url = f'{BASE}{path}?{query}'
    return requests.request(method, url, headers=headers).json()

Core Endpoints

Purpose	Method	Endpoint
Spot 잔고	GET	/api/v3/account
Futures 잔고	GET	/fapi/v2/account
Futures 포지션	GET	/fapi/v2/positionRisk
현재가	GET	/api/v3/ticker/price
Spot 주문	POST	/api/v3/order
Futures 주문	POST	/fapi/v1/order
주문 취소	DELETE	/api/v3/order
거래 내역	GET	/api/v3/myTrades

value_usd 계산법

# Spot
for asset in account['balances']:
    free = float(asset['free'])
    locked = float(asset['locked'])
    total = free + locked
    if asset['asset'] in ('USDT', 'USDC', 'BUSD'):
        value_usd = total
    else:
        price = get_price(f"{asset['asset']}USDT")
        value_usd = total * price

# Futures — IMPORTANT: unrealizedProfit만 사용
for pos in positions:
    notional = abs(float(pos['notional']))  # 레버리지 포함 명목가
    equity = notional / float(pos['leverage'])  # 실제 투자 원금
    unrealized_pnl = float(pos['unrealizedProfit'])
    value_usd = equity + unrealized_pnl  # 이것이 실제 자산 가치

계정 정보

Spot + Futures 통합 계정
Futures: Cross/Isolated 마진
수수료: Maker 0.1%, Taker 0.1% (BNB 할인 시 0.075%)
Rate limit: 1200 requests/min (weight 기반)

주의사항

Futures notional은 레버리지 포함 → equity = notional / leverage
timestamp 오차 1000ms 이내 필요 (서버 시간 동기화)
IP whitelist 권장 (API key 보안)

실전 교훈 (CRITICAL)

Hedge Mode (2026-02-16 발견)

계정이 Hedge mode (dualSidePosition: true)로 설정됨
모든 주문에 positionSide 파라미터 필수: LONG 또는 SHORT
없으면 -4061 "position side does not match" 에러
확인: GET /fapi/v1/positionSide/dual

TAKE_PROFIT_MARKET 사용 불가 (2026-02-16)

/fapi/v1/order에서 TAKE_PROFIT_MARKET 실패: -4120 "use Algo Order API"
STOP_MARKET은 정상 작동 (SL 설정 가능)
해결: TAKE_PROFIT (limit) 타입 사용
- stopPrice + price (stopPrice보다 약간 낮게) + timeInForce: GTE_GTC
- closePosition: true 불가 → quantity 명시 필수

TP 주문 소실 위험

Algo 주문(TAKE_PROFIT_MARKET)은 조건 충족 안 되면 자동 소멸될 수 있음
정기적으로 GET /fapi/v1/openOrders로 TP/SL 존재 확인 필수

스크립트

scripts/check_futures_positions.py — 선물 포지션 + 주문 조회
scripts/set_tp_order.py — TP 주문 설정 (Hedge mode + TAKE_PROFIT LIMIT 대응)