nowpayments 0.2.0

data/examples/jwt_authentication_example.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+# JWT Authentication Example
+
+require "nowpayments"
+
+# Initialize client with API key
+client = NOWPayments::Client.new(
+  api_key: "YOUR_API_KEY",
+  sandbox: true # Use sandbox for testing
+)
+
+# ============================================
+# Example 1: Basic Authentication
+# ============================================
+
+puts "Example 1: Basic JWT Authentication"
+puts "=" * 50
+
+# Authenticate to get JWT token (expires in 5 minutes)
+auth_response = client.authenticate(
+  email: "your_email@example.com",
+  password: "your_password"
+)
+
+puts "✅ Authenticated successfully!"
+puts "Token: #{auth_response["token"][0..20]}..."
+puts "Time remaining: #{client.jwt_time_remaining} seconds"
+puts
+
+# ============================================
+# Example 2: Operations Requiring JWT Auth
+# ============================================
+
+puts "Example 2: Creating a Payout (Requires JWT)"
+puts "=" * 50
+
+# Create a payout (requires JWT Bearer token)
+payout_response = client.create_payout(
+  withdrawals: [
+    {
+      address: "TEmGwPeRTPiLFLVfBxXkSP91yc5GMNQhfS",
+      currency: "trx",
+      amount: 10
+    }
+  ],
+  payout_description: "Test payout"
+)
+
+puts "✅ Payout created!"
+puts "Batch ID: #{payout_response["id"]}"
+puts "Status: #{payout_response["withdrawals"].first["status"]}"
+puts
+
+# Verify payout with 2FA code
+client.verify_payout(
+  batch_withdrawal_id: payout_response["id"],
+  verification_code: "123456" # From Google Authenticator or email
+)
+
+puts "✅ Payout verified!"
+puts
+
+# ============================================
+# Example 3: Token Management
+# ============================================
+
+puts "Example 3: Token Lifecycle Management"
+puts "=" * 50
+
+# Check token status
+puts "Token expired? #{client.jwt_expired?}"
+puts "Time remaining: #{client.jwt_time_remaining} seconds"
+puts
+
+# Manual token refresh (if you have credentials stored)
+if client.jwt_time_remaining < 60
+  puts "⚠️  Token expiring soon, re-authenticating..."
+  client.authenticate(
+    email: "your_email@example.com",
+    password: "your_password"
+  )
+  puts "✅ Token refreshed!"
+end
+puts
+
+# ============================================
+# Example 4: Conversions (Requires JWT)
+# ============================================
+
+puts "Example 4: Currency Conversions"
+puts "=" * 50
+
+# All conversion endpoints require JWT authentication
+conversion = client.create_conversion(
+  from_currency: "btc",
+  to_currency: "eth",
+  amount: 0.1
+)
+
+puts "✅ Conversion created!"
+puts "Conversion ID: #{conversion["conversion_id"]}"
+puts
+
+# Check conversion status
+status = client.conversion_status(conversion["conversion_id"])
+puts "Status: #{status["status"]}"
+puts
+
+# ============================================
+# Example 5: Custody Operations (Requires JWT)
+# ============================================
+
+puts "Example 5: Custody/Sub-Account Operations"
+puts "=" * 50
+
+# Create user account
+user = client.create_sub_account(user_id: "user_12345")
+puts "✅ User account created: #{user["result"]["id"]}"
+puts
+
+# Transfer between accounts (requires JWT)
+transfer = client.transfer_between_sub_accounts(
+  currency: "trx",
+  amount: 5,
+  from_id: "111111",
+  to_id: "222222"
+)
+
+puts "✅ Transfer initiated!"
+puts "Transfer ID: #{transfer["result"]["id"]}"
+puts "Status: #{transfer["result"]["status"]}"
+puts
+
+# ============================================
+# Example 6: Recurring Payments (DELETE requires JWT)
+# ============================================
+
+puts "Example 6: Managing Recurring Payments"
+puts "=" * 50
+
+# Delete recurring payment (requires JWT)
+result = client.delete_recurring_payment("subscription_id")
+puts "✅ Recurring payment deleted: #{result["result"]}"
+puts
+
+# ============================================
+# Example 7: Token Cleanup
+# ============================================
+
+puts "Example 7: Token Cleanup"
+puts "=" * 50
+
+# Clear token when done (optional, for security)
+client.clear_jwt_token
+puts "✅ JWT token cleared"
+puts "Token expired? #{client.jwt_expired?}"
+puts
+
+# ============================================
+# Example 8: Auto-Refresh Pattern
+# ============================================
+
+puts "Example 8: Auto-Refresh Pattern"
+puts "=" * 50
+
+# Store credentials for auto-refresh
+EMAIL = "your_email@example.com"
+PASSWORD = "your_password"
+
+# Helper method to ensure authenticated
+def ensure_authenticated(client, email, password)
+  return unless client.jwt_expired?
+
+  puts "🔄 Token expired, re-authenticating..."
+  client.authenticate(email: email, password: password)
+  puts "✅ Re-authenticated!"
+end
+
+# Before each JWT-required operation
+ensure_authenticated(client, EMAIL, PASSWORD)
+payout = client.list_payouts(limit: 10, offset: 0)
+puts "✅ Listed #{payout["count"]} payouts"
+puts
+
+# ============================================
+# Example 9: Multiple Operations Pattern
+# ============================================
+
+puts "Example 9: Efficient Multiple Operations"
+puts "=" * 50
+
+# Authenticate once at the beginning
+client.authenticate(
+  email: "your_email@example.com",
+  password: "your_password"
+)
+
+# Perform multiple operations (token valid for 5 minutes)
+operations = [
+  -> { client.balance },
+  -> { client.list_payouts(limit: 5, offset: 0) },
+  -> { client.list_conversions(limit: 5, offset: 0) },
+  -> { client.sub_account_balances }
+]
+
+operations.each_with_index do |operation, index|
+  # Check if token needs refresh before each operation
+  if client.jwt_expired?
+    puts "🔄 Refreshing token..."
+    client.authenticate(
+      email: "your_email@example.com",
+      password: "your_password"
+    )
+  end
+
+  result = operation.call
+  puts "✅ Operation #{index + 1} completed"
+rescue StandardError => e
+  puts "❌ Operation #{index + 1} failed: #{e.message}"
+end
+puts
+
+# ============================================
+# Example 10: Error Handling
+# ============================================
+
+puts "Example 10: Error Handling"
+puts "=" * 50
+
+begin
+  # Try to create payout without authentication
+  client.clear_jwt_token
+  client.create_payout(
+    withdrawals: [{ address: "TEmGwPeRTPiLFLVfBxXkSP91yc5GMNQhfS", currency: "trx", amount: 10 }]
+  )
+rescue StandardError => e
+  puts "❌ Expected error: #{e.class}"
+  puts "Message: #{e.message}"
+  puts "💡 Solution: Authenticate first!"
+  puts
+
+  # Authenticate and retry
+  client.authenticate(
+    email: "your_email@example.com",
+    password: "your_password"
+  )
+  puts "✅ Authenticated, retry succeeded!"
+end
+
+puts
+puts "=" * 50
+puts "🎉 All JWT authentication examples completed!"
+puts "=" * 50

data/examples/simple_demo.rb

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "nowpayments"
+require "dotenv"
+
+Dotenv.load
+
+# Initialize client
+client = NOWPayments::Client.new(
+  api_key: ENV.fetch("NOWPAYMENTS_SANDBOX_API_KEY", nil),
+  sandbox: true
+)
+
+puts "=== NOWPayments API Demo ===\n\n"
+
+# 1. Check API status
+puts "1. Checking API status..."
+status = client.status
+puts "   Status: #{status["message"]}\n\n"
+
+# 2. Get available currencies
+puts "2. Getting available currencies..."
+currencies = client.currencies
+puts "   Available: #{currencies["currencies"].first(10).join(", ")}...\n\n"
+
+# 3. Get minimum amount
+puts "3. Checking minimum amount for USD -> BTC..."
+min = client.min_amount(currency_from: "usd", currency_to: "btc")
+puts "   Minimum: #{min["min_amount"]} #{min["currency_to"]}\n\n"
+
+# 4. Estimate price
+puts "4. Estimating price for 100 USD in BTC..."
+estimate = client.estimate(
+  amount: 100,
+  currency_from: "usd",
+  currency_to: "btc"
+)
+puts "   Estimated: #{estimate["estimated_amount"]} BTC\n\n"
+
+# 5. Create a payment
+puts "5. Creating a payment..."
+payment = client.create_payment(
+  price_amount: 100.0,
+  price_currency: "usd",
+  pay_currency: "btc",
+  order_id: "demo-#{Time.now.to_i}",
+  order_description: "Demo payment"
+)
+puts "   Payment ID: #{payment["payment_id"]}"
+puts "   Pay Address: #{payment["pay_address"]}"
+puts "   Pay Amount: #{payment["pay_amount"]} #{payment["pay_currency"]}"
+puts "   Status: #{payment["payment_status"]}\n\n"
+
+# 6. Check payment status
+puts "6. Checking payment status..."
+status = client.payment(payment["payment_id"])
+puts "   Current status: #{status["payment_status"]}\n\n"
+
+# 7. Create an invoice
+puts "7. Creating an invoice..."
+invoice = client.create_invoice(
+  price_amount: 50.0,
+  price_currency: "usd",
+  order_id: "invoice-#{Time.now.to_i}"
+)
+puts "   Invoice ID: #{invoice["id"]}"
+puts "   Invoice URL: #{invoice["invoice_url"]}\n\n"
+
+puts "=== Demo Complete ===\n"
+puts "All endpoints working correctly!"

data/examples/webhook_server.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# Example Sinatra webhook receiver
+#
+# Usage:
+#   ruby examples/webhook_server.rb
+#   Then use ngrok to expose: ngrok http 4567
+#   Configure the ngrok URL in NOWPayments dashboard
+
+require "sinatra"
+require "nowpayments"
+require "dotenv"
+require "json"
+
+Dotenv.load
+
+# Configure logging
+set :logging, true
+
+# Webhook endpoint
+post "/webhooks/nowpayments" do
+  # Verify the webhook
+  payload = NOWPayments::Rack.verify_webhook(
+    request,
+    ENV.fetch("NOWPAYMENTS_SANDBOX_IPN_SECRET", nil)
+  )
+
+  logger.info "Received verified webhook: #{payload.inspect}"
+
+  # Handle different payment statuses
+  case payload["payment_status"]
+  when "finished"
+    logger.info "✅ Payment #{payload["payment_id"]} completed!"
+    logger.info "   Order: #{payload["order_id"]}"
+    logger.info "   Amount: #{payload["outcome_amount"]} #{payload["outcome_currency"]}"
+
+    # TODO: Fulfill order here
+    # Order.find_by(id: payload['order_id'])&.mark_paid!
+
+  when "failed"
+    logger.warn "❌ Payment #{payload["payment_id"]} failed"
+
+    # TODO: Cancel order here
+    # Order.find_by(id: payload['order_id'])&.cancel!
+
+  when "partially_paid"
+    logger.warn "⚠️  Payment #{payload["payment_id"]} partially paid"
+    logger.warn "   Expected: #{payload["pay_amount"]} #{payload["pay_currency"]}"
+    logger.warn "   Received: #{payload["actually_paid"]} #{payload["pay_currency"]}"
+
+  when "expired"
+    logger.info "⏱️  Payment #{payload["payment_id"]} expired"
+
+  else
+    logger.info "ℹ️  Payment #{payload["payment_id"]} status: #{payload["payment_status"]}"
+  end
+
+  # Always return 200 OK to acknowledge receipt
+  status 200
+  { success: true }.to_json
+rescue NOWPayments::SecurityError => e
+  # Invalid signature - potential fraud
+  logger.error "🔒 Security Error: #{e.message}"
+  status 403
+  { error: "Invalid signature" }.to_json
+rescue StandardError => e
+  # Other errors
+  logger.error "❌ Error processing webhook: #{e.message}"
+  logger.error e.backtrace.join("\n")
+  status 500
+  { error: "Internal server error" }.to_json
+end
+
+# Health check endpoint
+get "/health" do
+  { status: "ok", timestamp: Time.now.to_i }.to_json
+end
+
+# Start message
+puts "\n=== NOWPayments Webhook Server ==="
+puts "Listening on http://localhost:4567"
+puts "Webhook URL: http://localhost:4567/webhooks/nowpayments"
+puts "\nTo expose publicly, use ngrok:"
+puts "  ngrok http 4567"
+puts "\nThen configure the ngrok URL in NOWPayments dashboard\n\n"

data/lib/nowpayments/api/authentication.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module NOWPayments
+  module API
+    # JWT authentication endpoints
+    module Authentication
+      # Authenticate and obtain JWT token
+      # POST /v1/auth
+      # JWT tokens expire in 5 minutes for security reasons
+      # @param email [String] Your NOWPayments dashboard email (case-sensitive)
+      # @param password [String] Your NOWPayments dashboard password (case-sensitive)
+      # @return [Hash] Authentication response with JWT token
+      # @note Email and password are case-sensitive. test@gmail.com != Test@gmail.com
+      def authenticate(email:, password:)
+        response = post("auth", body: {
+                          email: email,
+                          password: password
+                        })
+
+        # Store token and expiry time (5 minutes from now)
+        if response.body["token"]
+          @jwt_token = response.body["token"]
+          @jwt_expires_at = Time.now + 300 # 5 minutes = 300 seconds
+
+          # Reset connection to include new Bearer token
+          reset_connection! if respond_to?(:reset_connection!, true)
+        end
+
+        response.body
+      end
+
+      # Get current JWT token (refreshes if expired)
+      # @param email [String, nil] Email for re-authentication if token expired
+      # @param password [String, nil] Password for re-authentication if token expired
+      # @return [String, nil] Current valid JWT token or nil
+      def jwt_token(email: nil, password: nil)
+        # Auto-refresh if expired and credentials provided
+        authenticate(email: email, password: password) if jwt_expired? && email && password
+
+        @jwt_token
+      end
+
+      # Check if JWT token is expired
+      # @return [Boolean] True if token is expired or not set
+      def jwt_expired?
+        !@jwt_token || !@jwt_expires_at || Time.now >= @jwt_expires_at
+      end
+
+      # Manually clear JWT token (e.g., for logout)
+      # @return [void]
+      def clear_jwt_token
+        @jwt_token = nil
+        @jwt_expires_at = nil
+      end
+
+      # Get time remaining until JWT token expires
+      # @return [Integer, nil] Seconds until expiry, or nil if no token
+      def jwt_time_remaining
+        return nil unless @jwt_token && @jwt_expires_at
+
+        remaining = (@jwt_expires_at - Time.now).to_i
+        remaining.positive? ? remaining : 0
+      end
+    end
+  end
+end

data/lib/nowpayments/api/conversions.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module NOWPayments
+  module API
+    # Conversion endpoints (requires JWT auth)
+    module Conversions
+      # Create a new conversion between currencies
+      # POST /v1/conversion
+      # Requires JWT authentication
+      # @param from_currency [String] Source currency code
+      # @param to_currency [String] Target currency code
+      # @param amount [Numeric] Amount to convert
+      # @return [Hash] Conversion details
+      def create_conversion(from_currency:, to_currency:, amount:)
+        post("conversion", body: {
+               from_currency: from_currency,
+               to_currency: to_currency,
+               amount: amount
+             }).body
+      end
+
+      # Get status of a specific conversion
+      # GET /v1/conversion/:conversion_id
+      # Requires JWT authentication
+      # @param conversion_id [String, Integer] Conversion ID
+      # @return [Hash] Conversion status details
+      def conversion_status(conversion_id)
+        get("conversion/#{conversion_id}").body
+      end
+
+      # List all conversions with pagination
+      # GET /v1/conversion
+      # Requires JWT authentication
+      # @param limit [Integer] Results per page
+      # @param offset [Integer] Offset for pagination
+      # @return [Hash] List of conversions
+      def list_conversions(limit: 10, offset: 0)
+        get("conversion", params: { limit: limit, offset: offset }).body
+      end
+    end
+  end
+end

data/lib/nowpayments/api/currencies.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module NOWPayments
+  module API
+    # Currency-related endpoints
+    module Currencies
+      # Get list of available currencies
+      # GET /v1/currencies
+      # @param fixed_rate [Boolean, nil] Optional flag to get currencies with min/max exchange amounts
+      # @return [Hash] Available currencies
+      def currencies(fixed_rate: nil)
+        params = {}
+        params[:fixed_rate] = fixed_rate unless fixed_rate.nil?
+        get("currencies", params: params).body
+      end
+
+      # Get list of available currencies with full info
+      # GET /v1/full-currencies
+      # @return [Hash] Full currency information
+      def full_currencies
+        get("full-currencies").body
+      end
+
+      # Get list of available currencies checked by merchant
+      # GET /v1/merchant/coins
+      # @return [Hash] Merchant's checked currencies
+      def merchant_coins
+        get("merchant/coins").body
+      end
+    end
+  end
+end

data/lib/nowpayments/api/custody.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module NOWPayments
+  module API
+    # Custody/sub-partner endpoints for managing customer accounts
+    module Custody
+      # Create a new sub-account (user account)
+      # POST /v1/sub-partner/balance
+      # @param user_id [String] Unique user identifier (your internal user ID)
+      # @return [Hash] Created sub-account details
+      def create_sub_account(user_id:)
+        post("sub-partner/balance", body: { Name: user_id }).body
+      end
+
+      # Get balance for a specific sub-account
+      # GET /v1/sub-partner/balance/:user_id
+      # @param user_id [String] User identifier (path parameter)
+      # @return [Hash] User balance details
+      def sub_account_balance(user_id)
+        get("sub-partner/balance/#{user_id}").body
+      end
+
+      # Get balance for all sub-accounts
+      # GET /v1/sub-partner/balance
+      # @return [Hash] Array of all user balances
+      def sub_account_balances
+        get("sub-partner/balance").body
+      end
+
+      # List sub-accounts with filters
+      # GET /v1/sub-partner
+      # @param id [String, Integer, Array, nil] Filter by specific user ID(s)
+      # @param limit [Integer] Results per page
+      # @param offset [Integer] Offset for pagination
+      # @param order [String] Sort order (ASC or DESC)
+      # @return [Hash] List of sub-accounts
+      def list_sub_accounts(id: nil, limit: 10, offset: 0, order: "ASC")
+        params = { limit: limit, offset: offset, order: order }
+        params[:id] = id if id
+
+        get("sub-partner", params: params).body
+      end
+
+      # Transfer between sub-accounts
+      # POST /v1/sub-partner/transfer
+      # @param currency [String] Currency code
+      # @param amount [Numeric] Amount to transfer
+      # @param from_id [String, Integer] Source sub-account ID
+      # @param to_id [String, Integer] Destination sub-account ID
+      # @return [Hash] Transfer result
+      def transfer_between_sub_accounts(currency:, amount:, from_id:, to_id:)
+        post("sub-partner/transfer", body: {
+               currency: currency,
+               amount: amount,
+               from_id: from_id,
+               to_id: to_id
+             }).body
+      end
+
+      # Create deposit request for sub-account (external crypto deposit)
+      # POST /v1/sub-partner/deposit
+      # @param user_id [String] User identifier
+      # @param currency [String] Cryptocurrency code
+      # @param amount [Numeric, nil] Optional amount
+      # @return [Hash] Deposit address and details
+      def create_sub_account_deposit(user_id:, currency:, amount: nil)
+        params = {
+          Name: user_id,
+          currency: currency
+        }
+        params[:amount] = amount if amount
+
+        post("sub-partner/deposit", body: params).body
+      end
+
+      # Create payment deposit for sub-account
+      # POST /v1/sub-partner/payment
+      # @param sub_partner_id [String, Integer] Sub-account ID
+      # @param currency [String] Currency code
+      # @param amount [Numeric] Payment amount
+      # @param fixed_rate [Boolean, nil] Fixed rate flag
+      # @return [Hash] Payment deposit details
+      def create_sub_account_payment_deposit(sub_partner_id:, currency:, amount:, fixed_rate: nil)
+        params = {
+          sub_partner_id: sub_partner_id,
+          currency: currency,
+          amount: amount
+        }
+        params[:fixed_rate] = fixed_rate unless fixed_rate.nil?
+
+        post("sub-partner/payment", body: params).body
+      end
+
+      # Transfer funds from master account to sub-account
+      # POST /v1/sub-partner/deposit-from-master
+      # @param user_id [String] User identifier
+      # @param currency [String] Cryptocurrency code
+      # @param amount [Numeric] Amount to transfer
+      # @return [Hash] Transfer result
+      def transfer_to_sub_account(user_id:, currency:, amount:)
+        post("sub-partner/deposit-from-master", body: {
+               Name: user_id,
+               currency: currency,
+               amount: amount
+             }).body
+      end
+
+      # Write-off (withdraw) funds from sub-account to master account
+      # POST /v1/sub-partner/write-off
+      # @param user_id [String] User identifier
+      # @param currency [String] Cryptocurrency code
+      # @param amount [Numeric] Amount to withdraw
+      # @return [Hash] Write-off result
+      def withdraw_from_sub_account(user_id:, currency:, amount:)
+        post("sub-partner/write-off", body: {
+               Name: user_id,
+               currency: currency,
+               amount: amount
+             }).body
+      end
+
+      # Get details of a specific transfer
+      # GET /v1/sub-partner/transfer
+      # @param transfer_id [String, Integer] Transfer ID
+      # @return [Hash] Transfer details
+      def sub_account_transfer(transfer_id)
+        get("sub-partner/transfer", params: { id: transfer_id }).body
+      end
+
+      # Get list of all transfers
+      # GET /v1/sub-partner/transfers
+      # @param id [String, Integer, Array, nil] Filter by specific transfer ID(s)
+      # @param status [String, Array, nil] Filter by status (CREATED, WAITING, FINISHED, REJECTED)
+      # @param limit [Integer] Results per page
+      # @param offset [Integer] Offset for pagination
+      # @param order [String] Sort order (ASC or DESC)
+      # @return [Hash] List of transfers
+      def sub_account_transfers(id: nil, status: nil, limit: 10, offset: 0, order: "ASC")
+        params = { limit: limit, offset: offset, order: order }
+        params[:id] = id if id
+        params[:status] = status if status
+
+        get("sub-partner/transfers", params: params).body
+      end
+    end
+  end
+end