{"_id":"@bonzofinancelabs/hak-bonzo-plugin","_rev":"2-096388d0adc2a1cb579b90c758f17f62","name":"@bonzofinancelabs/hak-bonzo-plugin","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@bonzofinancelabs/hak-bonzo-plugin","version":"1.0.0","keywords":["bonzo","bonzo-finance","aave","lending","defi","hedera","agent-kit","plugin"],"author":{"name":"Bonzo Finance Labs"},"license":"MIT","_id":"@bonzofinancelabs/hak-bonzo-plugin@1.0.0","maintainers":[{"name":"gaurangtorvekar","email":"gaurangtorvekar@gmail.com"}],"homepage":"https://github.com/Bonzo-Labs/bonzoPlugin#readme","bugs":{"url":"https://github.com/Bonzo-Labs/bonzoPlugin/issues"},"dist":{"shasum":"d562b176ab8eed25878c7a7f22b221677144e97f","tarball":"https://registry.npmjs.org/@bonzofinancelabs/hak-bonzo-plugin/-/hak-bonzo-plugin-1.0.0.tgz","fileCount":10,"integrity":"sha512-0dRpM9p3Toi2TN6A0xHCZcCNQjkj1JXnpSNAhmPqJmhMALpDliHf7kRA6ZmfqfIOBKufgCH22ftcBQDtsDRmYw==","signatures":[{"sig":"MEUCIGmbdtOjg3BctPX5zaI3MRK2jFARPkDVQ3kzV0TpOedxAiEAuIrcqAQSTjGGXm60ghiG1+l2RzUor+hH5eil1L6NV/c=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":278429},"main":"./dist/plugin.cjs","type":"module","types":"./dist/plugin.d.ts","module":"./dist/plugin.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/plugin.d.ts","import":"./dist/plugin.js","require":"./dist/plugin.cjs"}},"gitHead":"aba897034ca3a7cd9a70893e535a7b074eaf0d18","private":false,"scripts":{"test":"echo \"Error: no test specified\" && exit 1","build":"tsup","start":"bun run src/index.ts"},"_npmUser":{"name":"gaurangtorvekar","email":"gaurangtorvekar@gmail.com"},"repository":{"url":"git+https://github.com/Bonzo-Labs/bonzoPlugin.git","type":"git"},"_npmVersion":"10.9.2","description":"The official Hedera Agent Kit plugin for Bonzo Finance - Aave v2-compatible lending protocol on Hedera","directories":{},"_nodeVersion":"22.17.1","dependencies":{"zod":"^3.25.76","bignumber.js":"^9.3.1","@ethersproject/abi":"^5.8.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","dotenv":"^16.4.5","prompts":"^2.4.2","langchain":"^0.3.30","@types/bun":"latest","typescript":"^5","@types/prompts":"^2.4.9","@langchain/openai":"^0.6.3"},"peerDependencies":{"@hashgraph/sdk":"^2.74.0","hedera-agent-kit":"^3.4.0"},"peerDependenciesMeta":{"@hashgraph/sdk":{"optional":false},"hedera-agent-kit":{"optional":false}},"_npmOperationalInternal":{"tmp":"tmp/hak-bonzo-plugin_1.0.0_1761903969186_0.32454824481671785","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@bonzofinancelabs/hak-bonzo-plugin","version":"1.0.1","description":"The official Hedera Agent Kit plugin for Bonzo Finance - Aave v2-compatible lending protocol on Hedera. ⚠️ USE AT YOUR OWN RISK - Always test on testnet first. Bonzo Finance Labs is NOT responsible for any losses.","private":false,"type":"module","main":"./dist/plugin.cjs","module":"./dist/plugin.js","types":"./dist/plugin.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/plugin.d.ts","require":"./dist/plugin.cjs","import":"./dist/plugin.js"}},"repository":{"type":"git","url":"git+https://github.com/Bonzo-Labs/bonzoPlugin.git"},"bugs":{"url":"https://github.com/Bonzo-Labs/bonzoPlugin/issues"},"keywords":["bonzo","bonzo-finance","aave","lending","defi","hedera","agent-kit","plugin"],"author":{"name":"Bonzo Finance Labs"},"license":"MIT","scripts":{"build":"tsup","start":"bun run src/index.ts","test":"echo \"Error: no test specified\" && exit 1"},"dependencies":{"@ethersproject/abi":"^5.8.0","bignumber.js":"^9.3.1","zod":"^3.25.76"},"devDependencies":{"@langchain/openai":"^0.6.3","@types/bun":"latest","@types/prompts":"^2.4.9","dotenv":"^16.4.5","langchain":"^0.3.30","prompts":"^2.4.2","tsup":"^8.5.0","typescript":"^5"},"peerDependencies":{"@hashgraph/sdk":"^2.74.0","hedera-agent-kit":"^3.4.0"},"peerDependenciesMeta":{"@hashgraph/sdk":{"optional":false},"hedera-agent-kit":{"optional":false}},"_id":"@bonzofinancelabs/hak-bonzo-plugin@1.0.1","gitHead":"fc3e9e822bbab454cbeaa9dea51a4ad11f011aa9","homepage":"https://github.com/Bonzo-Labs/bonzoPlugin#readme","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-CNoth/yUFrAUvV12UFkY/Db25sacq72AbgiBB5FFW8TqV4PzeNJjvKJfl9//eqDk9jhyt8LmqzAUCWAHDE9xcw==","shasum":"3e9b6a7cf715676d015e4b917108bad4bd0a980d","tarball":"https://registry.npmjs.org/@bonzofinancelabs/hak-bonzo-plugin/-/hak-bonzo-plugin-1.0.1.tgz","fileCount":10,"unpackedSize":279342,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBK76UkCfT4x6UHQGbSRZtuVKE2XjE8dtBUda8k5bNYIAiAH6NLfOCaxG4C7bu3DDuJO5b5yBu8Z1WS0CdnhPrf7rA=="}]},"_npmUser":{"name":"gaurangtorvekar","email":"gaurangtorvekar@gmail.com"},"directories":{},"maintainers":[{"name":"gaurangtorvekar","email":"gaurangtorvekar@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/hak-bonzo-plugin_1.0.1_1762071836527_0.34070755801404573"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-31T09:46:09.037Z","modified":"2025-11-02T08:23:56.989Z","1.0.0":"2025-10-31T09:46:09.403Z","1.0.1":"2025-11-02T08:23:56.760Z"},"bugs":{"url":"https://github.com/Bonzo-Labs/bonzoPlugin/issues"},"author":{"name":"Bonzo Finance Labs"},"license":"MIT","homepage":"https://github.com/Bonzo-Labs/bonzoPlugin#readme","keywords":["bonzo","bonzo-finance","aave","lending","defi","hedera","agent-kit","plugin"],"repository":{"type":"git","url":"git+https://github.com/Bonzo-Labs/bonzoPlugin.git"},"description":"The official Hedera Agent Kit plugin for Bonzo Finance - Aave v2-compatible lending protocol on Hedera. ⚠️ USE AT YOUR OWN RISK - Always test on testnet first. Bonzo Finance Labs is NOT responsible for any losses.","maintainers":[{"name":"gaurangtorvekar","email":"gaurangtorvekar@gmail.com"}],"readme":"# Hedera Agent Kit - Bonzo Plugin\n\nA plugin for [Hedera Agent Kit](https://github.com/hashgraph/hedera-agent-kit) that provides seamless integration with [Bonzo Finance](https://bonzo.finance), an Aave v2–compatible lending protocol on the Hedera network.\n\n---\n\n## ⚠️ **IMPORTANT DISCLAIMER**\n\n**Bonzo Finance Labs is NOT responsible for any loss incurred by using this SDK plugin. This software is provided \"as is\" without warranty of any kind.**\n\n**⚠️ USE AT YOUR OWN RISK ⚠️**\n\n- **Do Your Own Research (DYOR)** before using this plugin\n- **Always test on testnet first** before using on mainnet\n- This plugin interacts with smart contracts and financial protocols\n- Cryptocurrency transactions are irreversible\n- Always verify contract addresses and parameters before executing transactions\n- The authors and maintainers assume no liability for any losses, damages, or consequences arising from the use of this software\n\nBy using this plugin, you acknowledge that you understand the risks and agree to use it at your own discretion.\n\n---\n\n## Overview\n\nThe Bonzo plugin enables AI agents to interact with the Bonzo lending protocol, providing comprehensive functionality for:\n\n- **Market Data**: Fetch real-time market information (tokens, APYs, liquidity, utilization)\n- **Approve**: Approve ERC20 tokens for Bonzo operations\n- **Deposit**: Supply tokens to the lending pool\n- **Withdraw**: Withdraw supplied tokens from the lending pool\n- **Borrow**: Borrow tokens from the lending pool (stable or variable rate)\n- **Repay**: Repay borrowed tokens\n\n## Installation\n\n```bash\nnpm install @bonzofinancelabs/hak-bonzo-plugin\n```\n\n## Quick Start\n\n```typescript\nimport { HederaLangchainToolkit, AgentMode } from \"hedera-agent-kit\";\nimport { bonzoPlugin } from \"@bonzofinancelabs/hak-bonzo-plugin\";\nimport { Client } from \"@hashgraph/sdk\";\n\nconst client = Client.forTestnet(); // or Client.forMainnet()\n\nconst toolkit = new HederaLangchainToolkit({\n  client,\n  configuration: {\n    context: { mode: AgentMode.AUTONOMOUS },\n    plugins: [bonzoPlugin],\n    tools: [],\n  },\n});\n\nconst tools = toolkit.getTools();\n```\n\n### CLI Usage\n\nIf you want to run the CLI example included in this repository:\n\n```bash\n# Clone the repository\ngit clone https://github.com/Bonzo-Labs/bonzoPlugin\ncd bonzoPlugin\n\n# Install dependencies\nbun install\n\n# Run CLI (testnet by default)\nbun run src/index.ts\n\n# Or specify network and operator\nHEDERA_NETWORK=mainnet ACCOUNT_ID=0.0.x PRIVATE_KEY=0x... bun run src/index.ts\n\n# Or use npm scripts (if npm is installed)\nnpm run start\n```\n\n## Tools\n\n### 1. Market Data Tool\n\nFetches real-time market data including supported tokens, supply/borrow APYs, liquidity, and utilization rates.\n\n- **Method**: `bonzo_market_data_tool`\n- **Parameters**: None\n- **Returns**: Human-readable summary of all Bonzo markets\n\n**Example usage**: \"What are the current APYs for tokens on Bonzo?\"\n\n---\n\n### 2. Approve ERC20 Tool\n\nApproves the Bonzo LendingPool (or a custom spender) to spend a given ERC20 token.\n\n- **Method**: `approve_erc20_tool`\n\n**Required Parameters:**\n\n- `tokenSymbol`: Token symbol (e.g., \"USDC\", \"HBAR\")\n- `amount`: Amount to approve (human-readable number or string)\n\n**Optional Parameters:**\n\n- `spender`: EVM address of spender (defaults to LendingPool address)\n- `useMax`: If `true`, approves maximum amount (`type(uint256).max`)\n\n**Example usage**: \"Approve 1000 USDC for Bonzo\"\n\n---\n\n### 3. Deposit Tool\n\nSupplies tokens to the Bonzo lending pool. Users earn supply APY on deposited tokens.\n\n- **Method**: `bonzo_deposit_tool`\n\n**Required Parameters:**\n\n- `tokenSymbol`: Token symbol to deposit\n- `amount`: Amount to deposit (human-readable number or string)\n\n**Optional Parameters:**\n\n- `onBehalfOf`: Hedera account ID to deposit on behalf of (defaults to caller's account)\n- `referralCode`: Referral code (default: 0)\n\n> 💡 **Note**: You must approve the token before depositing. Use `approve_erc20_tool` first.\n\n**Example usage**: \"Deposit 1000 USDC to Bonzo\"\n\n---\n\n### 4. Withdraw Tool\n\nWithdraws previously supplied tokens from the Bonzo lending pool.\n\n- **Method**: `bonzo_withdraw_tool`\n\n**Required Parameters:**\n\n- `tokenSymbol`: Token symbol to withdraw\n- `amount`: Amount to withdraw (human-readable number or string)\n\n**Optional Parameters:**\n\n- `to`: Hedera account ID to withdraw to (defaults to caller's account)\n- `withdrawAll`: If `true`, withdraws all available balance\n\n**Example usage**: \"Withdraw 500 USDC from Bonzo\"\n\n---\n\n### 5. Borrow Tool\n\nBorrows tokens from the Bonzo lending pool at either stable or variable interest rates.\n\n- **Method**: `bonzo_borrow_tool`\n\n**Required Parameters:**\n\n- `tokenSymbol`: Token symbol to borrow\n- `amount`: Amount to borrow (human-readable number or string)\n- `rateMode`: Interest rate mode - `\"stable\"` or `\"variable\"`\n\n**Optional Parameters:**\n\n- `onBehalfOf`: Hedera account ID to borrow on behalf of (defaults to caller's account)\n- `referralCode`: Referral code (default: 0)\n\n> 💡 **Note**: You must have sufficient collateral deposited before borrowing.\n\n**Example usage**: \"Borrow 100 USDC at variable rate from Bonzo\"\n\n---\n\n### 6. Repay Tool\n\nRepays borrowed tokens to the Bonzo lending pool.\n\n- **Method**: `bonzo_repay_tool`\n\n**Required Parameters:**\n\n- `tokenSymbol`: Token symbol to repay\n- `amount`: Amount to repay (human-readable number or string)\n- `rateMode`: Interest rate mode - `\"stable\"` or `\"variable\"` (must match the original borrow)\n\n**Optional Parameters:**\n\n- `onBehalfOf`: Hedera account ID to repay on behalf of (defaults to caller's account)\n- `repayAll`: If `true`, repays the entire borrowed amount\n\n> 💡 **Note**: You must approve the underlying token before repaying. Use `approve_erc20_tool` first.\n\n**Example usage**: \"Repay 50 USDC variable rate debt on Bonzo\"\n\n## Address Resolution\n\nAll contract addresses are sourced from `bonzo-contracts.json` included with the plugin. The plugin automatically resolves addresses based on the network:\n\n- **Networks**: `hedera_mainnet` and `hedera_testnet` sections\n- **Per-token addresses**: `token` (underlying ERC20), `aToken`, `stableDebt`, `variableDebt`\n- **Core contracts**: `LendingPool`, `LendingPoolAddressesProvider`, oracles, helpers\n- **Network detection**: Automatically determined via the Hedera client (`client.ledgerId`)\n\n## Network Selection\n\nThe plugin supports both Hedera Testnet and Mainnet. The network is determined by the Hashgraph SDK client configuration:\n\n```typescript\n// For testnet\nconst client = Client.forTestnet();\n\n// For mainnet\nconst client = Client.forMainnet();\n```\n\nWhen using the CLI, set the `HEDERA_NETWORK` environment variable:\n\n```bash\nHEDERA_NETWORK=mainnet ACCOUNT_ID=0.0.x PRIVATE_KEY=0x... npm run start\n```\n\n## AgentMode Support\n\nThe plugin supports both agent execution modes:\n\n- **`AUTONOMOUS`**: Transactions are executed on-chain and return receipt/transactionId\n- **`RETURN_BYTES`**: Transactions are frozen and return hex-encoded bytes for external signing\n\nConfigure via the Hedera Agent Kit context:\n\n```typescript\nimport { AgentMode } from \"hedera-agent-kit\";\n\nconst toolkit = new HederaLangchainToolkit({\n  client,\n  configuration: {\n    context: { mode: AgentMode.AUTONOMOUS }, // or AgentMode.RETURN_BYTES\n    plugins: [bonzoPlugin],\n  },\n});\n```\n\n## Transaction Execution\n\n- **ABI Encoding**: Uses `@ethersproject/abi` Interfaces (Aave v2 function signatures)\n- **Transaction Building**: Hashgraph SDK `ContractExecuteTransaction`\n- **Gas & Fees**: Configured with sensible defaults (customizable per tool)\n\n## Usage Examples\n\n### Approve and Deposit\n\n```typescript\nimport { bonzoPlugin, bonzoPluginToolNames } from \"@bonzofinancelabs/hak-bonzo-plugin\";\n\n// In your agent context, the tools are automatically available\n// The agent can call:\n// 1. \"Approve 1000 USDC for Bonzo\"\n// 2. \"Deposit 1000 USDC to Bonzo\"\n```\n\n### Borrow and Repay\n\n```typescript\n// Agent can execute:\n// 1. \"Borrow 100 USDC at variable rate from Bonzo\"\n// 2. \"Repay 50 USDC variable rate debt on Bonzo\"\n```\n\n### Withdraw\n\n```typescript\n// Agent can execute:\n// \"Withdraw 500 USDC from Bonzo\"\n```\n\n### Complete Workflow Example\n\n```typescript\nimport { HederaLangchainToolkit, AgentMode } from \"hedera-agent-kit\";\nimport { bonzoPlugin } from \"@bonzofinancelabs/hak-bonzo-plugin\";\nimport { Client, PrivateKey } from \"@hashgraph/sdk\";\n\nconst client = Client.forTestnet();\nclient.setOperator(\"0.0.xxxxx\", PrivateKey.fromStringECDSA(\"0x...\"));\n\nconst toolkit = new HederaLangchainToolkit({\n  client,\n  configuration: {\n    context: { mode: AgentMode.AUTONOMOUS },\n    plugins: [bonzoPlugin],\n  },\n});\n\nconst tools = toolkit.getTools();\n// Tools are now available for the agent to use\n```\n\n## Development\n\n### Repository Structure\n\n```\nbonzoPlugin/\n├── src/\n│   ├── plugin.ts                    # Plugin definition and exports\n│   ├── index.ts                     # CLI entry point\n│   ├── client.ts                    # LangChain agent factory\n│   ├── tools.ts                     # Market data tool\n│   ├── bonzo/\n│   │   ├── bonzo-market-service.ts  # Market API service\n│   │   ├── bonzo.zod.ts            # Zod parameter schemas\n│   │   └── utils.ts                # Shared utilities\n│   └── tools/\n│       ├── approve-erc20.ts        # Approve tool\n│       ├── deposit.ts              # Deposit tool\n│       ├── withdraw.ts             # Withdraw tool\n│       ├── borrow.ts               # Borrow tool\n│       └── repay.ts                # Repay tool\n├── bonzo-contracts.json            # Contract addresses by network\n└── package.json\n```\n\n### Environment Variables\n\n**Required for CLI:**\n\n- `OPENAI_API_KEY`: OpenAI API key for the agent LLM\n\n**Required for Autonomous Mode:**\n\n- `ACCOUNT_ID` or `HEDERA_ACCOUNT_ID`: Hedera account ID\n- `PRIVATE_KEY` or `HEDERA_PRIVATE_KEY`: ECDSA private key (0x... format)\n\n**Optional:**\n\n- `HEDERA_NETWORK`: Network selection (`testnet` | `mainnet`, default: `testnet`)\n- `HAK_MODE` or `AGENT_MODE`: Agent mode (`autonomous` | `return_bytes`, default: `return_bytes`)\n\n### Security Notes\n\n- Never commit secrets or `.env` files\n- Use environment variables or secure credential management\n- Testnet is recommended for development and testing\n\n## Important Notes\n\n### Token Association\n\nSome assets may require token association on Hedera before executing actions. Ensure your Hedera account has associated the token or has auto-association enabled.\n\n### Approvals Required\n\n- **Deposit**: Requires approval of the underlying token before depositing\n- **Repay**: Requires approval of the underlying token before repaying\n\n### Network Differences\n\n- Testnet has fewer markets than mainnet\n- Tools will provide clear error messages with available symbols if a token isn't configured on the selected network\n\n### HBAR Handling\n\nFor HBAR-native flows, wrapping/unwrapping may be needed via gateway contracts depending on Bonzo's implementation.\n\n## Tool Names Reference\n\nFor programmatic access to tool names:\n\n```typescript\nimport { bonzoPluginToolNames } from \"@bonzofinancelabs/hak-bonzo-plugin\";\n\nconsole.log(bonzoPluginToolNames.BONZO_MARKET_DATA_TOOL);\nconsole.log(bonzoPluginToolNames.APPROVE_ERC20_TOOL);\nconsole.log(bonzoPluginToolNames.BONZO_DEPOSIT_TOOL);\nconsole.log(bonzoPluginToolNames.BONZO_WITHDRAW_TOOL);\nconsole.log(bonzoPluginToolNames.BONZO_BORROW_TOOL);\nconsole.log(bonzoPluginToolNames.BONZO_REPAY_TOOL);\n```\n\n## Related Documentation\n\n- [Aave v2 Developer Docs](https://docs.aave.com/developers/) - ABI references and function signatures\n- [Hedera Agent Kit Documentation](https://github.com/hashgraph/hedera-agent-kit) - Plugin and tool development guide\n- [Bonzo Finance](https://bonzo.finance) - Protocol website and documentation\n\n## License\n\nMIT\n\n---\n\nMade with ❤️ by [Bonzo Finance Labs](https://bonzo.finance/)\n","readmeFilename":"README.md"}