Entity API

The Entity API is provided free of charge by Helium. The data provided focuses on infrequently changing attributes of Hotspots such as their owner and asserted location. This API is provided without any guarantees of uptime or support, and is intended for light use cases.For more in-depth analysis, refer to Oracles and Solana on-chain data.

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.

Active/Inactive Status

Active or Inactive status is deprecated for this API and will return false for all Hotspots on all routes.

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", //Deprecated, always false
          "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", //Deprecated, always false
      "lat": 0,
      "long": 0
    },
    {
      "key_to_asset_key": "string",
      "entity_key_str": "string",
      "is_active": "boolean", //Deprecated, always false
      "lat": 0,
      "long": 0
    },
    {
      "key_to_asset_key": "string",
      "entity_key_str": "string",
      "is_active": "boolean", //Deprecated, always false
      "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", // Deprecated, always false
      "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", // Deprecated, always false
      "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"
}