{"openapi":"3.1.0","info":{"title":"DCFTP API","version":"1.0.0","description":"Read a DCFTP account and trade on Hyperliquid (testnet) through DCFTP. Authenticate with `Authorization: Bearer dk_test_<keyId>.<secret>` (Settings → API keys; the key is shown once). Trading needs the key's trade permission and an approved server-side trading agent: a Hyperliquid agent key DCFTP holds encrypted, which can trade but never withdraw. Every order carries the DCFTP builder fee (0.025%). Decimals are strings. Errors are JSON { error: { code, message } }. Send an `Idempotency-Key` with every order: then any failed or timed-out order is safe to retry with the same Idempotency-Key. Hyperliquid costs: /account and the trading routes read the account from Hyperliquid (cached 2 s per wallet), /markets is cached 5 s; the server spends at most 1000 Hyperliquid request weight per minute for all API clients together and answers 503 busy beyond that. API keys cannot move money, by design: there is no withdraw, transfer or send endpoint (GET /balances is read-only), and the server-side trading agent could not sign such actions on Hyperliquid even if one existed; withdrawals and transfers are signed by your own wallet in the DCFTP app."},"servers":[{"url":"/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"dk_test_<keyId>.<secret>"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["bad_request","builder_fee_not_approved","exchange_rejected","invalid_key","key_revoked","key_expired","ip_not_allowed","scope_missing","not_found","agent_required","agent_expired","idempotency_conflict","invalid_order","limit_exceeded","rate_limited","upstream_unavailable","agent_unavailable","busy"]},"message":{"type":"string"}}}}}}}}},"schemas":{"OrderLeg":{"type":"object","properties":{"leg":{"type":"integer"},"role":{"enum":["main","tp","sl"]},"status":{"enum":["resting","filled","waiting","canceled","triggered","error"]},"oid":{"type":["integer","null"]},"cloid":{"type":["string","null"]},"filledSz":{"type":"string","description":"Filled legs: size filled"},"avgPx":{"type":"string","description":"Filled legs: average fill price"},"error":{"type":"string"},"hlStatus":{"type":"string","description":"Hyperliquid order status, on a response settled after a retry"}}}}},"x-errors":[{"status":400,"code":"bad_request","meaning":"Malformed body or query (unknown fields are rejected)."},{"status":400,"code":"builder_fee_not_approved","meaning":"The wallet never approved DCFTP's builder fee (0.025 %), which every API order carries. Approve it once (one wallet signature) on DCFTP's /connect/patternxradar page or in the terminal, then retry; nothing was placed."},{"status":400,"code":"exchange_rejected","meaning":"Hyperliquid refused the request; message is its text. A partly rejected order lists every leg in `orders`."},{"status":401,"code":"invalid_key","meaning":"Missing, malformed or unknown API key, or wrong secret."},{"status":403,"code":"key_revoked","meaning":"The key was revoked."},{"status":403,"code":"key_expired","meaning":"The key is past its expiry."},{"status":403,"code":"ip_not_allowed","meaning":"The request IP is not in the key's allowlist."},{"status":403,"code":"scope_missing","meaning":"The key lacks the read or trade permission."},{"status":404,"code":"not_found","meaning":"Unknown endpoint, or the order is not open."},{"status":409,"code":"agent_required","meaning":"Approve the server-side trading agent in DCFTP Settings → API keys."},{"status":409,"code":"agent_expired","meaning":"The server-side trading agent expired; renew it in Settings."},{"status":409,"code":"idempotency_conflict","meaning":"Idempotency-Key reused for a different request, or that request is still running."},{"status":422,"code":"invalid_order","meaning":"Unknown market, bad price/size, below the $10 minimum, wrong TP/SL side, no position, …"},{"status":422,"code":"limit_exceeded","meaning":"Over the key's maxOrderNotional or dailyNotional (`limit`, `cap`, `used`, `notional` in the error)."},{"status":429,"code":"rate_limited","meaning":"600 reads (120 for /account + /balances) / 120 writes per minute per key; 30 failed logins per minute per IP."},{"status":502,"code":"upstream_unavailable","meaning":"Hyperliquid did not answer. Orders sent with an Idempotency-Key are safe to retry with the same Idempotency-Key: the outcome is settled, never doubled."},{"status":503,"code":"agent_unavailable","meaning":"Trading through API keys is not enabled on this server."},{"status":503,"code":"busy","meaning":"The server is at its Hyperliquid request budget, another order of this key is being placed, or too many key checks are queued; retry shortly."}],"paths":{"/account":{"get":{"summary":"Account summary, positions and open orders (cached 2 s; 120 per minute per key)","x-scope":"read","responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"type":"object","properties":{"wallet":{"type":"string"},"network":{"type":"string"},"summary":{"type":"object","description":"accountValue, totalMarginUsed, totalNtlPos, withdrawable, and, when Hyperliquid reports them, crossMaintenanceMarginUsed and crossAccountValue (cross positions are liquidated when the first reaches the second); decimal strings"},"positions":{"type":"array"},"openOrders":{"type":"array"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/balances":{"get":{"summary":"Perps summary and spot token balances (cached 2 s; shares the 120 per minute per key with /account). Read-only: API keys cannot withdraw, transfer or send","x-scope":"read","responses":{"200":{"description":"Balances","content":{"application/json":{"schema":{"type":"object","properties":{"wallet":{"type":"string"},"network":{"type":"string"},"perps":{"type":"object","description":"accountValue, withdrawable, totalMarginUsed, totalNtlPos (decimal strings)"},"spot":{"type":"array","description":"Non-zero spot balances (USDC always listed): { coin, token, total, hold, available }"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/fills":{"get":{"summary":"Fills, newest first (keyset paging)","x-scope":"read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"before","in":"query","description":"Epoch ms: fills strictly older than this (from `next.before`)","schema":{"type":"integer"}},{"name":"beforeId","in":"query","description":"From `next.beforeId`; requires before","schema":{"type":"integer"}}],"responses":{"200":{"description":"A page of fills; `source` is web or api (the client that placed the order). `fee` is the total fee, inclusive of `builderFee` (Hyperliquid semantics): never add them. `liquidation` is true when Hyperliquid marked the fill as part of a liquidation.","content":{"application/json":{"schema":{"type":"object","properties":{"fills":{"type":"array"},"next":{"type":["object","null"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/markets":{"get":{"summary":"Tradable markets: perps (type perp: mark, mid, funding) then USDC-quoted spot pairs (type spot: coin = wire name such as @107, symbol BASE/QUOTE, index = asset id, mark, mid, 24h volume)","x-scope":"read","responses":{"200":{"description":"Markets","content":{"application/json":{"schema":{"type":"object","properties":{"markets":{"type":"array"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/orders":{"post":{"summary":"Place an order (optionally with attached TP/SL)","x-scope":"trade","parameters":[{"name":"Idempotency-Key","in":"header","description":"1-64 printable characters. Safe to retry with the same Idempotency-Key after any error or timeout (24 h): the stored or settled outcome is returned and the order is never placed twice. Client order ids are derived from it: leg 0 = `0x` + the first 32 hex characters of sha256(\"<keyId>|<Idempotency-Key>\") (keyId = the 16-hex part of `dk_<env>_<keyId>`), attached TP/SL legs use \"<keyId>|<Idempotency-Key>|<i>\" (i = 1, 2), so you can look the order up with GET /orders/{cloid} yourself. A retry while the first request is still being sent gets 409 idempotency_conflict for up to 45 s; after that the outcome is settled with Hyperliquid, so retry for at least 60 s.","schema":{"type":"string","maxLength":64}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["coin","side","kind"],"additionalProperties":false,"properties":{"coin":{"type":"string","example":"BTC","description":"Perp coin (BTC, xyz:AAPL) or a USDC-quoted spot pair as BASE/QUOTE (HYPE/USDC) or its wire name (@107). Spot: market or limit only, no reduceOnly or TP/SL, notional in USDC, modify not supported; the DCFTP builder fee is charged by Hyperliquid on spot sells only."},"side":{"enum":["buy","sell"]},"kind":{"enum":["market","limit","stopMarket","stopLimit"]},"size":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"Size in coin (give size or notional)","example":"0.001"},"notional":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"Size in USD at the reference price (give size or notional)","example":"100"},"price":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"Limit price (limit, stopLimit)"},"triggerPx":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"Trigger price (stopMarket, stopLimit)"},"tif":{"enum":["Gtc","Ioc","Alo"],"default":"Gtc"},"reduceOnly":{"type":"boolean","default":false},"slippageBps":{"type":"integer","minimum":0,"maximum":5000,"default":100,"description":"Market and trigger legs"},"takeProfitPx":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"Attached take-profit trigger"},"stopLossPx":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"Attached stop-loss trigger"},"cloid":{"type":"string","pattern":"^0x[0-9a-fA-F]{32}$","description":"Your client order id for the main leg"}}}}}},"responses":{"201":{"description":"Placed; one entry per leg","content":{"application/json":{"schema":{"type":"object","properties":{"coin":{"type":"string"},"size":{"type":"string"},"notional":{"type":["string","null"]},"orders":{"type":"array","items":{"$ref":"#/components/schemas/OrderLeg"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Cancel all open orders (of one coin with ?coin=)","x-scope":"trade","parameters":[{"name":"coin","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled (a partly failed cancel is 400 with `cancelled` and `failed` oids)","content":{"application/json":{"schema":{"type":"object","properties":{"cancelled":{"type":"integer"},"oids":{"type":"array","items":{"type":"integer"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/orders/{id}":{"get":{"summary":"One order by oid or client order id: status, filled size, average fill price (60 per minute per key; final states cached 10 s)","x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"description":"oid (integer) or cloid (0x + 32 hex)","schema":{"type":"string"}}],"responses":{"200":{"description":"status: open | filled | canceled | rejected | triggered | unknown (unknown = Hyperliquid has no such order); hlStatus is the raw Hyperliquid status (e.g. marginCanceled). filledSz = origSz minus what is left; avgPx is the size-weighted fill price (null when nothing filled).","content":{"application/json":{"schema":{"type":"object","properties":{"oid":{"type":["integer","null"]},"cloid":{"type":["string","null"]},"coin":{"type":["string","null"]},"side":{"enum":["B","A",null]},"status":{"enum":["open","filled","canceled","rejected","triggered","unknown"]},"hlStatus":{"type":["string","null"]},"origSz":{"type":["string","null"]},"filledSz":{"type":["string","null"]},"avgPx":{"type":["string","null"]},"limitPx":{"type":["string","null"]},"statusTimestamp":{"type":["integer","null"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Cancel one open order (by oid)","x-scope":"trade","parameters":[{"name":"id","in":"path","required":true,"description":"The order id (oid)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"cancelled":{"type":"integer"},"oids":{"type":"array","items":{"type":"integer"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}},"patch":{"summary":"Modify an open order (price, size and/or trigger) as a replacement","x-scope":"trade","description":"The replacement keeps side, kind (limit / stop / TP / SL), TIF and reduce-only, carries the builder fee and counts against the key limits like a new order; it gets a new oid and client order id. Ordinary orders: the replacement is placed first, then the old order is cancelled (if that cancel fails, Hyperliquid is asked about the old order: already canceled → `cancelledOld: true`; filled → the replacement is cancelled instead and the response has `cancelledOld: false`, `replacementCancelled: true` and a `warning` (`replacementCancelled: false` = both may be open or filled); still open → `cancelledOld: false` and a `warning`, cancel it with DELETE). Position TP/SL: the old one is cancelled first, then the new one is placed. A remaining size below the $10 minimum cannot be moved (422).","parameters":[{"name":"id","in":"path","required":true,"description":"The order id (oid)","schema":{"type":"integer"}},{"name":"Idempotency-Key","in":"header","description":"As for POST /orders: safe to retry; the replacement client order id is 0x + the first 32 hex of sha256(\"<keyId>|<Idempotency-Key>\").","schema":{"type":"string","maxLength":64}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"price":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"New limit price (limit, stopLimit)"},"size":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"New remaining size in coin"},"triggerPx":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"New trigger price (stop / TP / SL)"},"slippageBps":{"type":"integer","minimum":0,"maximum":5000,"default":100,"description":"Market triggers: slippage cap from the trigger"}}}}}},"responses":{"200":{"description":"Replaced","content":{"application/json":{"schema":{"type":"object","properties":{"coin":{"type":"string"},"replacedOid":{"type":"integer"},"cancelledOld":{"type":"boolean"},"replacementCancelled":{"type":"boolean","description":"Present when the old order filled before it could be cancelled: true = the replacement was cancelled instead"},"size":{"type":"string"},"notional":{"type":["string","null"]},"orders":{"type":"array","items":{"$ref":"#/components/schemas/OrderLeg"}},"warning":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/positions/{coin}/close":{"post":{"summary":"Close a position at market (reduce-only)","x-scope":"trade","parameters":[{"name":"coin","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"size":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"Part of the position to close (default: all)"},"slippageBps":{"type":"integer","minimum":0,"maximum":5000}}}}}},"responses":{"201":{"description":"Close order sent","content":{"application/json":{"schema":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/OrderLeg"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/positions/{coin}/tpsl":{"put":{"summary":"Set the position's take-profit and/or stop-loss (replaces the previous ones)","x-scope":"trade","parameters":[{"name":"coin","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"tpPx":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"Take-profit trigger"},"slPx":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"Stop-loss trigger"},"slippageBps":{"type":"integer","minimum":0,"maximum":5000}}}}}},"responses":{"200":{"description":"TP/SL placed"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/leverage":{"put":{"summary":"Set leverage and margin mode for a coin","x-scope":"trade","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["coin","leverage","isCross"],"additionalProperties":false,"properties":{"coin":{"type":"string"},"leverage":{"type":"integer","minimum":1,"maximum":100,"description":"Also capped by the market's maxLeverage (see /markets)"},"isCross":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"coin":{"type":"string"},"leverage":{"type":"integer"},"isCross":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/dead-mans-switch":{"get":{"summary":"Dead man's switch state","x-scope":"read","responses":{"200":{"description":"armedUntil: epoch ms when the scheduled cancel-all fires, or null (not armed, already fired, or disarmed). Informational: Hyperliquid cannot be asked, this is what DCFTP last armed.","content":{"application/json":{"schema":{"type":"object","properties":{"armedUntil":{"type":["integer","null"]}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Arm the dead man's switch (Hyperliquid scheduleCancel) for N seconds","x-scope":"trade","description":"When the time passes, Hyperliquid cancels ALL of your open orders on every market, including orders placed from the DCFTP app or any other client (resting limits, stops, TP/SL; positions stay open). Nothing re-arms it: a bot that wants to stay protected calls this again before it fires (e.g. every 30 s with seconds=60); calling again moves the time. Hyperliquid enforces a minimum traded volume before an account may use it and returns 400 exchange_rejected with its own text otherwise. 5 s to 24 h.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["seconds"],"additionalProperties":false,"properties":{"seconds":{"type":"integer","minimum":5,"maximum":86400,"description":"Lead until the cancel-all fires"}}}}}},"responses":{"200":{"description":"Armed","content":{"application/json":{"schema":{"type":"object","properties":{"armedUntil":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Disarm the dead man's switch (deletes every scheduled cancel)","x-scope":"trade","responses":{"200":{"description":"Disarmed","content":{"application/json":{"schema":{"type":"object","properties":{"armedUntil":{"type":"null"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/openapi.json":{"get":{"summary":"This document","security":[],"responses":{"200":{"description":"OpenAPI 3.1"}}}}}}