n8n Community Node for Crossmint

This community node for n8n provides a complete integration with Crossmint's Wallet and Checkout APIs. It allows users and AI agents to manage blockchain wallets and automate the purchase of physical products with cryptocurrency, all within your n8n workflows.

🚀 Installation

1. Go to your n8n instance.
2. From the menu, go to Settings > Community Nodes.
3. Click on Install a community node.
4. Enter the npm package name: n8n-nodes-crossmint.
5. Click Install.

Once installed, the "Crossmint" node will appear in your workflow editor.

⚙️ Configuration

Before using the node, you must configure your Crossmint credentials:

1. In n8n, go to Credentials and click Add credential.
2. Search for "Crossmint API" and select it.
3. Enter your Crossmint API Key (must be a server-side API key with appropriate permissions).
4. Select the Environment (Staging for testing, Production for real operations).
5. Save the credentials.

⚠️ Important: This node requires a server-side API key from Crossmint. Client-side keys will not work. Ensure your API key has the necessary permissions for wallet and checkout operations.

💡 Supported Operations

The node is organized into two primary resources: Wallet and Checkout.

Resource: Wallet

Operations for managing blockchain wallets.

• Get or Create Wallet: Creates a new Smart Wallet or retrieves an existing one if it's already associated with a user identifier on a specific blockchain. This operation is idempotent.
• Get Wallet: Retrieves the details of an existing wallet using its walletLocator.
• Transfer Token: Sends tokens (like USDC) from a Crossmint wallet to any other address or user.
• Get Balance: Checks the balance of native and other tokens (like USDC) for a specific wallet on one or more chains.

Resource: Checkout

Operations to automate the purchase of physical products with cryptocurrency. This is a two-step process.

• 1. Create Order:

  • Function: Creates a purchase order in Crossmint for a product from Amazon or Shopify.
  • Key Input: Product URL or identifier, recipient details (name, email, physical address), and payment details (which cryptocurrency to use and from which wallet to pay).
  • Key Output: Returns an order object containing the final price and, most importantly, a serializedTransaction. This serialized transaction is the "payment authorization" needed for the next step.

• 2. Pay Order:

  • Function: Executes the payment for a previously created order.
  • Key Input: The serializedTransaction obtained from the "Create Order" step.
  • Key Output: The transaction confirmation once it's submitted to the blockchain, with a pending status.

📖 API Reference

For detailed information about each operation, parameters, and response formats, refer to the official Crossmint API documentation:

Wallet Operations

• Get or Create Wallet: Crossmint Wallets API
• Get Wallet: Crossmint Wallets API - Get Wallet
• Transfer Token: Crossmint Wallets API - Transfer Tokens
• Get Balance: Crossmint Wallets API - Get Balance

Checkout Operations

• Create Order: Crossmint Checkout API - Create Order
• Pay Order: Crossmint Checkout API - Submit Transaction

Additional Resources

• Supported Chains and Tokens

🔑 Understanding Wallet Locators

Wallet locators are a key concept used throughout all Crossmint node operations. They provide a flexible way to identify and reference wallets using different types of identifiers.

Locator Types

For more detailed information about wallet locator formats and specifications, see: Crossmint Wallet Locators Documentation

Chain Types

• EVM: Ethereum Virtual Machine compatible chains (Ethereum, Polygon, Base, Arbitrum, etc.)
• Solana: Solana blockchain

Usage Across Operations

Wallet Operations:

• Get or Create Wallet: Use any locator type to create or retrieve a wallet
• Get Wallet: Query wallet details using any locator format
• Transfer Token: Specify both origin and recipient wallets using locators
• Get Balance: Check balances for wallets identified by locators

Checkout Operations:

• Pay Order: Use wallet locators to specify the payer address

Best Practices

1. Email locators are ideal for user-friendly identification
2. Wallet addresses provide direct blockchain access
3. "Me" locators are perfect for API key owner operations
4. User ID locators work well with existing user management systems
5. Always specify the correct chain type for non-address locators

Example Workflows

Workflow 1: Create a Wallet and Send Funds

This workflow creates a wallet for a new user and sends them 5 USDC.

1. Start Node: Initiates the workflow.
2. Crossmint Node (Wallet > Get or Create Wallet):
   • User Identifier: user-001
   • Identifier Type: User ID
   • Chain: Polygon Amoy
3. Crossmint Node (Wallet > Transfer Token):
   • Origin Wallet Locator: Your main wallet's email (e.g., email:company@funds.com:evm:smart).
   • Recipient Wallet Locator: The email of the user whose wallet was just created (e.g., email:user@example.com:evm).
   • Token: polygon-amoy:usdc
   • Amount: 5

Workflow 2: Purchase an Amazon Product with an Agent

This workflow simulates an AI agent purchasing a product for a user.

1. Start Node: Could be a webhook that receives an instruction like {"product": "amazon:B01DFKC2SO", "email": "customer@email.com", ...}.
2. Crossmint Node (Checkout > Create Order):
   • Platform: Amazon
   • Product Identifier: {{ $json.body.product }}
   • Recipient Email: {{ $json.body.email }}
   • Recipient Name, Address, etc.: Filled in with data from the webhook.
   • Payer Wallet Address: The address of the agent's wallet that holds the funds (USDC).
3. Crossmint Node (Checkout > Pay Order):
   • Serialized Transaction: Mapped from the previous node's output: {{ $('Create Order').item.json.result.order.payment.preparation.serializedTransaction }}.
   • Payer Wallet Address: The same agent wallet address.
4. Send Email Node: Notifies the user that their purchase is in process, including the orderId from the response.

🛠️ Local Development & Testing

Quick Setup for Testing Locally

If you want to test the node locally without installing it globally:

1. Install n8n globally:

   npm install n8n -g
   

2. Install the Crossmint node:

   npm install n8n-nodes-crossmint
   

3. Start n8n:

   n8n start
   

4. Configure the community node:

   • Open your browser and go to the n8n interface (usually http://localhost:5678)
   • Click on Settings (bottom left corner)
   • Go to Community Nodes
   • Click Install a community node
   • Enter: n8n-nodes-crossmint
   • Click Install

For more information about n8n installation, see: n8n Installation Guide

Development Setup

For contributing to this project:

1. Clone the repository:

   git clone [https://github.com/YourUsername/n8n-nodes-crossmint.git](https://github.com/YourUsername/n8n-nodes-crossmint.git)
   cd n8n-nodes-crossmint
   

2. Install dependencies and build:

   npm install
   npm run build
   

3. Link your node for testing:

   npm link
   cd ~/.n8n/
   npm link n8n-nodes-crossmint
   

4. Start n8n in a separate terminal (n8n start) and your node will appear.

📄 License

MIT