@mysten/sui/docs/hello-sui.md

Sui TypeScript API

# Hello Sui

> Build your first Sui application with the TypeScript SDK

This basic example introduces you to the Sui TypeScript SDK. The Node.js example mints SUI on a Sui
network and then queries the address to get a sum for the owned SUI. 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 Sui development network (Devnet, Testnet, local). If you don't already have
an address, use the [Sui Client CLI](https://docs.sui.io/references/cli/client) or the
[Sui Wallet browser extension](https://docs.mystenlabs.com) to create one.

You also need [Node.js](https://nodejs.org/en/download/current) and a package manager like
[pnpm](https://pnpm.io/installation) 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-sui` in this example) and make
it the working directory.

```sh
mkdir hello-sui
cd hello-sui
```

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 Sui TypeScript SDK:

```sh npm2yarn
npm i -D @mysten/sui
```

The SDK is published as an ESM only package, so you also need to set `"type": "module"` in your
`package.json`. Your `package.json` file should look like this:

```json
{
	"type": "module",
	"dependencies": {
		"@mysten/sui": "^<VERSION_NUMBER>"
	}
}
```

## Get some SUI for your account

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

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

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

// create a new SuiGrpcClient object pointing to the network you want to use
const suiClient = new SuiGrpcClient({
	network: 'devnet',
	baseUrl: 'https://fullnode.devnet.sui.io:443',
});

// Convert MIST to Sui
const balance = (balance) => {
	return Number.parseInt(balance.totalBalance) / Number(MIST_PER_SUI);
};

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

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

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

// Output result to console.
console.log(
	`Balance before faucet: ${balance(suiBefore)} SUI. Balance after: ${balance(
		suiAfter,
	)} SUI. Hello, SUI!`,
);
```

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

```sh
node index.js
```

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

> **Note:** 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. For testnet, the best way to get
> SUI is via the Web UI: `faucet.sui.io`.

You can also use the [Sui Client CLI](https://docs.sui.io/references/cli/client) to perform client
calls on a Sui network.