@monad-agent-kit/core

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

Installation

``bash
bun add @monad-agent-kit/core


or


npm install @monad-agent-kit/core
`

Quick Start

`typescript
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:

`typescript
// 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:

`typescript
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):

`typescript
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:

`typescript
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:

`typescript
// 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:

`typescript
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

`typescript
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

`typescript
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

`typescript
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