Integration Guides

Quick Start

Get up and running with BillMyAgent in minutes. This guide will walk you through creating your first payment.

Step 1: Get Your API Key

First, you'll need to obtain an API key. Visit our Get API Key page for detailed instructions on how to obtain your API key. This key will be used to authenticate all your API requests.

Step 2: Install the SDK

Choose the SDK for your preferred framework:

# React
npm install @billmyagent/payments-react

# Vue
npm install @billmyagent/payments-vue

# Core SDK
npm install @billmyagent/payments-core

Step 3: Initialize the SDK

For basic usage:

import { PaymentClient } from '@billmyagent/payments-core';

const client = new PaymentClient({
  apiKey: 'your-api-key',
  baseURL: 'http://localhost:3001/api/v1'
});

For automatic 402 handling (recommended for AI agents):

import { PaymentClient, MetaMaskAdapter } from '@billmyagent/payments-core';

const walletAdapter = new MetaMaskAdapter();
const client = new PaymentClient({
  apiKey: 'your-api-key',
  baseURL: 'http://localhost:3001/api/v1',
  walletAdapter, // Enable automatic 402 handling
  autoHandle402: true, // Automatically handle payment requirements
});

Step 4: Create a Payment (Simplified API)

The simplified API automatically generates payment_payload and payment_required using x402 libraries. Just provide the basic payment parameters:

// Payment payloads are automatically generated!
const payment = await client.createPaymentSimple({
  amount: '1000000000000000000',
  currency: 'ETH',
  network: 'ethereum',
  scheme: 'exact'
});

console.log('Payment created:', payment.id);

Advanced API (Manual Payloads)

For advanced use cases where you need full control over x402 payloads, you can use the advanced API with manually generated payment_payload and payment_required:

const payment = await client.createPayment({
  amount: '1000000000000000000',
  currency: 'ETH',
  network: 'ethereum',
  scheme: 'exact',
  payment_payload: paymentPayload, // Manually generated
  payment_required: paymentRequired // Manually generated
});

console.log('Payment created:', payment.id);

React Integration

For React applications, use the provided PaymentButton component or hooks:

Using PaymentButton Component

import { PaymentButton, PaymentClient } from '@billmyagent/payments-react';

function App() {
  const client = new PaymentClient({
    apiKey: 'your-api-key',
    baseURL: 'http://localhost:3001/api/v1'
  });

  return (
    <PaymentButton
      client={client}
      amount="1000000000000000000"
      currency="ETH"
      network="ethereum"
      scheme="exact"
      onSuccess={(payment) => console.log('Payment successful', payment)}
      onError={(error) => console.error('Payment failed', error)}
    >
      Pay Now
    </PaymentButton>
  );
}

Using usePayment Hook with Wallet Integration

import { usePayment } from '@billmyagent/payments-react';
import { MetaMaskAdapter } from '@billmyagent/payments-core';

function PaymentComponent() {
  const walletAdapter = new MetaMaskAdapter();
  const { 
    payment, 
    loading, 
    createPayment,
    walletConnected,
    connectWallet 
  } = usePayment({
    client: paymentClient,
    walletAdapter,
    autoConnect: true,
  });

  return (
    <div>
      {!walletConnected && (
        <button onClick={connectWallet}>Connect Wallet</button>
      )}
      <button onClick={() => createPayment({...})} disabled={loading}>
        Create Payment
      </button>
    </div>
  );
}

Vue Integration

For Vue applications, use the PaymentButton component with simplified parameters:

<template>
  <PaymentButton
    :client="client"
    amount="1000000000000000000"
    currency="ETH"
    network="ethereum"
    scheme="exact"
    @onSuccess="handleSuccess"
    @onError="handleError"
  >
    Pay Now
  </PaymentButton>
</template>

<script setup>
import { PaymentButton, PaymentClient } from '@billmyagent/payments-vue';

const client = new PaymentClient({
  apiKey: 'your-api-key',
  baseURL: 'http://localhost:3001/api/v1'
});

const handleSuccess = (payment) => {
  console.log('Payment successful', payment);
};

const handleError = (error) => {
  console.error('Payment failed', error);
};
</script>

Handling HTTP 402 Payment Required

When an API endpoint requires payment, it returns HTTP 402 with payment instructions. Our SDKs can automatically handle this:

// With wallet adapter configured, 402 responses are handled automatically
const client = new PaymentClient({
  apiKey: 'your-api-key',
  walletAdapter: new MetaMaskAdapter(),
  autoHandle402: true,
});

// When API returns 402:
// 1. SDK detects 402 response
// 2. Parses payment instructions
// 3. Prompts user to sign via wallet
// 4. Submits signed payment
// 5. Waits for verification
// 6. Retries original request automatically

try {
  const result = await client.getPayment('payment-id');
  // Payment handled automatically if needed!
} catch (error) {
  // Handle other errors
}

Webhook Integration

To receive payment events, set up a webhook endpoint in your application and register it with BillMyAgent. Webhooks will be sent for events like:

• Payment created
• Payment verified
• Payment completed
• Payment failed
• HTTP 402 responses (when payment is required)

Next Steps

Check out our Code Examples for more detailed implementation examples.