From 538d6fa5878cac56ba98d97f5b70ada052ffcc96 Mon Sep 17 00:00:00 2001 From: Daniel Oladepo <98762494+Danbaba1@users.noreply.github.com> Date: Thu, 10 Jul 2025 11:26:39 +0100 Subject: [PATCH 1/5] Create use-case.md --- submissions/wallet-danbaba1/use-case.md | 123 ++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 submissions/wallet-danbaba1/use-case.md diff --git a/submissions/wallet-danbaba1/use-case.md b/submissions/wallet-danbaba1/use-case.md new file mode 100644 index 0000000..93908f1 --- /dev/null +++ b/submissions/wallet-danbaba1/use-case.md @@ -0,0 +1,123 @@ +# Unlocking Global Financial Inclusion: How Interledger Wallet Addresses Transform Cross-Border Payments + +In today's interconnected world, the need for seamless, cost-effective cross-border payments has never been more critical. From freelancers receiving payments from international clients to families sending remittances across continents, traditional banking systems often fall short with high fees, slow processing times, and limited accessibility. This is where Chimoney's Interledger wallet address creation capability becomes a game-changer. + +## The Cross-Border Payment Challenge + +Consider Maria, a freelance graphic designer in Lagos, Nigeria, who works with clients across Europe and North America. Despite her growing client base, she faces several challenges: + +- **High transaction fees**: Traditional wire transfers can cost $15-50 per transaction +- **Slow processing**: International transfers often take 3-5 business days +- **Complex setup**: Opening international bank accounts requires extensive documentation +- **Exchange rate losses**: Multiple currency conversions eat into her earnings +- **Limited accessibility**: Some clients struggle with traditional payment methods + +Maria's story reflects the experiences of millions of professionals, small business owners, and individuals worldwide who need better financial infrastructure. + +## Enter Interledger Protocol and Chimoney + +The Interledger Protocol (ILP) represents a revolutionary approach to payments, creating an "internet of value" that enables seamless transfers across different payment networks, currencies, and institutions. Think of it as the HTTP of money – a universal standard that allows different financial systems to communicate and transfer value. + +Chimoney's implementation of Interledger wallet addresses provides users with a unique identifier that works across the global Interledger network. This address functions like an email address for money, making it incredibly simple to send and receive payments from anywhere in the world. + +## Real-World Use Cases + +### 1. Gig Economy and Freelancing + +**The Scenario**: Remote work has exploded globally, with platforms like Upwork, Fiverr, and Toptal connecting talent across borders. However, payment friction remains a significant challenge. + +**The Solution**: Freelancers can generate Interledger wallet addresses through Chimoney, enabling them to: +- Receive payments instantly from clients worldwide +- Eliminate intermediary bank fees +- Access funds in their local currency +- Maintain a professional payment setup with a single, memorable address + +**Example**: Instead of sharing complex bank details, David (freelancer in Kenya) simply shares his Interledger address: `david.kenya.chimoney.ilp` with his client in Germany. The client sends Euros, and David receives Kenyan Shillings instantly. + +### 2. International Remittances + +**The Scenario**: The World Bank estimates that remittances to low and middle-income countries reached $630 billion in 2022. Traditional channels like Western Union or MoneyGram often charge 6-10% in fees. + +**The Solution**: Migrant workers can use Chimoney's Interledger addresses to: +- Send money home with minimal fees +- Ensure faster delivery to family members +- Provide recipients with multiple redemption options (cash, mobile money, bank transfer) +- Track transactions transparently + +**Example**: Ahmed works in Dubai and needs to send money to his family in Bangladesh. Using his family's Interledger address, he can send AED that arrives as Bangladeshi Taka within minutes, not days. + +### 3. E-commerce and Digital Marketplaces + +**The Scenario**: Cross-border e-commerce continues to grow, but payment complexity often limits expansion into new markets. + +**The Solution**: Online businesses can integrate Interledger addresses to: +- Accept payments in customers' local currencies +- Reduce payment processing complexity +- Expand to markets previously considered too complex +- Offer customers familiar payment experiences + +**Example**: A craft marketplace based in Ghana can accept payments from customers in 50+ countries, with each customer paying in their preferred currency while the merchant receives Ghana Cedis. + +### 4. Charity and Non-Profit Organizations + +**The Scenario**: International NGOs and charities often lose significant portions of donations to transfer fees and currency conversion costs. + +**The Solution**: Organizations can use Interledger addresses to: +- Maximize the impact of every donation +- Provide transparent, trackable giving experiences +- Reduce operational overhead +- Enable micro-donations from global supporters + +**Example**: A education NGO in rural Tanzania can receive donations from supporters worldwide, with 98% of each donation reaching its intended purpose instead of being lost to fees. + +### 5. Supply Chain and B2B Payments + +**The Scenario**: Global supply chains involve complex payment flows between suppliers, manufacturers, and distributors across multiple countries. + +**The Solution**: Businesses can streamline payments using Interledger addresses to: +- Automate supplier payments across borders +- Reduce settlement times from weeks to minutes +- Lower transaction costs for high-volume operations +- Improve cash flow management + +**Example**: A electronics manufacturer in Shenzhen can instantly pay component suppliers in Taiwan, Thailand, and Malaysia using their respective Interledger addresses, optimizing working capital across the entire supply chain. + +## The Technical Advantage + +Chimoney's Interledger wallet address creation offers several technical benefits: + +- **Interoperability**: Works with any Interledger-enabled system globally +- **Programmability**: Enables automatic, conditional payments +- **Transparency**: All transactions are cryptographically verifiable +- **Scalability**: Can handle micro-payments to large transfers efficiently +- **Currency Agnostic**: Supports any currency or token +- **Always Available**: 24/7 operation without banking hour restrictions + +## Economic Impact + +The broader economic implications of widespread Interledger adoption through platforms like Chimoney include: + +- **Financial Inclusion**: Bringing unbanked populations into the global economy +- **Reduced Friction**: Lowering barriers to international trade and collaboration +- **Economic Growth**: Enabling new business models and revenue streams +- **Innovation Catalyst**: Fostering fintech innovation in developing markets +- **Cost Savings**: Redirecting billions in transaction fees toward productive uses + +## Looking Forward + +As the Interledger ecosystem matures, Chimoney's wallet address functionality positions users at the forefront of the financial revolution. Early adopters will benefit from: + +- **Network Effects**: Growing value as more participants join +- **Platform Advantages**: Access to expanding services and integrations +- **Cost Benefits**: Decreasing fees as the network scales +- **Innovation Access**: First access to new financial products and services + +## Conclusion + +Chimoney's Interledger wallet address creation capability isn't just a technical feature – it's a pathway to financial inclusion and global economic participation. Whether you're a freelancer in Lagos, a small business owner in Bangkok, or a non-profit in Nairobi, this technology can transform how you interact with the global economy. + +The future of payments is programmable, borderless, and inclusive. With Chimoney's Interledger integration, that future is available today. + +--- + +*Ready to create your own Interledger wallet address? Check out our comprehensive tutorial guide and setup instructions to get started in minutes.* From 50acafaf1ae5a855d1ceaa0b45e3026c4a77f06d Mon Sep 17 00:00:00 2001 From: Daniel Oladepo <98762494+Danbaba1@users.noreply.github.com> Date: Thu, 10 Jul 2025 11:51:09 +0100 Subject: [PATCH 2/5] Create tutorial.md --- submissions/wallet-danbaba1/tutorial.md | 655 ++++++++++++++++++++++++ 1 file changed, 655 insertions(+) create mode 100644 submissions/wallet-danbaba1/tutorial.md diff --git a/submissions/wallet-danbaba1/tutorial.md b/submissions/wallet-danbaba1/tutorial.md new file mode 100644 index 0000000..86058df --- /dev/null +++ b/submissions/wallet-danbaba1/tutorial.md @@ -0,0 +1,655 @@ +# Complete Tutorial: Creating Interledger Wallet Addresses with Chimoney API + +This comprehensive tutorial will walk you through the process of creating Interledger wallet addresses using the Chimoney API. By the end of this guide, you'll understand how to integrate this functionality into your applications and provide users with seamless cross-border payment capabilities. + +## Table of Contents + +1. [Understanding Interledger Wallet Addresses](#understanding-interledger-wallet-addresses) +2. [Prerequisites](#prerequisites) +3. [API Endpoint Overview](#api-endpoint-overview) +4. [Step-by-Step Implementation](#step-by-step-implementation) +5. [Error Handling](#error-handling) +6. [Testing Your Integration](#testing-your-integration) +7. [Best Practices](#best-practices) +8. [Next Steps](#next-steps) + +## Understanding Interledger Wallet Addresses + +An Interledger wallet address is like an email address for money. It's a unique identifier that allows users to send and receive payments across different networks and currencies seamlessly. When you create an Interledger wallet address through Chimoney, you're essentially giving a user a global payment endpoint that works 24/7. + +### Key Benefits + +- Universal compatibility across Interledger-enabled systems +- Instant cross-border transactions +- Minimal transaction fees +- Support for multiple currencies +- Programmable payment conditions + +## Prerequisites + +Before you begin, ensure you have: + +- **Chimoney Developer Account**: Sign up at [dash.chimoney.io](https://dash.chimoney.io) +- **API Access**: Request verification and API access by emailing support@chimoney.io +- **API Key**: Obtain from your Chimoney developer dashboard +- **Development Environment**: Node.js, Python, or your preferred programming language +- **Basic Understanding**: REST APIs and HTTP requests + +## API Endpoint Overview + +**Endpoint**: `POST /v0.2.4/accounts/issue-wallet-address` +**Base URL**: `https://api.chimoney.io/` +**Authentication**: API Key (X-API-KEY header) + +### Request Parameters + +```json +{ + "userID": "string", + "ilpUsername": "string" +} +``` + +- `userID`: Unique identifier for the user in your system +- `ilpUsername`: Desired username for the Interledger address (should follow naming conventions) + +### Response Format + +```json +{ + "status": "success", + "message": "Wallet Address issued successfully", + "data": "walletAddress123" +} +``` + +## Step-by-Step Implementation + +### Step 1: Set Up Your Environment + +First, let's set up the basic structure for making API calls to Chimoney. + +#### For Node.js: + +```javascript +// Install required dependencies +// npm install axios dotenv + +const axios = require('axios'); +require('dotenv').config(); + +// Configuration +const CHIMONEY_BASE_URL = 'https://api.chimoney.io'; +const API_KEY = process.env.CHIMONEY_API_KEY; + +// Create axios instance with default headers +const chimoneyAPI = axios.create({ + baseURL: CHIMONEY_BASE_URL, + headers: { + 'X-API-KEY': API_KEY, + 'Content-Type': 'application/json' + } +}); +``` + +#### For Python: + +```python +# Install required dependencies +# pip install requests python-dotenv + +import requests +import os +from dotenv import load_dotenv +import json + +# Load environment variables +load_dotenv() + +# Configuration +CHIMONEY_BASE_URL = 'https://api.chimoney.io' +API_KEY = os.getenv('CHIMONEY_API_KEY') + +# Default headers +headers = { + 'X-API-KEY': API_KEY, + 'Content-Type': 'application/json' +} +``` + +### Step 2: Create the Wallet Address Function + +#### Node.js Implementation: + +```javascript +async function createInterledgerWalletAddress(userID, ilpUsername) { + try { + // Validate input parameters + if (!userID || !ilpUsername) { + throw new Error('Both userID and ilpUsername are required'); + } + + // Prepare request payload + const payload = { + userID: userID, + ilpUsername: ilpUsername + }; + + console.log('Creating Interledger wallet address...'); + console.log('Payload:', JSON.stringify(payload, null, 2)); + + // Make API request + const response = await chimoneyAPI.post('/v0.2.4/accounts/issue-wallet-address', payload); + + // Handle successful response + if (response.data.status === 'success') { + console.log('✅ Wallet address created successfully!'); + console.log('Wallet Address:', response.data.data); + + return { + success: true, + walletAddress: response.data.data, + message: response.data.message + }; + } else { + throw new Error(response.data.message || 'Failed to create wallet address'); + } + + } catch (error) { + console.error('❌ Error creating wallet address:', error.message); + + if (error.response) { + // Handle specific error responses + console.error('Status:', error.response.status); + console.error('Error details:', error.response.data); + + return { + success: false, + error: error.response.data, + statusCode: error.response.status + }; + } + + return { + success: false, + error: error.message + }; + } +} +``` + +#### Python Implementation: + +```python +def create_interledger_wallet_address(user_id, ilp_username): + """ + Create an Interledger wallet address for a user + + Args: + user_id (str): Unique identifier for the user + ilp_username (str): Desired username for the Interledger address + + Returns: + dict: Response containing success status and wallet address or error details + """ + try: + # Validate input parameters + if not user_id or not ilp_username: + raise ValueError('Both user_id and ilp_username are required') + + # Prepare request payload + payload = { + 'userID': user_id, + 'ilpUsername': ilp_username + } + + print('Creating Interledger wallet address...') + print(f'Payload: {json.dumps(payload, indent=2)}') + + # Make API request + response = requests.post( + f'{CHIMONEY_BASE_URL}/v0.2.4/accounts/issue-wallet-address', + headers=headers, + json=payload, + timeout=30 + ) + + # Parse response + response_data = response.json() + + # Handle successful response + if response.status_code == 200 and response_data.get('status') == 'success': + print('✅ Wallet address created successfully!') + print(f'Wallet Address: {response_data["data"]}') + + return { + 'success': True, + 'wallet_address': response_data['data'], + 'message': response_data['message'] + } + else: + # Handle error response + error_message = response_data.get('message', 'Failed to create wallet address') + raise Exception(error_message) + + except requests.exceptions.RequestException as e: + print(f'❌ Request error: {str(e)}') + return { + 'success': False, + 'error': f'Request failed: {str(e)}' + } + except Exception as e: + print(f'❌ Error creating wallet address: {str(e)}') + return { + 'success': False, + 'error': str(e) + } +``` + +### Step 3: Username Validation and Generation + +Implement helper functions to ensure proper username formatting: + +#### Node.js: + +```javascript +function validateILPUsername(username) { + // ILP usernames should be lowercase alphanumeric with underscores/hyphens + const regex = /^[a-z0-9_-]+$/; + + if (!regex.test(username)) { + return { + valid: false, + message: 'Username must contain only lowercase letters, numbers, hyphens, and underscores' + }; + } + + if (username.length < 3 || username.length > 30) { + return { + valid: false, + message: 'Username must be between 3 and 30 characters' + }; + } + + return { valid: true }; +} + +function generateILPUsername(userID, email) { + // Generate a suggested username based on user data + let baseUsername; + + if (email) { + baseUsername = email.split('@')[0].toLowerCase(); + } else { + baseUsername = `user_${userID}`; + } + + // Clean the username + const cleanUsername = baseUsername + .replace(/[^a-z0-9_-]/g, '_') + .replace(/_{2,}/g, '_') + .replace(/^_|_$/g, ''); + + return cleanUsername || `user_${userID}`; +} +``` + +#### Python: + +```python +import re + +def validate_ilp_username(username): + """Validate ILP username format""" + pattern = r'^[a-z0-9_-]+$' + + if not re.match(pattern, username): + return { + 'valid': False, + 'message': 'Username must contain only lowercase letters, numbers, hyphens, and underscores' + } + + if len(username) < 3 or len(username) > 30: + return { + 'valid': False, + 'message': 'Username must be between 3 and 30 characters' + } + + return {'valid': True} + +def generate_ilp_username(user_id, email=None): + """Generate a suggested ILP username""" + if email: + base_username = email.split('@')[0].lower() + else: + base_username = f'user_{user_id}' + + # Clean the username + clean_username = re.sub(r'[^a-z0-9_-]', '_', base_username) + clean_username = re.sub(r'_{2,}', '_', clean_username) + clean_username = clean_username.strip('_') + + return clean_username or f'user_{user_id}' +``` + +### Step 4: Complete Integration Example + +Here's a complete example showing how to integrate wallet address creation into a user registration flow: + +#### Node.js: + +```javascript +async function registerUserWithWallet(userData) { + try { + const { userID, email, firstName, lastName } = userData; + + // Generate suggested username + const suggestedUsername = generateILPUsername(userID, email); + + // Validate username + const validation = validateILPUsername(suggestedUsername); + if (!validation.valid) { + throw new Error(`Username validation failed: ${validation.message}`); + } + + console.log(`Registering user ${userID} with ILP username: ${suggestedUsername}`); + + // Create Interledger wallet address + const walletResult = await createInterledgerWalletAddress(userID, suggestedUsername); + + if (walletResult.success) { + // Save wallet address to your database + const userRecord = { + userID, + email, + firstName, + lastName, + interledgerAddress: walletResult.walletAddress, + ilpUsername: suggestedUsername, + createdAt: new Date(), + status: 'active' + }; + + // Here you would save to your database + console.log('User registered successfully with wallet:', userRecord); + + return { + success: true, + user: userRecord, + walletAddress: walletResult.walletAddress + }; + } else { + throw new Error(`Failed to create wallet: ${walletResult.error}`); + } + + } catch (error) { + console.error('Registration failed:', error.message); + return { + success: false, + error: error.message + }; + } +} + +// Usage example +async function example() { + const result = await registerUserWithWallet({ + userID: 'user_12345', + email: 'john.doe@example.com', + firstName: 'John', + lastName: 'Doe' + }); + + if (result.success) { + console.log('🎉 User registration completed!'); + console.log('Wallet Address:', result.walletAddress); + } else { + console.log('❌ Registration failed:', result.error); + } +} +``` + +## Error Handling + +Implement comprehensive error handling for different scenarios: + +```javascript +function handleChimoneyError(error) { + if (error.response) { + const { status, data } = error.response; + + switch (status) { + case 400: + return { + type: 'validation_error', + message: 'Invalid request parameters', + details: data + }; + case 401: + return { + type: 'authentication_error', + message: 'Invalid or missing API key', + details: data + }; + case 403: + return { + type: 'authorization_error', + message: 'API access not enabled for account', + details: data + }; + case 500: + return { + type: 'server_error', + message: 'Internal server error occurred', + details: data + }; + default: + return { + type: 'unknown_error', + message: `Unexpected error: ${status}`, + details: data + }; + } + } else if (error.request) { + return { + type: 'network_error', + message: 'No response received from server', + details: error.message + }; + } else { + return { + type: 'client_error', + message: 'Error setting up the request', + details: error.message + }; + } +} +``` + +## Testing Your Integration + +### Unit Tests + +```javascript +// Jest unit test example +describe('Interledger Wallet Address Creation', () => { + test('should validate username correctly', () => { + expect(validateILPUsername('valid_username')).toEqual({ valid: true }); + expect(validateILPUsername('INVALID')).toEqual({ + valid: false, + message: expect.any(String) + }); + }); + + test('should generate username from email', () => { + const username = generateILPUsername('123', 'test@example.com'); + expect(username).toBe('test'); + }); + + test('should handle API errors gracefully', async () => { + // Mock API failure + const result = await createInterledgerWalletAddress('', ''); + expect(result.success).toBe(false); + expect(result.error).toBeDefined(); + }); +}); +``` + +### Integration Testing + +```javascript +async function testWalletCreation() { + console.log('🧪 Testing wallet address creation...'); + + const testCases = [ + { + name: 'Valid user data', + userID: 'test_user_001', + ilpUsername: 'test_user_001', + expectedSuccess: true + }, + { + name: 'Invalid username', + userID: 'test_user_002', + ilpUsername: 'INVALID USERNAME!', + expectedSuccess: false + }, + { + name: 'Missing userID', + userID: '', + ilpUsername: 'valid_username', + expectedSuccess: false + } + ]; + + for (const testCase of testCases) { + console.log(`\nTesting: ${testCase.name}`); + + const result = await createInterledgerWalletAddress( + testCase.userID, + testCase.ilpUsername + ); + + const passed = result.success === testCase.expectedSuccess; + console.log(passed ? '✅ PASS' : '❌ FAIL'); + + if (!passed) { + console.log('Expected:', testCase.expectedSuccess, 'Got:', result.success); + console.log('Result:', result); + } + } +} +``` + +## Best Practices + +### 1. Security Considerations + +```javascript +// Store API keys securely +const API_KEY = process.env.CHIMONEY_API_KEY; +if (!API_KEY) { + throw new Error('CHIMONEY_API_KEY environment variable is required'); +} + +// Validate input data +function sanitizeInput(input) { + if (typeof input !== 'string') { + throw new Error('Input must be a string'); + } + return input.trim().toLowerCase(); +} +``` + +### 2. Rate Limiting + +```javascript +// Implement rate limiting to avoid API throttling +const rateLimit = require('express-rate-limit'); + +const walletCreationLimiter = rateLimit({ + windowMs: 15 * 60 * 1000, // 15 minutes + max: 10, // Limit each IP to 10 wallet creations per windowMs + message: 'Too many wallet creation requests, please try again later' +}); +``` + +### 3. Logging and Monitoring + +```javascript +function logWalletCreation(userID, success, walletAddress = null, error = null) { + const logData = { + timestamp: new Date().toISOString(), + action: 'wallet_creation', + userID, + success, + walletAddress, + error: error ? error.message : null + }; + + console.log(JSON.stringify(logData)); + + // Send to monitoring service (e.g., DataDog, New Relic) + // monitoring.track('wallet_creation', logData); +} +``` + +### 4. Caching and Database Storage + +```javascript +async function createAndStoreWallet(userID, ilpUsername) { + // Check if wallet already exists + const existingWallet = await db.findWalletByUserID(userID); + if (existingWallet) { + return { + success: true, + walletAddress: existingWallet.address, + message: 'Wallet already exists' + }; + } + + // Create new wallet + const result = await createInterledgerWalletAddress(userID, ilpUsername); + + if (result.success) { + // Store in database + await db.saveWallet({ + userID, + ilpUsername, + walletAddress: result.walletAddress, + createdAt: new Date(), + provider: 'chimoney' + }); + } + + return result; +} +``` + +## Next Steps + +After successfully implementing Interledger wallet address creation, consider these enhancements: + +- **Wallet Management**: Implement functions to retrieve and update wallet information +- **Payment Integration**: Add functionality to send and receive payments to/from these addresses +- **Multi-Currency Support**: Explore Chimoney's multi-currency wallet features +- **Analytics**: Track wallet usage and transaction patterns +- **User Interface**: Build a user-friendly interface for wallet management +- **Mobile Integration**: Implement mobile SDK for wallet functionality + +## Conclusion + +You now have the knowledge and tools to integrate Interledger wallet address creation into your applications using the Chimoney API. This functionality opens up a world of possibilities for cross-border payments, remittances, and global financial services. + +Remember to: +- Always validate input data +- Handle errors gracefully +- Implement proper security measures +- Test thoroughly before going to production +- Monitor your integration for issues + +The combination of Interledger Protocol and Chimoney's robust API provides a powerful foundation for building the next generation of financial applications. + +--- + +*Need help? Join the Chimoney Discord community [Chimoney](https://discord.gg/TsyKnzT4qV) or check out our comprehensive setup guide for additional support.* From 87d206530aaa92ba70ecbe098faea1381397b419 Mon Sep 17 00:00:00 2001 From: Daniel Oladepo <98762494+Danbaba1@users.noreply.github.com> Date: Thu, 10 Jul 2025 11:59:19 +0100 Subject: [PATCH 3/5] Create setup.md --- submissions/wallet-danbaba1/setup.md | 899 +++++++++++++++++++++++++++ 1 file changed, 899 insertions(+) create mode 100644 submissions/wallet-danbaba1/setup.md diff --git a/submissions/wallet-danbaba1/setup.md b/submissions/wallet-danbaba1/setup.md new file mode 100644 index 0000000..790b5b0 --- /dev/null +++ b/submissions/wallet-danbaba1/setup.md @@ -0,0 +1,899 @@ +# Complete Setup Guide: Chimoney API Authentication and Environment Configuration + +This comprehensive setup guide will walk you through everything you need to get started with the Chimoney API, from account creation to making your first successful API call. By the end of this guide, you'll have a fully configured development environment ready to create Interledger wallet addresses. + +## Table of Contents + +1. [Account Setup](#account-setup) +2. [API Access Request](#api-access-request) +3. [Development Environment Setup](#development-environment-setup) +4. [Authentication Configuration](#authentication-configuration) +5. [Testing Your Setup](#testing-your-setup) +6. [Environment Variables](#environment-variables) +7. [Postman Collection](#postman-collection) +8. [Troubleshooting](#troubleshooting) +9. [Security Best Practices](#security-best-practices) +10. [Next Steps](#next-steps) + +## Account Setup + +### Step 1: Create Your Chimoney Account + +**Visit the Chimoney Dashboard** +- Navigate to `dash.chimoney.io` +- Click "Sign Up" to create a new account + +**Complete Registration** + +Required Information: +- Full Name +- Email Address +- Phone Number +- Country +- Business/Organization Name (if applicable) +- Password (minimum 8 characters) + +**Email Verification** +- Check your email for a verification link +- Click the link to verify your account +- You should now be able to log into the dashboard + +**Initial Dashboard Exploration** +- Familiarize yourself with the dashboard layout +- Note the navigation menu and available sections +- Look for the "API" or "Developer" section + +### Step 2: Profile Completion + +**Complete Your Profile** +- Add your profile picture (optional) +- Fill in any missing business information +- Verify your phone number if prompted + +**Security Settings** +- Enable two-factor authentication (2FA) - **Highly Recommended** +- Set up security questions +- Review login history + +## API Access Request + +### Step 3: Request API Access + +> ⚠️ **Important**: API access requires verification and approval from Chimoney. + +**Prepare Your Application** +- Document your use case clearly +- Prepare your website/application URL +- Have your business documentation ready + +**Send Verification Request** + +**To:** support@chimoney.io +**Subject:** API Access Request - [Your Company/Project Name] + +``` +Dear Chimoney Team, + +I am requesting API access for my [business/project] to integrate Chimoney's +payment services. Here are the details: + +Company/Project Name: [Your Name] +Website: [Your Website URL] +Use Case: [Describe your specific use case, e.g., "Creating Interledger +wallet addresses for freelancers to receive international payments"] +Expected Volume: [Estimated monthly transaction volume] +Target Markets: [Countries/regions you plan to serve] + +Additional Information: +- [Any relevant business licenses or registrations] +- [Previous experience with payment APIs] +- [Technical team size and expertise] + +Thank you for your consideration. + +Best regards, +[Your Name] +[Your Title] +[Your Contact Information] +``` + +**Alternative: Book a Demo** +- Visit Chimoney's demo booking page +- Schedule a call to discuss your use case +- This can expedite the approval process + +### Step 4: Wait for Approval + +- **Timeline**: Typically 1-3 business days +- **Follow-up**: If no response within 5 days, send a polite follow-up email +- **Approval Notification**: You'll receive an email confirming API access + +## Development Environment Setup + +### Step 5: Choose Your Development Stack + +**Recommended Environments:** + +#### Node.js Setup: + +```bash +# Check Node.js version (recommended: 16+) +node --version + +# If Node.js is not installed, visit https://nodejs.org/ +# Create a new project directory +mkdir chimoney-integration +cd chimoney-integration + +# Initialize npm project +npm init -y + +# Install required dependencies +npm install axios dotenv +npm install --save-dev jest nodemon + +# Create basic project structure +mkdir src +mkdir tests +mkdir config + +# Create essential files +touch .env +touch .env.example +touch .gitignore +touch src/chimoney-client.js +touch src/wallet-service.js +touch tests/wallet.test.js +``` + +#### Python Setup: + +```bash +# Check Python version (recommended: 3.8+) +python --version + +# Create virtual environment +python -m venv chimoney-env + +# Activate virtual environment +# On Windows: +chimoney-env\Scripts\activate +# On macOS/Linux: +source chimoney-env/bin/activate + +# Install required packages +pip install requests python-dotenv pytest + +# Create project structure +mkdir chimoney_integration +mkdir tests +mkdir config + +# Create essential files +touch .env +touch .env.example +touch .gitignore +touch chimoney_integration/__init__.py +touch chimoney_integration/client.py +touch chimoney_integration/wallet_service.py +touch tests/test_wallet.py +touch requirements.txt +``` + +#### PHP Setup: + +```bash +# Check PHP version (recommended: 8.0+) +php --version + +# Install Composer (if not already installed) +# Visit https://getcomposer.org/ + +# Create project directory +mkdir chimoney-integration +cd chimoney-integration + +# Initialize composer +composer init + +# Install dependencies +composer require guzzlehttp/guzzle vlucas/phpdotenv +composer require --dev phpunit/phpunit + +# Create project structure +mkdir src +mkdir tests +mkdir config + +# Create essential files +touch .env +touch .env.example +touch .gitignore +touch src/ChimoneyClient.php +touch src/WalletService.php +touch tests/WalletTest.php +``` + +### Step 6: Set Up Your .gitignore File + +Create a `.gitignore` file to protect sensitive information: + +```gitignore +# Environment variables +.env +.env.local +.env.*.local + +# Dependencies +node_modules/ +vendor/ +__pycache__/ +*.pyc + +# IDE files +.vscode/ +.idea/ +*.swp +*.swo + +# OS files +.DS_Store +Thumbs.db + +# Log files +*.log +logs/ + +# Testing +coverage/ +.nyc_output/ +.pytest_cache/ + +# Build outputs +dist/ +build/ +``` + +## Authentication Configuration + +### Step 7: Obtain Your API Key + +Once your API access is approved: + +**Log into Chimoney Dashboard** +- Go to `dash.chimoney.io` +- Navigate to the "API Keys" or "Developer" section + +**Generate API Key** +- Click "Generate New API Key" or similar button +- Copy the generated key immediately +- Store it securely (you may not be able to view it again) + +**API Key Format** + +Your API key will look something like: +``` +sk_live_1234567890abcdef1234567890abcdef +``` +or +``` +sk_test_1234567890abcdef1234567890abcdef +``` + +### Step 8: Configure Environment Variables + +Create your `.env` file with the following structure: + +```env +# Chimoney API Configuration +CHIMONEY_API_KEY=your_api_key_here +CHIMONEY_BASE_URL=https://api.chimoney.io +CHIMONEY_ENVIRONMENT=sandbox # or 'production' + +# Application Configuration +APP_NAME=Chimoney Integration +APP_ENV=development +APP_DEBUG=true + +# Database Configuration (if needed) +DB_HOST=localhost +DB_PORT=5432 +DB_NAME=chimoney_app +DB_USER=your_db_user +DB_PASS=your_db_password + +# Logging Configuration +LOG_LEVEL=debug +LOG_FILE=logs/app.log + +# Rate Limiting +RATE_LIMIT_WINDOW=15 # minutes +RATE_LIMIT_MAX_REQUESTS=100 + +# Webhook Configuration (for future use) +WEBHOOK_SECRET=your_webhook_secret +WEBHOOK_URL=https://your-domain.com/webhooks/chimoney +``` + +Create an `.env.example` file for your team: + +```env +# Copy this file to .env and fill in your actual values +CHIMONEY_API_KEY=sk_test_your_api_key_here +CHIMONEY_BASE_URL=https://api.chimoney.io +CHIMONEY_ENVIRONMENT=sandbox +APP_NAME=Chimoney Integration +APP_ENV=development +APP_DEBUG=true +DB_HOST=localhost +DB_PORT=5432 +DB_NAME=chimoney_app +DB_USER=your_db_user +DB_PASS=your_db_password +LOG_LEVEL=debug +LOG_FILE=logs/app.log +RATE_LIMIT_WINDOW=15 +RATE_LIMIT_MAX_REQUESTS=100 +WEBHOOK_SECRET=your_webhook_secret_here +WEBHOOK_URL=https://your-domain.com/webhooks/chimoney +``` + +## Testing Your Setup + +### Step 9: Create Your First API Client + +#### Node.js Client: + +```javascript +// src/chimoney-client.js +const axios = require('axios'); +require('dotenv').config(); + +class ChimoneyClient { + constructor() { + this.apiKey = process.env.CHIMONEY_API_KEY; + this.baseURL = process.env.CHIMONEY_BASE_URL || 'https://api.chimoney.io'; + + if (!this.apiKey) { + throw new Error('CHIMONEY_API_KEY is required in environment variables'); + } + + this.client = axios.create({ + baseURL: this.baseURL, + headers: { + 'X-API-KEY': this.apiKey, + 'Content-Type': 'application/json', + 'User-Agent': 'Chimoney-Integration/1.0' + }, + timeout: 30000 // 30 seconds + }); + + // Add request interceptor for logging + this.client.interceptors.request.use( + (config) => { + console.log(`Making ${config.method.toUpperCase()} request to ${config.url}`); + return config; + }, + (error) => { + console.error('Request error:', error); + return Promise.reject(error); + } + ); + + // Add response interceptor for error handling + this.client.interceptors.response.use( + (response) => { + console.log(`Response received: ${response.status}`); + return response; + }, + (error) => { + console.error('Response error:', error.response?.data || error.message); + return Promise.reject(error); + } + ); + } + + async testConnection() { + try { + // Test with a simple endpoint + const response = await this.client.get('/v0.2.4/info/assets'); + return { + success: true, + message: 'Connection successful', + data: response.data + }; + } catch (error) { + return { + success: false, + message: 'Connection failed', + error: error.response?.data || error.message + }; + } + } +} + +module.exports = ChimoneyClient; +``` + +#### Python Client: + +```python +# chimoney_integration/client.py +import os +import requests +import json +from dotenv import load_dotenv + +# Load environment variables +load_dotenv() + +class ChimoneyClient: + def __init__(self): + self.api_key = os.getenv('CHIMONEY_API_KEY') + self.base_url = os.getenv('CHIMONEY_BASE_URL', 'https://api.chimoney.io') + + if not self.api_key: + raise ValueError('CHIMONEY_API_KEY is required in environment variables') + + self.headers = { + 'X-API-KEY': self.api_key, + 'Content-Type': 'application/json', + 'User-Agent': 'Chimoney-Integration/1.0' + } + + def _make_request(self, method, endpoint, data=None): + """Make HTTP request to Chimoney API""" + url = f"{self.base_url}{endpoint}" + + print(f"Making {method.upper()} request to {url}") + + try: + response = requests.request( + method=method, + url=url, + headers=self.headers, + json=data, + timeout=30 + ) + + print(f"Response received: {response.status_code}") + + # Parse JSON response + response_data = response.json() + + if response.status_code == 200: + return { + 'success': True, + 'data': response_data, + 'status_code': response.status_code + } + else: + return { + 'success': False, + 'error': response_data, + 'status_code': response.status_code + } + + except requests.exceptions.RequestException as e: + print(f"Request error: {str(e)}") + return { + 'success': False, + 'error': f'Request failed: {str(e)}' + } + except json.JSONDecodeError as e: + print(f"JSON decode error: {str(e)}") + return { + 'success': False, + 'error': f'Invalid JSON response: {str(e)}' + } + + def test_connection(self): + """Test API connection""" + try: + result = self._make_request('GET', '/v0.2.4/info/assets') + + if result['success']: + return { + 'success': True, + 'message': 'Connection successful', + 'data': result['data'] + } + else: + return { + 'success': False, + 'message': 'Connection failed', + 'error': result['error'] + } + + except Exception as e: + return { + 'success': False, + 'message': 'Connection test failed', + 'error': str(e) + } +``` + +### Step 10: Test Your Configuration + +Create a test script to verify everything is working: + +#### Node.js Test: + +```javascript +// tests/setup-test.js +const ChimoneyClient = require('../src/chimoney-client'); + +async function testSetup() { + console.log('🧪 Testing Chimoney API Setup...\n'); + + try { + // Test 1: Environment Variables + console.log('1. Checking environment variables...'); + const requiredVars = ['CHIMONEY_API_KEY', 'CHIMONEY_BASE_URL']; + const missingVars = requiredVars.filter(varName => !process.env[varName]); + + if (missingVars.length > 0) { + console.log('❌ Missing environment variables:', missingVars); + return; + } + console.log('✅ Environment variables configured correctly\n'); + + // Test 2: API Key Format + console.log('2. Validating API key format...'); + const apiKey = process.env.CHIMONEY_API_KEY; + if (!apiKey.startsWith('sk_')) { + console.log('⚠️ Warning: API key should start with "sk_"'); + } + console.log('✅ API key format looks valid\n'); + + // Test 3: API Connection + console.log('3. Testing API connection...'); + const client = new ChimoneyClient(); + const connectionTest = await client.testConnection(); + + if (connectionTest.success) { + console.log('✅ API connection successful!'); + console.log('📊 Available assets:', connectionTest.data?.data?.length || 0); + } else { + console.log('❌ API connection failed:', connectionTest.error); + return; + } + + console.log('\n🎉 Setup test completed successfully!'); + console.log('You are ready to start integrating with Chimoney API.'); + + } catch (error) { + console.error('❌ Setup test failed:', error.message); + } +} + +// Run the test +testSetup(); +``` + +#### Python Test: + +```python +# tests/test_setup.py +import os +import sys +sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) + +from chimoney_integration.client import ChimoneyClient + +def test_setup(): + print('🧪 Testing Chimoney API Setup...\n') + + try: + # Test 1: Environment Variables + print('1. Checking environment variables...') + required_vars = ['CHIMONEY_API_KEY', 'CHIMONEY_BASE_URL'] + missing_vars = [var for var in required_vars if not os.getenv(var)] + + if missing_vars: + print(f'❌ Missing environment variables: {missing_vars}') + return + print('✅ Environment variables configured correctly\n') + + # Test 2: API Key Format + print('2. Validating API key format...') + api_key = os.getenv('CHIMONEY_API_KEY') + if not api_key.startswith('sk_'): + print('⚠️ Warning: API key should start with "sk_"') + print('✅ API key format looks valid\n') + + # Test 3: API Connection + print('3. Testing API connection...') + client = ChimoneyClient() + connection_test = client.test_connection() + + if connection_test['success']: + print('✅ API connection successful!') + assets_count = len(connection_test['data'].get('data', [])) if connection_test['data'] else 0 + print(f'📊 Available assets: {assets_count}') + else: + print(f'❌ API connection failed: {connection_test["error"]}') + return + + print('\n🎉 Setup test completed successfully!') + print('You are ready to start integrating with Chimoney API.') + + except Exception as error: + print(f'❌ Setup test failed: {str(error)}') + +if __name__ == '__main__': + test_setup() +``` + +**Run your test:** + +```bash +# Node.js +node tests/setup-test.js + +# Python +python tests/test_setup.py +``` + +**Expected output:** + +``` +🧪 Testing Chimoney API Setup... + +1. Checking environment variables... +✅ Environment variables configured correctly + +2. Validating API key format... +✅ API key format looks valid + +3. Testing API connection... +Making GET request to /v0.2.4/info/assets +Response received: 200 +✅ API connection successful! +📊 Available assets: 15 + +🎉 Setup test completed successfully! +You are ready to start integrating with Chimoney API. +``` + +## Postman Collection + +### Step 11: Set Up Postman for API Testing + +**Download Postman** +- Visit `postman.com` +- Download and install Postman + +**Create Chimoney Collection** +- Open Postman +- Click "New" → "Collection" +- Name it "Chimoney API" +- Add description: "Collection for testing Chimoney API endpoints" + +**Set Up Environment Variables** +- Click the gear icon (⚙️) in the top-right +- Click "Add" to create a new environment +- Name it "Chimoney Development" +- Add variables: + - `base_url`: `https://api.chimoney.io` + - `api_key`: `your_api_key_here` + +**Create Test Requests** + +**Test Connection Request:** +- **Method:** GET +- **URL:** `{{base_url}}/v0.2.4/info/assets` +- **Headers:** + - `X-API-KEY`: `{{api_key}}` + - `Content-Type`: `application/json` + +**Create Wallet Address Request:** +- **Method:** POST +- **URL:** `{{base_url}}/v0.2.4/accounts/issue-wallet-address` +- **Headers:** + - `X-API-KEY`: `{{api_key}}` + - `Content-Type`: `application/json` +- **Body (raw JSON):** + ```json + { + "userID": "test_user_001", + "ilpUsername": "test_user_001" + } + ``` + +**Export Collection** +- Click the three dots (⋯) next to your collection +- Select "Export" +- Choose "Collection v2.1" +- Save the file for your team + +## Troubleshooting + +### Common Issues and Solutions + +#### Issue 1: "API key is not defined" Error + +```json +{ + "status": "error", + "error": "API key is not defined. Generate a new one from the developer portal." +} +``` + +**Solutions:** +- Verify your API key is correct in `.env` file +- Ensure no extra spaces or characters in the API key +- Check that your environment variables are being loaded properly +- Verify the header name is exactly `X-API-KEY` + +#### Issue 2: "API Access not enabled" Error + +```json +{ + "status": "error", + "error": "API Access not enabled for account Test. Email support@chimoney.io" +} +``` + +**Solutions:** +- Your account hasn't been approved for API access yet +- Email `support@chimoney.io` with your account details +- Wait for verification process to complete + +#### Issue 3: Connection Timeout + +**Solutions:** +- Check your internet connection +- Verify the base URL is correct +- Increase timeout in your HTTP client +- Check if there are any firewall restrictions + +#### Issue 4: SSL Certificate Errors + +**Solutions:** +- Ensure you're using HTTPS URLs +- Update your HTTP client library +- Check system date and time settings + +#### Issue 5: Environment Variables Not Loading + +**Solutions:** +- Verify `.env` file is in the correct directory +- Check file permissions +- Ensure dotenv is properly configured +- Restart your application after making changes + +### Debug Mode + +Enable debug logging for detailed troubleshooting: + +#### Node.js Debug: + +```javascript +// Add to your client +const debug = process.env.APP_DEBUG === 'true'; + +if (debug) { + console.log('Debug mode enabled'); + console.log('API Key (partial):', this.apiKey.substring(0, 10) + '...'); + console.log('Base URL:', this.baseURL); +} +``` + +#### Python Debug: + +```python +import logging + +# Configure logging +if os.getenv('APP_DEBUG', 'false').lower() == 'true': + logging.basicConfig(level=logging.DEBUG) + logger = logging.getLogger(__name__) + logger.debug('Debug mode enabled') + logger.debug(f'API Key (partial): {self.api_key[:10]}...') + logger.debug(f'Base URL: {self.base_url}') +``` + +## Security Best Practices + +### API Key Security + +**Never commit API keys to version control** +- Always use environment variables +- Add `.env` to `.gitignore` +- Use different keys for different environments + +**Rotate API keys regularly** +- Generate new keys every 90 days +- Update keys in all environments +- Monitor usage for unusual activity + +**Restrict API key permissions** +- Use the principle of least privilege +- Create separate keys for different services +- Monitor and log API key usage + +**Secure storage in production** +- Use secrets management services (AWS Secrets Manager, Azure Key Vault) +- Encrypt environment variables +- Implement proper access controls + +### Network Security + +```javascript +// Add request signing (example) +const crypto = require('crypto'); + +function signRequest(payload, secret) { + return crypto + .createHmac('sha256', secret) + .update(JSON.stringify(payload)) + .digest('hex'); +} + +// Add to request headers +headers['X-Signature'] = signRequest(requestBody, process.env.WEBHOOK_SECRET); +``` + +### Rate Limiting + +```javascript +// Implement client-side rate limiting +class RateLimiter { + constructor(maxRequests = 100, windowMs = 60000) { + this.maxRequests = maxRequests; + this.windowMs = windowMs; + this.requests = []; + } + + canMakeRequest() { + const now = Date.now(); + this.requests = this.requests.filter(time => now - time < this.windowMs); + + if (this.requests.length >= this.maxRequests) { + return false; + } + + this.requests.push(now); + return true; + } +} +``` + +## Next Steps + +### Immediate Actions + +- Complete the setup test to ensure everything is working +- Join the Chimoney Discord community for support +- Bookmark the API documentation for reference +- Set up monitoring for your API usage + +### Development Roadmap + +- **Week 1:** Complete setup and basic integration +- **Week 2:** Implement wallet address creation +- **Week 3:** Add error handling and logging +- **Week 4:** Build user interface and testing + +### Advanced Features to Explore + +- **Webhooks:** Set up real-time notifications +- **Multi-currency wallets:** Expand payment options +- **Bulk operations:** Handle multiple transactions +- **Analytics:** Track usage and performance +- **Mobile SDKs:** Extend to mobile applications + +### Support Resources + +- **Discord Community:** https://discord.gg/TsyKnzT4qV +- **Email Support:** support@chimoney.io +- **API Documentation:** Chimoney Developer Docs +- **Status Page:** Check for API status updates +- **GitHub Examples:** Look for community examples and integrations + +--- + +**Congratulations! 🎉** You now have a fully configured development environment for the Chimoney API. You're ready to start building amazing financial applications that connect users across the globe. + +Remember to keep your API keys secure, test thoroughly, and reach out to the community when you need help. Happy coding! From 7aefe6768fde6e56047111d41778f951a29bb0e4 Mon Sep 17 00:00:00 2001 From: Daniel Oladepo <98762494+Danbaba1@users.noreply.github.com> Date: Sat, 16 Aug 2025 12:44:45 +0100 Subject: [PATCH 4/5] Update tutorial.md --- submissions/wallet-danbaba1/tutorial.md | 106 +++++++++++++++++++++--- 1 file changed, 94 insertions(+), 12 deletions(-) diff --git a/submissions/wallet-danbaba1/tutorial.md b/submissions/wallet-danbaba1/tutorial.md index 86058df..e21eb65 100644 --- a/submissions/wallet-danbaba1/tutorial.md +++ b/submissions/wallet-danbaba1/tutorial.md @@ -15,7 +15,7 @@ This comprehensive tutorial will walk you through the process of creating Interl ## Understanding Interledger Wallet Addresses -An Interledger wallet address is like an email address for money. It's a unique identifier that allows users to send and receive payments across different networks and currencies seamlessly. When you create an Interledger wallet address through Chimoney, you're essentially giving a user a global payment endpoint that works 24/7. +Before diving into the technical implementation, it's essential to understand what we're building and why it matters. An Interledger wallet address is like an email address for money. It's a unique identifier that allows users to send and receive payments across different networks and currencies seamlessly. When you create an Interledger wallet address through Chimoney, you're essentially giving a user a global payment endpoint that works 24/7. ### Key Benefits @@ -27,7 +27,7 @@ An Interledger wallet address is like an email address for money. It's a unique ## Prerequisites -Before you begin, ensure you have: +Now that you understand the concept, let's ensure you have everything needed to start building. Before you begin, ensure you have: - **Chimoney Developer Account**: Sign up at [dash.chimoney.io](https://dash.chimoney.io) - **API Access**: Request verification and API access by emailing support@chimoney.io @@ -37,6 +37,8 @@ Before you begin, ensure you have: ## API Endpoint Overview +With your prerequisites in place, let's examine the specific API endpoint we'll be working with. Understanding the endpoint structure and expected parameters is crucial for successful integration. + **Endpoint**: `POST /v0.2.4/accounts/issue-wallet-address` **Base URL**: `https://api.chimoney.io/` **Authentication**: API Key (X-API-KEY header) @@ -65,6 +67,8 @@ Before you begin, ensure you have: ## Step-by-Step Implementation +Now that we've covered the fundamentals, let's build the actual implementation. We'll start by setting up our development environment and then create the core functionality step by step. + ### Step 1: Set Up Your Environment First, let's set up the basic structure for making API calls to Chimoney. @@ -119,6 +123,8 @@ headers = { ### Step 2: Create the Wallet Address Function +With our environment configured, we can now create the main function that will handle wallet address creation. This function will handle the API communication and provide meaningful feedback about the operation's success or failure. + #### Node.js Implementation: ```javascript @@ -248,7 +254,7 @@ def create_interledger_wallet_address(user_id, ilp_username): ### Step 3: Username Validation and Generation -Implement helper functions to ensure proper username formatting: +Before creating wallet addresses, we need to ensure that usernames meet the required format standards. This step is crucial because invalid usernames will cause the API request to fail. Let's implement helper functions to validate and generate proper usernames. #### Node.js: @@ -334,7 +340,7 @@ def generate_ilp_username(user_id, email=None): ### Step 4: Complete Integration Example -Here's a complete example showing how to integrate wallet address creation into a user registration flow: +Now let's bring everything together in a comprehensive example that shows how to integrate wallet address creation into a real-world user registration flow. This example demonstrates how all the components work together seamlessly. #### Node.js: @@ -411,7 +417,63 @@ async function example() { ## Error Handling -Implement comprehensive error handling for different scenarios: +Robust error handling is critical for a production-ready integration. When working with the Chimoney API, you'll encounter various types of errors, each requiring different approaches to resolve. Understanding these errors and how to handle them properly will save you significant debugging time and provide a better user experience. + +### Common Error Types and Solutions + +**Authentication Errors (401 Unauthorized)** +This occurs when your API key is invalid, missing, or has been revoked. The API will return a 401 status code with details about the authentication failure. + +*How to fix:* +- Verify your API key is correctly set in your environment variables +- Ensure the API key hasn't expired or been revoked +- Check that you're using the correct header format (`X-API-KEY`) +- Contact Chimoney support if your account needs API access activation + +**Validation Errors (400 Bad Request)** +These happen when the request parameters don't meet the API's requirements. This could be due to missing required fields, invalid data formats, or constraint violations. + +*How to fix:* +- Check that both `userID` and `ilpUsername` are provided +- Ensure the `ilpUsername` follows the naming conventions (lowercase, alphanumeric, underscores, and hyphens only) +- Verify the username length is between 3-30 characters +- Validate that the `userID` is a valid string identifier + +**Authorization Errors (403 Forbidden)** +Even with a valid API key, you might not have permission to perform certain operations. This typically occurs when your account doesn't have the required privileges. + +*How to fix:* +- Contact Chimoney support to enable wallet creation permissions for your account +- Verify your account is in good standing and meets the requirements for API access +- Check if there are any account-level restrictions or limitations + +**Duplicate Resource Errors** +If you try to create a wallet address for a user who already has one, or use a username that's already taken, you'll receive an error indicating the resource already exists. + +*How to fix:* +- Implement checks to see if a user already has a wallet before creating a new one +- Generate alternative usernames if the preferred one is taken +- Consider using UUIDs or timestamps to make usernames unique + +**Network and Server Errors (500+ Status Codes)** +These indicate problems on Chimoney's end or network connectivity issues. They're usually temporary and can be resolved with retry logic. + +*How to fix:* +- Implement exponential backoff retry logic for server errors +- Check your internet connection and firewall settings +- Monitor Chimoney's status page for any ongoing service issues +- Set appropriate timeouts for your requests (recommended: 30 seconds) + +**Rate Limiting Errors (429 Too Many Requests)** +If you exceed the API rate limits, you'll receive a 429 status code. This protects both your application and Chimoney's infrastructure. + +*How to fix:* +- Implement rate limiting in your application to stay within API limits +- Use queue systems for batch operations +- Consider caching results to reduce API calls +- Respect the `Retry-After` header in the response + +### Implementing Comprehensive Error Handling ```javascript function handleChimoneyError(error) { @@ -423,44 +485,58 @@ function handleChimoneyError(error) { return { type: 'validation_error', message: 'Invalid request parameters', - details: data + details: data, + userMessage: 'Please check your input and try again.' }; case 401: return { type: 'authentication_error', message: 'Invalid or missing API key', - details: data + details: data, + userMessage: 'Authentication failed. Please contact support.' }; case 403: return { type: 'authorization_error', message: 'API access not enabled for account', - details: data + details: data, + userMessage: 'Account permissions insufficient. Contact support.' + }; + case 429: + return { + type: 'rate_limit_error', + message: 'Too many requests', + details: data, + userMessage: 'Please wait a moment before trying again.' }; case 500: return { type: 'server_error', message: 'Internal server error occurred', - details: data + details: data, + userMessage: 'Service temporarily unavailable. Please try again later.' }; default: return { type: 'unknown_error', message: `Unexpected error: ${status}`, - details: data + details: data, + userMessage: 'An unexpected error occurred. Please try again.' }; } } else if (error.request) { return { type: 'network_error', message: 'No response received from server', - details: error.message + details: error.message, + userMessage: 'Network error. Please check your connection and try again.' }; } else { return { type: 'client_error', message: 'Error setting up the request', - details: error.message + details: error.message, + userMessage: 'Request setup failed. Please try again.' }; } } @@ -468,6 +544,8 @@ function handleChimoneyError(error) { ## Testing Your Integration +Before deploying to production, thorough testing is essential to ensure your integration works correctly under various conditions. Let's create comprehensive tests that cover both successful operations and error scenarios. + ### Unit Tests ```javascript @@ -543,6 +621,8 @@ async function testWalletCreation() { ## Best Practices +As you prepare to deploy your integration to production, following these best practices will help ensure reliability, security, and maintainability of your wallet address creation system. + ### 1. Security Considerations ```javascript @@ -628,6 +708,8 @@ async function createAndStoreWallet(userID, ilpUsername) { ## Next Steps +Congratulations on successfully implementing Interledger wallet address creation! Now that you have a solid foundation, here are some logical next steps to enhance your payment infrastructure and provide even more value to your users. + After successfully implementing Interledger wallet address creation, consider these enhancements: - **Wallet Management**: Implement functions to retrieve and update wallet information From c49f18a41946757f80f0fe869ceb0c04d35cb70e Mon Sep 17 00:00:00 2001 From: Daniel Oladepo <98762494+Danbaba1@users.noreply.github.com> Date: Sat, 16 Aug 2025 13:05:24 +0100 Subject: [PATCH 5/5] Update setup.md --- submissions/wallet-danbaba1/setup.md | 908 +++++++++++++++++++++++---- 1 file changed, 799 insertions(+), 109 deletions(-) diff --git a/submissions/wallet-danbaba1/setup.md b/submissions/wallet-danbaba1/setup.md index 790b5b0..5e2a75f 100644 --- a/submissions/wallet-danbaba1/setup.md +++ b/submissions/wallet-danbaba1/setup.md @@ -17,15 +17,20 @@ This comprehensive setup guide will walk you through everything you need to get ## Account Setup +Getting started with Chimoney begins with creating your developer account and setting up the necessary credentials. This process is straightforward but requires attention to detail to ensure everything is configured correctly for API access. + ### Step 1: Create Your Chimoney Account +The first step in your Chimoney journey is creating an account that will serve as your gateway to all API functionality. + **Visit the Chimoney Dashboard** - Navigate to `dash.chimoney.io` - Click "Sign Up" to create a new account **Complete Registration** -Required Information: +You'll need to provide accurate information as this will be used for account verification: + - Full Name - Email Address - Phone Number @@ -33,6 +38,8 @@ Required Information: - Business/Organization Name (if applicable) - Password (minimum 8 characters) +> **💡 Pro Tip:** Use a professional email address as this will be your primary contact method for support and important API updates. + **Email Verification** - Check your email for a verification link - Click the link to verify your account @@ -45,26 +52,41 @@ Required Information: ### Step 2: Profile Completion +Before requesting API access, it's important to complete your profile to establish credibility and speed up the approval process. + **Complete Your Profile** -- Add your profile picture (optional) +- Add your profile picture (optional but recommended) - Fill in any missing business information - Verify your phone number if prompted **Security Settings** + +Security is paramount when working with financial APIs. Set up these essential security measures: + - Enable two-factor authentication (2FA) - **Highly Recommended** - Set up security questions - Review login history +> **⚠️ Important:** Two-factor authentication is strongly recommended as it protects your account from unauthorized access, especially when handling API keys. + +Now that your account is properly set up, let's move on to requesting the API access you'll need for development. + ## API Access Request +Unlike many APIs that provide immediate access, Chimoney requires verification before granting API privileges. This extra step ensures security and compliance with financial regulations, protecting both you and your users. + ### Step 3: Request API Access -> ⚠️ **Important**: API access requires verification and approval from Chimoney. +> ⚠️ **Important**: API access requires verification and approval from Chimoney. This process typically takes 1-3 business days and is necessary for regulatory compliance. **Prepare Your Application** + +Before reaching out to Chimoney, gather the following information to expedite the approval process: + - Document your use case clearly - Prepare your website/application URL - Have your business documentation ready +- Estimate your expected transaction volume **Send Verification Request** @@ -104,17 +126,25 @@ Best regards, ### Step 4: Wait for Approval -- **Timeline**: Typically 1-3 business days -- **Follow-up**: If no response within 5 days, send a polite follow-up email -- **Approval Notification**: You'll receive an email confirming API access +**Timeline**: Typically 1-3 business days +**Follow-up**: If no response within 5 days, send a polite follow-up email +**Approval Notification**: You'll receive an email confirming API access + +While waiting for approval, you can proceed with setting up your development environment to be ready when access is granted. ## Development Environment Setup +With your API access request submitted, it's time to prepare your development environment. This section will guide you through setting up the necessary tools and dependencies for your chosen programming language. + +> **📝 Note:** You only need to follow the setup instructions for your preferred programming language - you don't need to set up all three options. + ### Step 5: Choose Your Development Stack -**Recommended Environments:** +Select one of the following environments based on your project requirements and team expertise. -#### Node.js Setup: +#### Node.js Setup + +Node.js is excellent for building APIs and web applications with JavaScript. If your team is familiar with JavaScript or you're building a web-based application, this is often the best choice. ```bash # Check Node.js version (recommended: 16+) @@ -146,7 +176,15 @@ touch src/wallet-service.js touch tests/wallet.test.js ``` -#### Python Setup: +**Why these dependencies?** +- `axios`: HTTP client for making API requests +- `dotenv`: Loads environment variables securely +- `jest`: Testing framework for unit tests +- `nodemon`: Automatically restarts your application during development + +#### Python Setup + +Python is ideal for data processing, automation, and backend services. Choose this if your team prefers Python or you're building data-intensive applications. ```bash # Check Python version (recommended: 3.8+) @@ -180,7 +218,14 @@ touch tests/test_wallet.py touch requirements.txt ``` -#### PHP Setup: +**Why these packages?** +- `requests`: Python's most popular HTTP library +- `python-dotenv`: Manages environment variables +- `pytest`: Powerful testing framework for Python + +#### PHP Setup + +PHP is perfect for web applications and has strong support for financial integrations. Choose this if you're working with WordPress, Laravel, or other PHP frameworks. ```bash # Check PHP version (recommended: 8.0+) @@ -214,51 +259,64 @@ touch src/WalletService.php touch tests/WalletTest.php ``` +**Why these packages?** +- `guzzlehttp/guzzle`: Robust HTTP client for PHP +- `vlucas/phpdotenv`: Environment variable management +- `phpunit/phpunit`: Standard testing framework for PHP + ### Step 6: Set Up Your .gitignore File +The `.gitignore` file is crucial for protecting sensitive information like API keys from being accidentally committed to version control. This prevents security breaches and keeps your credentials safe. + Create a `.gitignore` file to protect sensitive information: ```gitignore -# Environment variables +# Environment variables - Contains sensitive API keys and secrets .env .env.local .env.*.local -# Dependencies +# Dependencies - Third-party packages (can be reinstalled) node_modules/ vendor/ __pycache__/ *.pyc -# IDE files +# IDE files - Editor-specific configuration files .vscode/ .idea/ *.swp *.swo -# OS files +# OS files - Operating system generated files .DS_Store Thumbs.db -# Log files +# Log files - May contain sensitive debugging information *.log logs/ -# Testing +# Testing - Test coverage and cache files coverage/ .nyc_output/ .pytest_cache/ -# Build outputs +# Build outputs - Generated files that can be recreated dist/ build/ ``` +> **🔒 Security Note:** The `.env` file contains your API keys and other sensitive information. Never commit this file to version control as it could expose your credentials to unauthorized users. + +With your development environment now configured, let's move on to setting up authentication with your Chimoney API credentials. + ## Authentication Configuration +Now that your development environment is ready, it's time to configure authentication. This involves obtaining your API key from Chimoney and setting up secure credential management in your application. + ### Step 7: Obtain Your API Key -Once your API access is approved: +Once your API access is approved, you'll need to retrieve your unique API key from the Chimoney dashboard. **Log into Chimoney Dashboard** - Go to `dash.chimoney.io` @@ -269,19 +327,27 @@ Once your API access is approved: - Copy the generated key immediately - Store it securely (you may not be able to view it again) +> **⚠️ Critical:** Your API key is like a password - treat it with the same level of security. Never share it publicly or include it directly in your code. + **API Key Format** Your API key will look something like: ``` -sk_live_1234567890abcdef1234567890abcdef +sk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ``` or ``` -sk_test_1234567890abcdef1234567890abcdef +sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ``` +The prefix indicates the environment: +- `sk_test_`: Sandbox/testing environment +- `sk_live_`: Production environment + ### Step 8: Configure Environment Variables +Environment variables are a secure way to store sensitive configuration data like API keys. They keep your credentials separate from your code and allow different settings for development, testing, and production environments. + Create your `.env` file with the following structure: ```env @@ -295,7 +361,7 @@ APP_NAME=Chimoney Integration APP_ENV=development APP_DEBUG=true -# Database Configuration (if needed) +# Database Configuration (if needed for your application) DB_HOST=localhost DB_PORT=5432 DB_NAME=chimoney_app @@ -306,7 +372,7 @@ DB_PASS=your_db_password LOG_LEVEL=debug LOG_FILE=logs/app.log -# Rate Limiting +# Rate Limiting (prevents API abuse) RATE_LIMIT_WINDOW=15 # minutes RATE_LIMIT_MAX_REQUESTS=100 @@ -315,7 +381,14 @@ WEBHOOK_SECRET=your_webhook_secret WEBHOOK_URL=https://your-domain.com/webhooks/chimoney ``` -Create an `.env.example` file for your team: +**What each configuration does:** +- **CHIMONEY_API_KEY**: Your secret key for API authentication +- **CHIMONEY_BASE_URL**: The API endpoint (usually doesn't change) +- **CHIMONEY_ENVIRONMENT**: Helps track which environment you're using +- **Rate limiting**: Prevents accidentally overwhelming the API with requests +- **Webhook settings**: For receiving real-time notifications (advanced feature) + +Create an `.env.example` file for your team (without sensitive values): ```env # Copy this file to .env and fill in your actual values @@ -338,11 +411,21 @@ WEBHOOK_SECRET=your_webhook_secret_here WEBHOOK_URL=https://your-domain.com/webhooks/chimoney ``` +> **📝 Team Tip:** The `.env.example` file shows your team what environment variables they need to set up without exposing actual credentials. Share this file freely, but never share the actual `.env` file. + +Now that authentication is configured, let's test everything to make sure it's working correctly. + ## Testing Your Setup +Before diving into complex integrations, it's crucial to verify that your setup is working correctly. This testing phase will catch configuration issues early and save you debugging time later. + ### Step 9: Create Your First API Client -#### Node.js Client: +Let's create a reusable client that will handle all communication with the Chimoney API. This client will include proper error handling, logging, and security headers. + +#### Node.js Client + +This client provides a clean interface for making API calls with built-in error handling and logging: ```javascript // src/chimoney-client.js @@ -365,7 +448,7 @@ class ChimoneyClient { 'Content-Type': 'application/json', 'User-Agent': 'Chimoney-Integration/1.0' }, - timeout: 30000 // 30 seconds + timeout: 30000 // 30 seconds timeout prevents hanging requests }); // Add request interceptor for logging @@ -395,7 +478,7 @@ class ChimoneyClient { async testConnection() { try { - // Test with a simple endpoint + // Test with a simple endpoint that returns available assets const response = await this.client.get('/v0.2.4/info/assets'); return { success: true, @@ -415,7 +498,9 @@ class ChimoneyClient { module.exports = ChimoneyClient; ``` -#### Python Client: +#### Python Client + +This Python client provides similar functionality with proper error handling and logging: ```python # chimoney_integration/client.py @@ -442,7 +527,7 @@ class ChimoneyClient: } def _make_request(self, method, endpoint, data=None): - """Make HTTP request to Chimoney API""" + """Make HTTP request to Chimoney API with proper error handling""" url = f"{self.base_url}{endpoint}" print(f"Making {method.upper()} request to {url}") @@ -453,7 +538,7 @@ class ChimoneyClient: url=url, headers=self.headers, json=data, - timeout=30 + timeout=30 # 30 seconds timeout ) print(f"Response received: {response.status_code}") @@ -488,7 +573,7 @@ class ChimoneyClient: } def test_connection(self): - """Test API connection""" + """Test API connection by fetching available assets""" try: result = self._make_request('GET', '/v0.2.4/info/assets') @@ -515,9 +600,11 @@ class ChimoneyClient: ### Step 10: Test Your Configuration -Create a test script to verify everything is working: +Now let's create a comprehensive test script to verify that everything is working properly. This test will check your environment variables, validate your API key format, and test the connection to Chimoney's servers. + +#### Node.js Test -#### Node.js Test: +This test script will systematically verify each part of your setup: ```javascript // tests/setup-test.js @@ -534,6 +621,7 @@ async function testSetup() { if (missingVars.length > 0) { console.log('❌ Missing environment variables:', missingVars); + console.log('💡 Make sure your .env file exists and contains all required variables'); return; } console.log('✅ Environment variables configured correctly\n'); @@ -543,6 +631,7 @@ async function testSetup() { const apiKey = process.env.CHIMONEY_API_KEY; if (!apiKey.startsWith('sk_')) { console.log('⚠️ Warning: API key should start with "sk_"'); + console.log('💡 Double-check that you copied the complete API key from your dashboard'); } console.log('✅ API key format looks valid\n'); @@ -556,6 +645,7 @@ async function testSetup() { console.log('📊 Available assets:', connectionTest.data?.data?.length || 0); } else { console.log('❌ API connection failed:', connectionTest.error); + console.log('💡 Check your internet connection and API key validity'); return; } @@ -564,6 +654,7 @@ async function testSetup() { } catch (error) { console.error('❌ Setup test failed:', error.message); + console.log('💡 Review the error message above and check your configuration'); } } @@ -571,7 +662,9 @@ async function testSetup() { testSetup(); ``` -#### Python Test: +#### Python Test + +Here's the equivalent test for Python developers: ```python # tests/test_setup.py @@ -592,6 +685,7 @@ def test_setup(): if missing_vars: print(f'❌ Missing environment variables: {missing_vars}') + print('💡 Make sure your .env file exists and contains all required variables') return print('✅ Environment variables configured correctly\n') @@ -600,6 +694,7 @@ def test_setup(): api_key = os.getenv('CHIMONEY_API_KEY') if not api_key.startswith('sk_'): print('⚠️ Warning: API key should start with "sk_"') + print('💡 Double-check that you copied the complete API key from your dashboard') print('✅ API key format looks valid\n') # Test 3: API Connection @@ -613,6 +708,7 @@ def test_setup(): print(f'📊 Available assets: {assets_count}') else: print(f'❌ API connection failed: {connection_test["error"]}') + print('💡 Check your internet connection and API key validity') return print('\n🎉 Setup test completed successfully!') @@ -620,6 +716,7 @@ def test_setup(): except Exception as error: print(f'❌ Setup test failed: {str(error)}') + print('💡 Review the error message above and check your configuration') if __name__ == '__main__': test_setup() @@ -656,21 +753,100 @@ Response received: 200 You are ready to start integrating with Chimoney API. ``` +If you see this success message, congratulations! Your setup is complete and working correctly. If you encounter any errors, the troubleshooting section below will help you resolve them. + +## Environment Variables + +Understanding and properly managing environment variables is crucial for maintaining security and flexibility in your application. Let's dive deeper into why they matter and how to use them effectively. + +### What Are Environment Variables? + +Environment variables are configuration values that exist outside your application code. They're particularly important for storing sensitive information like API keys because they: + +- Keep secrets out of your source code +- Allow different configurations for different environments (development, testing, production) +- Can be changed without modifying code +- Are not accidentally shared when you commit code to version control + +### Essential Environment Variables for Chimoney + +Here's a detailed breakdown of the key environment variables you'll need: + +```env +# Core Chimoney API Settings +CHIMONEY_API_KEY=sk_test_your_actual_key_here +CHIMONEY_BASE_URL=https://api.chimoney.io +CHIMONEY_ENVIRONMENT=sandbox + +# Application Settings +APP_NAME=My Chimoney Integration +APP_ENV=development +APP_DEBUG=true + +# Rate Limiting (prevents API abuse) +RATE_LIMIT_WINDOW=15 +RATE_LIMIT_MAX_REQUESTS=100 + +# Logging +LOG_LEVEL=info +LOG_FILE=logs/chimoney.log +``` + +**Variable Explanations:** + +- **CHIMONEY_API_KEY**: Your unique identifier for API access - treat this like a password +- **CHIMONEY_BASE_URL**: The API server address (rarely changes) +- **CHIMONEY_ENVIRONMENT**: Helps you track which environment you're using +- **APP_DEBUG**: When true, enables detailed logging for troubleshooting +- **RATE_LIMIT_***: Prevents accidentally overwhelming the API with too many requests + +### Managing Multiple Environments + +As your application grows, you'll need different configurations for different stages: + +**Development (.env.development)** +```env +CHIMONEY_API_KEY=sk_test_development_key +APP_DEBUG=true +LOG_LEVEL=debug +``` + +**Production (.env.production)** +```env +CHIMONEY_API_KEY=sk_live_production_key +APP_DEBUG=false +LOG_LEVEL=error +``` + +> **🚨 Critical Security Note:** Never use production API keys in development environments, and never commit any `.env` file to version control. + +With your environment properly configured, let's set up Postman for easy API testing and exploration. + ## Postman Collection +Postman is an excellent tool for testing APIs before integrating them into your application. It allows you to experiment with different requests, save common operations, and share API examples with your team. + ### Step 11: Set Up Postman for API Testing +Let's configure Postman to work seamlessly with the Chimoney API, making it easy to test and debug your integration. + **Download Postman** - Visit `postman.com` -- Download and install Postman +- Download and install Postman (it's free for basic use) **Create Chimoney Collection** + +A collection in Postman is like a folder for organizing related API requests: + - Open Postman - Click "New" → "Collection" - Name it "Chimoney API" - Add description: "Collection for testing Chimoney API endpoints" **Set Up Environment Variables** + +Postman environments let you store variables like API keys that can be reused across requests: + - Click the gear icon (⚙️) in the top-right - Click "Add" to create a new environment - Name it "Chimoney Development" @@ -678,16 +854,26 @@ You are ready to start integrating with Chimoney API. - `base_url`: `https://api.chimoney.io` - `api_key`: `your_api_key_here` +> **💡 Postman Tip:** Using variables makes it easy to switch between development and production environments without changing individual requests. + **Create Test Requests** -**Test Connection Request:** +Let's create two essential requests that you'll use frequently: + +**1. Test Connection Request:** + +This request verifies your API access and returns available assets: + - **Method:** GET - **URL:** `{{base_url}}/v0.2.4/info/assets` - **Headers:** - `X-API-KEY`: `{{api_key}}` - `Content-Type`: `application/json` -**Create Wallet Address Request:** +**2. Create Wallet Address Request:** + +This request demonstrates the main functionality of creating wallet addresses: + - **Method:** POST - **URL:** `{{base_url}}/v0.2.4/accounts/issue-wallet-address` - **Headers:** @@ -701,18 +887,25 @@ You are ready to start integrating with Chimoney API. } ``` -**Export Collection** +**Export Collection for Team Sharing** - Click the three dots (⋯) next to your collection - Select "Export" - Choose "Collection v2.1" - Save the file for your team +> **👥 Team Collaboration:** Sharing the exported collection file ensures everyone on your team uses the same request formats and can quickly get up to speed with the API. + +Now that you have your testing tools ready, let's address common issues you might encounter during setup. + ## Troubleshooting +Even with careful setup, you might encounter issues along the way. This section covers the most common problems developers face when integrating with the Chimoney API and provides clear solutions. + ### Common Issues and Solutions #### Issue 1: "API key is not defined" Error +**Error Message:** ```json { "status": "error", @@ -720,14 +913,22 @@ You are ready to start integrating with Chimoney API. } ``` +**What this means:** The API can't find or recognize your API key. + **Solutions:** -- Verify your API key is correct in `.env` file -- Ensure no extra spaces or characters in the API key -- Check that your environment variables are being loaded properly -- Verify the header name is exactly `X-API-KEY` +1. **Check your .env file**: Verify your API key is correctly set in `.env` file +2. **Remove extra characters**: Ensure no extra spaces or characters before/after the API key +3. **Restart your application**: Environment variables are loaded when the application starts +4. **Verify header name**: The header must be exactly `X-API-KEY` (case-sensitive) + +**Quick Test:** +```javascript +console.log('API Key:', process.env.CHIMONEY_API_KEY ? 'Present' : 'Missing'); +``` #### Issue 2: "API Access not enabled" Error +**Error Message:** ```json { "status": "error", @@ -735,93 +936,206 @@ You are ready to start integrating with Chimoney API. } ``` +**What this means:** Your account hasn't been approved for API access yet. + **Solutions:** -- Your account hasn't been approved for API access yet -- Email `support@chimoney.io` with your account details -- Wait for verification process to complete +1. **Wait for approval**: The verification process typically takes 1-3 business days +2. **Check your email**: Look for an approval notification from Chimoney +3. **Follow up**: If it's been more than 5 business days, send a polite follow-up email +4. **Provide more details**: Consider providing additional information about your use case #### Issue 3: Connection Timeout +**What this means:** Your request is taking too long to complete, often due to network issues. + **Solutions:** -- Check your internet connection -- Verify the base URL is correct -- Increase timeout in your HTTP client -- Check if there are any firewall restrictions +1. **Check internet connection**: Verify you have stable internet access +2. **Verify the base URL**: Ensure you're using `https://api.chimoney.io` +3. **Increase timeout**: Set timeout to at least 30 seconds in your HTTP client +4. **Check firewall**: Ensure your firewall isn't blocking outbound HTTPS requests + +**Example timeout configuration:** +```javascript +// Node.js with axios +timeout: 30000 // 30 seconds + +// Python with requests +timeout=30 +``` #### Issue 4: SSL Certificate Errors +**What this means:** Your system can't verify the security certificate of the API server. + **Solutions:** -- Ensure you're using HTTPS URLs -- Update your HTTP client library -- Check system date and time settings +1. **Update your HTTP client**: Ensure you're using the latest version +2. **Check system time**: Incorrect system time can cause certificate validation to fail +3. **Use HTTPS URLs**: Always use `https://` instead of `http://` +4. **Update certificates**: Ensure your system has updated root certificates #### Issue 5: Environment Variables Not Loading +**What this means:** Your application can't access the values you've set in your `.env` file. + +**Solutions:** +1. **Check file location**: Ensure `.env` is in your project root directory +2. **Verify file permissions**: Make sure the file is readable by your application +3. **Import dotenv correctly**: Ensure you're loading dotenv at the start of your application +4. **Restart application**: Environment variables are loaded when the application starts + +**Quick debugging:** +```javascript +// Node.js +console.log('All env vars:', Object.keys(process.env).filter(key => key.startsWith('CHIMONEY'))); + +// Python +import os +print('Chimoney vars:', {k: v for k, v in os.environ.items() if k.startswith('CHIMONEY')}) +``` + +#### Issue 6: Rate Limiting Errors (429 Status) + +**What this means:** You're making too many requests too quickly. + **Solutions:** -- Verify `.env` file is in the correct directory -- Check file permissions -- Ensure dotenv is properly configured -- Restart your application after making changes +1. **Implement rate limiting**: Add delays between requests +2. **Use exponential backoff**: Gradually increase delay times after errors +3. **Batch operations**: Combine multiple operations when possible +4. **Respect retry headers**: Check for `Retry-After` header in responses -### Debug Mode +### Debug Mode Configuration -Enable debug logging for detailed troubleshooting: +Enable detailed logging to troubleshoot issues more effectively: -#### Node.js Debug: +#### Node.js Debug Setup ```javascript -// Add to your client +// Add to your client configuration const debug = process.env.APP_DEBUG === 'true'; -if (debug) { - console.log('Debug mode enabled'); - console.log('API Key (partial):', this.apiKey.substring(0, 10) + '...'); - console.log('Base URL:', this.baseURL); +class ChimoneyClient { + constructor() { + // ... existing code ... + + if (debug) { + console.log('🔍 Debug mode enabled'); + console.log('📍 API Key (partial):', this.apiKey.substring(0, 10) + '...'); + console.log('🌐 Base URL:', this.baseURL); + console.log('⚙️ Environment:', process.env.CHIMONEY_ENVIRONMENT); + } + } } ``` -#### Python Debug: +#### Python Debug Setup ```python import logging +import os -# Configure logging +# Configure detailed logging when debug mode is enabled if os.getenv('APP_DEBUG', 'false').lower() == 'true': - logging.basicConfig(level=logging.DEBUG) + logging.basicConfig( + level=logging.DEBUG, + format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' + ) logger = logging.getLogger(__name__) - logger.debug('Debug mode enabled') - logger.debug(f'API Key (partial): {self.api_key[:10]}...') - logger.debug(f'Base URL: {self.base_url}') + logger.debug('🔍 Debug mode enabled') + logger.debug(f'📍 API Key (partial): {self.api_key[:10]}...') + logger.debug(f'🌐 Base URL: {self.base_url}') ``` +> **🐛 Debugging Tip:** Enable debug mode only during development. It can expose sensitive information and slow down your application in production. + +With troubleshooting knowledge in hand, let's explore essential security practices to protect your integration. + ## Security Best Practices +Security is paramount when working with financial APIs. Following these best practices will protect your application, your users' data, and maintain compliance with financial regulations. + ### API Key Security -**Never commit API keys to version control** -- Always use environment variables -- Add `.env` to `.gitignore` -- Use different keys for different environments +Your API key is the gateway to your Chimoney integration - protecting it properly is essential. -**Rotate API keys regularly** -- Generate new keys every 90 days -- Update keys in all environments -- Monitor usage for unusual activity +**Never Commit API Keys to Version Control** -**Restrict API key permissions** -- Use the principle of least privilege -- Create separate keys for different services -- Monitor and log API key usage +API keys should never appear in your source code or be committed to repositories like GitHub: -**Secure storage in production** -- Use secrets management services (AWS Secrets Manager, Azure Key Vault) -- Encrypt environment variables -- Implement proper access controls +```javascript +// ❌ NEVER do this +const apiKey = 'sk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // Hardcoded - very bad! + +// ✅ Always do this +const apiKey = process.env.CHIMONEY_API_KEY; // From environment variables +``` + +**Why this matters:** Once code is committed to version control, the API key could be exposed to anyone with access to the repository, including future team members or if the repository becomes public. + +**Rotate API Keys Regularly** + +Implement a regular rotation schedule for your API keys: + +- **Generate new keys**: Create new API keys every 90 days +- **Update all environments**: Ensure all systems use the new key +- **Monitor usage**: Track API usage for unusual activity +- **Revoke old keys**: Disable old keys after confirming the new ones work + +**Restrict API Key Permissions** + +Follow the principle of least privilege: + +- **Use separate keys**: Create different keys for different services or environments +- **Monitor access patterns**: Regularly review which endpoints your keys are accessing +- **Set up alerts**: Configure notifications for unusual API usage + +**Secure Storage in Production** + +For production environments, use professional secrets management: + +```javascript +// Example using AWS Secrets Manager +const AWS = require('aws-sdk'); +const secretsManager = new AWS.SecretsManager(); + +async function getChimoneyApiKey() { + try { + const secret = await secretsManager.getSecretValue({ + SecretId: 'chimoney-api-key' + }).promise(); + + return JSON.parse(secret.SecretString).apiKey; + } catch (error) { + console.error('Failed to retrieve API key from secrets manager:', error); + throw error; + } +} +``` + +**Popular secrets management services:** +- AWS Secrets Manager +- Azure Key Vault +- Google Secret Manager +- HashiCorp Vault ### Network Security +Protect your API communications from interception and tampering. + +**Always Use HTTPS** + +```javascript +// ✅ Correct - uses HTTPS +const baseURL = 'https://api.chimoney.io'; + +// ❌ Never use HTTP for API calls +const baseURL = 'http://api.chimoney.io'; // Insecure! +``` + +**Implement Request Signing** (Advanced) + +For additional security, you can sign your requests: + ```javascript -// Add request signing (example) const crypto = require('crypto'); function signRequest(payload, secret) { @@ -832,13 +1146,30 @@ function signRequest(payload, secret) { } // Add to request headers -headers['X-Signature'] = signRequest(requestBody, process.env.WEBHOOK_SECRET); +const signature = signRequest(requestBody, process.env.WEBHOOK_SECRET); +headers['X-Signature'] = `sha256=${signature}`; ``` -### Rate Limiting +**Validate SSL Certificates** + +Ensure your HTTP client validates SSL certificates: + +```javascript +// Node.js with axios - this is enabled by default +const client = axios.create({ + baseURL: 'https://api.chimoney.io', + // SSL verification is enabled by default + httpsAgent: new https.Agent({ + rejectUnauthorized: true // Ensures SSL certificate validation + }) +}); +``` + +### Rate Limiting and Abuse Prevention + +Implement client-side rate limiting to prevent accidental API abuse: ```javascript -// Implement client-side rate limiting class RateLimiter { constructor(maxRequests = 100, windowMs = 60000) { this.maxRequests = maxRequests; @@ -848,52 +1179,411 @@ class RateLimiter { canMakeRequest() { const now = Date.now(); + // Remove old requests outside the window this.requests = this.requests.filter(time => now - time < this.windowMs); + // Check if we're at the limit if (this.requests.length >= this.maxRequests) { + const oldestRequest = Math.min(...this.requests); + const waitTime = this.windowMs - (now - oldestRequest); + console.log(`Rate limit reached. Wait ${waitTime}ms before next request.`); return false; } + // Record this request this.requests.push(now); return true; } + + async waitIfNeeded() { + if (!this.canMakeRequest()) { + const waitTime = this.getWaitTime(); + console.log(`Waiting ${waitTime}ms due to rate limiting...`); + await new Promise(resolve => setTimeout(resolve, waitTime)); + } + } + + getWaitTime() { + if (this.requests.length === 0) return 0; + const now = Date.now(); + const oldestRequest = Math.min(...this.requests); + return Math.max(0, this.windowMs - (now - oldestRequest)); + } +} + +// Usage example +const rateLimiter = new RateLimiter(50, 60000); // 50 requests per minute + +async function makeApiCall() { + await rateLimiter.waitIfNeeded(); + // Make your API call here + return await client.post('/v0.2.4/accounts/issue-wallet-address', data); +} +``` + +### Input Validation and Sanitization + +Always validate and sanitize input data before sending it to the API: + +```javascript +function validateUserInput(userID, ilpUsername) { + const errors = []; + + // Validate userID + if (!userID || typeof userID !== 'string') { + errors.push('userID must be a non-empty string'); + } else if (userID.length > 100) { + errors.push('userID must be less than 100 characters'); + } + + // Validate ilpUsername + if (!ilpUsername || typeof ilpUsername !== 'string') { + errors.push('ilpUsername must be a non-empty string'); + } else if (!/^[a-z0-9_-]+$/.test(ilpUsername)) { + errors.push('ilpUsername must contain only lowercase letters, numbers, hyphens, and underscores'); + } else if (ilpUsername.length < 3 || ilpUsername.length > 30) { + errors.push('ilpUsername must be between 3 and 30 characters'); + } + + return { + isValid: errors.length === 0, + errors: errors + }; +} + +// Usage +const validation = validateUserInput(userID, ilpUsername); +if (!validation.isValid) { + console.error('Validation failed:', validation.errors); + return { success: false, errors: validation.errors }; } ``` +### Logging and Monitoring + +Implement comprehensive logging while protecting sensitive data: + +```javascript +function createSecureLogger() { + const winston = require('winston'); + + return winston.createLogger({ + level: process.env.LOG_LEVEL || 'info', + format: winston.format.combine( + winston.format.timestamp(), + winston.format.errors({ stack: true }), + winston.format.json(), + winston.format.printf(({ timestamp, level, message, ...meta }) => { + // Remove sensitive data from logs + const sanitizedMeta = sanitizeLogData(meta); + return JSON.stringify({ + timestamp, + level, + message, + ...sanitizedMeta + }); + }) + ), + transports: [ + new winston.transports.File({ filename: 'logs/error.log', level: 'error' }), + new winston.transports.File({ filename: 'logs/combined.log' }), + ...(process.env.NODE_ENV !== 'production' ? [new winston.transports.Console()] : []) + ] + }); +} + +function sanitizeLogData(data) { + const sensitiveKeys = ['apikey', 'password', 'token', 'secret']; + const sanitized = { ...data }; + + Object.keys(sanitized).forEach(key => { + if (sensitiveKeys.some(sensitive => key.toLowerCase().includes(sensitive))) { + sanitized[key] = '[REDACTED]'; + } + }); + + return sanitized; +} +``` + +With security measures in place, let's explore what comes next in your Chimoney integration journey. + ## Next Steps +Congratulations! You've successfully set up your Chimoney API integration environment. Now it's time to put everything to work and start building amazing financial applications. + ### Immediate Actions -- Complete the setup test to ensure everything is working -- Join the Chimoney Discord community for support -- Bookmark the API documentation for reference -- Set up monitoring for your API usage +Before diving into development, complete these essential tasks: + +**1. Complete Your Setup Verification** +- Run the setup test script one final time to ensure everything is working +- Document any configuration specific to your environment +- Create a backup of your working configuration + +**2. Join the Chimoney Community** +- Join the [Chimoney Discord community](https://discord.gg/TsyKnzT4qV) for real-time support and discussions +- Follow Chimoney on social media for updates and announcements +- Bookmark the API documentation for quick reference + +**3. Set Up Monitoring** +- Configure logging for your API usage +- Set up alerts for API errors or unusual usage patterns +- Create a simple dashboard to track your integration's health + +**4. Plan Your Development Approach** +- Define your specific use cases and requirements +- Create a timeline for your integration milestones +- Identify potential challenges and plan solutions ### Development Roadmap -- **Week 1:** Complete setup and basic integration -- **Week 2:** Implement wallet address creation -- **Week 3:** Add error handling and logging -- **Week 4:** Build user interface and testing +Here's a suggested timeline for building your Chimoney integration: + +**Week 1: Foundation Building** +- Complete setup and basic integration testing +- Implement your first wallet address creation +- Set up error handling and logging systems +- Create basic unit tests + +**Week 2: Core Functionality** +- Build the main wallet creation workflow +- Implement user management features +- Add input validation and security measures +- Expand your test coverage + +**Week 3: Polish and Enhancement** +- Add comprehensive error handling +- Implement rate limiting and optimization +- Build monitoring and alerting systems +- Conduct thorough integration testing + +**Week 4: User Experience and Testing** +- Create user-friendly interfaces +- Implement proper error messages for users +- Conduct user acceptance testing +- Prepare for production deployment ### Advanced Features to Explore -- **Webhooks:** Set up real-time notifications -- **Multi-currency wallets:** Expand payment options -- **Bulk operations:** Handle multiple transactions -- **Analytics:** Track usage and performance -- **Mobile SDKs:** Extend to mobile applications +As your integration matures, consider these advanced capabilities: + +**Webhooks for Real-Time Notifications** + +Webhooks allow your application to receive real-time updates about transactions and account changes: + +```javascript +// Example webhook handler +app.post('/webhooks/chimoney', (req, res) => { + const signature = req.headers['x-signature']; + const payload = req.body; + + // Verify webhook signature + const expectedSignature = createSignature(payload, process.env.WEBHOOK_SECRET); + + if (signature === expectedSignature) { + // Process the webhook + handleChimoneyWebhook(payload); + res.status(200).send('OK'); + } else { + res.status(401).send('Unauthorized'); + } +}); +``` + +**Multi-Currency Wallet Support** + +Expand your integration to support multiple currencies and payment methods: + +```javascript +async function createMultiCurrencyWallet(userID, currencies = ['USD', 'NGN', 'GHS']) { + const walletPromises = currencies.map(currency => + createCurrencySpecificWallet(userID, currency) + ); + + const wallets = await Promise.all(walletPromises); + return wallets; +} +``` + +**Bulk Operations for Scale** + +Handle multiple operations efficiently: + +```javascript +async function createWalletsInBatch(users) { + const batchSize = 10; // Process 10 at a time + const results = []; + + for (let i = 0; i < users.length; i += batchSize) { + const batch = users.slice(i, i + batchSize); + const batchResults = await Promise.allSettled( + batch.map(user => createInterledgerWalletAddress(user.id, user.username)) + ); + results.push(...batchResults); + + // Add delay between batches to respect rate limits + if (i + batchSize < users.length) { + await new Promise(resolve => setTimeout(resolve, 1000)); + } + } + + return results; +} +``` + +**Analytics and Reporting** + +Track important metrics about your integration: + +```javascript +class ChimoneyAnalytics { + constructor() { + this.metrics = { + walletsCreated: 0, + apiCalls: 0, + errors: 0, + responseTime: [] + }; + } + + recordWalletCreation() { + this.metrics.walletsCreated++; + } + + recordApiCall(responseTime) { + this.metrics.apiCalls++; + this.metrics.responseTime.push(responseTime); + } + + recordError() { + this.metrics.errors++; + } + + getReport() { + return { + ...this.metrics, + averageResponseTime: this.metrics.responseTime.reduce((a, b) => a + b, 0) / this.metrics.responseTime.length || 0, + errorRate: this.metrics.errors / this.metrics.apiCalls || 0 + }; + } +} +``` + +**Mobile Integration** + +Extend your integration to mobile applications: + +```javascript +// React Native example +import { ChimoneyClient } from './chimoney-client'; + +const MobileWalletService = { + async createWalletForUser(userData) { + try { + const client = new ChimoneyClient(); + const result = await client.createInterledgerWalletAddress( + userData.id, + userData.username + ); + + if (result.success) { + // Store wallet address locally + await AsyncStorage.setItem(`wallet_${userData.id}`, result.walletAddress); + } + + return result; + } catch (error) { + console.error('Mobile wallet creation failed:', error); + throw error; + } + } +}; +``` ### Support Resources -- **Discord Community:** https://discord.gg/TsyKnzT4qV -- **Email Support:** support@chimoney.io -- **API Documentation:** Chimoney Developer Docs -- **Status Page:** Check for API status updates -- **GitHub Examples:** Look for community examples and integrations +As you build your integration, these resources will be invaluable: + +**Primary Support Channels:** +- **Discord Community**: [https://discord.gg/TsyKnzT4qV](https://discord.gg/TsyKnzT4qV) - Real-time help from the community +- **Email Support**: support@chimoney.io - Official technical support +- **API Documentation**: Comprehensive guides and reference materials + +**Development Resources:** +- **GitHub Examples**: Community-contributed integration examples +- **Status Page**: Real-time API status and maintenance updates +- **Developer Blog**: Best practices, tutorials, and feature announcements + +**Best Practices for Getting Help:** +1. **Search first**: Check Discord and documentation for similar issues +2. **Provide context**: Include relevant code, error messages, and steps to reproduce +3. **Be specific**: Describe exactly what you're trying to achieve +4. **Share minimal examples**: Create simple test cases that demonstrate the issue + +### Preparing for Production + +When you're ready to deploy your integration: + +**1. Security Checklist** +- [ ] Production API keys are stored securely +- [ ] All sensitive data is properly encrypted +- [ ] Rate limiting is implemented +- [ ] Input validation is comprehensive +- [ ] Error handling doesn't expose sensitive information + +**2. Performance Checklist** +- [ ] API calls are optimized and cached where appropriate +- [ ] Timeout values are set appropriately +- [ ] Retry logic is implemented for transient failures +- [ ] Database queries are optimized +- [ ] Monitoring and alerting are configured + +**3. User Experience Checklist** +- [ ] Error messages are user-friendly +- [ ] Loading states are implemented +- [ ] Success confirmations are clear +- [ ] Help documentation is available +- [ ] Support contact information is easily accessible --- -**Congratulations! 🎉** You now have a fully configured development environment for the Chimoney API. You're ready to start building amazing financial applications that connect users across the globe. +## Conclusion + +**Congratulations! 🎉** You now have a fully configured development environment for the Chimoney API, complete with security best practices, error handling, and testing capabilities. You're ready to start building amazing financial applications that connect users across the globe. + +### Key Achievements + +Through this guide, you have: + +- ✅ Created and verified your Chimoney developer account +- ✅ Configured a secure development environment +- ✅ Implemented proper API authentication +- ✅ Set up comprehensive testing and debugging tools +- ✅ Learned essential security practices +- ✅ Prepared for scalable, production-ready development + +### Remember the Fundamentals + +As you continue building: + +- **Security First**: Always protect API keys and sensitive data +- **Test Thoroughly**: Verify every integration before going live +- **Monitor Continuously**: Keep track of your API usage and performance +- **Stay Updated**: Follow Chimoney announcements for new features and updates +- **Engage with Community**: Don't hesitate to ask questions and share your experiences + +### Your Next Steps + +1. **Start Building**: Use the foundation you've created to build your specific use case +2. **Join the Community**: Connect with other developers in the Chimoney Discord +3. **Share Your Success**: Help others by documenting your experiences and solutions +4. **Keep Learning**: Explore advanced features as your needs grow + +The combination of Interledger Protocol and Chimoney's robust API provides a powerful foundation for building the next generation of financial applications. Whether you're creating payment solutions for freelancers, building remittance services, or developing e-commerce platforms, you now have the tools and knowledge to succeed. + +**Happy coding!** 🚀 + +--- -Remember to keep your API keys secure, test thoroughly, and reach out to the community when you need help. Happy coding! +*Need help along the way? The Chimoney community is here to support you. Join us on [Discord](https://discord.gg/TsyKnzT4qV) or reach out to support@chimoney.io for assistance.*