Podpis požadavků
Endpointy s oprávněním account a trade vyžadují kromě API klíče i podpis, který dokazuje, že požadavek odesílá držitel secretu.
Kdy se podepisuje
Podpis vyžaduje každý endpoint, u kterého reference uvádí oprávnění account nebo trade: zůstatky, historii, ověření, zadávání a rušení pokynů. Stejně se podepisují všechny endpointy partnerského klíče s oprávněním subaccounts, viz Klíč partnera. Endpointy tržních dat podpis nevyžadují a hlavičky podpisu ignorují.
| Hlavička | Hodnota |
|---|---|
X-COINERO-APIKEY | Klíč, tedy hodnota začínající ck_ (u partnerského klíče pk_). Do podpisu nevstupuje. |
X-COINERO-TIMESTAMP | Aktuální čas v milisekundách od 1. 1. 1970 (UTC), zapsaný samými číslicemi. |
X-COINERO-SIGNATURE | Podpis jako 64 hexadecimálních znaků; na velikosti písmen nezáleží. |
Jak se podpis počítá
signature = hex( HMAC-SHA256( secret, timestamp + METHOD + path + body ) )| Část | Co do ní patří |
|---|---|
timestamp | Hodnota hlavičky X-COINERO-TIMESTAMP přesně tak, jak ji posíláte. |
METHOD | Metoda HTTP velkými písmeny: GET, POST nebo DELETE. |
path | Cesta včetně dotazu přesně tak, jak ji odesíláte, například /v1/orders?status=open&limit=20. Bez dekódování a bez přeřazení parametrů. Server bere cíl požadavku z prvního řádku HTTP požadavku. |
body | Tělo požadavku bajt po bajtu. U GET a DELETE je prázdné. Podepsané tělo smí mít nejvýš 64 KiB. |
secret | Bajty dekódované ze standardního Base64, ve kterém jste secret dostali (32 bajtů). Nepoužívejte jeho textový zápis. |
Části se spojují bez oddělovačů. Řetězec před tělem se kóduje jako UTF-8 a tělo se k němu připojí beze změny. Výsledek je podpis, který pošlete v hlavičce X-COINERO-SIGNATURE.
Podepisujte to, co odesíláte.
INVALID_SIGNATURE je rozdíl mezi podepsaným a odeslaným textem: jiné pořadí parametrů v dotazu, tělo, které HTTP knihovna přeformátovala, nebo secret použitý jako text místo dekódovaných bajtů. Tělo sestavte jednou, podepište tento řetězec a odešlete tentýž řetězec. V curlu proto použijte --data-binary, ne -d, který z těla odstraňuje znaky konce řádku.Časové okno
Časová značka se smí lišit od času serveru nejvýš o 30 sekund na obě strany. Mimo okno API vrací HTTP 401 s kódem TIMESTAMP_OUT_OF_WINDOW. Odpověď nese pole serverTime a serverTimeMs s časem serveru, podle kterého opravíte hodiny klienta. Časová značka v sekundách nebo ve formátu ISO 8601 je také mimo okno.
API nepoužívá jednorázové hodnoty (nonce): ty vyžadují stav na klíč a rozbíjejí paralelní volání. Zachycený požadavek by tedy šlo uvnitř okna přehrát, proto je okno krátké. Požadavky posílejte jen přes HTTPS a hodiny serveru držte synchronizované (NTP). Rozdíl proti hodinám Coinera změříte přes GET /v1/time.
Chyby podpisu
| Kód | Stav | Příčina |
|---|---|---|
SIGNATURE_REQUIRED | 401 | Chybí hlavička X-COINERO-TIMESTAMP, X-COINERO-SIGNATURE, nebo obě. |
INVALID_SIGNATURE | 401 | Podpis nesouhlasí, nebo je podepsané tělo větší než 64 KiB. |
TIMESTAMP_OUT_OF_WINDOW | 401 | Časová značka je dál než 30 sekund od času serveru. |
API kontroluje postupně klíč, adresu (omezení na IP), podpis a až potom oprávnění. Požadavek s chybným podpisem se proto nedozví, jaká oprávnění klíč má; chyba INSUFFICIENT_PERMISSION přijde teprve u správně podepsaného požadavku.
Secret nikdy do prohlížeče ani do repozitáře.
Referenční vektor
Vektor slouží k ověření vlastní implementace dřív, než zavoláte API. Se stejným secretem, časovou značkou, metodou, cestou a tělem musí vyjít stejný podpis. Cesty a tělo jsou ilustrační, na výpočtu podpisu to nic nemění. Stejný kód ukázek jsme spustili s hodnotami vektoru a ve všech třech jazycích vyšel uvedený podpis.
| Vektor 1: POST s tělem | Hodnota |
|---|---|
| Secret (Base64) | AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8= |
| Secret (hex, klíč HMAC) | 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f |
X-COINERO-TIMESTAMP | 1767225600000 (2026-01-01T00:00:00.000Z) |
| Metoda | POST |
| Cesta s dotazem | /v1/orders?symbol=BTC-CZK&clientOrderId=bot-42 |
| Tělo | {"symbol":"BTC-CZK","side":"buy","type":"limit","amount":"0.01000000","price":"2100000.00"} |
X-COINERO-SIGNATURE | 4cd7e967538cfed695a9226348de67d689e02878f1f118e1a6161a0f96697c5b |
| Vektor 2: GET bez těla | Hodnota |
|---|---|
| Secret, časová značka | Stejné jako ve vektoru 1 |
| Metoda a cesta | GET /v1/account/balances (prázdné tělo) |
X-COINERO-SIGNATURE | 82a6875e355f06592fc51458a0b7c2fea32922e1df9df9f4fcac607da1aa0b07 |
Stejný vektor ověřuje test serveru, takže se vektor a kód serveru nemohou rozejít.