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

# Triggers

> POST /api/trigger — Credit points to a wallet by firing a named trigger.

Triggers let your application credit points to a wallet when a specific event occurs — a user crafts an item, completes a quest, makes a purchase, or any custom event you define.

Triggers are configured in your dashboard under **Triggers**. Each trigger has a unique key, a name, and a fixed points amount.

***

## POST /api/trigger

### Request

```bash theme={null}
POST https://api.rewards.so/trigger
Authorization: Bearer rw_your_api_key
Content-Type: application/json
```

```json theme={null}
{
  "triggerKey": "craft_artifact",
  "walletAddress": "0xabc123...",
  "pointSystemId": "your-point-system-uuid"
}
```

| Field           | Type     | Required | Description                                        |
| --------------- | -------- | -------- | -------------------------------------------------- |
| `triggerKey`    | `string` | Yes      | The trigger key defined in your Triggers dashboard |
| `walletAddress` | `string` | Yes      | The wallet address to credit points to             |
| `pointSystemId` | `string` | Yes      | UUID of the target point system                    |

### Response `200`

```json theme={null}
{
  "success": true,
  "pointsAdded": 10,
  "triggerKey": "craft_artifact",
  "walletAddress": "0xabc123..."
}
```

### Errors

| Status | Message                                                             | Fix                                                       |
| ------ | ------------------------------------------------------------------- | --------------------------------------------------------- |
| `400`  | `Missing required fields: triggerKey, walletAddress, pointSystemId` | Include all three fields in the body                      |
| `401`  | `Missing API key`                                                   | Provide an `Authorization: Bearer rw_xxx` header          |
| `401`  | `Invalid API key format`                                            | Key must start with `rw_`                                 |
| `401`  | `Invalid API key`                                                   | Key not found — check your dashboard                      |
| `403`  | `This API key does not have trigger permissions`                    | Use a key with `trigger` or `all` permissions             |
| `403`  | `This API key does not have access to the specified point system`   | Ensure the key is scoped to the target point system       |
| `403`  | `Trigger is inactive`                                               | Enable the trigger in the Triggers dashboard              |
| `403`  | `Wallet is blacklisted`                                             | Wallet has been blacklisted in this point system          |
| `404`  | `Trigger not found`                                                 | Check the `triggerKey` matches exactly what's in Triggers |
| `429`  | `Rate limit exceeded`                                               | Max 10 calls/min per key + wallet + trigger combination   |

***

## Rate limiting

Each unique combination of `(api_key, walletAddress, triggerKey)` is limited to **10 calls per minute**. This prevents infinite loops from misconfigured event handlers.

When rate limited, the response includes a `Retry-After` header (in seconds).

```
HTTP/1.1 429 Too Many Requests
Retry-After: 42
```

***

## Wallet auto-creation

If the `walletAddress` doesn't exist yet in the point system, it is automatically created before the points are credited. You don't need to register wallets in advance.

***

## Code examples

<CodeGroup>
  ```js JavaScript theme={null}
  await fetch("https://api.rewards.so/trigger", {
    method: "POST",
    headers: {
      "Authorization": "Bearer rw_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      triggerKey: "craft_artifact",
      walletAddress: "0xabc123...",
      pointSystemId: "your-point-system-uuid",
    }),
  });
  ```

  ```ts TypeScript theme={null}
  type TriggerResponse = {
    success: boolean;
    pointsAdded: number;
    triggerKey: string;
    walletAddress: string;
  };

  async function fireRewardTrigger(
    triggerKey: string,
    walletAddress: string,
    pointSystemId: string
  ): Promise<TriggerResponse> {
    const res = await fetch("https://api.rewards.so/trigger", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.REWARDS_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ triggerKey, walletAddress, pointSystemId }),
    });

    if (!res.ok) {
      const error = await res.json();
      throw new Error(error.message ?? `HTTP ${res.status}`);
    }

    return res.json();
  }
  ```

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

  response = requests.post(
      "https://api.rewards.so/trigger",
      headers={
          "Authorization": "Bearer rw_your_api_key",
          "Content-Type": "application/json",
      },
      json={
          "triggerKey": "craft_artifact",
          "walletAddress": "0xabc123...",
          "pointSystemId": "your-point-system-uuid",
      },
  )

  data = response.json()
  print(f"Points added: {data['pointsAdded']}")
  ```
</CodeGroup>

***

## Setting up a trigger

1. Dashboard → **Triggers** → **New trigger**
2. Set an **Event name** (display only) and a **Trigger key** (used in API calls)
3. Set the **Points** amount awarded per call
4. The trigger is active by default — use the toggle to pause it without deleting it