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

# Quick Start

> Install a Trophy SDK, authenticate, identify a user, and submit your first metric event in about five minutes.

Here you'll integrate your application with Trophy and start building your first gamified feature in about five minutes.

<Tabs>
  <Tab title="Using AI" icon="bot">
    These instructions are for using Trophy with AI assistants that support MCP — for example Claude, ChatGPT, Cursor, or Claude Code.

    <Steps>
      <Step title="Create your Trophy account">
        First, [create a new account](https://app.trophy.so/sign-up?utm_source=docs\&utm_medium=quickstart) if you don't have one already. Complete onboarding to get your account set up.
      </Step>

      <Step title="Connect Trophy MCP servers">
        Connect both Trophy MCP servers in your AI client for the best experience:

        * Docs MCP server URL: `https://docs.trophy.so/mcp` (live documentation context)
        * Account MCP server URL: `https://mcp.trophy.so/mcp` (account actions — OAuth sign-in required)

        Setup guides: [Docs MCP installation](/mcp/docs-mcp-server/installation), [Account MCP installation](/mcp/account-mcp-server/installation).

        <Tip>
          Use the [Docs MCP](/mcp/docs-mcp-server/introduction) as on-demand docs context and the [Account MCP](/mcp/account-mcp-server/introduction) for account changes. Use both for [best practice](/mcp/best-practice).
        </Tip>
      </Step>

      <Step title="Ask your AI to perform initial setup">
        Here's a prompt you can use with your AI assistant to perform initial Trophy setup:

        <Prompt description="Perform initial Trophy setup" icon="paperclip" iconType="solid" actions={["copy", "cursor"]}>
          I'm adding gamification to my app using Trophy.

          Before making changes, verify the connected Trophy MCP Servers are available. Use the Docs MCP server as the primary source of truth for Trophy integration details, and the Account MCP server to configure my account.

          Please do the full initial setup end-to-end:

          1. Detect the backend language/framework in this repo and install the relevant official Trophy SDK (or use HTTP calls if no SDK is available). Report to Trophy support if no SDK is available.
          2. Add `TROPHY_API_KEY` to environment config in a secure way (no secrets committed to git), and wire it into the Trophy SDK client initialization.
          3. Add code to set up metric event tracking for the chosen user activity (ask if not known yet) using the Trophy SDK client, wiring all required user attributes like ID, and using placeholders for all optional attributes like name, email, tz and signUpDate, unless already known or required by the use case.
          4. Add basic error handling and logging around Trophy SDK calls.
          5. Add or update a short README section explaining how the integration works and how to extend it.

          Constraints:

          * Use Docs MCP tool results for all Trophy-specific implementation decisions and integrations.
          * Do not rely on prior memory for Trophy SDK behavior when MCP provides an answer.
          * Keep secrets out of source control.
          * Use existing project patterns and naming conventions.
          * Show a concise summary of changed files and how to test the setup.
          * Suggest next steps based on the gamification features Trophy supports and the use case.
        </Prompt>

        This will:

        1. Add the relevant [Trophy SDK](/api-reference/client-libraries) to your app based on your tech stack
        2. Add a new `TROPHY_API_KEY` variable to your environment settings
        3. Add code to track metric events for the chosen user activity using the Trophy SDK client - required for all gamification features.
      </Step>

      <Step title="Build your first gamification feature">
        Once initial setup is complete, pick a common use case and paste the matching prompt into your AI assistant:

        <Prompt description="Daily streak" icon="paperclip" iconType="solid" actions={["copy", "cursor"]}>
          Build a daily streak feature with Trophy.

          Use the Docs MCP as the source of truth for how streaks work, and the Account MCP to configure my account.

          Goals:

          1. Drive the streak from a core user activity already tracked (or that we should track) as a Trophy metric.
          2. Ensure every user identify/upsert and metric event includes the user's `tz` attribute (IANA timezone). This is required for streaks to evaluate calendar days correctly for each user.
          3. Configure the streak featuer in Trophy using a sensible threshold for the chosen metric.
          4. Enable streak freezes and streak pauses if they fit this product; otherwise omit them and say why.
          5. Wire any app-side reads or UI needed to show the user's current streak, freezes, and pause state.
          6. Summarize what was configured, what code changed, and how to verify the streak end to end. Explicitly explain back why sending `tz` matters for a functioning streak feature.
        </Prompt>

        <Prompt description="Achievements library" icon="paperclip" iconType="solid" actions={["copy", "cursor"]}>
          Build an achievements library with Trophy.

          Use the Docs MCP as the source of truth for achievement types and triggers, and the Account MCP to configure my account.

          Goals:

          1. Create a set of achievements tied to core user actions tracked as Trophy metric events.
          2. Add any one-time API-triggered achievements (and other achievement types) that fit the product.
          3. Wire app-side handling for unlocks and a minimal way to list completed vs incomplete achievements.
          4. Summarize what was configured, what code changed, and how to verify unlocks end to end.
        </Prompt>

        <Prompt description="XP system" icon="paperclip" iconType="solid" actions={["copy", "cursor"]}>
          Build an XP points system with Trophy.

          Use the Docs MCP as the source of truth for points systems, triggers, and levels, and the Account MCP to configure my account.

          Goals:

          1. Create a points system that awards XP for a few key user actions tracked as Trophy metrics.
          2. Configure triggers in the points system to award XP for the chosen user actions.
          3. Configure levels and boosts if relevant for the use case.
          4. Wire app-side reads or UI needed to show the user's XP total and level progress.
          5. Summarize what was configured, what code changed, and how to verify points awards end to end.
        </Prompt>

        <Prompt description="Weekly leaderboard" icon="paperclip" iconType="solid" actions={["copy", "cursor"]}>
          Build a repeating weekly leaderboard with Trophy.

          Use the Docs MCP as the source of truth for leaderboards, and the Account MCP to configure my account.

          Goals:

          1. Create a weekly recurring leaderboard driven by a core user action tracked as a Trophy metric.
          2. Configure ranking logic based on the chosen metric and configure the weekly reset schedule for the leaderboard.
          3. Wire app-side reads or UI needed to show rankings for the current week and the current user's place.
          4. Summarize what was configured, what code changed, and how to verify rankings end to end.
        </Prompt>

        For more ideas on what to build next, explore:

        <CardGroup>
          <Card title="Achievements" icon="trophy" href="/features/achievements">
            Reward users for continued progress or taking specific actions.
          </Card>

          <Card title="Streaks" icon="flame" href="/features/streaks">
            Motivate users to build regular usage habits.
          </Card>

          <Card title="Points" icon="sparkle" href="/features/points">
            Build sophisticated points systems to reward and retain users.
          </Card>

          <Card
            title="Leaderboards"
            icon={
          <svg
            width="20"
            height="18"
            viewBox="0 0 20 18"
            fill="none"
            xmlns="http://www.w3.org/2000/svg"
            className="text-primary dark:text-primary-light"
          >
            <path
              d="M2 16H6V8H2V16ZM8 16H12V2H8V16ZM14 16H18V10H14V16ZM0 16V8C0 7.45 0.195833 6.97917 0.5875 6.5875C0.979167 6.19583 1.45 6 2 6H6V2C6 1.45 6.19583 0.979167 6.5875 0.5875C6.97917 0.195833 7.45 0 8 0H12C12.55 0 13.0208 0.195833 13.4125 0.5875C13.8042 0.979167 14 1.45 14 2V8H18C18.55 8 19.0208 8.19583 19.4125 8.5875C19.8042 8.97917 20 9.45 20 10V16C20 16.55 19.8042 17.0208 19.4125 17.4125C19.0208 17.8042 18.55 18 18 18H2C1.45 18 0.979167 17.8042 0.5875 17.4125C0.195833 17.0208 0 16.55 0 16Z"
              fill="currentColor"
            />
          </svg>
        }
            href="/features/leaderboards"
          >
            Create friendly competitions to increase user engagement.
          </Card>

          <Card title="Emails" icon="mail" href="/features/emails">
            Deliver personalized lifecycle emails to users at the perfect moment.
          </Card>

          <Card title="Push Notifications" icon="bell" href="/features/push-notifications">
            Drive automated notification flows using personalized gamification data.
          </Card>
        </CardGroup>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Manual" icon="user">
    These instructions are for those who want to implement Trophy by hand. If instead you prefer to use AI, switch tabs above.

    <Steps>
      <Step title="Create your Trophy account">
        First, [create a new account](https://app.trophy.so/sign-up?utm_source=docs\&utm_medium=quickstart) if you don't already have one and head into the [Trophy dashboard](https://app.trophy.so).

        Head through onboarding to get your account set up.
      </Step>

      <Step title="Add the Trophy SDK to your backend">
        We have SDK libraries available in most major programming languages but if you don't see yours listed, let us know and we'll make one!

        <CodeGroup>
          ```bash Node theme={null}
          npm install @trophyso/node
          ```

          ```bash Ruby theme={null}
          gem install trophy_api_client
          ```

          ```bash Python theme={null}
          pip install trophy
          ```

          ```bash PHP theme={null}
          composer require trophyso/php
          ```

          ```bash Java (Gradle) theme={null}
          implementation 'so.trophy:trophy-java:1.0.0'
          ```

          ```bash Java (Maven) theme={null}
          <dependency>
            <groupId>so.trophy</groupId>
            <artifactId>trophy-java</artifactId>
            <version>1.0.0</version>
          </dependency>
          ```

          ```bash Go theme={null}
          go get github.com/trophy-so/trophy-go
          ```

          ```bash .NET (C#) theme={null}
          // .NET Core CLI
          dotnet add package Trophy

          // Nuget Package Manager
          nuget install Trophy

          // Visual Studio
          Install-Package Trophy
          ```
        </CodeGroup>

        Alternatively, you can directly call the API using any server-side HTTP client.
      </Step>

      <Step title="Set up environment">
        Head to the [integration page](https://app.trophy.so/integration) of the Trophy dashboard and create a new API key.

        Add your API key as an environment variable in your backend application:

        ```bash theme={null}
        TROPHY_API_KEY='*******'
        ```

        Then initialize the Trophy API client in your backend using that API key:

        <CodeGroup>
          ```typescript Node theme={null}
          import { TrophyApiClient } from "@trophyso/node";

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

          ```ruby Ruby theme={null}
          client = TrophyApiClient::Client.new(
            :api_key => ENV["TROPHY_API_KEY"]
          )
          ```

          ```python Python theme={null}
          from trophy import Trophy

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

          ```php PHP theme={null}
          use Trophy\TrophyClient;

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

          ```java Java (Gradle) theme={null}
          TrophyApiClient client = TrophyApiClient.builder()
              .apiKey(System.getenv("TROPHY_API_KEY"))
              .build();
          ```

          ```java Java (Maven) theme={null}
          TrophyApiClient client = TrophyApiClient.builder()
              .apiKey(System.getenv("TROPHY_API_KEY"))
              .build();
          ```

          ```go Go theme={null}
          client, err := trophy.NewClient(
              option.WithAPIKey(os.Getenv("TROPHY_API_KEY")),
          )
          ```

          ```csharp .NET (C#) theme={null}
          var trophy = new TrophyClient(
              Environment.GetEnvironmentVariable("TROPHY_API_KEY")
          );
          ```
        </CodeGroup>

        Make sure all Trophy SDK calls use this client for authentication.
      </Step>

      <Step title="Create your first metric">
        All gamification features are driven by user interactions. In Trophy, you use [Metrics](/features/metrics) to define and model those interactions and [Events](/features/events) to track them.

        Here you'll create your first metric to get started. In the Trophy dashboard, head into the [metrics page](https://app.trophy.so/metrics) and hit the *New Metric* button:

        <Frame>
          <video autoPlay muted loop playsInline className="w-full aspect-video" src="https://mintcdn.com/trophy/rGjOHIeZYrVU9hOo/assets/features/metrics/create_new_metric.mp4?fit=max&auto=format&n=rGjOHIeZYrVU9hOo&q=85&s=dca1fdce56e526e270e90746ac3cfb4f" data-path="assets/features/metrics/create_new_metric.mp4" />
        </Frame>

        Give the metric a name and hit *Save*.
      </Step>

      <Step title="Integrate the metric into your backend">
        Once you've created your metric, head to the configure tab and copy it's unique API reference key.

        <Frame>
          <video autoPlay muted loop playsInline className="w-full aspect-video" src="https://mintcdn.com/trophy/sjC5fVEc34Ek6lvm/assets/quick-start/copy_metric_key.mp4?fit=max&auto=format&n=sjC5fVEc34Ek6lvm&q=85&s=0e320adc442f5025cba4eb135fc47375" data-path="assets/quick-start/copy_metric_key.mp4" />
        </Frame>

        To track an event against this metric when a user interacts with your product, call the [metric change event API](/api-reference/endpoints/events/submit-a-metric-event), passing along details of the user that made the interaction. In this example the metric key would be `flashcards-flipped`:

        <CodeGroup>
          ```bash cURL theme={null}
          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
          }'
          ```

          ```typescript Node theme={null}
          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",
            }
          );
          ```

          ```python Python theme={null}
          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
          )
          ```

          ```php PHP theme={null}
          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);
          ```

          ```java Java theme={null}
          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);
          ```

          ```go Go theme={null}
          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",
              },
          )
          ```

          ```csharp C# theme={null}
          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);
          ```

          ```ruby Ruby theme={null}
          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
          )
          ```
        </CodeGroup>

        By making this call, you're telling Trophy that a specific user made an interaction with your product. As a result, Trophy will process any gamification features like achievements or streaks that you've configured against the metric automatically.

        Use the response to react to changes in the user's gamification state and power UI elements:

        ```json Response [expandable] theme={null}
        {
          "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
        }
        ```
      </Step>

      <Step title="Continue building your gamification experience">
        With a metric integrated into your backend, you're ready to start adding gamification features to your product.

        Follow the links below to learn more about each feature you can build with Trophy:

        <CardGroup>
          <Card title="Achievements" icon="trophy" href="/features/achievements">
            Reward users for continued progress or taking specific actions.
          </Card>

          <Card title="Streaks" icon="flame" href="/features/streaks">
            Motivate users to build regular usage habits.
          </Card>

          <Card title="Points" icon="sparkle" href="/features/points">
            Build sophisticated points systems to reward and retain users.
          </Card>

          <Card
            title="Leaderboards"
            icon={
          <svg
            width="20"
            height="18"
            viewBox="0 0 20 18"
            fill="none"
            xmlns="http://www.w3.org/2000/svg"
            className="text-primary dark:text-primary-light"
          >
            <path
              d="M2 16H6V8H2V16ZM8 16H12V2H8V16ZM14 16H18V10H14V16ZM0 16V8C0 7.45 0.195833 6.97917 0.5875 6.5875C0.979167 6.19583 1.45 6 2 6H6V2C6 1.45 6.19583 0.979167 6.5875 0.5875C6.97917 0.195833 7.45 0 8 0H12C12.55 0 13.0208 0.195833 13.4125 0.5875C13.8042 0.979167 14 1.45 14 2V8H18C18.55 8 19.0208 8.19583 19.4125 8.5875C19.8042 8.97917 20 9.45 20 10V16C20 16.55 19.8042 17.0208 19.4125 17.4125C19.0208 17.8042 18.55 18 18 18H2C1.45 18 0.979167 17.8042 0.5875 17.4125C0.195833 17.0208 0 16.55 0 16Z"
              fill="currentColor"
            />
          </svg>
        }
            href="/features/leaderboards"
          >
            Create friendly competitions to increase user engagement.
          </Card>

          <Card title="Emails" icon="mail" href="/features/emails">
            Deliver personalized lifecycle emails to users at the perfect moment.
          </Card>

          <Card title="Push Notifications" icon="bell" href="/features/push-notifications">
            Drive automated notification flows using personalized gamification data.
          </Card>
        </CardGroup>

        Or, explore our [API reference](/api-reference/introduction) to get familiar with what Trophy can do.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<h2 id="get-support">
  Get Support
</h2>

Want to get in touch with the Trophy team? Reach out to us via [email](mailto:support@trophy.so). We're here to help!


## Related topics

- [Quick Start](/webhooks/quickstart.md)
- [Welcome to Trophy](/getting-started/introduction.md)
- [Introduction](/webhooks/introduction.md)
- [Emails](/features/emails.md)
- [Points boost started](/webhooks/events/points/points-boost-started.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.