> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zbdpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Rewards from Server

> Use your API key to send rewards securely from your backend using the Earn API (v2).

This method ensures all rewards are issued from a trusted environment, preventing client-side abuse and maintaining full control over reward distribution.

<Warning>
  Reward Unit Configuration. The reward unit (e.g., 1 satoshi or \$0.10) is defined for your game by your ZBD Customer Success Manager.
</Warning>

## Configuration

### Header Parameters

<ParamField required header="x-api-key" type="string">
  API key used for authentication. Obtain this from the **Create an API Key** step.
</ParamField>

### Body Parameters

<ParamField required body="rewardsUserId" type="string">
  The recipient's ZBD Rewards User ID
</ParamField>

<ParamField required body="amount" type="number">
  Reward amount in configured units

  Example: `10` (units defined by your ZBD Customer Success Manager)
</ParamField>

<ResponseExample>
  ```json 201 - Success theme={null}
  {
    "success": true,
    "message": "Success.",
    "data": [
      {
        "transactionId": "f7553b31-5ae2-43bf-a200-c0a966e94071"
      }
    ]
  }
  ```
</ResponseExample>

### Response Status Codes

| Code | Description |
| - | - |
| `201` | Reward sent successfully |
| `400` | Bad request – invalid parameters |
| `401` | Unauthorized – invalid or missing API key |
| `404` | Rewards user not found |
| `500` | Internal server error |

<ResponseExample>
  ```json 400 - Bad Request theme={null}
  {
    "success": false,
    "message": "Invalid parameters"
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "success": false,
    "message": "Invalid or missing API key"
  }
  ```

  ```json 404 - User Not Found theme={null}
  {
    "success": false,
    "message": "Rewards user not found"
  }
  ```

  ```json 500 - Server Error theme={null}
  {
    "success": false,
    "message": "Internal server error"
  }
  ```
</ResponseExample>

## Response Fields

| Field | Type | Description |
| - | - | - |
| `success` | boolean | Whether the request was successful |
| `message` | string | Response message |
| `data` | array | Array containing transaction details |
| `transactionId` | string | Unique transaction identifier |

***

<Note>
  Security Reminder, Never expose your API key in client-side code. Always send rewards from your backend server where your API key is securely stored.
</Note>

## Code Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  const apiKey = process.env.REWARDS_API_KEY;

  async function sendReward(rewardsUserId, amount) {
    const response = await fetch('https://api.zbdpay.com/api/v2/rewards/limited-achievement/reward', {
      method: 'POST',
      headers: {
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        rewardsUserId,
        amount
      })
    });

    const data = await response.json();

    if (data.success) {
      console.log(`Reward sent! Transaction ID: ${data.data[0].transactionId}`);
      return data.data[0];
    } else {
      throw new Error(`Failed to send reward: ${data.message}`);
    }
  }

  // Example: Send 10 reward units
  await sendReward('f2154d1a-67e6-46f2-b293-b4b226948dc9', 10);
  ```

  ```bash cURL theme={null}
  curl --location 'https://api.zbdpay.com/api/v2/rewards/limited-achievement/reward' \
  --header 'x-api-key: <x-api-key>' \
  --data '{
    "rewardsUserId": "f2154d1a-67e6-46f2-b293-b4b226948dc9",
    "amount": 10
  }'
  ```

  ```python Python theme={null}
  import requests
  import os

  api_key = os.getenv('REWARDS_API_KEY')

  def send_reward(rewards_user_id, amount):
      """Send a reward to a user from your server"""

      url = "https://api.zbdpay.com/api/v2/rewards/limited-achievement/reward"
      headers = {
          "x-api-key": api_key
      }
      payload = {
          "rewardsUserId": rewards_user_id,
          "amount": amount
      }

      response = requests.post(url, json=payload, headers=headers)
      data = response.json()

      if data["success"]:
          print(f"Reward sent! TX ID: {data['data'][0]['transactionId']}")
          return data["data"][0]
      else:
          raise Exception(f"Failed: {data['message']}")

  # Example usage
  send_reward("f2154d1a-67e6-46f2-b293-b4b226948dc9", 10)
  ```
</CodeGroup>

## Try It Out

Ready to send your first reward from the server? Use our API playground on the right to test with your API key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.