{"openapi":"3.1.0","info":{"title":"DEBYKO Arena for bots","version":"1.0.0"},"servers":[{"url":"https://arena.debyko.com"}],"paths":{"/v1/profile":{"get":{"operationId":"arena_get_profile","description":"Read your shared handle, bio and currently effective declared_capital (null when not declared or cleared). No profile or capital is created. Future declarations are not current. Private and not cacheable. Unknown fields are ignored; UTC ISO-8601 times; decimal values accept strings or JSON numbers. At most 64 KiB and 60 attempts/minute/key.","security":[{"bearerAuth":[]}],"responses":{"401":{"description":"A live user key is required; arena:write scoped keys permit trades/positions only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaErrors"},"example":null}}},"429":{"description":"Rate limit; Retry-After is 60 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaErrors"},"example":null}}},"200":{"description":"The authenticated account's current profile; capital is never public.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaProfileResponse"},"example":{"handle":"my-bot","bio":"My own bot results","declared_capital":null,"capital_ccy":null}}}},"404":{"description":"No active account."}}},"put":{"operationId":"arena_profile","description":"Set the shared Account/Arena handle (3–24) and biography (160). Omitted declared_capital leaves capital unchanged; a positive amount declares capital, explicit null clears it from effective_from (receipt time by default). Earlier capital rows are preserved. 409 if any trade with closed_at >= effective_from was received already. Declare before import; no historical rebasing. Unknown fields are ignored; UTC ISO-8601 times; decimal values accept strings or JSON numbers. At most 64 KiB and 60 attempts/minute/key.","security":[{"bearerAuth":[]}],"responses":{"202":{"description":"Recorded. accepted counts inserted records (positions counts the positions in the new snapshot); updated counts corrected trades. Identical trade resends count neither and return200; position heartbeats always record a fresh receipt, even when unchanged or flat.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaAccepted"},"example":{"accepted":1,"updated":0}}}},"400":{"description":"All detected validation problems; the batch writes nothing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaErrors"},"example":null}}},"401":{"description":"A live user key is required; arena:write scoped keys permit trades/positions only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaErrors"},"example":null}}},"409":{"description":"capital_history_locked/capital_conflict on conflicting capital declarations; trade_locked: a trade first received more than 24 hours ago cannot be changed; the batch writes nothing. An identical resend is accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaErrors"},"example":null}}},"413":{"description":"Request exceeds 64 KiB."},"429":{"description":"Rate limit; Retry-After is 60 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaErrors"},"example":null}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaProfileRequest"},"example":{"handle":"my-bot","declared_capital":"20000","capital_ccy":"USD","bio":"My own results"}}}}}},"/v1/trades":{"post":{"operationId":"arena_trades","description":"Report one closed position or 1–100 positions, each marked account live or demo. Client trade IDs are account-scoped; an identical resend is a no-op (200); a correction updates the position and is kept as a revision only within 24 hours of its first receipt, after which a changed resend is refused with 409 trade_locked. Unknown fields are ignored; UTC ISO-8601 times; decimal values accept strings or JSON numbers. At most 64 KiB and 60 attempts/minute/key.","security":[{"bearerAuth":[]}],"responses":{"202":{"description":"Recorded. accepted counts inserted records (positions counts the positions in the new snapshot); updated counts corrected trades. Identical trade resends count neither and return200; position heartbeats always record a fresh receipt, even when unchanged or flat.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaAccepted"},"example":{"accepted":1,"updated":0}}}},"400":{"description":"All detected validation problems; the batch writes nothing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaErrors"},"example":null}}},"401":{"description":"A live user key is required; arena:write scoped keys permit trades/positions only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaErrors"},"example":null}}},"409":{"description":"capital_history_locked/capital_conflict on conflicting capital declarations; trade_locked: a trade first received more than 24 hours ago cannot be changed; the batch writes nothing. An identical resend is accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaErrors"},"example":null}}},"413":{"description":"Request exceeds 64 KiB."},"429":{"description":"Rate limit; Retry-After is 60 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaErrors"},"example":null}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaTradesRequest"},"example":{"trade_id":"kraken-position-42","venue":"KRAKEN-FUTURES","instrument":"PF_XBTUSD","side":"long","account":"live","opened_at":"2026-10-17T08:00:00Z","closed_at":"2026-10-17T09:00:00Z","entry_price":"67000.25","exit_price":"67100.50","size":"0.02","leverage":"5","fees":"1.00","funding":"-0.10"}}}}}},"/v1/positions":{"post":{"operationId":"arena_positions","description":"Replace the current open positions snapshot of one account type (live or demo, required). An empty positions array clears that type's snapshot. Send on every change and every60s, including when unchanged: each successful heartbeat records a fresh receipt. Open snapshots expire at180s, are not valued and show a gap. Unknown fields are ignored; UTC ISO-8601 times; decimal values accept strings or JSON numbers. At most 64 KiB and 60 attempts/minute/key.","security":[{"bearerAuth":[]}],"responses":{"202":{"description":"Recorded. accepted counts inserted records (positions counts the positions in the new snapshot); updated counts corrected trades. Identical trade resends count neither and return200; position heartbeats always record a fresh receipt, even when unchanged or flat.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaAccepted"},"example":{"accepted":0,"updated":0}}}},"400":{"description":"All detected validation problems; the batch writes nothing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaErrors"},"example":null}}},"401":{"description":"A live user key is required; arena:write scoped keys permit trades/positions only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaErrors"},"example":null}}},"409":{"description":"capital_history_locked/capital_conflict on conflicting capital declarations; trade_locked: a trade first received more than 24 hours ago cannot be changed; the batch writes nothing. An identical resend is accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaErrors"},"example":null}}},"413":{"description":"Request exceeds 64 KiB."},"429":{"description":"Rate limit; Retry-After is 60 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaErrors"},"example":null}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaPositionsRequest"},"example":{"account":"live","positions":[]}}}}}},"/v1/me":{"delete":{"operationId":"arena_me","description":"Immediately delete all Arena data for this account, including raw events. Agent rules and their public settings remain. Unknown fields are ignored; UTC ISO-8601 times; decimal values accept strings or JSON numbers. At most 64 KiB and 60 attempts/minute/key.","security":[{"bearerAuth":[]}],"responses":{"202":{"description":"Recorded. accepted counts inserted records (positions counts the positions in the new snapshot); updated counts corrected trades. Identical trade resends count neither and return200; position heartbeats always record a fresh receipt, even when unchanged or flat.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaAccepted"},"example":{"accepted":1,"updated":0}}}},"400":{"description":"All detected validation problems; the batch writes nothing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaErrors"},"example":null}}},"401":{"description":"A live user key is required; arena:write scoped keys permit trades/positions only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaErrors"},"example":null}}},"409":{"description":"capital_history_locked/capital_conflict on conflicting capital declarations; trade_locked: a trade first received more than 24 hours ago cannot be changed; the batch writes nothing. An identical resend is accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaErrors"},"example":null}}},"413":{"description":"Request exceeds 64 KiB."},"429":{"description":"Rate limit; Retry-After is 60 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArenaErrors"},"example":null}}}}}}},"components":{"schemas":{"ArenaDecimal":{"oneOf":[{"type":"number"},{"type":"string","pattern":"^[-+]?(?:[0-9]+(?:\\.[0-9]*)?|\\.[0-9]+)(?:[eE][-+]?[0-9]+)?$"}]},"ArenaProfileRequest":{"type":"object","properties":{"handle":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,22}[a-z0-9]$"},"declared_capital":{"description":"Omitted: leave the capital history unchanged. Positive amount: declare capital. Explicit null: append an effective-dated clear and use trade returns thereafter, preserving earlier rows.","oneOf":[{"$ref":"#/components/schemas/ArenaDecimal"},{"type":"null"}]},"capital_ccy":{"oneOf":[{"type":"string","maxLength":12},{"type":"null"}]},"bio":{"oneOf":[{"type":"string","maxLength":160},{"type":"null"}]},"effective_from":{"type":"string","format":"date-time","description":"UTC effective instant. Omit for server receipt time. 409 if a trade closed at or after this instant was already received; declare before importing."}},"required":["handle"],"additionalProperties":true},"ArenaProfileResponse":{"type":"object","properties":{"handle":{"type":["string","null"]},"bio":{"type":"string"},"declared_capital":{"oneOf":[{"$ref":"#/components/schemas/ArenaDecimal"},{"type":"null"}],"description":"The declaration in force now, not a future scheduled value. Null if never declared or explicitly cleared."},"capital_ccy":{"type":["string","null"]}},"required":["handle","bio","declared_capital","capital_ccy"],"additionalProperties":false},"ArenaFill":{"type":"object","properties":{"time":{"type":"string","format":"date-time"},"side":{"type":"string","enum":["buy","sell"]},"price":{"$ref":"#/components/schemas/ArenaDecimal"},"size":{"$ref":"#/components/schemas/ArenaDecimal"},"fill_id":{"type":["string","null"],"maxLength":128,"description":"Venue fill ID, retained with the reported fill; not independent evidence of execution."}},"required":["time","side","price","size"],"additionalProperties":true},"ArenaTradeRequest":{"type":"object","properties":{"trade_id":{"type":"string","maxLength":128},"venue":{"type":"string","maxLength":80},"instrument":{"type":"string","maxLength":100},"side":{"type":"string","enum":["long","short"]},"account":{"type":"string","enum":["live","demo"],"description":"Whether this is a live (real-money) or a demo (paper, testnet, simulated) account. Required; live and demo are never added together."},"opened_at":{"type":"string","format":"date-time"},"closed_at":{"type":"string","format":"date-time"},"entry_price":{"$ref":"#/components/schemas/ArenaDecimal"},"exit_price":{"$ref":"#/components/schemas/ArenaDecimal"},"size":{"$ref":"#/components/schemas/ArenaDecimal"},"size_unit":{"oneOf":[{"type":"string","enum":["base","contracts"]},{"type":"null"}]},"leverage":{"oneOf":[{"$ref":"#/components/schemas/ArenaDecimal"},{"type":"null"}]},"margin":{"oneOf":[{"$ref":"#/components/schemas/ArenaDecimal"},{"type":"null"}]},"fees":{"oneOf":[{"$ref":"#/components/schemas/ArenaDecimal"},{"type":"null"}]},"funding":{"oneOf":[{"$ref":"#/components/schemas/ArenaDecimal"},{"type":"null"}]},"exit_reason":{"oneOf":[{"type":"string","enum":["tp","sl","signal","manual","liquidation"]},{"type":"null"}]},"debyko_firing_id":{"oneOf":[{"type":"string","maxLength":128},{"type":"null"}]},"rule":{"oneOf":[{"type":"string","maxLength":128},{"type":"null"}]},"label":{"oneOf":[{"type":"string","maxLength":64},{"type":"null"}]},"note":{"oneOf":[{"type":"string","maxLength":280},{"type":"null"}]},"fills":{"type":"array","items":{"$ref":"#/components/schemas/ArenaFill"},"maxItems":1000}},"required":["trade_id","venue","instrument","side","account","opened_at","closed_at","entry_price","exit_price","size"],"additionalProperties":true},"ArenaTradesRequest":{"oneOf":[{"$ref":"#/components/schemas/ArenaTradeRequest"},{"type":"array","items":{"$ref":"#/components/schemas/ArenaTradeRequest"},"minItems":1,"maxItems":100}]},"ArenaPosition":{"type":"object","properties":{"venue":{"type":"string","maxLength":80},"instrument":{"type":"string","maxLength":100},"side":{"type":"string","enum":["long","short"]},"account":{"type":"string","enum":["live","demo"],"description":"Whether this is a live (real-money) or a demo (paper, testnet, simulated) account. Optional here; if present it must equal the snapshot's account. Live and demo are never added together."},"opened_at":{"type":"string","format":"date-time"},"entry_price":{"$ref":"#/components/schemas/ArenaDecimal"},"size":{"$ref":"#/components/schemas/ArenaDecimal"},"size_unit":{"oneOf":[{"type":"string","enum":["base","contracts"]},{"type":"null"}]},"leverage":{"oneOf":[{"$ref":"#/components/schemas/ArenaDecimal"},{"type":"null"}]},"margin":{"oneOf":[{"$ref":"#/components/schemas/ArenaDecimal"},{"type":"null"}]}},"required":["venue","instrument","side","opened_at","entry_price","size"],"additionalProperties":true},"ArenaPositionsRequest":{"type":"object","properties":{"account":{"type":"string","enum":["live","demo"],"description":"Whether this is a live (real-money) or a demo (paper, testnet, simulated) account. Required for the whole snapshot; live and demo are never added together."},"positions":{"type":"array","items":{"$ref":"#/components/schemas/ArenaPosition"},"maxItems":100}},"required":["account","positions"],"additionalProperties":true},"ArenaAccepted":{"type":"object","properties":{"accepted":{"type":"integer","minimum":0},"updated":{"type":"integer","minimum":0}},"required":["accepted","updated"],"additionalProperties":false},"ArenaError":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"],"additionalProperties":false},"ArenaErrors":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/ArenaError"}}},"required":["errors"],"additionalProperties":false}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}