> For the complete documentation index, see [llms.txt](https://developers.ethos.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.ethos.network/api-documentation/api-v2/perps.md). # Perps ## GET /perps > List perps markets with pagination and sorting ```json {"openapi":"3.1.0","info":{"title":"Ethos API","version":"v2"},"tags":[{"name":"perps"}],"servers":[{"url":"https://api.ethos.network/api/v2"}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer"}},"schemas":{"error.BAD_REQUEST":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Invalid input data error (400)","description":"The error information"},"error.UNAUTHORIZED":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Authorization not provided error (401)","description":"The error information"},"error.FORBIDDEN":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Insufficient access error (403)","description":"The error information"},"error.NOT_FOUND":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Not found error (404)","description":"The error information"},"error.INTERNAL_SERVER_ERROR":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Internal server error error (500)","description":"The error information"}}},"paths":{"/perps":{"get":{"operationId":"perps-list","summary":"List perps markets with pagination and sorting","tags":["perps"],"parameters":[{"in":"query","name":"orderBy","schema":{"default":"volumeTotal","type":"string","enum":["createdAt","longOI","shortOI","volume24h","volumeTotal"]}},{"in":"query","name":"orderDirection","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"in":"query","name":"limit","schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"in":"query","name":"cursor","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"marketOnchainId":{"type":"number"},"subjectUserkey":{"anyOf":[{"type":"string"},{"type":"null"}]},"subject":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"profileId":{"anyOf":[{"type":"number"},{"type":"null"}]},"displayName":{"type":"string"},"username":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarUrl":{"type":"string","format":"uri"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"score":{"type":"number"},"status":{"type":"string","enum":["ACTIVE","INACTIVE","MERGED"]},"userkeys":{"type":"array","items":{"type":"string"}},"xpTotal":{"type":"number"},"xpStreakDays":{"type":"number"},"xpRemovedDueToAbuse":{"type":"boolean"},"influenceFactor":{"type":"number"},"influenceFactorPercentile":{"type":"number"},"humanVerificationStatus":{"anyOf":[{"type":"string","enum":["REQUESTED","VERIFIED","REVOKED","PENDING"]},{"type":"null"}]},"validatorNftCount":{"type":"number"},"links":{"type":"object","properties":{"profile":{"type":"string","format":"uri"},"scoreBreakdown":{"type":"string","format":"uri"}},"required":["profile","scoreBreakdown"],"additionalProperties":false},"stats":{"type":"object","properties":{"review":{"type":"object","properties":{"received":{"type":"object","properties":{"negative":{"type":"number"},"neutral":{"type":"number"},"positive":{"type":"number"}},"required":["negative","neutral","positive"],"additionalProperties":false}},"required":["received"],"additionalProperties":false},"vouch":{"type":"object","properties":{"given":{"type":"object","properties":{"amountWeiTotal":{"type":"integer","format":"int64"},"count":{"type":"number"}},"required":["amountWeiTotal","count"],"additionalProperties":false},"received":{"type":"object","properties":{"amountWeiTotal":{"type":"integer","format":"int64"},"count":{"type":"number"}},"required":["amountWeiTotal","count"],"additionalProperties":false}},"required":["given","received"],"additionalProperties":false,"description":"@deprecated Native-currency lifetime totals only. Use stats.vouchTotals (per-token). Removed after 2026-10-20."},"vouchTotals":{"minItems":1,"type":"array","items":{"type":"object","properties":{"balance":{"type":"object","properties":{"given":{"type":"integer","format":"int64"},"received":{"type":"integer","format":"int64"}},"required":["given","received"],"additionalProperties":false},"count":{"type":"object","properties":{"given":{"type":"integer","minimum":0,"maximum":9007199254740991},"received":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["given","received"],"additionalProperties":false},"token":{"type":"object","properties":{"address":{"anyOf":[{"type":"string","description":"Ethereum address (0x-prefixed, 20 bytes)"},{"type":"null"}]},"decimals":{"type":"integer","minimum":0,"maximum":9007199254740991},"id":{"type":"string","description":"Lowercase token identifier (e.g. `eth`)"}},"required":["address","decimals","id"],"additionalProperties":false}},"required":["balance","count","token"],"additionalProperties":false}}},"required":["review","vouch","vouchTotals"],"additionalProperties":false}},"required":["id","profileId","displayName","username","avatarUrl","description","score","status","userkeys","xpTotal","xpStreakDays","xpRemovedDueToAbuse","influenceFactor","influenceFactorPercentile","validatorNftCount","links","stats"],"additionalProperties":false},{"type":"null"}]},"pauseState":{"type":"string","enum":["active","reduce_only","paused"]},"markPrice":{"type":"integer","format":"int64"},"lastFundingRate":{"type":"integer","format":"int64"},"longOI":{"type":"integer","format":"int64"},"shortOI":{"type":"integer","format":"int64"},"volumeTotal":{"type":"integer","format":"int64"},"volume24h":{"type":"integer","format":"int64"},"createdAt":{"type":"string"}},"required":["id","marketOnchainId","subjectUserkey","subject","pauseState","markPrice","lastFundingRate","longOI","shortOI","volumeTotal","volume24h","createdAt"],"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["values","nextCursor"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}}}} ``` ## GET /perps/open-positions > List every open position a trader holds across perps markets ```json {"openapi":"3.1.0","info":{"title":"Ethos API","version":"v2"},"tags":[{"name":"perps"}],"servers":[{"url":"https://api.ethos.network/api/v2"}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer"}},"schemas":{"error.BAD_REQUEST":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Invalid input data error (400)","description":"The error information"},"error.UNAUTHORIZED":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Authorization not provided error (401)","description":"The error information"},"error.FORBIDDEN":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Insufficient access error (403)","description":"The error information"},"error.NOT_FOUND":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Not found error (404)","description":"The error information"},"error.INTERNAL_SERVER_ERROR":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Internal server error error (500)","description":"The error information"}}},"paths":{"/perps/open-positions":{"get":{"operationId":"perps-openPositions","summary":"List every open position a trader holds across perps markets","tags":["perps"],"parameters":[{"in":"query","name":"traderAddress","schema":{"type":"string","description":"Ethereum address (0x-prefixed, 20 bytes)"},"required":true,"description":"Ethereum address (0x-prefixed, 20 bytes)"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"values":{"type":"array","items":{"type":"object","properties":{"market":{"type":"object","properties":{"id":{"type":"number"},"marketOnchainId":{"type":"number"},"subjectUserkey":{"anyOf":[{"type":"string"},{"type":"null"}]},"subject":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"profileId":{"anyOf":[{"type":"number"},{"type":"null"}]},"displayName":{"type":"string"},"username":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarUrl":{"type":"string","format":"uri"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"score":{"type":"number"},"status":{"type":"string","enum":["ACTIVE","INACTIVE","MERGED"]},"userkeys":{"type":"array","items":{"type":"string"}},"xpTotal":{"type":"number"},"xpStreakDays":{"type":"number"},"xpRemovedDueToAbuse":{"type":"boolean"},"influenceFactor":{"type":"number"},"influenceFactorPercentile":{"type":"number"},"humanVerificationStatus":{"anyOf":[{"type":"string","enum":["REQUESTED","VERIFIED","REVOKED","PENDING"]},{"type":"null"}]},"validatorNftCount":{"type":"number"},"links":{"type":"object","properties":{"profile":{"type":"string","format":"uri"},"scoreBreakdown":{"type":"string","format":"uri"}},"required":["profile","scoreBreakdown"],"additionalProperties":false},"stats":{"type":"object","properties":{"review":{"type":"object","properties":{"received":{"type":"object","properties":{"negative":{"type":"number"},"neutral":{"type":"number"},"positive":{"type":"number"}},"required":["negative","neutral","positive"],"additionalProperties":false}},"required":["received"],"additionalProperties":false},"vouch":{"type":"object","properties":{"given":{"type":"object","properties":{"amountWeiTotal":{"type":"integer","format":"int64"},"count":{"type":"number"}},"required":["amountWeiTotal","count"],"additionalProperties":false},"received":{"type":"object","properties":{"amountWeiTotal":{"type":"integer","format":"int64"},"count":{"type":"number"}},"required":["amountWeiTotal","count"],"additionalProperties":false}},"required":["given","received"],"additionalProperties":false,"description":"@deprecated Native-currency lifetime totals only. Use stats.vouchTotals (per-token). Removed after 2026-10-20."},"vouchTotals":{"minItems":1,"type":"array","items":{"type":"object","properties":{"balance":{"type":"object","properties":{"given":{"type":"integer","format":"int64"},"received":{"type":"integer","format":"int64"}},"required":["given","received"],"additionalProperties":false},"count":{"type":"object","properties":{"given":{"type":"integer","minimum":0,"maximum":9007199254740991},"received":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["given","received"],"additionalProperties":false},"token":{"type":"object","properties":{"address":{"anyOf":[{"type":"string","description":"Ethereum address (0x-prefixed, 20 bytes)"},{"type":"null"}]},"decimals":{"type":"integer","minimum":0,"maximum":9007199254740991},"id":{"type":"string","description":"Lowercase token identifier (e.g. `eth`)"}},"required":["address","decimals","id"],"additionalProperties":false}},"required":["balance","count","token"],"additionalProperties":false}}},"required":["review","vouch","vouchTotals"],"additionalProperties":false}},"required":["id","profileId","displayName","username","avatarUrl","description","score","status","userkeys","xpTotal","xpStreakDays","xpRemovedDueToAbuse","influenceFactor","influenceFactorPercentile","validatorNftCount","links","stats"],"additionalProperties":false},{"type":"null"}]},"pauseState":{"type":"string","enum":["active","reduce_only","paused"]},"markPrice":{"type":"integer","format":"int64"},"lastFundingRate":{"type":"integer","format":"int64"},"longOI":{"type":"integer","format":"int64"},"shortOI":{"type":"integer","format":"int64"},"volumeTotal":{"type":"integer","format":"int64"},"volume24h":{"type":"integer","format":"int64"},"createdAt":{"type":"string"}},"required":["id","marketOnchainId","subjectUserkey","subject","pauseState","markPrice","lastFundingRate","longOI","shortOI","volumeTotal","volume24h","createdAt"],"additionalProperties":false},"size":{"type":"integer","format":"int64"},"collateral":{"type":"integer","format":"int64"},"pnl":{"anyOf":[{"type":"integer","format":"int64"},{"type":"null"}]},"pnlPercent":{"anyOf":[{"type":"number"},{"type":"null"}]},"entryLeverage":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["market","size","collateral","pnl","pnlPercent","entryLeverage"],"additionalProperties":false}}},"required":["values"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}}}} ``` ## GET /perps/liquidations > List perps liquidations, optionally filtered by market or trader ```json {"openapi":"3.1.0","info":{"title":"Ethos API","version":"v2"},"tags":[{"name":"perps"}],"servers":[{"url":"https://api.ethos.network/api/v2"}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer"}},"schemas":{"error.BAD_REQUEST":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Invalid input data error (400)","description":"The error information"},"error.UNAUTHORIZED":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Authorization not provided error (401)","description":"The error information"},"error.FORBIDDEN":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Insufficient access error (403)","description":"The error information"},"error.NOT_FOUND":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Not found error (404)","description":"The error information"},"error.INTERNAL_SERVER_ERROR":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Internal server error error (500)","description":"The error information"}}},"paths":{"/perps/liquidations":{"get":{"operationId":"perps-liquidations","summary":"List perps liquidations, optionally filtered by market or trader","tags":["perps"],"parameters":[{"in":"query","name":"marketOnchainId","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"in":"query","name":"traderAddress","schema":{"type":"string","description":"Ethereum address (0x-prefixed, 20 bytes)"}},{"in":"query","name":"limit","schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"in":"query","name":"cursor","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"marketId":{"type":"number"},"marketOnchainId":{"type":"number"},"traderAddress":{"type":"string","description":"Ethereum address (0x-prefixed, 20 bytes)"},"trader":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"profileId":{"anyOf":[{"type":"number"},{"type":"null"}]},"displayName":{"type":"string"},"username":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarUrl":{"type":"string","format":"uri"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"score":{"type":"number"},"status":{"type":"string","enum":["ACTIVE","INACTIVE","MERGED"]},"userkeys":{"type":"array","items":{"type":"string"}},"xpTotal":{"type":"number"},"xpStreakDays":{"type":"number"},"xpRemovedDueToAbuse":{"type":"boolean"},"influenceFactor":{"type":"number"},"influenceFactorPercentile":{"type":"number"},"humanVerificationStatus":{"anyOf":[{"type":"string","enum":["REQUESTED","VERIFIED","REVOKED","PENDING"]},{"type":"null"}]},"validatorNftCount":{"type":"number"},"links":{"type":"object","properties":{"profile":{"type":"string","format":"uri"},"scoreBreakdown":{"type":"string","format":"uri"}},"required":["profile","scoreBreakdown"],"additionalProperties":false},"stats":{"type":"object","properties":{"review":{"type":"object","properties":{"received":{"type":"object","properties":{"negative":{"type":"number"},"neutral":{"type":"number"},"positive":{"type":"number"}},"required":["negative","neutral","positive"],"additionalProperties":false}},"required":["received"],"additionalProperties":false},"vouch":{"type":"object","properties":{"given":{"type":"object","properties":{"amountWeiTotal":{"type":"integer","format":"int64"},"count":{"type":"number"}},"required":["amountWeiTotal","count"],"additionalProperties":false},"received":{"type":"object","properties":{"amountWeiTotal":{"type":"integer","format":"int64"},"count":{"type":"number"}},"required":["amountWeiTotal","count"],"additionalProperties":false}},"required":["given","received"],"additionalProperties":false,"description":"@deprecated Native-currency lifetime totals only. Use stats.vouchTotals (per-token). Removed after 2026-10-20."},"vouchTotals":{"minItems":1,"type":"array","items":{"type":"object","properties":{"balance":{"type":"object","properties":{"given":{"type":"integer","format":"int64"},"received":{"type":"integer","format":"int64"}},"required":["given","received"],"additionalProperties":false},"count":{"type":"object","properties":{"given":{"type":"integer","minimum":0,"maximum":9007199254740991},"received":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["given","received"],"additionalProperties":false},"token":{"type":"object","properties":{"address":{"anyOf":[{"type":"string","description":"Ethereum address (0x-prefixed, 20 bytes)"},{"type":"null"}]},"decimals":{"type":"integer","minimum":0,"maximum":9007199254740991},"id":{"type":"string","description":"Lowercase token identifier (e.g. `eth`)"}},"required":["address","decimals","id"],"additionalProperties":false}},"required":["balance","count","token"],"additionalProperties":false}}},"required":["review","vouch","vouchTotals"],"additionalProperties":false}},"required":["id","profileId","displayName","username","avatarUrl","description","score","status","userkeys","xpTotal","xpStreakDays","xpRemovedDueToAbuse","influenceFactor","influenceFactorPercentile","validatorNftCount","links","stats"],"additionalProperties":false},{"type":"null"}]},"keeper":{"type":"string","description":"Ethereum address (0x-prefixed, 20 bytes)"},"notional":{"type":"integer","format":"int64"},"bountyPaid":{"type":"integer","format":"int64"},"realizedPnl":{"type":"integer","format":"int64"},"badDebt":{"type":"integer","format":"int64"},"createdAt":{"type":"string"}},"required":["id","marketId","marketOnchainId","traderAddress","trader","keeper","notional","bountyPaid","realizedPnl","badDebt","createdAt"],"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["values","nextCursor"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}}}} ``` ## GET /perps/protocol-stats > Get protocol-wide perps stats (insurance fund, total open interest) ```json {"openapi":"3.1.0","info":{"title":"Ethos API","version":"v2"},"tags":[{"name":"perps"}],"servers":[{"url":"https://api.ethos.network/api/v2"}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer"}},"schemas":{"error.UNAUTHORIZED":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Authorization not provided error (401)","description":"The error information"},"error.FORBIDDEN":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Insufficient access error (403)","description":"The error information"},"error.INTERNAL_SERVER_ERROR":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Internal server error error (500)","description":"The error information"}}},"paths":{"/perps/protocol-stats":{"get":{"operationId":"perps-protocolStats","summary":"Get protocol-wide perps stats (insurance fund, total open interest)","tags":["perps"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"insuranceFund":{"type":"integer","format":"int64"},"totalOpenInterest":{"type":"integer","format":"int64"}},"required":["insuranceFund","totalOpenInterest"],"additionalProperties":false}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}}}} ``` ## GET /perps/{marketOnchainId} > Get a single perps market by on-chain ID ```json {"openapi":"3.1.0","info":{"title":"Ethos API","version":"v2"},"tags":[{"name":"perps"}],"servers":[{"url":"https://api.ethos.network/api/v2"}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer"}},"schemas":{"error.BAD_REQUEST":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Invalid input data error (400)","description":"The error information"},"error.UNAUTHORIZED":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Authorization not provided error (401)","description":"The error information"},"error.FORBIDDEN":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Insufficient access error (403)","description":"The error information"},"error.NOT_FOUND":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Not found error (404)","description":"The error information"},"error.INTERNAL_SERVER_ERROR":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Internal server error error (500)","description":"The error information"}}},"paths":{"/perps/{marketOnchainId}":{"get":{"operationId":"perps-get","summary":"Get a single perps market by on-chain ID","tags":["perps"],"parameters":[{"in":"path","name":"marketOnchainId","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"number"},"marketOnchainId":{"type":"number"},"subjectUserkey":{"anyOf":[{"type":"string"},{"type":"null"}]},"subject":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"profileId":{"anyOf":[{"type":"number"},{"type":"null"}]},"displayName":{"type":"string"},"username":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarUrl":{"type":"string","format":"uri"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"score":{"type":"number"},"status":{"type":"string","enum":["ACTIVE","INACTIVE","MERGED"]},"userkeys":{"type":"array","items":{"type":"string"}},"xpTotal":{"type":"number"},"xpStreakDays":{"type":"number"},"xpRemovedDueToAbuse":{"type":"boolean"},"influenceFactor":{"type":"number"},"influenceFactorPercentile":{"type":"number"},"humanVerificationStatus":{"anyOf":[{"type":"string","enum":["REQUESTED","VERIFIED","REVOKED","PENDING"]},{"type":"null"}]},"validatorNftCount":{"type":"number"},"links":{"type":"object","properties":{"profile":{"type":"string","format":"uri"},"scoreBreakdown":{"type":"string","format":"uri"}},"required":["profile","scoreBreakdown"],"additionalProperties":false},"stats":{"type":"object","properties":{"review":{"type":"object","properties":{"received":{"type":"object","properties":{"negative":{"type":"number"},"neutral":{"type":"number"},"positive":{"type":"number"}},"required":["negative","neutral","positive"],"additionalProperties":false}},"required":["received"],"additionalProperties":false},"vouch":{"type":"object","properties":{"given":{"type":"object","properties":{"amountWeiTotal":{"type":"integer","format":"int64"},"count":{"type":"number"}},"required":["amountWeiTotal","count"],"additionalProperties":false},"received":{"type":"object","properties":{"amountWeiTotal":{"type":"integer","format":"int64"},"count":{"type":"number"}},"required":["amountWeiTotal","count"],"additionalProperties":false}},"required":["given","received"],"additionalProperties":false,"description":"@deprecated Native-currency lifetime totals only. Use stats.vouchTotals (per-token). Removed after 2026-10-20."},"vouchTotals":{"minItems":1,"type":"array","items":{"type":"object","properties":{"balance":{"type":"object","properties":{"given":{"type":"integer","format":"int64"},"received":{"type":"integer","format":"int64"}},"required":["given","received"],"additionalProperties":false},"count":{"type":"object","properties":{"given":{"type":"integer","minimum":0,"maximum":9007199254740991},"received":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["given","received"],"additionalProperties":false},"token":{"type":"object","properties":{"address":{"anyOf":[{"type":"string","description":"Ethereum address (0x-prefixed, 20 bytes)"},{"type":"null"}]},"decimals":{"type":"integer","minimum":0,"maximum":9007199254740991},"id":{"type":"string","description":"Lowercase token identifier (e.g. `eth`)"}},"required":["address","decimals","id"],"additionalProperties":false}},"required":["balance","count","token"],"additionalProperties":false}}},"required":["review","vouch","vouchTotals"],"additionalProperties":false}},"required":["id","profileId","displayName","username","avatarUrl","description","score","status","userkeys","xpTotal","xpStreakDays","xpRemovedDueToAbuse","influenceFactor","influenceFactorPercentile","validatorNftCount","links","stats"],"additionalProperties":false},{"type":"null"}]},"pauseState":{"type":"string","enum":["active","reduce_only","paused"]},"markPrice":{"type":"integer","format":"int64"},"lastFundingRate":{"type":"integer","format":"int64"},"longOI":{"type":"integer","format":"int64"},"shortOI":{"type":"integer","format":"int64"},"volumeTotal":{"type":"integer","format":"int64"},"volume24h":{"type":"integer","format":"int64"},"createdAt":{"type":"string"},"initialMarginRatio":{"type":"integer","format":"int64"},"maintenanceMarginRatio":{"type":"integer","format":"int64"},"minMargin":{"type":"integer","format":"int64"},"maxLeverage":{"type":"integer","format":"int64"},"perTxNotionalCap":{"type":"integer","format":"int64"},"perBlockNotionalCap":{"type":"integer","format":"int64"},"skewScale":{"type":"integer","format":"int64"},"maxFundingVelocityPerDay":{"type":"integer","format":"int64"},"liquidationBountyBps":{"type":"number"},"liquidationFeeBps":{"type":"number"},"makerFeeBps":{"type":"number"},"takerFeeBps":{"type":"number"},"skew":{"type":"integer","format":"int64"},"totalCollateral":{"type":"integer","format":"int64"},"fundingValue":{"type":"integer","format":"int64"},"lastFundingTime":{"anyOf":[{"type":"string"},{"type":"null"}]},"markUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","marketOnchainId","subjectUserkey","subject","pauseState","markPrice","lastFundingRate","longOI","shortOI","volumeTotal","volume24h","createdAt","initialMarginRatio","maintenanceMarginRatio","minMargin","maxLeverage","perTxNotionalCap","perBlockNotionalCap","skewScale","maxFundingVelocityPerDay","liquidationBountyBps","liquidationFeeBps","makerFeeBps","takerFeeBps","skew","totalCollateral","fundingValue","lastFundingTime","markUpdatedAt"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}}}} ``` ## GET /perps/{marketOnchainId}/position > Get a trader’s position in a perps market ```json {"openapi":"3.1.0","info":{"title":"Ethos API","version":"v2"},"tags":[{"name":"perps"}],"servers":[{"url":"https://api.ethos.network/api/v2"}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer"}},"schemas":{"error.BAD_REQUEST":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Invalid input data error (400)","description":"The error information"},"error.UNAUTHORIZED":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Authorization not provided error (401)","description":"The error information"},"error.FORBIDDEN":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Insufficient access error (403)","description":"The error information"},"error.NOT_FOUND":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Not found error (404)","description":"The error information"},"error.INTERNAL_SERVER_ERROR":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Internal server error error (500)","description":"The error information"}}},"paths":{"/perps/{marketOnchainId}/position":{"get":{"operationId":"perps-position","summary":"Get a trader’s position in a perps market","tags":["perps"],"parameters":[{"in":"path","name":"marketOnchainId","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"required":true},{"in":"query","name":"traderAddress","schema":{"type":"string","description":"Ethereum address (0x-prefixed, 20 bytes)"},"required":true,"description":"Ethereum address (0x-prefixed, 20 bytes)"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"marketId":{"type":"number"},"marketOnchainId":{"type":"number"},"traderAddress":{"type":"string","description":"Ethereum address (0x-prefixed, 20 bytes)"},"size":{"type":"integer","format":"int64"},"collateral":{"type":"integer","format":"int64"},"entrySignal":{"type":"integer","format":"int64"},"fundingSnapshot":{"type":"integer","format":"int64"},"openedAt":{"type":"string"},"lastUpdatedAt":{"type":"string"},"isClosed":{"type":"boolean"},"closedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"isFlagged":{"type":"boolean"},"flaggedKeeper":{"anyOf":[{"type":"string","description":"Ethereum address (0x-prefixed, 20 bytes)"},{"type":"null"}]},"flaggedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lifetimeRealizedPnl":{"type":"integer","format":"int64"},"pnl":{"anyOf":[{"type":"integer","format":"int64"},{"type":"null"}]},"pnlPercent":{"anyOf":[{"type":"number"},{"type":"null"}]},"entryLeverage":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["marketId","marketOnchainId","traderAddress","size","collateral","entrySignal","fundingSnapshot","openedAt","lastUpdatedAt","isClosed","closedAt","isFlagged","flaggedKeeper","flaggedAt","lifetimeRealizedPnl","pnl","pnlPercent","entryLeverage"],"additionalProperties":false},{"type":"null"}]}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}}}} ``` ## GET /perps/{marketOnchainId}/trade-history > Get trade history for a perps market ```json {"openapi":"3.1.0","info":{"title":"Ethos API","version":"v2"},"tags":[{"name":"perps"}],"servers":[{"url":"https://api.ethos.network/api/v2"}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer"}},"schemas":{"error.BAD_REQUEST":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Invalid input data error (400)","description":"The error information"},"error.UNAUTHORIZED":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Authorization not provided error (401)","description":"The error information"},"error.FORBIDDEN":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Insufficient access error (403)","description":"The error information"},"error.NOT_FOUND":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Not found error (404)","description":"The error information"},"error.INTERNAL_SERVER_ERROR":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Internal server error error (500)","description":"The error information"}}},"paths":{"/perps/{marketOnchainId}/trade-history":{"get":{"operationId":"perps-tradeHistory","summary":"Get trade history for a perps market","tags":["perps"],"parameters":[{"in":"path","name":"marketOnchainId","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"required":true},{"in":"query","name":"traderAddress","schema":{"type":"string","description":"Ethereum address (0x-prefixed, 20 bytes)"}},{"in":"query","name":"limit","schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"in":"query","name":"cursor","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"type":{"type":"string","enum":["OPEN","CLOSE","LIQUIDATION","FORCE_CLOSE"]},"traderAddress":{"type":"string","description":"Ethereum address (0x-prefixed, 20 bytes)"},"trader":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"profileId":{"anyOf":[{"type":"number"},{"type":"null"}]},"displayName":{"type":"string"},"username":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarUrl":{"type":"string","format":"uri"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"score":{"type":"number"},"status":{"type":"string","enum":["ACTIVE","INACTIVE","MERGED"]},"userkeys":{"type":"array","items":{"type":"string"}},"xpTotal":{"type":"number"},"xpStreakDays":{"type":"number"},"xpRemovedDueToAbuse":{"type":"boolean"},"influenceFactor":{"type":"number"},"influenceFactorPercentile":{"type":"number"},"humanVerificationStatus":{"anyOf":[{"type":"string","enum":["REQUESTED","VERIFIED","REVOKED","PENDING"]},{"type":"null"}]},"validatorNftCount":{"type":"number"},"links":{"type":"object","properties":{"profile":{"type":"string","format":"uri"},"scoreBreakdown":{"type":"string","format":"uri"}},"required":["profile","scoreBreakdown"],"additionalProperties":false},"stats":{"type":"object","properties":{"review":{"type":"object","properties":{"received":{"type":"object","properties":{"negative":{"type":"number"},"neutral":{"type":"number"},"positive":{"type":"number"}},"required":["negative","neutral","positive"],"additionalProperties":false}},"required":["received"],"additionalProperties":false},"vouch":{"type":"object","properties":{"given":{"type":"object","properties":{"amountWeiTotal":{"type":"integer","format":"int64"},"count":{"type":"number"}},"required":["amountWeiTotal","count"],"additionalProperties":false},"received":{"type":"object","properties":{"amountWeiTotal":{"type":"integer","format":"int64"},"count":{"type":"number"}},"required":["amountWeiTotal","count"],"additionalProperties":false}},"required":["given","received"],"additionalProperties":false,"description":"@deprecated Native-currency lifetime totals only. Use stats.vouchTotals (per-token). Removed after 2026-10-20."},"vouchTotals":{"minItems":1,"type":"array","items":{"type":"object","properties":{"balance":{"type":"object","properties":{"given":{"type":"integer","format":"int64"},"received":{"type":"integer","format":"int64"}},"required":["given","received"],"additionalProperties":false},"count":{"type":"object","properties":{"given":{"type":"integer","minimum":0,"maximum":9007199254740991},"received":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["given","received"],"additionalProperties":false},"token":{"type":"object","properties":{"address":{"anyOf":[{"type":"string","description":"Ethereum address (0x-prefixed, 20 bytes)"},{"type":"null"}]},"decimals":{"type":"integer","minimum":0,"maximum":9007199254740991},"id":{"type":"string","description":"Lowercase token identifier (e.g. `eth`)"}},"required":["address","decimals","id"],"additionalProperties":false}},"required":["balance","count","token"],"additionalProperties":false}}},"required":["review","vouch","vouchTotals"],"additionalProperties":false}},"required":["id","profileId","displayName","username","avatarUrl","description","score","status","userkeys","xpTotal","xpStreakDays","xpRemovedDueToAbuse","influenceFactor","influenceFactorPercentile","validatorNftCount","links","stats"],"additionalProperties":false},{"type":"null"}]},"sizeDelta":{"type":"integer","format":"int64"},"collateralAmount":{"type":"integer","format":"int64"},"realizedPnl":{"anyOf":[{"type":"integer","format":"int64"},{"type":"null"}]},"signal":{"type":"integer","format":"int64"},"newSize":{"type":"integer","format":"int64"},"newCollateral":{"type":"integer","format":"int64"},"createdAt":{"type":"string"}},"required":["id","type","traderAddress","trader","sizeDelta","collateralAmount","realizedPnl","signal","newSize","newCollateral","createdAt"],"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["values","nextCursor"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}}}} ``` ## GET /perps/{marketOnchainId}/funding-history > Get funding history for a perps market ```json {"openapi":"3.1.0","info":{"title":"Ethos API","version":"v2"},"tags":[{"name":"perps"}],"servers":[{"url":"https://api.ethos.network/api/v2"}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer"}},"schemas":{"error.BAD_REQUEST":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Invalid input data error (400)","description":"The error information"},"error.UNAUTHORIZED":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Authorization not provided error (401)","description":"The error information"},"error.FORBIDDEN":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Insufficient access error (403)","description":"The error information"},"error.NOT_FOUND":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Not found error (404)","description":"The error information"},"error.INTERNAL_SERVER_ERROR":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Internal server error error (500)","description":"The error information"}}},"paths":{"/perps/{marketOnchainId}/funding-history":{"get":{"operationId":"perps-fundingHistory","summary":"Get funding history for a perps market","tags":["perps"],"parameters":[{"in":"path","name":"marketOnchainId","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"required":true},{"in":"query","name":"limit","schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"in":"query","name":"cursor","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"fundingValue":{"type":"integer","format":"int64"},"fundingRate":{"type":"integer","format":"int64"},"skew":{"type":"integer","format":"int64"},"createdAt":{"type":"string"}},"required":["id","fundingValue","fundingRate","skew","createdAt"],"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["values","nextCursor"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}}}} ``` ## GET /perps/{marketOnchainId}/mark-history > Get bucketed mark and funding-rate history for a perps market ```json {"openapi":"3.1.0","info":{"title":"Ethos API","version":"v2"},"tags":[{"name":"perps"}],"servers":[{"url":"https://api.ethos.network/api/v2"}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer"}},"schemas":{"error.BAD_REQUEST":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Invalid input data error (400)","description":"The error information"},"error.UNAUTHORIZED":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Authorization not provided error (401)","description":"The error information"},"error.FORBIDDEN":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Insufficient access error (403)","description":"The error information"},"error.NOT_FOUND":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Not found error (404)","description":"The error information"},"error.INTERNAL_SERVER_ERROR":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Internal server error error (500)","description":"The error information"}}},"paths":{"/perps/{marketOnchainId}/mark-history":{"get":{"operationId":"perps-markHistory","summary":"Get bucketed mark and funding-rate history for a perps market","tags":["perps"],"parameters":[{"in":"path","name":"marketOnchainId","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"required":true},{"in":"query","name":"duration","schema":{"default":"7d","type":"string","enum":["1h","1d","7d","30d","90d","6m","1y","all"]}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"duration":{"type":"string","enum":["1h","1d","7d","30d","90d","6m","1y","all"]},"values":{"type":"array","items":{"type":"object","properties":{"timeBucket":{"type":"string"},"markPrice":{"type":"integer","format":"int64"},"fundingRate":{"anyOf":[{"type":"integer","format":"int64"},{"type":"null"}]}},"required":["timeBucket","markPrice","fundingRate"],"additionalProperties":false}}},"required":["duration","values"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}}}} ``` ## GET /perps/{marketOnchainId}/top-traders > List top traders for a perps market by lifetime realized PnL ```json {"openapi":"3.1.0","info":{"title":"Ethos API","version":"v2"},"tags":[{"name":"perps"}],"servers":[{"url":"https://api.ethos.network/api/v2"}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer"}},"schemas":{"error.BAD_REQUEST":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Invalid input data error (400)","description":"The error information"},"error.UNAUTHORIZED":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Authorization not provided error (401)","description":"The error information"},"error.FORBIDDEN":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Insufficient access error (403)","description":"The error information"},"error.NOT_FOUND":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Not found error (404)","description":"The error information"},"error.INTERNAL_SERVER_ERROR":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Internal server error error (500)","description":"The error information"}}},"paths":{"/perps/{marketOnchainId}/top-traders":{"get":{"operationId":"perps-topTraders","summary":"List top traders for a perps market by lifetime realized PnL","tags":["perps"],"parameters":[{"in":"path","name":"marketOnchainId","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"values":{"type":"array","items":{"type":"object","properties":{"traderAddress":{"type":"string","description":"Ethereum address (0x-prefixed, 20 bytes)"},"trader":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"profileId":{"anyOf":[{"type":"number"},{"type":"null"}]},"displayName":{"type":"string"},"username":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarUrl":{"type":"string","format":"uri"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"score":{"type":"number"},"status":{"type":"string","enum":["ACTIVE","INACTIVE","MERGED"]},"userkeys":{"type":"array","items":{"type":"string"}},"xpTotal":{"type":"number"},"xpStreakDays":{"type":"number"},"xpRemovedDueToAbuse":{"type":"boolean"},"influenceFactor":{"type":"number"},"influenceFactorPercentile":{"type":"number"},"humanVerificationStatus":{"anyOf":[{"type":"string","enum":["REQUESTED","VERIFIED","REVOKED","PENDING"]},{"type":"null"}]},"validatorNftCount":{"type":"number"},"links":{"type":"object","properties":{"profile":{"type":"string","format":"uri"},"scoreBreakdown":{"type":"string","format":"uri"}},"required":["profile","scoreBreakdown"],"additionalProperties":false},"stats":{"type":"object","properties":{"review":{"type":"object","properties":{"received":{"type":"object","properties":{"negative":{"type":"number"},"neutral":{"type":"number"},"positive":{"type":"number"}},"required":["negative","neutral","positive"],"additionalProperties":false}},"required":["received"],"additionalProperties":false},"vouch":{"type":"object","properties":{"given":{"type":"object","properties":{"amountWeiTotal":{"type":"integer","format":"int64"},"count":{"type":"number"}},"required":["amountWeiTotal","count"],"additionalProperties":false},"received":{"type":"object","properties":{"amountWeiTotal":{"type":"integer","format":"int64"},"count":{"type":"number"}},"required":["amountWeiTotal","count"],"additionalProperties":false}},"required":["given","received"],"additionalProperties":false,"description":"@deprecated Native-currency lifetime totals only. Use stats.vouchTotals (per-token). Removed after 2026-10-20."},"vouchTotals":{"minItems":1,"type":"array","items":{"type":"object","properties":{"balance":{"type":"object","properties":{"given":{"type":"integer","format":"int64"},"received":{"type":"integer","format":"int64"}},"required":["given","received"],"additionalProperties":false},"count":{"type":"object","properties":{"given":{"type":"integer","minimum":0,"maximum":9007199254740991},"received":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["given","received"],"additionalProperties":false},"token":{"type":"object","properties":{"address":{"anyOf":[{"type":"string","description":"Ethereum address (0x-prefixed, 20 bytes)"},{"type":"null"}]},"decimals":{"type":"integer","minimum":0,"maximum":9007199254740991},"id":{"type":"string","description":"Lowercase token identifier (e.g. `eth`)"}},"required":["address","decimals","id"],"additionalProperties":false}},"required":["balance","count","token"],"additionalProperties":false}}},"required":["review","vouch","vouchTotals"],"additionalProperties":false}},"required":["id","profileId","displayName","username","avatarUrl","description","score","status","userkeys","xpTotal","xpStreakDays","xpRemovedDueToAbuse","influenceFactor","influenceFactorPercentile","validatorNftCount","links","stats"],"additionalProperties":false},{"type":"null"}]},"lifetimeRealizedPnl":{"type":"integer","format":"int64"},"hasOpenPosition":{"type":"boolean"}},"required":["traderAddress","trader","lifetimeRealizedPnl","hasOpenPosition"],"additionalProperties":false}}},"required":["values"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}}}} ``` ## GET /perps/{marketOnchainId}/simulate-open > Quote opening or growing a perps position ```json {"openapi":"3.1.0","info":{"title":"Ethos API","version":"v2"},"tags":[{"name":"perps"}],"servers":[{"url":"https://api.ethos.network/api/v2"}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer"}},"schemas":{"error.BAD_REQUEST":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Invalid input data error (400)","description":"The error information"},"error.UNAUTHORIZED":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Authorization not provided error (401)","description":"The error information"},"error.FORBIDDEN":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Insufficient access error (403)","description":"The error information"},"error.NOT_FOUND":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Not found error (404)","description":"The error information"},"error.INTERNAL_SERVER_ERROR":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Internal server error error (500)","description":"The error information"}}},"paths":{"/perps/{marketOnchainId}/simulate-open":{"get":{"operationId":"perps-simulateOpen","summary":"Quote opening or growing a perps position","tags":["perps"],"parameters":[{"in":"path","name":"marketOnchainId","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"required":true},{"in":"query","name":"collateralDelta","schema":{"type":"string"},"required":true},{"in":"query","name":"leverage","schema":{"type":"string","enum":["1","2","3","5","10"]},"required":true},{"in":"query","name":"side","schema":{"type":"string","enum":["long","short"]},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","const":"ok"},"entrySignal":{"type":"integer","format":"int64"},"notional":{"type":"integer","format":"int64"},"required":{"type":"integer","format":"int64"},"sizeDelta":{"type":"integer","format":"int64"},"perTxNotionalCap":{"type":"integer","format":"int64"},"notionalCapOk":{"type":"boolean"},"worstCaseUpside":{"type":"integer","format":"int64"},"leveragedUpsideOk":{"type":"boolean"}},"required":["status","entrySignal","notional","required","sizeDelta","perTxNotionalCap","notionalCapOk","worstCaseUpside","leveragedUpsideOk"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"unavailable"},"reason":{"type":"string","enum":["belowMinMargin","markUnavailable","sizeTooSmall"]}},"required":["status","reason"],"additionalProperties":false}],"type":"object"}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}}}} ``` ## GET /perps/{marketOnchainId}/simulate-close > Quote closing or reducing a perps position ```json {"openapi":"3.1.0","info":{"title":"Ethos API","version":"v2"},"tags":[{"name":"perps"}],"servers":[{"url":"https://api.ethos.network/api/v2"}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer"}},"schemas":{"error.BAD_REQUEST":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Invalid input data error (400)","description":"The error information"},"error.UNAUTHORIZED":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Authorization not provided error (401)","description":"The error information"},"error.FORBIDDEN":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Insufficient access error (403)","description":"The error information"},"error.NOT_FOUND":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Not found error (404)","description":"The error information"},"error.INTERNAL_SERVER_ERROR":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Internal server error error (500)","description":"The error information"}}},"paths":{"/perps/{marketOnchainId}/simulate-close":{"get":{"operationId":"perps-simulateClose","summary":"Quote closing or reducing a perps position","tags":["perps"],"parameters":[{"in":"path","name":"marketOnchainId","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"required":true},{"in":"query","name":"trader","schema":{"type":"string","description":"Ethereum address (0x-prefixed, 20 bytes)"},"required":true,"description":"Ethereum address (0x-prefixed, 20 bytes)"},{"in":"query","name":"sizeDelta","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"closeSignal":{"type":"integer","format":"int64"},"collateralReturned":{"type":"integer","format":"int64"},"realizedPnl":{"type":"integer","format":"int64"}},"required":["closeSignal","collateralReturned","realizedPnl"],"additionalProperties":false},{"type":"null"}]}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}}}} ``` ## GET /perps/{marketOnchainId}/quotes > Get margin ratio, free collateral, liquidation signal, and funding rate ```json {"openapi":"3.1.0","info":{"title":"Ethos API","version":"v2"},"tags":[{"name":"perps"}],"servers":[{"url":"https://api.ethos.network/api/v2"}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer"}},"schemas":{"error.BAD_REQUEST":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Invalid input data error (400)","description":"The error information"},"error.UNAUTHORIZED":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Authorization not provided error (401)","description":"The error information"},"error.FORBIDDEN":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Insufficient access error (403)","description":"The error information"},"error.NOT_FOUND":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Not found error (404)","description":"The error information"},"error.INTERNAL_SERVER_ERROR":{"type":"object","properties":{"message":{"type":"string","description":"The error message"},"code":{"type":"string","description":"The error code"},"issues":{"description":"An array of issues that were responsible for the error","type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","code"],"additionalProperties":false,"title":"Internal server error error (500)","description":"The error information"}}},"paths":{"/perps/{marketOnchainId}/quotes":{"get":{"operationId":"perps-quotes","summary":"Get margin ratio, free collateral, liquidation signal, and funding rate","tags":["perps"],"parameters":[{"in":"path","name":"marketOnchainId","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"required":true},{"in":"query","name":"trader","schema":{"type":"string","description":"Ethereum address (0x-prefixed, 20 bytes)"},"required":true,"description":"Ethereum address (0x-prefixed, 20 bytes)"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"marginRatio":{"type":"integer","format":"int64"},"freeCollateral":{"type":"integer","format":"int64"},"removableCollateral":{"type":"integer","format":"int64"},"liquidationSignal":{"type":"integer","format":"int64"},"fundingRate":{"type":"integer","format":"int64"}},"required":["marginRatio","freeCollateral","removableCollateral","liquidationSignal","fundingRate"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}}}} ```