{"openapi":"3.1.0","info":{"title":"Killbot Strategy API","version":"1.0.0","description":"Stream of trading decisions of a live Killbot strategy, for execution on your own account. Information for your own execution decisions, not investment advice. Past performance does not guarantee future results.","contact":{"name":"Killbot","url":"https://killbot.cash/partners"},"license":{"name":"Proprietary — use under the Killbot partner agreement","url":"https://killbot.cash/terms"}},"servers":[{"url":"https://api.killbot.cash/api/v1"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Issued in the partner dashboard. We store only its SHA-256 hash — a lost key is replaced, never recovered."}},"schemas":{"Event":{"type":"object","required":["id","strategyId","kind","tradeId","symbol","side","riskShare","price","decidedMs"],"properties":{"id":{"type":"integer","description":"Cursor value. Pass the last one you saw as `after`."},"strategyId":{"type":"string","example":"killbot-core"},"kind":{"type":"string","enum":["open","close"]},"tradeId":{"type":"integer","description":"Position id; an open and its close share it. Use (tradeId, kind) for idempotency — never act twice on the same pair."},"symbol":{"type":"string","example":"ONDOUSDT"},"side":{"type":"string","enum":["long","short"],"description":"Position direction, not order side."},"riskShare":{"type":"number","description":"Position size as a share of the strategy capital (notional ÷ capital). Your size = your capital × riskShare. Across all open positions the sum can exceed 1 — positions use leverage.","example":0.1483},"price":{"type":"number","description":"Our execution price — reference for your slippage control."},"decidedMs":{"type":"integer","format":"int64"},"executedMs":{"type":["integer","null"],"format":"int64"},"closeReason":{"type":["string","null"],"enum":["signal_exit","stop_loss","risk_limit","other",null],"description":"null on open."}}},"Position":{"type":"object","required":["tradeId","symbol","side","riskShare","price"],"properties":{"tradeId":{"type":"integer"},"symbol":{"type":"string"},"side":{"type":"string","enum":["long","short"]},"riskShare":{"type":"number"},"price":{"type":"number"},"executedMs":{"type":["integer","null"],"format":"int64"}}},"Strategy":{"type":"object","required":["id","name","venue"],"properties":{"id":{"type":"string","example":"killbot-core"},"name":{"type":"string"},"description":{"type":"string"},"venue":{"type":"string","example":"binance-usdm-futures"},"instruments":{"type":"string"},"since":{"type":"string","format":"date"},"delaySec":{"type":"integer","description":"Your plan’s delay. 0 = real time."}}}}},"paths":{"/strategies":{"get":{"summary":"Strategies available to your key","operationId":"listStrategies","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"strategies":{"type":"array","items":{"$ref":"#/components/schemas/Strategy"}}}}}}}}},"401":{"description":"Missing or unknown API key."}}}},"/strategies/{id}":{"get":{"summary":"One strategy, with your plan’s delay","operationId":"getStrategy","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Strategy"}}}}}},"401":{"description":"Missing or unknown API key."},"403":{"description":"The key has no access to this strategy."},"404":{"description":"No such strategy."}}}},"/strategies/{id}/events":{"get":{"summary":"Decisions by cursor, in order","description":"Poll with the last cursor you received; start with after=0. When there is nothing new, cursor equals after — keep polling with it.","operationId":"listEvents","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"after","in":"query","schema":{"type":"integer","default":0},"description":"Last event id you processed."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"cursor":{"type":"integer"},"delaySec":{"type":"integer"},"serverTimeMs":{"type":"integer","format":"int64"}}}}}}}},"400":{"description":"Invalid query parameter."},"401":{"description":"Missing or unknown API key."},"403":{"description":"The key has no access to this strategy."},"404":{"description":"No such strategy."},"429":{"description":"Rate limit — 300 requests per minute."}}}},"/strategies/{id}/positions":{"get":{"summary":"Open positions for reconciliation","description":"Derived from the same event log. After downtime: close what is not in this list, treat missing opens as missed. As of now − delaySec on delayed plans.","operationId":"listPositions","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"strategyId":{"type":"string"},"positions":{"type":"array","items":{"$ref":"#/components/schemas/Position"}},"asOfMs":{"type":"integer","format":"int64"},"delaySec":{"type":"integer"}}}}}}}},"401":{"description":"Missing or unknown API key."},"403":{"description":"The key has no access to this strategy."},"404":{"description":"No such strategy."}}}},"/strategies/{id}/performance":{"get":{"summary":"Results as published by Binance Copy Trading","description":"The same numbers anyone sees on the public portfolio page, refreshed every 10 minutes. If Binance is unavailable, windows and aumUsdt are null — never zeros.","operationId":"getPerformance","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"strategyId":{"type":"string"},"source":{"type":"string","example":"binance-copy-trading"},"since":{"type":"string","format":"date"},"windows":{"type":["object","null"],"properties":{"7D":{"type":["object","null"],"properties":{"roiPct":{"type":"number"},"pnlUsdt":{"type":"number"},"maxDrawdownPct":{"type":"number"},"winRatePct":{"type":"number"},"trades":{"type":"integer"}}},"30D":{"type":["object","null"],"properties":{"roiPct":{"type":"number"},"pnlUsdt":{"type":"number"},"maxDrawdownPct":{"type":"number"},"winRatePct":{"type":"number"},"trades":{"type":"integer"}}},"90D":{"type":["object","null"],"properties":{"roiPct":{"type":"number"},"pnlUsdt":{"type":"number"},"maxDrawdownPct":{"type":"number"},"winRatePct":{"type":"number"},"trades":{"type":"integer"}}},"180D":{"type":["object","null"],"properties":{"roiPct":{"type":"number"},"pnlUsdt":{"type":"number"},"maxDrawdownPct":{"type":"number"},"winRatePct":{"type":"number"},"trades":{"type":"integer"}}}}},"aumUsdt":{"type":["number","null"]},"fetchedAtMs":{"type":"integer","format":"int64"}}}}}}}},"401":{"description":"Missing or unknown API key."},"403":{"description":"The key has no access to this strategy."},"404":{"description":"No such strategy."}}}},"/strategies/{id}/webhook":{"get":{"summary":"Delivery state of your webhook","description":"Last delivered event, failures, next retry, last error. Webhooks come with paid plans; deliveries are in order, at least once, HMAC-signed.","operationId":"getWebhookState","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"strategyId":{"type":"string"},"configured":{"type":"boolean"},"lastEventId":{"type":["integer","null"]},"failures":{"type":"integer"},"nextRetryMs":{"type":["integer","null"],"format":"int64"},"lastError":{"type":["string","null"]}}}}}}}},"401":{"description":"Missing or unknown API key."},"403":{"description":"The key has no access to this strategy."},"404":{"description":"No such strategy."}}}}}}