@profullstack/coinpay 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,16 @@
 # @profullstack/coinpay
 
-CoinPay SDK & CLI - Cryptocurrency payment integration for Node.js
+CoinPay SDK & CLI - Accept cryptocurrency payments in your application.
+
+## Overview
+
+CoinPay allows merchants to accept cryptocurrency payments from their customers. When a customer wants to pay:
+
+1. **Your server** calls the CoinPay API to create a payment request
+2. **CoinPay** generates a unique payment address and QR code
+3. **Your customer** sends cryptocurrency to that address
+4. **CoinPay** monitors the blockchain and notifies you via webhook when payment is confirmed
+5. **Funds** are automatically forwarded to your configured wallet (minus a small fee)
 
 ## Installation
 
@@ -17,48 +27,88 @@ pnpm add -g @profullstack/coinpay
 
 ## Quick Start
 
-### SDK Usage
+### 1. Get Your API Key
+
+1. Sign up at [coinpayportal.com](https://coinpayportal.com)
+2. Create a business in your dashboard
+3. Configure your wallet addresses for each cryptocurrency you want to accept
+4. Copy your API key (starts with `cp_live_`)
+
+### 2. Create a Payment (SDK)
 
 ```javascript
 import { CoinPayClient } from '@profullstack/coinpay';
 
-// Initialize the client
+// Initialize with your API key
 const coinpay = new CoinPayClient({
-  apiKey: 'your-api-key',
+  apiKey: 'cp_live_your_api_key_here',
 });
 
-// Create a payment
+// Create a payment when customer checks out
 const payment = await coinpay.createPayment({
-  businessId: 'biz_123',
-  amount: 100,
-  currency: 'USD',
-  cryptocurrency: 'BTC',
-  description: 'Order #12345',
+  businessId: 'your-business-id',  // From your dashboard
+  amount: 99.99,                    // Amount in fiat currency
+  currency: 'USD',                  // Fiat currency (default: USD)
+  blockchain: 'BTC',                // Cryptocurrency to accept
+  description: 'Order #12345',      // Shown to customer
+  metadata: {                       // Your custom data
+    orderId: '12345',
+    customerEmail: 'customer@example.com'
+  }
 });
 
-console.log(`Payment address: ${payment.address}`);
-console.log(`Amount: ${payment.cryptoAmount} ${payment.cryptocurrency}`);
+// Display to customer
+console.log('Send payment to:', payment.payment.payment_address);
+console.log('Amount:', payment.payment.crypto_amount, payment.payment.blockchain);
+console.log('QR Code:', payment.payment.qr_code);
 ```
 
-### CLI Usage
+### 3. Create a Payment (cURL)
 
 ```bash
-# Configure your API key
-coinpay config set-key sk_live_xxxxx
+curl -X POST https://coinpayportal.com/api/payments/create \
+  -H "Authorization: Bearer cp_live_your_api_key_here" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "business_id": "your-business-id",
+    "amount": 99.99,
+    "currency": "USD",
+    "blockchain": "BTC",
+    "description": "Order #12345",
+    "metadata": {
+      "orderId": "12345",
+      "customerEmail": "customer@example.com"
+    }
+  }'
+```
 
-# Create a payment
-coinpay payment create --business-id biz_123 --amount 100 --currency USD --crypto BTC
+### 4. Create a Payment (CLI)
 
-# Get payment details
-coinpay payment get pay_abc123
-
-# List payments
-coinpay payment list --business-id biz_123
+```bash
+# Configure your API key (one-time setup)
+coinpay config set-key cp_live_your_api_key_here
 
-# Get exchange rates
-coinpay rates get BTC
+# Create a payment
+coinpay payment create \
+  --business-id your-business-id \
+  --amount 99.99 \
+  --blockchain BTC \
+  --description "Order #12345"
 ```
 
+## Supported Blockchains
+
+| Blockchain | Code | Description |
+|------------|------|-------------|
+| Bitcoin | `BTC` | Native Bitcoin |
+| Bitcoin Cash | `BCH` | Bitcoin Cash |
+| Ethereum | `ETH` | Native Ether |
+| Polygon | `MATIC` | Native MATIC |
+| Solana | `SOL` | Native SOL |
+| USDC (Ethereum) | `USDC_ETH` | USDC on Ethereum |
+| USDC (Polygon) | `USDC_MATIC` | USDC on Polygon |
+| USDC (Solana) | `USDC_SOL` | USDC on Solana |
+
 ## SDK API Reference
 
 ### CoinPayClient
@@ -67,39 +117,136 @@ coinpay rates get BTC
 import { CoinPayClient } from '@profullstack/coinpay';
 
 const client = new CoinPayClient({
-  apiKey: 'your-api-key',
-  baseUrl: 'https://coinpay.dev/api', // optional
-  timeout: 30000, // optional, in milliseconds
+  apiKey: 'cp_live_xxxxx',           // Required: Your API key
+  baseUrl: 'https://coinpayportal.com/api', // Optional: API URL
+  timeout: 30000,                     // Optional: Request timeout (ms)
 });
 ```
 
-### Payments
+### Creating Payments
 
 ```javascript
 // Create a payment
 const payment = await client.createPayment({
-  businessId: 'biz_123',
-  amount: 100,
-  currency: 'USD',
-  cryptocurrency: 'BTC',
-  description: 'Order #12345',
-  metadata: JSON.stringify({ orderId: '12345' }),
-  callbackUrl: 'https://your-site.com/webhook',
+  businessId: 'biz_123',      // Required: Your business ID
+  amount: 100,                // Required: Amount in fiat
+  currency: 'USD',            // Optional: Fiat currency (default: USD)
+  blockchain: 'ETH',          // Required: Blockchain to use
+  description: 'Order #123',  // Optional: Description for customer
+  metadata: { ... },          // Optional: Your custom data
+});
+
+// Response structure
+{
+  success: true,
+  payment: {
+    id: 'pay_abc123',
+    business_id: 'biz_123',
+    amount: 100,
+    currency: 'USD',
+    blockchain: 'ETH',
+    crypto_amount: '0.0456',
+    payment_address: '0x1234...5678',
+    qr_code: 'data:image/png;base64,...',
+    status: 'pending',
+    expires_at: '2024-01-01T01:00:00.000Z',
+    created_at: '2024-01-01T00:00:00.000Z'
+  },
+  usage: {
+    current: 45,
+    limit: 100,
+    remaining: 55
+  }
+}
+```
+
+### Checking Payment Status
+
+There are two ways to know when a payment is complete:
+
+#### Option 1: Polling (Simple)
+
+Use `getPayment()` to check status, or `waitForPayment()` to poll until complete:
+
+```javascript
+// Check status once
+const result = await client.getPayment('pay_abc123');
+console.log(result.payment.status);
+
+// Or wait for payment to complete (polls automatically)
+const payment = await client.waitForPayment('pay_abc123', {
+  interval: 5000,      // Check every 5 seconds
+  timeout: 600000,     // Give up after 10 minutes
+  onStatusChange: (status, payment) => {
+    console.log(`Status changed to: ${status}`);
+  }
 });
 
-// Get payment by ID
-const payment = await client.getPayment('pay_abc123');
+if (payment.payment.status === 'confirmed' || payment.payment.status === 'forwarded') {
+  console.log('Payment successful!');
+} else {
+  console.log('Payment failed or expired');
+}
+```
+
+#### Option 2: Webhooks (Recommended for Production)
+
+Configure a webhook URL in your business settings to receive real-time notifications:
+
+```javascript
+// Your webhook endpoint receives POST requests like:
+{
+  "event": "payment.confirmed",
+  "data": {
+    "payment": {
+      "id": "pay_abc123",
+      "status": "confirmed",
+      "metadata": { "orderId": "12345" }
+    }
+  }
+}
+```
+
+See [Webhook Integration](#webhook-integration) for full details.
+
+**Payment Statuses:**
+- `pending` - Waiting for payment
+- `detected` - Payment detected, waiting for confirmations
+- `confirmed` - Payment confirmed on blockchain
+- `forwarding` - Forwarding to your wallet
+- `forwarded` - Successfully sent to your wallet
+- `expired` - Payment request expired
+- `failed` - Payment failed
+
+### Getting QR Code
+
+The QR code endpoint returns binary PNG image data.
+
+```javascript
+// Get QR code URL for use in HTML <img> tags
+const qrUrl = client.getPaymentQRUrl('pay_abc123');
+// Returns: "https://coinpayportal.com/api/payments/pay_abc123/qr"
+
+// Use directly in HTML
+// <img src={qrUrl} alt="Payment QR Code" />
+
+// Get QR code as binary data (for server-side processing)
+const imageData = await client.getPaymentQR('pay_abc123');
 
-// List payments
+// Save to file (Node.js)
+import fs from 'fs';
+fs.writeFileSync('payment-qr.png', Buffer.from(imageData));
+```
+
+### Listing Payments
+
+```javascript
 const payments = await client.listPayments({
   businessId: 'biz_123',
-  status: 'completed', // optional
-  limit: 20, // optional
-  offset: 0, // optional
+  status: 'completed',  // Optional filter
+  limit: 20,            // Optional (default: 20)
+  offset: 0,            // Optional pagination
 });
-
-// Get payment QR code
-const qr = await client.getPaymentQR('pay_abc123', 'png');
 ```
 
 ### Exchange Rates
@@ -107,47 +254,100 @@ const qr = await client.getPaymentQR('pay_abc123', 'png');
 ```javascript
 // Get single rate
 const rate = await client.getExchangeRate('BTC', 'USD');
+// { from: 'BTC', to: 'USD', rate: 43250.00 }
 
 // Get multiple rates
 const rates = await client.getExchangeRates(['BTC', 'ETH', 'SOL'], 'USD');
 ```
 
-### Businesses
+## Direct API Usage (fetch/curl)
+
+### Create Payment
 
 ```javascript
-// Create a business
-const business = await client.createBusiness({
-  name: 'My Store',
-  webhookUrl: 'https://your-site.com/webhook',
-  walletAddresses: {
-    BTC: 'bc1q...',
-    ETH: '0x...',
+// Using fetch
+const response = await fetch('https://coinpayportal.com/api/payments/create', {
+  method: 'POST',
+  headers: {
+    'Authorization': 'Bearer cp_live_your_api_key',
+    'Content-Type': 'application/json',
   },
+  body: JSON.stringify({
+    business_id: 'your-business-id',
+    amount: 50.00,
+    currency: 'USD',
+    blockchain: 'ETH',
+    description: 'Premium subscription',
+    metadata: {
+      userId: 'user_123',
+      plan: 'premium'
+    }
+  }),
 });
 
-// Get business
-const business = await client.getBusiness('biz_123');
+const data = await response.json();
+console.log(data.payment.payment_address);
+```
+
+```bash
+# Using cURL
+curl -X POST https://coinpayportal.com/api/payments/create \
+  -H "Authorization: Bearer cp_live_your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "business_id": "your-business-id",
+    "amount": 50.00,
+    "currency": "USD",
+    "blockchain": "ETH",
+    "description": "Premium subscription"
+  }'
+```
 
-// List businesses
-const businesses = await client.listBusinesses();
+### Get Payment Status
 
-// Update business
-const updated = await client.updateBusiness('biz_123', {
-  name: 'Updated Name',
+```javascript
+const response = await fetch('https://coinpayportal.com/api/payments/pay_abc123', {
+  headers: {
+    'Authorization': 'Bearer cp_live_your_api_key',
+  },
 });
+const data = await response.json();
 ```
 
-### Webhooks
+```bash
+curl https://coinpayportal.com/api/payments/pay_abc123 \
+  -H "Authorization: Bearer cp_live_your_api_key"
+```
 
-```javascript
-// Get webhook logs
-const logs = await client.getWebhookLogs('biz_123', 50);
+## Webhook Integration
 
-// Test webhook
-const result = await client.testWebhook('biz_123', 'payment.completed');
+When payment status changes, CoinPay sends a POST request to your configured webhook URL:
+
+```javascript
+// Webhook payload
+{
+  "event": "payment.confirmed",
+  "timestamp": "2024-01-01T00:15:00.000Z",
+  "data": {
+    "payment": {
+      "id": "pay_abc123",
+      "business_id": "biz_123",
+      "amount": 100.00,
+      "currency": "USD",
+      "crypto_amount": "0.0456",
+      "blockchain": "ETH",
+      "status": "confirmed",
+      "tx_hash": "0xabc...def",
+      "metadata": {
+        "orderId": "12345"
+      }
+    }
+  },
+  "signature": "sha256_hmac_signature"
+}
 ```
 
-## Webhook Verification
+### Verifying Webhooks
 
 ```javascript
 import { verifyWebhookSignature, createWebhookHandler } from '@profullstack/coinpay';
@@ -163,101 +363,98 @@ const isValid = verifyWebhookSignature({
 app.post('/webhook', createWebhookHandler({
   secret: 'your-webhook-secret',
   onEvent: async (event) => {
-    console.log('Received event:', event.type);
-    
     switch (event.type) {
-      case 'payment.completed':
-        // Handle completed payment
+      case 'payment.confirmed':
+        // Mark order as paid
+        await markOrderPaid(event.data.payment.metadata.orderId);
+        break;
+      case 'payment.forwarded':
+        // Funds received in your wallet
         break;
       case 'payment.expired':
         // Handle expired payment
         break;
     }
   },
-  onError: (error) => {
-    console.error('Webhook error:', error);
-  },
 }));
 ```
 
-## Webhook Events
+### Webhook Events
 
 | Event | Description |
 |-------|-------------|
-| `payment.created` | Payment was created |
-| `payment.pending` | Payment is pending confirmation |
-| `payment.confirming` | Payment is being confirmed |
-| `payment.completed` | Payment completed successfully |
-| `payment.expired` | Payment expired |
+| `payment.created` | Payment request created |
+| `payment.detected` | Payment detected on blockchain |
+| `payment.confirmed` | Payment confirmed (safe to fulfill order) |
+| `payment.forwarding` | Forwarding funds to your wallet |
+| `payment.forwarded` | Funds sent to your wallet |
+| `payment.expired` | Payment request expired |
 | `payment.failed` | Payment failed |
-| `payment.refunded` | Payment was refunded |
 
-## CLI Commands
+## CLI Reference
 
 ### Configuration
 
 ```bash
-coinpay config set-key <api-key>    # Set API key
-coinpay config set-url <base-url>   # Set custom API URL
-coinpay config show                  # Show current config
+# Set your API key
+coinpay config set-key cp_live_xxxxx
+
+# Set custom API URL (for development)
+coinpay config set-url http://localhost:3000/api
+
+# Show current configuration
+coinpay config show
 ```
 
 ### Payments
 
 ```bash
-coinpay payment create [options]
-  --business-id <id>    Business ID (required)
-  --amount <amount>     Amount in fiat (required)
-  --currency <code>     Fiat currency (required)
-  --crypto <code>       Cryptocurrency (required)
-  --description <text>  Description (optional)
-
-coinpay payment get <payment-id>
-coinpay payment list --business-id <id> [--status <status>] [--limit <n>]
-coinpay payment qr <payment-id> [--format png|svg]
+# Create a payment
+coinpay payment create \
+  --business-id biz_123 \
+  --amount 100 \
+  --blockchain BTC \
+  --description "Order #12345"
+
+# Get payment details
+coinpay payment get pay_abc123
+
+# List payments
+coinpay payment list --business-id biz_123 --status pending --limit 10
+
+# Get QR code (saves as PNG file)
+coinpay payment qr pay_abc123 --output payment-qr.png
 ```
 
 ### Businesses
 
 ```bash
-coinpay business create --name <name> [--webhook-url <url>]
-coinpay business get <business-id>
+# List your businesses
 coinpay business list
-coinpay business update <business-id> [--name <name>] [--webhook-url <url>]
-```
 
-### Exchange Rates
+# Get business details
+coinpay business get biz_123
 
-```bash
-coinpay rates get <crypto> [--fiat <currency>]
-coinpay rates list [--fiat <currency>]
+# Create a business
+coinpay business create --name "My Store" --webhook-url https://mysite.com/webhook
 ```
 
-### Webhooks
+### Exchange Rates
 
 ```bash
-coinpay webhook logs <business-id> [--limit <n>]
-coinpay webhook test <business-id> [--event <type>]
-```
-
-## Supported Cryptocurrencies
-
-- **BTC** - Bitcoin
-- **BCH** - Bitcoin Cash
-- **ETH** - Ethereum
-- **MATIC** - Polygon
-- **SOL** - Solana
-
-## Supported Fiat Currencies
+# Get rate for a cryptocurrency
+coinpay rates get BTC
 
-- USD, EUR, GBP, CAD, AUD, and more
+# Get all rates
+coinpay rates list
+```
 
 ## Environment Variables
 
 | Variable | Description |
 |----------|-------------|
 | `COINPAY_API_KEY` | API key (overrides config file) |
-| `COINPAY_BASE_URL` | Custom API URL |
+| `COINPAY_BASE_URL` | Custom API URL (for development) |
 
 ## Error Handling
 
@@ -268,13 +465,91 @@ try {
   if (error.status === 401) {
     console.error('Invalid API key');
   } else if (error.status === 400) {
-    console.error('Invalid request:', error.response);
+    console.error('Invalid request:', error.response?.error);
+  } else if (error.status === 429) {
+    console.error('Rate limit exceeded or transaction limit reached');
+    console.error('Usage:', error.response?.usage);
   } else {
     console.error('Error:', error.message);
   }
 }
 ```
 
+## Common Integration Patterns
+
+### E-commerce Checkout
+
+```javascript
+// In your checkout handler
+app.post('/checkout', async (req, res) => {
+  const { orderId, amount, cryptocurrency } = req.body;
+  
+  const payment = await coinpay.createPayment({
+    businessId: process.env.COINPAY_BUSINESS_ID,
+    amount,
+    blockchain: cryptocurrency,
+    description: `Order #${orderId}`,
+    metadata: { orderId }
+  });
+  
+  // Save payment ID to your order
+  await db.orders.update(orderId, { 
+    paymentId: payment.payment.id,
+    paymentAddress: payment.payment.payment_address
+  });
+  
+  res.json({
+    paymentAddress: payment.payment.payment_address,
+    amount: payment.payment.crypto_amount,
+    qrCode: payment.payment.qr_code,
+    expiresAt: payment.payment.expires_at
+  });
+});
+
+// Webhook handler
+app.post('/webhook/coinpay', createWebhookHandler({
+  secret: process.env.COINPAY_WEBHOOK_SECRET,
+  onEvent: async (event) => {
+    if (event.type === 'payment.confirmed') {
+      const { orderId } = event.data.payment.metadata;
+      await db.orders.update(orderId, { status: 'paid' });
+      await sendOrderConfirmationEmail(orderId);
+    }
+  }
+}));
+```
+
+### Subscription Payments
+
+```javascript
+// Create subscription payment
+const payment = await coinpay.createPayment({
+  businessId: process.env.COINPAY_BUSINESS_ID,
+  amount: 9.99,
+  blockchain: 'USDC_MATIC',  // Stablecoin for predictable pricing
+  description: 'Monthly subscription',
+  metadata: {
+    userId: user.id,
+    subscriptionId: subscription.id,
+    period: '2024-01'
+  }
+});
+```
+
+## Testing
+
+For development and testing, you can:
+
+1. Use the dashboard's "Create Test Payment" feature
+2. Set a custom `baseUrl` pointing to your local development server
+3. Use testnet addresses (when supported)
+
+## Support
+
+- Documentation: [docs.coinpayportal.com](https://docs.coinpayportal.com)
+- Email: support@coinpayportal.com
+- Status: [status.coinpayportal.com](https://status.coinpayportal.com)
+
 ## License
 
 MIT

package/bin/coinpay.js

@@ -6,7 +6,7 @@
  */
 
 import { CoinPayClient } from '../src/client.js';
-import { PaymentStatus, Cryptocurrency, FiatCurrency } from '../src/payments.js';
+import { PaymentStatus, Blockchain, FiatCurrency } from '../src/payments.js';
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
@@ -70,7 +70,7 @@ function getApiKey() {
  */
 function getBaseUrl() {
   const config = loadConfig();
-  return process.env.COINPAY_BASE_URL || config.baseUrl || 'https://coinpay.dev/api';
+  return process.env.COINPAY_BASE_URL || config.baseUrl || 'https://coinpayportal.com/api';
 }
 
 /**
@@ -152,15 +152,31 @@ ${colors.cyan}Options:${colors.reset}
   --version, -v           Show version
   --json                  Output as JSON
   --business-id <id>      Business ID for operations
-  --amount <amount>       Payment amount
-  --currency <code>       Fiat currency (USD, EUR, etc.)
-  --crypto <code>         Cryptocurrency (BTC, ETH, etc.)
+  --amount <amount>       Payment amount in fiat currency
+  --currency <code>       Fiat currency (USD, EUR, etc.) - default: USD
+  --blockchain <code>     Blockchain (BTC, ETH, SOL, MATIC, BCH, USDC_ETH, USDC_MATIC, USDC_SOL)
+  --description <text>    Payment description
 
 ${colors.cyan}Examples:${colors.reset}
-  coinpay config set-key sk_live_xxxxx
-  coinpay payment create --business-id biz_123 --amount 100 --currency USD --crypto BTC
+  # Configure your API key (get it from your CoinPay dashboard)
+  coinpay config set-key cp_live_xxxxx
+
+  # Create a $100 Bitcoin payment
+  coinpay payment create --business-id biz_123 --amount 100 --blockchain BTC
+
+  # Create a $50 Ethereum payment with description
+  coinpay payment create --business-id biz_123 --amount 50 --blockchain ETH --description "Order #12345"
+
+  # Create a USDC payment on Polygon
+  coinpay payment create --business-id biz_123 --amount 25 --blockchain USDC_MATIC
+
+  # Get payment status
   coinpay payment get pay_abc123
+
+  # Get exchange rates
   coinpay rates get BTC
+
+  # List your businesses
   coinpay business list
 
 ${colors.cyan}Environment Variables:${colors.reset}
@@ -218,10 +234,11 @@ async function handlePayment(subcommand, args, flags) {
   
   switch (subcommand) {
     case 'create': {
-      const { 'business-id': businessId, amount, currency, crypto, description } = flags;
+      const { 'business-id': businessId, amount, currency = 'USD', blockchain, description } = flags;
       
-      if (!businessId || !amount || !currency || !crypto) {
-        print.error('Required: --business-id, --amount, --currency, --crypto');
+      if (!businessId || !amount || !blockchain) {
+        print.error('Required: --business-id, --amount, --blockchain');
+        print.info('Example: coinpay payment create --business-id biz_123 --amount 100 --blockchain BTC');
         return;
       }
       
@@ -229,12 +246,19 @@ async function handlePayment(subcommand, args, flags) {
         businessId,
         amount: parseFloat(amount),
         currency,
-        cryptocurrency: crypto,
+        blockchain,
         description,
       });
       
       print.success('Payment created');
-      print.json(payment);
+      if (payment.payment) {
+        print.info(`Payment Address: ${payment.payment.payment_address}`);
+        print.info(`Amount: ${payment.payment.crypto_amount} ${payment.payment.blockchain}`);
+        print.info(`Expires: ${payment.payment.expires_at}`);
+      }
+      if (!flags.json) {
+        print.json(payment);
+      }
       break;
     }
     
@@ -364,7 +388,7 @@ async function handleRates(subcommand, args, flags) {
       const { fiat } = flags;
       
       if (!crypto) {
-        print.error('Cryptocurrency code required (BTC, ETH, etc.)');
+        print.error('Blockchain code required (BTC, ETH, SOL, etc.)');
         return;
       }
       
@@ -375,7 +399,7 @@ async function handleRates(subcommand, args, flags) {
     
     case 'list': {
       const { fiat } = flags;
-      const cryptos = Object.values(Cryptocurrency);
+      const cryptos = Object.values(Blockchain);
       const rates = await client.getExchangeRates(cryptos, fiat);
       print.json(rates);
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CoinPay SDK & CLI - Cryptocurrency payment integration for Node.js",
   "type": "module",
   "main": "./src/index.js",

package/src/client.js

@@ -3,7 +3,7 @@
  * Main client class for interacting with the CoinPay API
  */
 
-const DEFAULT_BASE_URL = 'https://coinpay.dev/api';
+const DEFAULT_BASE_URL = 'https://coinpayportal.com/api';
 
 /**
  * CoinPay API Client
@@ -17,7 +17,7 @@ export class CoinPayClient {
    * Create a new CoinPay client
    * @param {Object} options - Client options
    * @param {string} options.apiKey - Your CoinPay API key
-   * @param {string} [options.baseUrl] - API base URL (default: https://coinpay.dev/api)
+   * @param {string} [options.baseUrl] - API base URL (default: https://coinpayportal.com/api)
    * @param {number} [options.timeout] - Request timeout in ms (default: 30000)
    */
   constructor({ apiKey, baseUrl = DEFAULT_BASE_URL, timeout = 30000 }) {
@@ -47,7 +47,7 @@ export class CoinPayClient {
         signal: controller.signal,
         headers: {
           'Content-Type': 'application/json',
-          'X-API-Key': this.#apiKey,
+          'Authorization': `Bearer ${this.#apiKey}`,
           ...options.headers,
         },
       });
@@ -74,48 +74,142 @@ export class CoinPayClient {
 
   /**
    * Create a new payment
+   *
+   * This is the primary method for merchants to create payment requests.
+   * When a customer needs to pay, call this method to generate a unique
+   * payment address and QR code.
+   *
    * @param {Object} params - Payment parameters
-   * @param {string} params.businessId - Business ID
-   * @param {number} params.amount - Amount in fiat currency
-   * @param {string} params.currency - Fiat currency code (USD, EUR, etc.)
-   * @param {string} params.cryptocurrency - Cryptocurrency code (BTC, ETH, etc.)
-   * @param {string} [params.description] - Payment description
-   * @param {string} [params.metadata] - Custom metadata (JSON string)
-   * @param {string} [params.callbackUrl] - Webhook callback URL
-   * @returns {Promise<Object>} Created payment
+   * @param {string} params.businessId - Business ID (from your CoinPay dashboard)
+   * @param {number} params.amount - Amount in fiat currency (e.g., 100.00)
+   * @param {string} [params.currency='USD'] - Fiat currency code (USD, EUR, etc.)
+   * @param {string} params.blockchain - Blockchain/cryptocurrency (BTC, ETH, SOL, MATIC, BCH, USDC_ETH, USDC_MATIC, USDC_SOL)
+   * @param {string} [params.description] - Payment description (shown to customer)
+   * @param {Object} [params.metadata] - Custom metadata (e.g., { orderId: 'ORD-123', customerId: 'CUST-456' })
+   * @returns {Promise<Object>} Created payment with address and QR code
+   *
+   * @example
+   * // Create a $50 payment in Bitcoin
+   * const payment = await client.createPayment({
+   *   businessId: 'your-business-id',
+   *   amount: 50.00,
+   *   currency: 'USD',
+   *   blockchain: 'BTC',
+   *   description: 'Order #12345',
+   *   metadata: { orderId: '12345', customerEmail: 'customer@example.com' }
+   * });
+   *
+   * // Display payment.payment_address and payment.qr_code to customer
    */
   async createPayment({
     businessId,
     amount,
-    currency,
-    cryptocurrency,
+    currency = 'USD',
+    blockchain,
     description,
     metadata,
-    callbackUrl,
   }) {
+    // Map to API field names (snake_case)
     return this.request('/payments/create', {
       method: 'POST',
       body: JSON.stringify({
-        businessId,
+        business_id: businessId,
         amount,
         currency,
-        cryptocurrency,
+        blockchain: blockchain?.toUpperCase(),
         description,
         metadata,
-        callbackUrl,
       }),
     });
   }
 
   /**
    * Get payment by ID
+   *
+   * Use this to check the current status of a payment. You can poll this
+   * endpoint to wait for payment completion, or use webhooks for real-time
+   * notifications.
+   *
    * @param {string} paymentId - Payment ID
-   * @returns {Promise<Object>} Payment details
+   * @returns {Promise<Object>} Payment details including status
+   *
+   * @example
+   * const result = await client.getPayment('pay_abc123');
+   * console.log(result.payment.status); // 'pending', 'confirmed', 'forwarded', etc.
    */
   async getPayment(paymentId) {
     return this.request(`/payments/${paymentId}`);
   }
 
+  /**
+   * Wait for payment to reach a terminal status
+   *
+   * Polls the payment status until it reaches a terminal state (confirmed,
+   * forwarded, expired, or failed). Useful for simple integrations that
+   * don't use webhooks.
+   *
+   * For production use, webhooks are recommended over polling.
+   *
+   * @param {string} paymentId - Payment ID
+   * @param {Object} [options] - Polling options
+   * @param {number} [options.interval=5000] - Polling interval in ms (default: 5 seconds)
+   * @param {number} [options.timeout=3600000] - Maximum wait time in ms (default: 1 hour)
+   * @param {string[]} [options.targetStatuses] - Statuses to wait for (default: ['confirmed', 'forwarded', 'expired', 'failed'])
+   * @param {Function} [options.onStatusChange] - Callback when status changes
+   * @returns {Promise<Object>} Final payment details
+   *
+   * @example
+   * // Simple usage - wait for payment to complete
+   * const payment = await client.waitForPayment('pay_abc123');
+   * if (payment.payment.status === 'confirmed' || payment.payment.status === 'forwarded') {
+   *   console.log('Payment successful!');
+   * }
+   *
+   * @example
+   * // With status change callback
+   * const payment = await client.waitForPayment('pay_abc123', {
+   *   interval: 3000,
+   *   timeout: 600000, // 10 minutes
+   *   onStatusChange: (status, payment) => {
+   *     console.log(`Payment status: ${status}`);
+   *   }
+   * });
+   */
+  async waitForPayment(paymentId, options = {}) {
+    const {
+      interval = 5000,
+      timeout = 3600000,
+      targetStatuses = ['confirmed', 'forwarded', 'expired', 'failed'],
+      onStatusChange,
+    } = options;
+
+    const startTime = Date.now();
+    let lastStatus = null;
+
+    while (Date.now() - startTime < timeout) {
+      const result = await this.getPayment(paymentId);
+      const currentStatus = result.payment?.status;
+
+      // Notify on status change
+      if (currentStatus !== lastStatus) {
+        if (onStatusChange && lastStatus !== null) {
+          onStatusChange(currentStatus, result.payment);
+        }
+        lastStatus = currentStatus;
+      }
+
+      // Check if we've reached a target status
+      if (targetStatuses.includes(currentStatus)) {
+        return result;
+      }
+
+      // Wait before next poll
+      await new Promise(resolve => setTimeout(resolve, interval));
+    }
+
+    throw new Error(`Payment status check timed out after ${timeout}ms`);
+  }
+
   /**
    * List payments for a business
    * @param {Object} params - Query parameters
@@ -140,13 +234,66 @@ export class CoinPayClient {
   }
 
   /**
-   * Get payment QR code
+   * Get payment QR code URL
+   *
+   * Returns the URL to the QR code image endpoint. The endpoint returns
+   * binary PNG image data that can be used directly in an <img> tag.
+   *
    * @param {string} paymentId - Payment ID
-   * @param {string} [format] - QR code format (png, svg)
-   * @returns {Promise<Object>} QR code data
+   * @returns {string} URL to the QR code image
+   *
+   * @example
+   * // Get QR code URL for use in HTML
+   * const qrUrl = client.getPaymentQRUrl('pay_abc123');
+   * // Use in HTML: <img src={qrUrl} alt="Payment QR Code" />
    */
-  async getPaymentQR(paymentId, format = 'png') {
-    return this.request(`/payments/${paymentId}/qr?format=${format}`);
+  getPaymentQRUrl(paymentId) {
+    return `${this.#baseUrl}/payments/${paymentId}/qr`;
+  }
+
+  /**
+   * Get payment QR code as binary image data
+   *
+   * Fetches the QR code image as binary data (ArrayBuffer).
+   * Useful for server-side processing or saving to file.
+   *
+   * @param {string} paymentId - Payment ID
+   * @returns {Promise<ArrayBuffer>} QR code image as binary data
+   *
+   * @example
+   * // Get QR code as binary data
+   * const imageData = await client.getPaymentQR('pay_abc123');
+   * // Save to file (Node.js)
+   * fs.writeFileSync('qr.png', Buffer.from(imageData));
+   */
+  async getPaymentQR(paymentId) {
+    const url = `${this.#baseUrl}/payments/${paymentId}/qr`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.#timeout);
+
+    try {
+      const response = await fetch(url, {
+        signal: controller.signal,
+        headers: {
+          'Authorization': `Bearer ${this.#apiKey}`,
+        },
+      });
+
+      if (!response.ok) {
+        const error = new Error(`HTTP ${response.status}`);
+        error.status = response.status;
+        throw error;
+      }
+
+      return response.arrayBuffer();
+    } catch (error) {
+      if (error.name === 'AbortError') {
+        throw new Error(`Request timeout after ${this.#timeout}ms`);
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
   }
 
   /**

package/src/index.js

@@ -3,10 +3,31 @@
  * Cryptocurrency payment integration for Node.js
  *
  * @module @profullstack/coinpay
+ *
+ * @example
+ * // Quick start
+ * import { CoinPayClient, Blockchain } from '@profullstack/coinpay';
+ *
+ * const client = new CoinPayClient({ apiKey: 'cp_live_xxxxx' });
+ *
+ * const payment = await client.createPayment({
+ *   businessId: 'your-business-id',
+ *   amount: 100,
+ *   blockchain: Blockchain.BTC,
+ *   description: 'Order #12345'
+ * });
  */
 
 import { CoinPayClient } from './client.js';
-import { createPayment, getPayment, listPayments } from './payments.js';
+import {
+  createPayment,
+  getPayment,
+  listPayments,
+  Blockchain,
+  Cryptocurrency,
+  PaymentStatus,
+  FiatCurrency,
+} from './payments.js';
 import {
   verifyWebhookSignature,
   generateWebhookSignature,
@@ -16,10 +37,21 @@ import {
 } from './webhooks.js';
 
 export {
+  // Client
   CoinPayClient,
+  
+  // Payment functions
   createPayment,
   getPayment,
   listPayments,
+  
+  // Constants
+  Blockchain,
+  Cryptocurrency,  // Deprecated, use Blockchain
+  PaymentStatus,
+  FiatCurrency,
+  
+  // Webhook utilities
   verifyWebhookSignature,
   generateWebhookSignature,
   parseWebhookPayload,

package/src/payments.js

@@ -1,33 +1,65 @@
 /**
  * Payment utilities for CoinPay SDK
+ *
+ * This module provides helper functions for creating and managing cryptocurrency payments.
+ *
+ * @example
+ * // Quick payment creation
+ * import { createPayment } from '@coinpay/sdk';
+ *
+ * const payment = await createPayment({
+ *   apiKey: 'cp_live_xxxxx',
+ *   businessId: 'your-business-id',
+ *   amount: 100.00,
+ *   blockchain: 'ETH',
+ *   description: 'Order #12345'
+ * });
  */
 
 import { CoinPayClient } from './client.js';
 
 /**
  * Create a payment using a client instance or API key
+ *
+ * This is a convenience function for creating payments without manually
+ * instantiating a client. For multiple operations, create a client instance
+ * and reuse it.
+ *
  * @param {Object} params - Payment parameters
- * @param {string} params.apiKey - API key (if not using client)
- * @param {CoinPayClient} [params.client] - Existing client instance
- * @param {string} params.businessId - Business ID
- * @param {number} params.amount - Amount in fiat currency
- * @param {string} params.currency - Fiat currency code
- * @param {string} params.cryptocurrency - Cryptocurrency code
- * @param {string} [params.description] - Payment description
- * @param {string} [params.metadata] - Custom metadata
- * @param {string} [params.callbackUrl] - Webhook callback URL
- * @returns {Promise<Object>} Created payment
+ * @param {string} params.apiKey - API key (required if not using client)
+ * @param {CoinPayClient} [params.client] - Existing client instance (optional)
+ * @param {string} params.businessId - Business ID from your CoinPay dashboard
+ * @param {number} params.amount - Amount in fiat currency (e.g., 100.00)
+ * @param {string} [params.currency='USD'] - Fiat currency code (USD, EUR, etc.)
+ * @param {string} params.blockchain - Blockchain to use (BTC, ETH, SOL, MATIC, BCH, USDC_ETH, USDC_MATIC, USDC_SOL)
+ * @param {string} [params.description] - Payment description shown to customer
+ * @param {Object} [params.metadata] - Custom metadata for your records
+ * @returns {Promise<Object>} Created payment with address and QR code
+ *
+ * @example
+ * // Create a Bitcoin payment
+ * const payment = await createPayment({
+ *   apiKey: 'cp_live_xxxxx',
+ *   businessId: 'biz_123',
+ *   amount: 50.00,
+ *   currency: 'USD',
+ *   blockchain: 'BTC',
+ *   description: 'Premium subscription',
+ *   metadata: { userId: 'user_456', plan: 'premium' }
+ * });
+ *
+ * console.log('Payment address:', payment.payment.payment_address);
+ * console.log('Amount in BTC:', payment.payment.crypto_amount);
  */
 export async function createPayment({
   apiKey,
   client,
   businessId,
   amount,
-  currency,
-  cryptocurrency,
+  currency = 'USD',
+  blockchain,
   description,
   metadata,
-  callbackUrl,
 }) {
   const coinpay = client || new CoinPayClient({ apiKey });
   
@@ -35,10 +67,9 @@ export async function createPayment({
     businessId,
     amount,
     currency,
-    cryptocurrency,
+    blockchain,
     description,
     metadata,
-    callbackUrl,
   });
 }
 
@@ -91,16 +122,44 @@ export const PaymentStatus = {
 };
 
 /**
- * Supported cryptocurrencies
+ * Supported blockchains/cryptocurrencies
+ *
+ * Use these constants when creating payments to ensure valid blockchain values.
+ *
+ * @example
+ * import { Blockchain, createPayment } from '@coinpay/sdk';
+ *
+ * const payment = await createPayment({
+ *   apiKey: 'cp_live_xxxxx',
+ *   businessId: 'biz_123',
+ *   amount: 100,
+ *   blockchain: Blockchain.ETH
+ * });
  */
-export const Cryptocurrency = {
+export const Blockchain = {
+  /** Bitcoin */
   BTC: 'BTC',
+  /** Bitcoin Cash */
   BCH: 'BCH',
+  /** Ethereum */
   ETH: 'ETH',
+  /** Polygon (MATIC) */
   MATIC: 'MATIC',
+  /** Solana */
   SOL: 'SOL',
+  /** USDC on Ethereum */
+  USDC_ETH: 'USDC_ETH',
+  /** USDC on Polygon */
+  USDC_MATIC: 'USDC_MATIC',
+  /** USDC on Solana */
+  USDC_SOL: 'USDC_SOL',
 };
 
+/**
+ * @deprecated Use Blockchain instead
+ */
+export const Cryptocurrency = Blockchain;
+
 /**
  * Supported fiat currencies
  */
@@ -117,6 +176,7 @@ export default {
   getPayment,
   listPayments,
   PaymentStatus,
+  Blockchain,
   Cryptocurrency,
   FiatCurrency,
 };