How-to use the Ledger Stax Metadata tool? | Developers

How-to use the Ledger Stax Metadata tool?

Estimated reading time: 8 minutes

This article is for NFT dApp developers and NFT creators who want to allow their audience to showcase their NFTs on the Ledger Stax device.

Ledger Stax Lock Screen

The Lock screen is the first thing users see when they pick up their Ledger Stax. The Lock Screen can be customized by choosing an image from the NFT gallery or from the user’s smartphone.

The Ledger screen has specific requirements which need to be considered:

  • Dimension: The screen’s resolution is 672px (height) by 400px (width). For an optimal display of the NFT on Ledger Stax, make sure the NFT image height is 1.68x the width and the minimum width is 400px (ex: 840px * 500px).
  • Color profile: The Ledger Stax screen supports up to 16 levels of gray (4-bit grayscale).
CryptoPunk on Ledger Stax
CryptoPunk on Ledger Stax

Ledger Live will give the NFT owner an option to crop the image for their NFT and the color will be converted to 4-bit grayscale, but in a lot of instances it won’t look ideal.

As a creator, you can provide a dedicated secondary image that will only be used for displaying on Ledger Stax’s lock screen. As an example, for the [ Ledger ] Market Pass - Genesis Edition NFT, you can see below the primary image against the secondary image that has been designed for Ledger Stax.

Introducing the Ledger Stax metadata

In order to showcase NFTs on Ledger Stax (with the dedicated secondary image), we’ve introduced a new metadata ledger_stax_image that points to the location of the file where the Ledger Stax image is stored.

The metadata schema is open to all. As a dApp developer, you can create a flow where end-users will upload an image for Ledger Stax which will then trigger the metadata update.

You have two options:

  • Update manually if the metadata is mutable
  • Use the Ledger Stax Metadata tool if the metadata is immutable

Update mutable metadata

If the Metadata of your NFTs can be updated (“mutable metadata”), then simply follow the below instructions:

  1. First, make sure that the Ledger Stax images of your NFTs fit the Ledger Stax device requirements.
  2. Then, upload the images somewhere in the cloud (any storage provider like AWS S3, Google Cloud or IPFS could work).
  3. Once your Ledger Stax images are uploaded to the cloud, all you need is to add their location (URL) to the NFT Metadata file. The Metadata standard is open for all and simply consists of adding a ledger_stax_image field (pointing to the Ledger Stax image location) inside the ledger_metadata attribute as shown below:
    "name": "Sample NFT Title #1",
    "description": "Learn how add the Ledger Stax image URL in the metadata file.", 
    "image": "", 
    "attributes": [ ... ], 
    "ledger_metadata": {
        "ledger_stax_image": "" // Location of the Ledger Stax image
Check out this article for a more in-depth step-by-step guide on the metadata update.

Use the Ledger Stax metadata tool for immutable metadata

Sometimes you can’t change the metadata yourself due to their immutable nature or simply because you don’t have the technical capability to do so. Don’t worry, we got you covered. We built a UI tool that makes it super easy to update the metadata of your collection, at a click of a button.

1. Open the tool:

2. Connect to your wallet (clear signing is required)

CryptoPunk on Ledger Stax
Wallet connection

3. Once your wallet is connected, select the contract that contains the tokens (NFTs) you wish to add/update the Ledger Stax metadata for.

Note that you can see for each contract the number of tokens available (total supply) and how many of them are Ledger Stax compatible (i.e. the ledger_stax_image attribute [pointing to the Ledger Stax compatible image location] is part of your Metadata).

Only ERC-721 and ERC-1155 smart contracts which are owned by the connected wallet will be shown on this page.
CryptoPunk on Ledger Stax
List of smart contracts you own

4.Select the tokens you wish to add/update the Ledger Stax metadata for.

CryptoPunk on Ledger Stax
List of tokens

Note that you can select tokens in bulk in three different ways:

  • Select all tokens of the contract.
  • Select a token range.
  • Select only tokens without Ledger Stax metadata.

5. Upon the selected tokens, provide the folder location (URL) where the Ledger Stax images are stored and hit the “Update Metadata” button.

The folder must contain images that follow the following requirements:
  • Supported files: JPEG (.jpeg/.jpg) and PNG (.png)
  • File name convention: {token_id}.{file_extension}
Where should I upload my Ledger Stax images?
  • We strongly recommend to upload your Ledger Stax images on one of our validated storage providers: AWS S3 or Google Cloud. IPFS is also supported but not optimal for large folders.
  • You could store them anywhere else as long as the hosting server can handle a minimum of 100 read requests per second.
  • The ability to upload files right from the app will be supported soon!

6. Should your Ledger Stax images comply with the requirements, your metadata will be updated, and your NFTs can now be showcased on the Ledger Stax screen. You’re ready to go!

CryptoPunk on Ledger Stax
Ledger Stax metadata successfully updated

In case of errors with the Ledger Stax images (i.e. images missing in the folder), we’ll report them in the modal dialog as shown below:

CryptoPunk on Ledger Stax
We found some errors

To resolve the issues:

  • Click on the “Fix now” button.
  • In your cloud-based folder, fix the missing images by making sure that all selected tokens have an associated image with the right convention name.
  • Click on the “Update metadata” button to start over the Update Metadata process

Did you find this page helpful?

How would you improve this page for developers?

Getting Started
Theme Features