Distribute Reward

Distribute rewards to one or many members. The primary write endpoint for the rewards layer. Supports single and batch payloads, with automatic HeartBeat (HRTB) status multiplier application for protocol-multiplied reward types. All amounts shown in USD; internally calculated in MNEE (electronic cash).

Endpoint

POST /mnee/reward/distribute

Request

Headers

Body

Send either a single recipient or a batch. Batch payloads can include up to 100 recipients per request.

{
  "recipients": [
    {
      "badgeId": "hb_00001",
      "amount": 500,
      "type": "event_bonus",
      "metadata": {
        "eventId": "evento_001",
        "eventName": "Main Stage Showcase",
        "reason": "Scanned 5 times"
      },
      "restrictions": {
        "releaseAfter": "2024-12-31T23:59:59Z",
        "releaseCondition": "quest_completed"
      }
    }
  ],
  "batchId": "batch_2024_12_01_001",
  "priority": "normal"
}

Fields

Response

Success (200)

{
  "transactionId": "tx_8f4a9b2e",
  "batchId": "batch_2024_12_01_001",
  "totalRecipients": 1,
  "totalAmount": 500,
  "totalAfterMultiplier": 625,
  "processedCount": 1,
  "failedCount": 0,
  "status": "accepted",
  "statusDetails": [
    {
      "badgeId": "hb_00001",
      "amount": 500,
      "multiplier": 1.25,
      "finalAmount": 625,
      "status": "queued",
      "message": "Reward queued for settlement. HRTB multiplier 1.25x applied."
    }
  ],
  "settlesIn": "~5 blocks",
  "settlesAt": "2024-12-01T18:45:30Z"
}

Partial Failure (207)

Some recipients succeeded, some failed. Check statusDetails for per-recipient status.

{
  "transactionId": "tx_8f4a9b2e",
  "batchId": "batch_2024_12_01_001",
  "totalRecipients": 2,
  "processedCount": 1,
  "failedCount": 1,
  "status": "partial",
  "statusDetails": [
    {
      "badgeId": "hb_00001",
      "status": "queued",
      "amount": 500,
      "finalAmount": 625,
      "message": "Reward queued."
    },
    {
      "badgeId": "hb_99999",
      "status": "failed",
      "amount": 300,
      "error": "badge_not_found",
      "message": "Badge hb_99999 does not exist or is inactive."
    }
  ]
}

Error (400, 401, 429, 500)

{
  "error": "invalid_reward_type",
  "message": "Reward type 'invalid_type' is not recognized.",
  "requestId": "req_xyz123"
}

Multiplier Application

The HeartBeat (HRTB) status multiplier is automatically fetched and applied at delivery time for protocol-multiplied reward types. The final amount is calculated as:

finalAmount = baseAmount × statusMultiplier

Multiplied reward types: event_bonus, quest_step, challenge_reward, referral

Non-multiplied reward types: p2p, gift_redemption (always at face value). All amounts in USD.

Restrictions & Unlocks

Use restrictions to lock rewards until a time or condition is met. Common use cases:

• Time-based lock: Rewards from a past event become withdrawable on a future date.
• Condition-based lock: Quest rewards unlock only after the quest is completed.

Members see locked funds in their balance but cannot spend them until the restriction clears.

Idempotency & Retries

Provide an Idempotency-Key header (UUID format) to ensure that duplicate requests don't create duplicate rewards. If you retry with the same key within 24 hours, the API returns the original response without re-processing.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Batch Processing

Batches are atomic up to the point of failure. If 90 of 100 recipients succeed and 10 fail, you receive a 207 response with per-recipient details. Retry failed recipients individually or in a new batch.

The Idempotency-Key applies to the entire batch. If you retry the same batch with the same key, all recipients are skipped.

Webhooks

When a reward settles, a webhook event fires:

{
  "event": "reward.settled",
  "transactionId": "tx_8f4a9b2e",
  "badgeId": "hb_00001",
  "amount": 625,
  "type": "event_bonus",
  "settledAt": "2024-12-01T18:45:30Z"
}

Subscribe to reward.settled, reward.failed, and reward.queued in your program dashboard. See MNEE Webhook Events.

Rate Limits

Standard rate limits apply. See Rate Limits.

Examples

Single Reward

curl -X POST https://api.heartbadge.io/mnee/reward/distribute \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      {
        "badgeId": "hb_00001",
        "amount": 1000,
        "type": "event_bonus",
        "metadata": {
          "eventId": "evt_42",
          "reason": "Attended VIP lounge"
        }
      }
    ]
  }'

Batch with Restrictions

curl -X POST https://api.heartbadge.io/mnee/reward/distribute \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "recipients": [
      {
        "badgeId": "hb_00001",
        "amount": 500,
        "type": "quest_step",
        "restrictions": {
          "releaseAfter": "2024-12-15T00:00:00Z"
        }
      },
      {
        "badgeId": "hb_00002",
        "amount": 500,
        "type": "quest_step",
        "restrictions": {
          "releaseCondition": "quest_completed"
        }
      }
    ],
    "batchId": "batch_2024_12_quest_001"
  }'

See Also

• Member Status — fetch current balance and status multiplier
• Balance Query — query past transactions and restrictions
• MNEE Rewards Pipeline — how rewards flow through the system