目錄
前言
在進入和退出倉位時,了解和使用加密貨幣交易的 API 有助擴展多種不同的可能性。您僅需要一些簡單編碼知識,就可以使用交易所後端程式來自動執行交易策略,更能在不使用網站的情況下更快找到與之相符的高效能應用程式。
本系列旨在向您介紹幣安的 REST API 並教授與之互動的方式。其後,您應該對查詢有關市場和倉位的資訊,以及下達不同類型訂單充滿信心。
在本文中,我們將利用 Postman 與交易所通訊。無需擔心,我們不會將任何真實資金暴露於風險之中。
必備條件
測試網金鑰
我們將使用測試網以達至我們的目的。這將為我們提供一些現實世界中沒有任何價值的資金,其功能與真正代幣完全相同。若您對 API 感到滿意,則可以開始使用它來進行真正資金交易。
首先前往現貨測試網路。
如要獲得存取權限,則您需要使用 GitHub 帳戶登入。如果您還沒有帳戶,請建立一個。
按一下身分驗證並透過 GitHub 登入。
在 API 金鑰下,系統將會告知您尚未註冊任何金鑰。按一下生成 HMAC_SHA256 金鑰可建立一個金鑰對。
在下一個畫面為金鑰新增一個標籤。隨意命名,然後點擊產生 。
您會看到兩個金鑰:API 金鑰和密鑰。由於事關重大,請先將它記錄下來,否則將需要再建立另一組金鑰。我們建議您利用電腦的記事 app 將它儲存起來,以便日後輕鬆複製及貼上。
註:標記金鑰對管理不同金鑰十分重要,因此在真實的交易情況下很值得為此花點時間。您的帳戶可同時具備多種不同權限的金鑰。如果您運行多個交易機器人,或使用帶有描述性標籤的獨立金鑰,則可以更輕鬆地管理權限或將個別金鑰刪除,而無需變更所有交易機器人。
下載並安裝 Postman
Postman 是一個 API 協作平台。由於我們可以存取將要測試的幣安請求集合而無需編寫任何程式碼,這對我們而言是個完美起點。
該程式適用於 Mac、Windows 和 Linux。請前往下載頁面,並下載 .zip 檔案。
完成後,在檔案瀏覽器中查找、安裝並啟動該應用程式,這樣就大功告成了!請注意,您可以建立一個帳戶來登入,但這並非必要步驟。如果想要略過該步驟,選擇視窗底部的選項即可。
建立環境
在此階段,您會看到類似於下列內容的介面。
我們要首先建立環境,這僅是供我們把變數新增至將要使用之請求組的其中一種方法。要完成此步驟,我們首先需要從幣安 GitHub 儲存庫中取得相關資訊:請前往此處,並下載 .zip 檔案。
下載應該不會花很長時間。在檔案瀏覽器中查找該檔案並解壓縮,之後回到 Postman。
按一下右上角的齒輪圖示(如上圖所示),您會看到管理環境彈出式視窗。
選擇匯入 ,然後導覽至剛剛解壓縮的資料夾 (binance-postman-api)。
進入資料夾,然後進入環境資料夾。
現在您會看到兩個檔案(一個用於主網,一個用於測試網)。我們在這裡選擇 binance_com_spot_testnet_api.postman_environment.json。確保您擁有正確的金鑰,因為金鑰不能與其他金鑰混用。
我們快要大功告成了。按一下幣安現貨測試網 API,您將看到以下變數。貼上先前儲存的金鑰,編輯紅色框框內的兩個參數。按一下更新並退出彈出式視窗。
在此畫面上,「時間戳」和「簽名」欄位留空。這兩個值將在每次請求時自動建立。
還有最後一項任務尚待完成。您將在之前點按來設定環境的齒輪圖示右側看到一個下拉式功能表,目前表示無環境。按一下並選擇幣安現貨測試網 API。
匯入集合
現在我們要匯入集合,即我們在交易中需要的各種請求,它們將在我們進行調用時完成繁重工作。將其載入我們的環境中:
按一下左上角的匯入。
在彈出式視窗的檔案標籤下,選擇上傳檔案。
我們再次查找 binance-postman-api 資料夾。查找並開啟該資料夾。
此時,請在子目錄中輸入集合。
這裡又有兩個檔案了。一個可供使用期貨 API。但我們現在使用的是現貨,因此需要選擇 binance_spot_api_v1.postman_collection.json 檔案。
現在您應該會看到一個確認畫面,將匯入的集合標示為 Postman 集合格式。選擇「匯入」。
在視窗左側的「集合」標籤下,您會發現我們有一個包含 100 多種請求的資料夾。恭喜!已經匯入成功了。在下一節中,我們將詳細說明可以提出的各種請求。
提出請求
如果您在「集合」標籤下展開資料夾,會看到可以提出的各種不同請求。從顏色編碼中,您可能會注意到我們可以使用三種方法:
GET:GET(取得)方法可用來擷取伺服器的內容,可用其查詢帳戶餘額、資產價格等資訊。
POST:我們通常使用 POST(發布)在伺服器上建立資訊。而下訂單、請求提現等操作也需要用到。
DELETE:DELETE(刪除)方法可請求伺服器刪除資訊,可隨時用來取消訂單。
尋找幣種清單和交易規則
現在來執行第一個請求!我們將得到可以在交易所進行交易的幣種和交易規則:
GET /exchangeInfo
這項指令不需要任何其他參數,您可以將其複製並貼上到地址列,即會得到回應。但是,若為包含多個參數的請求,Postman 可以輕鬆查看並予以修改。
要加載此請求,請選擇市場 > 交易所資訊。會彈出類似於以下所示的標籤:
在這裡不需要執行任何其他操作,請繼續並點擊發送。您將得到回應:
在最上方的反白顯示部分,您會看到一些重要資訊:
回應狀態(200 表示我們已成功,400-499 表示我們遇到問題)
接收回應所花費的時間(不到一秒鐘)
回應的大小(約 22KB)。
第二個方塊內是回應的主體,已經仔細編排,以便更輕鬆地查看。這包含交易所的資訊、您可以交易的貨幣對及其最小/最大金額。
資訊量看起來很多,但採用這種格式可極為輕鬆地對其進行編程處理。在編寫與之互動的腳本時,可從回應中選取特定元素的特定屬性。
核查帳戶餘額
我們來核查自己所擁有的資產及其相應數量:
GET /account
可以在交易 > 帳戶資訊下找到該選項。按一下會顯示與上一個相似的版面配置,但會看到兩個新變數:時間戳和簽名。簽名是一種安全措施,因為我們正在要求存取敏感資訊,必須證明我們是帳戶持有人。
時間戳會告訴伺服器請求是何時發送的。由於網路可能不穩定或遇到停機情況,因而伺服器收到請求的時間可能比預期的要晚得多。如果時間過長,則會拒絕該請求。您可以使用 recvWindow 參數指定要等待的時長,該參數預設為 5000 毫秒。
Postman 可幫我們處理這兩個欄位。按一下發送即可得到回應。您可以查看六種資產的餘額:BNB、BTC、BUSD、ETH、LTC 和 TRX。餘額將分為可用和鎖定兩部分。我們尚未鎖定任何資產,因此您的資產應全部顯示為可用。
恭喜您獲得了新的(不存在)資產!
如何取得幣種的目前價格
我們可透過不同方式取得資產的目前價格。最簡單的可能是提出以下請求:
GET /api/v3/ticker/24hr
如您所想,以上指令為我們提供過去二十四小時的資產價格資訊。在市場 > 24 小時行情價格變動統計中可以找到該資訊。使用的預設幣種變數為 BTCUSDT。
您可以直接發送此資訊,以查看價格資訊明細。您也可以變更幣種(變更為 BNBBUSD、LTCUSDT等),也可以取消核取變數,以返回 40 交易對的資料。
我們還有一個更簡單的調用(市場 > 幣種價格代號),它會返回資產的目前交易價格:
GET /api/v3/price
與以前一樣,您可以變更幣種變數或將其完全移除,並取得所有幣種的最新價格。
核查目前訂單簿的深度
訂單簿深度(也稱為市場深度或 DOM )可以告訴我們很多市場資訊。我們將調用以下指令來傳回一些有用資訊:
GET api/v3/depth
當我們使用預設值(市場 > 訂單簿)發送此指令時,它會告知我們有關 BTCUSDT 的出價與需求。測試網伺服器不會產生與實際資料一樣多的資料,所以下面是您在實際環境下會看到的螢幕截圖:
在上方的反白顯示部分,我們可以看到第一個出價。由於我們正在查看 BTCUSDT 的訂單簿,上面的數字即某人願意為您的 BTC 支付的價格,下方則為他們願意買入的數量。這就表示,此訂單要求以每 BTC 9704.65 USDT 的價格買下 0.999 BTC。如果繼續向下捲動,我們會看到所報價格逐漸下降,這代表願意支付較少費用的買方。
如果您想要物有所值,最高報價自然是最有吸引力的。比如說,如果您要推銷 3 BTC,只能以最佳價格出售 0.999 BTC,剩下的需要接受其後更為便宜的報價,直到整個訂單履行完畢。
繼續向下捲動,您將看到其他需求。它們與出價的作用相似,不同之處在於它們表示訂單要以 USDT 的價格出售 BTC。
下測試訂單
現在我們要來發布測試訂單。
POST api/v3/order/test
即使我們只使用測試網上的資金,該請求實際上也不會下單。測試網在實際提交訂單之前對測試訂單很有用。在交易 > 測試新訂單 (TRADE) 項下可以找到這個指令。
您可以看到這裡涉及到更多參數。讓我們瀏覽已經核取的參數:
symbol – 我們以前遇到過這個參數,這表示您要交易的貨幣對。
side – 可在此指定要買入還是出售。對於 BTCUSDT 交易對,買入表示您想以 USDT 的價格買入 BTC,而出售則會以 USDT 的價格出售 BTC。
type – 要提交的訂單類型。可能的值(此處已做詳細說明):
LIMIT(限價單)
MARKET(市價單)
STOP_LOSS(止損單)
STOP_LOSS_LIMIT(限價止損單)
TAKE_PROFIT(止盈單)
TAKE_PROFIT_LIMIT(限價止盈單)
LIMIT_MAKER(限價掛單方)
timeInForce– 此參數表示您希望執行訂單的方式:
GTC(取消前有效) – GTC 或許是最受歡迎的設定,將確保您的訂單在履行或取消前一直有效。
FOK(全部成交或取消) – FOK 指示交易所一次完整執行某個訂單。如果交易所無法這樣做,則立即取消訂單。
IOC(立即成交,否則取消) – 必須立即執行全部或部分訂單,否則該訂單將被取消。與 FOK 不同的是,如果訂單可以部分履行,則不會被取消。
quantity – 簡單來說,就是您要買入或出售的資產數量。
price – 您要出售資產的價格。比如在 BTCUSDT 交易對中,價格將以 USDT 表示。
newClientOrderId – 訂單識別碼。這並非必填欄位,但您可以將其設定為一個識別碼,方便您在稍後查詢。否則,交易所會隨機產生該識別碼。
好!我們現在來建立測試訂單。我們需要使用自動產生的數值:以 $9000 USDT 出售 0.1 BTC 的限價單。點擊 [發送]。如果此操作成功,作為回應,我們即可取得 {}。
下達真正的訂單
是時候下達真正的假訂單了。
POST /api/v3/order
導覽至 [交易] > [新訂單]。您現在相當熟悉測試訂單,應該不會意外這裡出現了參數。我們保留原有的數值,但由於我們是長期看漲的投資者,因此會將價格改為以 $40,000 出售。請微調價格數值來反映這一點。然後點擊 [發送]。
如果成功的話,您的回應即會傳回各種訂單詳細資料。
查看未結訂單的狀態
在上一節,我們已確認下達了訂單,但如果稍後想再查看一次,該怎麼辦?我們有幾項可以使用的要求。
GET /api/v3/openOrders
您會在 [交易] > [目前的未結訂單] (USER_DATA) 中找到此端點。預設會選擇 BTCUSDT。點擊 [發送]即會取得所有未結的 BTCUSDT 訂單 (目前為止,只會看到我們先前設定的項目)。您可以選擇不指定幣種,這樣反而會傳回所有的未結訂單。
GET /api/v3/allOrders
[交易] > [所有訂單] (USER_DATA) 將為您概述所有訂單 – 不只是未結訂單。在這裡,您必須提供幣種。orderId、startTime、endTime 及 limit 為可選參數,有助於縮小您的搜尋範圍。在這裡,我們忽略它們,因此請取消核取。點擊 [發送],然後您會看到與之前一樣的回應。如果您有任何關閉或取消的訂單,它們也會顯示在這裡。
最後,我們可以利用下列端點來查詢特定訂單:
GET /api/v3/order
在 [交易] > [查詢訂單] (USER_DATA) 下取得此端點。您必須提供 orderId 或 origClientOrderId (您可以新增至訂單的「newClientOrderId」可選標籤)。取消核取 orderId。再來是 origClientOrderId,我們將提供先前預設標籤 – 「my_order_id_1」。填寫欄位,然後點擊 [發送] 來取得回應。
取消訂單
一段時間過後,我們可能會認為 $40,000 目標有點太過樂觀,因此希望將其取消。在此情況下,則需要使用:
DELETE /api/v3/order
在 [交易] > [取消訂單] 下,會有可讓我們將訂單挑出並取消的要求。取消核取 orderId 和 newClientOrderId,然後將「my_order_id_1」傳遞為 origClientOrderId 的數值。
發送此要求後訂單即會傳回。向下滾動至「狀態」,即可看到該訂單已確實取消。若要確認這一點,請重新使用 GET /api/v3/openOrders 端點 (為您提供空白清單),或是搭配 origClientOrderId 的 GET /api/v3/order。
下達立即成交的訂單
由於先前訂單為限價單,且唯一觸發條件為 BTC 價格達到 $40,000 時,因此該訂單並未成交。如果是市價單,則指的是「以資產目前交易的任意價格買入/出售」。這樣就會立即成交。
因此,我們要返回 [交易] > [新訂單]。我們會展示回應類型 (newOrderRespType),這是可供我們根據預期從伺服器取得的回應加以微調的參數。共有三種選項:ACK、RESULT 或 FULL – 您可以在這裡看到每個回應的範例。接著會使用 ACK,這樣一來,我們就會知道已收到訂單。
您可以在下方看到我們即將提交市價單,以 BUSD 目前的市場價格出售 BNB (幣安幣)。
請注意,回應訊息中給我們的資訊很少:
您可以使用 /api/v3/allOrders 端點來驗證已成交的訂單。
檢查您的交易
最後,我們看一下用來檢查交易的端點:
GET /api/v3/myTrades
位置就在 [交易] > [帳戶交易清單] (USER_DATA) 下方。這可讓您檢查特定幣種的每筆交易。如果您想看到所有預設幣種的交易 (BTCUSDT),只要取消核取 startTime、endTime 及 fromId 即可。接著,回應會傳回多達 500 筆交易 – 若要查看更多筆數,只要隨意微調 limit 即可。
使用 Postman 來偵錯
在 Postman 中,您可以進一步揭露原始的 HTTP 要求和回應。
此選單會開啟 Postman 主控台,接著列印出每項要求的詳細資料。
總結
本指南目的在於深入淺出地向您介紹幣安 API,且不需要編寫任何一行程式碼。如果您跟得上其中的內容,那麼現在應該可以了解我們如何提出要求及提交資訊。
在本系列的下一個章節中,我們會介紹一些基本編碼概念,我們將使用這些編碼自動買賣加密貨幣及其他數位資產。
在此過程中遇到疑難問題?請前往我們日漸茁壯的幣安開發人員社區論壇,也可以查看文件。