home / skills / multiversx / mx-ai-skills / mvx_sdk_js_tokens

mvx_sdk_js_tokens skill

safe

This skill simplifies building and managing MultiversX token transfers, issuance, and queries in JavaScript/TypeScript SDKs for faster safe deployments.

npx playbooks add skill multiversx/mx-ai-skills --skill mvx_sdk_js_tokens

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.2 KB

---
name: mvx_sdk_js_tokens
description: Token operations (ESDT/NFT/SFT) for MultiversX TypeScript/JavaScript SDK.
---

# MultiversX SDK-JS Token Operations

This skill covers ESDT (fungible), NFT, and SFT token operations.

## Token Transfers

### Native EGLD Transfer
```typescript
const controller = entrypoint.createTransfersController();

const tx = await controller.createTransactionForTransfer(account, nonce, {
    receiver: Address.newFromBech32("erd1..."),
    nativeAmount: 1000000000000000000n  // 1 EGLD (18 decimals)
});
```

### ESDT Token Transfer
```typescript
import { TokenTransfer } from "@multiversx/sdk-core";

const tx = await controller.createTransactionForTransfer(account, nonce, {
    receiver: receiverAddress,
    tokenTransfers: [
        TokenTransfer.fungibleFromBigInteger("TOKEN-abc123", 1000000n)
    ]
});
```

### NFT/SFT Transfer
```typescript
const tx = await controller.createTransactionForTransfer(account, nonce, {
    receiver: receiverAddress,
    tokenTransfers: [
        TokenTransfer.nftFromBigInteger("NFT-abc123", 1n, 1n)  // nonce=1, quantity=1
    ]
});
```

## Token Issuance

### Issue Fungible Token
```typescript
const controller = entrypoint.createTokenManagementController();

const tx = await controller.createTransactionForIssuingFungible(account, nonce, {
    tokenName: "MyToken",
    tokenTicker: "MTK",
    initialSupply: 1_000_000_000000n,  // With decimals
    numDecimals: 6n,
    canFreeze: false,
    canWipe: true,
    canPause: false,
    canChangeOwner: true,
    canUpgrade: true,
    canAddSpecialRoles: true
});

const txHash = await entrypoint.sendTransaction(tx);
const outcome = await controller.awaitCompletedIssueFungible(txHash);
const tokenIdentifier = outcome[0].tokenIdentifier;
```

### Issue Semi-Fungible Token
```typescript
const tx = await controller.createTransactionForIssuingSemiFungible(account, nonce, {
    tokenName: "MySFT",
    tokenTicker: "SFT",
    canFreeze: false,
    canWipe: true,
    canPause: false,
    canTransferNFTCreateRole: true,
    canChangeOwner: true,
    canUpgrade: true,
    canAddSpecialRoles: true
});
```

### Register and Set NFT Roles
```typescript
const tx = await controller.createTransactionForRegisteringAndSettingRoles(account, nonce, {
    tokenName: "MyNFT",
    tokenTicker: "MNFT",
    tokenType: "NonFungibleESDT"
});
```

## Token Role Management

```typescript
// Set special role
const tx = await controller.createTransactionForSettingSpecialRole(account, nonce, {
    tokenIdentifier: "TOKEN-abc123",
    user: userAddress,
    addRoleLocalMint: true,
    addRoleLocalBurn: true
});
```

## Token Queries

```typescript
const provider = entrypoint.createNetworkProvider();

// Get specific token
const token = await provider.getTokenOfAccount(address, "TOKEN-abc123");

// Get all fungible tokens
const tokens = await provider.getFungibleTokensOfAccount(address);

// Get all NFTs
const nfts = await provider.getNonFungibleTokensOfAccount(address);
```

## Best Practices

1. **Decimals**: EGLD has 18 decimals, custom tokens vary
2. **Token identifiers**: Format is `TICKER-hexhash` (e.g., `USDC-a1b2c3`)
3. **NFT nonces**: Start at 1, increment per mint
4. **Gas**: Token operations need ~60,000,000+ gas

Overview

This skill provides token operations for the MultiversX TypeScript/JavaScript SDK, covering ESDT (fungible), NFT and SFT workflows. It explains how to create transfers, issue tokens, set roles, and query token state using SDK controllers and the network provider. The content highlights concrete code patterns, required parameters, and common pitfalls to avoid.

How this skill works

The SDK exposes controllers for transfers and token management plus a network provider for queries. You create transactions (native EGLD, ESDT, NFT/SFT) via controller helper methods, sign/send them, and optionally await completion to obtain outcomes like token identifiers. Role management and token issuance require specific flags and sufficient gas; queries return token lists or single token objects for accounts.

When to use it

Send native EGLD payments between accounts
Transfer fungible ESDT tokens or batched token transfers
Transfer or mint NFTs and SFTs (non-fungible / semi-fungible assets)
Issue new fungible tokens or register NFTs/SFTs on-chain
Set or update special roles (mint/burn/creator permissions)
Query account tokens and NFT collections for UI or reconciliation

Best practices

Remember EGLD uses 18 decimals; custom tokens set numDecimals at issuance
Use token identifiers in the form TICKER-hexhash (e.g., USDC-a1b2c3) when referencing tokens
Start NFT nonces at 1 and increment per mint to avoid collisions
Provision sufficient gas for token operations (expect ~60,000,000+ gas for many actions)
Await transaction completion when you need on-chain outcomes like a new token identifier
Set explicit role flags during issuance or via role management transactions to limit privileges

Example use cases

Create a payment widget that sends native EGLD or ESDT tokens from users to a merchant account
Issue a new utility token (fungible) with custom decimals and supply, then distribute initial balances
Mint an NFT collection and set creator/mint roles so a dApp can mint items programmatically
Transfer an SFT batch to represent in-game consumables with quantity >1
Build a dashboard that queries and displays all fungible tokens and NFTs owned by a user

FAQ

How do I get a new token identifier after issuing a token?

Send the issuance transaction and await the controller’s completion helper; the outcome contains the tokenIdentifier returned on-chain.

What decimals should I use for custom tokens?

Choose decimals based on smallest unit you need; common choices are 6 or 18. Remember EGLD is 18 decimals and client UIs must format amounts accordingly.