Get your first Radix AI agent running in 5 minutes. We’ll start with Stokenet (testnet) - it’s free and safe for learning.

1. Install

npm install radix-agent-kit

2. Setup Environment

Create a .env file in your project:

OPENAI_API_KEY=your-openai-api-key
RADIX_MNEMONIC=your-twenty-four-word-mnemonic-phrase

Node.js users: You need to import dotenv/config at the top of your files to load environment variables. This is shown in all code examples below.

Start with Stokenet! Use the testnet for learning. Only switch to mainnet when you’re ready for production.

3. Create Your Agent

Choose your setup: new wallet or existing wallet.

import "dotenv/config"; // Required for Node.js environments
import { RadixAgent, RadixNetwork, RadixMnemonicWallet } from "radix-agent-kit";

// Generate a new 24-word wallet
const wallet = RadixMnemonicWallet.generateRandom({
  networkId: 2 // Stokenet
});

console.log("🔑 Your address:", wallet.getAddress());
console.log("📝 Your mnemonic:", wallet.getMnemonic());

// Create agent with new wallet
const agent = new RadixAgent({
  networkId: RadixNetwork.Stokenet,
  openaiApiKey: process.env.OPENAI_API_KEY,
  wallet: wallet
});

// ⚠️ New wallets start with 0 XRD!
// Use the agent to request funding: see step 4 below

4. Get Testnet XRD

New wallets start empty. Get testnet XRD using your agent:

// Ask your agent to fund your wallet
const result = await agent.run("Fund my wallet with testnet XRD");
console.log(result);

// Check if it worked
await agent.run("What's my XRD balance?");

The agent will automatically:

  • Request XRD from the Stokenet faucet
  • Try multiple funding methods for reliability
  • Show you the funding status and new balance

Option 2: Manual Funding (Backup)

If the agent funding doesn’t work, you can manually request:

  1. Copy your address from step 3
  2. Visit: Stokenet Dashboard
  3. Paste your address and request testnet XRD
  4. Verify: Ask your agent “What’s my balance?”

How much XRD? The agent typically requests 10,000 testnet XRD, which is plenty for learning and testing all features.

5. Test Your Agent

Try these basic commands to verify everything works:

async function testAgent() {
  try {
    // Check balance
    console.log(await agent.run("What's my XRD balance?"));
    
    // Get account info
    console.log(await agent.run("Show my account details"));
    
    // Check current epoch
    console.log(await agent.run("What's the current epoch?"));
    
  } catch (error) {
    console.error("Error:", error.message);
  }
}

testAgent();

6. Basic Operations

Once your wallet has XRD, try these operations:

💰 Account Operations

// Check balances
await agent.run("What's my XRD balance?");
await agent.run("Show all my token balances");

// Account information
await agent.run("Show my account details");

// Request more testnet XRD if needed
await agent.run("Fund my wallet");

🪙 Create Tokens

// Create a fungible token
await agent.run("Create a token called GameCoin with symbol GAME and supply 1000000");

// Create an NFT collection
await agent.run("Create NFT collection called CryptoArt");

💸 Transfer Assets

// Send XRD (replace with a real address)
await agent.run("Send 10 XRD to account_tdx_2_1c8atrq...");

// Send custom tokens
await agent.run("Send 100 GameCoin to account_tdx_2_1c8atrq...");

🥩 Staking

// Stake XRD (replace with a real validator address)
await agent.run("Stake 100 XRD with validator_tdx_2_1sd5368...");

// Check staking status
await agent.run("Show my staking positions");

// Claim rewards
await agent.run("Claim rewards from validator_tdx_2_1sd5368...");

🏊 DeFi Operations (Mainnet Only)

// Create a liquidity pool
await agent.run("Create pool with 1000 XRD and 2000 TOKEN with 0.3% fee");

// Add liquidity to existing pool
await agent.run("Add 500 XRD and 1000 TOKEN to pool component_rdx_...");

// Swap tokens
await agent.run("Swap 100 XRD for TOKEN in pool component_rdx_...");

// Remove liquidity
await agent.run("Remove 50 LP tokens from pool component_rdx_...");

DeFi on Stokenet: Ociswap pools are only available on Mainnet. For Stokenet testing, deploy your own pool blueprint like SimplePool.

7. Configuration Options

Customize your agent with these options:

const agent = new RadixAgent({
  // Required
  networkId: RadixNetwork.Stokenet,
  openaiApiKey: process.env.OPENAI_API_KEY,
  
  // Wallet (choose one)
  mnemonic: process.env.RADIX_MNEMONIC,  // Use existing wallet
  wallet: myWallet,                      // Use wallet instance
  
  // Optional AI settings
  model: "gpt-4",                        // Default: "gpt-4"
  temperature: 0.1,                      // Default: 0.1 (focused)
  useMemory: true,                       // Remember conversation
  maxIterations: 10,                     // Max AI reasoning steps
  
  // Optional app settings
  applicationName: "MyRadixApp",         // For Gateway API
  verbose: true,                         // Debug logging
  skipAutoFunding: false                 // Disable auto-funding
});

8. Direct API Usage

Skip the AI and use blockchain functions directly:

import { 
  RadixGatewayClient, 
  RadixMnemonicWallet,
  RadixTransactionBuilder,
  Token,
  DeFi,
  Component,
  FaucetHelper
} from "radix-agent-kit";

// Setup core components
const gateway = new RadixGatewayClient({ 
  networkId: RadixNetwork.Stokenet 
});

const wallet = RadixMnemonicWallet.fromMnemonic(
  process.env.RADIX_MNEMONIC!, 
  { networkId: 2 } // Stokenet
);

// Fund wallet directly
const faucetHelper = new FaucetHelper();
const fundingResult = await faucetHelper.forceFundWallet(wallet);
console.log("Funding result:", fundingResult);

// Check balance directly
const balances = await gateway.getAccountBalances(wallet.getAddress());
console.log("Balances:", balances);

// Create token directly
const token = new Token(
  new RadixTransactionBuilder({ networkId: RadixNetwork.Stokenet }),
  gateway,
  2
);

const txHash = await token.createFungibleResource({
  name: "MyToken",
  symbol: "MTK", 
  initialSupply: "1000000",
  divisibility: 18
}, wallet, await gateway.getCurrentEpoch());

console.log("Token created:", txHash);

9. Error Handling

Always handle errors in production:

async function safeOperation() {
  try {
    const response = await agent.run("Send 1000000 XRD to invalid_address");
    console.log("✅ Success:", response);
  } catch (error) {
    console.error("❌ Error:", error.message);
    
    // Common errors:
    // - "Insufficient XRD balance"
    // - "Invalid account address format"
    // - "Network timeout - retry"
    // - "Invalid OpenAI API key"
  }
}

10. Next Steps

Common Issues

“Funding request failed”

  • The Stokenet faucet might be busy
  • Try again: await agent.run("Fund my wallet")
  • Use manual funding as backup

“Insufficient funds”

  • Request more XRD: await agent.run("Fund my wallet")
  • Check balance: await agent.run("What's my balance?")

“Invalid address format”

  • Stokenet addresses start with account_tdx_2_
  • Mainnet addresses start with account_rdx_

“OpenAI API error”

  • Check your API key is valid
  • Ensure you have API credits available

“Network timeout”

  • Radix Gateway might be busy
  • Try again after a few seconds

Ready for more? Once comfortable with these basics, explore the full feature set in our Features Guide or dive into Real Examples.