@x1pays/sdk

TypeScript SDK for the x402 payment protocol on X1 blockchain.

🚀 Features

• ✅ Simple API for x402 payments
• ✅ Sign and send payments with Solana keypairs
• ✅ Automatic payment verification
• ✅ Testnet and Mainnet support
• ✅ TypeScript support with full type definitions
• ✅ Lightweight and fast

📦 Installation

npm install @x1pays/sdk
# or
pnpm add @x1pays/sdk
# or
yarn add @x1pays/sdk

🔧 Quick Start

import { Keypair } from '@solana/web3.js';
import { getWithPayment, PayConfig } from '@x1pays/sdk';

// Load your wallet keypair
const payer = Keypair.fromSecretKey(/* your secret key */);

// Configure payment
const config: PayConfig = {
  facilitatorUrl: 'https://facilitator.x1pays.com',
  payTo: 'MERCHANT_ADDRESS_HERE',
  asset: 'wXNT_TOKEN_MINT_ADDRESS',
  network: 'x1-testnet', // or 'x1-mainnet'
  amountAtomic: '1000' // Amount in lamports (0.000001 wXNT)
};

// Make a payment-protected API call
const data = await getWithPayment(
  'https://api.example.com/protected-endpoint',
  payer,
  config
);

console.log('Response:', data);

📖 API Reference

getWithPayment(url, payer, config)

Makes an HTTP GET request with x402 payment authorization.

Parameters:

• url (string): The API endpoint to call
• payer (Keypair): Solana keypair for signing the payment
• config (PayConfig): Payment configuration object

Returns: Promise - The API response data

Throws: Error if payment is not accepted (402 status)

signPayment(payer, payload)

Signs a payment payload with the payer's keypair.

Parameters:

• payer (Keypair): Solana keypair for signing
• payload (object): Payment payload to sign

Returns: string - Base58 encoded signature

PayConfig

Payment configuration interface:

interface PayConfig {
  facilitatorUrl: string;      // X1Pays facilitator URL
  payTo: string;                // Merchant wallet address
  asset: string;                // wXNT token mint address
  network?: 'x1-mainnet' | 'x1-testnet';  // Default: 'x1-mainnet'
  amountAtomic: string;         // Amount in lamports
}

💡 Examples

Basic Payment

import { Keypair } from '@solana/web3.js';
import { getWithPayment } from '@x1pays/sdk';

const payer = Keypair.generate(); // Or load from file/env

try {
  const response = await getWithPayment(
    'https://api.example.com/data',
    payer,
    {
      facilitatorUrl: 'http://localhost:4000',
      payTo: 'MerchantPublicKeyHere',
      asset: 'wXNT_MINT_ADDRESS',
      network: 'x1-testnet',
      amountAtomic: '1000' // 0.000001 wXNT
    }
  );
  
  console.log('Success:', response);
} catch (error) {
  console.error('Payment failed:', error);
}

Using Environment Variables

import { Keypair } from '@solana/web3.js';
import { getWithPayment } from '@x1pays/sdk';
import bs58 from 'bs58';

// Load keypair from environment
const secretKey = bs58.decode(process.env.WALLET_SECRET_KEY!);
const payer = Keypair.fromSecretKey(secretKey);

const config = {
  facilitatorUrl: process.env.FACILITATOR_URL!,
  payTo: process.env.MERCHANT_ADDRESS!,
  asset: process.env.WXNT_MINT!,
  network: process.env.NETWORK as 'x1-testnet' | 'x1-mainnet',
  amountAtomic: process.env.PAYMENT_AMOUNT!
};

const data = await getWithPayment('/api/endpoint', payer, config);

Error Handling

try {
  const data = await getWithPayment(url, payer, config);
  console.log('Payment successful:', data);
} catch (error) {
  if (error instanceof Error) {
    if (error.message.includes('402')) {
      console.error('Payment was rejected by the server');
    } else if (error.message.includes('network')) {
      console.error('Network error - check your connection');
    } else {
      console.error('Unknown error:', error.message);
    }
  }
}

🔐 Security Best Practices

1. Never commit private keys - Use environment variables
2. Validate merchant addresses - Ensure you're paying the correct merchant
3. Use testnet first - Test your integration before going to mainnet
4. Monitor spending - Track your payment amounts
5. Secure keypair storage - Use secure key management for production

🌐 Network Configuration

Testnet

{
  network: 'x1-testnet',
  facilitatorUrl: 'http://localhost:4000', // Your testnet facilitator
  asset: 'TESTNET_WXNT_MINT'
}

Mainnet

{
  network: 'x1-mainnet',
  facilitatorUrl: 'https://facilitator.x1pays.com',
  asset: 'MAINNET_WXNT_MINT'
}

🛠️ Development

# Install dependencies
pnpm install

# Build the package
pnpm build

# Run tests
pnpm test

# Watch mode
pnpm dev

📚 Learn More

• X1Pays Documentation
• x402 Protocol Specification
• X1 Blockchain

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE file for details

🔗 Links

• GitHub
• NPM Package
• Website

💬 Support

• Discord: X1Pays Community
• Twitter: @X1Pays
• Email: [email protected]

Built with ❤️ by the X1Pays team