---
title: Points API
canonical_url: "https://trophy.so/developers/points"
description: "Points API: award points automatically, configure levels and boosts from the dashboard. SDKs for Node.js, Python, Go, Java, PHP, Ruby, and .NET."
---

# The API for XP, coins and loyalty points

Add points to your app in under an hour. Trophy handles awarding points automatically based on user actions, promoting users between levels, and applying boost multiplers during limited-time events, all with a fully traceable points ledger and cheat prevention safeguards. Start for free, scale to millions of users.

[Full feature documentation](https://docs.trophy.so/features/points.md)

## Quickstart: award and read XP

Configure a points system and metric triggers in the Trophy dashboard (or via MCP), then award points by sending metric events. Fetch the user’s balance, awards, and level for your UI.

```ts
import { TrophyApiClient } from "@trophyso/node";

const trophy = new TrophyApiClient({ apiKey: process.env.TROPHY_API_KEY });

// 1. Award XP by tracking the metric that powers your points trigger
const eventResponse = await trophy.metrics.event("workouts", {
  user: { id: "user-123" },
  value: 1,
});

console.log("Points awarded:", eventResponse.points);

// 2. Read the user's balance, recent awards, level, and maxPoints cap
const points = await trophy.users.points("user-123", "xp");

console.log("Total:", points.total);
console.log("Max points:", points.maxPoints);
console.log("Recent awards:", points.awards);
```

## Why use Trophy's points API?

Building a reliable points system API requires ledger-grade consistency. Every award, multiplier, and deduction must be atomic — and getting that right in-house is harder than it looks.

| Consideration | Trophy | Build in-house | Why it matters |
| --- | --- | --- | --- |
| Integration Time | Points accrue automatically from metric events with a full ledger history and anti-cheating safeguards. Configure multipliers and level thresholds in the dashboard in minutes. | Build custom points ledger, transaction history, multiplier system and level progression. Expect 3-5 weeks, or longer for anti-cheating safeguards. | Point systems require transactional consistency — every award, deduction, and multiplier must be atomic. Building this correctly requries exhaustive testing and validation that most teams underestimate. |
| Reliability | Atomic point transactions with full audit trail. No double-counting, no lost points. | You must ensure points are never double-awarded or silently dropped, even under concurrent events, retries, and partial failures. | Points are a form of virtual currency. Users notice when their balance is wrong, and debugging ledger inconsistencies after the fact is painful if your domain model hasn't been designed to support this. |
| Scalability | Trophy handles millions of high-frequency points calculations every day across hundreds of thousands of users in real time. | Real-time point aggregation across multiple event sources becomes a hot-path database problem as your user base grows. | Point balance queries are among the most frequent operations in a gamification system. Caching helps until cache invalidation introduces its own consistency bugs. |
| Ongoing Maintenance | Non-techincal users can adjust multipliers, add point sources, and modify level thresholds from the dashboard. | Changing point values, adding new multiplier rules, or adjusting level thresholds requires code changes and careful data migration work that cause bottlenecks between product and engineering. | Product teams will want to tune point economies frequently. Making every adjustment a code change creates friction between product and engineering. |
| Feature Development | Level progression, boost mechanics, multiple point currencies, and detailed history ship regularly. | Each new feature — multipliers, boosts, level-up rewards, seasonal points — adds complexity to your ledger and aggregation logic. | Point economies evolve as you learn what motivates users. You'll want to experiment with multipliers, decay, and bonus events without re-engineering your ledger. |

## Points endpoints

Use Trophy's points API to award and track XP, loyalty points, or any custom currency. Points accrue automatically from metric events with full ledger history and anti-cheating safeguards.

### `POST /metrics/{key}/event`

Send a metric event to track user activity and award points.

Docs: https://docs.trophy.so/api-reference/endpoints/metrics/send-a-metric-change-event.md

```ts
// Track a user event
await trophy.metrics.event("lessons", {
    user: {
      id: "user-123"
    },
    value: 1
  }
);

// This single event:
// - Records user activity
// - Awards points
// - Returns new points balance
```

### `GET /users/{id}/points/{key}`

Get a user's points for a specific points system, including recent awards.

Docs: https://docs.trophy.so/api-reference/endpoints/users/get-a-users-points.md

```ts
// Fetch user points balance
const points = await trophy.users
  .points("user-123", "xp");

// Response:
// {
//   key: "xp", 
//   name: "XP",
//   total: 2450,
//   awards: [{ 
//     awarded: 10, 
//     trigger: {...} 
//   }]
// }
```

### `POST /points/boosts`

Create points boosts for multiple users. Boosts multiply points earned during a time period.

Docs: https://docs.trophy.so/admin-api/endpoints/points/create-boosts.md

```ts
// Create a points boost
await trophy.admin.points.boosts.create({
  systemKey: "xp",
  boosts: [{
    userId: "user-123",
    name: "Double XP Weekend",
    start: '2024-01-01',
    end: '2024-01-03',
    multiplier: 2
  }]
});
```

## Code examples

### points-display.tsx

```ts
// Fetch and display points UI

const points = await trophy.users
  .points("user-123", "xp");

// Render XP progress bar
return (
  <XPBar
    total={points.total}
    name={points.name}
    awards={points.awards}
  />
);
```

## FAQ

### How do experience points (XP) and loyalty points work?

Trophy's points API lets you define any type of points system — experience points, coins, loyalty points — and configure which user actions award them and how many. When users trigger those actions through metric events, points are awarded and tracked automatically with a full ledger history.

### Can I build a loyalty rewards program with this API?

Yes. Trophy's loyalty points API supports any reward mechanic — loyalty points for purchases, XP for engagement, coins for referrals. You configure point values per metric, set caps, set up levels for progression tiers, and use boosts for limited-time events like double-points weekends.

### How does Trophy prevent cheating/farming?

Trophy's points API has built in idempotency and deduplication to prevent cheating and farming. Every point award is atomic and only applied once, even if the event is sent multiple times.

### How do I display points and levels in my app?

Use the [get user points](https://docs.trophy.so/api-reference/endpoints/users/get-a-users-points) endpoint to fetch a user's total points, recent awards, current level, and any configured caps. You can then render a progress bar, level badge, or any other UI element in your app with full control.

### Can I have multiple points systems in the same app?

Yes. Trophy's points API supports multiple independent points systems in the same app — "XP" for progression, "coins" for a virtual currency, "loyalty" for a rewards programme. Each system is configured and tracked independently with its own point values, caps, and boost rules.

### Can I display points and levels in React, React Native, or mobile apps?

Yes. Adding points and levels to your app with Trophy uses server-side SDKs (Node.js, Python, Go, Java, PHP, Ruby, and .NET) to handle points logic on your backend. The API returns point totals and award history that you can render in any frontend — React, React Native, Next.js, Swift, Kotlin, Flutter, or any other framework.