Walutomat API (beta)

Interfejs programistyczny (API) Walutomatu umożliwia automatyzację działań na giełdzie wymiany walut dostępnej w ramach serwisu. Oparty jest o standardową architekturę REST, w której podstawowa linia podziału przebiega pomiędzy wywołaniami odczytującymi stan obiektów - GET a tymi, które modyfikują stan systemu - POST. Metody, które odwołują się do obiektów specyficznych dla użytkownika zabezpieczone są dodatkowym mechanizmem autoryzacji. Wywołania HTTP zwracają kod błędu, interpretacja tych kodów zamieszczona jest poniżej.

Obecna wersja interfejsu ma status testowy i aby z niego skorzystać należy wyrazić taką chcęć kontaktując się uprzednio z naszym biurem obsługi klienta. W przyszłości planujemy udostępnić API szerokiemu gronu naszych klientów.

Informacje ogólne

Słowniki i typy wyliczeniowe

Dostępne waluty
EUR
GBP
USD
CHF
PLN

Pary walutowe na giełdzie
X_Y, gdzie
X=waluta bazowa
Y=waluta kwotowana
EUR_GBP
EUR_USD
EUR_CHF
EUR_PLN
GBP_USD
GBP_CHF
GBP_PLN
USD_CHF
USD_PLN
CHF_PLN

Cena oferty na giełdzie

Cenę oferty określa się zawsze jako stosunek waluty bazowej do kwotowanej. Walutomat.pl pozwala składać oferty kupna/sprzedaży z wolumenem wyrażonym w dowolnej walucie z danej pary, ale cenę należy zawsze podać jako stosunek waluty bazowej do kwotowanej, odpowiedniej dla wybranej pary walutowej.

Usługi publiczne

Oferty z giełdy

GET /api/v1/public/market/orderbook/:pair

nazwa opis
pair patrz dostępne pary walutowe

np. /api/v1/public/market/orderbook/EUR_USD

Odpowiedź zawiera maksymalnie po 10 pozycji po stronie kupna (bids) i sprzedaży (asks), oferty są agregowane po cenie (price) i zawierają wolumeny wyrażone w obydwu walutach.

Przykład:

{
    "pair": "EUR_PLN",
    "bids": [
        {
            "price": "4.3518",
            "baseVolume": "4189.27",
            "marketVolume": "18230.91"
        },
        {
            "price": "4.3378",
            "baseVolume": "2425.37",
            "marketVolume": "10520.79"
        },
        {
            "price": "4.3374",
            "baseVolume": "1653.66",
            "marketVolume": "7172.65"
        }
    ],
    "asks": [
        {
            "price": "4.3545",
            "baseVolume": "3105.86",
            "marketVolume": "13524.46"
        },
        {
            "price": "4.3564",
            "baseVolume": "201.04",
            "marketVolume": "875.80"
        }
    ]
}

Usługi wymagające uwierzytelnienia kluczem współdzielonym

Uwierzytelnienie opera się na parze kluczy:

Instrukcja podpisania i uwierzytelnienia żądania:

Przykład:

uri=/api/v1/market/orders/close/5137bdb7-acde-41ff-aeb2-0908af0bd3d9
ts=1517480182188
body=
echo -n "$uri$ts$body" | openssl dgst -sha256 -binary -hmac 766j0m0hcaz0ml8erklf0ww18 | xxd -p -c 256

# wynik:
b789acef01059fbf40b787be6ce8e7a414a0130106a9dd5eb57c40fd2ea4d80a

Gotowe zapytanie z wygenerowanym podpisem:

apikey=45fzyerg5iyjnseqahocwba18
secret=766j0m0hcaz0ml8erklf0ww18
uri=/api/v1/market/orders/close/5137bdb7-acde-41ff-aeb2-0908af0bd3d9

ts=$(date +%s)000
sign=$(echo -n $uri$ts | openssl dgst -sha256 -binary -hmac $secret | xxd -p -c 256)
curl -i \
  -H "X-API-KEY: $apikey" \
  -H "X-API-NONCE: $ts" \
  -H "X-API-SIGNATURE: $sign" \
  -X POST "https://api.walutomat.pl$uri"

Identyfikator konta klienta

GET /api/v1/account/id

Odpowiedź zawiera identyfikator klienta, powiązany z identyfikatorem API.

Przykład:

"12345678"

Saldo portfela

GET /api/v1/account/balances

Odpowiedź zawiera saldo portfela dla wszystkich par walutowych.

Przykład:

[
    {
        "currency": "EUR",
        "balanceAll": "123.00",
        "balanceAvailable": "79.00",
        "balanceReserved": "44.00"
    },
    {
        "currency": "PLN",
        "balanceAll": "444.00",
        "balanceAvailable": "137.02",
        "balanceReserved": "306.98"
    }
]

Informacja o ofercie

GET /api/v1/market/orders/:orderId

nazwa opis
orderId identyfikator oferty o którą pytamy

np. /api/v1/market/orders/d8f974f4-626c-45fc-b0b9-005ea6541296

Przykład:

{
    "found": true,
    "order": {
        "orderId": "d8f974f4-626c-45fc-b0b9-005ea6541296",
        "submitId": "916f1f98-01f6-412a-85e7-2482f1f4c157",
        "submitTs": "2018-02-02T10:06:01.111Z",
        "updateTs": "2018-02-02T10:06:01.396Z",
        "status": "COMPLETED",
        "market": "EUR_PLN",
        "buySell": "BUY",
        "volume": "15.00",
        "volumeCurrency": "PLN",
        "otherCurrency": "EUR",
        "price": "4.2321",
        "completion": 100,
        "soldAmount": "3.46 EUR",
        "boughtAmount": "15.03 PLN",
        "feeRate": "0.0020",
        "feeAmountMax": "0.03 PLN"
    }
}

Lista aktywnych ofert na giełdzie

GET /api/v1/market/orders

Zwraca listę wszystkich ofert, które są na giełdzie i biorą udział w parowaniu ofert.

Przykład:

[
    {
        "orderId": "2035e361-e672-457a-9c3c-0e86e5ff54d6",
        "submitId": "114f5dd1-0781-44af-acd8-a460d81ed0c1",
        "submitTs": "2018-01-12T13:41:36.160Z",
        "updateTs": "2018-01-12T13:41:36.269Z",
        "status": "MARKET_PUBLISHED",
        "market": "GBP_PLN",
        "buySell": "SELL",
        "volume": "44.00",
        "volumeCurrency": "PLN",
        "otherCurrency": "GBP",
        "price": "5.1503",
        "completion": 0,
        "soldAmount": "0.00 PLN",
        "boughtAmount": "0.00 GBP",
        "feeRate": "0.0020",
        "feeAmountMax": "0.02 GBP"
    }
]

Złożenie oferty na giełdzie

POST /api/v1/market/orders

Walutomat.pl pozwala na złożenie oferty kupna/sprzedaży z dowolnej waluty na dowolną inną wspieraną przez system. Można więc złożyć ofertę kupna lub sprzedaży np.:

Cena zawsze musi być wyrażona zgodnie z tabelą Pary walutowe, patrz cena oferty na giełdzie. W przykładzie powyżej, cena price jest w wyrażona w postaci 4.2321 PLN za 1 EUR zarówno dla oferty kupna i sprzedaży.

Parametry żądania:

nazwa opis
submitId identyfikator żądania (GUID lub UUID), nie może zostać powtórzony dla kolejnych zleceń – spowoduje to uznanie żądania jako duplikat
pair para walutowa
price cena oferty na giełdzie
buySell BUY (kupno) lub SELL (sprzedaż)
volume kwota wyrażona w walucie kupowanej/sprzedawanej
volumeCurrency waluta, w której określona jest kwota
otherCurrency waluta, na którą dokonujemy wymiany

W przypadku, gdy powtórzymy żądanie wykorzystując ten sam submitId – wtedy system uzna to za duplikat (system przeszukuje oferty złożone do 78 godzin wstecz). Mechanizm ten daje możliwość ponownego złożenia tej samej oferty, gdy nie mamy pewności czy poprzednia próba zakończyła się sukcesem, np. w przypadku zerwania połączenia, awarii systemu, itp.

Odpowiedź zawiera identyfikator zlecenia orderId oraz informację o tym, czy żądanie nie zostało potraktowane jako powtórzenie, ze względu na pole submitId.

Przykład:

POST /api/v1/market/orders?submitId=916f1f98-01f6-412a-85e7-2482f1f4c112&pair=EUR_PLN&buySell=BUY&price=4.2321&volume=1.00&volumeCurrency=PLN&otherCurrency=EUR

Sukces:

HTTP/1.1 201 Created
Location: /api/v1/market/orders/22dba34d-d266-4084-9f3e-1b2c7c78c172

{
  "orderId": "22dba34d-d266-4084-9f3e-1b2c7c78c172",
  "duplicate":false
}

Wycofanie/zamknięcie oferty

POST /api/v1/market/orders/close/:orderId

nazwa opis
orderId identyfikator oferty

Zamknięcie oferty, która zakończyła się wcześniej lub została już zamknięta zwraca odpowiedź

HTTP/1.1 404 OPEN_ORDER_NOT_FOUND

Zamknięcie oferty, która nie brała udziału w żadnej wymianie kończy ją statusem WITHDREW, w innym wypadku status będzie CLOSED.

Przykład:

POST /api/v1/market/orders/close/:orderId

Odpowiedź:

HTTP/1.1 200 OK

{
    "orderId": "889f53d8-601a-4fd9-8fab-835317db2b45",
    "submitId": "eb8d0f28-57b1-4974-8c83-d3f047bf6b10",
    "submitTs": "2018-01-30T15:33:07.894Z",
    "updateTs": "2018-02-02T12:10:46.348Z",
    "status": "WITHDREW",
    "market": "EUR_PLN",
    "buySell": "BUY",
    "volume": "2.00",
    "volumeCurrency": "EUR",
    "otherCurrency": "PLN",
    "price": "4.2323",
    "completion": 0,
    "soldAmount": "0.00 PLN",
    "boughtAmount": "0.00 EUR",
    "feeRate": "0.0020",
    "feeAmountMax": "0.01 EUR"
}