{"openapi":"3.1.0","info":{"title":"PerpCity Bot API","description":"Bot & AI Agent API for PerpCity market data","version":"0.1.0"},"paths":{"/v1/markets":{"get":{"tags":["Markets (v1, frozen)"],"summary":"List Markets","operationId":"list_markets_v1_markets_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__common__PaginatedResponse_MarketResponse___1"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/markets/{market_id}":{"get":{"tags":["Markets (v1, frozen)"],"summary":"Get Market","operationId":"get_market_v1_markets__market_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"market_id","in":"path","required":true,"schema":{"type":"string","title":"Market Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__v1__markets__MarketDetailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/markets/{market_id}/live":{"get":{"tags":["Markets (v1, frozen)"],"summary":"Get Live Market","operationId":"get_live_market_v1_markets__market_id__live_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"market_id","in":"path","required":true,"schema":{"type":"string","title":"Market Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__v1__markets__LiveMarketResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/markets/{market_id}/oi":{"get":{"tags":["Markets (v1, frozen)"],"summary":"Get Oi History","operationId":"get_oi_history_v1_markets__market_id__oi_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"market_id","in":"path","required":true,"schema":{"type":"string","title":"Market Id"}},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start Time"}},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Time"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_OIResponse_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/markets/{market_id}/stats":{"get":{"tags":["Markets (v1, frozen)"],"summary":"Get Market Stats","operationId":"get_market_stats_v1_markets__market_id__stats_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"market_id","in":"path","required":true,"schema":{"type":"string","title":"Market Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__v1__markets__StatsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/markets/{market_id}/snapshots":{"get":{"tags":["Markets (v1, frozen)"],"summary":"Get Snapshots","operationId":"get_snapshots_v1_markets__market_id__snapshots_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"market_id","in":"path","required":true,"schema":{"type":"string","title":"Market Id"}},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start Time"}},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Time"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__common__PaginatedResponse_SnapshotResponse___1"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/markets/{market_id}/trades":{"get":{"tags":["Markets (v1, frozen)"],"summary":"Get Market Trades","operationId":"get_market_trades_v1_markets__market_id__trades_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"market_id","in":"path","required":true,"schema":{"type":"string","title":"Market Id"}},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start Time"}},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Time"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__common__PaginatedResponse_TradeResponse___1"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/positions":{"get":{"tags":["Positions (v1, frozen)"],"summary":"List Positions","operationId":"list_positions_v1_positions_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"wallet","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by wallet address (hex)","title":"Wallet"},"description":"Filter by wallet address (hex)"},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by market/perp ID (hex)","title":"Market Id"},"description":"Filter by market/perp ID (hex)"},{"name":"is_open","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Open"}},{"name":"is_maker","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Maker"}},{"name":"is_long","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Long"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__common__PaginatedResponse_PositionResponse___1"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/positions/liquidatable":{"get":{"tags":["Positions (v1, frozen)"],"summary":"List Liquidatable Positions","description":"Indexed-only liquidatable-candidate filter (NO on-chain eth_call).\n\nReturns a PERMISSIVE candidate set computed purely from indexed Goldsky data,\nplus the execution params a liquidation bot needs (`amount`, `is_maker`,\n`perp`, `id`). The bot-api is a public surface and must never fan out to the\nRPC per request; exactness is the bot's job -- it confirms each candidate\ngas-free (simulate before send) before spending gas. A row here is \"worth\nchecking\", not \"guaranteed liquidatable\".","operationId":"list_liquidatable_positions_v1_positions_liquidatable_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by market/perp ID (hex)","title":"Market Id"},"description":"Filter by market/perp ID (hex)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__common__PaginatedResponse_LiquidatablePositionResponse___1"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/positions/{position_id}":{"get":{"tags":["Positions (v1, frozen)"],"summary":"Get Position","operationId":"get_position_v1_positions__position_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"position_id","in":"path","required":true,"schema":{"type":"integer","title":"Position Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__v1__positions__PositionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/keys":{"post":{"tags":["Admin (v1, frozen)"],"summary":"Create Key","description":"Create a new API key.","operationId":"create_key_v1_admin_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__routers__v1__admin__CreateKeyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/markets":{"get":{"tags":["Markets"],"summary":"List Markets","operationId":"list_markets_markets_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"beacon","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by beacon address (hex)","title":"Beacon"},"description":"Filter by beacon address (hex)"},{"name":"min_open_interest","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0.0},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"description":"Filter by open_interest_long + open_interest_short >= value","title":"Min Open Interest"},"description":"Filter by open_interest_long + open_interest_short >= value"},{"name":"max_open_interest","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0.0},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"description":"Filter by open_interest_long + open_interest_short <= value","title":"Max Open Interest"},"description":"Filter by open_interest_long + open_interest_short <= value"},{"name":"has_liquidity","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by liquidity > 0","title":"Has Liquidity"},"description":"Filter by liquidity > 0"},{"name":"active","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by any open interest or liquidity present","title":"Active"},"description":"Filter by any open interest or liquidity present"},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Substring match over name/symbol/ticker","title":"Q"},"description":"Substring match over name/symbol/ticker"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","pattern":"^(open_interest|funding|liquidity|created)$","description":"open_interest|funding|liquidity|created","default":"created","title":"Sort"},"description":"open_interest|funding|liquidity|created"},{"name":"order","in":"query","required":false,"schema":{"type":"string","pattern":"^(asc|desc)$","description":"asc|desc","default":"desc","title":"Order"},"description":"asc|desc"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__common__PaginatedResponse_MarketResponse___2"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/markets/{perp_address}":{"get":{"tags":["Markets"],"summary":"Get Market","operationId":"get_market_markets__perp_address__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"perp_address","in":"path","required":true,"schema":{"type":"string","title":"Perp Address"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__markets__MarketDetailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/markets/{perp_address}/live":{"get":{"tags":["Markets"],"summary":"Get Live Market","operationId":"get_live_market_markets__perp_address__live_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"perp_address","in":"path","required":true,"schema":{"type":"string","title":"Perp Address"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__markets__LiveMarketResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/markets/{perp_address}/stats":{"get":{"tags":["Markets"],"summary":"Get Market Stats","operationId":"get_market_stats_markets__perp_address__stats_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"perp_address","in":"path","required":true,"schema":{"type":"string","title":"Perp Address"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__markets__StatsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/markets/{perp_address}/snapshots":{"get":{"tags":["Markets"],"summary":"Get Snapshots","operationId":"get_snapshots_markets__perp_address__snapshots_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"perp_address","in":"path","required":true,"schema":{"type":"string","title":"Perp Address"}},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start Time"}},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Time"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__common__PaginatedResponse_SnapshotResponse___2"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/markets/{perp_address}/trades":{"get":{"tags":["Markets"],"summary":"Get Market Trades","operationId":"get_market_trades_markets__perp_address__trades_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"perp_address","in":"path","required":true,"schema":{"type":"string","title":"Perp Address"}},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start Time"}},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Time"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__common__PaginatedResponse_TradeResponse___2"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/markets/{ticker}/history":{"get":{"tags":["Markets"],"summary":"Get Market History","description":"Full merged beacon pre-history: raw source values AND index, from before\nthe beacon existed on-chain through the live on-chain series, keyed by the\nmarket's `ticker`.\n\nIndexed-only (no eth_calls / RPC): resolves the ticker via `market_metadata`\n(app-backend DB) and reads `series_history` + `beacon_snapshot` from the\nGoldsky/Tiger DB. Requires BOTH DBs (ticker resolution + the merge), so it\ndepends on `get_app_backend_db` directly rather than the graceful-degrade\noptional wrapper used by the cosmetics-only endpoints.","operationId":"get_market_history_markets__ticker__history_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start Time"}},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Time"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":500,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_MarketHistoryPoint_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/positions":{"get":{"tags":["Positions"],"summary":"List Positions","operationId":"list_positions_positions_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"holder","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by holder wallet address (hex)","title":"Holder"},"description":"Filter by holder wallet address (hex)"},{"name":"is_open","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Open"}},{"name":"is_maker","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Maker"}},{"name":"is_long","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Long"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"perp_address","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Perp contract address (hex) -- canonical identifier","title":"Perp Address"},"description":"Perp contract address (hex) -- canonical identifier"},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Deprecated alias for perp_address (legacy /v1 naming)","deprecated":true,"title":"Market Id"},"description":"Deprecated alias for perp_address (legacy /v1 naming)","deprecated":true},{"name":"perp","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Deprecated alias for perp_address","deprecated":true,"title":"Perp"},"description":"Deprecated alias for perp_address","deprecated":true},{"name":"perp_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Deprecated alias for perp_address","deprecated":true,"title":"Perp Id"},"description":"Deprecated alias for perp_address","deprecated":true}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__common__PaginatedResponse_PositionResponse___2"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/positions/liquidatable":{"get":{"tags":["Positions"],"summary":"List Liquidatable Positions","description":"Indexed-only liquidatable-candidate filter (NO on-chain eth_call), enriched\nwith holder/notional/health/distance-to-liquidation/estimated-reward/staleness.\n\nReturns a PERMISSIVE candidate set computed purely from indexed Goldsky data,\nplus the execution params a liquidation bot needs (`amount`, `is_maker`,\n`perp_address`, `id`). The bot-api is a public surface and must never fan out\nto the RPC per request; exactness is the bot's job -- it confirms each\ncandidate gas-free (simulate before send) before spending gas. A row here is\n\"worth checking\", not \"guaranteed liquidatable\".","operationId":"list_liquidatable_positions_positions_liquidatable_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"sort","in":"query","required":false,"schema":{"type":"string","pattern":"^(most_underwater|largest_reward)$","description":"most_underwater (default) | largest_reward","default":"most_underwater","title":"Sort"},"description":"most_underwater (default) | largest_reward"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"perp_address","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Perp contract address (hex) -- canonical identifier","title":"Perp Address"},"description":"Perp contract address (hex) -- canonical identifier"},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Deprecated alias for perp_address (legacy /v1 naming)","deprecated":true,"title":"Market Id"},"description":"Deprecated alias for perp_address (legacy /v1 naming)","deprecated":true},{"name":"perp","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Deprecated alias for perp_address","deprecated":true,"title":"Perp"},"description":"Deprecated alias for perp_address","deprecated":true},{"name":"perp_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Deprecated alias for perp_address","deprecated":true,"title":"Perp Id"},"description":"Deprecated alias for perp_address","deprecated":true}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__common__PaginatedResponse_LiquidatablePositionResponse___2"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/positions/{position_id}":{"get":{"tags":["Positions"],"summary":"Get Position","operationId":"get_position_positions__position_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"position_id","in":"path","required":true,"schema":{"type":"integer","title":"Position Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__positions__PositionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/keys":{"post":{"tags":["Admin"],"summary":"Create Key","description":"Create a new API key.","operationId":"create_key_admin_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__routers__admin__CreateKeyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/auth/keys":{"get":{"tags":["Developer Signup"],"summary":"List Keys","description":"List the authenticated developer's keys (previews only, never the secret).","operationId":"list_keys_auth_keys_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/KeyInfo"},"type":"array","title":"Response List Keys Auth Keys Get"}}}}},"security":[{"HTTPBearer":[]}]},"post":{"tags":["Developer Signup"],"summary":"Create Key","description":"Issue a new pc_bot_ key for the Privy-authenticated developer.","operationId":"create_key_auth_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__routers__auth__CreateKeyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewKeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/auth/keys/{key_id}":{"delete":{"tags":["Developer Signup"],"summary":"Revoke Key","description":"Revoke one of the authenticated developer's keys (idempotent-ish).","operationId":"revoke_key_auth_keys__key_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"integer","title":"Key Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/":{"get":{"summary":"Root","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"KeyInfo":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"key_preview":{"type":"string","title":"Key Preview"},"is_active":{"type":"boolean","title":"Is Active"},"created_at":{"type":"string","title":"Created At"},"last_used_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used At"}},"type":"object","required":["id","name","key_preview","is_active","created_at"],"title":"KeyInfo","description":"Key metadata for listing -- never includes the full secret."},"KeyResponse":{"properties":{"id":{"type":"integer","title":"Id"},"key":{"type":"string","title":"Key"},"name":{"type":"string","title":"Name"},"is_active":{"type":"boolean","title":"Is Active"},"created_at":{"type":"string","title":"Created At"},"last_used_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used At"}},"type":"object","required":["id","key","name","is_active","created_at"],"title":"KeyResponse"},"LiquidatableHealth":{"properties":{"margin_ratio":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Margin Ratio","description":"Approx indexed margin ratio (equity/notional); None if uncomputable"},"liq_margin_ratio":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Liq Margin Ratio","description":"Maintenance (liquidation) margin ratio threshold, decimal form"}},"type":"object","title":"LiquidatableHealth","description":"Margin-ratio health snapshot for a liquidatable candidate."},"MarketHistoryPoint":{"properties":{"ts":{"type":"string","format":"date-time","title":"Ts"},"raw_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Raw Value","description":"Raw source measurement (series_history; whole life)"},"index_x96":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Index X96","description":"Q96 index for this tick (None if NULL/<=0)"},"origin":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origin","description":"Provenance: backfill | mirror | folded (pre-boundary) or chain (live)"}},"type":"object","required":["ts"],"title":"MarketHistoryPoint","description":"One point of a market's merged pre-history + live series.\n\nBoth legs are returned as raw points (no forward-fill): `raw_value` is the\nraw source measurement (from `series_history`, present for the whole life),\nand `index_x96` is the Q96 index following the time-split (pre-boundary from\n`series_history`, at/after the boundary from on-chain `beacon_snapshot`).\n`index_x96` is None when that tick carries no index (NULL / <= 0) -- the raw\npoint still stands. See `MarketDataService.get_market_history` for the full\nmerge contract shared with the backend-api."},"NewKeyResponse":{"properties":{"id":{"type":"integer","title":"Id"},"key":{"type":"string","title":"Key"},"name":{"type":"string","title":"Name"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","key","name","created_at"],"title":"NewKeyResponse","description":"Returned once, at creation -- the only time the full key is exposed."},"OIResponse":{"properties":{"perp_id":{"type":"string","title":"Perp Id"},"taker_long_oi":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Taker Long Oi"},"taker_short_oi":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Taker Short Oi"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"}},"type":"object","required":["perp_id","taker_long_oi","taker_short_oi","timestamp"],"title":"OIResponse","description":"Historical OI point.\n\nNOTE: Under v0.1.0, OI history is no longer stored on `PerpSnapshot`;\nit must be summed from `TakerAction.long_oi_delta` /\n`short_oi_delta`. The endpoint backed by this shape currently returns\nan empty page -- see `MarketDataService.get_oi_history` for the\ndeprecation note."},"PaginatedResponse_MarketHistoryPoint_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/MarketHistoryPoint"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["items","total","limit","offset","has_more"],"title":"PaginatedResponse[MarketHistoryPoint]"},"PaginatedResponse_OIResponse_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/OIResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["items","total","limit","offset","has_more"],"title":"PaginatedResponse[OIResponse]"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"app__routers__admin__CreateKeyRequest":{"properties":{"name":{"type":"string","title":"Name"}},"type":"object","required":["name"],"title":"CreateKeyRequest"},"app__routers__auth__CreateKeyRequest":{"properties":{"name":{"type":"string","maxLength":100,"title":"Name","default":"default"}},"type":"object","title":"CreateKeyRequest"},"app__routers__v1__admin__CreateKeyRequest":{"properties":{"name":{"type":"string","title":"Name"}},"type":"object","required":["name"],"title":"CreateKeyRequest"},"app__schemas__common__PaginatedResponse_LiquidatablePositionResponse___1":{"properties":{"items":{"items":{"$ref":"#/components/schemas/app__schemas__v1__positions__LiquidatablePositionResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["items","total","limit","offset","has_more"],"title":"PaginatedResponse[LiquidatablePositionResponse]"},"app__schemas__common__PaginatedResponse_LiquidatablePositionResponse___2":{"properties":{"items":{"items":{"$ref":"#/components/schemas/app__schemas__positions__LiquidatablePositionResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["items","total","limit","offset","has_more"],"title":"PaginatedResponse[LiquidatablePositionResponse]"},"app__schemas__common__PaginatedResponse_MarketResponse___1":{"properties":{"items":{"items":{"$ref":"#/components/schemas/app__schemas__v1__markets__MarketResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["items","total","limit","offset","has_more"],"title":"PaginatedResponse[MarketResponse]"},"app__schemas__common__PaginatedResponse_MarketResponse___2":{"properties":{"items":{"items":{"$ref":"#/components/schemas/app__schemas__markets__MarketResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["items","total","limit","offset","has_more"],"title":"PaginatedResponse[MarketResponse]"},"app__schemas__common__PaginatedResponse_PositionResponse___1":{"properties":{"items":{"items":{"$ref":"#/components/schemas/app__schemas__v1__positions__PositionResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["items","total","limit","offset","has_more"],"title":"PaginatedResponse[PositionResponse]"},"app__schemas__common__PaginatedResponse_PositionResponse___2":{"properties":{"items":{"items":{"$ref":"#/components/schemas/app__schemas__positions__PositionResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["items","total","limit","offset","has_more"],"title":"PaginatedResponse[PositionResponse]"},"app__schemas__common__PaginatedResponse_SnapshotResponse___1":{"properties":{"items":{"items":{"$ref":"#/components/schemas/app__schemas__v1__markets__SnapshotResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["items","total","limit","offset","has_more"],"title":"PaginatedResponse[SnapshotResponse]"},"app__schemas__common__PaginatedResponse_SnapshotResponse___2":{"properties":{"items":{"items":{"$ref":"#/components/schemas/app__schemas__markets__SnapshotResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["items","total","limit","offset","has_more"],"title":"PaginatedResponse[SnapshotResponse]"},"app__schemas__common__PaginatedResponse_TradeResponse___1":{"properties":{"items":{"items":{"$ref":"#/components/schemas/app__schemas__v1__markets__TradeResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["items","total","limit","offset","has_more"],"title":"PaginatedResponse[TradeResponse]"},"app__schemas__common__PaginatedResponse_TradeResponse___2":{"properties":{"items":{"items":{"$ref":"#/components/schemas/app__schemas__markets__TradeResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["items","total","limit","offset","has_more"],"title":"PaginatedResponse[TradeResponse]"},"app__schemas__markets__LiveMarketResponse":{"properties":{"perp_address":{"type":"string","title":"Perp Address"},"perp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Perp","description":"Deprecated alias for perp_address"},"mark_price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Mark Price"},"index_price":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Index Price"},"funding_rate_daily":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Funding Rate Daily"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"}},"type":"object","required":["perp_address","mark_price","timestamp"],"title":"LiveMarketResponse"},"app__schemas__markets__MarketDetailResponse":{"properties":{"market":{"$ref":"#/components/schemas/app__schemas__markets__MarketResponse"},"latest_snapshot":{"anyOf":[{"$ref":"#/components/schemas/app__schemas__markets__SnapshotResponse"},{"type":"null"}]},"live":{"anyOf":[{"$ref":"#/components/schemas/app__schemas__markets__LiveMarketResponse"},{"type":"null"}],"description":"Live mark/index/funding folded in (None if no snapshot data yet)"}},"type":"object","required":["market"],"title":"MarketDetailResponse"},"app__schemas__markets__MarketResponse":{"properties":{"perp_address":{"type":"string","title":"Perp Address","description":"Perp contract address, hex"},"perp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Perp","description":"Deprecated alias for perp_address"},"beacon_address":{"type":"string","title":"Beacon Address","description":"Beacon address, hex"},"owner":{"type":"string","title":"Owner"},"name":{"type":"string","title":"Name"},"symbol":{"type":"string","title":"Symbol"},"token_uri":{"type":"string","title":"Token Uri"},"pool_id":{"type":"string","title":"Pool Id"},"pricing_module":{"type":"string","title":"Pricing Module"},"funding_module":{"type":"string","title":"Funding Module"},"fees_module":{"type":"string","title":"Fees Module"},"margin_ratios_module":{"type":"string","title":"Margin Ratios Module"},"price_impact_module":{"type":"string","title":"Price Impact Module"},"ema_window":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Ema Window"},"protocol_fee":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Protocol Fee"},"mark_price":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Mark Price","description":"Decoded from ema_amm_price_x96"},"index_price":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Index Price","description":"Decoded from ema_index_price_x96"},"funding_rate_daily":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Funding Rate Daily","description":"funding_per_day"},"open_interest_long":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Open Interest Long"},"open_interest_short":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Open Interest Short"},"capacity_long":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Capacity Long"},"capacity_short":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Capacity Short"},"liquidity":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Liquidity"},"tick":{"type":"integer","title":"Tick"},"insurance":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Insurance"},"bad_debt":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Bad Debt"},"total_margin":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Margin"},"created_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Created At"},"last_touched_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Touched At"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Market description"},"photo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Photo Url","description":"Market photo URL"},"data_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Source","description":"Data source identifier"},"card_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Label","description":"Card display label"},"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker","description":"Short ticker symbol"}},"type":"object","required":["perp_address","beacon_address","owner","name","symbol","token_uri","pool_id","pricing_module","funding_module","fees_module","margin_ratios_module","price_impact_module","ema_window","protocol_fee","open_interest_long","open_interest_short","capacity_long","capacity_short","liquidity","tick","insurance","bad_debt","total_margin"],"title":"MarketResponse","description":"Rich market state from the indexed `Perp` entity, plus optional\napp-backend cosmetics (graceful no-op if that DB isn't configured)."},"app__schemas__markets__SnapshotResponse":{"properties":{"id":{"type":"integer","title":"Id"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"},"perp_address":{"type":"string","title":"Perp Address"},"perp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Perp","description":"Deprecated alias for perp_address"},"amm_price_x96":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amm Price X96"},"mark_price":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Mark Price","description":"Derived from amm_price_x96: (x / 2**96)**2"}},"type":"object","required":["id","timestamp","perp_address","amm_price_x96"],"title":"SnapshotResponse","description":"Per-AMM-tick market snapshot. See `app/schemas/v1/markets.py` for the\nv0.1.0 subgraph field-trimming notes -- unchanged here except the\nidentifier (`perp_address` canonical, `perp` deprecated alias)."},"app__schemas__markets__StatsResponse":{"properties":{"perp_address":{"type":"string","title":"Perp Address"},"perp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Perp","description":"Deprecated alias for perp_address"},"price_24h_high":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price 24H High"},"price_24h_low":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price 24H Low"},"price_24h_change":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price 24H Change"},"price_24h_change_percent":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price 24H Change Percent"}},"type":"object","required":["perp_address","price_24h_high","price_24h_low","price_24h_change","price_24h_change_percent"],"title":"StatsResponse"},"app__schemas__markets__TradeResponse":{"properties":{"id":{"type":"integer","title":"Id"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"},"perp_address":{"type":"string","title":"Perp Address"},"perp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Perp","description":"Deprecated alias for perp_address"},"pos_id":{"type":"integer","title":"Pos Id"},"was_liquidated":{"type":"boolean","title":"Was Liquidated"},"perp_delta":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Perp Delta"},"usd_delta":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Usd Delta"},"mark_price":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Mark Price"},"funding":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Funding"},"util_fees":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Util Fees"},"liq_fee":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Liq Fee"}},"type":"object","required":["id","timestamp","perp_address","pos_id","was_liquidated","perp_delta","usd_delta"],"title":"TradeResponse","description":"Recent close trade derived from `TakerAction` where `action_type='Close'`.\nSee `app/schemas/v1/markets.py` for field-provenance notes -- unchanged\nhere except the identifier (`perp_address` canonical, `perp` deprecated\nalias)."},"app__schemas__positions__LiquidatablePositionResponse":{"properties":{"id":{"type":"integer","title":"Id","description":"On-chain position id (pos_id)"},"perp_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Perp Address","description":"Market (Perp) contract address, hex"},"perp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Perp","description":"Deprecated alias for perp_address"},"is_maker":{"type":"boolean","title":"Is Maker"},"amount":{"type":"string","title":"Amount","description":"Full liquidation size as an integer string (base units): |perp_delta| for takers, liquidity for makers"},"mode":{"type":"string","title":"Mode","description":"Liquidation mode (V1 == full)","default":"full"},"margin_ratio":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Margin Ratio","description":"Approx indexed margin ratio (equity/notional); None if uncomputable"},"liq_margin_ratio":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Liq Margin Ratio","description":"Maintenance (liquidation) margin ratio threshold, decimal form"},"as_of":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"As Of","description":"Unix ts of the mark snapshot used (indexed-data freshness)"},"holder":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Holder","description":"Position holder wallet address, hex"},"notional":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Notional","description":"|perp_delta| * mark_price; None if uncomputable"},"health":{"$ref":"#/components/schemas/LiquidatableHealth"},"distance_to_liquidation":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Distance To Liquidation","description":"Unbuffered margin_ratio - liq_margin_ratio; non-positive means already past the raw (unbuffered) threshold"},"estimated_reward":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Estimated Reward","description":"Rough indexed-only estimate of the liquidator reward -- a prioritization signal, NOT a guarantee of the on-chain payout"},"is_stale":{"type":"boolean","title":"Is Stale","description":"True if the indexed mark snapshot predates the staleness threshold, or freshness is unknown","default":true}},"type":"object","required":["id","is_maker","amount"],"title":"LiquidatablePositionResponse","description":"A liquidatable CANDIDATE plus the params a liquidation bot needs.\n\nComputed from indexed data only (no on-chain `eth_call`) and PERMISSIVE by\ndesign: a row here means \"worth confirming\", NOT \"guaranteed liquidatable\".\nThe consuming bot MUST confirm exactly on-chain (gas-free simulate before\nsend) before spending gas.\n\nKeeps every `/v1` field for parity plus additive enrichment: `holder`,\n`notional`, `health`, `distance_to_liquidation`, `estimated_reward`,\n`is_stale`."},"app__schemas__positions__PositionResponse":{"properties":{"id":{"type":"integer","title":"Id","description":"On-chain position id (pos_id)"},"open_timestamp":{"type":"integer","title":"Open Timestamp"},"perp_address":{"type":"string","title":"Perp Address","description":"Market (Perp) contract address, hex"},"perp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Perp","description":"Deprecated alias for perp_address"},"holder":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Holder"},"is_maker":{"type":"boolean","title":"Is Maker"},"is_long":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Long"},"is_closed":{"type":"boolean","title":"Is Closed"},"close_timestamp":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Close Timestamp"},"was_liquidated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Was Liquidated"},"margin":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Margin"},"perp_delta":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Perp Delta"},"usd_delta":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Usd Delta"},"avg_entry_amm_price_x96":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Avg Entry Amm Price X96"},"liq_margin_ratio":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Liq Margin Ratio"},"backstop_margin_ratio":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Backstop Margin Ratio"},"current_mark_price":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Current Mark Price"},"unrealized_pnl":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Unrealized Pnl"},"effective_margin":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Effective Margin"}},"type":"object","required":["id","open_timestamp","perp_address","is_maker","is_closed"],"title":"PositionResponse","description":"Response shape for a single position from `/positions`.\n\nSourced from the v0.1.0 Goldsky `Position` entity (see\n`app/schemas/v1/positions.py` for field provenance notes -- unchanged\nhere except the identifier: `perp_address` is canonical, `perp` is a\ndeprecated alias carrying the same value."},"app__schemas__v1__markets__LiveMarketResponse":{"properties":{"perp_id":{"type":"string","title":"Perp Id"},"mark_price":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Mark Price"},"index_price":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Index Price"},"funding_rate_daily":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Funding Rate Daily"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"}},"type":"object","required":["perp_id","mark_price","timestamp"],"title":"LiveMarketResponse"},"app__schemas__v1__markets__MarketDetailResponse":{"properties":{"market":{"$ref":"#/components/schemas/app__schemas__v1__markets__MarketResponse"},"latest_snapshot":{"anyOf":[{"$ref":"#/components/schemas/app__schemas__v1__markets__SnapshotResponse"},{"type":"null"}]}},"type":"object","required":["market"],"title":"MarketDetailResponse"},"app__schemas__v1__markets__MarketResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Perp ID (hex)"},"beacon":{"type":"string","title":"Beacon","description":"Beacon address (hex)"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Human-readable market name"},"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker","description":"Short ticker symbol"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Market description"},"photo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Photo Url","description":"Market photo URL"},"data_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Source","description":"Data source identifier"},"card_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Label","description":"Card display label"}},"type":"object","required":["id","beacon"],"title":"MarketResponse"},"app__schemas__v1__markets__SnapshotResponse":{"properties":{"id":{"type":"integer","title":"Id"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"},"perp":{"type":"string","title":"Perp"},"amm_price_x96":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amm Price X96"},"mark_price":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Mark Price","description":"Derived from amm_price_x96: (x / 2**96)**2"}},"type":"object","required":["id","timestamp","perp","amm_price_x96"],"title":"SnapshotResponse","description":"Per-AMM-tick market snapshot.\n\nv0.1.0 trimmed `PerpSnapshot` down to `id`, `timestamp`, `perp`, and\n`amm_price_x96`. We expose a derived `mark_price` (= `(x / 2^96)^2`)\nfor backward-compat. The OI/notional fields previously on snapshot\nare now on `Perp` directly (current value only); historical OI must\nbe summed from `TakerAction.long_oi_delta` / `short_oi_delta` and is\nnot currently surfaced."},"app__schemas__v1__markets__StatsResponse":{"properties":{"perp_id":{"type":"string","title":"Perp Id"},"price_24h_high":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price 24H High"},"price_24h_low":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price 24H Low"},"price_24h_change":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price 24H Change"},"price_24h_change_percent":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Price 24H Change Percent"}},"type":"object","required":["perp_id","price_24h_high","price_24h_low","price_24h_change","price_24h_change_percent"],"title":"StatsResponse"},"app__schemas__v1__markets__TradeResponse":{"properties":{"id":{"type":"integer","title":"Id"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"},"perp":{"type":"string","title":"Perp"},"pos_id":{"type":"integer","title":"Pos Id"},"was_liquidated":{"type":"boolean","title":"Was Liquidated"},"perp_delta":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Perp Delta"},"usd_delta":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Usd Delta"},"mark_price":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Mark Price"},"funding":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Funding"},"util_fees":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Util Fees"},"liq_fee":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Liq Fee"}},"type":"object","required":["id","timestamp","perp","pos_id","was_liquidated","perp_delta","usd_delta"],"title":"TradeResponse","description":"Recent close trade derived from `TakerAction` where\n`action_type='Close'`.\n\nField changes vs. the legacy schema:\n\n- `tx_hash` and `was_partial_close` are no longer in the subgraph and\n  have been dropped.\n- `was_maker` is removed -- this endpoint surfaces taker closes only.\n- `was_liquidated` maps to the new `liquidation` boolean.\n- `exit_perp_delta` / `exit_usd_delta` map to `perp_delta` / `usd_delta`.\n- `mark_price` is derived from `avg_execution_price_x96`."},"app__schemas__v1__positions__LiquidatablePositionResponse":{"properties":{"id":{"type":"integer","title":"Id","description":"On-chain position id (pos_id)"},"perp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Perp","description":"Market (Perp) contract address, hex"},"is_maker":{"type":"boolean","title":"Is Maker"},"amount":{"type":"string","title":"Amount","description":"Full liquidation size as an integer string (base units): |perp_delta| for takers, liquidity for makers"},"mode":{"type":"string","title":"Mode","description":"Liquidation mode (V1 == full)","default":"full"},"margin_ratio":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Margin Ratio","description":"Approx indexed margin ratio (equity/notional); None if uncomputable"},"liq_margin_ratio":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Liq Margin Ratio","description":"Maintenance (liquidation) margin ratio threshold, decimal form"},"as_of":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"As Of","description":"Unix ts of the mark snapshot used (indexed-data freshness)"}},"type":"object","required":["id","is_maker","amount"],"title":"LiquidatablePositionResponse","description":"A liquidatable CANDIDATE plus the params a liquidation bot needs.\n\nComputed from indexed data only (no on-chain `eth_call`) and PERMISSIVE by\ndesign: a row here means \"worth confirming\", NOT \"guaranteed liquidatable\".\nThe consuming bot MUST confirm exactly on-chain (gas-free simulate before\nsend) before spending gas."},"app__schemas__v1__positions__PositionResponse":{"properties":{"id":{"type":"integer","title":"Id","description":"On-chain position id (pos_id)"},"open_timestamp":{"type":"integer","title":"Open Timestamp"},"perp":{"type":"string","title":"Perp"},"holder":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Holder"},"is_maker":{"type":"boolean","title":"Is Maker"},"is_long":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Long"},"is_closed":{"type":"boolean","title":"Is Closed"},"close_timestamp":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Close Timestamp"},"was_liquidated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Was Liquidated"},"margin":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Margin"},"perp_delta":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Perp Delta"},"usd_delta":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Usd Delta"},"avg_entry_amm_price_x96":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Avg Entry Amm Price X96"},"liq_margin_ratio":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Liq Margin Ratio"},"backstop_margin_ratio":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Backstop Margin Ratio"},"current_mark_price":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Current Mark Price"},"unrealized_pnl":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Unrealized Pnl"},"effective_margin":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Effective Margin"}},"type":"object","required":["id","open_timestamp","perp","is_maker","is_closed"],"title":"PositionResponse","description":"Response shape for a single position from `/v1/positions`.\n\nThe wire shape preserves the keys clients have historically depended on\n(`id`, `perp`, `is_long`, `was_liquidated`, `open_timestamp`,\n`close_timestamp`) while sourcing them from the v0.1.0 Goldsky entity:\n\n- `id` is the on-chain `pos_id` (BigInt) -- the subgraph's bytes-typed\n  `id` is the internal entity hash and not what consumers want.\n- `is_long` is derived from `sign(perp_delta)` since the subgraph no\n  longer exposes it directly.\n- `was_liquidated` coalesces the new `wasMakerLiquidated` and\n  `wasTakerLiquidated` booleans.\n- `open_timestamp` / `close_timestamp` are aliased onto the renamed\n  `openedAtTimestamp` / `closedAtTimestamp`.\n\nNew fields surfaced from v0.1.0: `margin`, `perp_delta`, `usd_delta`,\n`liq_margin_ratio`, `backstop_margin_ratio`, `avg_entry_amm_price_x96`."}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-Admin-Secret"},"HTTPBearer":{"type":"http","scheme":"bearer"}}}}