mirror of
https://github.com/status-im/sn-api.git
synced 2026-08-30 17:21:13 +00:00
Filip Pajic
99d456f512
* handle potential APY service exceptions * document apy field as potentially undefined * linting fixes
690 lines
21 KiB
JSON
690 lines
21 KiB
JSON
{
|
|
"openapi" : "3.0.3",
|
|
"info" : {
|
|
"title" : "Status Network API - sn-api - V1",
|
|
"description" : "This is the OpenAPI documentation of the Status Network API. The service is not intended for public use but for Status company and its products.",
|
|
"version" : "1.0.0",
|
|
"contact" : { }
|
|
},
|
|
"servers" : [ {
|
|
"url" : "http://localhost:3001/api/v1"
|
|
} ],
|
|
"paths" : {
|
|
"/status" : {
|
|
"get" : {
|
|
"summary" : "Server Status",
|
|
"description" : "Returns 200 and \"Alive check\" message if the server is running properly",
|
|
"tags" : [ "status" ],
|
|
"operationId" : "serverStatus",
|
|
"responses" : {
|
|
"200" : {
|
|
"description" : "Message returned by the server on its liveness",
|
|
"content" : {
|
|
"application/json" : {
|
|
"schema" : {
|
|
"properties" : {
|
|
"message" : {
|
|
"type" : "string"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/auth/ethereum" : {
|
|
"post" : {
|
|
"summary" : "Unified login + register endpoint via Ethereum signature",
|
|
"tags" : [ "auth" ],
|
|
"requestBody" : {
|
|
"content" : {
|
|
"application/json" : {
|
|
"schema" : {
|
|
"properties" : {
|
|
"payload" : {
|
|
"type" : "string",
|
|
"description" : "Stringified base64 encoded representation of the signed payload. The payload is an object containing unix timestamp of signature time. ({ timestamp: number })"
|
|
},
|
|
"signature" : {
|
|
"type" : "string",
|
|
"description" : "The signature hash of the signed payload object."
|
|
}
|
|
},
|
|
"type" : "object",
|
|
"required" : [ "payload", "signature" ]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses" : {
|
|
"200" : {
|
|
"$ref" : "#/components/responses/UserSession"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/auth/me" : {
|
|
"get" : {
|
|
"summary" : "Returns currently logged in user's data",
|
|
"tags" : [ "auth" ],
|
|
"responses" : {
|
|
"200" : {
|
|
"description" : "",
|
|
"content" : {
|
|
"application/json" : {
|
|
"schema" : {
|
|
"$ref" : "#/components/schemas/User"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/auth/logout" : {
|
|
"post" : {
|
|
"summary" : "Logs out currently authenticated user",
|
|
"tags" : [ "auth" ],
|
|
"responses" : {
|
|
"200" : {
|
|
"description" : ""
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/apps" : {
|
|
"get" : {
|
|
"description" : "List of applications in the ecosystem",
|
|
"tags" : [ "apps" ],
|
|
"parameters" : [ {
|
|
"name" : "offset",
|
|
"in" : "query",
|
|
"description" : "Offset for pagination, determined by application's UUID",
|
|
"allowEmptyValue" : true,
|
|
"schema" : {
|
|
"type" : "string",
|
|
"format" : "uuid"
|
|
}
|
|
}, {
|
|
"name" : "limit",
|
|
"in" : "query",
|
|
"description" : "Number of maximal items to get",
|
|
"allowEmptyValue" : true,
|
|
"schema" : {
|
|
"type" : "number"
|
|
}
|
|
}, {
|
|
"name" : "category",
|
|
"in" : "query",
|
|
"allowEmptyValue" : true,
|
|
"schema" : {
|
|
"items" : {
|
|
"type" : "string",
|
|
"enum" : [ "AI", "BRIDGE", "COMMUNITY", "DEFI", "GAMING", "INFRA", "NFT", "PAYMENT", "PRIVACY", "SOCIAL", "SPENDING", "TOOLING", "WALLET" ]
|
|
},
|
|
"type" : "array"
|
|
}
|
|
}, {
|
|
"name" : "sortBy",
|
|
"in" : "query",
|
|
"description" : "Sorting parameter",
|
|
"allowEmptyValue" : true,
|
|
"schema" : {
|
|
"type" : "string",
|
|
"enum" : [ "POPULAR", "NEW" ]
|
|
}
|
|
}, {
|
|
"name" : "onlyFeatured",
|
|
"in" : "query",
|
|
"allowEmptyValue" : true,
|
|
"schema" : {
|
|
"type" : "boolean"
|
|
},
|
|
"description" : "Filter only featured ecosystem application"
|
|
} ],
|
|
"responses" : {
|
|
"200" : {
|
|
"description" : "",
|
|
"content" : {
|
|
"application/json" : {
|
|
"schema" : {
|
|
"items" : {
|
|
"$ref" : "#/components/schemas/EcosystemApplication"
|
|
},
|
|
"type" : "array"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/karma/{walletAddress}" : {
|
|
"parameters" : [ {
|
|
"name" : "walletAddress",
|
|
"in" : "path",
|
|
"description" : "Wallet address of the Karma holder",
|
|
"required" : true,
|
|
"schema" : {
|
|
"type" : "string",
|
|
"description" : "Ethereum wallet address"
|
|
}
|
|
} ],
|
|
"get" : {
|
|
"description" : "Gets the Karma data about a specific wallet address",
|
|
"tags" : [ "karma" ],
|
|
"responses" : {
|
|
"200" : {
|
|
"description" : "",
|
|
"content" : {
|
|
"application/json" : {
|
|
"schema" : {
|
|
"$ref" : "#/components/schemas/KarmaHolder"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/karma/leaderboard" : {
|
|
"get" : {
|
|
"summary" : "Gets the leaderboard of all of the karma holders",
|
|
"description" : "Returns multiple lists.\n\"best\" - The best ranked addresses overall\n\"gainers\" - The biggest gainers for a time period defined by the backend, (a week)\n\"ranked\" - List that will be empty if no session, but will return ranked list of 10 addresses with the authenticated one and their respective positions",
|
|
"tags" : [ "karma" ],
|
|
"responses" : {
|
|
"200" : {
|
|
"description" : "",
|
|
"content" : {
|
|
"application/json" : {
|
|
"schema" : {
|
|
"properties" : {
|
|
"best" : {
|
|
"items" : {
|
|
"properties" : {
|
|
"address" : {
|
|
"type" : "string"
|
|
},
|
|
"karma" : {
|
|
"type" : "number"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
},
|
|
"type" : "array",
|
|
"description" : "Overall best addresses that hold the most karma"
|
|
},
|
|
"gainers" : {
|
|
"items" : {
|
|
"properties" : {
|
|
"address" : {
|
|
"type" : "string"
|
|
},
|
|
"diff" : {
|
|
"type" : "number"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
},
|
|
"type" : "array",
|
|
"description" : "Top gainers for a specific time period (week)"
|
|
},
|
|
"ranked" : {
|
|
"items" : {
|
|
"properties" : {
|
|
"address" : {
|
|
"type" : "string"
|
|
},
|
|
"karma" : {
|
|
"type" : "number"
|
|
},
|
|
"globalPosition" : {
|
|
"type" : "number",
|
|
"minimum" : 1
|
|
}
|
|
},
|
|
"type" : "object"
|
|
},
|
|
"type" : "array",
|
|
"description" : "List of ranked addresses based on authenticated wallet. Will return an empty array in case of no authenticated session"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/captcha/cap/challenge" : {
|
|
"post" : {
|
|
"summary" : "Generates challenge for the frontend to solve",
|
|
"tags" : [ "captcha" ],
|
|
"responses" : {
|
|
"200" : {
|
|
"description" : "",
|
|
"content" : {
|
|
"application/json" : {
|
|
"schema" : {
|
|
"properties" : {
|
|
"challenge" : {
|
|
"properties" : {
|
|
"c" : {
|
|
"type" : "number"
|
|
},
|
|
"s" : {
|
|
"type" : "number"
|
|
},
|
|
"d" : {
|
|
"type" : "number"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
},
|
|
"token" : {
|
|
"type" : "string"
|
|
},
|
|
"expires" : {
|
|
"type" : "number"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/captcha/cap/redeem" : {
|
|
"post" : {
|
|
"summary" : "Route used for validating the result of PoW for a given challenge",
|
|
"tags" : [ "captcha" ],
|
|
"requestBody" : {
|
|
"content" : {
|
|
"application/json" : {
|
|
"schema" : {
|
|
"properties" : {
|
|
"token" : {
|
|
"type" : "string",
|
|
"required" : [ null ]
|
|
},
|
|
"solutions" : {
|
|
"items" : {
|
|
"type" : "number"
|
|
},
|
|
"type" : "array",
|
|
"required" : [ null ]
|
|
}
|
|
},
|
|
"type" : "object"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses" : {
|
|
"200" : {
|
|
"description" : "",
|
|
"content" : {
|
|
"application/json" : {
|
|
"schema" : {
|
|
"properties" : {
|
|
"success" : {
|
|
"type" : "boolean",
|
|
"required" : [ null ]
|
|
},
|
|
"message" : {
|
|
"type" : "string"
|
|
},
|
|
"token" : {
|
|
"type" : "string"
|
|
},
|
|
"expires" : {
|
|
"type" : "number"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/auth/me/session" : {
|
|
"get" : {
|
|
"summary" : "Adds currently logged in user's session data (primarily used for SIWE)",
|
|
"tags" : [ "auth" ],
|
|
"responses" : {
|
|
"200" : {
|
|
"$ref" : "#/components/responses/UserSession"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/sybil/connect-provider/pow" : {
|
|
"post" : {
|
|
"description" : "Connect POW provider via Captcha verification for minting onboarding karma",
|
|
"tags" : [ "sybil" ],
|
|
"requestBody" : {
|
|
"content" : {
|
|
"application/json" : {
|
|
"schema" : {
|
|
"properties" : {
|
|
"token" : {
|
|
"type" : "string",
|
|
"description" : "Token received from successfull Captcha challenge redeeming"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses" : {
|
|
"200" : {
|
|
"$ref" : "#/components/responses/ConnectProviderResponse"
|
|
},
|
|
"409" : {
|
|
"description" : "Error when provider is already connected"
|
|
},
|
|
"400" : {
|
|
"description" : "Bad request error if token is invalid"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/predeposits/vaults" : {
|
|
"get" : {
|
|
"tags" : [ "predeposits" ],
|
|
"responses" : {
|
|
"200" : {
|
|
"description" : "",
|
|
"content" : {
|
|
"application/json" : {
|
|
"schema" : {
|
|
"type" : "array",
|
|
"items" : {
|
|
"properties" : {
|
|
"vaultAddress" : {
|
|
"type" : "string",
|
|
"description" : "Ethereum address of the vault"
|
|
},
|
|
"apy" : {
|
|
"type" : "number",
|
|
"minimum" : 0,
|
|
"maximum" : 100,
|
|
"description" : "Expected APY percentage for the given vault. Can be undefined in case of calculation failure"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/auth/me/quota" : {
|
|
"get" : {
|
|
"description" : "Fetches user transaction quotas",
|
|
"tags" : [ "auth" ],
|
|
"responses" : {
|
|
"200" : {
|
|
"description" : "",
|
|
"content" : {
|
|
"application/json" : {
|
|
"schema" : {
|
|
"properties" : {
|
|
"address" : {
|
|
"type" : "string",
|
|
"description" : "Ethereum address of the logged in user"
|
|
},
|
|
"tier" : {
|
|
"properties" : {
|
|
"name" : {
|
|
"type" : "string",
|
|
"description" : "Karma Tier name"
|
|
},
|
|
"quotaPerEpoch" : {
|
|
"type" : "string",
|
|
"description" : "Total number of transactions available for an epoch of the specified tier",
|
|
"example" : "2025-12-27T00:00:00.432Z"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
},
|
|
"epoch" : {
|
|
"properties" : {
|
|
"id" : {
|
|
"type" : "string",
|
|
"description" : "Current epoch ID"
|
|
},
|
|
"txCount" : {
|
|
"type" : "string",
|
|
"description" : "Total number of transactions available for an epoch of the specified tier"
|
|
},
|
|
"remainingQuota" : {
|
|
"type" : "string",
|
|
"description" : "Transactions left for the address in the current epoch"
|
|
},
|
|
"resetsAt" : {
|
|
"type" : "string",
|
|
"format" : "date",
|
|
"description" : "Epoch restart time",
|
|
"example" : "2025-12-27T00:00:00.432Z"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
},
|
|
"denyList" : {
|
|
"properties" : {
|
|
"isActive" : {
|
|
"type" : "boolean",
|
|
"description" : "Indicator if the current address is on the deny list"
|
|
},
|
|
"expiresAt" : {
|
|
"type" : "string",
|
|
"format" : "date",
|
|
"example" : "2025-12-27T00:00:00.432Z"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
},
|
|
"lastUpdatedAt" : {
|
|
"type" : "string",
|
|
"format" : "date",
|
|
"example" : "2025-12-27T00:00:00.432Z"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
},
|
|
"example" : {
|
|
"result" : {
|
|
"address" : "0xb71a06a1c801941f48181140232ecbf16623b28d",
|
|
"tier" : {
|
|
"name" : "regular",
|
|
"quotaPerEpoch" : "480"
|
|
},
|
|
"epoch" : {
|
|
"id" : "20449",
|
|
"txCount" : "480",
|
|
"remainingQuota" : "129",
|
|
"resetsAt" : "2025-12-27T00:00:00.432Z"
|
|
},
|
|
"denyList" : {
|
|
"isActive" : false,
|
|
"expiresAt" : null
|
|
},
|
|
"lastUpdatedAt" : "2025-12-26T17:32:47.432Z"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"tags" : [ {
|
|
"name" : "status",
|
|
"description" : "Server health data"
|
|
}, {
|
|
"name" : "auth",
|
|
"description" : "Server authentication"
|
|
}, {
|
|
"name" : "apps",
|
|
"description" : "Ecosystem applications"
|
|
}, {
|
|
"name" : "karma",
|
|
"description" : "Karma related endpoints"
|
|
}, {
|
|
"name" : "captcha",
|
|
"description" : "Captcha endpoints"
|
|
}, {
|
|
"name" : "sybil",
|
|
"description" : "Sybil protection related routes"
|
|
}, {
|
|
"name" : "predeposits",
|
|
"description" : "Pre-Deposit campaing related routes"
|
|
} ],
|
|
"components" : {
|
|
"schemas" : {
|
|
"EcosystemApplication" : {
|
|
"properties" : {
|
|
"id" : {
|
|
"type" : "string",
|
|
"format" : "uuid",
|
|
"description" : "Unique ID of the ecosystem application"
|
|
},
|
|
"title" : {
|
|
"type" : "string",
|
|
"description" : "The title of the ecosystem project"
|
|
},
|
|
"description" : {
|
|
"type" : "string",
|
|
"description" : "Description of the ecosystem project"
|
|
},
|
|
"socials" : {
|
|
"properties" : {
|
|
"x" : {
|
|
"type" : "string",
|
|
"format" : "uri",
|
|
"description" : "X/Twitter URI of the ecosystem project"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
},
|
|
"isFeatured" : {
|
|
"type" : "boolean",
|
|
"description" : "Flag indicating if the project should be marked as featured"
|
|
},
|
|
"link" : {
|
|
"type" : "string",
|
|
"format" : "uri",
|
|
"description" : "Ecosystem application website link"
|
|
},
|
|
"profileImgURI" : {
|
|
"type" : "string",
|
|
"format" : "uri",
|
|
"description" : "URI of the image to be displayed"
|
|
},
|
|
"bannerImgURI" : {
|
|
"type" : "string",
|
|
"format" : "uri",
|
|
"description" : "Banner image URI"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
},
|
|
"KarmaHolder" : {
|
|
"properties" : {
|
|
"address" : {
|
|
"type" : "string"
|
|
},
|
|
"balance" : {
|
|
"type" : "integer"
|
|
},
|
|
"breakdown" : {
|
|
"items" : {
|
|
"properties" : {
|
|
"source" : {
|
|
"type" : "string",
|
|
"enum" : [ "ONBOARDING", "STAKING", "LIQUIDITY_PROVIDING", "PFP_DONATOR", "ECOSYSTEM_BUILDING", "APP_USAGE" ],
|
|
"description" : "The source of which the karma was gained"
|
|
},
|
|
"amount" : {
|
|
"type" : "integer"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
},
|
|
"type" : "array"
|
|
},
|
|
"tierLevel" : {
|
|
"type" : "number"
|
|
},
|
|
"globalPosition" : {
|
|
"type" : "number",
|
|
"description" : "Global position on the leaderboard of an address"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
},
|
|
"User" : {
|
|
"properties" : {
|
|
"address" : {
|
|
"type" : "string",
|
|
"description" : "Ethereum wallet address of the user in lower case"
|
|
},
|
|
"connectedSybilProviders" : {
|
|
"type" : "string",
|
|
"enum" : [ "POW" ]
|
|
},
|
|
"globalPosition" : {
|
|
"type" : "number"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
}
|
|
},
|
|
"responses" : {
|
|
"UserSession" : {
|
|
"description" : "",
|
|
"content" : {
|
|
"application/json" : {
|
|
"schema" : {
|
|
"properties" : {
|
|
"address" : {
|
|
"type" : "string"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"ConnectProviderResponse" : {
|
|
"description" : "",
|
|
"content" : {
|
|
"application/json" : {
|
|
"schema" : {
|
|
"properties" : {
|
|
"success" : {
|
|
"type" : "boolean"
|
|
}
|
|
},
|
|
"type" : "object"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|