@elizaos/plugin-multiversx

MultiversX blockchain integration plugin for Eliza OS that enables on chain actions.

Overview

This plugin aims to be the basis of all interactions with the MultiversX ecosystem.

Features

• EGLD and ESDT token transfers
• Token creation and management
• Pool creation on xExchange
• Swap tokens
• Lend EGLD and add collateral on Hatom
• Wallet balance recovery
• Multiple network support (mainnet, devnet, testnet)
• Secure transaction signing
• Automatic nonce management
• Transaction status tracking
• Built-in denomination handling
• Comprehensive error handling

Prerequisites

To use the Receive_EGLD action of this plugin, you must set up a QR Code API. The implementation is available here: QrCode_generator.

Adding a new action

Reuse providers and utilities from the existing actions where possible. Add more utilities if you think they will be useful for other actions.

1. Add the action to the actions directory. Try to follow the naming convention of the other actions.
2. Export the action in the index.ts file.

Installation

npx elizaos plugins add @elizaos-plugins/plugin-multiversx

Configuration

The plugin requires environment variables or runtime settings:

MVX_PRIVATE_KEY=your-wallet-private-key
MVX_NETWORK=devnet  # mainnet, devnet, or testnet
ACCESS_TOKEN_MANAGEMENT_TO=everyone  # you can put an userid to limit token managament to one user only (use same id as in the database)
QR_CODE_API_URL=  

Usage

Token Transfer

import { multiversxPlugin } from "@elizaos/plugin-multiversx";

// Send EGLD to an erd address
const result = await eliza.execute({
    action: "SEND_TOKEN",
    content: {
        tokenAddress: "erd1...",
        amount: "1",
        tokenIdentifier: "EGLD",
    },
});

// Send EGLD to a herotag
const result = await eliza.execute({
    action: "SEND_TOKEN",
    content: {
        tokenAddress: "elpulpo",
        amount: "1",
        tokenIdentifier: "EGLD",
    },
});

// Send ESDT with identifier
const result = await eliza.execute({
    action: "SEND_TOKEN",
    content: {
        tokenAddress: "erd1...",
        amount: "100",
        tokenIdentifier: "TEST-a1b2c3",
    },
});

// Send ESDT with ticker
const result = await eliza.execute({
    action: "SEND_TOKEN",
    content: {
        tokenAddress: "erd1...",
        amount: "100",
        tokenIdentifier: "TEST",
    },
});

Token Creation

const result = await eliza.execute({
    action: "CREATE_TOKEN",
    content: {
        tokenName: "TestToken",
        tokenTicker: "TEST",
        decimals: "18",
        amount: "1000000",
    },
});

Token Swap

const result = await eliza.execute({
    action: "SWAP",
    content: {
        tokenIn: "EGLD",
        amountIn: "1",
        tokenOut: "MEX"
    },
});

Pool Creation

const result = await eliza.execute({
    action: "CREATE_POOL",
    content: {
        baseTokenID: "KWAK",
        quoteTokenID: "EGLD",
        baseAmount: "1000000",
        quoteAmount: "20"
    },
});

Check Wallet

const result = await eliza.execute({
    action: "CHECK_WALLET"
});

Get address

const result = await eliza.execute({
    action: "GET_ADDRESS"
});

Lend Egld

const result = await eliza.execute({
    action: "LEND_EGLD",
    content: {
        "amount": "10"
    },
});

Add Collateral

const result = await eliza.execute({
    action: "ADD_COLLATERAL",
    content: {
        "amount": "40",
        "tokenIdentifier": "HEGLD"
    },
});

Troubleshooting

Common Issues

1. Transaction Failures

   • Verify wallet has sufficient balance
   • Check network configuration matches intended network
   • Ensure correct token identifiers
   • Verify recipient address format

2. Configuration Problems

   • Validate private key format
   • Check network selection is valid
   • Ensure environment variables are properly set
   • Verify wallet permissions for token operations

3. Token Creation Issues

   • Check token name and ticker format
   • Verify EGLD balance for issuance fee
   • Ensure unique token identifiers
   • Monitor transaction status

4. Network Connectivity

   • Verify network endpoint availability
   • Check API rate limits
   • Monitor network status
   • Ensure proper network selection

Security Best Practices

1. Key Management

   • Never expose private keys in code
   • Use environment variables for sensitive data
   • Implement key rotation policies
   • Monitor wallet activity

2. Transaction Safety

   • Validate all transaction parameters
   • Implement transaction limits
   • Use proper denomination handling
   • Double-check recipient addresses

3. Network Security

   • Use secure network connections
   • Implement retry mechanisms
   • Monitor for suspicious activity
   • Keep dependencies updated

4. Error Handling

   • Implement comprehensive error logging
   • Handle network timeouts gracefully
   • Validate all user inputs
   • Provide clear error messages

Testing

Run the test suite:

pnpm test

Watch mode for development:

pnpm test:watch

Dependencies

• @multiversx/sdk-core: ^13.15.0
• bignumber.js: ^9.1.2
• tsup: ^8.3.5
• vitest: ^2.1.5

Contributing

Contributions are welcome! Please see the CONTRIBUTING.md file for more information.

Credits

This plugin integrates with the MultiversX blockchain using their official SDK.

Special thanks to:

• The MultiversX team for developing the MultiversX blockchain
• The Eliza community for their contributions and feedback.

For more information about MultiversX blockchain capabilities:

• MultiversX Documentation
• MultiversX Developer Portal
• MultiversX GitHub Repository

License

This plugin is part of the Eliza project. See the main project repository for license information.