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

# Earn and use GEM

> Nontransferable benefit units earned from settled protocol swap fees.

GEM is a nontransferable benefit unit in the local protocol. Settled swaps can earn GEM, and an approved service can burn it with holder consent. GEM has no transferable market pair or guaranteed cash value.

<Info>
  These mechanics run on Anvil. The app's gacha balance is separate sample
  state; opening a bag there does not mint or burn onchain GEM.
</Info>

For a visual introduction, start with [Meet GEMs](/guides/gems).

## Intended eligibility and current limits

GRAPL intends to drop GEM to traders who generate legitimate volume in eligible tokens. Final eligibility and anti-abuse rules are still being defined. The local fee-based implementation does not detect wash trading, Sybil activity or related-wallet patterns; it has no review epochs, multidimensional scoring or clawback. A positive fee and replay protection do not establish legitimate activity.

## How a swap earns GEM

```mermaid theme={null}
flowchart TD
  Swap[Settle authenticated swap] --> Fee[Collect GRAPL protocol fee]
  Fee --> Reserve[Share to GEM reserve]
  Fee --> Treasury[Share to treasury]
  Fee --> Rewards[Calculate fee-based GEM reward]
  Rewards --> Cap[Limit by remaining lifetime issuance]
  Cap --> Wallet[Mint GEM to trader]
```

`SwapRewards` accepts a unique trade ID from the authorized router and receives the protocol fee. IDs bind chain, router and nonce and cannot be consumed twice. Rewards are proportional to fees, limited by remaining lifetime issuance. Zero fee yields zero GEM; trading an unrelated external pool does not automatically earn GEM.

<Tabs>
  <Tab title="Local example">
    **10 GRAPL** of executed volume pays **0.05 GRAPL** at 50 basis points. With 100 GEM per GRAPL of fee, that earns **5 GEM**, assuming sufficient lifetime capacity. Half the fee enters the reserve; half goes to treasury.

    These are [test parameters](/reference/local-parameters), not approved launch economics. LP fees and gas are separate.
  </Tab>

  <Tab title="Lifetime cap">
    Minting stops at the lifetime cap. Swaps and fees can continue with zero new GEM. Burning reduces outstanding supply but never restores lifetime mint capacity.
  </Tab>

  <Tab title="Emergency pause">
    Relevant GEM, reserve or rewards pauses can revert the whole trading transaction. Pause is an emergency stop, not a mode that silently trades without rewards.
  </Tab>
</Tabs>

## Spending requires benefit consent

GEM blocks ordinary transfers and ERC-20 approvals. A holder grants a limited allowance through `GemReserve.approveBenefit(service, amount)`. An approved service uses `consumeFor` to spend the allowance, burn GEM and receive the corresponding GRAPL reference debit.

This allowance is separate from a token-trading approval. Users can replace it with zero while the service remains approved. The legitimate burner is the reserve, but an administrator can assign the underlying burner role elsewhere; see [authority risks](/reference/security).

<CardGroup cols={2}>
  <Card title="Understand the reserve" icon="vault" href="/concepts/gem-reserve">
    How funding, supply and the benefit ceiling determine a reference debit.
  </Card>

  <Card title="Understand token bags" icon="gift" href="/concepts/gacha">
    Follow payment, inventory reservation and delivery.
  </Card>
</CardGroup>


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