MEXC API를 위한 더 안전한 AI 에이전트 워크플로우 구축하기

저는 MEXC API를 중심으로 한 AI 에이전트 워크플로우를 위한 작은 오픈 소스 리포지토리(repo)를 작업해 왔습니다.

이 프로젝트는 "트레이딩 봇 (trading bot)"을 지향하는 것이 아닙니다. 목표는 더 구체적입니다. Claude Code, Codex 스타일의 에이전트 및 이와 유사한 도구들과 같은 코딩 에이전트(coding agents)들이 실제 거래소 API 워크플로우와 작업할 때 더 안전한 구조를 가질 수 있도록 하는 것입니다.

첫 번째 구현 대상은 MEXC입니다.

GitHub 리포지토리:

https://github.com/mncrftfrcnm/mexc-agent-trading-skills

프로젝트 소개

이 리포지토리는 MEXC API 워크플로우와 함께 작동하는 AI 코딩 에이전트를 위한 실험적인 스킬(skills)/프롬프트(prompts)를 포함하고 있습니다.

스킬은 크게 네 가지 영역으로 나뉩니다:

MEXC 현물 REST (MEXC Spot REST)
MEXC 현물 웹소켓 (MEXC Spot WebSocket)
MEXC 선물 REST (MEXC Futures REST)
MEXC 선물 웹소켓 (MEXC Futures WebSocket)

각 스킬은 에이전트가 매번 방대한 API 레퍼런스(API reference)를 읽어야 하는 대신, 더 작고 집중된 명령어 세트를 제공합니다. 또한 이 리포지토리에는 헬퍼 스크립트(helper scripts), 엔드포인트 레시피(endpoint recipes), 웹소켓(WebSocket) 참고 사항, 그리고 자격 증명(credentials) 및 실제 액션(live actions) 처리를 위한 안전 규칙이 포함되어 있습니다.

간단히 말해, 이 스킬들은 에이전트가 다음과 같은 작업을 수행하도록 도울 수 있습니다:

공개 시장 데이터 쿼리 (query public market data)
현물(Spot) 또는 선물(Futures) 잔액과 같은 계정 정보 확인
계정 내 사용 가능한 토큰/자산 확인
서명된 REST 요청(signed REST requests) 생성
환경 변수(environment variables)로부터 로컬 API 자격 증명 사용
실제 요청을 보내기 전 드라이 런 (dry-runs) 사용
실제 현물 주문 전 현물 테스트 주문 (Spot test orders) 사용
시장 데이터, 오더북(order-book) 업데이트, 계정/주문 이벤트에 대한 웹소켓 스트림 (WebSocket streams) 활용
API 키, 서명(signatures), 리슨 키(listen keys) 또는 개인 계정 데이터 출력 방지

핵심 아이디어는 기본적으로 안전하지 않은 행동을 하기 어렵게 만드는 것입니다.

제작 이유

코딩 에이전트는 API와 작업할 때 유용하지만, 실제 거래(live trading) API는 일반적인 개발자용 API와는 다릅니다.

만약 에이전트가 일반적인 테스트 API에 잘못된 요청을 보낸다면, 아마도 그 요청은 그냥 실패하고 끝날 것입니다. 하지만 거래(trading) API에 잘못된 요청을 보낸다면, 원치 않는 주문을 넣거나, 무언가를 취소하거나, 계정 또는 포지션 설정을 변경하거나, 자격 증명(credentials)을 노출하거나, 개인 계정 데이터를 로그에 유출할 수도 있습니다.

이것이 바로 이 리포지토리(repo)가 줄이고자 하는 문제입니다.

이 프로젝트는 더 안전한 기본 설정(defaults)에 집중합니다:

사용자가 채팅창에 API 키를 붙여넣도록 요청하는 대신 로컬 환경 변수(environment variables) 사용
드라이 런(dry-runs) 및 읽기 전용(read-only) 요청을 우선적으로 사용
실제 인증된 쓰기(write) 요청을 수행하기 전 명시적인 확인 요구
드라이 런 출력에서 민감한 값 마스킹(redact)
현물(Spot) 및 선물(Futures) 워크플로우 분리
REST 및 WebSocket 워크플로우 분리
실험적인 영역, 특히 선물(Futures) 실시간 주문(live-order) 워크플로우를 명확하게 표시

리포지토리 구조 (Repo structure)

이 리포지토리는 다양한 에이전트 환경에 맞는 호환 레이아웃을 포함하고 있습니다.

Claude / Claude Code / Claude Desktop를 위해서는 Claude용 스킬(skill) 폴더가 준비되어 있습니다.

Codex 스타일의 리포지토리 에이전트를 위해서는 별도의 Codex 지향 레이아웃이 있습니다.

주요 스킬은 다음과 같습니다:

mexc-spot-rest
mexc-spot-websocket
mexc-futures-rest
...

REST 스킬에는 요청 생성 및 서명(signing)을 위한 로컬 헬퍼 스크립트(helper scripts)가 포함되어 있습니다.

WebSocket 스킬에는 퍼블릭 스트림(public streams), 프라이빗 스트림(private streams), 재연결 동작(reconnect behavior), 리슨 키(listen keys), 오더북(order-book) 업데이트, 그리고 민감한 스트림 데이터 처리 방법에 대한 워크플로우 노트가 포함되어 있습니다.

Spot REST 스킬 포함 내용

Spot REST 스킬은 다음과 같은 일회성 REST API 워크플로우에 집중합니다:

퍼블릭 시장 데이터 (public market data)
서버 시간 (server time)
심볼(symbol) 및 거래소 정보
서명된 계정 읽기 (signed account reads)
잔액 확인 (balance checks)
Spot 테스트 주문 (Spot test orders)
주문 조회 (order lookup)
서명된 요청 생성 (signed request construction)
민감한 값이 마스킹된 드라이 런 출력 (dry-run output with sensitive values redacted)

헬퍼 스크립트는 에이전트가 매번 서명 프로세스를 수동으로 다시 구축할 필요 없이 요청을 생성하고 서명할 수 있도록 설계되었습니다.

Spot WebSocket 스킬 포함 내용

Spot WebSocket 스킬은 실시간 Spot 스트리밍 워크플로우를 위한 것입니다.

다음 내용을 포함합니다:

퍼블릭 거래 스트림 (public trade streams)
티커 (ticker) 및 데프스 (depth) 스트림
Protobuf 기반 퍼블릭 메시지 (protobuf-based public messages)
Listen-key 기반 프라이빗 스트림 (listen-key based private streams)
계정 및 주문 업데이트 (account and order updates)
재연결 동작 (reconnect behavior)
로컬 오더북 복구 (local order-book recovery)
로그 내 Listen-key 노출 방지 (avoiding listen-key exposure in logs)

이는 일반적인 REST 작업에 WebSocket 로직을 혼합하는 대신, 에이전트에게 데이터 스트리밍을 위한 명확한 워크플로우를 제공하기 위함입니다.

Futures REST 스킬 포함 내용

Futures REST 스킬은 다음과 같은 Futures API 워크플로우에 집중합니다:

퍼블릭 계약 데이터 (public contract data)
계약 상세 정보 (contract details)
서버 상태 (server status)
계정 자산 (account assets)
포지션 정보 (position information)
서명된 Futures 요청 (signed Futures requests)
계약 메타데이터 확인 (contract metadata checks)
정밀도 및 레버리지 관련 정보 (precision and leverage-related information)
라이브 워크플로우를 위한 더 안전한 요청 패턴 (safer request patterns for live workflows)

Futures 라이브 주문 지원은 아직 실험적인 단계로 취급됩니다. 엔드포인트의 가용성, 권한 및 유지 관리 상태가 다를 수 있으므로, 리포지토리는 Futures 프라이빗 쓰기 엔드포인트(private write endpoints)에 대해 경고를 유지합니다.

Futures WebSocket 스킬 포함 내용

Futures WebSocket 스킬은 라이브 계약 시장 데이터 및 프라이빗 Futures 이벤트를 위한 것입니다.

다음 내용을 포함합니다:

퍼블릭 계약 스트림 (public contract streams)
티커 (tickers), 거래 (deals), 데프스 (depth), 펀딩 (funding) 및 가격 관련 스트림
프라이빗 계정, 주문 및 포지션 스트림 (private account, order, and position streams)
Ping/Pong 동작 (ping/pong behavior)
재연결 및 재구독 (reconnects and resubscriptions)
스냅샷을 통한 오더북 복구 (order-book recovery from snapshots)
프라이빗 인증 페이로드 및 계정 데이터의 비식별화 (redacting private authentication payloads and account data)

현재 테스트 항목

현재 리포지토리에는 Spot REST 및 Futures REST 요청 서명 헬퍼(request-signing helpers)에 대한 셀프 테스트(self-tests)가 포함되어 있습니다.

CI 워크플로우 또한 다음을 수행합니다:

Spot REST 헬퍼 셀프 테스트 실행
Futures REST 헬퍼 셀프 테스트 실행
Python 파일 컴파일
gitleaks 비밀 정보 스캐닝 (gitleaks secret scanning) 실행
TruffleHog 검증된 비밀 정보 스캐닝 (TruffleHog verified secret scanning) 실행

즉, 리포지토리는 CI에서 로컬 헬퍼 스크립트, Python 구문 및 기본적인 비밀 정보 위생(secret hygiene)을 이미 점검하고 있습니다.

현재 프로젝트 상태:

현물 (Spot) REST 헬퍼 서명: 자체 테스트 완료
선물 (Futures) REST 헬퍼 서명: 자체 테스트 완료
Python 파일: 컴파일 테스트 완료
비밀 정보 스캐닝 (Secret scanning): CI에 포함됨
WebSocket 워크플로우: 문서화되었으며 에이전트 기술 (agent skills)로 구조화됨
라이브 트레이딩 워크플로우: 확인 규칙 및 경고에 의해 보호되며, 프로덕션 준비 완료(production-ready) 상태라고 주장하지 않음

안전 모델 (Safety model)

이 리포지토리(repo)는 에이전트가 무심코 라이브 트레이딩 동작을 수행해서는 안 된다는 아이디어를 중심으로 설계되었습니다.

기본적으로 헬퍼 스크립트는 드라이 런 (dry-run) 동작을 선호합니다. 인증된 라이브 비-GET (non-GET) 요청에는 명시적인 확인 플래그 (confirmation flags)가 필요합니다. API 키, 서명 (signatures), 리슨 키 (listen keys)와 같은 민감한 값은 비공개로 취급되며 로그에 출력하거나 저장해서는 안 됩니다.

또한 이 프로젝트는 다음 사항을 권장합니다:

이 프로젝트를 위한 전용 API 키 사용
출금 권한 비활성화
가능한 경우 IP 제한 설정
최소한의 필수 API 권한만 부여
라이브 테스트를 수행할 경우 아주 작은 테스트 규모 유지
라이브 동작을 수행하기 전 모든 심볼 (symbol), 사이드 (side), 주문 유형 (order type), 가격 (price), 수량 (quantity), 레버리지 (leverage) 및 계정 유형 (account type)을 검토

중요 면책 조항 (Important disclaimer)

이 프로젝트는 비공식적이며 MEXC와 관련이 없습니다.

이는 금융 조언, 투자 조언, 트레이딩 조언이 아니며, 어떠한 자산의 매수, 매도 또는 보유를 권장하는 것도 아닙니다.

라이브 트레이딩 API는 실제 잔고, 주문 및 포지션에 영향을 미칠 수 있습니다. 이 리포지토리는 개발자 실험 및 구조화된 에이전트 워크플로우를 위한 것이며, 관리되지 않는 라이브 트레이딩을 위한 것이 아닙니다.