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

# onTokenLifecycleEventsCreated

> Live stream of ERC-20 / SPL mint and burn events for a single token or for an entire network.

<Note>
  Subscriptions use `wss://graphql.mobula.io/graphql` with the `graphql-transport-ws` protocol. `wss://graphql.mobula.io/graphql/subscriptions` is also supported for backwards compatibility.
</Note>

### Returns

<ResponseField name="onTokenLifecycleEventsCreated" type="AddTokenLifecycleEventsOutput!">
  Batched mint/burn events delivered as they are produced upstream. See [AddTokenLifecycleEventsOutput](/api-reference/graphql/types/AddTokenLifecycleEventsOutput).
</ResponseField>

### Arguments

<ResponseField name="networkId" type="Int">
  Network id to scope the subscription to (e.g. `1` for Ethereum, `56` for BNB Chain, `1399811149` for Solana). Optional in the schema, but required at runtime — there is no cross-network firehose.
</ResponseField>

<ResponseField name="address" type="String">
  Token contract address. **Optional**:

  * Provide an `address` to receive only that token's mint/burn events on the given network.
  * Omit `address` to receive every mint/burn event on the entire network (per-network firehose).
</ResponseField>

### Behavior

* Fires for ERC-20 `Transfer(from = 0x0)` / `Transfer(to = 0x0)` events on EVM chains and for SPL `mintTo` / `burn` instructions on Solana. The mint/burn classification is performed upstream in the transfer extractor.
* `totalSupply` and `circulatingSupply` are looked up from the token storage cache at fan-out time, but **only** when the GraphQL selection set requests them — selecting only `amount` skips the lookup entirely.
* Multiple events can be delivered in one push: the resolver returns `{ id, events: [...] }`, where `events` may contain several mint/burn events that landed in the same upstream batch.
* The same event reaches both token-scoped subscribers (`tokenAddress + networkId`) and the network-firehose subscribers (`networkId` only) on that chain.

### Example — single token on a specific network

Stream mint/burn events for one token on BNB Chain (`networkId: 56`):

```graphql theme={null}
subscription {
  onTokenLifecycleEventsCreated(
    networkId: 56
    address: "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c"
  ) {
    id
    events {
      tokenAddress
      networkId
      blockHash
      blockNumber
      id
      logIndex
      maker
      timestamp
      transactionHash
      transactionIndex
      eventType
      data {
        __typename
        ... on TokenMintEventData {
          amount
          totalSupply
          circulatingSupply
        }
        ... on TokenBurnEventData {
          amount
          totalSupply
          circulatingSupply
        }
      }
    }
  }
}
```

### Example — every mint/burn on a network (firehose)

Omit `address` to receive every mint/burn event on the network. This subscribes to all token lifecycle activity on BNB Chain:

```graphql theme={null}
subscription {
  onTokenLifecycleEventsCreated(networkId: 56) {
    id
    events {
      tokenAddress
      networkId
      blockHash
      blockNumber
      id
      logIndex
      maker
      timestamp
      transactionHash
      transactionIndex
      eventType
      data {
        __typename
        ... on TokenMintEventData {
          amount
          totalSupply
          circulatingSupply
        }
        ... on TokenBurnEventData {
          amount
          totalSupply
          circulatingSupply
        }
      }
    }
  }
}
```

### Example — JSON request body

The same firehose query as a JSON-encoded subscription frame (e.g. for `graphql-transport-ws`):

```json theme={null}
{
  "query": "subscription { onTokenLifecycleEventsCreated(networkId: 56) { id events { tokenAddress networkId blockHash blockNumber id logIndex maker timestamp transactionHash transactionIndex eventType data { __typename ... on TokenMintEventData { amount totalSupply circulatingSupply } ... on TokenBurnEventData { amount totalSupply circulatingSupply } } } } }"
}
```