들어가며
이 시리즈의 목적은 바이낸스의 REST API를 소개하는 것이며, 이와 상호 작용하는 방법을 전달하기 위합입니다. 글의 말미에서는 시장과 여러분의 포지션에 대한 정보를 요청하고 다양한 유형의 주문을 자신있게 제출할 수 있게 되기를 바랍니다.
준비 사항
테스트넷 키
우리는 목적에 맞게 테스트넷을 사용할 것입니다. 테스트넷에서는 실제 가치는 없는 자금을 사용해볼 수 있습니다. 테스트 자금은 실제 코인이나 토큰과 정확히 같은 방식으로 작동하기 때문에, API에 익숙해진 다음 실제 자금을 사용해 거래할 수 있습니다.
- 현물 테스트넷 네트워크로 이동합니다.
- 접속을 위해서는 깃허브 계정이 필요합니다. 깃허브 계정이 없다면 생성합니다.
- 인증을 클릭한 다음 깃허브를 통해 가입합니다.
- API 키 아래에서 등록된 키가 없다는 안내를 받을 것입니다. HMAC_SHA256 키 생성을 키 쌍을 생성합니다.
- 다음 화면에서 키에 라벨을 지정합니다. 원하는 이름을 입력하고, 생성 버튼을 클릭합니다.
- API 키와 시크릿 키, 두 가지의 키가 표시될 것입니다. 이를 바로 기록해 둬야 합니다. 그렇지 않으면 키 생성 과정을 다시 시작해야 합니다. 해당 키들을 쉽게 복사해 붙여넣기 하기 위해, 기기의 노트 앱에 저장하는 것을 추천드립니다.
포스트맨 다운로드 및 설치
포스트맨은 API 협력 플랫폼입니다. 우리는 한 줄의 코드도 작성할 필요 없이 테스트하려는 일련의 바이낸스 요청들에 접근할 수 있습니다.
다운로드가 완료되면 여러분의 파일 탐색기에 이를 설치하시기 바랍니다. 애플리케이션을 실행하면, 이제 시작할 준비가 된 것입니다! 로그인을 하려면 계정을 생성해도 되지만, 필수는 아닙니다. 로그인 과정을 건너뛰고 싶다면, 화면 아래에 있는 옵션을 선택하면 됩니다.
환경 생성하기
이번 단계에서는 다음과 같은 인터페이스를 보게 될 것입니다.
다운로드는 오래 걸리지 않을 것입니다. 파일 탐색기에서 해당 파일을 찾아 압축을 풉니다. 그리고 다시 포스트맨으로 돌아옵니다.
- 불러오기(Import)를 클릭한 다음, 조금 전 압축을 푼 폴더를 지정합니다(binance-postman-api).
- 다음으로 환경 설정 폴더를 입력합니다.
- 두 개의 파일을 보게 될 것입니다(하나는 메인넷, 다른 하나는 테스트넷). 우리가 원하는 것은 binance_com_spot_testnet_api.postman_environment.json입니다. 다른 환경에서는 키가 작동하지 않으므로, 정확한 파일을 선택하시기 바랍니다.
해당 창에서 타임스탬프와 서명란은 비워둡니다. 두 값은 요청에 따라 자동으로 생성될 것입니다.
컬렉션 불러오기
이제 우리는 컬렉션을 불러올 것입니다. 컬렉션은 우리가 요청을 진행할 때, 우리를 도와주는 광범위한 요청들을 모아놓은 것입니다. 다음 과정을 통해 이를 우리의 환경으로 불러옵니다.
- 왼쪽 상단 코너의 불러오기(Import)를 클릭합니다.
- 팝업 창이 뜨면, 파일 탭 아래에서 업로드 파일을 선택합니다.
- 다시 한 번 binance-postman-api 폴더를 찾습니다. 위치를 지정하고 이를 엽니다.
- 이번에는 서브디렉토리에 컬렉션(collections)을 입력합니다.
- 다시 한 번 두 개의 파일이 보일 것입니다. 하나는 선물 API를 위한 것입니다. 우리는 현물 거래소에서 작업할 것이므로, binance_spot_api_v1.postman_collection.json 파일을 선택합니다.
- 이제 포스트맨 컬렉션 형식에 불러올 파일들을 확인하는 창이 보일 것입니다. 불러오기(Import)를 클릭합니다.
컬렉션 탭 아래에 있는 왼쪽 창에서 100개 이상의 요청이 있는 폴더를 볼 수 있을 것입니다. 축하드립니다! 잘 진행되었습니다. 다음 섹션에서는 우리가 생성할 수 있는 요청의 종류에 대해 살펴보도록 하겠습니다.
요청하기
컬랙션 탭 아래에 있는 폴더를 확장하면 우리가 생성할 수 있는 다양한 요청들을 발견할 수 있습니다. 컬러 코딩(color-coding)에서 다음과 같이 세 가지 방법을 사용할 수 있다는 것을 발견하실 것입니다.
- GET: GET 메소드는 서버에서 무언가를 검색할 때 사용합니다. 우리는 이를 여러분의 계정 잔고와 자산 가격 등의 정보를 찾는 데 사용할 것입니다.
- POST: POST 메소드는 보통 서버에서 정보를 생성할 때 사용합니다. 이는 주문 배치와 출금 요청 등에 필요합니다.
- DELETE: DELETE 메소드는 서버에 정보 삭제 요청을 할 때 필요합니다. 주문 취소에 유용하게 사용될 것입니다.
심볼과 트레이딩 규칙 목록 찾기
첫 번째 요청을 생성할 시간입니다! 거래소에서 거래할 수 있는 심볼과 트레이딩 규칙을 불러올 것입니다.
GET /exchangeInfo
이는 추가적인 매개 변수를 취하지 않으며, 이를 주소창에 복사해서 붙여 넣으면 응답을 받게 될 것입니다. 여러 매개 변수를 포함시킬 수 있는 요청에 대해, 포스트맨은 이를 쉽게 보고 수정할 수 있게 해줍니다.
가장 위에 하이라이트 표시된 부분에서, 다음과 같은 중요한 정보를 볼 수 있습니다.
- 응답 상태(200은 요청이 성공했다는 의미이며, 400-499는 문제가 있다는 의미)
응답 수신까지 걸린 시간(1초 미만)
응답 크기(~22KB)
두 번째 박스에는 응답들이 모여있습니다. 이는 정갈하게 표시되어 있기 때문에, 눈으로 보기가 쉽습니다. 여기에는 거래소 자체 정보와 거래할 수 있는 거래쌍, 최소/최대 금액이 포함됩니다.
정보가 많은 것 같아 보일 수 있지만, 이는 프로그램적으로 무척 다루기 쉬운 형태입니다. 상호작용을 위한 스크립트를 작성할 때는, 해당 응답에서 특정 요소의 특정 속성을 간단하게 선택할 수 있을 것입니다.
계정 잔고 확인
보유하고 있는 자산과 수량을 확인해 봅시다.
GET /account새로운(실제로는 존재하지 않는) 자산을 얻게 되신 걸 축하드립니다!
심볼의 현재 가격 불러오는 방법
우리는 다양한 방법으로 자산의 현재 가격을 불러올 수 있습니다. 가장 간단한 요청은 다음과 같을 것입니다.
GET /api/v3/ticker/24hrGET /api/v3/price이전과 마찬가지로, 심볼 변수를 변경하거나 이를 모두 삭제할 수 있으며, 모든 심볼의 최신 가격을 불러올 수도 있습니다.
현재 오더북 깊이 확인
오더북 깊이(또는 시장 깊이, DOM)는 시장에 대해 많은 것을 말해줍니다. 우리는 다음을 통해 몇 가지 유용한 정보를 호출할 것입니다.
GET api/v3/depth우리가 이를 기본 값으로 전송할 때(Market > Order Book), 우리는 BTCUSDT 매수 및 매도에 대한 응답을 전송하는 것입니다. 테스트넷 서버는 실제 서버보다 많은 정보를 보내지 않으며, 아래의 스크린샷은 실제 환경에서 보게 되는 것입니다.
위에서 하이라이트 된 영역에서 우리는 첫 번째 매수를 발견할 수 있습니다. 우리는 BTCUSDT 호가창을 보고 있기 때문에, 위의 숫자는 누군가 여러분의 BTC에 대한 대가로 지불할 가격입니다. 아래의 숫자는 구매하고자 하는 수량입니다. 그러므로 이 주문은 9704.65 USDT의 가격에 0.999 BTC를 매수하겠다는 것입니다. 스크롤을 아래로 내리면, 매수 가격이 내려가는 것을 볼 수 있으며, 이는 매수자가 더 적은 금액을 지불하겠다는 의미입니다.
여러분이 가장 매력적인 주문을 찾는다면 이는 가장 위의 주문일 것입니다. 그렇긴 하지만, 여러분이 시장가로 3 BTC를 매도하고자 한다면, 0.999 BTC만을 최고의 가격에 판매할 수 있을 것입니다. 여러분은 주문이 모두 체결될 때까지 이후의 (더 낮은 가격) 주문을 체결시켜야 합니다.
테스트 주문 생성
이제 우리는 테스트 주문을 생성해 볼 것입니다.
POST api/v3/order/test
여러분은 더 많은 매개 변수가 포함되어 있는 것을 볼 수 있을 것입니다. 선택된 항목들을 살펴보겠습니다.
- symbol – 이전에 우연히 이를 본 적이 있습니다. 이는 여러분이 거래하고자 하는 쌍입니다.
- side – 여기서는 여러분의 매수 또는 매도 여부를 결정합니다. BTCUSDT 쌍에서 BUY는 USDT로 BTC를 구매하고 싶다는 것이며, SELL은 BTC를 USDT로 판매하고 싶다는 것입니다.
- type – 여러분이 제출하고자 하는 주문 유형입니다. 가능한 값은 다음과 같습니다(여기에 자세히 설명되어 있음):
- LIMIT
- MARKET
- STOP_LOSS
- STOP_LOSS_LIMIT
- TAKE_PROFIT
- TAKE_PROFIT_LIMIT
- LIMIT_MAKER
- timeInForce– 이는 여러분의 주문을 어떻게 실행할지를 결정하는 매개 변수입니다.
- GTC (good till canceled) – 가장 널리 사용되는 설정 중 하나일 GTC는 주문이 체결되거나 이를 취소하기 전까지 유효한 주문입니다.
- FOK (fill or kill) – FOK 거래소에게 한 번에 주문을 실행하도록 지시합니다. 만약 그럴 수 없다면, 주문이 즉시 취소됩니다.
- IOC (immediate or cancel) – 전부 혹은 일부 주문이 즉시 실행되거나 취소됩니다. FOK와 달리, 일부만 체겨될 수 있다면 주문은 취소되지 않습니다.
- quantity – 여러분이 매수 또는 매도하고자 하는 자산 수량입니다.
- price – 여러분이 매도하고자 하는 가격입니다. BTCUSDT 쌍에서는 USDT로 표시됩니다.
- newClientOrderId – 주문 식별자입니다. 필수 영역은 아니지만, 나중에 쿼리를 쉽게 처리할 수 있도록 식별자로 설정할 수 있습니다. 그렇지 않은 경우, 거래소에 의해 임의로 생성됩니다.
실제 주문 생성
이제 실제 테스트 주문을 배치해보겠습니다.
POST /api/v3/order주문이 성공적이었다면, 여러 세부 정보와 함께 응답이 전송될 것입니다.
미체결 주문 상태 확인
우리는 이전 섹션에서 주문이 생성되었다는 확인을 받았지만, 이후에는 이를 어떻게 확인할 수 있을까요? 우리의 요청을 처리할 몇 가지 방법이 있습니다.
GET /api/v3/openOrdersGET /api/v3/allOrders마지막으로, 특정 주문을 요청할 수 있습니다.
GET /api/v3/order주문 취소
시간이 지난 후, $40,000 목표값이 지나치게 낙관적이었다고 판단하여, 이를 취소하고자 합니다. 이 경우에는 다음을 사용할 수 있습니다.
DELETE /api/v3/order즉시 체결 주문 생성
아래에서는 BNB를 현 시장 가격으로 BUSD를 판매하려는 시장가 주문을 살펴볼 수 있습니다.
해당 응답은 우리에게 최소한의 정보만을 제공한다는 점을 알아둘 필요가 있습니다.
거래 확인
마지막으로 거래를 확인하는 엔드포인트를 살펴보도록 하겠습니다.
GET /api/v3/myTrades포스트맨을 사용한 디버깅
포스트맨에서는 원시 HTTP 요청 및 응답을 추가로 요청할 수 있습니다.
이 메뉴는 각 요청의 세부 정보를 출력하는 포스트맨 콘솔을 엽니다.
마치며
이번 설명의 목적은 한 줄의 코드도 작성하지 않고, 바이낸스 API를 가볍게 설명하기 위함이었습니다. 각 과정들을 잘 따라오셨다면, 정보를 요청하고 제출하는 방법을 아실 것입니다.