Welcome to Trophy

Trophy is the gamification layer for consumer apps. Build points, achievements, streaks, and leaderboards in minutes with Trophy’s pre-built APIs and SDKs.

Getting started

Install a Trophy SDK to track user activity and power points, achievements, streaks, and leaderboards in your app.

npm install @trophyso/node

gem install trophy_api_client

pip install trophy

composer require trophyso/php

implementation 'so.trophy:trophy-java:1.0.0'

<dependency>
  <groupId>so.trophy</groupId>
  <artifactId>trophy-java</artifactId>
  <version>1.0.0</version>
</dependency>

go get github.com/trophy-so/trophy-go

// .NET Core CLI
dotnet add package Trophy

// Nuget Package Manager
nuget install Trophy

// Visual Studio
Install-Package Trophy

Quick Start

Set up a Trophy account and build your first feature in five minutes.

Use the REST API

Learn how to use the REST API to integrate Trophy into your application.

View a complete example

Full example application with a full gamification stack using Trophy.

Using AI agents

Connect Trophy’s MCP servers so agents can read live docs and configure your account while integrating.

Using Trophy’s MCP servers is recommended for a faster set up and development experience.

Docs MCP

Live documentation search for AI agents.

Account MCP

Configure your Trophy account using AI agents.

Best practice

Recommended setup for using both MCP servers together.

Send your first event

All gamification features are powered by metric events. Here’s how to send your first event using a Trophy SDK:

curl -X POST https://api.trophy.so/v1/metrics/flashcards-flipped/event \
     -H "X-API-KEY: $TROPHY_API_KEY" \
     -H "Idempotency-Key: flashcard-view-42" \
     -H "Content-Type: application/json" \
     -d '{
  "user": {
    "id": "18",
    "email": "user@example.com",
    "tz": "Europe/London"
  },
  "value": 1
}'

import { TrophyApiClient } from "@trophyso/node";
import type { EventResponse } from "@trophyso/node/api";

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

// user.id is required. email and tz are optional but recommended
// (tz is required for correct streak calendar days).
const response: EventResponse = await trophy.metrics.event(
  "flashcards-flipped",
  {
    user: {
      id: "18",
      email: "user@example.com",
      tz: "Europe/London",
    },
    value: 1,
    // Protects against duplicate events from the same flashcard
    idempotencyKey: "flashcard-view-42",
  }
);

from trophy import Trophy
from trophy.types import EventRequestUser

client = Trophy(
    api_key=os.environ.get("TROPHY_API_KEY"),
)

# user.id is required. email and tz are optional but recommended
# (tz is required for correct streak calendar days).
response = client.metrics.event(
    key="flashcards-flipped",
    user=EventRequestUser(
        id="18",
        email="user@example.com",
        tz="Europe/London",
    ),
    value=1.0,
    idempotencyKey="flashcard-view-42", # Protects against duplicate events from the same flashcard
)

use Trophy\TrophyClient;
use Trophy\Types\EventRequestUser;
use Trophy\Types\MetricsEventRequest;

$trophy = new TrophyClient([
    'apiKey' => getenv('TROPHY_API_KEY')
]);

// user.id is required. email and tz are optional but recommended
// (tz is required for correct streak calendar days).
$user = new EventRequestUser([
    'id' => '18',
    'email' => 'user@example.com',
    'tz' => 'Europe/London',
]);

$request = new MetricsEventRequest([
    'user' => $user,
    'value' => 1,
    // Protects against duplicate events from the same flashcard
    'idempotencyKey' => 'flashcard-view-42',
]);

$response = $trophy->metrics->event("flashcards-flipped", $request);

TrophyApiClient client = TrophyApiClient.builder()
    .apiKey(System.getenv("TROPHY_API_KEY"))
    .build();

// user.id is required. email and tz are optional but recommended
// (tz is required for correct streak calendar days).
MetricsEventRequest request = MetricsEventRequest.builder()
      .user(
        EventRequestUser.builder()
          .id("18")
          .email("user@example.com")
          .tz("Europe/London")
          .build()
      )
      .value(1)
      // Protects against duplicate events from the same flashcard
      .idempotencyKey("flashcard-view-42")
      .build();

EventResponse response = client.metrics().event("flashcards-flipped", request);

client, err := trophy.NewClient(
    option.WithAPIKey(os.Getenv("TROPHY_API_KEY")),
)
if err != nil {
    log.Fatal(err)
}

// user.id is required. email and tz are optional but recommended
// (tz is required for correct streak calendar days).
response, err := client.Metrics.Event(
    "flashcards-flipped",
    &api.MetricsEventRequest{
        User: &api.EventRequestUser{
            Id: "18",
            Email: "user@example.com",
            Tz: "Europe/London",
        },
        Value: 1,
        // Protects against duplicate events from the same flashcard
        IdempotencyKey: "flashcard-view-42",
    },
)

var trophy = new TrophyClient(
    Environment.GetEnvironmentVariable("TROPHY_API_KEY")
);

// user.id is required. email and tz are optional but recommended
// (tz is required for correct streak calendar days).
var user = new EventRequestUser {
   Id = "18",
   Email = "user@example.com",
   Tz = "Europe/London"
};

var request = new MetricsEventRequest {
   User = user,
   Value = 1,
   // Protects against duplicate events from the same flashcard
   IdempotencyKey = "flashcard-view-42"
};

var response = await trophy.Metrics.EventAsync("flashcards-flipped", request);

client = TrophyApiClient::Client.new(
  :api_key => ENV["TROPHY_API_KEY"]
)

# user.id is required. email and tz are optional but recommended
# (tz is required for correct streak calendar days).
result = client.metrics.event(
  :key => 'flashcards-flipped',
  :user => {
    :id => '18',
    :email => 'user@example.com',
    :tz => 'Europe/London'
  },
  :value => 1,
  :idempotencyKey => 'flashcard-view-42' # Protects against duplicate events from the same flashcard
)

The response includes changes to gamification state as a result of the event including:

The user’s new total value for the metric
Any newly unlocked achievements
New points totals and rewards
An updated streak object
Any new leaderboard positions

Use this response to react to changes in the user’s gamification state and power UI elements.

Response

{
  "metricId": "d01dcbcb-d51e-4c12-b054-dc811dcdc623",
  "eventId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
  "total": 750,
  "achievements": [
    {
      "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
      "trigger": "metric",
      "metricId": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
      "metricName": "Flashcards Flipped",
      "metricValue": 500,
      "name": "500 Flashcards Flipped",
      "description": "Flip 500 flashcards in the app.",
      "badgeUrl": null,
      "userAttributes": [],
      "achievedAt": "2020-01-01T00:00:00Z"
    }
  ],
  "currentStreak": {
    "length": 1,
    "frequency": "daily",
    "started": "2025-04-02",
    "periodStart": "2025-03-31",
    "periodEnd": "2025-04-05",
    "expires": "2025-04-12",
    "extended": true
  },
  "points": {
    "xp": {
      "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
      "key": "xp",
      "name": "XP",
      "description": null,
      "badgeUrl": null,
      "maxPoints": null,
      "total": 10,
      "level": {
        "id": "1140fe51-6bce-4b44-b0ad-bddc4e123534",
        "key": "bronze",
        "name": "Bronze",
        "description": "Starting level",
        "badgeUrl": null,
        "points": 0
      },
      "added": 10,
      "awards": [
        {
          "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
          "awarded": 10,
          "date": "2021-01-01T00:00:00Z",
          "total": 10,
          "trigger": {
            "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
            "type": "metric",
            "metricName": "Flashcards Flipped",
            "metricThreshold": 100,
            "points": 10,
            "status": "active",
            "userAttributes": [],
            "created": "2021-01-01T00:00:00Z",
            "updated": "2021-01-01T00:00:00Z"
          }
        }
      ]
    }
  },
  "leaderboards": {
    "daily_champions": {
      "id": "0040fe51-6bce-4b44-b0ad-bddc4e123535",
      "key": "daily_champions",
      "name": "Daily Champions",
      "description": null,
      "status": "active",
      "rankBy": "metric",
      "runUnit": "day",
      "runInterval": 1,
      "maxParticipants": 100,
      "breakdownAttributes": [],
      "metricName": "Flashcards Flipped",
      "metricKey": "flashcards-flipped",
      "threshold": 10,
      "start": "2025-01-01",
      "end": null,
      "startTime": null,
      "endTime": null,
      "previousRank": 50,
      "rank": 12
    }
  },
  "idempotencyKey": "flashcard-view-42",
  "idempotentReplayed": false
}

Build by use case

For more information on how to build common gamification features using Trophy, see the following guides:

Achievements

Unlock achievements from progress or one-time actions.

Streaks

Drive daily or weekly habit loops with timezone-awareness built-in.

Points

Award points from in-app actions and set up levels and boosts.

Leaderboards

Create recurring or one-off leaderboards.

Emails

Lifecycle emails driven by streaks, achievements, and activity.

Push notifications

Automated notification flows using gamification data.

UI Kit

Ship gamification UI faster with Trophy’s React component library, built on shadcn/ui and designed to work with Trophy data shapes.

UI Kit

Explore pre-built UI components for streaks, achievements, leaderboards, points and more.

Production checklist

Before you deploy your integration to production, review the recommended steps in the production checklist:

Production checklist

Recommended steps to ensure your integration is production-ready.

Pricing

Trophy meters usage by monthly active users (MAUs). An MAU is a user who sends at least one metric event in a given calendar month. You are not charged for churned users who stop sending events. The free tier includes 1,000 MAUs. Paid plans start at $25/month with overages.

Billing

Free tier, paid plans, allowances, and overages.

Pricing estimator

Get an estimate of monthly costs based on expected usage.

Get Support

Want to get in touch with the Trophy team? Reach out to us via email. We’re here to help!

Getting Started

Features

Platform

Account

Getting started

Quick Start

Use the REST API

View a complete example

Using AI agents

Docs MCP

Account MCP

Best practice

Send your first event

Build by use case

Achievements

Streaks

Points

Leaderboards

Emails

Push notifications

UI Kit

UI Kit

Production checklist

Production checklist

Pricing

Billing

Pricing estimator

Get Support

​Getting started

Quick Start

Use the REST API

View a complete example

​Using AI agents

Docs MCP

Account MCP

Best practice

​Send your first event

​Build by use case

Achievements

Streaks

Points

Leaderboards

Emails

Push notifications

​UI Kit

UI Kit

​Production checklist

Production checklist

​Pricing

Billing

Pricing estimator

​Get Support

Getting started

Using AI agents

Send your first event

Build by use case

UI Kit

Production checklist

Pricing

Get Support