API transakcyjne BitMarket.pl
Transkrypt
API transakcyjne BitMarket.pl
API transakcyjne BitMarket.pl Wersja 20140402 1. 2. Sposób łączenia się z API ................................................................................................................. 2 1.1. Klucze API ................................................................................................................................ 2 1.2. Podpisywanie wiadomości ...................................................................................................... 2 1.3. Parametr tonce ........................................................................................................................ 2 1.4. Limity zapytań ......................................................................................................................... 3 1.5. Odpowiedzi serwera ................................................................................................................ 3 1.6. Przykładowy kod...................................................................................................................... 3 1.7. Przykładowe zwracane wartości ............................................................................................. 4 1.8. Kody błędów ............................................................................................................................ 4 Lista metod API................................................................................................................................ 5 2.1. info - pobranie informacji o koncie ......................................................................................... 5 2.2. trade - złożenie oferty na giełdzie ........................................................................................... 5 2.3. cancel - odwołanie oferty ........................................................................................................ 6 2.4. orders - lista złożonych ofert ................................................................................................... 6 2.5. history - historia operacji na koncie ........................................................................................ 6 2.6. trades - lista wymian na koncie ............................................................................................... 7 1. Sposób łączenia się z API Aby wywołać funkcję API, należy wysłać żądanie POST na następujący adres: https://www.bitmarket.pl/api2/ Żądanie musi zawierać odpowiednie parametry opisujące operację. Wymaganym parametrem jest parametr method który wskazuje na operację do wykonania, oraz parametr tonce służący do oznaczenia czasu wykonania operacji. Pozostałe parametry definiują sposób wykonania tej operacji, zgodnie z opisem operacji w następnym rozdziale. 1.1. Klucze API Do wywołania każdej operacji API konieczne jest podanie klucza uwierzytelniającego. Klucz ten należy wygenerować na stronie: https://www.bitmarket.pl/apikeys.php Każdy klucz posiada przypisane następujące właściwości: Klucz jawny - jest to widoczny na liście kod, który identyfikuje klucz oraz użytkownika posługującego się kluczem. Klucz tajny - jest to kod służący do podpisywania wiadomości. Kod ten pokazywany jest tylko podczas tworzenia klucza API. Uprawnienia - lista operacji, które możliwe są do wykonania za pomocą klucza. Możliwe jest zawężenie listy dozwolonych operacji, dzięki czemu osoba posługująca się kluczem nie będzie mogła modyfikować stanu konta ani pobierać informacji, do których dany klucz nie ma dostępu. Klucz jawny musi być podany w nagłówku o nazwie API-Key podczas wywołania funkcji API. 1.2. Podpisywanie wiadomości Parametry POST każdej operacji API muszą być podpisane kodem uwierzytelniania wiadomości (HMAC). Służy do tego klucz tajny, który należy wykorzystać do podpisu parametrów za pomocą algorytmu SHA512. Dzięki temu zabezpieczeniu, osoba która pozna klucz jawny API nie będzie nadal mogła wykonywać operacji na koncie nie znając klucza tajnego. Wartość podpisu musi być podana w nagłówku o nazwie API-Hash podczas wywołania funkcji API. 1.3. Parametr tonce Parametr tonce jest obowiązkowy przy wywołaniu każdej operacji API i służy zabezpieczeniu przed atakami odtworzenia wiadomości (replay attacks). Parametr ten musi zawierać liczbę opisującą bieżący czas wywołania operacji API w formacie Unix timestamp. Podczas przetwarzania operacji, wartość ta jest porównywana z bieżącym czasem serwera; jeśli różnica jest większa niż 5 sekund, operacja nie zostanie wykonana. Dzięki temu, osoba która pozna podpis danej operacji nie będzie mogła jej później powtórzyć, ponieważ nie będzie możliwe podanie innej wartości tego parametru. Ze względu na wykorzystanie czasu do zabezpieczenia operacji, niezbędne jest aby czas na komputerze z którego wywoływane są operacje API był aktualny. Ponieważ zegary w wielu komputerach typu PC działają zbyt wolno lub zbyt szybko, wskazane jest użycie synchronizacji z publicznym serwerem czasu NTP, na przykład tempus1.gum.gov.pl. 1.4. Limity zapytań Liczba możliwych do wykonania komend API transakcyjnego jest ograniczona do 200 w 10-minutowej jednostce czasu. Limit ten jest globalny dla całego konta użytkownika, niezależnie od ilości posiadanych i wykorzystywanych kluczy API. 1.5. Odpowiedzi serwera Odpowiedź serwera jest każdorazowo wysyłana w postaci JSON. Jeśli odpowiedź jest poprawna, zawiera ona element success o wartości true, oraz element data zawierający wynik wykonania operacji. Zwracany jest także obiekt limit, który zawiera następujące pola: used - liczba wykonanych komend w wyznaczonej jednostce czasu. allowed - maksymalna dozwolona liczba komend w jednostce czasu. expires - czas (w formacie Unix timestamp) zakończenia wyznaczonej jednostki czasu. Jeśli odpowiedź jest niepoprawna, zawiera element error z numerem błędu, oraz element errorMsg zawierający opis tekstowy błędu. 1.6. Przykładowy kod Przykładowy kod w języku PHP służący do wywołania funkcji API: function bitmarket_api($method, $params = array()) { $key = "klucz_jawny"; $secret = "klucz_tajny"; $params["method"] = $method; $params["tonce"] = time(); $post = http_build_query($params, "", "&"); $sign = hash_hmac("sha512", $post, $secret); $headers = array( "API-Key: " . $key, "API-Hash: " . $sign, ); $curl = curl_init(); curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_setopt($curl, CURLOPT_URL, "https://www.bitmarket.pl/api2/"); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, $post); curl_setopt($curl, CURLOPT_HTTPHEADER, $headers); $ret = curl_exec($curl); return json_decode($ret); } 1.7. Przykładowe zwracane wartości Przykład odpowiedzi poprawnej po wykonaniu operacji info (komenda wykonana poprawnie): { "success":true, "data": { "balances": { "available": { "PLN":4.166000000000, "BTC":0.029140000000, "LTC":10.301000000000 }, "blocked": { "PLN":59.4, "BTC":0, "LTC":0.089 } } }, "limit": { "used" : 1, "allowed" : 200, "expires" : 1395750600, } } Przykład odpowiedzi błędnej (komenda wykonana niepoprawnie): { "error":502, "errorMsg":"Invalid message hash" } 1.8. Kody błędów W aplikacji zdefiniowano następujące kody błędów: Kod 500 501 502 503 504 505 506 400 401 402 403 Opis Błędne wywołanie HTTP (metodą inną niż POST) Błędny klucz jawny API Błędny podpis wiadomości kluczem tajnym Błędna wartość parametru czasu tonce Klucz nie posiada uprawnień do wykonania tej operacji Nieprawidłowa wartość parametru method Zbyte wiele komend w jednostce czasu Błędna wartość parametru market (para walut do wymiany) Błędna wartość parametru type (rodzaj operacji na giełdzie) Błędna wartość parametru amount (kwota operacji) Błędna wartość parametru rate (kurs wymiany) 404 405 406 407 408 409 300 Kwota operacji jest nieprawidłowa Saldo jest niewystarczające do wykonania operacji Użytkownik nie złożył wskazanej oferty na giełdzie Błędna wartość parametru currency (kod waluty) Błędna wartość parametru count (liczba operacji do pobrania) Błędna wartość parametru start (numer pierwszej operacji do pobrania) Wewnętrzny błąd aplikacji - opis błędu znajduje się w parametrze errorMsg 2. Lista metod API Poniżej zaprezentowana jest lista metod aktualnie obsługiwanych przez API. Nazwę metody należy za każdym razem przekazać w parametrze method. 2.1. info - pobranie informacji o koncie Parametry wejściowe: brak Parametry wyjściowe: balances - obiekt opisujący salda kont w poszczególnych walutach: available - obiekt opisujący kwoty dostępne w każdej walucie (PLN, BTC, LTC). blocked - obiekt opisujący kwoty zablokowane w ofertach na giełdzie, w każdej walucie (PLN, BTC, LTC). 2.2. trade - złożenie oferty na giełdzie Parametry wejściowe: market - para walut do handlu (możliwe wartości w tej chwili: "BTCPLN", "LTCPLN"). type - rodzaj operacji: kupno ("bid" lub "buy") lub sprzedaż ("sell" lub "ask"). amount - kwota kryptowaluty do kupna lub sprzedaży. rate - kurs wymiany kryptowaluty. Parametry wyjściowe: id - identyfikator złożonej oferty. order - obiekt opisujący złożoną ofertę: id - identyfikator oferty. market - para walut. amount - kwota kryptowaluty. rate - kurs wymiany kryptowaluty. fiat - kwota przeliczona na walutę fiducjarną (PLN). type - rodzaj oferty ("buy" lub "sell"). time - czas złożenia oferty. balances - salda kont po złożeniu oferty (jak w metodzie info). Podczas składania oferty możliwe są trzy scenariusze: 1) Oferta zostanie zrealizowana w całości, ponieważ na giełdzie znajduje się już zlecenie odwrotne. W takim wypadku pola id oraz order będą puste. 2) Oferta zostanie zrealizowana częściowo. W takim wypadku złożona zostanie oferta odpowiadająca pozostałej części kryptowalut. Pole id zawierać będzie identyfikator złożonej oferty, a pole order jej parametry. 3) Oferta zostanie złożona w całości. Pole id zawierać będzie identyfikator złożonej oferty, a pole order jej parametry (identyczne w tym wypadku z parametrami wejściowymi). 2.3. cancel - odwołanie oferty Parametry wejściowe: id - identyfikator oferty. Parametry wyjściowe: balances - salda kont po odwołaniu oferty. 2.4. orders - lista złożonych ofert Parametry wejściowe: market - para walut do handlu (możliwe wartości w tej chwili: brak, "BTCPLN", "LTCPLN"). Parametry wyjściowe: jeśli podano parametr market, zwracany jest obiekt zawierający podane poniżej pola. Jeśli nie podano tego parametru, zwracany jest obiekt którego polami są nazwy wszystkich możliwych par walut, a wartościami opisane niżej obiekty: buy - lista obiektów opisujących złożone oferty kupna; parametry tych obiektów są identyczne jak w przypadku wartości zwracanych przez metodę order. sell - lista obiektów opisujących złożone oferty kupna; parametry tych obiektów są identyczne jak w przypadku wartości zwracanych przez metodę order. 2.5. history - historia operacji na koncie Parametry wejściowe: currency - kod waluty, dla której pobrana zostanie historia (możliwe wartości w tej chwili to "PLN", "BTC", "LTC"). count - liczba elementów do zwrócenia od 1 do 1000 (domyślnie 1000). start - numer pierwszego elementu, liczony od 0 (domyślnie 0). Parametry wyjściowe: total - liczba wszystkich obiektów w historii operacji. start - numer pierwszej operacji. count - liczba zwróconych operacji. results - lista obiektów opisujących zmiany salda na wskazanym koncie: id - identyfikator operacji. amount - kwota operacji. currency - kod waluty. rate - kurs wymiany (jeśli operacja dotyczy wymiany na giełdzie). commission - pobrana prowizja. time - czas wykonania operacji. type - rodzaj operacji: "deposit" - wpłata na konto. "withdraw" - wypłata z konta. "withdrawCancel" - anulowanie wypłaty z konta. "order" - złożenie oferty na giełdzie. "trade" - wymiana na giełdzie. "cancel" - anulowanie oferty na giełdzie. 2.6. trades - lista wymian na koncie Parametry wejściowe: market - para walut do handlu (możliwe wartości w tej chwili: "BTCPLN", "LTCPLN"). count - liczba elementów do zwrócenia od 1 do 1000 (domyślnie 1000). start - numer pierwszego elementu, liczony od 0 (domyślnie 0). Parametry wyjściowe: total - liczba wszystkich obiektów w historii wymian. start - numer pierwszej wymiany. count - liczba zwróconych obiektów. results - lista obiektów opisujących wymiany na wskazanym rynku dokonane na koncie użytkownika: id - identyfikator wymiany. type - rodzaj wymiany ("buy" - kupno, "sell" - sprzedaż). amountCrypto - kwota wymiany w kryptowalucie. currencyCrypto - kod kryptowaluty. amountFiat - kwota wymiany w walucie fiducjarnej. currencyFiat - kod waluty fiducjarnej. rate - kurs wymiany. time - czas wymiany.