Implemented 3Land SDK into solana-agent-kit (#136)

# Pull Request Description

## Changes Made
This PR adds the following changes:
- Integrated 3land SDK into send-ai-sdk to enable AI agents to create
Collections and NFTs
- Every  NFT creation automatically lists on 3.land marketplace
- Added comprehensive test suite for 3land tools integration
- Updated documentation with usage examples and implementation details

## Implementation Details
- Implemented new 3land tools module in `/test/tools/3land.ts`
- Added SDK wrapper functions for NFT and collection creation 

## Transaction executed by agent 
Example collection creation:
```typescript
const optionsWithBase58: StoreInitOptions = {
  privateKey: "",
  isMainnet: true, // if false, collection will be created on devnet 3.land (dev.3.land)
};

 const collectionOpts: CreateCollectionOptions = {
    collectionName: "",
    collectionSymbol: "",
    collectionDescription: "",
    mainImageUrl: ""
  };

const result = await agent.create3LandCollection(
      optionsWithBase58,
      collectionOpts
    );
```
example nft creation
```typescript
const optionsWithBase58: StoreInitOptions = {
  privateKey: "",
  isMainnet: true, // if false, listing will be on devnet 3.land (dev.3.land)
};
const collectionAccount = ""; //hash for the collection
const createItemOptions: CreateSingleOptions = {
  itemName: "",
  sellerFee: 500, //5%
  itemAmount: 100, //total items to be created
  itemSymbol: "",
  itemDescription: "",
  traits: [
    { trait_type: "", value: "" },
  ],
  price: 0, //100000000 == 0.1 sol, can be set to 0 for a free mint
  mainImageUrl: "",
  splHash: "", //present if listing is on a specific SPL token, if not present sale will be on $SOL
};
const isMainnet = true;
const result = await agent.create3LandNft(
  optionsWithBase58,
  collectionAccount,
  createItemOptions,
  isMainnet
);
```
## Additional Notes
- The integration enables seamless NFT creation and marketplace listing
through a single API call
- NFT listings can be done in any SPL token
- Test collection creation TX:
https://solscan.io/tx/4ypfwWedTwvVX5HLP9hZzc86CGbSLbBPStNNuXHw9eq9rmFeHtCZgccCkZhuKrNVWdy2RNEDBnYRY1Tq6t2iYAsj?cluster=devnet

## Checklist
- [x] I have tested these changes locally
- [x] I have updated the documentation
- [x] I have added a transaction link

README.md

@@ -35,7 +35,10 @@ Anyone - whether an SF-based AI researcher or a crypto-native builder - can brin
   - Balance checks
   - Stake SOL
   - Zk compressed Airdrop by Light Protocol and Helius
-
+- **NFTs on 3.Land**
+  - Create your own collection
+  - NFT creation and automatic listing on 3.land
+  - List your NFT for sale in any SPL token
 - **NFT Management via Metaplex**
   - Collection deployment
   - NFT minting
@@ -127,6 +130,57 @@ const result = await agent.deployToken(
 
 console.log("Token Mint Address:", result.mint.toString());
 ```
+### Create NFT Collection on 3Land
+```typescript
+const optionsWithBase58: StoreInitOptions = {
+  privateKey: "",
+  isMainnet: true, // if false, collection will be created on devnet 3.land (dev.3.land)
+};
+
+ const collectionOpts: CreateCollectionOptions = {
+    collectionName: "",
+    collectionSymbol: "",
+    collectionDescription: "",
+    mainImageUrl: ""
+  };
+
+const result = await agent.create3LandCollection(
+      optionsWithBase58,
+      collectionOpts
+    );
+```
+
+### Create NFT on 3Land
+When creating an NFT using 3Land's tool, it automatically goes for sale on 3.land website
+```typescript
+const optionsWithBase58: StoreInitOptions = {
+  privateKey: "",
+  isMainnet: true, // if false, listing will be on devnet 3.land (dev.3.land)
+};
+const collectionAccount = ""; //hash for the collection
+const createItemOptions: CreateSingleOptions = {
+  itemName: "",
+  sellerFee: 500, //5%
+  itemAmount: 100, //total items to be created
+  itemSymbol: "",
+  itemDescription: "",
+  traits: [
+    { trait_type: "", value: "" },
+  ],
+  price: 0, //100000000 == 0.1 sol, can be set to 0 for a free mint
+  mainImageUrl: "",
+  splHash: "", //present if listing is on a specific SPL token, if not present sale will be on $SOL
+};
+const isMainnet = true;
+const result = await agent.create3LandNft(
+  optionsWithBase58,
+  collectionAccount,
+  createItemOptions,
+  isMainnet
+);
+
+```
+
 
 ### Create NFT Collection
 

examples/agent-kit-langgraph/src/utils/solanaAgent.ts

@@ -3,7 +3,7 @@ import { SolanaAgentKit, createSolanaTools } from "solana-agent-kit";
 export const agentKit = new SolanaAgentKit(
   process.env.SOLANA_PRIVATE_KEY!,
   process.env.RPC_URL!,
-  process.env.OPENAI_API_KEY!,
+  { OPENAI_API_KEY: process.env.OPENAI_API_KEY! },
 );
 
 export const solanaTools = createSolanaTools(agentKit);

package.json

@@ -23,6 +23,7 @@
 	"author": "sendaifun",
 	"license": "Apache-2.0",
 	"dependencies": {
+		"@3land/listings-sdk": "^0.0.4",
 		"@ai-sdk/openai": "^1.0.11",
 		"@bonfida/spl-name-service": "^3.0.7",
 		"@cks-systems/manifest-sdk": "0.1.59",

src/agent/index.ts

@@ -75,6 +75,15 @@ import {
   FlashTradeParams,
   FlashCloseTradeParams,
 } from "../types";
+import {
+  createCollection,
+  createSingle,
+} from "../tools/create_3land_collectible";
+import {
+  CreateCollectionOptions,
+  CreateSingleOptions,
+  StoreInitOptions,
+} from "@3land/listings-sdk/dist/types/implementation/implementationTypes";
 
 /**
  * Main class for interacting with Solana blockchain
@@ -563,4 +572,27 @@ export class SolanaAgentKit {
   async flashCloseTrade(params: FlashCloseTradeParams): Promise<string> {
     return flashCloseTrade(this, params);
   }
+
+  async create3LandCollection(
+    optionsWithBase58: StoreInitOptions,
+    collectionOpts: CreateCollectionOptions,
+  ): Promise<string> {
+    const tx = await createCollection(optionsWithBase58, collectionOpts);
+    return `Transaction: ${tx}`;
+  }
+
+  async create3LandNft(
+    optionsWithBase58: StoreInitOptions,
+    collectionAccount: string,
+    createItemOptions: CreateSingleOptions,
+    isMainnet: boolean,
+  ): Promise<string> {
+    const tx = await createSingle(
+      optionsWithBase58,
+      collectionAccount,
+      createItemOptions,
+      isMainnet,
+    );
+    return `Transaction: ${tx}`;
+  }
 }

src/langchain/index.ts

@@ -9,6 +9,11 @@ import {
   SolanaAgentKit,
 } from "../index";
 import { create_image, FEE_TIERS, generateOrdersfromPattern } from "../tools";
+import {
+  CreateCollectionOptions,
+  CreateSingleOptions,
+  StoreInitOptions,
+} from "@3land/listings-sdk/dist/types/implementation/implementationTypes";
 
 export class SolanaBalanceTool extends Tool {
   name = "solana_balance";
@@ -2250,6 +2255,153 @@ export class SolanaFetchTokenDetailedReportTool extends Tool {
   }
 }
 
+export class Solana3LandCreateSingle extends Tool {
+  name = "3land_minting_tool";
+  description = `Creates an NFT and lists it on 3.land's website
+
+  Inputs:
+  privateKey (required): represents the privateKey of the wallet - can be an array of numbers, Uint8Array or base58 string
+  collectionAccount (optional): represents the account for the nft collection
+  itemName (required): the name of the NFT
+  sellerFee (required): the fee of the seller
+  itemAmount (required): the amount of the NFTs that can be minted
+  itemDescription (required): the description of the NFT
+  traits (required): the traits of the NFT [{trait_type: string, value: string}]
+  price (required): the price of the item, if is 0 the listing will be free
+  mainImageUrl (required): the main image of the NFT
+  coverImageUrl (optional): the cover image of the NFT
+  splHash (optional): the hash of the spl token, if not provided listing will be in $SOL
+  isMainnet (required): defines is the tx takes places in mainnet
+  `;
+
+  constructor(private solanaKit: SolanaAgentKit) {
+    super();
+  }
+
+  protected async _call(input: string): Promise<string> {
+    try {
+      const inputFormat = JSON.parse(input);
+      const privateKey = inputFormat.privateKey;
+      const isMainnet = inputFormat.isMainnet;
+
+      const optionsWithBase58: StoreInitOptions = {
+        ...(privateKey && { privateKey }),
+        ...(isMainnet && { isMainnet }),
+      };
+
+      let collectionAccount = inputFormat.collectionAccount;
+
+      const itemName = inputFormat?.itemName;
+      const sellerFee = inputFormat?.sellerFee;
+      const itemAmount = inputFormat?.itemAmount;
+      const itemSymbol = inputFormat?.itemSymbol;
+      const itemDescription = inputFormat?.itemDescription;
+      const traits = inputFormat?.traits;
+      const price = inputFormat?.price;
+      const mainImageUrl = inputFormat?.mainImageUrl;
+      const coverImageUrl = inputFormat?.coverImageUrl;
+      const splHash = inputFormat?.splHash;
+
+      const createItemOptions: CreateSingleOptions = {
+        ...(itemName && { itemName }),
+        ...(sellerFee && { sellerFee }),
+        ...(itemAmount && { itemAmount }),
+        ...(itemSymbol && { itemSymbol }),
+        ...(itemDescription && { itemDescription }),
+        ...(traits && { traits }),
+        ...(price && { price }),
+        ...(mainImageUrl && { mainImageUrl }),
+        ...(coverImageUrl && { coverImageUrl }),
+        ...(splHash && { splHash }),
+      };
+
+      if (!collectionAccount) {
+        throw new Error("Collection account is required");
+      }
+
+      const tx = await this.solanaKit.create3LandNft(
+        optionsWithBase58,
+        collectionAccount,
+        createItemOptions,
+        isMainnet,
+      );
+      return JSON.stringify({
+        status: "success",
+        message: `Created listing successfully ${tx}`,
+        transaction: tx,
+      });
+    } catch (error: any) {
+      return JSON.stringify({
+        status: "error",
+        message: error.message,
+        code: error.code || "UNKNOWN_ERROR",
+      });
+    }
+  }
+}
+
+export class Solana3LandCreateCollection extends Tool {
+  name = "3land_minting_tool";
+  description = `Creates an NFT Collection that you can visit on 3.land's website (3.land/collection/{collectionAccount})
+  
+  Inputs:
+  privateKey (required): represents the privateKey of the wallet - can be an array of numbers, Uint8Array or base58 string
+  isMainnet (required): defines is the tx takes places in mainnet
+  collectionSymbol (required): the symbol of the collection
+  collectionName (required): the name of the collection
+  collectionDescription (required): the description of the collection
+  mainImageUrl (required): the image of the collection
+  coverImageUrl (optional): the cover image of the collection
+  `;
+
+  constructor(private solanaKit: SolanaAgentKit) {
+    super();
+  }
+
+  protected async _call(input: string): Promise<string> {
+    try {
+      const inputFormat = JSON.parse(input);
+      const privateKey = inputFormat.privateKey;
+      const isMainnet = inputFormat.isMainnet;
+
+      const optionsWithBase58: StoreInitOptions = {
+        ...(privateKey && { privateKey }),
+        ...(isMainnet && { isMainnet }),
+      };
+
+      const collectionSymbol = inputFormat?.collectionSymbol;
+      const collectionName = inputFormat?.collectionName;
+      const collectionDescription = inputFormat?.collectionDescription;
+      const mainImageUrl = inputFormat?.mainImageUrl;
+      const coverImageUrl = inputFormat?.coverImageUrl;
+
+      const collectionOpts: CreateCollectionOptions = {
+        ...(collectionSymbol && { collectionSymbol }),
+        ...(collectionName && { collectionName }),
+        ...(collectionDescription && { collectionDescription }),
+        ...(mainImageUrl && { mainImageUrl }),
+        ...(coverImageUrl && { coverImageUrl }),
+      };
+
+      const tx = await this.solanaKit.create3LandCollection(
+        optionsWithBase58,
+        collectionOpts,
+      );
+      return JSON.stringify({
+        status: "success",
+        message: `Created Collection successfully ${tx}`,
+        transaction: tx,
+      });
+    } catch (error: any) {
+      return JSON.stringify({
+        status: "error",
+        message: error.message,
+        code: error.code || "UNKNOWN_ERROR",
+      });
+    }
+  }
+}
+
 export function createSolanaTools(solanaKit: SolanaAgentKit) {
   return [
     new SolanaBalanceTool(solanaKit),
@@ -2302,9 +2454,12 @@ export function createSolanaTools(solanaKit: SolanaAgentKit) {
     new SolanaCancelNFTListingTool(solanaKit),
     new SolanaFetchTokenReportSummaryTool(solanaKit),
     new SolanaFetchTokenDetailedReportTool(solanaKit),
+    new Solana3LandCreateSingle(solanaKit),
+    new Solana3LandCreateCollection(solanaKit),
     new SolanaPerpOpenTradeTool(solanaKit),
     new SolanaPerpCloseTradeTool(solanaKit),
     new SolanaFlashOpenTrade(solanaKit),
     new SolanaFlashCloseTrade(solanaKit),
+    new Solana3LandCreateSingle(solanaKit),
   ];
 }

src/tools/create_3land_collectible.ts

@@ -0,0 +1,69 @@
+import { createCollectionImp, createSingleImp } from "@3land/listings-sdk";
+import {
+  StoreInitOptions,
+  CreateCollectionOptions,
+  CreateSingleOptions,
+} from "@3land/listings-sdk/dist/types/implementation/implementationTypes";
+
+/**
+ * Create a collection on 3Land
+ * @param optionsWithBase58 represents the privateKey of the wallet - can be an array of numbers, Uint8Array or base58 string
+ * @param collectionOpts represents the options for the collection creation
+ * @returns
+ */
+export async function createCollection(
+  optionsWithBase58: StoreInitOptions,
+  collectionOpts: CreateCollectionOptions,
+) {
+  try {
+    const collection = await createCollectionImp(
+      optionsWithBase58,
+      collectionOpts,
+    );
+    return collection;
+  } catch (error: any) {
+    throw new Error(`Collection creation failed: ${error.message}`);
+  }
+}
+
+/**
+ * Create a single edition on 3Land
+ * @param optionsWithBase58 represents the privateKey of the wallet - can be an array of numbers, Uint8Array or base58 string
+ * @param collectionAccount represents the account for the nft collection
+ * @param createItemOptions the options for the creation of the single NFT listing
+ * @returns
+ */
+export async function createSingle(
+  optionsWithBase58: StoreInitOptions,
+  collectionAccount: string,
+  createItemOptions: CreateSingleOptions,
+  isMainnet: boolean,
+) {
+  try {
+    const landStore = isMainnet
+      ? "AmQNs2kgw4LvS9sm6yE9JJ4Hs3JpVu65eyx9pxMG2xA"
+      : "GyPCu89S63P9NcCQAtuSJesiefhhgpGWrNVJs4bF2cSK";
+
+    const singleEditionTx = await createSingleImp(
+      optionsWithBase58,
+      landStore,
+      collectionAccount,
+      createItemOptions,
+    );
+    return singleEditionTx;
+  } catch (error: any) {
+    throw new Error(`Single edition creation failed: ${error.message}`);
+  }
+}
+
+/**
+ * Buy a single edition on 3Land
+ * @param
+ * @returns
+ */
+// export async function buySingle() {
+//   try {
+//   } catch (error: any) {
+//     throw new Error(`Buying single edition failed: ${error.message}`);
+//   }
+// }

src/tools/index.ts

@@ -45,3 +45,5 @@ export * from "./trade";
 export * from "./transfer";
 export * from "./flash_open_trade";
 export * from "./flash_close_trade";
+
+export * from "./create_3land_collectible";