Triggers

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

POST https://api.rewards.so/trigger
Authorization: Bearer rw_your_api_key
Content-Type: application/json

{
  "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
`idempotencyKey`	`string`	No	Up to 128 characters, unique per event (a transaction hash, an order id). A second call with the same key credits nothing and returns `409`

Response `200`

{
  "success": true,
  "pointsAdded": 10,
  "triggerKey": "craft_artifact",
  "walletAddress": "0xabc123..."
}

Errors

Status	Message	Fix
`409`	`This idempotencyKey was already processed`	This event was already credited: nothing to do
`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

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",
  }),
});

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();
}

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']}")

Setting up a trigger

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

Overview

Endpoints

POST /api/trigger

Request

Response `200`

Errors

Rate limiting

Wallet auto-creation

Code examples

Setting up a trigger

​POST /api/trigger

​Request

​Response 200

​Errors

​Rate limiting

​Wallet auto-creation

​Code examples

​Setting up a trigger

POST /api/trigger

Request

Response `200`

Errors

Rate limiting

Wallet auto-creation

Code examples

Setting up a trigger