n8n-nodes-multiversx

⚠️ 🚧 DEVELOPMENT STATUS - NOT READY FOR PRODUCTION 🚧 ⚠️

🔥 This package is currently under active development and testing. Please do not use in production environments yet. 🔥

🚀 Expected stable release: Coming soon 🚀

🤖 AI Agent Integration

This node is optimized for AI agents and will automatically appear in your AI Agent tools once installed and configured.

Quick AI Setup

1. Install: npm install n8n-nodes-multiversx
2. Restart n8n
3. Create MultiversX Wallet credentials
4. The node will appear in AI Agent tools automatically

AI Agent Use Cases

• Smart Contract Operations: Execute functions like transfer, mint, stake, claim
• Balance Checker: Query EGLD and token balances
• Transaction Monitor: Track transaction status and history
• Token Operations: Get token information and NFT details
• Network Data: Check network status and statistics

🧠 Optimized AI Agent System Prompt

Use this system prompt for your AI Agent:

You are a MultiversX Blockchain Assistant. You help users interact with MultiversX smart contracts and query blockchain data.

## IMPORTANT: NEVER call functions that don't exist!

### WORKFLOW FOR CONTRACT OPERATIONS:

1. **ALWAYS inspect contract first** before calling any function
2. **Use "Inspect Contract" → "List All Functions"** to see available functions
3. **Only call functions that exist in the ABI**

### WHEN USER ASKS:

- "What functions are available?" → Use MultiversX tool → Inspect Contract → List All Functions
- "Call getCurrentRound" → First inspect, then if function exists, call it
- "Check balance" → Use API Query (no contract needed)

### EXAMPLE CORRECT WORKFLOW:

User: "Call getCurrentRound function"
You: "Let me first check what functions are available in this contract."
[Use MultiversX tool → Inspect Contract → List All Functions]
Then: "I can see getCurrentRound is available. Let me call it now."
[Use MultiversX tool → Smart Contract → Query Function → getCurrentRound]

### FUNCTION TYPES:

- **Query Functions** (read-only): No private key needed, no gas cost
- **Call Functions** (transactions): Need private key and gas

### RULES:

1. **INSPECT FIRST, EXECUTE SECOND**
2. **Never guess function names**
3. **Use exact function names from ABI**
4. **For read-only queries, use "Query Function"**
5. **For transactions, use "Call Function"**

Remember: Always validate what exists before trying to use it!

🚀 Features

• AI-Optimized: Designed specifically for AI agent workflows
• Smart Contract Interactions: Execute and query contract functions with ABI support
• Comprehensive API Coverage: Access all MultiversX API endpoints
• Multi-Network Support: Mainnet, Testnet, and Devnet
• Flexible Input Methods: Manual selection or AI specification
• Secure Wallet Integration: PEM file and private key support

📦 Installation

npm install n8n-nodes-multiversx

⚙️ Configuration

Step 1: Create MultiversX Wallet Credentials

1. Go to Settings → Credentials → Create New Credential
2. Search for MultiversX Wallet and select it
3. Configure your wallet:

Environment: Choose your network

• Mainnet: https://api.multiversx.com
• Testnet: https://testnet-api.multiversx.com
• Devnet: https://devnet-api.multiversx.com

Wallet Setup: Provide either

• PEM File Content: Full PEM format with headers
• Private Key Hex: 64-character hex string

4. Test the connection and Save

Step 2: Add to AI Agent Workflow

1. Create new workflow with Chat Trigger
2. Add AI Agent node
3. The MultiversX tool will appear automatically in available tools
4. Configure your AI model and memory as needed

🔧 Usage Examples

Smart Contract Operations

Token Transfer

{
	"operation": "smartContract",
	"contractAction": "callFunction",
	"contractAddress": "erd1qqqqqqqqqqqqqpgq...",
	"functionInputMethod": "ai",
	"functionNameDirect": "transfer",
	"functionArgsDirect": {
		"args": [
			{
				"name": "recipient",
				"value": "erd1spyavw0956vq68xj8y4tenjpq2wd5a9p2c6j8gsz7ztyrnpxrruqzu47vn",
				"type": "address"
			},
			{
				"name": "amount",
				"value": "1000000000000000000",
				"type": "bignumber"
			}
		]
	},
	"gasLimit": 5000000,
	"value": "0"
}

Query Contract Data

{
	"operation": "smartContract",
	"contractAction": "queryFunction",
	"contractAddress": "erd1qqqqqqqqqqqqqpgq...",
	"functionInputMethod": "ai",
	"functionNameDirect": "getBalance",
	"functionArgsDirect": {
		"args": [
			{
				"name": "address",
				"value": "erd1spyavw0956vq68xj8y4tenjpq2wd5a9p2c6j8gsz7ztyrnpxrruqzu47vn",
				"type": "address"
			}
		]
	}
}

API Queries

Check Account Balance

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

Get Transaction Details

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

🎯 AI Agent Best Practices

1. Always Use the Tool

❌ "You can check your balance by going to the explorer..."
✅ "Let me check your balance now using the MultiversX tool."

2. Ask for Required Information

✅ "I need your wallet address to check the balance."
✅ "Please provide the contract ABI for this operation."

3. Explain Actions

✅ "I'm now calling the 'transfer' function on your contract..."
✅ "Querying the network for your transaction status..."

4. Handle Results Properly

✅ "Transaction successful! Hash: abc123..."
✅ "Your balance is 15.5 EGLD"

🔍 Function Argument Types

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

🛠️ Troubleshooting

AI Not Using Tool

1. Check system prompt - Make sure it emphasizes tool usage
2. Verify tool description - Should be clear about capabilities
3. Test with direct commands - "Use MultiversX tool to check balance"

Common Errors

• "Invalid address" → Check address format (must start with erd1)
• "ABI required" → Provide contract ABI for smart contract operations
• "Insufficient gas" → Increase gas limit

Gas Limit Guidelines

• Simple queries: No gas needed
• Token transfers: 1,000,000 - 2,000,000
• Complex contracts: 5,000,000 - 10,000,000

🌐 Supported Networks

| Network | URL | Chain ID | | ------- | ------------------------------------ | -------- | | Mainnet | https://api.multiversx.com | 1 | | Testnet | https://testnet-api.multiversx.com | T | | Devnet | https://devnet-api.multiversx.com | D |

📋 Requirements

• n8n version 0.198.0+
• Node.js 16.x+
• Valid MultiversX wallet
• Internet connection

🤝 Support

For issues or questions:

1. Check MultiversX documentation
2. Test on Devnet first
3. Verify ABI format for smart contracts
4. Check network connectivity

Ready to build with MultiversX! 🚀