@monad-agent-kit/core

Core SDK for building AI agents that interact with the Monad blockchain.

Installation

bun add @monad-agent-kit/core
# or
npm install @monad-agent-kit/core

Quick Start

import { MonadAgentKit } from "@monad-agent-kit/core"

const agent = new MonadAgentKit({
  privateKey: "0x...",
  chainId: 10143, // Monad Testnet
})

// Execute a built-in action
const result = await agent.execute("readContract", {
  address: "0x...",
  abi: [{ type: "function", name: "balanceOf", inputs: [{ type: "address" }], outputs: [{ type: "uint256" }], stateMutability: "view" }],
  functionName: "balanceOf",
  args: ["0x..."],
})

Wallet Providers

The SDK supports three wallet sources:

// 1. Private key (sync)
const agent = new MonadAgentKit({ privateKey: "0x..." })

// 2. Pre-configured viem Account (sync)
import { privateKeyToAccount } from "viem/accounts"
const account = privateKeyToAccount("0x...")
const agent = new MonadAgentKit({ account })

// 3. EIP-1193 provider like MetaMask, WalletConnect, Privy (async)
const agent = await MonadAgentKit.create({ provider: window.ethereum })

Plugin System

Register plugins to extend the agent with domain-specific actions:

import { tokenPlugin } from "@monad-agent-kit/plugin-token"
import { defiPlugin } from "@monad-agent-kit/plugin-defi"

await agent.use(tokenPlugin)
await agent.use(defiPlugin)

// All plugin actions are now available via agent.execute()
await agent.execute("transfer", { to: "0x...", amount: "1.0" })
await agent.execute("swap", { tokenIn: "0x...", tokenOut: "0x...", amountIn: "1.0" })

Built-in Actions

These are auto-registered — no plugin needed:

| Action | Description | |--------|-------------| | readContract | Call any read-only contract function | | writeContract | Execute any state-changing contract function | | subscribeEvents | Subscribe to on-chain events by address/signature | | getEventLog | Retrieve captured events from a subscription | | unsubscribeEvents | Stop watching and remove a subscription |

Name Resolution

Built-in resolvers for ENS (.eth) and Mon Name Service (.mon):

import { MonadAgentKit, CompositeNameResolver, MnsNameResolver, EnsNameResolver } from "@monad-agent-kit/core"

const agent = new MonadAgentKit({
  privateKey: "0x...",
  nameResolver: new CompositeNameResolver([
    new MnsNameResolver(publicClient),
    new EnsNameResolver(),
  ]),
})

// Names are resolved automatically in actions that accept addresses
await agent.execute("transfer", { to: "alice.mon", amount: "1.0" })

Safety Rails

Constrain agent behavior with spending limits, action scoping, and approval gates:

const agent = new MonadAgentKit({
  privateKey: "0x...",
  safety: {
    allowedActions: ["transfer", "getBalance", "getQuote"],
    spendingLimits: {
      perAction: "10",  // max 10 MON per action
      daily: "100",     // max 100 MON per day
    },
    addressWhitelist: ["0xabc...", "0xdef..."],
    approvalHandler: async (request) => {
      // Custom approval logic (e.g., human-in-the-loop)
      return confirm(`Approve ${request.action}?`)
    },
  },
})

Transaction Logging

Every action execution is automatically logged:

// Access the tx log
const entries = await agent.txLog.query({ action: "transfer", limit: 10 })
const stats = await agent.txLog.count()

// Use a custom store (default: InMemoryTxLogStore)
import { InMemoryTxLogStore } from "@monad-agent-kit/core"
const agent = new MonadAgentKit({
  privateKey: "0x...",
  txLog: new InMemoryTxLogStore({ maxEntries: 5000 }),
})

Event Monitoring

Subscribe to on-chain events with polling-based monitoring:

const agent = new MonadAgentKit({
  privateKey: "0x...",
  events: { pollingInterval: 2000, maxEventsPerSubscription: 1000 },
})

const result = await agent.execute("subscribeEvents", {
  address: "0x...",
  event: "Transfer(address,address,uint256)",
})

// Later, retrieve captured events
const events = await agent.execute("getEventLog", {
  subscriptionId: result.data.subscriptionId,
})

// Clean up
agent.destroy()

Utilities

import {
  normalizeAddress,
  getTokenDecimals,
  isNativeToken,
  getExplorerTxUrl,
  resolveNameOrAddress,
  MAINNET_CHAIN_ID,
  TESTNET_CHAIN_ID,
  NATIVE_TOKEN_ADDRESS,
} from "@monad-agent-kit/core"

Networks

| Network | Chain ID | Constant | |---------|----------|----------| | Mainnet | 143 | MAINNET_CHAIN_ID | | Testnet | 10143 | TESTNET_CHAIN_ID |

Creating Custom Actions

import { defineAction, successResult, errorResult } from "@monad-agent-kit/core"

const myAction = defineAction({
  name: "myAction",
  description: "Does something useful",
  category: "custom",
  parameters: {
    type: "object",
    properties: {
      param: { type: "string", description: "A parameter" },
    },
    required: ["param"],
  },
  async execute(params, context) {
    // context.publicClient - read operations
    // context.wallet - write operations
    // context.agent - agent info
    return successResult({ result: "done" })
  },
})

agent.registerAction(myAction)

Creating Custom Plugins

import { definePlugin } from "@monad-agent-kit/core"

const myPlugin = definePlugin({
  name: "my-plugin",
  actions: [actionA, actionB],
  async initialize(agent) {
    // Optional setup logic
  },
})

await agent.use(myPlugin)

License

MIT