---
updatedAt: 2026-10-02T12:55:20.000Z
agentTools:
  projectIndex: https://docs.ccview.io/llms.txt
---

# Coupons Stream

couponsCreated pushes every reward coupon as it is created, with the provider, the beneficiary and the round.

`couponsCreated` emits a batch of reward coupons created on the ledger at the same moment. On Canton, activity in a mining round earns reward coupons: an app earns one for the transfers it facilitates, and a featured app earns more. Each event carries an array of coupons, and each coupon in it names the provider that earned it, the party that will receive the reward, the amount and the round. Once the round closes, the coupon is claimed and the reward is minted.

Use it to track rewards for your app in real time, confirm that activity is being credited to the right beneficiary, or reconcile against your own activity records before the round closes.

## Subscribe

```graphql
subscription Coupons {
  couponsCreated(filter: { network: "mainnet" }) {
    recordTime
    round
    provider
    beneficiary
    amount
    featured
    contractId
  }
}
```

[Open in GraphiQL ↗](https://ccview.io/graphiql?query=subscription%20Coupons%20%7B%0A%20%20couponsCreated%28filter%3A%20%7B%20network%3A%20%22mainnet%22%20%7D%29%20%7B%0A%20%20%20%20recordTime%0A%20%20%20%20round%0A%20%20%20%20provider%0A%20%20%20%20beneficiary%0A%20%20%20%20amount%0A%20%20%20%20featured%0A%20%20%20%20contractId%0A%20%20%7D%0A%7D)

## Filter

All fields are optional and combine with AND. See [Filters](/reference/streams#filters) for the shared rules.

| Field         | Type     | Matches                                              |
| :------------ | :------- | :--------------------------------------------------- |
| `network`     | `String` | `mainnet`, `testnet` or `devnet`                     |
| `provider`    | `String` | Provider party ID or app name that earned the coupon |
| `beneficiary` | `String` | Beneficiary party ID or its ANS name                 |

## Event fields

| Field         | Type       | Meaning                                                                                     |
| :------------ | :--------- | :------------------------------------------------------------------------------------------ |
| `network`     | `String!`  | Network the coupon belongs to                                                               |
| `recordTime`  | `String!`  | Ledger record time, ISO 8601 UTC                                                            |
| `round`       | `Int!`     | Mining round the coupon was issued in                                                       |
| `provider`    | `String!`  | Provider party ID of the app that earned the coupon                                         |
| `beneficiary` | `String!`  | Party ID that receives the reward                                                           |
| `amount`      | `String!`  | Reward amount as a decimal string                                                           |
| `featured`    | `Boolean!` | `true` when the coupon was earned by a featured app, which is rewarded at the featured rate |
| `contractId`  | `String!`  | Contract ID of the coupon on the ledger. Stable key for deduplication                       |

## Example message

Values are illustrative.

```json
{
  "data": {
    "couponsCreated": [
      {
        "recordTime": "2026-09-30T14:03:11.482913130Z",
        "round": 61234,
        "provider": "wallet-app::12204b77e1…",
        "beneficiary": "wallet-app::12204b77e1…",
        "amount": "0.0312000000",
        "featured": true,
        "contractId": "00a1c3…"
      },
      {
        "recordTime": "2026-09-30T14:03:12.004118902Z",
        "round": 61234,
        "provider": "dex-venue::1220e4a1b0…",
        "beneficiary": "dex-treasury::1220b9e2c4…",
        "amount": "0.0040000000",
        "featured": false,
        "contractId": "00f7d2…"
      }
    ]
  }
}
```

## Example: rewards earned by your app

Filter on your provider party. Group by `round` to see what each round will pay out, and by `beneficiary` to check that rewards go where you configured them.

```graphql
subscription MyAppRewards {
  couponsCreated(filter: { network: "mainnet", provider: "my-app::1220c0de…" }) {
    recordTime
    round
    beneficiary
    amount
    featured
  }
}
```

[Open in GraphiQL ↗](https://ccview.io/graphiql?query=subscription%20MyAppRewards%20%7B%0A%20%20couponsCreated%28filter%3A%20%7B%20network%3A%20%22mainnet%22%2C%20provider%3A%20%22my-app%3A%3A1220c0de%E2%80%A6%22%20%7D%29%20%7B%0A%20%20%20%20recordTime%0A%20%20%20%20round%0A%20%20%20%20beneficiary%0A%20%20%20%20amount%0A%20%20%20%20featured%0A%20%20%7D%0A%7D)

## Related REST endpoints

[Rewards history](/reference/rewards_history_v1) for history and backfill. [Rewards statistics](/reference/rewards_stats_v1) and [Rewards leaderboard](/reference/rewards_leaderboard_v1) for aggregates. [Get featured app profile](/reference/featured_app_profile_v1) for the app's featured status.