Hotspot API

The Hotspot API is provided free of charge by the Helium Foundation. The data provided focuses on infrequently changing attributes of Hotspots such as their owner and asserted location. For more in-depth analysis, refer to Oracles and Solana on-chain data.

The API runs inside an AWS EKS cluster and leverages an RDS instance for improved accessibility of on-chain Hotspot data. The API sits behind Cloudflare to offer reduced latency via endpoint caching. As on-chain Hotspot data is updated (e.g., attributes such as location, activity, and ownership), invalidations are created to ensure up-to-date data is provided to API consumers.

In the interest of anonymity, the latitude/longitude data provided by the API is obfuscated to H3 resolution 8 rather than resolution 12 stored on-chain on Solana.

An active Hotspot is defined as having rewards issued within the last 30 days (either for Proof of Coverage or data transfer).

Wallet Info by Wallet Public Key

GET https://entities.nft.helium.io/v2/wallet/:walletPublicKey

Get wallet information by wallet public key including Hotspot count, list of Hotspot records, and token account balances.

Request

Path Parameters

Param	Type	Note
Wallet public key (required)	string	Solana public key/address for the wallet

Response

200: OK

{
  "hotspots_count": 1,
  "hotspots": [
    {
      "name": "string",
      "description": "string",
      "image": "string",
      "asset_id": "string",
      "key_to_asset_key": "string",
      "entity_key_b64": "string",
      "key_serialization": "string",
      "entity_key_str": "string",
      "hotspot_infos": {
        "iot": {
          "address": "string", // Solana address
          "street": "string",
          "city": "string",
          "state": "string",
          "country": "string",
          "is_active": "boolean",
          "location": "string", // Obfuscated
          "dc_onboarding_fee_paid": "string",
          "elevation": 0,
          "gain": 0,
          "created_at": "string",
          "asset": "string",
          "lat": 0, // Obfuscated
          "long": 0 // Obfuscated
        },
        "mobile": {
          "location": null
        }
      },
      "attributes": [
        {
          "trait_type": "ecc_compact",
          "value": "string"
        },
        {
          "trait_type": "entity_key_string",
          "value": "string"
        },
        {
          "trait_type": "entity_key",
          "value": "string"
        },
        {
          "trait_type": "rewardable",
          "value": "boolean"
        },
        {
          "trait_type": "networks",
          "value": ["string"]
        },
        {
          "trait_type": "iot_city",
          "value": "string"
        },
        {
          "trait_type": "iot_state",
          "value": "string"
        },
        {
          "trait_type": "iot_country",
          "value": "string"
        },
        {
          "trait_type": "iot_lat", // Obfuscated
          "value": 0
        },
        {
          "trait_type": "iot_long", // Obfuscated
          "value": 0
        }
      ]
    }
  ],
  "balances": [
    {
      "mint": "hntyVP6YFm1Hg25TN9WGLqM12b8TQmcknKrdu1oxWux",
      "balance": "0"
    },
    {
      "mint": "mb1eu7TzEc71KxDpsmsKoucSSuuoGLv1drys1oP2jh6",
      "balance": "0"
    },
    {
      "mint": "iotEVVZLEywoTn1QdwNPddxPWszn3zFhEot3MfL9fns",
      "balance": "0"
    },
    {
      "mint": "dcuc8Amr83Wz27ZkQ2K9NS6r8zRpf1J6cvArEBDZDmm",
      "balance": "0"
    }
  ]
}

500: Error

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "string"
}

Hotspot Pagination Metadata

GET https://entities.nft.helium.io/v2/hotspots/pagination-metadata?subnetwork=<subnetwork>

Get general information about the pagination of Hotspots in a particular subnetwork including pagination page size, total number of Hotspots, and total number of pages.

Request

Query Parameters

Param	Type	Note
Subnetwork (required)	string	Name of subnetwork (iot, mobile, etc)

Response

200: OK

{
  "pageSize": 0,
  "totalItems": 0,
  "totalPages": 0
}

400: Error

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "string"
}

500: Error

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "string"
}

List Hotspots by Subnetwork

GET https://entities.nft.helium.io/v2/hotspots?subnetwork=<subnetwork>&cursor=<cursor>

Get a list of key-value pairs denoting Hotspots in a particular subnetwork. If the returned cursor field is a non-null value, more results are available. If no cursor is provided (e.g., if the URL does not include the &cursor=<cursor> query string component), then the first page of results is returned along with a cursor value for the subsequent page.

Request

Query Parameters

Param	Type	Note
Subnetwork (required)	string	Name of subnetwork (iot, mobile, etc.)
Cursor (optional)	string	Cursor for the next page of Hotspots to fetch

Response

200: OK

{
  "cursor": "string", // Or null if there are no more Hotspots to fetch
  "items": [
    {
      "key_to_asset_key": "string",
      "entity_key_str": "string",
      "is_active": "boolean",
      "lat": 0,
      "long": 0
    },
    {
      "key_to_asset_key": "string",
      "entity_key_str": "string",
      "is_active": "boolean",
      "lat": 0,
      "long": 0
    },
    {
      "key_to_asset_key": "string",
      "entity_key_str": "string",
      "is_active": "boolean",
      "lat": 0,
      "long": 0
    }
  ]
}

400: Error

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "string"
}

500: Error

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "string"
}

Hotspot Info by Key to Asset Key

GET https://entities.nft.helium.io/v1/:keyToAssetKey

GET https://entities.nft.helium.io/v2/hotspot/:keyToAssetKey

Get Hotspot records based on the key to asset value. Both the /v1 and /v2/hotspot routes return identical results and are merely provided for backward compatibility.

Request

Path Parameters

Param	Type	Note
Key to asset (required)	string	Public key of on-chain KeyToAssetV0 struct

Response

200: OK

{
  "name": "string",
  "description": "string",
  "image": "string",
  "asset_id": "string",
  "key_to_asset_key": "string",
  "entity_key_b64": "string",
  "key_serialization": "string",
  "entity_key_str": "string",
  "hotspot_infos": {
    "iot": {
      "address": "string", // Solana address
      "street": "string",
      "city": "string",
      "state": "string",
      "country": "string",
      "is_active": "boolean",
      "location": "string", // Obfuscated
      "dc_onboarding_fee_paid": "string",
      "elevation": 0,
      "gain": 0,
      "created_at": "string",
      "asset": "string",
      "lat": 0, // Obfuscated
      "long": 0 // Obfuscated
    },
    "mobile": {
      "location": null
    }
  },
  "attributes": [
    {
      "trait_type": "ecc_compact",
      "value": "string"
    },
    {
      "trait_type": "entity_key_string",
      "value": "string"
    },
    {
      "trait_type": "entity_key",
      "value": "string"
    },
    {
      "trait_type": "rewardable",
      "value": "boolean"
    },
    {
      "trait_type": "networks",
      "value": ["string"]
    },
    {
      "trait_type": "iot_city",
      "value": "string"
    },
    {
      "trait_type": "iot_state",
      "value": "string"
    },
    {
      "trait_type": "iot_country",
      "value": "string"
    },
    {
      "trait_type": "iot_lat", // Obfuscated
      "value": 0
    },
    {
      "trait_type": "iot_long", // Obfuscated
      "value": 0
    }
  ]
}

404: Error

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "string"
}

500: Error

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "string"
}

Hotspot Info by Entity/ECC Compact Key

GET https://entities.nft.helium.io/:eccCompact

Get Hotspot records based on the entity / ECC compact key value.

Request

Path Parameters

Param	Type	Note
Entity / ECC compact key	string	Legacy Helium L1 address of the Hotspot

Response

200: OK

{
  "name": "string",
  "description": "string",
  "image": "string",
  "asset_id": "string",
  "key_to_asset_key": "string",
  "entity_key_b64": "string",
  "key_serialization": "string",
  "entity_key_str": "string",
  "hotspot_infos": {
    "iot": {
      "address": "string", // Solana address
      "street": "string",
      "city": "string",
      "state": "string",
      "country": "string",
      "is_active": "boolean",
      "location": "string", // Obfuscated
      "dc_onboarding_fee_paid": "string",
      "elevation": 0,
      "gain": 0,
      "created_at": "string",
      "asset": "string",
      "lat": 0, // Obfuscated
      "long": 0 // Obfuscated
    },
    "mobile": {
      "location": null
    }
  },
  "attributes": [
    {
      "trait_type": "ecc_compact",
      "value": "string"
    },
    {
      "trait_type": "entity_key_string",
      "value": "string"
    },
    {
      "trait_type": "entity_key",
      "value": "string"
    },
    {
      "trait_type": "rewardable",
      "value": "boolean"
    },
    {
      "trait_type": "networks",
      "value": ["string"]
    },
    {
      "trait_type": "iot_city",
      "value": "string"
    },
    {
      "trait_type": "iot_state",
      "value": "string"
    },
    {
      "trait_type": "iot_country",
      "value": "string"
    },
    {
      "trait_type": "iot_lat", // Obfuscated
      "value": 0
    },
    {
      "trait_type": "iot_long", // Obfuscated
      "value": 0
    }
  ]
}

404: Error

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "string"
}

500: Error

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "string"
}

List OUI Organization Info

GET https://entities.nft.helium.io/v2/oui/all

Get a list of OUIs registered on the Helium Network and corresponding organization info.

Response

200: OK

{
  "orgs": [
    {
      "oui": 1,
      "owner": "string", // Org admin key
      "payer": "string", // Key only used for DC payments
      "escrow": "string", // Escrow account key
      "delegate_keys": [ // List of keys allowed some specific actions, see services.
        "string"
      ],
      "locked": "boolean" // Is org locked because of no payment
    },
    {
      "oui": 2,
      "owner": "string",
      "payer": "string",
      "escrow": "string",
      "delegate_keys": [
        "string"
      ],
      "locked": "boolean"
    },
    {
      "oui": 3,
      "owner": "string",
      "payer": "string",
      "escrow": "string",
      "delegate_keys": [
        "string"
      ],
      "locked": "boolean"
    },
  ]
}

500: Error

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "string"
}

OUI Organization Info by OUI ID

GET https://entities.nft.helium.io/v2/oui/:id

Get an OUI registered on the Helium Network and corresponding organization info by the OUI ID.

Request

Path Parameters

Param	Type	Note
OUI ID (required)	string	ID of the OUI (e.g., 1) for getting info

Response

200: OK

{
  "oui": 1, // OUI ID
  "owner": "string", // Org admin key
  "payer": "string", // Key only used for DC payments
  "escrow": "string", // Escrow account key
  "delegate_keys": [ // List of keys allowed some specific actions, see services.
    "string"
  ],
  "locked": "boolean" // Is org locked because of no payment
}

400: Error

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "string"
}

500: Error

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "string"
}