> For the complete documentation index, see [llms.txt](https://moken.gitbook.io/moken-dev-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://moken.gitbook.io/moken-dev-docs/onboard-your-depin/api-documentation-for-integration.md). # API Documentation for Integration Below is the updated outline of the API you need to implement to integrate your services with DePIN Tracker. This document details the required endpoints, input parameters, and expected responses. Our platform interacts with mining devices, retrieving their statuses, rewards, and associated metadata. Your API will need to implement the following GET endpoints to ensure seamless integration. **Note:** All endpoints are optional, but you must provide at least one of `getStatus` or `getRewards` for your DePIN to be added to the tracker. We strongly suggest implementing all possible endpoints. ## 1. **`https://api.yourservice.com/getStatus`** **Description:** Fetches the current operational status and issues of a miner device. * **Method:** GET * **Query Parameters:** * `deviceId` (string): Unique identifier of the miner device. * `secondaryDeviceId` (string | null): Optional second identifier for the device, e.g., `deviceSerialNumber` or `hexId`. * **Headers:** * `Authorization`: You must provide us with your Authorization value. * **Response (Status 200 - IMinerStatus):** * `issues` (MinerIssueWithGravity\[]): Array of current issues, each with a severity level (`gravity`). * Possible `gravity` values: * `High` * `Medium` * `Low` * The `type` must be in CamelCase, short, and descriptive (e.g., `SpeedTestMissing`, `Offline`). * **Note:** If the miner is down or offline, use `Offline` as the issue type with `gravity` set to `High`. * **Response (Status 404):** Miner does not exist. **Example Response (200):** ```json { "issues": [ { "type": "SpeedTestMissing", "gravity": "Medium" }, { "type": "Offline", "gravity": "High" } ] } ``` **Important:** You must provide a complete list of possible issue types so we can display help labels to the user. *** ## 2. **`https://api.yourservice.com/getRewards`** **Description:** Retrieves rewards earned by a miner over a specified period. * **Method:** GET * **Query Parameters:** * `deviceId` (string): Unique identifier of the miner. * `secondaryDeviceId` (string | null): Optional second identifier for the miner. * `period` (string): Time range for rewards. Accepted values are `1d`, `3d`, `7d`, `14d`, `30d`, `365d`, `24h`, `all`. * **Headers:** * `Authorization`: You must provide us with your Authorization value. * **Response (Status 200 - IAbstractReward\[]):** * `date` (string): Date of the reward in ISO 8601 format. * `tokens` (object\[]): Array of tokens earned, each with an `amount` and `symbol`. * **Response (Status 404):** Miner does not exist. * **Response (Status 200 - Empty Array):** Miner exists but has no rewards. **Example Response (200):** ```json [ { "date": "2025-01-01T00:00:00Z", "tokens": [ { "amount": 10.5, "symbol": "HNT" }, { "amount": 0.8, "symbol": "SOL" } ] } ] ``` **Example Response (200 - Empty Array):** ```json [] ``` **Notes:** * This endpoint must only return **complete and finalized** reward data. If the reward data for a given date is still subject to change (e.g. token values not finalized), that day's data must not be returned. * Symbol must be in UPPERCASE. You must provide a list of token symbols with their respective links to Coinmarketcap (if listed). * This endpoint must not be paginated. We will query with `period=all` only once. *** ## 3. **`https://api.yourservice.com/getMinersByWallet`** **Description:** Retrieves a list of miners associated with a specific wallet address. * **Method:** GET * **Query Parameters:** * `walletAddress` (string): Wallet address. * **Headers:** * `Authorization`: You must provide us with your Authorization value. * **Response (Status 200 - IDevice\[]):** * `deviceId` (string): Unique identifier of the miner. * `secondaryDeviceId` (string | null): Optional secondary identifier. * `friendlyName` (string): User-friendly name of the miner. * `type` (MinerType): The DePIN name in CamelCase. We will provide this value to you. **Example Response (200):** ```json [ { "deviceId": "miner123", "secondaryDeviceId": "serial456", "friendlyName": "Main Miner", "type": "Helium" } ] ``` **Example Response (200 - Empty Array):** ```json [] ``` **Note:** Let us know if your network contains devices of significantly different types so we can define multiple MinerType values for you. *** ## 4. **`https://api.yourservice.com/getMinersByName`** **Description:** Fetches miners based on their friendly name or alias. * **Method:** GET * **Query Parameters:** * `name` (string): Friendly name of the miner. * **Headers:** * `Authorization`: You must provide us with your Authorization value. * **Response (Status 200 - IDevice\[]):** * `deviceId` (string): Unique identifier of the miner. * `secondaryDeviceId` (string | null): Optional secondary identifier. * `friendlyName` (string): User-friendly name of the miner. * `type` (MinerType): The DePIN name in CamelCase. We will provide this value to you. **Example Response (200):** ```json [ { "deviceId": "miner789", "secondaryDeviceId": null, "friendlyName": "Backup Miner", "type": "Geodnet" } ] ``` **Example Response (200 - Empty Array):** ```json [] ``` **Note:** Let us know if your network contains devices of significantly different types so we can define multiple MinerType values for you. *** ## 5. **`https://api.yourservice.com/getLocation`** **Description:** Fetches the geographical location of a miner device. * **Method:** GET * **Query Parameters:** * `deviceId` (string): Unique identifier of the miner. * `secondaryDeviceId` (string | null): Optional second identifier. * **Headers:** * `Authorization`: You must provide us with your Authorization value. * **Response (Status 200 - ILocation):** * `lat` (number): Latitude of the miner. * `lng` (number): Longitude of the miner. * **Response (Status 404):** Miner ID is invalid. **Example Response (200):** ```json { "lat": 37.7749, "lng": -122.4194 } ``` **Example Response (404):** ```json { "error": "Invalid miner ID" } ``` ## 6. `https://api.yourservice.com/getProduct` **Description:** Returns the product identifier (e.g., UPC or model number) for a specific miner device. * **Method:** GET * **Query Parameters:** * `deviceId` (string): Unique identifier of the miner. * `secondaryDeviceId` (string | null): Optional second identifier. * **Headers:** * `Authorization`: You must provide us with your Authorization value. * **Response (200 - IProduct):** ```json { "identifier": "UPC-1234567890" } ``` * **Response (Status 404):** Miner ID is invalid. **Note:** This field helps us identify specific device models and differentiate between variations. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://moken.gitbook.io/moken-dev-docs/onboard-your-depin/api-documentation-for-integration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.