Získat API klíč
Obchodní API

WebSocket

Ceny, kniha pokynů, obchody a změny na účtu v reálném čase místo opakovaného dotazování.

Co budete potřebovat.

API klíč s oprávněním market stačí pro kanály ticker, book a trades. Soukromé kanály (orders, balances, deposits, withdrawals) vyžadují oprávnění account a ověření spojení. Klíč i secret patří na váš server: prohlížeč neumí poslat hlavičku s klíčem při navázání spojení a secret se do něj dostat nesmí.

Připojení

Adresa je wss://publicapi.coinero.cz/v1/ws. Navázání spojení je obyčejný požadavek GET s hlavičkou X-COINERO-APIKEY. Podpis se nepřidává. Spojení se pak povýší na WebSocket. Každé odmítnutí přijde jako běžná chybová odpověď HTTP před povýšením:

StavKódKdy
400INVALID_PARAMETERPožadavek na /v1/ws nežádá o povýšení na WebSocket.
401MISSING_API_KEY, INVALID_API_KEYKlíč chybí nebo neplatí. Klíč zneplatněný před méně než minutou je odmítnutý také.
403IP_NOT_ALLOWEDKlíč je omezený na seznam adres a spojení přichází odjinud.
405METHOD_NOT_ALLOWEDJiná metoda než GET nebo HEAD (HEAD dostane 400 INVALID_PARAMETER).
429RATE_LIMIT_EXCEEDEDNavázání spojení se počítá do obecného limitu klíče.
429TOO_MANY_CONNECTIONSKlíč už má 5 otevřených spojení.
503SERVICE_MAINTENANCEBrána je vypnutá, probíhá údržba nebo je instance plná. Odpověď má hlavičku Retry-After.

Požadavek bez povýšení vrací 400, ne 426: klient se rozhoduje podle kódu chyby, ne podle stavu HTTP. Zprávy po navázání spojení se do limitu požadavků nepočítají.

Tvar zpráv

Každá zpráva je jeden textový rámec s jedním objektem JSON. Na binární rámec a zprávu nad 16 KiB server odpoví chybou a spojení zůstane otevřené. Neznámá pole se ignorují, ale známá pole musí mít správný typ: reqId je celé číslo, ne řetězec.

SměrTvar
Požadavek klienta{ "method", "params", "reqId" }. Metody: subscribe, unsubscribe, auth, ping. reqId je nepovinné číslo, které server vrací v odpovědi.
Odpověď serveru{ "method", "reqId", "success", "result" } nebo místo result objekt error s poli code a detail. method a reqId jsou v odpovědi vždy; mají hodnotu null, když se je ze zprávy nepodařilo přečíst.
Data{ "channel", "type", "seq", "data" }, kde type je snapshot nebo update a data je pole položek.
Úvodní zpráva{ "method": "hello", "nonce", "serverTime", "serverTimeMs", "seq": 0 }

Položky v data mají přesně tvar odpovědi REST: položka kanálu ticker je odpověď GET /v1/ticker, položka kanálu orders objekt pokynu z GET /v1/orders/{orderId} a tak dál. Kód, který zpracovává odpovědi REST, zpracuje i stream.

Server může poslat unsubscribe i sám od sebe. Taková zpráva má reqId: null, success: false, v error důvod a v result odhlášený kanál a symboly. Dnes se to stane jen při vypnutí referenčních tržních dat (kód NOT_FOUND).

Úvodní zpráva a ověření

Hned po povýšení pošle server zprávu hello. Dostane ji každé spojení včetně těch, které ověření nepotřebují. Nese:

  • nonce: výzva, 32 náhodných bajtů v base64url bez doplňku (43 znaků). Platí 30 s a jen jednou.
  • serverTime a serverTimeMs: čas serveru.
  • seq: vždy 0. První datová zpráva má seq 1.

Kanály s oprávněním market ověření nevyžadují. Před odběrem soukromého kanálu odpovězte na výzvu metodou auth:

signature = hex( HMAC-SHA256( secret, nonce ) )

Nepodepisujete kanonický řetězec jako u REST.

Podpis spojení je HMAC-SHA256 nad samotným textem nonce. Žádné časové razítko, metoda ani cesta v něm nejsou. Z podpisu požadavků REST platí jen dvě věci: klíčem HMAC je secret dekódovaný z Base64 a podpis se posílá jako 64 malých nebo velkých hexadecimálních znaků. nonce se podepisuje jako text v ASCII přesně tak, jak přišel, ne jako dekódované bajty.
  • Úspěch: odpověď success: true. Spojení je ověřené a odběr soukromých kanálů je povolený.
  • Chybějící nebo netextový signature: INVALID_PARAMETER. Výzva se nespotřebuje a můžete poslat auth znovu.
  • Podpis jiného tvaru než 64 hexadecimálních znaků, nesprávný podpis nebo výzva starší než 30 s: odpověď INVALID_SIGNATURE a zavření spojení kódem 1008. Výzva je spotřebovaná a další pokus vyžaduje nové spojení.
  • Druhé auth na ověřeném spojení: INVALID_PARAMETER, spojení zůstává.
  • subscribe soukromého kanálu bez auth: SIGNATURE_REQUIRED. Klíč bez oprávnění account: INSUFFICIENT_PERMISSION; oprávnění se kontroluje jako první.

Podpis si v terminálu ověříte přes openssl, stejným postupem jako podpis požadavků, jen nad textem nonce:

printf '%s' "$NONCE" | openssl dgst -sha256 -mac HMAC \
  -macopt hexkey:$(printf '%s' "$COINERO_API_SECRET" | base64 -d | xxd -p -c 256)

Kanály

KanálOprávněníParametrySnapshotUpdate
tickermarketsymbols, nebo all: trueVyžádané symboly, tvar GET /v1/ticker.Změněné symboly; nejvýš jedna zpráva za sekundu na symbol.
bookmarketsymbols, depth (10, 25 nebo 100, výchozí 10)Kniha v hloubce odběru, tvar GET /v1/depth.Celá kniha (ne rozdíl), jen když se změnila.
tradesmarketsymbolsPosledních 50 obchodů od nejstaršího, tvar GET /v1/trades.Dávka nových obchodů za poslední sekundu.
ordersaccount, authžádnéOtevřené pokyny (nejvýš 1000).Celý objekt pokynu při každé změně stavu nebo naplnění.
balancesaccount, authžádnéZůstatky, tvar GET /v1/account/balances.Celý seznam zůstatků při změně; nejvýš jednou za sekundu. Připsání odměny ze stakingu se zatím projeví až s další změnou zůstatku, aktuální hodnotu vrací vždy GET /v1/account/balances.
depositsaccount, authžádnéPrázdný (data: []).Fiat vklad při každé změně stavu, krypto vklad při připsání.
withdrawalsaccount, authžádnéPrázdný (data: []).Fiat výběr při každé změně stavu.

Odběr a snapshot

  • Na každý subscribe server odpoví success a hned za odpovědí pošle snapshot. Po opakovaném subscribe téhož kanálu pošle snapshot znovu.
  • Kvůli neznámému symbolu server odmítne celý požadavek kódem UNKNOWN_SYMBOL, nic se nepřihlásí. Seznam obchodovaných symbolů vrací GET /v1/markets.
  • Když data nejde dočasně přečíst, server odmítne požadavek kódem MARKET_DATA_UNAVAILABLE, nic se nepřihlásí a subscribe zopakujte za chvíli. Stejně skončí soukromý kanál, jehož snapshot se nepodařilo přečíst.
  • Symbol, který se právě nepodařilo ocenit, ve snapshotu chybí a přijde až s prvním updatem.
  • unsubscribe přijímá stejné parametry. U kanálu ticker odhlásí all: true všechno.
  • Soukromé kanály se týkají celého účtu, proto nepřijímají symbols ani all (INVALID_PARAMETER).
  • Kanál ticker slučuje změny: první změna po klidu odejde hned, další změny v téže sekundě se sloučí do jedné zprávy na konci intervalu a vyhrává poslední hodnota.

all: true v kanálu ticker znamená všechny symboly obchodované v okamžiku přihlášení. Trh přidaný později se k odběru nepřidá sám.

Kanály book a trades

Jsou to referenční data burzy, ne ceny, za které obchodujete, a zapínají se spolu s endpointy depth a trades. Když jsou vypnutá, subscribe odpoví success: false s kódem NOT_FOUND. Vypnutí za běhu zruší už existující odběry: do 2 s dostanete za každý kanál zprávu unsubscribe od serveru. Spojení a odběr ticker zůstávají. Po opětovném zapnutí se musíte přihlásit znovu.

  • all: true se u těchto kanálů nepřijímá (INVALID_PARAMETER). Kvůli trhu, jehož data nejdou vydat ani odvodit, server odmítne celý požadavek kódem MARKET_HAS_NO_DEPTH.
  • Snímek knihy má dnes 25 úrovní na stranu, takže depth: 100 vrátí, co snímek obsahuje. Jedno spojení má na symbol jednu hloubku: druhý subscribe téhož symbolu hloubku přepíše a pošle nový snapshot.
  • Update knihy odejde jen tehdy, když se změnilo to, co uvidíte: odběr hloubky 10 nevyvolá zprávy při změnách hlouběji v knize.
  • U trhů v CZK se kniha odvozuje z trhu v EUR kurzem. Po změně kurzu dostanete zprávu typu snapshot s přepočtenou knihou, i když se kniha v EUR nezměnila. Kurz se čte zhruba každých 10 s. Změna se do streamu dostane nejpozději za zhruba 25 s. Obchody už odeslané se nepřepočítávají.
  • Obchody se neopakují: každý tradeId dostanete ve snapshotu nebo v updatu jen jednou. Když se kurz změní uvnitř sekundy, odejdou obchody téhož symbolu ve dvou položkách jedné zprávy, každá s vlastním conversionRate.

Soukromé kanály

  • Položky mají tvar odpovědí REST. Objekt pokynu nemá fills, stejně jako v REST.
  • Pokyny, vklady a výběry se neslučují: každá událost vyvolá jeden update. Dvě události téhož pokynu těsně po sobě mohou přinést dvakrát tentýž objekt.
  • Update hned po snapshotu pokynů může být starší než snapshot (například open u pokynu, který je ve snapshotu už filled). Při rozporu se řiďte pozdější zprávou o stejném orderId, nebo stav ověřte přes GET /v1/orders/{orderId}.
  • Snapshot vkladů a výběrů je prázdný, historii čtěte přes REST. Pohyby, které REST nevydává (platby přes Lightning, pohyby před migrací), nepřijdou ani ve streamu.
  • Deaktivace účtu zavře všechna spojení kódem 1008 INVALID_API_KEY.

Kanály vkladů a výběrů zatím nepokrývají všechno.

Kanál withdrawals zatím vydává jen bankovní výběry, ne výběry kryptoměn. Kanál deposits vydává krypto vklad jen při připsání, ne jeho dřívější stavy (pending, onHold, rejected, failed). Stav takových převodů čtěte z GET /v1/account/withdrawals a GET /v1/account/deposits.

Pořadí zpráv a mezery

Pole seq roste o jedna s každou datovou zprávou na spojení, přes všechny kanály společně. Odpovědi na požadavky ho nemají. Mezera v seq znamená, že jste zprávu nedostali.

Zmeškané zprávy server nedoplňuje. Po mezeře, po výpadku i po vypnutí a zapnutí kanálu postupujte stejně: připojte se znovu (nebo opakujte subscribe). Dostanete čerstvý snapshot; historii, která mezitím vznikla, dočtěte přes REST. U pokynů, vkladů a výběrů použijte filtr from s posledním známým okamžikem.

Ping a pong

Server posílá protokolový ping každých 30 s a spojení, které do dalších 30 s neodpoví pongem, přeruší. Běžné knihovny odpovídají samy. Nečinná spojení se na cestě k serveru zavírají po 100 s, ping je drží otevřená. Knihovna, která protokolové rámce nezpřístupňuje, může posílat zprávu {"method":"ping","reqId":5} a dostane pong se stejným reqId a časem serveru.

Limity

LimitHodnotaPři překročení
Spojení na klíč5Navázání spojení vrací 429 TOO_MANY_CONNECTIONS.
Spojení na instanci API2000Navázání spojení vrací 503 SERVICE_MAINTENANCE. Zkuste to znovu po Retry-After.
Symbolů na spojení100, přes všechny kanálysubscribe skončí kódem TOO_MANY_SUBSCRIPTIONS a nic se nepřihlásí.
Příchozích zpráv10 za sekunduZpráva se zahodí a přijde RATE_LIMIT_EXCEEDED. Třetí sekunda s odmítnutím během 10 s spojení zavře kódem 1008.
Velikost příchozí zprávy16 KiBZpráva se zahodí a přijde INVALID_PARAMETER.
Odchozí fronta1 MiBServer spojení zavře kódem 1008 SLOW_CONSUMER.

Limit symbolů počítá sjednocení symbolů všech kanálů: BTCEUR v kanálech ticker i book je jeden symbol a opakovaný subscribe téhož symbolu se nepočítá znovu. Odběr all: true se počítá jako všechny obchodované symboly, takže u velkého katalogu může překročit limit.

TOO_MANY_SUBSCRIPTIONS a SLOW_CONSUMER existují jen na WebSocketu a nejsou v katalogu chyb. SLOW_CONSUMER znamená, že zprávy nestíháte číst: čtěte zprávy ve vlastním vlákně nebo úloze, těžké zpracování dělejte jinde a nepřihlašujte víc symbolů, než zpracujete.

Zavírací kódy

Důvod zavření je vždy jen strojový kód, aby šel číst automaticky.

KódDůvodKdy a co dělat
1000prázdnýOdpověď na zavření, které začal klient.
1001SERVICE_MAINTENANCEServer se zastavuje (nasazení, restart). Připojte se znovu s odstupem.
1008INVALID_SIGNATURENeplatná nebo prošlá odpověď na výzvu. Před dalším připojením opravte podpis.
1008INVALID_API_KEYKlíč přestal platit (zrušení, pozastavení, expirace, zablokovaný účet). Bez nového klíče se nepřipojujte.
1008RATE_LIMIT_EXCEEDEDOpakované překročení limitu příchozích zpráv. Snižte frekvenci zpráv.
1008SLOW_CONSUMEROdchozí fronta přesáhla limit. Zrychlete čtení.
1013SERVICE_MAINTENANCEBrána je vypnutá nebo probíhá údržba. Zkuste to později.
1013INTERNAL_ERRORNeočekávaná chyba na naší straně. Připojte se znovu s odstupem.

Porušení pravidel nese kód 1008, „zkuste později“ kód 1013. Kód 1006 (spojení spadlo bez zavírací zprávy) generuje vaše knihovna, ne server; zacházejte s ním jako s výpadkem.

Připojení po výpadku

Při každém nasazení Coinera se všechna spojení zavřou kódem 1001, takže znovupřipojení je běžný provoz, ne výjimka. Klient by měl:

  • připojovat se s exponenciálním odstupem od 1 s do 60 s a s náhodným rozptylem, například min(60, 2^pokus) × náhodně 0,5 až 1,0 sekundy, aby se po nasazení nepřipojili všichni klienti ve stejný okamžik;
  • po úspěšném hello odstup vynulovat;
  • po každém hello poslat znovu auth (je-li potřeba) a všechna subscribe, výzva je pokaždé nová;
  • po 429 a 503 při navázání spojení respektovat Retry-After;
  • po 1008 INVALID_API_KEY a INVALID_SIGNATURE se bez opravy příčiny nepřipojovat;
  • po znovupřipojení dočíst zmeškaná data přes REST, viz výše.

Údržba, vypnutí a zneplatnění klíče

  • Vypnutí nebo údržba: navázání spojení vrací 503 SERVICE_MAINTENANCE s Retry-After a otevřená spojení se do 2 s zavřou kódem 1013. Stav brány ukazuje komponenta stream ve stavu služby.
  • Zneplatnění klíče: spojení klíče, který byl zrušen, pozastaven nebo vypršel, se zavře kódem 1008 INVALID_API_KEY, nejpozději do 60 s.
  • Výpadek zdroje dat: komponenta stream přejde do stavu degraded. Spojení zůstávají, dostanete snapshot, ale updaty nemusí chodit.

Ukázky klienta

Ukázky se připojí s klíčem, odebírají ticker, po auth odebírají orders, vypisují snapshot a updaty, kontrolují seq a po mezeře nebo zavření se připojí znovu s odstupem. Klíč a secret čtou z proměnných prostředí COINERO_API_KEY a COINERO_API_SECRET (secret v Base64, jako u podpisu požadavků). Bez secretu běží jen ticker. Adresu lze přepsat proměnnou COINERO_WS_URL.

  • JavaScript potřebuje Node.js 22 nebo novější. Používá vestavěný WebSocket, takže se nic neinstaluje. Ten stav HTTP odmítnutého navázání spojení nevidí: klient po pěti neúspěšných pokusech bez hello skončí a nelze v něm rozlišit 401 od 429 ani číst Retry-After. Předání hlavičky s klíčem jako druhý argument konstruktoru je rozšíření Node.js, které prohlížeč nemá.
  • Python stav HTTP vidí (401 a 403 ukončí klienta, 429 a 503 respektují Retry-After). Potřebuje balíček websockets verze 14 nebo novější: pip install "websockets>=14".
// Klient WebSocketu Coinera: ticker bez ověření, po auth i kanál orders.
// Potřebuje Node.js 22 nebo novější (vestavěný WebSocket), žádný balíček navíc.
// Spuštění: COINERO_API_KEY=... COINERO_API_SECRET=... node websocket-client.mjs
import { createHmac } from "node:crypto";

const WS_URL = process.env.COINERO_WS_URL ?? "wss://publicapi.coinero.cz/v1/ws";
const API_KEY = process.env.COINERO_API_KEY;
const API_SECRET = process.env.COINERO_API_SECRET; // Base64, jako u podpisu REST; bez něj běží jen ticker
const MAX_FAILED_CONNECTS = 5; // po sobě jdoucí pokusy bez hello, pak klient skončí

if (!API_KEY) {
  console.error("Nastavte proměnnou prostředí COINERO_API_KEY.");
  process.exit(1);
}

// Po těchto důvodech zavření se nepřipojujte znovu, dokud neopravíte příčinu.
const FATAL_REASONS = new Set(["INVALID_API_KEY", "INVALID_SIGNATURE"]);

let attempt = 0;
let failedConnects = 0;

function connect() {
  // Hlavička s klíčem je rozšíření Node.js (undici), v prohlížeči neexistuje.
  const ws = new WebSocket(WS_URL, { headers: { "X-COINERO-APIKEY": API_KEY } });
  let lastSeq = 0; // seq poslední datové zprávy; hello nese 0
  let pingTimer;
  let helloReceived = false;

  const send = (message) => ws.send(JSON.stringify(message));

  ws.addEventListener("message", (event) => {
    const message = JSON.parse(event.data);

    if (message.method === "hello") {
      helloReceived = true;
      attempt = 0; // spojení vzniklo, odstup se vynuluje
      failedConnects = 0;
      lastSeq = message.seq;
      send({ method: "subscribe", params: { channel: "ticker", symbols: ["BTCEUR", "BTCCZK"] }, reqId: 1 });
      if (API_SECRET) {
        // Podpis se počítá nad textem nonce (ASCII) a secret se nejdřív dekóduje z Base64.
        const signature = createHmac("sha256", Buffer.from(API_SECRET, "base64")).update(message.nonce, "ascii").digest("hex");
        send({ method: "auth", params: { signature }, reqId: 2 });
      }
      pingTimer = setInterval(() => send({ method: "ping", reqId: 99 }), 25_000);
      return;
    }

    if (message.channel) {
      // Zmeškané zprávy server nedoplňuje: po mezeře v seq se připojte znovu a dostanete snapshot.
      if (message.seq !== lastSeq + 1) {
        console.warn(`mezera v seq: čekáno ${lastSeq + 1}, přišlo ${message.seq}`);
        ws.close(1000);
        return;
      }
      lastSeq = message.seq;
      console.log(message.channel, message.type, `seq=${message.seq}`, JSON.stringify(message.data));
      return;
    }

    // Odpověď na požadavek: method, reqId, success a result, nebo error.
    console.log("odpověď", JSON.stringify(message));
    if (message.method === "auth" && message.success) {
      send({ method: "subscribe", params: { channel: "orders" }, reqId: 3 });
    }
  });

  ws.addEventListener("close", (event) => {
    clearInterval(pingTimer);
    console.log(`zavřeno: ${event.code} ${event.reason}`);
    if (FATAL_REASONS.has(event.reason)) {
      console.error("Klíč nebo podpis není v pořádku, nepřipojuji se znovu.");
      process.exit(1);
    }
    // Vestavěný WebSocket nezpřístupní stav HTTP odmítnutého navázání spojení (401, 403, 429),
    // proto se po opakovaných pokusech bez hello vzdáváme.
    if (!helloReceived && ++failedConnects >= MAX_FAILED_CONNECTS) {
      console.error("Spojení se nedaří navázat. Zkontrolujte klíč a omezení na IP adresy.");
      process.exit(1);
    }
    // Exponenciální odstup 1 až 60 s s náhodným rozptylem 0,5 až 1,0.
    const delay = Math.min(60, 2 ** attempt) * (0.5 + Math.random() * 0.5);
    attempt += 1;
    console.log(`znovu za ${delay.toFixed(1)} s`);
    setTimeout(connect, delay * 1000);
  });

  // Chyba spojení (například odmítnuté navázání spojení) vždy skončí událostí close.
  ws.addEventListener("error", () => {});
}

connect();