Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Perps

List perps markets with pagination and sorting

get
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
orderBystring · enumOptionalDefault: volumeTotalPossible values:
orderDirectionstring · enumOptionalDefault: descPossible values:
limitinteger · min: 1 · max: 100OptionalDefault: 50
cursorinteger · max: 9007199254740991Optional
Responses
200

Successful response

application/json
nextCursornumber · nullableRequired
get/perps
GET /api/v2/perps HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "values": [
    {
      "id": 1,
      "marketOnchainId": 1,
      "subjectUserkey": "text",
      "subject": {
        "id": 1,
        "profileId": 1,
        "displayName": "text",
        "username": "text",
        "avatarUrl": "https://example.com",
        "description": "text",
        "score": 1,
        "status": "ACTIVE",
        "userkeys": [
          "text"
        ],
        "xpTotal": 1,
        "xpStreakDays": 1,
        "xpRemovedDueToAbuse": true,
        "influenceFactor": 1,
        "influenceFactorPercentile": 1,
        "humanVerificationStatus": "REQUESTED",
        "validatorNftCount": 1,
        "links": {
          "profile": "https://example.com",
          "scoreBreakdown": "https://example.com"
        },
        "stats": {
          "review": {
            "received": {
              "negative": 1,
              "neutral": 1,
              "positive": 1
            }
          },
          "vouch": {
            "given": {
              "amountWeiTotal": 1,
              "count": 1
            },
            "received": {
              "amountWeiTotal": 1,
              "count": 1
            }
          },
          "vouchTotals": [
            {
              "balance": {
                "given": 1,
                "received": 1
              },
              "count": {
                "given": 1,
                "received": 1
              },
              "token": {
                "address": "text",
                "decimals": 1,
                "id": "text"
              }
            }
          ]
        }
      },
      "pauseState": "active",
      "markPrice": 1,
      "lastFundingRate": 1,
      "longOI": 1,
      "shortOI": 1,
      "volumeTotal": 1,
      "volume24h": 1,
      "createdAt": "text"
    }
  ],
  "nextCursor": 1
}

List every open position a trader holds across perps markets

get
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
traderAddressstringRequired

Ethereum address (0x-prefixed, 20 bytes)

Responses
200

Successful response

application/json
get/perps/open-positions
GET /api/v2/perps/open-positions?traderAddress=text HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "values": [
    {
      "market": {
        "id": 1,
        "marketOnchainId": 1,
        "subjectUserkey": "text",
        "subject": {
          "id": 1,
          "profileId": 1,
          "displayName": "text",
          "username": "text",
          "avatarUrl": "https://example.com",
          "description": "text",
          "score": 1,
          "status": "ACTIVE",
          "userkeys": [
            "text"
          ],
          "xpTotal": 1,
          "xpStreakDays": 1,
          "xpRemovedDueToAbuse": true,
          "influenceFactor": 1,
          "influenceFactorPercentile": 1,
          "humanVerificationStatus": "REQUESTED",
          "validatorNftCount": 1,
          "links": {
            "profile": "https://example.com",
            "scoreBreakdown": "https://example.com"
          },
          "stats": {
            "review": {
              "received": {
                "negative": 1,
                "neutral": 1,
                "positive": 1
              }
            },
            "vouch": {
              "given": {
                "amountWeiTotal": 1,
                "count": 1
              },
              "received": {
                "amountWeiTotal": 1,
                "count": 1
              }
            },
            "vouchTotals": [
              {
                "balance": {
                  "given": 1,
                  "received": 1
                },
                "count": {
                  "given": 1,
                  "received": 1
                },
                "token": {
                  "address": "text",
                  "decimals": 1,
                  "id": "text"
                }
              }
            ]
          }
        },
        "pauseState": "active",
        "markPrice": 1,
        "lastFundingRate": 1,
        "longOI": 1,
        "shortOI": 1,
        "volumeTotal": 1,
        "volume24h": 1,
        "createdAt": "text"
      },
      "size": 1,
      "collateral": 1,
      "pnl": 1,
      "pnlPercent": 1,
      "entryLeverage": 1
    }
  ]
}

List perps liquidations, optionally filtered by market or trader

get
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
marketOnchainIdinteger · max: 9007199254740991Optional
traderAddressstringOptional

Ethereum address (0x-prefixed, 20 bytes)

limitinteger · min: 1 · max: 100OptionalDefault: 50
cursorinteger · max: 9007199254740991Optional
Responses
200

Successful response

application/json
nextCursornumber · nullableRequired
get/perps/liquidations
GET /api/v2/perps/liquidations HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "values": [
    {
      "id": 1,
      "marketId": 1,
      "marketOnchainId": 1,
      "traderAddress": "text",
      "trader": {
        "id": 1,
        "profileId": 1,
        "displayName": "text",
        "username": "text",
        "avatarUrl": "https://example.com",
        "description": "text",
        "score": 1,
        "status": "ACTIVE",
        "userkeys": [
          "text"
        ],
        "xpTotal": 1,
        "xpStreakDays": 1,
        "xpRemovedDueToAbuse": true,
        "influenceFactor": 1,
        "influenceFactorPercentile": 1,
        "humanVerificationStatus": "REQUESTED",
        "validatorNftCount": 1,
        "links": {
          "profile": "https://example.com",
          "scoreBreakdown": "https://example.com"
        },
        "stats": {
          "review": {
            "received": {
              "negative": 1,
              "neutral": 1,
              "positive": 1
            }
          },
          "vouch": {
            "given": {
              "amountWeiTotal": 1,
              "count": 1
            },
            "received": {
              "amountWeiTotal": 1,
              "count": 1
            }
          },
          "vouchTotals": [
            {
              "balance": {
                "given": 1,
                "received": 1
              },
              "count": {
                "given": 1,
                "received": 1
              },
              "token": {
                "address": "text",
                "decimals": 1,
                "id": "text"
              }
            }
          ]
        }
      },
      "keeper": "text",
      "notional": 1,
      "bountyPaid": 1,
      "realizedPnl": 1,
      "badDebt": 1,
      "createdAt": "text"
    }
  ],
  "nextCursor": 1
}

Get protocol-wide perps stats (insurance fund, total open interest)

get
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Responses
200

Successful response

application/json
insuranceFundinteger · int64Required
totalOpenInterestinteger · int64Required
get/perps/protocol-stats
GET /api/v2/perps/protocol-stats HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "insuranceFund": 1,
  "totalOpenInterest": 1
}

Get a single perps market by on-chain ID

get
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
marketOnchainIdinteger · max: 9007199254740991Required
Responses
200

Successful response

application/json
idnumberRequired
marketOnchainIdnumberRequired
subjectUserkeystring · nullableRequired
pauseStatestring · enumRequiredPossible values:
markPriceinteger · int64Required
lastFundingRateinteger · int64Required
longOIinteger · int64Required
shortOIinteger · int64Required
volumeTotalinteger · int64Required
volume24hinteger · int64Required
createdAtstringRequired
initialMarginRatiointeger · int64Required
maintenanceMarginRatiointeger · int64Required
minMargininteger · int64Required
maxLeverageinteger · int64Required
perTxNotionalCapinteger · int64Required
perBlockNotionalCapinteger · int64Required
skewScaleinteger · int64Required
maxFundingVelocityPerDayinteger · int64Required
liquidationBountyBpsnumberRequired
liquidationFeeBpsnumberRequired
makerFeeBpsnumberRequired
takerFeeBpsnumberRequired
skewinteger · int64Required
totalCollateralinteger · int64Required
fundingValueinteger · int64Required
lastFundingTimestring · nullableRequired
markUpdatedAtstring · nullableRequired
get/perps/{marketOnchainId}
GET /api/v2/perps/{marketOnchainId} HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": 1,
  "marketOnchainId": 1,
  "subjectUserkey": "text",
  "subject": {
    "id": 1,
    "profileId": 1,
    "displayName": "text",
    "username": "text",
    "avatarUrl": "https://example.com",
    "description": "text",
    "score": 1,
    "status": "ACTIVE",
    "userkeys": [
      "text"
    ],
    "xpTotal": 1,
    "xpStreakDays": 1,
    "xpRemovedDueToAbuse": true,
    "influenceFactor": 1,
    "influenceFactorPercentile": 1,
    "humanVerificationStatus": "REQUESTED",
    "validatorNftCount": 1,
    "links": {
      "profile": "https://example.com",
      "scoreBreakdown": "https://example.com"
    },
    "stats": {
      "review": {
        "received": {
          "negative": 1,
          "neutral": 1,
          "positive": 1
        }
      },
      "vouch": {
        "given": {
          "amountWeiTotal": 1,
          "count": 1
        },
        "received": {
          "amountWeiTotal": 1,
          "count": 1
        }
      },
      "vouchTotals": [
        {
          "balance": {
            "given": 1,
            "received": 1
          },
          "count": {
            "given": 1,
            "received": 1
          },
          "token": {
            "address": "text",
            "decimals": 1,
            "id": "text"
          }
        }
      ]
    }
  },
  "pauseState": "active",
  "markPrice": 1,
  "lastFundingRate": 1,
  "longOI": 1,
  "shortOI": 1,
  "volumeTotal": 1,
  "volume24h": 1,
  "createdAt": "text",
  "initialMarginRatio": 1,
  "maintenanceMarginRatio": 1,
  "minMargin": 1,
  "maxLeverage": 1,
  "perTxNotionalCap": 1,
  "perBlockNotionalCap": 1,
  "skewScale": 1,
  "maxFundingVelocityPerDay": 1,
  "liquidationBountyBps": 1,
  "liquidationFeeBps": 1,
  "makerFeeBps": 1,
  "takerFeeBps": 1,
  "skew": 1,
  "totalCollateral": 1,
  "fundingValue": 1,
  "lastFundingTime": "text",
  "markUpdatedAt": "text"
}

Get a trader’s position in a perps market

get
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
marketOnchainIdinteger · max: 9007199254740991Required
Query parameters
traderAddressstringRequired

Ethereum address (0x-prefixed, 20 bytes)

Responses
200

Successful response

application/json
marketIdnumberRequired
marketOnchainIdnumberRequired
traderAddressstringRequired

Ethereum address (0x-prefixed, 20 bytes)

sizeinteger · int64Required
collateralinteger · int64Required
entrySignalinteger · int64Required
fundingSnapshotinteger · int64Required
openedAtstringRequired
lastUpdatedAtstringRequired
isClosedbooleanRequired
closedAtstring · nullableRequired
isFlaggedbooleanRequired
flaggedKeeperstring · nullableRequired

Ethereum address (0x-prefixed, 20 bytes)

flaggedAtstring · nullableRequired
lifetimeRealizedPnlinteger · int64Required
pnlinteger · int64 · nullableRequired
pnlPercentnumber · nullableRequired
entryLeveragenumber · nullableRequired
get/perps/{marketOnchainId}/position
GET /api/v2/perps/{marketOnchainId}/position?traderAddress=text HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "marketId": 1,
  "marketOnchainId": 1,
  "traderAddress": "text",
  "size": 1,
  "collateral": 1,
  "entrySignal": 1,
  "fundingSnapshot": 1,
  "openedAt": "text",
  "lastUpdatedAt": "text",
  "isClosed": true,
  "closedAt": "text",
  "isFlagged": true,
  "flaggedKeeper": "text",
  "flaggedAt": "text",
  "lifetimeRealizedPnl": 1,
  "pnl": 1,
  "pnlPercent": 1,
  "entryLeverage": 1
}

Get trade history for a perps market

get
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
marketOnchainIdinteger · max: 9007199254740991Required
Query parameters
traderAddressstringOptional

Ethereum address (0x-prefixed, 20 bytes)

limitinteger · min: 1 · max: 100OptionalDefault: 50
cursorinteger · max: 9007199254740991Optional
Responses
200

Successful response

application/json
nextCursornumber · nullableRequired
get/perps/{marketOnchainId}/trade-history
GET /api/v2/perps/{marketOnchainId}/trade-history HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "values": [
    {
      "id": 1,
      "type": "OPEN",
      "traderAddress": "text",
      "trader": {
        "id": 1,
        "profileId": 1,
        "displayName": "text",
        "username": "text",
        "avatarUrl": "https://example.com",
        "description": "text",
        "score": 1,
        "status": "ACTIVE",
        "userkeys": [
          "text"
        ],
        "xpTotal": 1,
        "xpStreakDays": 1,
        "xpRemovedDueToAbuse": true,
        "influenceFactor": 1,
        "influenceFactorPercentile": 1,
        "humanVerificationStatus": "REQUESTED",
        "validatorNftCount": 1,
        "links": {
          "profile": "https://example.com",
          "scoreBreakdown": "https://example.com"
        },
        "stats": {
          "review": {
            "received": {
              "negative": 1,
              "neutral": 1,
              "positive": 1
            }
          },
          "vouch": {
            "given": {
              "amountWeiTotal": 1,
              "count": 1
            },
            "received": {
              "amountWeiTotal": 1,
              "count": 1
            }
          },
          "vouchTotals": [
            {
              "balance": {
                "given": 1,
                "received": 1
              },
              "count": {
                "given": 1,
                "received": 1
              },
              "token": {
                "address": "text",
                "decimals": 1,
                "id": "text"
              }
            }
          ]
        }
      },
      "sizeDelta": 1,
      "collateralAmount": 1,
      "realizedPnl": 1,
      "signal": 1,
      "newSize": 1,
      "newCollateral": 1,
      "createdAt": "text"
    }
  ],
  "nextCursor": 1
}

Get funding history for a perps market

get
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
marketOnchainIdinteger · max: 9007199254740991Required
Query parameters
limitinteger · min: 1 · max: 100OptionalDefault: 50
cursorinteger · max: 9007199254740991Optional
Responses
200

Successful response

application/json
nextCursornumber · nullableRequired
get/perps/{marketOnchainId}/funding-history
GET /api/v2/perps/{marketOnchainId}/funding-history HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "values": [
    {
      "id": 1,
      "fundingValue": 1,
      "fundingRate": 1,
      "skew": 1,
      "createdAt": "text"
    }
  ],
  "nextCursor": 1
}

Get bucketed mark and funding-rate history for a perps market

get
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
marketOnchainIdinteger · max: 9007199254740991Required
Query parameters
durationstring · enumOptionalDefault: 7dPossible values:
Responses
200

Successful response

application/json
durationstring · enumRequiredPossible values:
get/perps/{marketOnchainId}/mark-history
GET /api/v2/perps/{marketOnchainId}/mark-history HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "duration": "1h",
  "values": [
    {
      "timeBucket": "text",
      "markPrice": 1,
      "fundingRate": 1
    }
  ]
}

List top traders for a perps market by lifetime realized PnL

get
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
marketOnchainIdinteger · max: 9007199254740991Required
Responses
200

Successful response

application/json
get/perps/{marketOnchainId}/top-traders
GET /api/v2/perps/{marketOnchainId}/top-traders HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "values": [
    {
      "traderAddress": "text",
      "trader": {
        "id": 1,
        "profileId": 1,
        "displayName": "text",
        "username": "text",
        "avatarUrl": "https://example.com",
        "description": "text",
        "score": 1,
        "status": "ACTIVE",
        "userkeys": [
          "text"
        ],
        "xpTotal": 1,
        "xpStreakDays": 1,
        "xpRemovedDueToAbuse": true,
        "influenceFactor": 1,
        "influenceFactorPercentile": 1,
        "humanVerificationStatus": "REQUESTED",
        "validatorNftCount": 1,
        "links": {
          "profile": "https://example.com",
          "scoreBreakdown": "https://example.com"
        },
        "stats": {
          "review": {
            "received": {
              "negative": 1,
              "neutral": 1,
              "positive": 1
            }
          },
          "vouch": {
            "given": {
              "amountWeiTotal": 1,
              "count": 1
            },
            "received": {
              "amountWeiTotal": 1,
              "count": 1
            }
          },
          "vouchTotals": [
            {
              "balance": {
                "given": 1,
                "received": 1
              },
              "count": {
                "given": 1,
                "received": 1
              },
              "token": {
                "address": "text",
                "decimals": 1,
                "id": "text"
              }
            }
          ]
        }
      },
      "lifetimeRealizedPnl": 1,
      "hasOpenPosition": true
    }
  ]
}

Quote opening or growing a perps position

get
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
marketOnchainIdinteger · max: 9007199254740991Required
Query parameters
collateralDeltastringRequired
leveragestring · enumRequiredPossible values:
sidestring · enumRequiredPossible values:
Responses
200

Successful response

application/json
or
get/perps/{marketOnchainId}/simulate-open
GET /api/v2/perps/{marketOnchainId}/simulate-open?collateralDelta=text&leverage=1&side=long HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "status": "text",
  "entrySignal": 1,
  "notional": 1,
  "required": 1,
  "sizeDelta": 1,
  "perTxNotionalCap": 1,
  "notionalCapOk": true,
  "worstCaseUpside": 1,
  "leveragedUpsideOk": true
}

Quote closing or reducing a perps position

get
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
marketOnchainIdinteger · max: 9007199254740991Required
Query parameters
traderstringRequired

Ethereum address (0x-prefixed, 20 bytes)

sizeDeltastringRequired
Responses
200

Successful response

application/json
closeSignalinteger · int64Required
collateralReturnedinteger · int64Required
realizedPnlinteger · int64Required
get/perps/{marketOnchainId}/simulate-close
GET /api/v2/perps/{marketOnchainId}/simulate-close?trader=text&sizeDelta=text HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "closeSignal": 1,
  "collateralReturned": 1,
  "realizedPnl": 1
}

Get margin ratio, free collateral, liquidation signal, and funding rate

get
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
marketOnchainIdinteger · max: 9007199254740991Required
Query parameters
traderstringRequired

Ethereum address (0x-prefixed, 20 bytes)

Responses
200

Successful response

application/json
marginRatiointeger · int64Required
freeCollateralinteger · int64Required
removableCollateralinteger · int64Required
liquidationSignalinteger · int64Required
fundingRateinteger · int64Required
get/perps/{marketOnchainId}/quotes
GET /api/v2/perps/{marketOnchainId}/quotes?trader=text HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "marginRatio": 1,
  "freeCollateral": 1,
  "removableCollateral": 1,
  "liquidationSignal": 1,
  "fundingRate": 1
}
PreviousNftsNextProfiles

Last updated