Získat API klíč
Subúčty (partneři)

Pokyny za subúčet

Pokyn za subúčet je běžný pokyn z části Obchodování. Navíc nese blok partner a nákup se u partnera s potvrzováním dokončuje ve dvou krocích.

Endpointy

EndpointCo dělá
POST …/orders/validateStejné kontroly jako zadání a odhad s poplatkem partnera. Nic nezapisuje.
POST …/ordersZadání pokynu. Nákup u partnera s potvrzováním vznikne ve stavu pendingConfirmation.
POST …/orders/{orderId}/confirmPotvrzení blokace peněz klienta. Tělo je prázdné.
GET …/ordersPokyny jednoho subúčtu, stejné stránkování a filtry jako GET /v1/orders. Pokyn čekající na potvrzení v seznamu není, vrací ho detail a seznam přes subúčty.
GET …/orders/{orderId}Detail pokynu. Místo orderId lze zadat i číslo pokynu partnera (partner.orderNumber).
GET /v1/subaccounts/ordersPokyny všech subúčtů podle času poslední změny, kurzorově. Slouží ke sledování stavů, viz níže.

Všechny cesty kromě poslední mají prefix /v1/subaccounts/{externalClientRef} a vyžadují partnerský klíč a podpis. Ruční zrušení API nenabízí: tržní pokyn se neruší a nepotvrzený nákup zruší systém po uplynutí lhůty.

Tělo zadání

Tělo je tělo zadání pokynu klientského účtu s těmito pravidly:

  • type je jen market. Platný typ limit vrací HTTP 400 ORDER_TYPE_NOT_ALLOWED, jinou hodnotu INVALID_ORDER.
  • symbol je trh z allowedMarkets subúčtu, kotovaný v měně vypořádání vašeho partnerského účtu.
  • Nákup zadává quoteQuantity, tedy částku k investování bez poplatku partnera. Poplatek se připočítá navrch.
  • Prodej zadává quantity, nebo sellAll: true pro celou disponibilní pozici; s sellAll se quantity neposílá.
  • clientOrderId je povinné a jedinečné ve vašem partnerském účtu. Opakování se stejným clientOrderId vrátí existující pokyn s HTTP 200 bez porovnání těla. Použití u jiného subúčtu vrací 409 REQUEST_ID_CONFLICT.

Dvoufázový nákup

U partnera s potvrzováním (partner.confirmationRequired: true) nákup neprobíhá, dokud nepotvrdíte, že jste klientovi zablokovali peníze. Coinero tak nikdy nezačne obchodovat za peníze, které klient nemá.

  1. Zadání

    POST …/orders provede kontroly (stav subúčtu, idempotence, partner aktivní, měna a trh, meze pokynu, denní limit klienta, strop nevypořádaných pokynů) a vrátí HTTP 201 s pokynem ve stavu pendingConfirmation. Blok partner nese orientační ceny: feeAmount (poplatek navrch), totalAmount (investice plus poplatek, tedy částka k blokaci) a blockDeadline. V účetnictví Coinera se zatím nic nezapsalo.

  2. Blokace u vás

    Zablokujete klientovi částku totalAmount ve svém systému. Lhůta blockDeadline je okamžik přijetí plus lhůta nastavená pro váš partnerský účet (výchozí 30 sekund).

  3. Potvrzení

    POST …/orders/{orderId}/confirm před lhůtou ověří ochrannou mez ceny. Cena buyPrice z GET /v1/ticker se porovná s cenou při přijetí a pohyb přes mez partnera (výchozí 2 %, v obou směrech) pokyn zamítne: odpověď je HTTP 200 s pokynem ve stavu rejected a rejectionReason: priceMoved, nic se nezaúčtuje a blokaci uvolníte. Jinak Coinero financuje subúčet z vašeho master účtu a pokyn přejde do stavu new, dál jako každý pokyn.

  4. Bez potvrzení

    Pokyn, který nepotvrdíte do blockDeadline, se zruší se stavem cancelled a rejectionReason: blockTimeout. Potvrzení po lhůtě vrací 409 ORDER_NOT_CONFIRMABLE.

  • Potvrzení je idempotentní: už potvrzený pokyn vrátí beze změny.
  • Když chybí tržní cena, vrací zadání i potvrzení 503 PRICING_UNAVAILABLE; čekající pokyn lze potvrdit znovu do konce lhůty. Odmítnutí při potvrzení kontrolami (TRADE_REJECTED, EXPOSURE_CAP_EXCEEDED) nic nezaúčtuje a pokyn dál čeká do konce lhůty.
  • Čekající pokyn se počítá do denního limitu klienta; do stropu nevypořádaných pokynů partnera se počítá až potvrzením.
  • Prodej potvrzení nepotřebuje: kryptoměnu blokuje Coinero při zadání a pokyn jde rovnou do stavu new. confirm u prodeje vrací ORDER_NOT_CONFIRMABLE.
  • Partner bez potvrzování (předfinancovaný master účet) má confirmationRequired: false, blockDeadline: null a pokyn jde rovnou do stavu new.

Hodnoty nastavení.

Lhůtu blokace a ochrannou mez nastavuje Coinero pro váš partnerský účet (výchozí 30 sekund a 2 %), v odpovědi je vždy vidíte: lhůtu v blockDeadline a v odhadu orientační cenu, se kterou se mez porovná. Neodvozujte je z této stránky.

Blok partner

Pokyn za subúčet je objekt pokynu z části Obchodování rozšířený o blok partner. U pokynů klientského účtu blok chybí. Stav pendingConfirmation je navíc mezi stavy pokynu; neznámé stavy zpracujte bez selhání.

PolePopis
partner.orderNumberČíslo pokynu vašeho partnerského účtu, například ABCD-0000001234; jeho číslice jsou variabilním symbolem platby za pokyn.
partner.externalClientRefIdentifikátor klienta ve vašem systému, za kterého pokyn je.
partner.feeAmountPoplatek 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.totalAmountNá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.netProceedsProdej: 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.blockDeadlineDo kdy musíte blokaci potvrdit, ISO 8601, UTC; jen ve stavu pendingConfirmation, jinak null. Pole je v odpovědi vždy.
partner.confirmationRequiredTrue, když pokyn čekal na vaše potvrzení blokace; u prodeje a u partnera bez potvrzování false.
partner.confirmedAtKdy jste blokaci potvrdili, ISO 8601, UTC, jinak null. Pole je v odpovědi vždy.
partner.settledAtKdy 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.

cancellable je u pokynů za subúčet vždy false. Pole settled na úrovni pokynu je vypořádání obchodu na účtu, partner.settledAt vypořádání s vámi (platba spárovaná, nebo výplata odeslaná); doplní se později bez změny status.

rejectionReasonVýznam
operationalIssuedočasný provozní problém na straně Coinera nebo burzy; rezervované prostředky se uvolnily a pokyn lze zadat znovu
otherjakýkoli jiný důvod
priceMovedjen pokyn za subúčet: cena se mezi přijetím a potvrzením pohnula víc, než dovoluje ochranná mez partnera; nic se nezaúčtovalo
blockTimeoutjen pokyn za subúčet: partner nepotvrdil blokaci prostředků do lhůty, pokyn je zrušený; nic se nezaúčtovalo

Ověření pokynu

POST …/orders/validate provede stejné kontroly jako zadání. Odmítnutí není chyba: odpověď je HTTP 200 s valid: false a kódem, se kterým by zadání skončilo. U valid: true nese estimate cenu, poplatek partnera, u nákupu částku k blokaci (total), u prodeje čistý výtěžek (netProceeds), meze pokynu a zbývající denní limit klienta; meze a limit jsou v Kč. Ověření nic nezapisuje, nepočítá se do limitu pokynů a clientOrderId je u něj nepovinné.

Sledování stavů

Změny stavů pokynů dostanete webhooky (order.*). Jako záloha a pro dohnání po výpadku slouží GET /v1/subaccounts/orders, plnohodnotná cesta, kterou lze používat i bez webhooků.

  • Pokyny všech subúčtů jsou řazené vzestupně podle času poslední změny. Odpověď nese items, nextCursor, hasMore a limit (výchozí 50, nejvýš 500).
  • Další stránku načtete s nextCursor v parametru cursor. Kurzor je i na poslední stránce s položkami, abyste mohli později dočíst novější změny.
  • Po výpadku pošlete updatedAfter s časem poslední zpracované změny (ISO 8601, chybějící posun znamená UTC, nebo milisekundy).
  • status filtruje jednu hodnotu stavu nebo open pro všechny neukončené pokyny.
  • Seznam vrací jen změny starší než 5 sekund, aby kurzor nepřeskočil pozdě uloženou změnu. Čerstvou změnu proto uvidíte o chvíli později.

Chyby

KódStavKdy
ORDER_TYPE_NOT_ALLOWED400Pokyn za subúčet může být jen tržní (market).
ASSET_NOT_SUPPORTED422Váš partnerský účet tuto kryptoměnu neobchoduje.
CURRENCY_NOT_SUPPORTED422Kotovací měna trhu není měnou vypořádání vašeho partnerského účtu.
AMOUNT_OUT_OF_RANGE422Hodnota pokynu je mimo nejmenší a největší pokyn partnera.
DAILY_LIMIT_EXCEEDED422Pokyn by překročil denní limit klienta.
EXPOSURE_CAP_EXCEEDED422Pokyn by překročil strop nevypořádaných pokynů partnera.
INSUFFICIENT_POSITION422Subúčet nedrží tolik kryptoměny, kolik chcete prodat.
TRADE_REJECTED422Obchodní pravidla Coinera pokyn odmítla.
REQUEST_ID_CONFLICT409Stejné clientOrderId už váš partnerský účet použil u jiného subúčtu.
ORDER_NOT_FOUND404Pokyn s tímto identifikátorem na účtu není.
ORDER_NOT_CONFIRMABLE409Pokyn nečeká na potvrzení blokace prostředků.
PRICING_UNAVAILABLE503Coinero teď pokyn nedokáže ocenit.
CONCURRENT_UPDATE409Pokyn nebo zůstatek účtu ve stejnou chvíli změnil jiný požadavek.
PARTNER_BUSY503Coinero právě zpracovává jiné požadavky vašeho partnerského účtu.
PARTNER_SUSPENDED409Partnerský účet je pozastavený nebo ukončený.
CLIENT_RESTRICTED409Subúčet v tomto stavu nejde měnit ani s ním obchodovat.
CLIENT_BLOCKED409Subúčet je zablokovaný, nejde měnit ani s ním obchodovat.
CLIENT_NOT_FOUND404Subúčet s tímto identifikátorem klienta partner nemá.

Při vypnutém obchodování přes API nebo vypnuté partnerské části vrací zadání i potvrzení HTTP 503 SERVICE_MAINTENANCE s Retry-After. Ověření pokynu a čtení běží dál. Stav ukazuje komponenta subaccounts ve stavu služby. Zadání i potvrzení se počítají do limitu pokynů (300 za minutu).