Skip to main content

Hello IOTA

This basic example introduces you to the IOTA TypeScript SDK. The Node.js example mints IOTA on a IOTA network and then queries the address to get a sum for the owned IOTA. You don't need to use an IDE to complete the example, but one like Microsoft Visual Studio Code helps centralize more advanced projects.

Before you begin​

You need an address on a IOTA development network (Devnet, Testnet, local). If you don't already have an address, use the IOTA Client CLI or the IOTA Wallet browser extension to create one.

You also need Node.js and a package manager like pnpm to follow this example, so install them on your system if you haven't already.

Start a project​

Using a Terminal or Console, create a folder on your system (hello-iota in this example) and make it the working directory.

mkdir hello-iota
cd hello-iota

When you use a package manager to install the necessary packages, it downloads the modules to your node_modules folder and adds the references to your package.json file, creating the file if it doesn't already exist. For this example, you need only the IOTA TypeScript SDK:

npm i -D @iota/iota-sdk

Your package.json file now has a dependencies section with @iota/iota-sdk listed with the package version number.

"dependencies": {
    "@iota/iota-sdk": "^<VERSION_NUMBER>"
}

Get some IOTA for your account​

Instead of a 'Hello World' output to your console, this example introduces some IOTA to your wallet address. You must be on Devnet, Testnet, or a local network to use a faucet for minting IOTA.

Create a new index.js file in the root of your project with the following code.

import { getFullnodeUrl, IotaClient } from '@iota/iota-sdk/client';
import { getFaucetHost, requestIotaFromFaucetV1 } from '@iota/iota-sdk/faucet';
import { NANOS_PER_IOTA } from '@iota/iota-sdk/utils';

// replace <YOUR_IOTA_ADDRESS> with your actual address, which is in the form 0x123...
const MY_ADDRESS = '<YOUR_IOTA_ADDRESS>';

// create a new IotaClient object pointing to the network you want to use
const iotaClient = new IotaClient({ url: getFullnodeUrl('devnet') });

// Convert NANOS to IOTA
const balance = (balance) => {
    return Number.parseInt(balance.totalBalance) / Number(NANOS_PER_IOTA);
};

// store the JSON representation for the IOTA the address owns before using faucet
const iotaBefore = await iotaClient.getBalance({
    owner: MY_ADDRESS,
});

await requestIotaFromFaucetV1({
    // use getFaucetHost to make sure you're using correct faucet address
    // you can also just use the address (see IOTA TypeScript SDK Quick Start for values)
    host: getFaucetHost('devnet'),
    recipient: MY_ADDRESS,
});

// store the JSON representation for the IOTA the address owns after using faucet
const iotaAfter = await iotaClient.getBalance({
    owner: MY_ADDRESS,
});

// Output result to console.
console.log(
    `Balance before faucet: ${balance(iotaBefore)} IOTA. Balance after: ${balance(
        iotaAfter,
    )} IOTA. Hello, IOTA!`,
);

Save the file, then use Node.js to run it in your Console or Terminal:

node index.js

The code imports the requestIotaFromFaucetv1 function from the SDK and calls it to mint IOTA for the provided address. The code also imports IotaClient to create a new client on the IOTA network that it uses to query the address and output the amount of IOTA the address owns before and after using the faucet. You can check the total IOTA for your address using the IOTA Wallet or IOTA Client CLI.

info

Faucets on Devnet and Testnet are rate limited. If you run the script too many times, you surpass the limit and must wait to successfully run it again.

You can also use the IOTA Client CLI to perform client calls on a IOTA network.