dappily-agent-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dappily
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+# 🦞 Dappily Agent Kit
+
+**Solana Agent Kit-style actions for Hedera — HTS tokens, NFTs, transfers, and more.**
+
+Give any AI agent the ability to interact with the Hedera network. Inspired by [solana-agent-kit](https://github.com/sendaifun/solana-agent-kit).
+
+## Proven on Testnet
+
+Every action has been tested with real transactions on Hedera testnet — not just schema validation, but actual on-chain execution with verified receipts:
+
+| Action | Testnet Proof |
+|--------|---------------|
+| GET_BALANCE | ✅ 999 ℏ queried |
+| HBAR_TRANSFER | ✅ Receipt: SUCCESS |
+| CREATE_TOKEN | ✅ Token `0.0.7932264` created |
+| MINT_TOKEN | ✅ Supply 10000 → 15000 |
+| BURN_TOKEN | ✅ Supply 15000 → 14000 |
+| TRANSFER_TOKEN | ✅ 100 tokens moved |
+| CREATE_NFT_COLLECTION | ✅ Collection `0.0.7932266` created |
+| MINT_NFT | ✅ Serials [1, 2, 3] returned |
+| BURN_NFT | ✅ Serial #3 destroyed |
+
+## Quickstart
+
+```bash
+npm install dappily-agent-kit @hashgraph/sdk
+```
+
+```typescript
+import { HederaAgentKit, getBalanceAction, createTokenAction } from "dappily-agent-kit";
+
+// Initialize with your Hedera credentials
+const agent = new HederaAgentKit(
+  "0.0.YOUR_ACCOUNT",
+  "YOUR_PRIVATE_KEY",
+  "testnet" // or "mainnet"
+);
+
+// Check balance
+const balance = await getBalanceAction.handler(agent, {});
+if (balance.ok) {
+  console.log(balance.data.hbarBalance); // "150.5 ℏ"
+}
+
+// Create a token
+const token = await createTokenAction.handler(agent, {
+  name: "My Token",
+  symbol: "MTK",
+  initialSupply: 1000000,
+  decimals: 2,
+});
+if (token.ok) {
+  console.log(token.data.tokenId); // "0.0.XXXXX"
+}
+```
+
+## Actions
+
+### Core
+
+| Action | Input | Description |
+|--------|-------|-------------|
+| `GET_BALANCE` | `{ accountId?: string }` | Get HBAR + token balances. Defaults to agent's account. |
+| `HBAR_TRANSFER` | `{ to, amount, memo? }` | Send HBAR to another account. |
+
+### Fungible Tokens (HTS)
+
+| Action | Input | Description |
+|--------|-------|-------------|
+| `CREATE_TOKEN` | `{ name, symbol, initialSupply, decimals?, memo? }` | Create a new fungible token. |
+| `ASSOCIATE_TOKEN` | `{ tokenId, accountId?, accountPrivateKey? }` | Associate a token with an account. |
+| `TRANSFER_TOKEN` | `{ tokenId, to, amount, memo? }` | Transfer fungible tokens. Pre-flight association check. |
+| `MINT_TOKEN` | `{ tokenId, amount, supplyPrivateKey? }` | Mint additional supply. |
+| `BURN_TOKEN` | `{ tokenId, amount, supplyPrivateKey? }` | Burn supply (irreversible). |
+
+### NFTs (HTS)
+
+| Action | Input | Description |
+|--------|-------|-------------|
+| `CREATE_NFT_COLLECTION` | `{ name, symbol, maxSupply?, memo? }` | Create an NFT collection. |
+| `MINT_NFT` | `{ tokenId, metadata: string[], supplyPrivateKey? }` | Mint NFTs with base64 metadata. Returns serial numbers. |
+| `TRANSFER_NFT` | `{ tokenId, serial, to, senderPrivateKey? }` | Transfer an NFT. Pre-flight association check. |
+| `BURN_NFT` | `{ tokenId, serial, supplyPrivateKey? }` | Burn an NFT (irreversible). |
+
+## Standardized Output
+
+Every action returns the same shape:
+
+```typescript
+// Success
+{
+  ok: true,
+  summary: "Sent 10 HBAR to 0.0.12345",
+  txId: "0.0.98765@1700000000.000000000",
+  receipt: { status: "SUCCESS" },
+  data: { /* action-specific */ }
+}
+
+// Failure
+{
+  ok: false,
+  error: "INSUFFICIENT_PAYER_BALANCE",
+  details: "The sending account does not have enough HBAR."
+}
+```
+
+Error codes are mapped from Hedera's native codes to human-readable messages. Pre-flight checks (like association verification) prevent wasted transactions.
+
+## Action Discovery
+
+```typescript
+import { actions, getActionByName, findActionBySimile } from "dappily-agent-kit";
+
+// List all actions
+actions.forEach(a => console.log(a.name, a.description));
+
+// Lookup by name
+const action = getActionByName("HBAR_TRANSFER");
+
+// Fuzzy match (for AI agents)
+const match = findActionBySimile("send some hbar");
+// → hbarTransferAction
+```
+
+## Examples
+
+See the [`examples/`](./examples) directory:
+
+- **`balance.ts`** — Check account balance
+- **`fungible-lifecycle.ts`** — Create → Mint → Transfer → Burn
+- **`nft-lifecycle.ts`** — Create collection → Mint NFTs → Burn
+
+```bash
+OPERATOR_ID=0.0.XXXXX OPERATOR_KEY=302e... npx ts-node examples/balance.ts
+```
+
+## Security
+
+⚠️ **Private keys in action inputs** are supported for development and testing. For production:
+
+- Use environment variables or a vault for key storage
+- Never log or persist private keys
+- Plan to integrate wallet signing (HashPack / WalletConnect) for third-party accounts
+- The `accountPrivateKey` and `supplyPrivateKey` fields will be replaced with a signing interface in a future version
+
+## Architecture
+
+```
+dappily-agent-kit/
+├── src/
+│   ├── index.ts              # Public API surface
+│   ├── agent/index.ts        # HederaAgentKit (client + operator)
+│   ├── actions/
+│   │   ├── index.ts          # Registry + lookup helpers
+│   │   ├── get_balance.ts    # GET_BALANCE
+│   │   ├── transfer.ts       # HBAR_TRANSFER
+│   │   ├── create_token.ts   # CREATE_TOKEN
+│   │   ├── associate_token.ts
+│   │   ├── transfer_token.ts
+│   │   ├── mint_token.ts
+│   │   ├── burn_token.ts
+│   │   ├── create_nft_collection.ts
+│   │   ├── mint_nft.ts
+│   │   ├── transfer_nft.ts
+│   │   └── burn_nft.ts
+│   └── types/action.ts       # ActionResult, Action, etc.
+├── examples/
+│   ├── balance.ts
+│   ├── fungible-lifecycle.ts
+│   └── nft-lifecycle.ts
+├── dist/                     # Built output (CJS + types)
+├── package.json
+├── tsconfig.build.json
+└── LICENSE
+```
+
+## Roadmap
+
+- [ ] HCS (Hedera Consensus Service) — topic create/submit
+- [ ] Mirror Node queries — token info, NFT metadata, transaction history
+- [ ] Wallet signing interface (replace private key inputs)
+- [ ] Smart contract deployment + invocation
+- [ ] Scheduled transactions
+- [ ] Multi-sig support
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+---
+
+Built by [Dappily](https://dappily.io) 🦞

package/dist/actions/associate_token.d.ts

@@ -0,0 +1,4 @@
+import { Action } from "../types/action";
+declare const associateTokenAction: Action;
+export default associateTokenAction;
+//# sourceMappingURL=associate_token.d.ts.map

package/dist/actions/associate_token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"associate_token.d.ts","sourceRoot":"","sources":["../../src/actions/associate_token.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAgB,MAAM,iBAAiB,CAAC;AAQvD,QAAA,MAAM,oBAAoB,EAAE,MAyL3B,CAAC;AAEF,eAAe,oBAAoB,CAAC"}

package/dist/actions/associate_token.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const zod_1 = require("zod");
+const sdk_1 = require("@hashgraph/sdk");
+const associateTokenAction = {
+    name: "ASSOCIATE_TOKEN",
+    similes: [
+        "associate token",
+        "link token",
+        "add token",
+        "enable token",
+        "opt in token",
+        "connect token",
+    ],
+    description: "Associate a token with a Hedera account so it can receive that token. On Hedera, accounts must explicitly opt-in to receive tokens. If no accountId is provided, associates with the agent's operator account. For third-party accounts, a private key is required (short-term; wallet signing planned).",
+    examples: [
+        [
+            {
+                input: {
+                    tokenId: "0.0.99999",
+                },
+                output: {
+                    ok: true,
+                    summary: "Associated token 0.0.99999 with account 0.0.12345",
+                    txId: "0.0.12345@1700000000.000000000",
+                    receipt: { status: "SUCCESS" },
+                    data: {
+                        tokenId: "0.0.99999",
+                        accountId: "0.0.12345",
+                        explorerUrl: "https://hashscan.io/testnet/transaction/...",
+                    },
+                },
+                explanation: "Associate a token with the agent's own account",
+            },
+        ],
+        [
+            {
+                input: {
+                    tokenId: "0.0.99999",
+                    accountId: "0.0.54321",
+                    accountPrivateKey: "302e020100300506...hex...",
+                },
+                output: {
+                    ok: true,
+                    summary: "Associated token 0.0.99999 with account 0.0.54321",
+                    txId: "0.0.12345@1700000000.000000000",
+                    receipt: { status: "SUCCESS" },
+                    data: {
+                        tokenId: "0.0.99999",
+                        accountId: "0.0.54321",
+                        explorerUrl: "https://hashscan.io/testnet/transaction/...",
+                    },
+                },
+                explanation: "Associate a token with a third-party account using their private key",
+            },
+        ],
+    ],
+    schema: zod_1.z.object({
+        tokenId: zod_1.z
+            .string()
+            .regex(/^\d+\.\d+\.\d+$/, "Invalid Hedera Token ID format (must be 0.0.X)")
+            .describe("The token ID to associate (e.g. 0.0.99999)"),
+        accountId: zod_1.z
+            .string()
+            .regex(/^\d+\.\d+\.\d+$/, "Invalid Hedera Account ID format (must be 0.0.X)")
+            .optional()
+            .describe("The account to associate the token with. Defaults to the agent's operator account."),
+        accountPrivateKey: zod_1.z
+            .string()
+            .optional()
+            .describe("⚠️ Private key of the target account (required for third-party accounts). Will be replaced by wallet signing in a future version."),
+    }),
+    requiresConfirmation: true,
+    simulate: async (agent, input) => {
+        const targetAccount = input.accountId || agent.accountId.toString();
+        const isThirdParty = input.accountId && input.accountId !== agent.accountId.toString();
+        const warnings = [];
+        if (isThirdParty && !input.accountPrivateKey) {
+            warnings.push("Third-party account requires a private key. The transaction will fail without it.");
+        }
+        return {
+            summary: `Associate token ${input.tokenId} with account ${targetAccount}`,
+            estimatedFeeHbar: 0.05,
+            warnings,
+        };
+    },
+    handler: async (agent, input) => {
+        try {
+            const targetAccountId = input.accountId
+                ? sdk_1.AccountId.fromString(input.accountId)
+                : agent.accountId;
+            const isThirdParty = input.accountId &&
+                input.accountId !== agent.accountId.toString();
+            // If third-party account but no key provided, fail early with guidance
+            if (isThirdParty && !input.accountPrivateKey) {
+                return {
+                    ok: false,
+                    error: "SIGNATURE_REQUIRED",
+                    details: `Account ${input.accountId} is not the agent's operator. Provide 'accountPrivateKey' or have the account owner sign via a wallet.`,
+                };
+            }
+            const tx = new sdk_1.TokenAssociateTransaction()
+                .setAccountId(targetAccountId)
+                .setTokenIds([input.tokenId]);
+            // Freeze the transaction before signing
+            const frozenTx = await tx.freezeWith(agent.client);
+            // Sign with the target account's key
+            if (isThirdParty && input.accountPrivateKey) {
+                const thirdPartyKey = sdk_1.PrivateKey.fromString(input.accountPrivateKey);
+                await frozenTx.sign(thirdPartyKey);
+            }
+            const response = await frozenTx.execute(agent.client);
+            const receipt = await response.getReceipt(agent.client);
+            if (receipt.status !== sdk_1.Status.Success) {
+                return {
+                    ok: false,
+                    error: receipt.status.toString(),
+                    details: `Token association failed with status: ${receipt.status.toString()}`,
+                };
+            }
+            const txId = response.transactionId.toString();
+            return {
+                ok: true,
+                summary: `Associated token ${input.tokenId} with account ${targetAccountId.toString()}`,
+                txId,
+                receipt: {
+                    status: receipt.status.toString(),
+                },
+                data: {
+                    tokenId: input.tokenId,
+                    accountId: targetAccountId.toString(),
+                    explorerUrl: agent.getExplorerUrl(txId),
+                },
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const knownErrors = {
+                TOKEN_ALREADY_ASSOCIATED_TO_ACCOUNT: "This token is already associated with this account.",
+                INVALID_ACCOUNT_ID: "The account ID does not exist on this network.",
+                INVALID_TOKEN_ID: "The token ID does not exist on this network.",
+                TOKENS_PER_ACCOUNT_LIMIT_EXCEEDED: "This account has reached its maximum token association limit.",
+                INVALID_SIGNATURE: "Transaction signature is invalid. Check the private key provided.",
+                INSUFFICIENT_PAYER_BALANCE: "Not enough HBAR to cover the transaction fee.",
+            };
+            const errorCode = Object.keys(knownErrors).find((code) => message.includes(code));
+            return {
+                ok: false,
+                error: errorCode || "ASSOCIATE_TOKEN_FAILED",
+                details: errorCode ? knownErrors[errorCode] : message,
+            };
+        }
+    },
+};
+exports.default = associateTokenAction;
+//# sourceMappingURL=associate_token.js.map

package/dist/actions/associate_token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"associate_token.js","sourceRoot":"","sources":["../../src/actions/associate_token.ts"],"names":[],"mappings":"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"}

package/dist/actions/burn_nft.d.ts

@@ -0,0 +1,4 @@
+import { Action } from "../types/action";
+declare const burnNftAction: Action;
+export default burnNftAction;
+//# sourceMappingURL=burn_nft.d.ts.map

package/dist/actions/burn_nft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"burn_nft.d.ts","sourceRoot":"","sources":["../../src/actions/burn_nft.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAgB,MAAM,iBAAiB,CAAC;AAOvD,QAAA,MAAM,aAAa,EAAE,MAuIpB,CAAC;AAEF,eAAe,aAAa,CAAC"}

package/dist/actions/burn_nft.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const zod_1 = require("zod");
+const sdk_1 = require("@hashgraph/sdk");
+const burnNftAction = {
+    name: "BURN_NFT",
+    similes: [
+        "burn nft",
+        "destroy nft",
+        "delete nft",
+        "remove nft",
+        "nft burn",
+    ],
+    description: "Permanently burn an NFT by serial number from the treasury account. This is irreversible. The collection must have a supply key. The NFT must be owned by the treasury.",
+    examples: [
+        [
+            {
+                input: {
+                    tokenId: "0.0.88888",
+                    serial: 3,
+                },
+                output: {
+                    ok: true,
+                    summary: "Burned NFT 0.0.88888 #3",
+                    txId: "0.0.12345@1700000000.000000000",
+                    receipt: { status: "SUCCESS" },
+                    data: {
+                        tokenId: "0.0.88888",
+                        serial: 3,
+                        explorerUrl: "https://hashscan.io/testnet/transaction/...",
+                    },
+                },
+                explanation: "Permanently burn NFT serial #3 from the treasury",
+            },
+        ],
+    ],
+    schema: zod_1.z.object({
+        tokenId: zod_1.z
+            .string()
+            .regex(/^\d+\.\d+\.\d+$/, "Invalid Hedera Token ID format (must be 0.0.X)")
+            .describe("The NFT collection token ID"),
+        serial: zod_1.z
+            .number()
+            .int()
+            .positive()
+            .describe("The serial number of the NFT to burn"),
+        memo: zod_1.z
+            .string()
+            .max(100)
+            .optional()
+            .describe("Optional transaction memo"),
+        supplyPrivateKey: zod_1.z
+            .string()
+            .optional()
+            .describe("⚠️ Supply key (only if different from operator key)"),
+    }),
+    requiresConfirmation: true,
+    simulate: async (_agent, input) => {
+        return {
+            summary: `Burn NFT ${input.tokenId} #${input.serial}`,
+            estimatedFeeHbar: 0.001,
+            warnings: [
+                "⚠️ NFT burns are irreversible. This serial number will be permanently destroyed.",
+            ],
+        };
+    },
+    handler: async (agent, input) => {
+        try {
+            const tx = new sdk_1.TokenBurnTransaction()
+                .setTokenId(input.tokenId)
+                .setSerials([input.serial]);
+            if (input.memo) {
+                tx.setTransactionMemo(input.memo);
+            }
+            const frozenTx = await tx.freezeWith(agent.client);
+            if (input.supplyPrivateKey) {
+                const supplyKey = sdk_1.PrivateKey.fromString(input.supplyPrivateKey);
+                await frozenTx.sign(supplyKey);
+            }
+            const response = await frozenTx.execute(agent.client);
+            const receipt = await response.getReceipt(agent.client);
+            if (receipt.status !== sdk_1.Status.Success) {
+                return {
+                    ok: false,
+                    error: receipt.status.toString(),
+                    details: `NFT burn failed with status: ${receipt.status.toString()}`,
+                };
+            }
+            const txId = response.transactionId.toString();
+            return {
+                ok: true,
+                summary: `Burned NFT ${input.tokenId} #${input.serial}`,
+                txId,
+                receipt: { status: receipt.status.toString() },
+                data: {
+                    tokenId: input.tokenId,
+                    serial: input.serial,
+                    explorerUrl: agent.getExplorerUrl(txId),
+                },
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const knownErrors = {
+                TOKEN_HAS_NO_SUPPLY_KEY: "This collection has no supply key. Burning is permanently disabled.",
+                INVALID_SIGNATURE: "Transaction signature is invalid. The supply key doesn't match.",
+                INVALID_TOKEN_ID: "The token ID does not exist on this network.",
+                INVALID_NFT_ID: "The specified NFT serial does not exist in this collection.",
+                SENDER_DOES_NOT_OWN_NFT_SERIAL_NO: "The treasury does not own this NFT serial. Only treasury-held NFTs can be burned.",
+                TOKEN_WAS_DELETED: "This collection has been deleted.",
+                INSUFFICIENT_PAYER_BALANCE: "Not enough HBAR to cover the transaction fee.",
+            };
+            const errorCode = Object.keys(knownErrors).find((code) => message.includes(code));
+            return {
+                ok: false,
+                error: errorCode || "BURN_NFT_FAILED",
+                details: errorCode ? knownErrors[errorCode] : message,
+            };
+        }
+    },
+};
+exports.default = burnNftAction;
+//# sourceMappingURL=burn_nft.js.map

package/dist/actions/burn_nft.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"burn_nft.js","sourceRoot":"","sources":["../../src/actions/burn_nft.ts"],"names":[],"mappings":"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"}

package/dist/actions/burn_token.d.ts

@@ -0,0 +1,4 @@
+import { Action } from "../types/action";
+declare const burnTokenAction: Action;
+export default burnTokenAction;
+//# sourceMappingURL=burn_token.d.ts.map

package/dist/actions/burn_token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"burn_token.d.ts","sourceRoot":"","sources":["../../src/actions/burn_token.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAgB,MAAM,iBAAiB,CAAC;AAOvD,QAAA,MAAM,eAAe,EAAE,MAqKtB,CAAC;AAEF,eAAe,eAAe,CAAC"}