sn-api/docs/api/v1.openapi_collection.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"
            }
          }
        }
      }
    }
  }
}