npm package: @monad-agent-kit/core
Description: Core package for Monad Agent Kit - AI agent SDK for Monad blockchain
Latest version: 0.1.2

# @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