Získat API klíč
Obchodní API

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.

API klíč s oprávněním 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

  1. 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.

  2. 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: true a v poli estimate nezá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 dostane valid: false s kódem chyby a doplňkovými poli (například minimum nebo available).

    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: true zadání nezaručuje. Odhad pokynu není závazná nabídka, pokyn se vypořádá za cenu v okamžiku zadání.

  3. 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ílejte clientOrderId (viz níže).

  4. Sledujte stav

    GET /v1/orders/{orderId} vrací aktuální stav. Místo dotazování můžete odebírat kanál orders WebSocketu: 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.

  5. 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 cancelled až po potvrzení burzou. Pokud se pokyn mezitím naplnil, skončí ve stavu filled. 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.

StranaquantityquoteQuantity
buyKolik základní měny chcete získat.Kolik kotovací měny chcete utratit.
sellKolik 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žadavekVýsledek
Nové clientOrderIdHTTP 201, pokyn byl zadán.
Stejné clientOrderId a stejné parametryHTTP 200 s existujícím pokynem v jeho aktuálním stavu, nový pokyn nevznikl.
Stejné clientOrderId a jiné parametryHTTP 409 CLIENT_ORDER_ID_REUSED, nový pokyn nevznikl.
Bez clientOrderIdKaž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

StavVýznam
newpokyn byl přijat a čeká na odeslání na burzu
placingpokyn se odesílá na burzu
openpokyn čeká na burze na naplnění
partiallyFilledpokyn je zčásti naplněný
filledpokyn je naplněný celý; vypořádání může následovat později (viz settled)
cancelledpokyn byl zrušen
expiredplatnost pokynu vypršela
rejectedpokyn byl odmítnut (viz rejectionReason)
pendingConfirmationjen 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

Chyby při zadání pokynu

Pokud zadání skončí chybou, pokyn nevznikl a nic se nerezervovalo.

KódStavPříčina
INVALID_ORDER400Chybně sestavené tělo; pole errors uvádí každý problém jako název pole a kód.
BELOW_MINIMUM400Pokyn je pod minimem trhu; pole minimum nese nejmenší přijímanou částku.
INSUFFICIENT_BALANCE400Dostupný zůstatek nepokrývá pokyn včetně poplatku; pole available nese zůstatek.
MARKET_NOT_TRADABLE400Pár je pozastavený, vyřazený nebo dočasně nedostupný.
CURRENCY_NOT_TRADABLE400Měnu lze v tomto směru teď obchodovat jen omezeně.
TRADING_LIMIT_EXCEEDED400Pokyn by překročil obchodní limit účtu za 24 hodin; pole limit a remaining ho uvádějí.
TOO_MANY_OPEN_ORDERS400Účet má nejvyšší počet otevřených pokynů, počítaných napříč aplikací a všemi klíči.
TRADING_NOT_ALLOWED403Účet teď nesmí obchodovat; pole reason uvádí důvod.
UNKNOWN_SYMBOL404Coinero tento pár neobchoduje, nebo už ho neobchoduje.
CLIENT_ORDER_ID_REUSED409Stejné clientOrderId už patří pokynu s jinými parametry.
CONCURRENT_UPDATE409Zůstatek účtu ve stejném okamžiku změnila jiná operace; pokyn nevznikl a požadavek je bezpečné zopakovat.
ORDER_RATE_LIMIT_EXCEEDED429Klíč zadal v aktuální minutě příliš mnoho pokynů.
PRICE_UNAVAILABLE503Chybí aktuální cena nebo kurz; pokyn nevznikl.
SERVICE_MAINTENANCE503Obchodová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.