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
| Endpoint | Co dělá |
|---|---|
| POST …/orders/validate | Stejné kontroly jako zadání a odhad s poplatkem partnera. Nic nezapisuje. |
| POST …/orders | Zadání pokynu. Nákup u partnera s potvrzováním vznikne ve stavu pendingConfirmation. |
| POST …/orders/{orderId}/confirm | Potvrzení blokace peněz klienta. Tělo je prázdné. |
| GET …/orders | Pokyny 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/orders | Pokyny 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:
typeje jenmarket. Platný typlimitvrací HTTP 400ORDER_TYPE_NOT_ALLOWED, jinou hodnotuINVALID_ORDER.symbolje trh zallowedMarketssubúč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, nebosellAll: truepro celou disponibilní pozici; ssellAllsequantityneposílá. clientOrderIdje povinné a jedinečné ve vašem partnerském účtu. Opakování se stejnýmclientOrderIdvrátí existující pokyn s HTTP 200 bez porovnání těla. Použití u jiného subúčtu vrací 409REQUEST_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á.
Zadání
POST …/ordersprovede 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 stavupendingConfirmation. Blokpartnernese orientační ceny:feeAmount(poplatek navrch),totalAmount(investice plus poplatek, tedy částka k blokaci) ablockDeadline. V účetnictví Coinera se zatím nic nezapsalo.Blokace u vás
Zablokujete klientovi částku
totalAmountve svém systému. LhůtablockDeadlineje okamžik přijetí plus lhůta nastavená pro váš partnerský účet (výchozí 30 sekund).Potvrzení
POST …/orders/{orderId}/confirmpřed lhůtou ověří ochrannou mez ceny. CenabuyPricez 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 stavurejectedarejectionReason: priceMoved, nic se nezaúčtuje a blokaci uvolníte. Jinak Coinero financuje subúčet z vašeho master účtu a pokyn přejde do stavunew, dál jako každý pokyn.Bez potvrzení
Pokyn, který nepotvrdíte do
blockDeadline, se zruší se stavemcancelledarejectionReason: blockTimeout. Potvrzení po lhůtě vrací 409ORDER_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.confirmu prodeje vracíORDER_NOT_CONFIRMABLE. - Partner bez potvrzování (předfinancovaný master účet) má
confirmationRequired: false,blockDeadline: nulla pokyn jde rovnou do stavunew.
Hodnoty nastavení.
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í.
| Pole | Popis |
|---|---|
partner.orderNumber | Číslo pokynu vašeho partnerského účtu, například ABCD-0000001234; jeho číslice jsou variabilním symbolem platby za pokyn. |
partner.externalClientRef | Identifikátor klienta ve vašem systému, za kterého pokyn je. |
partner.feeAmount | 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.totalAmount | 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.netProceeds | 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.blockDeadline | Do kdy musíte blokaci potvrdit, ISO 8601, UTC; jen ve stavu pendingConfirmation, jinak null. Pole je v odpovědi vždy. |
partner.confirmationRequired | True, když pokyn čekal na vaše potvrzení blokace; u prodeje a u partnera bez potvrzování false. |
partner.confirmedAt | Kdy jste blokaci potvrdili, ISO 8601, UTC, jinak null. Pole je v odpovědi vždy. |
partner.settledAt | 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. |
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.
| rejectionReason | Význam |
|---|---|
operationalIssue | dočasný provozní problém na straně Coinera nebo burzy; rezervované prostředky se uvolnily a pokyn lze zadat znovu |
other | jakýkoli jiný důvod |
priceMoved | jen 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 |
blockTimeout | jen 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,hasMorealimit(výchozí 50, nejvýš 500). - Další stránku načtete s
nextCursorv parametrucursor. 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
updatedAfters časem poslední zpracované změny (ISO 8601, chybějící posun znamená UTC, nebo milisekundy). statusfiltruje jednu hodnotu stavu neboopenpro 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ód | Stav | Kdy |
|---|---|---|
ORDER_TYPE_NOT_ALLOWED | 400 | Pokyn za subúčet může být jen tržní (market). |
ASSET_NOT_SUPPORTED | 422 | Váš partnerský účet tuto kryptoměnu neobchoduje. |
CURRENCY_NOT_SUPPORTED | 422 | Kotovací měna trhu není měnou vypořádání vašeho partnerského účtu. |
AMOUNT_OUT_OF_RANGE | 422 | Hodnota pokynu je mimo nejmenší a největší pokyn partnera. |
DAILY_LIMIT_EXCEEDED | 422 | Pokyn by překročil denní limit klienta. |
EXPOSURE_CAP_EXCEEDED | 422 | Pokyn by překročil strop nevypořádaných pokynů partnera. |
INSUFFICIENT_POSITION | 422 | Subúčet nedrží tolik kryptoměny, kolik chcete prodat. |
TRADE_REJECTED | 422 | Obchodní pravidla Coinera pokyn odmítla. |
REQUEST_ID_CONFLICT | 409 | Stejné clientOrderId už váš partnerský účet použil u jiného subúčtu. |
ORDER_NOT_FOUND | 404 | Pokyn s tímto identifikátorem na účtu není. |
ORDER_NOT_CONFIRMABLE | 409 | Pokyn nečeká na potvrzení blokace prostředků. |
PRICING_UNAVAILABLE | 503 | Coinero teď pokyn nedokáže ocenit. |
CONCURRENT_UPDATE | 409 | Pokyn nebo zůstatek účtu ve stejnou chvíli změnil jiný požadavek. |
PARTNER_BUSY | 503 | Coinero právě zpracovává jiné požadavky vašeho partnerského účtu. |
PARTNER_SUSPENDED | 409 | Partnerský účet je pozastavený nebo ukončený. |
CLIENT_RESTRICTED | 409 | Subúčet v tomto stavu nejde měnit ani s ním obchodovat. |
CLIENT_BLOCKED | 409 | Subúčet je zablokovaný, nejde měnit ani s ním obchodovat. |
CLIENT_NOT_FOUND | 404 | Subúč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).