@radiustechsystems/ai-agent-plugin-erc20 NPM

Radius AI Agent Toolkit - ERC20 Plugin

This plugin enables AI agents to interact with ERC20 tokens on Radius, allowing them to check balances, transfer tokens, and manage token approvals.

This package is part of the Radius AI Agent Toolkit, which provides tools for integrating AI agents with the Radius platform.

Installation

# Install this specific package
npm install @radiustechsystems/ai-agent-plugin-erc20

# Required peer dependencies
npm install @radiustechsystems/ai-agent-core
npm install @radiustechsystems/ai-agent-wallet

Prerequisites

Node.js >=20.12.2 <23
Radius wallet setup with a funded account

Usage

import { erc20, USDC } from "@radiustechsystems/ai-agent-plugin-erc20";
import { createRadiusWallet } from "@radiustechsystems/ai-agent-wallet";
import { getOnChainTools } from "@radiustechsystems/ai-agent-adapter-vercel-ai";

// Create a Radius wallet
const wallet = await createRadiusWallet({
  rpcUrl: process.env.RPC_PROVIDER_URL,
  privateKey: process.env.WALLET_PRIVATE_KEY
});

// Initialize the ERC20 plugin with predefined tokens
const erc20Plugin = erc20({
  tokens: [USDC]
});

// Create AI agent tools with the ERC20 plugin
const tools = await getOnChainTools({
  wallet,
  plugins: [erc20Plugin]
});

Adding Custom Tokens

You can add your own custom tokens by defining their details:

import { erc20, USDC } from "@radiustechsystems/ai-agent-plugin-erc20";

// Create an ERC20 plugin with both predefined and custom tokens
const erc20Plugin = erc20({
  tokens: [
    USDC, // Predefined token
    {
      // Custom token definition
      decimals: 18,
      symbol: "RADUSD",
      name: "Radius Token",
      chains: {
        "1223953": { // Radius testnet chain ID
          contractAddress: "0x9aeEa4f3025940dBdbf6863C7e16a23Ea95272a4"
        }
      }
    }
  ]
});

API Reference

`erc20(options)`

Creates a new ERC20 plugin instance.

Parameters:

options.tokens (Token[]): Array of token definitions to enable

Returns:

An ERC20Plugin instance that can be used with AI agent frameworks

Predefined Tokens

The package includes these predefined tokens:

USDC: USD Coin stablecoin
RADUSD: Radius Token

Provided Tools

The ERC20 plugin provides the following AI agent tools:

`get_token_info_by_symbol`

Gets information about a token by its symbol.

Parameters:

symbol (string): The token symbol to lookup

Example:

try {
  const tokenInfo = await getTokenInfoBySymbolTool.execute({ 
    symbol: "USDC" 
  });
  console.log("Token info:", tokenInfo);
  // { symbol: "USDC", name: "USD Coin", decimals: 6, address: "0x..." }
} catch (error) {
  console.error(`Token info lookup failed: ${error.message}`);
}

`get_token_balance`

Gets the balance of a specific token for an address.

Parameters:

tokenAddress (string): The token contract address
wallet (string, optional): The wallet address to check (defaults to connected wallet)

Example:

try {
  const balance = await getTokenBalanceTool.execute({
    tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
    wallet: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
  });
  console.log(`Balance: ${balance.formatted} ${balance.symbol}`);
} catch (error) {
  console.error(`Balance check failed: ${error.message}`);
}

`transfer`

Transfers tokens from the wallet to another address.

Parameters:

tokenAddress (string): The token contract address
to (string): The recipient address
amount (string): The amount to transfer
formatAmount (boolean, optional): Whether the amount is in decimal format (default: false)

`get_token_allowance`

Gets the current allowance for a spender.

Parameters:

tokenAddress (string): The token contract address
spender (string): The spender address
owner (string, optional): The token owner (defaults to connected wallet)

`approve`

Approves a spender to use a specific amount of tokens.

Parameters:

tokenAddress (string): The token contract address
spender (string): The spender address
amount (string): The amount to approve
formatAmount (boolean, optional): Whether the amount is in decimal format (default: false)

`convert_to_base_unit`

Converts a human-readable token amount to its base unit.

Parameters:

amount (string): The decimal amount (e.g., "10.5")
decimals (number): The token decimals (e.g., 6 for USDC, 18 for most tokens)

Example:

try {
  const baseUnitResult = await convertToBaseUnitTool.execute({
    amount: "100",
    decimals: 6 // USDC has 6 decimals
  });
  console.log(`100 USDC in base units: ${baseUnitResult}`); // 100000000
} catch (error) {
  console.error(`Conversion failed: ${error.message}`);
}

`convert_from_base_unit`

Converts a base unit token amount to its human-readable form.

Parameters:

amount (string): The amount in base units
decimals (number): The token decimals

Example:

try {
  const decimalResult = await convertFromBaseUnitTool.execute({
    amount: "100000000", // 100 USDC in base units
    decimals: 6 // USDC has 6 decimals
  });
  console.log(`100000000 base units in USDC: ${decimalResult}`); // "100"
} catch (error) {
  console.error(`Conversion failed: ${error.message}`);
}

Note on Tool Naming: The tool names in this documentation match the actual names used at runtime. The @Tool decorator in the implementation automatically converts camelCase method names to snake_case for the final tool names.