API transakcyjne BitMarket.pl Wersja 20140402 1. 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 2. 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 Opis 500 Błędne wywołanie HTTP (metodą inną niż POST) 501 Błędny klucz jawny API 502 Błędny podpis wiadomości kluczem tajnym 503 Błędna wartość parametru czasu tonce 504 Klucz nie posiada uprawnień do wykonania tej operacji 505 Nieprawidłowa wartość parametru method 506 Zbyte wiele komend w jednostce czasu 400 Błędna wartość parametru market (para walut do wymiany) 401 Błędna wartość parametru type (rodzaj operacji na giełdzie) 402 Błędna wartość parametru amount (kwota operacji) 403 Błędna wartość parametru rate (kurs wymiany)
404 Kwota operacji jest nieprawidłowa 405 Saldo jest niewystarczające do wykonania operacji 406 Użytkownik nie złożył wskazanej oferty na giełdzie 407 Błędna wartość parametru currency (kod waluty) 408 Błędna wartość parametru count (liczba operacji do pobrania) 409 Błędna wartość parametru start (numer pierwszej operacji do pobrania) 300 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 brak 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 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. 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 id - identyfikator oferty. balances - salda kont po odwołaniu oferty. 2.4. orders - lista złożonych ofert market - para walut do handlu (możliwe wartości w tej chwili: brak, "BTCPLN", "LTCPLN"). 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 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). 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 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). 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.