🔄How Auto-Pay Works

This guide explains the complete auto-pay flow from start to finish.

The Complete Flow

Phase 1: Setup (One-Time)

Group Configuration:

1. Group owner enables Premium Group status

2. Admin enables auto-pay in /settings

3. Admin selects payment token (e.g., USDT on BSC)

4. Settings saved ✅

User Preparation:

1. User opens bot via DM

2. Goes to Profile → Set Up Wallet

3. Selects correct chain (SOL or BSC)

4. Sends wallet address

5. Wallet validated and saved ✅

Phase 2: Starting Competition

Step 1: Initiate

Admin: /start_competition
Bot: Select duration...
Admin: Clicks "7 days"

Step 2: Payment Request If auto-pay enabled and token configured:

Bot → Admin (DM):
💰 Competition Payment Required

Prize Pool: $100.00
Service Fee (5%): $5.00
━━━━━━━━━━━━━━━
Total: $105.00 USD

💳 Send Payment To:
Network: BEP-20 (BSC)
Currency: USDT
Amount: 105.234567 USDT

Address: 0x7DB6962DB504...

⚠️ Important:
• Send EXACTLY 105.234567 USDT
• Do NOT send from an exchange
• Use BEP-20 (BSC) network
• Payment expires in 15 minutes

[Pay Now - Opens payment page]

Step 3: Payment Processing

Admin → Sends crypto to address
Bot ← Receives IPN notification
Bot → Validates payment
Bot → Updates payment status: confirmed ✅

Step 4: Distribution Setup

Bot → Admin (Group):
💰 Payment Confirmed!

Select prize distribution:
[🥇🥈 Top 2: 60-40]
[🥇🥈🥉 Top 3: 50-30-20]
[🥇🥈🥉 Top 3: 70-20-10]
[🎯 Top 5: 40-25-15-12-8]
[✏️ Custom Split]

Admin selects or types custom split:

Admin: 30, 25, 20, 15, 10
Bot: ✅ Distribution configured for 5 winners

Step 5: Competition Starts

Bot → Group:
🎉 Competition Started!

Duration: 7 days
Payment: Confirmed ✅
Distribution: Custom (5 winners) ✅

Payments will be made to winners' wallet 
addresses automatically.

[Get My Referral Link]

Phase 3: During Competition

Users Participating:

User clicks [Get My Referral Link]
Bot → User (DM): Sends unique referral link
User → Shares link everywhere
Friends → Click link, join, verify captcha
Bot → Updates scores in real-time
Leaderboard → Auto-updates every minute

Wallet Requirement Enforcement:

User (no wallet) → Tries to get referral link
Bot → User:
🔒 Wallet Required

This group has auto-pay enabled with USDT (BSC).
You need to set up your BSC wallet address 
before getting your referral link.

[💰 Set Up Wallet]

Phase 4: Competition Ends

Automatic Ending:

7 days pass...
Bot → Checks if time expired
Bot → Triggers end competition flow

Or Manual Ending:

Admin: /end_competition
Bot → Confirms: "End now?"
Admin: Yes
Bot → Triggers end competition flow

Phase 5: Automatic Payouts

Step 1: Fetch Data

Bot retrieves:
- Final leaderboard (top participants)
- Payment record (prize pool, currency)
- Distribution settings (percentages)
- Winner wallet addresses

Step 2: Calculate Amounts

For stablecoins (USDT/USDC):
  Rate = 1.0 (direct USD conversion)

For native tokens (SOL/BNB):
  Rate = actual_crypto_paid / total_usd
  (derived from payment data)

For each winner:
  Amount = (prize_pool_usd × percentage) / rate
  Rounded to 8 decimals, rounded down

Example:

Prize Pool: $100 USD
Token: SOL
Actual paid: 0.85 SOL for $105 total
Rate: (0.85 × 100/105) = 0.809523809...

Winner 1 (50%): 
  $50 ÷ 0.809523809 = 0.61764705 SOL

Winner 2 (30%):
  $30 ÷ 0.809523809 = 0.37058823 SOL

Winner 3 (20%):
  $20 ÷ 0.809523809 = 0.24705882 SOL

Step 3: Validate Wallets

For each winner:
  Check if wallet address exists
  Check if wallet matches token chain
  If invalid → Skip, add to withheld
  If valid → Proceed to payment

Step 4: Execute Payouts

For each valid winner:
  Create payout record in DB
  Call NowPayments API:
    POST /payout
    {
      currency: "sol",
      amount: "0.61764705",
      address: "8xK3r...",
      description: "Competition Winner"
    }
  Receive payout_id: "5000248325"
  Update DB with payout_id

Step 5: Payment Processing

NowPayments processes payment
Sends to blockchain
Bot receives IPN callback:
  {
    payout_id: "5000248325",
    status: "finished",
    hash: "0x47701..."
  }
Bot updates DB: status = finished
Bot sends confirmation to winner

Step 6: Notifications

Bot → Group:
💰 Competition Ended - Payouts Complete!

✅ Paid Successfully:
1. @user1 - 0.61764705 SOL ✅
2. @user2 - 0.37058823 SOL ✅
3. @user3 - 0.24705882 SOL ✅

All payments sent automatically!

Bot → Each Winner (DM):
🎉 Congratulations!

You won 3rd place in "ProjectX Group"!
Prize: 0.24705882 SOL

💰 Payment sent to your wallet:
8xK3r...jF9u

Transaction: 0x47701...0ec4

Check your wallet!

Phase 6: Final Leaderboard

Bot → Group (pinned):
🏁 Competition Ended!

🏆 Final Leaderboard 🏆

Regular: 1 pts | Premium: 3 pts

🥇 Alice: 45 pts (15 refs) 🎊
🥈 Bob: 38 pts (12 refs) 🎊
🥉 Charlie: 31 pts (10 refs) 🎊
4. David: 27 pts (9 refs)
5. Eve: 22 pts (7 refs)

🎉 Congratulations to the top 3 winners!
Prize: $100 in SOL

💰 Auto-pay enabled
Winners received automatic payments to their 
wallet addresses.

Thank you for participating!

Error Scenarios

Invalid Wallet Address

Winner has invalid wallet:
  Bot skips payment for that winner
  Amount added to withheld_amount
  Other winners still get paid
  
Bot → Group:
⚠️ 1 payment withheld due to invalid wallet
Contact @user4 to update wallet address

Bot → Admin:
ACTION REQUIRED: User @user4 has invalid 
wallet. Amount withheld: 0.12345678 SOL

Payment Below Minimum

Winner's calculated amount < minimum withdrawal:
  Bot skips payment
  Amount added to withheld
  Logs error
  
Bot → Group:
⚠️ 1 payout below minimum threshold

Network Failure

NowPayments API temporarily down:
  Bot retries automatically
  If persistent, logs critical alert
  Admin notified via monitoring system

Currency Consistency

Enforcement Rules

✅ Deposit and payout ALWAYS match

Deposited in USDT → Paid out in USDT
Deposited in SOL → Paid out in SOL
Never any currency conversion

✅ Token locked during active competition

Admin tries to change token:
Bot: ❌ Cannot change token while competition 
     is active or payment is pending

✅ Verification before payout

Before sending any payment:
  Check: payment_token == payout_token
  If mismatch: ABORT, send critical alert

Transaction Records

All payouts tracked in database:

competition_payouts table:
- payout_id
- competition_id
- winner_user_id
- rank
- percentage
- amount_crypto (8 decimal precision)
- currency
- wallet_address
- nowpayments_payout_id
- payout_status (pending/finished/failed)
- payout_hash (blockchain tx)
- error_message (if any)
- created_at, completed_at

Monitoring & Alerts

Critical Alerts (Sent to monitoring group)

• Database connection failures

• Payment verification failures

• Currency mismatches

• Payout API errors

Action Required Alerts

• Partial payments received

• Individual payout failures

• Invalid wallet addresses

• Amounts below minimum

All alerts include full context - payment IDs, amounts, currencies, error messages - for quick debugging.