POST /v1/subaccounts/{externalClientRef}/orders
Zadá tržní pokyn za subúčet z cesty: nákup částkou k investování (quoteQuantity), prodej množstvím nebo celou pozicí (sellAll).
Partnerský klíč s oprávněním subaccounts
pk_) s oprávněním subaccounts a podpis požadavku; klientský klíč dostane 403 INSUFFICIENT_PERMISSION. Postup je na stránkách Podpis požadavků a Klíč partnera.Parametry cesty
| Parametr | Popis |
|---|---|
| externalClientRefpovinnéstring | Identifikátor klienta ve vašem systému přesně tak, jak jste ho poslali při založení subúčtu, včetně velikosti písmen: 1 až 64 písmen bez diakritiky, číslic, pomlček a podtržítek. |
Hlavičky požadavku
| Hlavička | Popis |
|---|---|
| X-COINERO-TEST-SCENARIOvolitelnéstring | Jen v sandboxu (testovací partnerský účet na testovacím prostředí Coinera): vyžádá si testovací scénář pokynu. reject-market pokyn odmítne jako trh, partial-fill naplní polovinu a zbytek zruší, delayed-fill naplní pokyn za 30 sekund, timeout zdrží odpověď o lhůtu potvrzení vašeho partnerského účtu plus 5 sekund (nejvýš 220 sekund, pod limitem brány), takže nákup čekající na potvrzení se zruší s důvodem blockTimeout, a missing-payment naplní pokyn bez simulované platby. Neznámá hodnota skončí chybou 400 s kódem UNKNOWN_TEST_SCENARIO. Mimo sandbox se hlavička ignoruje. |
Tělo požadavku
application/json · PlaceSubaccountOrderBodyPodepište a odešlete bajt po bajtu totéž tělo, bez přeformátování. Neznámá pole API ignoruje a pole s hodnotou null je totéž jako pole vynechané.
| Pole | Popis |
|---|---|
| symbolpovinnéstring | Symbol trhu z allowedMarkets subúčtu, kotovaný v měně vypořádání vašeho partnerského účtu, například BTCCZK; velikost písmen nerozhoduje. |
| sidepovinnéstring | buy nebo sell z pohledu základní měny trhu. Jen malými písmeny. Hodnoty: buy, sell. |
| typepovinnéstring | market. Jiný typ vrací ORDER_TYPE_NOT_ALLOWED. Hodnoty: market, limit. |
| quantityvolitelnéstring | Prodej: množství základní měny k prodeji jako desetinný řetězec, například "0.01". U nákupu a spolu se sellAll nepovolené. |
| quoteQuantityvolitelnéstring | Nákup: částka kotovací měny k investování jako desetinný řetězec, bez poplatku partnera, který se připočte navíc. U prodeje nepovolené. |
| sellAllvolitelnéboolean | Prodej: true prodá celou dostupnou pozici; quantity se pak neposílá. |
| clientOrderIdvolitelnéstring | Váš identifikátor pokynu, 1 až 64 písmen, číslic, pomlček a podtržítek, jedinečný pro partnerský účet. U zadání povinný: opakování se stejným clientOrderId vrátí existující pokyn. U ověření nepovinný. |
Odpověď
201 · application/json · OrderResponseNákup partnera s potvrzováním vznikne ve stavu pendingConfirmation: blok partner nese číslo pokynu, poplatek, částku k blokaci (totalAmount) a lhůtu blockDeadline. Nic se nezaúčtuje, dokud blokaci nepotvrdíte přes POST …/orders/{orderId}/confirm; bez potvrzení se pokyn po lhůtě zruší s důvodem blockTimeout.
Prodej a nákup partnera bez potvrzování jdou rovnou do stavu new.
clientOrderId je povinné a jedinečné pro partnerský účet; opakování se stejným clientOrderId vrátí existující pokyn s odpovědí 200.
Typ jiný než market vrací 400 ORDER_TYPE_NOT_ALLOWED. Čekající pokyn se počítá do denního limitu klienta, do stropu nevypořádaných pokynů až potvrzením.
Vyžaduje partnerský API klíč s oprávněním subaccounts a podepsaný požadavek. Funguje pro subúčet v každém stavu kromě zamítnutého; neexistující, cizí nebo zamítnutý subúčet vrací 404 CLIENT_NOT_FOUND.
Počítá se do limitu zadání pokynů klíče. Odpověď se neukládá do cache.
Částky a ceny jsou desetinné řetězce, aby nedocházelo ke ztrátě přesnosti. Volitelná pole mohou v odpovědi zcela chybět; nenahrazují se hodnotou null.
| Pole | Popis |
|---|---|
| orderIdstring | Identifikátor pokynu. |
| clientOrderIdstring nebo null | Váš vlastní identifikátor pokynu tak, jak jste ho poslali, nebo null, když jste pokyn zadali bez něj. Pole je v odpovědi vždy. |
| symbolstring | Symbol trhu tak, jak byl zadán při zadání pokynu, například BTCCZK. |
| basestring | Kód základní měny trhu. |
| quotestring | Kód kotovací měny trhu. |
| sidestring | Strana pokynu z pohledu základní měny. Hodnoty: buy, sell. |
| typestring | Typ pokynu. Hodnoty: market, limit. |
| statusstring | Stav pokynu. Hodnoty: new, placing, open, partiallyFilled, filled, cancelled, expired, rejected, pendingConfirmation. |
| settledboolean | True, jakmile je pokyn vypořádaný na účtu. Naplněný pokyn se vypořádá krátce po naplnění; do té doby se získaná částka ještě může změnit. |
| cancellableboolean | True, když lze pokyn v jeho stavu zrušit. |
| requestedQuantitystring nebo null | Množství v základní měně, které jste zadali, nebo null, když jste zadali quoteQuantity. Právě jedno z requestedQuantity a requestedQuoteQuantity je vyplněné. Pole je v odpovědi vždy. |
| requestedQuoteQuantitystring nebo null | Částka v kotovací měně, kterou jste zadali, nebo null, když jste zadali quantity. Pole je v odpovědi vždy. |
| pricestring nebo null | Limitní cena v kotovací měně za jednotku základní měny tak, jak jste ji zadali (u trhů v CZK v CZK), nebo null u tržního pokynu. Pole je v odpovědi vždy. |
| filledQuantitystring nebo null | Naplněné množství v základní měně jako desetinný řetězec. Null na trhu, který Coinero kotuje opačně než burza (například USDCBTC), kde pokyn drží naplněné množství v kotovací měně. Pole je v odpovědi vždy. |
| averagePricestring nebo null | Průměrná cena naplnění v kotovací měně za jednotku základní měny, u trhů v CZK přepočtená kurzem pokynu, s nejméně šesti platnými číslicemi. Do prvního naplnění null. Pole je v odpovědi vždy. |
| feeApiMoney nebo null | Poplatek Coinera za pokyn, tedy údaj, který aplikace ukazuje jako poplatek. Do naplnění nula. Null jen tehdy, když není známa měna poplatku. Pole je v odpovědi vždy. |
| fee.amountstring | Částka jako desetinný řetězec s tečkou a nejméně s tolika místy, kolik má její měna. Zpracujte ji jako desetinné číslo, ne jako číslo s pohyblivou řádovou čárkou. |
| fee.currencystring | Kód měny částky, například BTC nebo CZK. |
| spentApiMoney | Částka, kterou jste skutečně zaplatili, v měně, kterou pokyn utrácí. Do naplnění nula. |
| spent.amountstring | Částka jako desetinný řetězec s tečkou a nejméně s tolika místy, kolik má její měna. Zpracujte ji jako desetinné číslo, ne jako číslo s pohyblivou řádovou čárkou. |
| spent.currencystring | Kód měny částky, například BTC nebo CZK. |
| receivedApiMoney | Částka, kterou jste skutečně získali, v měně, do které pokyn nakupuje nebo prodává, po odečtení poplatku Coinera. Do naplnění nula. |
| received.amountstring | Částka jako desetinný řetězec s tečkou a nejméně s tolika místy, kolik má její měna. Zpracujte ji jako desetinné číslo, ne jako číslo s pohyblivou řádovou čárkou. |
| received.currencystring | Kód měny částky, například BTC nebo CZK. |
| conversionOrderConversionResponse nebo null | Převod přes můstkovou měnu u trhů, které Coinero kotuje v měně, již burza neobchoduje (například CZK přes EUR), kurzem stanoveným pro tento pokyn; u přímo obchodovaných trhů null. Pole je v odpovědi vždy. |
| conversion.ratestring | Klientský kurz stanovený pro pokyn jako desetinný řetězec: počet jednotek kotovací měny trhu na jednu jednotku můstkové měny, například 25.2525 CZK za 1 EUR. Aplikace ho ukazuje jako použitý kurz. |
| conversion.currencystring | Kód můstkové měny, přes kterou se pokyn provádí, například EUR. |
| rejectionReasonstring nebo null | Proč byl pokyn odmítnut, nebo null, když odmítnut nebyl. Pole je v odpovědi vždy. |
| createdAtstring | Kdy byl pokyn vytvořen, ISO 8601, UTC, s milisekundami. |
| createdAtMsinteger (int64) | Stejný okamžik jako Unix timestamp v milisekundách. |
| filledAtstring nebo null | Kdy byl pokyn naplněn celý, ISO 8601, UTC, jinak null. Pole je v odpovědi vždy. |
| filledAtMsinteger nebo null | Stejný okamžik jako Unix timestamp v milisekundách. Případně null. Pole je v odpovědi vždy. |
| settledAtstring nebo null | Kdy byl pokyn vypořádán, ISO 8601, UTC, jinak null. Pole je v odpovědi vždy. |
| settledAtMsinteger nebo null | Stejný okamžik jako Unix timestamp v milisekundách. Případně null. Pole je v odpovědi vždy. |
| partnervolitelnéPartnerOrderBlockResponse | Údaje pokynu za subúčet vašeho partnerského účtu: číslo pokynu, poplatek partnera, částka k blokaci, potvrzení a vypořádání s partnerem. Jen u pokynů subúčtů; pokyny klientského účtu pole nemají. |
| partner.orderNumberstring | Číslo pokynu vašeho partnerského účtu, například ABCD-0000001234; jeho číslice jsou variabilním symbolem platby za pokyn. |
| partner.externalClientRefstring | Identifikátor klienta ve vašem systému, za kterého pokyn je. |
| partner.feeAmountApiMoney | Poplatek partnera: u nákupu navíc k investici (po vypořádání obchodu skutečně zaúčtovaný), u prodeje z hrubého výtěžku (do vypořádání obchodu nula). |
| partner.feeAmount.amountstring | Částka jako desetinný řetězec s tečkou a nejméně s tolika místy, kolik má její měna. Zpracujte ji jako desetinné číslo, ne jako číslo s pohyblivou řádovou čárkou. |
| partner.feeAmount.currencystring | Kód měny částky, například BTC nebo CZK. |
| partner.totalAmountApiMoney nebo null | Nákup: investice plus poplatek partnera, tedy částka, kterou klientovi zablokujete a Coineru zaplatíte. U prodeje null. Pole je v odpovědi vždy. |
| partner.totalAmount.amountstring | Částka jako desetinný řetězec s tečkou a nejméně s tolika místy, kolik má její měna. Zpracujte ji jako desetinné číslo, ne jako číslo s pohyblivou řádovou čárkou. |
| partner.totalAmount.currencystring | Kód měny částky, například BTC nebo CZK. |
| partner.netProceedsApiMoney nebo null | Prodej: výtěžek po poplatku partnera, který vám Coinero vyplatí; do vypořádání obchodu null. U nákupu null. Pole je v odpovědi vždy. |
| partner.netProceeds.amountstring | Částka jako desetinný řetězec s tečkou a nejméně s tolika místy, kolik má její měna. Zpracujte ji jako desetinné číslo, ne jako číslo s pohyblivou řádovou čárkou. |
| partner.netProceeds.currencystring | Kód měny částky, například BTC nebo CZK. |
| partner.blockDeadlinestring nebo null | Do kdy musíte blokaci potvrdit, ISO 8601, UTC; jen ve stavu pendingConfirmation, jinak null. Pole je v odpovědi vždy. |
| partner.blockDeadlineMsinteger nebo null | Stejný okamžik jako Unix timestamp v milisekundách. Případně null. Pole je v odpovědi vždy. |
| partner.confirmationRequiredboolean | True, když pokyn čekal na vaše potvrzení blokace; u prodeje a u partnera bez potvrzování false. |
| partner.confirmedAtstring nebo null | Kdy jste blokaci potvrdili, ISO 8601, UTC, jinak null. Pole je v odpovědi vždy. |
| partner.confirmedAtMsinteger nebo null | Stejný okamžik jako Unix timestamp v milisekundách. Případně null. Pole je v odpovědi vždy. |
| partner.settledAtstring nebo null | Kdy byl pokyn vypořádán s vaším partnerským účtem (spárovaná platba nebo odeslaná výplata), ISO 8601, UTC, jinak null. Pole settled pokynu je vypořádání obchodu na účtu, ne tohle. Pole je v odpovědi vždy. |
| partner.settledAtMsinteger nebo null | Stejný okamžik jako Unix timestamp v milisekundách. Případně null. Pole je v odpovědi vždy. |
Hodnoty stavů
Nové hodnoty mohou přibýt i v rámci v1; neznámou hodnotu zpracujte bez selhání.
| PublicOrderSide | Význam |
|---|---|
buy | nákup: platíte kotovací měnou a získáváte základní měnu |
sell | prodej: platíte základní měnou a získáváte kotovací měnu |
| PublicOrderType | Význam |
|---|---|
market | tržní pokyn se provede za aktuální tržní cenu |
limit | limitní pokyn se provede za zadanou limitní cenu nebo lepší |
| PublicOrderStatus | 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 |
Chyby
Chyby mají formát application/problem+json; zpracovávejte je podle pole code. Podrobnosti najdete v přehledu chyb.
| Stav | Kódy | Řešení |
|---|---|---|
| 400 | INVALID_ORDER, ORDER_TYPE_NOT_ALLOWED, UNKNOWN_TEST_SCENARIO | Pole errors uvádí každý problém jako název pole a kód; opravte je a pokyn pošlete znovu. Pošlete pokyn s type market; pokyn nevznikl. Opravte hodnotu hlavičky X-COINERO-TEST-SCENARIO, nebo ji vynechte; pokyn nevznikl ani se nepotvrdil. |
| 401 | MISSING_API_KEY, INVALID_API_KEY, SIGNATURE_REQUIRED, INVALID_SIGNATURE, TIMESTAMP_OUT_OF_WINDOW | Doplňte hlavičku X-COINERO-APIKEY. Ověřte hodnotu a stav klíče i aktivitu účtu. Doplňte hlavičky X-COINERO-TIMESTAMP a X-COINERO-SIGNATURE podle stránky Podpis požadavků. Zkontrolujte kanonický řetězec (časová značka, metoda velkými písmeny, cesta s dotazem, tělo bajt po bajtu) a že secret před HMAC dekódujete z Base64; stránka Podpis požadavků má referenční vektor. Použijte aktuální čas v milisekundách; pole serverTime a serverTimeMs v odpovědi nesou čas serveru, podle kterého opravte hodiny klienta. |
| 403 | INSUFFICIENT_PERMISSION, IP_NOT_ALLOWED | Pole requiredPermission uvádí, které oprávnění chybí. Oprávnění klíče nelze změnit; vytvořte nový klíč s potřebným oprávněním. Odešlete požadavek z adresy povolené u klíče, nebo vytvořte nový klíč, jehož seznam adresu obsahuje; seznam nelze dodatečně změnit. |
| 404 | CLIENT_NOT_FOUND, UNKNOWN_SYMBOL | Ověřte externalClientRef včetně velikosti písmen; neexistující, cizí i zamítnutý subúčet vracejí stejnou chybu. Subúčet založte přes POST /v1/subaccounts. Vyberte pár se stavem trading nebo paused z GET /v1/markets; neznámý i vyřazený pár vrací 404 a pole detail je od sebe odliší. |
| 405 | METHOD_NOT_ALLOWED | Použijte metodu z hlavičky Allow: GET a HEAD ke čtení, POST a DELETE jen u operací, které je mají v dokumentaci. |
| 409 | PARTNER_SUSPENDED, CLIENT_RESTRICTED, CLIENT_BLOCKED, CLIENT_CLOSED, REQUEST_ID_CONFLICT | Spolupráce je pozastavená nebo ukončená; kontaktujte Coinero. Čtení dat funguje dál. Subúčet je k posouzení nebo zamítnutý, případně mu obchodování teď nedovoluje Coinero; stav zjistíte přes GET /v1/subaccounts/{externalClientRef}, důvod Coinero nesděluje. Subúčet je zablokovaný a měnit ho nejde; čtení funguje dál, důvod Coinero nesděluje. Subúčet je ukončený; čtení funguje dál, zápisy ani nové založení se stejným externalClientRef nejdou. Pro vracejícího se klienta založte subúčet s novým identifikátorem. Pro nový pokyn použijte nové clientOrderId; clientOrderId je jedinečné v rámci celého partnerského účtu. |
| 422 | ASSET_NOT_SUPPORTED, CURRENCY_NOT_SUPPORTED, AMOUNT_OUT_OF_RANGE, DAILY_LIMIT_EXCEEDED, EXPOSURE_CAP_EXCEEDED, INSUFFICIENT_POSITION, TRADE_REJECTED | Použijte trh z allowedMarkets v GET /v1/subaccounts/{externalClientRef}; pokyn nevznikl. Použijte trh kotovaný v měně vypořádání, například BTCCZK; pokyn nevznikl. Upravte částku do mezí z limits v GET /v1/subaccounts/{externalClientRef}; pokyn nevznikl. Snižte částku do zbytku z dailyLimitRemaining v GET /v1/subaccounts/{externalClientRef}, nebo počkejte na další den; čekající pokyny se do limitu počítají, dokud neskončí. Vypořádejte otevřené nákupy a pokyn zadejte nebo potvrďte znovu; nic se nezaúčtovalo. Zjistěte dostupné množství přes GET /v1/subaccounts/{externalClientRef}/positions, nebo prodejte vše s sellAll true; pokyn nevznikl. Zkontrolujte trh v GET /v1/markets a částku; nic se nezaúčtovalo. Potvrzovaný pokyn dál čeká do konce lhůty. |
| 429 | RATE_LIMIT_EXCEEDED | Před dalším pokusem vyčkejte počet sekund z Retry-After. |
| 503 | PRICING_UNAVAILABLE, PARTNER_BUSY, MARKET_DATA_UNAVAILABLE, SERVICE_MAINTENANCE | Nic se nezměnilo; požadavek zopakujte za chvíli. Čekající pokyn lze potvrdit znovu do konce lhůty. Stejný požadavek zopakujte za několik sekund; opakování je bezpečné. Subúčet už mohl vzniknout: opakované založení ho vrátí a dokončí jeho kontroly. Data dočasně chybí; vyčkejte počet sekund z Retry-After a požadavek zopakujte. Probíhá údržba nebo je dočasně vypnuté obchodování či WebSocket; ověřte GET /v1/status a vyčkejte podle Retry-After. |