n8n-nodes-multiversx

This package provides comprehensive n8n nodes for interacting with the MultiversX blockchain network, enabling smart contract interactions, API queries, and blockchain data retrieval.

🚀 Features

• Smart Contract Interactions: Call and query smart contract functions
• ABI Support: Upload contract ABI for automatic function discovery
• Comprehensive API Coverage: Access MultiversX API for accounts, transactions, blocks, tokens, NFTs, and network data
• Multi-Network Support: Mainnet, Testnet, and Devnet compatibility
• Secure Wallet Integration: PEM file and private key management
• Flexible Operations: Both transaction execution and read-only queries
• AI Agent Ready: Optimized for AI workflow automation

📦 Installation

npm install n8n-nodes-multiversx

⚙️ Configuration

Step 1: Create MultiversX API Credentials

1. In your n8n instance, go to Settings → Credentials
2. Click Create New Credential
3. Search for MultiversX API and select it
4. Fill in the required fields:

Environment Selection

Choose your target network:

• Mainnet: Production network (https://api.multiversx.com)
• Testnet: Testing network (https://testnet-api.multiversx.com)
• Devnet: Development network (https://devnet-api.multiversx.com)

Wallet Configuration

You can provide your wallet in two ways:

Option 1: PEM File Content

-----BEGIN PRIVATE KEY for erd1...-----
your-private-key-content-here
-----END PRIVATE KEY for erd1...-----

Option 2: Private Key Hex

your-64-character-hex-private-key-without-0x-prefix

Additional Fields

• Wallet Password: Leave empty unless your wallet is encrypted
• Wallet Address: Your wallet address (erd1...) for verification

5. Click Test to verify the connection
6. Save the credentials

Step 2: Add MultiversX Node to Workflow

1. In your workflow, click Add Node
2. Search for MultiversX and add it
3. Select your created credentials
4. Choose your operation type

🔧 Usage Guide

Smart Contract Operations

1. Calling Smart Contract Functions

Setup:

1. Set Operation to Smart Contract
2. Set Contract Action to Call Function
3. Enter Contract Address (e.g., erd1qqqqqqqqqqqqqpgq...)
4. Upload Contract ABI (JSON format)
5. Select Function Name from the dropdown (auto-populated from ABI)
6. Configure Function Arguments if needed
7. Set Gas Limit (default: 5,000,000)
8. Set Value in EGLD (default: "0")

Example Configuration:

{
	"operation": "smartContract",
	"contractAction": "callFunction",
	"contractAddress": "erd1qqqqqqqqqqqqqpgqpsev0x4nufh240l44gf2t6qzkh9xvutqd8ssrnydzr",
	"functionName": "transfer",
	"functionArgs": {
		"args": [
			{
				"name": "recipient",
				"value": "erd1spyavw0956vq68xj8y4tenjpq2wd5a9p2c6j8gsz7ztyrnpxrruqzu47vn",
				"type": "address"
			},
			{
				"name": "amount",
				"value": "1000000000000000000",
				"type": "bignumber"
			}
		]
	},
	"gasLimit": 5000000,
	"value": "0"
}

2. Querying Smart Contract Functions (Read-Only)

Setup:

1. Set Operation to Smart Contract
2. Set Contract Action to Query Function
3. Enter Contract Address
4. Upload Contract ABI
5. Select Function Name
6. Configure Function Arguments if needed

Example Configuration:

{
	"operation": "smartContract",
	"contractAction": "queryFunction",
	"contractAddress": "erd1qqqqqqqqqqqqqpgqpsev0x4nufh240l44gf2t6qzkh9xvutqd8ssrnydzr",
	"functionName": "getBalance",
	"functionArgs": {
		"args": [
			{
				"name": "address",
				"value": "erd1spyavw0956vq68xj8y4tenjpq2wd5a9p2c6j8gsz7ztyrnpxrruqzu47vn",
				"type": "address"
			}
		]
	}
}

API Query Operations

1. Account Information

Get Account Balance:

{
	"operation": "apiQuery",
	"apiResource": "account",
	"accountAction": "getBalance",
	"address": "erd1spyavw0956vq68xj8y4tenjpq2wd5a9p2c6j8gsz7ztyrnpxrruqzu47vn"
}

Get Account Transactions:

{
	"operation": "apiQuery",
	"apiResource": "account",
	"accountAction": "getTransactions",
	"address": "erd1spyavw0956vq68xj8y4tenjpq2wd5a9p2c6j8gsz7ztyrnpxrruqzu47vn",
	"size": 50,
	"from": 0
}

2. Transaction Details

Get Transaction by Hash:

{
	"operation": "apiQuery",
	"apiResource": "transaction",
	"transactionAction": "getTransaction",
	"txHash": "your-transaction-hash-here"
}

3. Token and NFT Information

Get Token Details:

{
	"operation": "apiQuery",
	"apiResource": "token",
	"tokenAction": "getToken",
	"tokenIdentifier": "TOKEN-123456"
}

Get NFT Details:

{
	"operation": "apiQuery",
	"apiResource": "nft",
	"nftAction": "getNft",
	"tokenIdentifier": "COLLECTION-123456-01"
}

4. Network Information

Get Network Status:

{
	"operation": "apiQuery",
	"apiResource": "network",
	"networkAction": "getStatus"
}

📋 Function Argument Types

When configuring smart contract function arguments, use these types:

Type	Description	Example
string	Text values	"Hello World"
number	Integer numbers	42
bignumber	Large numbers	"1000000000000000000"
address	MultiversX addresses	"erd1..."
boolean	True/false values	"true" or "false"

🔍 Getting Contract ABI

To use smart contract functions, you need the contract's ABI (Application Binary Interface):

Method 1: From Contract Source

If you have the contract source code, the ABI is typically generated during compilation and saved as contract.abi.json.

Method 2: From MultiversX Explorer

1. Go to MultiversX Explorer
2. Search for your contract address
3. Go to the Code tab
4. Look for the ABI section and copy the JSON

Method 3: From API

curl https://api.multiversx.com/accounts/YOUR_CONTRACT_ADDRESS

🛠️ Troubleshooting

Common Issues

1. "Invalid address format" Error

• Ensure addresses start with erd1
• Check that the address is properly formatted
• Verify you're using the correct network

2. "Failed to parse ABI" Error

• Ensure the ABI is valid JSON format
• Check that all brackets and quotes are properly closed
• Verify the ABI matches the contract

3. "Transaction failed - insufficient gas" Error

• Increase the gas limit
• Check your account has enough EGLD for gas fees
• Verify the function parameters are correct

4. "Connection failed" Error

• Check your internet connection
• Verify the selected network is accessible
• Try switching to a different network environment

Gas Limit Guidelines

Operation Type	Recommended Gas Limit
Simple transfers	50,000 - 100,000
Token operations	500,000 - 1,000,000
Complex smart contracts	5,000,000 - 10,000,000
Contract deployment	60,000,000+

🌐 Supported Networks

Network	URL	Chain ID	Description
Mainnet	https://api.multiversx.com	1	Production network
Testnet	https://testnet-api.multiversx.com	T	Testing network
Devnet	https://devnet-api.multiversx.com	D	Development network

🔐 Security Best Practices

• Never share your private keys - Store them securely in n8n credentials
• Test on Devnet first - Always test your workflows on development network
• Use appropriate gas limits - Avoid setting gas limits too high
• Verify addresses - Double-check all addresses before transactions
• Monitor transactions - Keep track of transaction hashes for debugging

📋 Requirements

• n8n: Version 0.198.0 or higher
• Node.js: Version 16.x or higher
• MultiversX Wallet: Valid PEM file or private key
• Network Access: Internet connection to MultiversX APIs

🤝 Support

For issues, questions, or feature requests:

1. Check the MultiversX Documentation
2. Review transaction logs for detailed error messages
3. Test on Devnet before using Mainnet
4. Visit our GitHub repository for issues

📄 License

MIT License - see LICENSE file for details.

---

Happy Building with MultiversX! 🚀