MudVault Voting Rewards System
Complete API documentation for integrating voting rewards into your MUD. Let players earn in-game rewards for supporting your game!
Finding Your MUD ID: Hover over your MUD card and click the copy button next to "Play Now". The URL contains your MUD ID.
API Key Format: Your full API key looks like: mv_<mud_id>_<secret> — use the entire string as your API key.
Complete System Flow
- Register your MUD on mudvault.org
- Get your MUD ID when your MUD is created (e.g.,
123) - Enable rewards on your Edit MUD page and copy your API key
- Configure your MUD server with these credentials
- Player visits
mudvault.org/profileand gets a verification code - In-game, player types:
verify ABC123 - Your game sends a POST to the verification endpoint
- MudVault links the character to their account
- Store verification status locally (e.g.,
ch->pcdata->mudvault_verified = TRUE)
- Player votes for your MUD on mudvault.org
- MudVault generates a unique
reward_id - Reward is associated with the player's character name
- Added to the pending rewards queue
- Poll every 5 minutes OR when player runs a command like
checkvotes - Call
GET /rewards/pending/<mud_id> - Receive JSON array of all pending rewards
- Parse each reward object for processing
For each pending reward:
IF character is online:
1. Generate random reward (gold/items/quest points)
2. Give to player immediately
3. POST to /rewards/claim/<reward_id>
4. Log successful delivery
ELSE:
1. Save to local pending file
2. Check again when player logs in
3. Deliver and claim when possible
- MudVault receives claim POST
- Marks reward as delivered
- Removes from pending queue
- Won't appear in future polling
API Endpoints
POST https://mudvault.org/api/rewards/verify/confirm
Headers:
X-API-Key: mv_<mud_id>_<your_api_key>
Content-Type: application/json
Body:
{
"verification_code": "ABC123",
"character_name": "Despair"
}
Response: HTTP 200 on success, 400 on invalid codeGET https://mudvault.org/api/rewards/pending/<mud_id>
Headers:
X-API-Key: mv_<mud_id>_<your_api_key>
Response:
{
"mud_id": 123,
"pending_rewards": [
{
"reward_id": "2df28ed3-c14e-407e-b6e5-da37514eb619",
"vote_id": "ed2718b6-30f0-4b26-9324-19013112f0c6",
"character_name": "Despair",
"reward_token": "de713c9befb04144910a541ed36a9dda",
"voted_at": "2025-10-02T09:55:53.813636+00:00",
"delivery_attempts": 0
}
],
"count": 1,
"timestamp": "2025-10-02T10:54:56.656Z"
}POST https://mudvault.org/api/rewards/claim/<reward_id>
Headers:
X-API-Key: mv_<mud_id>_<your_api_key>
Body: Empty or {}
Response: HTTP 200 on successOptional: Webhook Integration (Instant Delivery)
Instead of polling every 5 minutes, MudVault can notify you instantly when someone votes. Think of it like MudVault calling your MUD directly saying "Hey, Despair just voted!"
How it works:
- Set up an endpoint on your MUD server that can receive HTTP POST requests
Example: https://yourmud.com/mudvault-webhook - Go to your Edit MUD page on MudVault, enter your Webhook URL and save
- When a player votes, MudVault immediately sends you the reward data
POST https://yourmud.com/mudvault-webhook
Headers:
X-MudVault-Signature: sha256=abc123...
Content-Type: application/json
Body:
{
"reward_id": "2df28ed3-c14e-407e-b6e5-da37514eb098",
"character_name": "Despair",
"reward_token": "de713c9befb04144910a541ed43a8dda",
"voted_at": "2025-10-02T09:55:53.813636+00:00"
}Verify the Signature!
- Take the entire request body as a string
- Create an HMAC-SHA256 hash using your webhook_secret as the key
- Convert to hex and add "sha256=" prefix
- Compare with X-MudVault-Signature header
- If they don't match, someone's trying to fake a vote - ignore it!
Webhook
Instant notification, but your server must be up. Best for real-time delivery.
Polling
Check every 5 minutes, always works. Great as a backup or standalone.
Best practice: Use both! Webhook for speed, polling for reliability. If your server is down when someone votes, MudVault will retry 3 times, and you can still get it via polling.
Additional Endpoints
GET https://mudvault.org/api/rewards/stats
Headers:
X-API-Key: mv_<mud_id>_<your_api_key>Returns total rewards created/delivered/pending, last 24 hours activity, and top voters (great for leaderboards!)
GET https://mudvault.org/api/rewards/claim/<reward_id>
Headers:
X-API-Key: mv_<mud_id>_<your_api_key>Returns current status (pending/delivered/claimed/failed), character name, reward token, and timestamps.
Error Handling
100 API calls per minute per MUD
This is plenty for normal use (polling every 5 min = 12 calls/hour). If you hit the limit, wait a minute and retry.
- API Key required for all requests
- MUD-specific endpoints (can only see own rewards)
- One-time claim (each reward_id is unique)
- Character verification links in-game to MudVault
Pro Tips from Production
- 1.Store reward_ids locally to prevent duplicate deliveries
- 2.Log everything - player name, reward given, timestamp
- 3.Give bonus rewards for first-time voters to encourage participation
- 4.Make your verify command case-insensitive (ABC123 = abc123)
- 5.Players can only vote once per 24 hours, but they'll appreciate getting their rewards quickly!
Example Full Cycle
Despair votes at 9:00 AM → MudVault creates reward_id abc-123
MUD polls at 9:05 AM → Gets pending reward for "Despair"
Despair is online → MUD gives 500,000 gold
MUD claims abc-123 → MudVault marks as delivered
Next poll at 9:10 AM → No pending rewards (already claimed)
If you have any questions, comments, concerns, or ideas, please let me know on Discord.
Join Discord— Asmodeus (MudVault Founder)