> ## 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).

Send rewards securely from your backend using the **ZBD 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: sdk_live_c21cfd2f98762456cac1729925be494d431c7c08127953c2434f39899c073aa6' \
  --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.