Quickstart

Ready to get started using NFT.Storage right now? Get up and running in minutes by following this quickstart guide. In this guide, we'll walk through the following steps:

1. Creating an NFT.Storage account
2. Uploading a file via the website
3. Getting a free API token
4. Using the JavaScript API

This guide uses Node.js since it's the fastest way to get started using the NFT.Storage JavaScript client programmatically, but don't worry if Node isn't your favorite runtime environment — or if you'd rather not do any coding at all. You can also use NFT.Storage in the following ways:

• Using the JavaScript client in web browsers.
• Upload and retrieve files directly from your Files page on the NFT.Storage website.

You can also use the HTTP API directly using any programming language or tooling that can send HTTP requests.

Create an account#

For this guide, you'll need an NFT.Storage account to get your API token and manage your stored data. You can sign up for free using your email address or GitHub.

Uploading a file using the website#

Once you're logged in, you can get started with NFT.Storage right away by uploading files using the website.

1. Click Files to go to your NFT.Storage file listing page.
2. Click the Upload button to go to the File upload page.
3. Click the Choose File button to select a file from your device:
4. If you're uploading a CAR file, tick the is CAR? check box.
5. Click the Upload button to store your file!

Once the upload is complete, you'll be able to view your file in the file listing page.

Get an API Token#

It only takes a few moments to get a free API token from NFT.Storage. This token enables you to interact with the NFT.Storage service without using the main website, enabling you to incorporate files stored using NFT.Storage directly into your applications and services.

1. Click Account to go to your NFT.Storage account page.
2. Click Create an API token.
3. Enter a descriptive name for your API token and click Create.
4. Make a note of the Token field somewhere secure where you know you won't lose it. You can click Copy to copy your new API token to your clipboard.

Using the JavaScript API#

If you're building apps with JavaScript or TypeScript, the NFT.Storage JavaScript client makes it simple to upload files and create ERC-1155 compatible NFT metadata.

The client library uses the familiar web File API and includes a File implementation for Node.js. Below is a small example that reads in the path to a file from the command line and stores the file with NFT.Storage.

You'll need Node.js version 16 or later for this example.

1. Make a new JavaScript project.

Create a new directory and use npm to create a new project:

mkdir nft-storage-quickstart
cd nft-storage-quickstart
npm init

NPM will ask a few questions about your project and create a package.json file.

2. Add the nft.storage client to your project dependencies.

Install the latest version of the nft.storage package:

npm install nft.storage

While we're at it, add the mime package, which will help us guess the file type for a given filename.

npm install mime

3. Create a file called upload.mjs and open it with your code editor.

Below is the code we need to upload an image with ERC-1155 compatible NFT metadata.

Paste in the code below and read through it. Feel free to remove the comments - they're just there to highlight what's going on.

// Import the NFTStorage class and File constructor from the 'nft.storage' package
import { NFTStorage, File } from 'nft.storage'

// The 'mime' npm package helps us set the correct file type on our File objects
import mime from 'mime'

// The 'fs' builtin module on Node.js provides access to the file system
import fs from 'fs'

// The 'path' module provides helpers for manipulating filesystem paths
import path from 'path'

// Paste your NFT.Storage API key into the quotes:
const NFT_STORAGE_KEY = 'REPLACE_ME_WITH_YOUR_KEY'

/**
  * Reads an image file from `imagePath` and stores an NFT with the given name and description.
  * @param {string} imagePath the path to an image file
  * @param {string} name a name for the NFT
  * @param {string} description a text description for the NFT
  */
async function storeNFT(imagePath, name, description) {
    // load the file from disk
    const image = await fileFromPath(imagePath)

    // create a new NFTStorage client using our API key
    const nftstorage = new NFTStorage({ token: NFT_STORAGE_KEY })

    // call client.store, passing in the image & metadata
    return nftstorage.store({
        image,
        name,
        description,
    })
}

/**
  * A helper to read a file from a location on disk and return a File object.
  * Note that this reads the entire file into memory and should not be used for
  * very large files. 
  * @param {string} filePath the path to a file to store
  * @returns {File} a File object containing the file content
  */
async function fileFromPath(filePath) {
    const content = await fs.promises.readFile(filePath)
    const type = mime.getType(filePath)
    return new File([content], path.basename(filePath), { type })
}


/**
 * The main entry point for the script that checks the command line arguments and
 * calls storeNFT.
 * 
 * To simplify the example, we don't do any fancy command line parsing. Just three
 * positional arguments for imagePath, name, and description
 */
async function main() {
    const args = process.argv.slice(2)
    if (args.length !== 3) {
        console.error(`usage: ${process.argv[0]} ${process.argv[1]} <image-path> <name> <description>`)
        process.exit(1)
    }

    const [imagePath, name, description] = args
    const result = await storeNFT(imagePath, name, description)
    console.log(result)
}

// Don't forget to actually call the main function!
// We can't `await` things at the top level, so this adds
// a .catch() to grab any errors and print them to the console.
main()
  .catch(err => {
      console.error(err)
      process.exit(1)
  })

4. Run your script with node

You should now be able to run the script and give it the path to an image file. You'll also need to supply a name and a description for the NFT.

In the example below, we'll assume there's a file called token.png in the same directory as the script. If your file is elsewhere, replace token.png with the path to your image.

node upload.mjs token.png 'A name for my token' 'A longer description for the token...'

Notice the quotes around 'A name for my token' and 'A longer description for the token...'. This causes the command line shell to treat the quoted text as a single argument instead of one for each word. Since our script is expecting exactly three arguments, you'll need to quote the name and description if there are spaces in them.

You should see something like this when you're finished:

Token {
  ipnft: 'bafyreifrkkhbwkf3fibwhbzcmpqnmh3b4t5t4ig7qdtymkdoatcycwe6n4',
  url: 'ipfs://bafyreifrkkhbwkf3fibwhbzcmpqnmh3b4t5t4ig7qdtymkdoatcycwe6n4/metadata.json'
}

The url is an IPFS url that can be viewed with Brave and other IPFS-aware tools and browsers. For other ways to access your token data, see our guide to retrieving NFT data.