# DiscordForge

## Overview
DiscordForge (discordforge.org) is a manually curated Discord bot, server, and template directory. Founded in 2025 by a Polish team, it is the first Polish-founded platform of this type. Every listing is reviewed by a human moderator before going live. Available in English and Polish.

## Core Philosophy
Unlike top.gg (which accepts any bot automatically) or Disboard (community-submitted servers with no review), DiscordForge manually reviews every single submission. Smaller catalog, higher quality. The goal is to surface the best projects, not the most projects.

## How Submissions Work
1. Developer submits bot/server/template via discordforge.org/add
2. Human moderator reviews within 24-48 hours (Forge/Premium: up to 24h, Free: 24-48h)
3. If approved: listing goes live and is searchable
4. If rejected: developer gets a DM with the reason and can resubmit after fixing

## Verification Requirements

### Bot Verification
- Online 24/7 (99%+ uptime) for 7 consecutive days
- In at least 100 servers
- Complete profile: description, commands listed, invite link
- No malicious code, excessive permissions, or data collection without consent
- Must comply with Discord ToS

### Server Verification
- At least 100 members with active engagement
- Active moderation and clear rules
- Professional appearance (icon, description, layout)
- Must comply with Discord ToS

### How to Apply for Verification
1. Go to Dashboard
2. Navigate to Statistics tab
3. Click "Apply for Verification" in Quick Actions
4. Wait 3-7 days (Free), up to 24h (Premium/Forge)

## Pricing & Plans

### Free - $0/month
- List bots, servers, templates
- Basic stats (votes, views, invite clicks)
- Vote once per 12 hours
- Bump every 2 hours (coming soon)

### Premium - $1.99/month
- Premium badge on profile
- Feature 1 project in catalog (catalog highlighting, cyan border/glow)
- Higher ranking in catalog
- Faster support replies
- Full analytics: CTR, traffic sources, heatmaps, vote graphs
- Bump every 1 hour (coming soon)

### Forge - $3.99/month
- Forge badge on profile
- Feature 2 projects in catalog (orange border/glow)
- All Premium features
- Export analytics data
- Priority verification (instant review)
- Early access to new features
- Direct support channel with the team
- Bump every 30 minutes (coming soon)

### Pioneer - Limited, referral-based, no monthly cost
- All Forge perks
- Permanent Pioneer badge (never obtainable once program ends)
- Free 3-day Forge Boost every month
- How to earn: refer a bot/server owner, they submit and mention your username in a Discord ticket - both get free Forge + Pioneer badge

## Forge Boost (Paid Promotion)
Separate from subscription tiers. Boosts your project to the Featured section on homepage and top of category results.
- Durations: 1, 3, 7, 30 days, or custom (1-30)
- Stackable - buying multiple boosts adds duration
- Can be purchased by anyone on any tier

## Voting System
- Users vote for bots/servers once every 12 hours
- Votes determine ranking position
- Weekly vote count resets every Monday at 00:00 UTC
- Vote manipulation (bots, scripts, bought votes, alt accounts) = permanent ban
- Developers can set up vote reward webhooks - when a user votes, DiscordForge sends a POST request to their server so they can reward the voter

## Vote Reward Webhooks (for developers)
When someone votes for your bot, DiscordForge fires a webhook to your configured URL with:
- User Discord ID and username
- Vote timestamp
- Weekly and total vote counts
Setup: Dashboard → Edit bot → Vote Webhook section

## API (for developers)
Base URL: https://discordforge.org

Official SDKs:
- Node.js (npm): discordforge-sdk
- Python (PyPI): discordforge

POST /api/v1/bots/stats - Update your bot's server count (rate limit: 1 req/5 min)
GET /api/bots/:id/votes/check?userId=... - Check if a user has voted (rate limit: 60 req/min)
GET /api/bots/:id - Fetch public bot info (no auth required)
POST /api/v1/bots/commands - Sync slash commands to DiscordForge (replaces all, max 200)
GET/POST /api/v1/bots/heartbeat - Record a push uptime heartbeat
GET /api/v1/bump/cooldown?userId=...&serverId=... - Check a user's bump cooldown
PATCH /api/v1/bots/listing - Update the authenticated approved bot's safe listing fields (20 writes/hour)
POST /api/v1/bots/announcements - Publish an approved bot's sanitized release update (10 posts/hour)

Auth: Authorization: Bearer YOUR_BOT_API_KEY
Get your API key: Dashboard → Edit bot → API Access section

Migration: POST /api/external/bots/commands, GET/POST /api/external/bots/heartbeat, GET /api/external/bump/cooldown, and POST /api/bots/stats return 410 Gone from 14 October 2026, 00:00 UTC. See https://discordforge.org/support/developers#api-v1-migration.

## Ranking System
- Votes are the primary ranking factor (all-time + weekly)
- Premium/Forge gives catalog highlighting and featured slots, NOT vote manipulation
- A free bot with more votes outranks a paid bot with fewer votes
- Weekly trending = bots with highest vote growth this week

## XP & Leveling System
Users earn XP through activity on DiscordForge:
- Adding a bot: 100 XP
- Bot gets verified: 200 XP
- Writing a review: 10 XP (max 5 reviews/day)
- Receiving a review on your bot: 15 XP (max 10/day)
- Voting: 5 XP
- Daily login: 10-40 XP (increases with streak)
- 7-day login streak: 50 XP bonus
- 30-day login streak: 200 XP bonus + badge

Levels follow: Level = sqrt(totalXP / 100)
Titles: Apprentice → Forgemaster (Level 20+)

Leaderboards: all-time, weekly, monthly - visible at discordforge.org/leaderboard

## Achievements
Automatic badges awarded for milestones:
- First Steps - reach Level 1 (25 XP reward)
- Getting Started - add first bot (50 XP)
- Reviewer - write 5 reviews (50 XP)
- Week Warrior - 7-day login streak (75 XP)
- Rising Star - reach Level 5 (100 XP)
- Bot Factory - have 3 approved bots (150 XP)
- Popular - receive 100 total votes (150 XP)
- Artisan - reach Level 10 (200 XP)
- Dedicated - 30-day login streak (200 XP)
- Forgemaster - reach Level 20 (500 XP)

## Bot/Project Quality Badges (automatic)
- Rising Star: 50%+ vote increase in past week
- Hot This Week: top 5% of weekly votes, min 100 weekly votes (resets Monday)
- Trending: 250+ total votes, 4.5+ rating, consistent 30-day activity
- 4.8+ Rating: average 4.8 stars from 10+ unique reviews
- Top 1% Voted: top 1% all-time, min 1000 global votes
- Trusted Developer: 2+ verified bots, no recent violations
- Forge Verified: passed full verification process

## Collections
Users can create public/private curated lists of bots. Up to 3 collections can be pinned to your profile. Featured collections are admin-curated.

## Forge Synergy (Cross-promotion)
Link your bot with a "Perfect Match" partner bot or server. Both projects appear on each other's pages as recommended companions. Proposal → Accept → Cross-promotion active.

## Analytics (Premium/Forge)
- Activity Heatmap: peak activity days and hours
- Top Countries: geographic breakdown
- CTR (Click-Through Rate): how effective your banner is
- Conversion Rate: profile views → actual invites
- Traffic Sources: where visitors come from
- Votes per Hour: granular voting data

## Platform Rules Summary
- Must be 13+ to use (Discord ToS requirement)
- No vote manipulation of any kind (bots, scripts, bought votes, alts)
- No malicious bots, spam, phishing, data collection without consent
- Reviews must be honest and based on real experience
- No harassment, impersonation, or abuse
- Subscriptions renew monthly, can be cancelled anytime
- Refund available within 14 days if premium features weren't used (EU law)
- Governing law: Poland (GDPR compliant)

## Privacy (Key Points)
- Data collected: Discord User ID, username, email, avatar (via OAuth2)
- Payment processing via Stripe (card data never touches DiscordForge servers)
- Analytics via Google Analytics 4 (IP anonymized)
- Data never sold to third parties
- Account deletion: personal data removed within 30 days
- Contact for privacy questions: contact@discordforge.org
- Compliant with GDPR and Polish data protection law

## Terms of Service (Key Points)
- Full ToS: discordforge.org/rules
- Vote manipulation = permanent ban
- Projects removed that violate Discord ToS
- DiscordForge not responsible for bot behavior in servers
- Disputes: Polish courts

## Common Questions

Q: Is DiscordForge a top.gg replacement?
A: No. top.gg has millions of listings with automated submission. DiscordForge is smaller and every project is manually reviewed. Different use case: DF for verified quality, top.gg for volume.

Q: How long does review take?
A: Free users: 24-48 hours. Premium/Forge: up to 24 hours. Forge: instant/priority.

Q: Can I get a refund?
A: Yes, within 14 days of purchase if premium features weren't materially used (EU consumer protection law). Contact: contact@discordforge.org

Q: How do vote webhooks work?
A: Go to Dashboard → Edit your bot → set your webhook URL. DiscordForge sends a POST request every time someone votes for your bot so you can reward them.

Q: Why is the catalog smaller than top.gg?
A: Every listing requires manual human review. We grow as more quality projects are submitted and pass review. Smaller but more trustworthy.

Q: Is logging in with Discord safe?
A: Yes. DiscordForge uses standard Discord OAuth2. We only request your basic public profile (username, ID, avatar). Your password never touches our servers.

Q: How do I cancel my subscription?
A: Dashboard → Billing → Cancel. Your perks stay until the end of the current billing period, then you switch back to free.

Q: What categories are available?
A: Bots: Moderation, Music, Economy, Fun, Tools, AI, Social, Leveling, Roleplay, Anime, Memes, Games, Dashboard
Servers: Gaming, Community, Education, Tech, Creative, Music, Anime, Roleplay, Memes, Esports, Language, Support
Templates: Community, Gaming, Education, Business, Creative, Roleplay, Support, Event, Minimalist, Aesthetic

## Links
- Homepage: https://discordforge.org
- Catalog: https://discordforge.org/catalog
- Submit: https://discordforge.org/add
- Blog: https://discordforge.org/blog
- Premium: https://discordforge.org/premium
- Verification guide: https://discordforge.org/support/verification
- Developer docs: https://discordforge.org/support/developers
- Server owner guide: https://discordforge.org/support/servers
- Privacy policy: https://discordforge.org/privacy
- Terms of Service: https://discordforge.org/rules
- Discord community: https://discord.gg/dfo
- Contact: contact@discordforge.org