API transakcyjne BitMarket.pl

API transakcyjne BitMarket.pl
Wersja 20140325
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:


market - para walut do handlu (możliwe wartości w tej chwili: "BTCPLN", "LTCPLN").
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.