Skip to main content

MCP Module (AI Commerce)

The mcp module enables AI-powered commerce with natural language shopping and cryptocurrency payments. Supports both V1 (Neon only) and V2 (Multi-chain: Sepolia, Amoy, Neon) flows.

Import​

const mcp = await brdzSDK.mcp;

Methods Overview​

MethodDescriptionAuth RequiredVersionHTTP Endpoint
step1_detectIntentDetect purchase intent from text❌V1/V2POST /mcp/step1
step2_parseProductExtract product data from URL❌V1/V2POST /mcp/step2
step3a_productConfirmationConfirm product with USDC pricing❌V1/V2POST /mcp/step3a
createOrderCreate order (V1 - Neon only)✅V1POST /mcp/create-order
executeOrderExecute payment (V1 - Neon only)✅V1POST /mcp/execute-order
chainSelectorShow available chains❌V2POST /mcp/chain-selector
createOrderV2Create order with chain selection✅V2POST /mcp/v2/create-order
executeOrderV2Execute payment on selected chain✅V2POST /mcp/v2/execute-order
checkChainBalanceCheck USDC balance on chain❌V2POST /mcp/chain-balance
getOrderGet order details✅V1/V2GET /mcp/order/:order_id
getRecentOrdersGet recent orders✅V1/V2GET /mcp/orders/recent
getDashboardStatsGet order statistics✅V1/V2GET /mcp/orders/stats
getAllOrdersGet all orders with pagination✅V1/V2GET /mcp/orders
getDashboardDataGet combined dashboard data✅V1/V2Multiple endpoints

V1 Flow Methods (Neon Chain Only)​

step1_detectIntent​

Detect purchase intent from natural language input using Groq AI.

Syntax​

const result = await mcp.step1_detectIntent(data);

Parameters​

interface IntentData {
  prompt: string;  // Natural language input expressing purchase intent
}

Returns​

Promise<{
  step: number;
  detected_intent: string;  // Groq AI response or fallback
  detected_url: string | null;  // Extracted URL or null
}>

Example​

const intent = await mcp.step1_detectIntent({
  prompt: "I want to buy wireless headphones from https://tokopedia.com/headphones-url"
});

console.log('Step:', intent.step);
console.log('AI Intent:', intent.detected_intent);
console.log('URL found:', intent.detected_url);

// Continue to step2 if URL detected
if (intent.detected_url) {
  // Proceed to step2_parseProduct
}

step2_parseProduct​

Parse product information from e-commerce URL using parseProduct agent.

Syntax​

const result = await mcp.step2_parseProduct(data);

Parameters​

interface ParseData {
  url: string;  // E-commerce product URL (http/https required)
}

Returns​

Promise<{
  step: number;
  product: {
    title: string;
    priceText: string;
    description?: string;
    image?: string;
    site: string;
    url: string;
    prompt_summary?: string;
  };
  ai_summary: string;  // Groq AI generated summary
}>

Example​

const product = await mcp.step2_parseProduct({
  url: 'https://tokopedia.com/product/wireless-bluetooth-headphones'
});

console.log('Product:', product.product.title);
console.log('Price:', product.product.priceText);
console.log('AI Summary:', product.ai_summary);

step3a_productConfirmation​

Confirm product details and convert pricing to USDC using convertPriceToUSDC service.

Syntax​

const result = await mcp.step3a_productConfirmation(data);

Parameters​

interface ConfirmationData {
  product: {
    title: string;        // Required
    priceText: string;    // Required (e.g., "Rp 299.000")
    description?: string;
    image?: string;
    site?: string;
    url?: string;
  };
}

Returns​

Promise<{
  step: string;  // "3a"
  product: {
    title: string;
    description?: string;
    image?: string;
    site?: string;
    url?: string;
  };
  pricing: {
    original: {
      amount: number;
      currency: string;
      formatted: string;
    };
    usdc: {
      amount: number;
      formatted: string;
    };
    conversion_rate: number;
    route: string;
  };
  ai_confirmation: string;  // Groq AI confirmation message
  ready_for_recipient_data: boolean;
}>

Example​

const confirmation = await mcp.step3a_productConfirmation({
  product: product.product
});

console.log('Original price:', confirmation.pricing.original.formatted);
console.log('USDC price:', confirmation.pricing.usdc.formatted);
console.log('AI confirmation:', confirmation.ai_confirmation);

createOrder​

Create purchase order with recipient information and wallet balance verification (V1 - Neon only).

Syntax​

const result = await mcp.createOrder(data);

Parameters​

interface OrderData {
  product: {
    title: string;
    description?: string;
    image?: string;
    site?: string;
    url?: string;
  };
  pricing: {
    original: {
      amount: number;
      currency: string;
      formatted: string;
    };
    usdc: {
      amount: number;
      formatted: string;
    };
    conversion_rate: number;
  };
  recipient: {
    name: string;        // Required
    address: string;     // Required
    phone?: string;
    notes?: string;
  };
  wallet_address: string;  // Required - user's wallet for balance check
}

Returns​

Promise<{
  step: string;  // "create-order"
  order_id: string;
  created_at: string;
  wallet: {
    address: string;
    balance_usdc: number;
    balance_formatted: string;
  };
  transaction: {
    required_usdc: number;
    sufficient_balance: boolean;
    can_proceed: boolean;
  };
  recipient: object;
  pricing: object;
  ready_for_payment: boolean;
}>

Example​

const order = await mcp.createOrder({
  product: confirmation.product,
  pricing: confirmation.pricing,
  recipient: {
    name: "John Doe",
    phone: "+628123456789",
    address: "Jl. Sudirman No. 123, Jakarta Selatan 12190, Indonesia",
    notes: "Please call before delivery"
  },
  wallet_address: "0x1234567890123456789012345678901234567890"
});

console.log('Order ID:', order.order_id);
console.log('Ready for payment:', order.ready_for_payment);
console.log('Balance sufficient:', order.transaction.sufficient_balance);

executeOrder​

Execute the purchase with USDC payment on Neon chain (V1).

Syntax​

const result = await mcp.executeOrder(data);

Parameters​

interface ExecuteData {
  order_id: string;           // Order ID from createOrder
  confirmation: string;       // Must contain "confirm"
  wallet_address: string;     // User's wallet address
}

Returns​

Promise<{
  step: string;  // "execute-order"
  success: boolean;
  order: {
    order_id: string;
    status: string;  // "COMPLETED"
    created_at: string;
    updated_at: string;
  };
  transaction: {
    tx_hash_payment: string;
    tx_hash_mcp: string;
    mcp_status: string;
    offramp_status: string;
    amount_paid: number;
    wallet_address: string;
  };
  pricing: {
    original: {
      amount: number;
      currency: string;
      formatted: string;
    };
    usdc: {
      amount: number;
      formatted: string;
    };
  };
  recipient: object;
  email_sent: boolean;
  completion_message: string;
}>

Example​

const execution = await mcp.executeOrder({
  order_id: order.order_id,
  confirmation: "confirmed",
  wallet_address: "0x1234567890123456789012345678901234567890"
});

console.log('Transaction hash:', execution.transaction.tx_hash_payment);
console.log('Order status:', execution.order.status);
console.log('Email sent:', execution.email_sent);

V2 Flow Methods (Multi-Chain Support)​

chainSelector​

Show available blockchain networks for user selection after product and recipient data.

Syntax​

const result = await mcp.chainSelector(data);

Parameters​

interface ChainSelectorData {
  product: object;    // Product from step3a
  pricing: object;    // Pricing from step3a
  recipient: object;  // Recipient information
}

Returns​

Promise<{
  step: string;  // "chain-selector"
  version: string;  // "v2"
  message: string;
  order_summary: {
    product: object;
    pricing: object;
    recipient: object;
  };
  chain_options: Array<{
    id: string;
    name: string;
    symbol: string;
    is_testnet: boolean;
    recommended: boolean;
    gas_estimate: string;
    contract_info: {
      usdc_contract: string;
      mcp_contract: string;
      rpc_url: string;
      explorer_url: string;
    };
  }>;
  instructions: {
    title: string;
    steps: string[];
    note: string;
  };
  next_step: {
    endpoint: string;
    method: string;
    required_fields: string[];
    note: string;
  };
}>

Example​

const chainSelector = await mcp.chainSelector({
  product: confirmation.product,
  pricing: confirmation.pricing,
  recipient: {
    name: "John Doe",
    address: "Jl. Sudirman No. 123, Jakarta"
  }
});

console.log('Available chains:', chainSelector.chain_options.length);
chainSelector.chain_options.forEach(chain => {
  console.log(`${chain.name} (${chain.id}) - Gas: ${chain.gas_estimate}`);
});

createOrderV2​

Create order with blockchain network selection (V2 Multi-chain).

Syntax​

const result = await mcp.createOrderV2(data);

Parameters​

interface OrderV2Data {
  product: object;
  pricing: object;
  recipient: object;
  selected_chain: string;    // Chain ID: "sepolia", "amoy", "neon"
  wallet_address: string;    // Wallet address for selected chain
}

Returns​

Promise<{
  step: string;  // "create-order-v2"
  version: string;  // "v2"
  order_id: string;
  created_at: string;
  chain_info: {
    selected_chain: string;
    chain_name: string;
    contract_info: object;
  };
  wallet: {
    address: string;
    balance_usdc: number;
    balance_display: string;
    validated: boolean;
  };
  transaction: {
    required_usdc: number;
    sufficient_balance: boolean;
    can_proceed: boolean;
  };
  order_details: object;
  next_step: string;
  ready_for_payment: boolean;
}>

Example​

const orderV2 = await mcp.createOrderV2({
  product: confirmation.product,
  pricing: confirmation.pricing,
  recipient: recipient,
  selected_chain: "amoy",
  wallet_address: "0x1234567890123456789012345678901234567890"
});

console.log('V2 Order ID:', orderV2.order_id);
console.log('Selected chain:', orderV2.chain_info.chain_name);
console.log('Balance sufficient:', orderV2.transaction.sufficient_balance);

executeOrderV2​

Execute payment on selected blockchain network (V2 Multi-chain).

Syntax​

const result = await mcp.executeOrderV2(data);

Parameters​

interface ExecuteV2Data {
  order_id: string;        // V2 order ID
  confirmation: string;    // Must contain "confirm"
  wallet_address: string;  // User's wallet address
}

Returns​

Promise<{
  step: string;  // "execute-order-v2"
  version: string;  // "v2"
  success: boolean;
  order: object;
  chain_execution: {
    chain_id: string;
    chain_name: string;
    is_v2_flow: boolean;
  };
  transaction: {
    tx_hash_payment: string;
    tx_hash_mcp: string;
    payment_explorer: string;
    mcp_explorer: string;
    mcp_status: string;
    offramp_status: string;
    amount_paid: number;
    wallet_address: string;
  };
  pricing: object;
  recipient: object;
  email_sent: boolean;
  completion_message: string;
}>

Example​

const executionV2 = await mcp.executeOrderV2({
  order_id: orderV2.order_id,
  confirmation: "confirmed",
  wallet_address: "0x1234567890123456789012345678901234567890"
});

console.log('Chain used:', executionV2.chain_execution.chain_name);
console.log('Payment TX:', executionV2.transaction.payment_explorer);
console.log('MCP TX:', executionV2.transaction.mcp_explorer);

checkChainBalance​

Check USDC balance on specific blockchain network (utility method).

Syntax​

const result = await mcp.checkChainBalance(data);

Parameters​

interface ChainBalanceData {
  wallet_address: string;  // Wallet address to check
  chain_id: string;        // Chain ID: "sepolia", "amoy", "neon"
}

Returns​

Promise<{
  success: boolean;
  data: {
    chain_id: string;
    chain_name: string;
    wallet_address: string;
    usdc_balance: {
      raw_balance: string;
      formatted_balance: string;
      display_balance: string;
      decimals: number;
    };
    contract_info: {
      usdc_contract: string;
      rpc_url: string;
    };
  };
}>

Example​

const balance = await mcp.checkChainBalance({
  wallet_address: "0x1234567890123456789012345678901234567890",
  chain_id: "amoy"
});

console.log('Balance on', balance.data.chain_name + ':', balance.data.usdc_balance.display_balance);

Order Management Methods​

getOrder​

Get detailed information about a specific order.

Syntax​

const result = await mcp.getOrder(order_id);

Parameters​

  • order_id (string): Order ID to retrieve

Returns​

Promise<{
  order: {
    order_id: string;
    user_id: number;
    product_data: object;
    recipient_name: string;
    recipient_phone: string;
    recipient_address: string;
    original_price: number;
    original_currency: string;
    usdc_amount: number;
    conversion_rate: number;
    order_status: string;
    tx_hash_burn: string;
    tx_hash_mcp: string;
    email_sent: boolean;
    special_notes: string;
    created_at: string;
    updated_at: string;
  };
  product: object;
}>

Example​

const orderDetails = await mcp.getOrder("ord_1234567890abcdef");
console.log('Order status:', orderDetails.order.order_status);
console.log('Product:', orderDetails.product.title);

getRecentOrders​

Get user's recent orders for dashboard display.

Syntax​

const result = await mcp.getRecentOrders(params);

Parameters​

interface RecentOrdersParams {
  limit?: number;  // Maximum orders to return (default: 5)
}

Returns​

Promise<{
  success: boolean;
  data: Array<{
    order_id: string;
    product_title: string;
    product_image: string | null;
    amount: number;
    currency: string;
    usdc_amount: number;
    status: string;
    created_at: string;
    formatted_amount: string;
    formatted_usdc: string;
  }>;
  count: number;
}>

Example​

const recentOrders = await mcp.getRecentOrders({ limit: 10 });
recentOrders.data.forEach(order => {
  console.log(`${order.product_title} - ${order.formatted_amount} (${order.status})`);
});

getDashboardStats​

Get user's order statistics for dashboard.

Syntax​

const result = await mcp.getDashboardStats();

Returns​

Promise<{
  success: boolean;
  data: {
    total_orders: number;
    completed_orders: number;
    processing_orders: number;
    total_spent_usdc: number;
    completion_rate: number;
    formatted_total_spent: string;
  };
}>

Example​

const stats = await mcp.getDashboardStats();
console.log('Total orders:', stats.data.total_orders);
console.log('Completion rate:', stats.data.completion_rate + '%');
console.log('Total spent:', stats.data.formatted_total_spent);

getAllOrders​

Get all user orders with pagination support.

Syntax​

const result = await mcp.getAllOrders(params);

Parameters​

interface AllOrdersParams {
  limit?: number;   // Records per page (default: 20, max: 100)
  offset?: number;  // Records to skip (default: 0)
}

Returns​

Promise<{
  success: boolean;
  data: Array<{
    order_id: string;
    product_data: object;
    product_title: string;
    product_image: string | null;
    recipient_name: string;
    recipient_address: string;
    recipient_phone: string;
    original_price: number;
    original_currency: string;
    usdc_amount: number;
    order_status: string;
    created_at: string;
    updated_at: string;
    tx_hash_payment: string;
    tx_hash_mcp: string;
    email_sent: boolean;
    special_notes: string;
    formatted_amount: string;
    formatted_usdc: string;
  }>;
  pagination: {
    count: number;
    limit: number;
    offset: number;
    has_more: boolean;
  };
}>

Example​

const allOrders = await mcp.getAllOrders({ limit: 20, offset: 0 });
console.log('Total orders in page:', allOrders.pagination.count);
console.log('Has more pages:', allOrders.pagination.has_more);

getDashboardData​

Get combined dashboard data (convenience method).

Syntax​

const result = await mcp.getDashboardData(recentLimit);

Parameters​

  • recentLimit (number, optional): Limit for recent orders (default: 5)

Returns​

Promise<{
  stats: object;         // From getDashboardStats
  recentOrders: Array;   // From getRecentOrders
  success: boolean;
}>

Example​

const dashboard = await mcp.getDashboardData(5);
console.log('Dashboard stats:', dashboard.stats);
console.log('Recent orders:', dashboard.recentOrders.length);

Complete V1 Shopping Flow Example​

class V1ShoppingFlow {
  constructor(sdk) {
    this.sdk = sdk;
    this.mcp = null;
    this.initMCP();
  }

  async initMCP() {
    this.mcp = await this.sdk.mcp;
  }

  async processShoppingRequest(userInput, recipient, walletAddress) {
    try {
      // Step 1: Detect intent
      const intent = await this.mcp.step1_detectIntent({
        prompt: userInput
      });

      if (!intent.detected_url) {
        return { error: 'No product URL detected in input' };
      }

      // Step 2: Parse product
      const product = await this.mcp.step2_parseProduct({
        url: intent.detected_url
      });

      console.log('AI Summary:', product.ai_summary);

      // Step 3a: Confirm with pricing
      const confirmation = await this.mcp.step3a_productConfirmation({
        product: product.product
      });

      console.log('AI Confirmation:', confirmation.ai_confirmation);

      // Create order (V1 - Neon only)
      const order = await this.mcp.createOrder({
        product: confirmation.product,
        pricing: confirmation.pricing,
        recipient: recipient,
        wallet_address: walletAddress
      });

      return {
        success: true,
        order_id: order.order_id,
        product: confirmation.product,
        pricing: confirmation.pricing,
        ready_for_payment: order.ready_for_payment,
        balance_sufficient: order.transaction.sufficient_balance
      };
    } catch (error) {
      throw new Error(`V1 Shopping flow failed: ${error.message}`);
    }
  }

  async completePurchase(orderId, walletAddress) {
    try {
      const result = await this.mcp.executeOrder({
        order_id: orderId,
        confirmation: 'confirmed',
        wallet_address: walletAddress
      });

      return {
        success: result.success,
        transaction_hash: result.transaction.tx_hash_payment,
        mcp_hash: result.transaction.tx_hash_mcp,
        email_sent: result.email_sent,
        message: result.completion_message
      };
    } catch (error) {
      throw new Error(`V1 Purchase execution failed: ${error.message}`);
    }
  }
}

Complete V2 Multi-Chain Shopping Flow Example​

class V2ShoppingFlow {
  constructor(sdk) {
    this.sdk = sdk;
    this.mcp = null;
    this.initMCP();
  }

  async initMCP() {
    this.mcp = await this.sdk.mcp;
  }

  async processShoppingRequest(userInput, recipient) {
    try {
      // Step 1-3a: Same as V1
      const intent = await this.mcp.step1_detectIntent({
        prompt: userInput
      });

      if (!intent.detected_url) {
        return { error: 'No product URL detected' };
      }

      const product = await this.mcp.step2_parseProduct({
        url: intent.detected_url
      });

      const confirmation = await this.mcp.step3a_productConfirmation({
        product: product.product
      });

      // V2: Show chain selector
      const chainSelector = await this.mcp.chainSelector({
        product: confirmation.product,
        pricing: confirmation.pricing,
        recipient: recipient
      });

      return {
        success: true,
        step: 'chain_selection',
        product: confirmation.product,
        pricing: confirmation.pricing,
        recipient: recipient,
        chain_options: chainSelector.chain_options,
        instructions: chainSelector.instructions
      };
    } catch (error) {
      throw new Error(`V2 Shopping preparation failed: ${error.message}`);
    }
  }

  async createOrderWithChain(productData, pricingData, recipient, selectedChain, walletAddress) {
    try {
      const orderV2 = await this.mcp.createOrderV2({
        product: productData,
        pricing: pricingData,
        recipient: recipient,
        selected_chain: selectedChain,
        wallet_address: walletAddress
      });

      return {
        success: true,
        order_id: orderV2.order_id,
        chain_info: orderV2.chain_info,
        ready_for_payment: orderV2.ready_for_payment,
        balance_sufficient: orderV2.transaction.sufficient_balance
      };
    } catch (error) {
      throw new Error(`V2 Order creation failed: ${error.message}`);
    }
  }

  async completePurchase(orderId, walletAddress) {
    try {
      const result = await this.mcp.executeOrderV2({
        order_id: orderId,
        confirmation: 'confirmed',
        wallet_address: walletAddress
      });

      return {
        success: result.success,
        chain_used: result.chain_execution.chain_name,
        payment_explorer: result.transaction.payment_explorer,
        mcp_explorer: result.transaction.mcp_explorer,
        email_sent: result.email_sent,
        message: result.completion_message
      };
    } catch (error) {
      throw new Error(`V2 Purchase execution failed: ${error.message}`);
    }
  }

  async checkWalletBalance(walletAddress, chainId) {
    try {
      const balance = await this.mcp.checkChainBalance({
        wallet_address: walletAddress,
        chain_id: chainId
      });

      return {
        chain: balance.data.chain_name,
        balance: balance.data.usdc_balance.display_balance,
        formatted: balance.data.usdc_balance.formatted_balance
      };
    } catch (error) {
      throw new Error(`Balance check failed: ${error.message}`);
    }
  }
}

Supported Chains (V2 Flow)​

Chain IDNameSymbolRecommendedGas EstimateNetwork Type
amoyPolygon AmoyMATIC✅ Yes~$0.01Testnet
sepoliaSepolia TestnetETH❌ No~$0.05Testnet
neonNeon DevNetNEON❌ No~$0.05Testnet

Error Handling​

All MCP methods can throw errors. Always wrap calls in try-catch blocks:

try {
  const result = await mcp.step1_detectIntent({ prompt: userInput });
  // Handle success
} catch (error) {
  if (error.message.includes('Prompt is required')) {
    // Handle missing prompt
  } else if (error.message.includes('Authentication required')) {
    // Handle auth error
  } else {
    // Handle other errors
    console.error('MCP operation failed:', error.message);
  }
}

Authentication Notes​

  • Steps 1, 2, 3a, chainSelector, checkChainBalance: No authentication required
  • createOrder, executeOrder, order management: Requires JWT token + API key
  • User validation: Must be active account with eKYC approval for order operations