Obchodování
Průvodce prvním pokynem: nejkratší cesta jedním požadavkem, volitelné ověření, zadání, sledování stavu a zrušení.
Nejkratší cesta
Pokyn zadá jediný podepsaný požadavek POST /v1/orders s minimálním tělem: symbol, side, type a jedno z polí quantity nebo quoteQuantity. Tržní nákup BTC za 50 EUR:
POST /v1/orders
X-COINERO-APIKEY, X-COINERO-TIMESTAMP, X-COINERO-SIGNATURE
{ "symbol": "BTCEUR", "side": "buy", "type": "market", "quoteQuantity": "50" }Žádný předchozí krok není povinný. Aby opakování po výpadku spojení nezadalo pokyn dvakrát, přidejte do těla clientOrderId (viz níže).
Co budete potřebovat.
trade (a tedy i account), jeho secret a podpis požadavků. Všechny kroky níže kromě prvního vyžadují podpis. Pokyny zadané klíčem jsou vaše pokyny i tehdy, když vzniknou chybou automatizace. Začněte proto malou částkou.První pokyn krok za krokem
Vyberte trh a zjistěte jeho minima
GET /v1/markets vrací trhy, jejich stav a minima. Obchodovat lze trhy se stavem
trading. Minima se řídí burzou a mění se, proto je čtěte před každým zadáním.Ověřte pokyn (volitelné)
POST /v1/orders/validate provede stejné kontroly jako zadání nad stejným tělem: zůstatek, limity, minima, stav účtu a trhu. Pokyn, který kontrolami projde, dostane
valid: truea v poliestimatenezávazný odhad pokynu se stejnými čísly, jaká ukazuje obchodní formulář v aplikaci: částku, kterou získáte nebo zaplatíte, cenu včetně poplatku Coinera, odhad poplatku a kurz u trhů v CZK. Odmítnutý pokyn dostanevalid: falses kódem chyby a doplňkovými poli (napříkladminimumneboavailable).Krok je volitelný, pokyn můžete zadat rovnou. Ověření se nepočítá do limitu zadaných pokynů a nic nerezervuje: cena, zůstatek i trh se mohou do zadání změnit a několik pojistek se ověří až při zadání, takže ani
valid: truezadání nezaručuje. Odhad pokynu není závazná nabídka, pokyn se vypořádá za cenu v okamžiku zadání.Zadejte pokyn
POST /v1/orders zadá pokyn a vrátí HTTP 201 s objektem pokynu a hlavičkou
Location. Pokyn rezervuje částku, kterou utrácí, dokud se nenaplní nebo nezruší. Vždy posílejteclientOrderId(viz níže).Sledujte stav
GET /v1/orders/{orderId} vrací aktuální stav. Místo dotazování můžete odebírat kanál
ordersWebSocketu: začne snímkem otevřených pokynů a pak posílá celý pokyn při každé změně stavu nebo naplnění. Seznam pokynů, například jen otevřených, vrací GET /v1/orders.Zrušte pokyn
DELETE /v1/orders/{orderId} vrací HTTP 202. Zrušení je asynchronní: odpověď nese pokyn tak, jak vypadal při přijetí požadavku, tedy typicky ještě otevřený, a stav se změní na
cancelledaž po potvrzení burzou. Pokud se pokyn mezitím naplnil, skončí ve stavufilled. Opakování požadavku během čekání nevadí.
quantity nebo quoteQuantity
Pokyn zadáváte buď v základní měně trhu (quantity), nebo v kotovací (quoteQuantity); vždy právě jedním z nich. U trhu BTCCZK je základní měna BTC a kotovací CZK.
| Strana | quantity | quoteQuantity |
|---|---|---|
buy | Kolik základní měny chcete získat. | Kolik kotovací měny chcete utratit. |
sell | Kolik základní měny chcete prodat. | Kolik kotovací měny chcete získat. |
Pokyn typu market se provede za aktuální tržní cenu, limit za zadanou cenu nebo lepší. Cena (price) je povinná jen u limitního pokynu a u tržního zakázaná; u trhů v CZK je v CZK. Jiné typy pokynů API nenabízí. Částky a ceny posílejte jako desetinné řetězce s tečkou, například "0.01". Objekt pokynu pak vrací, co jste zadali, v polích requestedQuantity a requestedQuoteQuantity (právě jedno je vyplněné).
clientOrderId a idempotence
Při výpadku spojení nevíte, zda pokyn vznikl. clientOrderId (1 až 64 písmen, číslic, spojovníků a podtržítek, jedinečné pro klíč) chrání zadání před zdvojením: zopakujte požadavek beze změny a dostanete existující pokyn, ne druhý.
| Požadavek | Výsledek |
|---|---|
Nové clientOrderId | HTTP 201, pokyn byl zadán. |
Stejné clientOrderId a stejné parametry | HTTP 200 s existujícím pokynem v jeho aktuálním stavu, nový pokyn nevznikl. |
Stejné clientOrderId a jiné parametry | HTTP 409 CLIENT_ORDER_ID_REUSED, nový pokyn nevznikl. |
Bez clientOrderId | Každý požadavek zadá nový pokyn. |
Pro nový pokyn vždy použijte nové clientOrderId, například s datem a pořadovým číslem. Pokyn zadaný přes API ho nese v poli clientOrderId i v seznamech.
Stavy pokynu
| Stav | Význam |
|---|---|
new | pokyn byl přijat a čeká na odeslání na burzu |
placing | pokyn se odesílá na burzu |
open | pokyn čeká na burze na naplnění |
partiallyFilled | pokyn je zčásti naplněný |
filled | pokyn je naplněný celý; vypořádání může následovat později (viz settled) |
cancelled | pokyn byl zrušen |
expired | platnost pokynu vypršela |
rejected | pokyn byl odmítnut (viz rejectionReason) |
pendingConfirmation | jen pokyn za subúčet: pokyn je přijatý a čeká, až partner potvrdí blokaci prostředků; nic se zatím nezaúčtovalo |
Běžný průběh je new, placing, open, případně partiallyFilled a filled. Pole cancellable říká, zda lze pokyn teď zrušit (jen open a partiallyFilled). Zamítnutý pokyn (rejected) nese důvod v rejectionReason: operationalIssue je dočasný provozní problém, rezervované prostředky se uvolnily a pokyn lze zadat znovu.
filled ještě neznamená, že je pokyn zaúčtovaný. Pole settled je true, až když je pokyn vypořádaný na účtu; do té doby se received může ještě změnit. Zůstatky a konečné částky čtěte z pokynů s settled: true. Neznámou hodnotu stavu zpracujte bez selhání: nové hodnoty mohou ve verzi v1 přibýt.
Objekt pokynu neobsahuje jednotlivá naplnění. Souhrn naplněného pokynu (množství, průměrná cena, poplatek Coinera, spent a received) nese pokyn sám a stejné údaje v podobě obchodu dává GET /v1/account/trades.
Trhy v CZK
Trhy kotované v CZK, například BTCCZK, Coinero provádí na burze přes EUR. Cena i částky jsou v CZK a přepočítávají se klientským kurzem, který je pro pokyn pevný a vidíte ho v poli conversion (rate je počet CZK na 1 EUR, currency je můstková měna). U přímo obchodovaných trhů je conversion null. Průměrná cena naplnění je u trhů v CZK přepočtená kurzem pokynu.
Kniha pokynů, obchody a svíčky trhů v CZK jsou naproti tomu odvozené z trhu EUR středním kurzem bez přirážky a uvádějí to v poli derivedFrom. Jsou to referenční data, ne ceny, za které obchodujete.
Limity
- 60 pokynů za minutu na klíč. Počítá se každý pokus o zadání, i zamítnutý; ověření a zrušení se do něj nepočítají. Při překročení přijde HTTP 429
ORDER_RATE_LIMIT_EXCEEDED. Podrobnosti jsou na stránce Limity požadavků. - Strop otevřených pokynů účtu. Počítají se pokyny z aplikace i ze všech klíčů dohromady; po jeho dosažení vrací zadání
TOO_MANY_OPEN_ORDERS. - Obchodní limit účtu za 24 hodin ve směru pokynu:
TRADING_LIMIT_EXCEEDED. - Minimum trhu z GET /v1/markets:
BELOW_MINIMUM.
Chyby při zadání pokynu
Pokud zadání skončí chybou, pokyn nevznikl a nic se nerezervovalo.
| Kód | Stav | Příčina |
|---|---|---|
INVALID_ORDER | 400 | Chybně sestavené tělo; pole errors uvádí každý problém jako název pole a kód. |
BELOW_MINIMUM | 400 | Pokyn je pod minimem trhu; pole minimum nese nejmenší přijímanou částku. |
INSUFFICIENT_BALANCE | 400 | Dostupný zůstatek nepokrývá pokyn včetně poplatku; pole available nese zůstatek. |
MARKET_NOT_TRADABLE | 400 | Pár je pozastavený, vyřazený nebo dočasně nedostupný. |
CURRENCY_NOT_TRADABLE | 400 | Měnu lze v tomto směru teď obchodovat jen omezeně. |
TRADING_LIMIT_EXCEEDED | 400 | Pokyn by překročil obchodní limit účtu za 24 hodin; pole limit a remaining ho uvádějí. |
TOO_MANY_OPEN_ORDERS | 400 | Účet má nejvyšší počet otevřených pokynů, počítaných napříč aplikací a všemi klíči. |
TRADING_NOT_ALLOWED | 403 | Účet teď nesmí obchodovat; pole reason uvádí důvod. |
UNKNOWN_SYMBOL | 404 | Coinero tento pár neobchoduje, nebo už ho neobchoduje. |
CLIENT_ORDER_ID_REUSED | 409 | Stejné clientOrderId už patří pokynu s jinými parametry. |
CONCURRENT_UPDATE | 409 | Zůstatek účtu ve stejném okamžiku změnila jiná operace; pokyn nevznikl a požadavek je bezpečné zopakovat. |
ORDER_RATE_LIMIT_EXCEEDED | 429 | Klíč zadal v aktuální minutě příliš mnoho pokynů. |
PRICE_UNAVAILABLE | 503 | Chybí aktuální cena nebo kurz; pokyn nevznikl. |
SERVICE_MAINTENANCE | 503 | Obchodování přes API je vypnuté nebo probíhá údržba; pokyn nevznikl. |
Když je obchodování přes API vypnuté, ověření, zadání i zrušení vracejí 503; zůstatky, seznamy pokynů a historie dál fungují. Stav služby ukazuje GET /v1/status.