Tokens

Tokens are the heartbeat of the Ark NFT ecosystem, representing unique digital assets.

Token Model

The token model encapsulates the intricate details of individual tokens within a contract on the ArkProject platform. Each token is uniquely identified by its token_id and is tethered to a specific contract_address, which denotes the contract it belongs to. The type property further classifies the nature of the token within that contract.

Every token is associated with an owner, indicating the current holder of the token. For those interested in the provenance and lifecycle of the token, properties like block_number_minted shed light on when the token came into existence, while the mint_transaction_hash provides a reference to the specific transaction that minted the token. The minter_address reveals the entity responsible for the minting action.

Properties

Name
contract_address
Type
string
Description
Unique identifier for the token contract.
Name
type
Type
string
Description
The type of contract.
Name
token_id
Type
string
Description
Token ID (decimal).
Name
token_id_hex
Type
string
Description
Token ID padded to 64 digits and prefixed with 0x.
Name
owner
Type
string
Description
The address of the owner of the token.
Name
mint_info
Type
object
Description
Information about the minting of the token.
Name
metadata
Type
object
Description
Metadata of the token.

Metadata

The Metadata object is structured into two key properties: normalized and raw. This dual-property design addresses the challenge of the non-standardized nature of NFT Metadata, where various projects adopt their unique structures.

Our approach involves normalizing the metadata for specified target types. In cases where an NFT does not match these types, we efficiently transform its metadata into a recognized format.

Normalized Metadata Properties

The resulting normalized metadata is presented in a streamlined, predictable JSON format, simplifying the process of working with diverse NFT metadata.

GET/v1/tokens/{contract_address}

Retrieve NFTs

This endpoint allows you to retrieve a paginated list of all tokens of a collection. By default, a maximum of hundred tokens are shown per page.

Path parameters

Name
contract_address
Type
string
Description
Hexadecimal address of the contract.

Query string parameters

Name
cursor
Type
string
Description
The cursor to get the next page. Retrieved from previous request that may be paginated.
Name
tokens_ids
Type
string
Description
A whitelist of token ID to be retrieved. You may repeat this query string parameter to whitelist more than one token ID. The token ID can be decimal or hexadecimal (with or without padding).
Name
limit
Type
number
Description
The limit on the number of items returned per request, defaulting to 100, with a 1MB data cap. (Refer to the pagination section below for more details.)

Request

GET

/v1/tokens/{contract_address}

curl -G https://api.arkproject.dev/v1/tokens/{contract_address} \
  -H "x-api-key: <INSERT_API_KEY_HERE>"

Response

{
  "cursor": null,
  "result": [
    {
      "contract_address": "0x1111",
          "token_id": "10017690",
          "token_id_hex": "0x000000000000000000000000000000000000000000000000000000000098db9a",
          "owner": "0xOwnerAddress",
          "mint_info": {
              "address": "0xOwnerAddress",
              "timestamp": 1695627964,
              "transaction_hash": "0xMintTransactionHash"
          },
          "metadata": {
              "normalized": {
                  "image_mime_type": "",
                  "image_key": "",
                  "image": "",
                  "image_data": "",
                  "external_url": "",
                  "description": "",
                  "name": "",
                  "attributes": [],
                  "properties": [],
                  "background_color": "",
                  "animation_url": "",
                  "animation_key": "",
                  "animation_mime_type": "",
                  "youtube_url": ""
              },
              "raw": "",
              "metadata_updated_at": 1701783069
          }
    },
    {
      "contract_address": "0x2222",
      // ...
    }
  ]
}

GET/v1/tokens/{contract_address}/{token_id}

Retrieve NFT

This endpoint allows you to retrieve a token by providing its contract address and its token ID. Refer to the list at the top of this page to see which properties are included with token objects.

Path parameters

Name
contract_address
Type
string
Description
Hexadecimal address of the contract.
Name
token_id
Type
string
Description
Hexadecimal or decimal token ID.

Request

GET

/v1/tokens/{contract_address}/{token_id}

curl https://api.arkproject.dev/v1/tokens/{contract_address}/{token_id} \
-H "x-api-key: <INSERT_API_KEY_HERE>"

Response

{
"result": {
    "contract_address": "0x05dbdedc203e92749e2e746e2d40a768d966bd243df04a6b712e222bc040a9af",
    "token_id": "10017690",
    "token_id_hex": "0x000000000000000000000000000000000000000000000000000000000098db9a",
    "owner": "0x00a69e64b09ef9830305c3e3166e2b42b3b38edd054c18a9105974f7eb949826",
    "mint_info": {
        "address": "0x00a69e64b09ef9830305c3e3166e2b42b3b38edd054c18a9105974f7eb949826",
        "timestamp": 1695627964,
        "transaction_hash": "0x01c44fac1a71a545af1280dc59f9608587e31e4e3607d01464e76583f51c113a"
    },
    "metadata": {
        "normalized": {
            "image_mime_type": "image/svg+xml",
            "image_key": "67c89c60b82f29b3439cfd88f7c0572df9bde9f457eadd321b6f25e6bbbd6e31.svg",
            "image": "https://starknet.id/api/identicons/10017690",
            "image_data": "",
            "external_url": "",
            "description": "This token represents an identity on Starknet.",
            "name": "Starknet ID: 10017690",
            "attributes": [],
            "properties": [],
            "background_color": "",
            "animation_url": "",
            "animation_key": "",
            "animation_mime_type": "",
            "youtube_url": ""
        },
        "raw": "{\"name\":\"Starknet ID: 10017690\",\"description\":\"This token represents an identity on Starknet.\",\"image\":\"https://starknet.id/api/identicons/10017690\",\"expiry\":null,\"attributes\":null}",
        "metadata_updated_at": 1701783069
    }
}
}

POST/v1/tokens/batch

Batch Retrieve NFTs

This API endpoint retrieves information about multiple tokens in a single request (batch).

Body parameters

Name
tokens
Type
array
Description

Tokens

Name
token_id
Type
string
Description
Unique identifier for the token within the contract
Name
contract_address
Type
string
Description
Contract address of the token

Request

POST

/v1/tokens/batch

  curl --location 'https://api.arkproject.dev/v1/tokens/batch' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <INSERT_API_KEY_HERE>' \
  --data '{
    "tokens": [
      {
        "contract_address": "0x00057c4b510d66eb1188a7173f31cccee47b9736d40185da8144377b896d5ff3",
        "token_id": "944683"
      },
      {
        "contract_address": "0x05dbdedc203e92749e2e746e2d40a768d966bd243df04a6b712e222bc040a9af",
        "token_id": "24356438889"
      }
    ]
  }'

Response

{
    "result": [
        {
            "contract_address": "0x00057c4b510d66eb1188a7173f31cccee47b9736d40185da8144377b896d5ff3",
            "contract_name": "Starknet Journey Set by Braavos",
            "token_id": "944683",
            "token_id_hex": "0x00000000000000000000000000000000000000000000000000000000000e6a2b",
            "owner": "0x0489b43f4a1792c309704f94ce6c56b1519a3e07c398f89fa55f6f88d90995ff",
            "mint_info": {
                "address": "0x0489b43f4a1792c309704f94ce6c56b1519a3e07c398f89fa55f6f88d90995ff",
                "timestamp": 1687602676,
                "transaction_hash": "0x0318d38f4b93cb0681ad064aedcca05889c94d41672e3934c53790f537ad6c5c",
                "block_number": null
            },
            "metadata": {...},
            "awaiting_metadata_update": false
        },
        {
            "contract_address": "0x05dbdedc203e92749e2e746e2d40a768d966bd243df04a6b712e222bc040a9af",
            "contract_name": "Starknet.id",
            "token_id": "24356438889",
            "token_id_hex": "0x00000000000000000000000000000000000000000000000000000005abc1c369",
            "owner": "0x0489b43f4a1792c309704f94ce6c56b1519a3e07c398f89fa55f6f88d90995ff",
            "mint_info": {
                "address": "0x0489b43f4a1792c309704f94ce6c56b1519a3e07c398f89fa55f6f88d90995ff",
                "timestamp": 1694759399,
                "transaction_hash": "0x0568b2ceeecb577af3ca2f1029a926f92d3d89ac782acc5c021264b701f27db1",
                "block_number": null
            },
            "metadata": {...},
            "awaiting_metadata_update": false
        }
    ]
}

POST/v1/tokens/{contract_address}/{token_id}/metadata/refresh

Refresh NFT Metadata

Resync the metadata for an NFT.

Important: Updating NFT information takes resources. To prevent overuse, there's a waiting period before refreshing the same NFT again.

Path parameters

Name
contract_address
Type
string
Description
Hexadecimal address of the NFT contract
Name
token_id
Type
string
Description
The ID of the token

Request

POST

/v1/tokens/{contract_address}/{token_id}/metadata/refresh

curl -X POST https://api.arkproject.dev/v1/tokens/{contract_address}/{token_id}/metadata/refresh \
  -H "Content-Type: application/json" \
  -H "x-api-key: <INSERT_API_KEY_HERE>"

Response

{
"result": "We've queued this token to update its metadata! It will be updated soon."
}