@near-agent/elizaos-plugin-near NPM

@elizaos/plugin-near

NEAR Protocol integration plugin for Eliza OS that enables token management, transfers, and swaps using Ref Finance.

Overview

This plugin aims to be the basis of all interactions with the NEAR ecosystem, providing seamless integration with NEAR Protocol and Ref Finance DEX.

Features

NEAR token transfers
Token swaps via Ref Finance
Multiple network support (mainnet, testnet)
Secure transaction signing
Automatic storage deposit handling
Real-time price feeds
Portfolio tracking and management
Smart routing for optimal swaps
Built-in denomination handling
Comprehensive error handling

Installation

pnpm install @elizaos/plugin-near

Configuration

The plugin requires environment variables or runtime settings:

NEAR_WALLET_SECRET_KEY=your-wallet-private-key
NEAR_WALLET_PUBLIC_KEY=your-wallet-public-key
NEAR_ADDRESS=your-account.near
NEAR_NETWORK=testnet  # mainnet or testnet
NEAR_RPC_URL=https://neart.lava.build
NEAR_SLIPPAGE=0.01  # 1% slippage tolerance

Usage

Token Transfer

import { nearPlugin } from "@elizaos/plugin-near";

// Send NEAR
const result = await eliza.execute({
    action: "SEND_NEAR",
    content: {
        recipient: "bob.near",
        amount: "1.5",
    },
});

Token Swap

const result = await eliza.execute({
    action: "EXECUTE_SWAP_NEAR",
    content: {
        inputTokenId: "wrap.near",
        outputTokenId: "token.v2.ref-finance.near",
        amount: "10",
    },
});

API Reference

Actions

`SEND_NEAR`

Transfers NEAR tokens to another account.

{
  action: 'SEND_NEAR',
  content: {
    recipient: string,    // Recipient's NEAR account (e.g., "bob.near")
    amount: string,       // Amount to send (in NEAR)
    tokenAddress?: string // Optional: for NEP-141 tokens
  }
}

`EXECUTE_SWAP_NEAR`

Executes a token swap using Ref Finance.

{
  action: 'EXECUTE_SWAP_NEAR',
  content: {
    inputTokenId: string,  // Input token contract (e.g., "wrap.near")
    outputTokenId: string, // Output token contract
    amount: string,        // Amount to swap
    slippageTolerance?: number // Optional: default from config
  }
}

Providers

Wallet Provider

Provides wallet information and portfolio tracking.

const walletInfo = await eliza.getProvider("wallet");
// Returns formatted portfolio including:
// - Account balance
// - Token balances
// - USD values
// - Market prices

Troubleshooting

Common Issues

Transaction Failures
- Check account balance
- Verify storage deposits
- Ensure sufficient gas
- Confirm slippage tolerance
Connection Problems
- Verify RPC endpoint
- Check network selection
- Ensure valid credentials
- Monitor API rate limits
Swap Issues
- Verify token pairs exist
- Check liquidity pools
- Confirm price impact
- Monitor slippage settings

Security Best Practices

Key Management
- Store private keys securely
- Use environment variables
- Implement key rotation
- Monitor account activity
Transaction Safety
- Validate all inputs
- Implement amount limits
- Double-check recipients
- Monitor transaction status
Network Security
- Use secure RPC endpoints
- Implement retry mechanisms
- Monitor for suspicious activity
- Keep dependencies updated
Error Handling
- Log all transaction attempts
- Handle timeouts gracefully
- Validate all user inputs
- Provide clear error messages