> ## Documentation Index > Fetch the complete documentation index at: https://docs.cabalspy.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Trading competitions > Run trading competitions between your platform users: ranked on real on-chain trades by PnL, volume, trades or win rate, with standings every 5 minutes and webhooks. Run trading competitions between your [platform users](https://docs.cabalspy.xyz/cabalspy-id/white-label.md). Participants are ranked on their real on-chain trades during the competition, by the metric you choose. You set the rules, CabalSpy ID starts the competition, computes the standings every 5 minutes, ends it on time and freezes the results. Competitions are for individual traders. A key only reaches the competitions of its own instance, and participants are your platform users, addressed by `external_id`. You can also create, change and cancel competitions and follow their standings on the instance's [Competitions](https://docs.cabalspy.xyz/cabalspy-id/dashboard.md#competitions) tab in the dashboard. Chain, enrollment, start time, description and prizes of an existing competition can only be changed through the API. ## Lifecycle | Status | Meaning | | - | - | | `scheduled` | Created, the start time has not come yet. | | `waiting` | The start time has passed, but fewer than `min_participants` joined. It starts as soon as enough have joined. | | `running` | Started. The timer of `duration_hours` runs from `started_at` to `ends_at`. | | `ended` | Over. The final standings are frozen and are the results. | | `cancelled` | Cancelled by you before it ended. | A competition starts at `starts_at`, or at once when you leave it out, but only once `min_participants` have joined. The duration counts from the actual start. At most **5 competitions** can be open at the same time (scheduled, waiting and running) per developer account, across all your instances. End or cancel one to start another. ## Who takes part * `enrollment: "opt_in"`: users take part when you [join](https://docs.cabalspy.xyz/cabalspy-id/competitions-participants.md) them, for example when they press a button on your site. * `enrollment: "all_users"`: every platform user of your instance takes part, also users you add later while the competition is scheduled, and while it runs if `late_join` is true. `late_join` decides whether users can still join after the start. `max_participants` caps the field, also with `all_users`: then the users you created first take part. A user who [left](https://docs.cabalspy.xyz/cabalspy-id/competitions-participants.md#leave) is not entered again automatically. ## What counts Each participant competes with **all their wallets that count on the competition's chain**. With the competition's `wallet_trust: "verified_only"`, only payment-verified wallets count; your instance's own `wallet_trust` [setting](https://docs.cabalspy.xyz/cabalspy-id/platform-users-settings.md) always applies too. Only trades made while the competition runs count. A wallet added or verified after the start counts from that moment on. ## Metrics | metric | Score | | - | - | | `pnl_usd` | Sells minus buys in USD during the competition. | | `pnl` | Sells minus buys in the chain's native currency. | | `volume_usd` | Buy plus sell volume in USD. | | `volume` | Buy plus sell volume in the native currency. | | `trades` | Number of buys and sells. | | `win_rate` | Winning closed positions as a percentage of closed positions. | Highest score ranks first. Ties are broken by higher USD volume, then by who joined first. ## Minimums `min_trades` and `min_volume_usd` set what a trader needs to be ranked. A participant below them, or without any trade, is still listed in the standings, with `rank: null` and `ranked: false`, after the ranked traders. With `metric: "win_rate"` a trader also needs at least one closed position. ## Changing the rules Every rule can be changed at any time, also while the competition runs, with [Update](https://docs.cabalspy.xyz/cabalspy-id/competitions-update.md). Each change raises `rules_version`, is recorded with what changed, when and in which phase, and is sent as the `competition.updated` webhook. The competition detail returns every change in `changes` and `changed_while_running`, so you can show participants a transparent rules history. Changing `duration_hours` while running moves `ends_at`. ## Standings and results Standings are recomputed every **5 minutes** while a competition runs, and once more when it ends. [Standings](https://docs.cabalspy.xyz/cabalspy-id/competitions-standings.md) returns them with `updated_at`; after the end they are final. ## Webhooks Competition events go to your instance's [webhook](https://docs.cabalspy.xyz/cabalspy-id/webhooks.md#competition-events): | Event | When | | - | - | | `competition.started` | The competition started. | | `competition.updated` | A rule was changed. | | `competition.standings` | New standings were computed, with the top 20. | | `competition.ended` | The competition ended with the results, or was cancelled. | ## Endpoints | Method | Path | Description | | - | - | - | | POST | [/v1/competitions](https://docs.cabalspy.xyz/cabalspy-id/competitions-create.md) | Create a competition. | | GET | [/v1/competitions](https://docs.cabalspy.xyz/cabalspy-id/competitions-list.md) | Your competitions. | | GET | [/v1/competitions/detail](https://docs.cabalspy.xyz/cabalspy-id/competitions-list.md#competition-detail) | One competition with its rules history. | | POST | [/v1/competitions/update](https://docs.cabalspy.xyz/cabalspy-id/competitions-update.md) | Change rules. | | POST | [/v1/competitions/cancel](https://docs.cabalspy.xyz/cabalspy-id/competitions-update.md#cancel) | Cancel. | | POST | [/v1/competitions/join](https://docs.cabalspy.xyz/cabalspy-id/competitions-participants.md) | Enter a user. | | POST | [/v1/competitions/leave](https://docs.cabalspy.xyz/cabalspy-id/competitions-participants.md#leave) | Take a user out. | | GET | [/v1/competitions/participants](https://docs.cabalspy.xyz/cabalspy-id/competitions-participants.md#list-participants) | Participants. | | GET | [/v1/competitions/standings](https://docs.cabalspy.xyz/cabalspy-id/competitions-standings.md) | Standings and results. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.