MudVault Voting Rewards System

Complete API documentation for integrating voting rewards into your MUD. Let players earn in-game rewards for supporting your game!

API v1.0

Production Ready

REST API

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

Step 1

Initial Setup (One-time)

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

Step 2

Player Character Linking

Player visits mudvault.org/profile and 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)

Step 3

Voting Creates Reward

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

Step 4

MUD Polls for Rewards

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

Step 5

Reward 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

Step 6

Reward Confirmation

MudVault receives claim POST
Marks reward as delivered
Removes from pending queue
Won't appear in future polling

API Endpoints

POST

Character Verification

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 code

GET

Check Pending Rewards

GET 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

Claim Reward as Delivered

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 success

Optional: 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",
  "vote_id": "ed2718b6-30f0-4b26-9324-19013112f0c6",
  "character_name": "Despair",
  "reward_token": "de713c9befb04144910a541ed43a8dda",
  "voted_at": "2025-10-02T09:55:53.813636+00:00",
  "mud_id": 123,
  "mud_name": "Your MUD Name"
}

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

Check Your Stats

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!)

Debug a Reward

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.

Character Management

GET

List Registered Characters

GET https://mudvault.org/api/rewards/characters/unlink

Headers:
  X-API-Key: mv_<mud_id>_<your_api_key>

Query params (optional):
  ?verified_only=true

Response:
{
  "mud_id": 123,
  "characters": [
    {
      "id": "uuid-here",
      "character_name": "Despair",
      "verified": true,
      "created_at": "2025-10-02T09:55:53.813636+00:00",
      "updated_at": "2025-10-02T09:55:53.813636+00:00"
    }
  ],
  "count": 1,
  "timestamp": "2025-10-02T10:54:56.656Z"
}

Lists all characters registered for your MUD. Use verified_only=true to only show verified characters.

DELETE

Unlink Character

DELETE https://mudvault.org/api/rewards/characters/unlink?character_name=Despair

Headers:
  X-API-Key: mv_<mud_id>_<your_api_key>

Response:
{
  "success": true,
  "message": "Character unlinked successfully",
  "character_name": "Despair",
  "was_verified": true
}

When to use this:

When a player deletes their character in your MUD
Frees up the character name so another player can register it
Prevents "name already registered" errors when names are reused
You can only unlink characters from YOUR MUD (API key enforced)

Data Formats

reward_token

Always exactly 32 hexadecimal characters (UUID without dashes)

de713c9befb04144910a541ed36a9dda

Safe to store as binary (16 bytes) if you want to save database space. Generated using UUID v4, guaranteed unique.

vote_id / reward_id

Standard UUID format with dashes (36 characters)

2df28ed3-c14e-407e-b6e5-da37514eb619

Error Handling

401

Unauthorized - Invalid or missing API key

404

Not Found - Invalid reward_id when claiming

400

Bad Request - Invalid or expired verification code

200

OK - Reward already claimed (returns success with message)

500

Server Error - MudVault service issue

Rate Limits

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.

Security Features

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)

MudVault Voting Rewards System

Complete API documentation for integrating voting rewards into your MUD. Let players earn in-game rewards for supporting your game!

API v1.0

Production Ready

REST API

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

Step 1

Initial Setup (One-time)

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

Step 2

Player Character Linking

Player visits mudvault.org/profile and 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)

Step 3

Voting Creates Reward

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

Step 4

MUD Polls for Rewards

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

Step 5

Reward 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

Step 6

Reward Confirmation

MudVault receives claim POST
Marks reward as delivered
Removes from pending queue
Won't appear in future polling

API Endpoints

POST

Character Verification

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 code

GET

Check Pending Rewards

GET 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

Claim Reward as Delivered

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 success

Optional: 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",
  "vote_id": "ed2718b6-30f0-4b26-9324-19013112f0c6",
  "character_name": "Despair",
  "reward_token": "de713c9befb04144910a541ed43a8dda",
  "voted_at": "2025-10-02T09:55:53.813636+00:00",
  "mud_id": 123,
  "mud_name": "Your MUD Name"
}

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

Check Your Stats

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!)

Debug a Reward

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.

Character Management

GET

List Registered Characters

GET https://mudvault.org/api/rewards/characters/unlink

Headers:
  X-API-Key: mv_<mud_id>_<your_api_key>

Query params (optional):
  ?verified_only=true

Response:
{
  "mud_id": 123,
  "characters": [
    {
      "id": "uuid-here",
      "character_name": "Despair",
      "verified": true,
      "created_at": "2025-10-02T09:55:53.813636+00:00",
      "updated_at": "2025-10-02T09:55:53.813636+00:00"
    }
  ],
  "count": 1,
  "timestamp": "2025-10-02T10:54:56.656Z"
}

Lists all characters registered for your MUD. Use verified_only=true to only show verified characters.

DELETE

Unlink Character

DELETE https://mudvault.org/api/rewards/characters/unlink?character_name=Despair

Headers:
  X-API-Key: mv_<mud_id>_<your_api_key>

Response:
{
  "success": true,
  "message": "Character unlinked successfully",
  "character_name": "Despair",
  "was_verified": true
}

When to use this:

When a player deletes their character in your MUD
Frees up the character name so another player can register it
Prevents "name already registered" errors when names are reused
You can only unlink characters from YOUR MUD (API key enforced)

Data Formats

reward_token

Always exactly 32 hexadecimal characters (UUID without dashes)

de713c9befb04144910a541ed36a9dda

Safe to store as binary (16 bytes) if you want to save database space. Generated using UUID v4, guaranteed unique.

vote_id / reward_id

Standard UUID format with dashes (36 characters)

2df28ed3-c14e-407e-b6e5-da37514eb619

Error Handling

401

Unauthorized - Invalid or missing API key

404

Not Found - Invalid reward_id when claiming

400

Bad Request - Invalid or expired verification code

200

OK - Reward already claimed (returns success with message)

500

Server Error - MudVault service issue

Rate Limits

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.

Security Features

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)

Rewards Documentation

MudVault Voting Rewards System

Complete System Flow

API Endpoints

Optional: Webhook Integration (Instant Delivery)

How it works:

Webhook

Polling

Additional Endpoints

Character Management

Data Formats

reward_token

vote_id / reward_id

Error Handling

Pro Tips from Production

Example Full Cycle

Rewards Documentation

MudVault Voting Rewards System

Complete System Flow

API Endpoints

Optional: Webhook Integration (Instant Delivery)

How it works:

Webhook

Polling

Additional Endpoints

Character Management

Data Formats

reward_token

vote_id / reward_id

Error Handling

Pro Tips from Production

Example Full Cycle