> For the complete documentation index, see [llms.txt](https://docs.cronos-pos.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cronos-pos.org/cronos-pos-chain-protocol/tiered-staking.md).

# Tiered Staking

Tiered staking is a new staking mechanism introduced in Cronos POS Chain v7 (via the `x/tieredrewards` module). CRO holders can lock their stake for a defined exit commitment period in exchange for a higher APY on top of standard staking rewards.

There are two components to staking rewards under the new model:

<table><thead><tr><th width="200.984375">Reward Type</th><th>Source</th><th>Condition</th></tr></thead><tbody><tr><td><strong>Base rewards</strong></td><td>The inflation + transaction fee + reserve top up</td><td>Must be delegated to a bonded validator</td></tr><tr><td><strong>Bonus rewards</strong></td><td>Tier Rewards Pool</td><td>Must be in a tier position AND delegated to a bonded validator</td></tr></tbody></table>

The base reward floor (\~3% APY) is guaranteed by the module - if block fees fall below the target rate, the rewards pool automatically tops up the shortfall. Bonus rewards are a fixed APY on top of the base rate, determined by the tier you choose.

**Key things to know:**

* **Voting rights preserved** \
  Tier-locked positions count toward governance voting power for the full duration of the lock.
* **Slashing applies** \
  Locked positions are subject to standard validator slashing rules.
* **Rewards are not automatic**\
  Rewards do not arrive in your wallet automatically. They are paid out when settlement runs inside a transaction or via hooks. Besides `claim-tier-rewards`, several other scenarios can implicitly **claim outstanding rewards** too (see Claim base and bonus rewards).
* **Change validator freely**  \
  You can move your position to a different validator at any time without triggering exit.

***

### Tier Structure

| Tier | Exit Commitment | Bonus APY | Total APY (approx.) | Min. Lock |
| ---- | --------------- | --------- | ------------------- | --------- |
| Base | —               | —         | \~3%                | —         |
| 1    | 1 year          | +2%       | \~5%                | 100 CRO   |
| 2    | 2 years         | +4%       | \~7%                | 100 CRO   |
| 3    | 4 years         | +7%       | \~10%               | 100 CRO   |

{% hint style="info" %}
APY values are illustrative. Actual rates depend on governance decisions and available protocol revenue. All tier parameters are governance-adjustable.
{% endhint %}

{% hint style="info" %}
**For integration:** Always fetch live tier values from the chain. Parameters can change via governance. \
Use `GET /chainmain/tieredrewards/v1/tiers` or `chain-maind query tieredrewards tiers`. \
The on-chain `Tier` struct fields are: `Id`, `ExitDuration`, `BonusApy` (decimal, e.g. `0.02` = 2%), `MinLockAmount`, `CloseOnly`.
{% endhint %}

The **exit commitment** is the waiting period that begins when you *choose* to exit - not when you originally locked your stake. You continue earning full base and bonus rewards throughout this waiting period.

When governance sets a tier to **close-only** (`CloseOnly = true`), no new positions can be opened in that tier. Existing positions continue earning rewards and can exit normally. This is how a tier is retired over time.

***

### Testnet vs Mainnet Parameters

Testnet uses shorter durations and lower minimums so full lifecycle flows can be tested in minutes.

| Parameter                   | Mainnet | Testnet   |
| --------------------------- | ------- | --------- |
| Tier 1 exit commitment      | 1 year  | 1 minute  |
| Tier 2 exit commitment      | 2 years | 2 minutes |
| Tier 3 exit commitment      | 4 years | 4 minutes |
| Min lock amount (all tiers) | 100 CRO | 1 CRO     |

**Endpoints:**

<table><thead><tr><th width="105.81640625">Network</th><th width="402.29296875">REST</th><th>Chain ID</th></tr></thead><tbody><tr><td>Mainnet</td><td><code>https://rest.mainnet.crypto.org</code></td><td><code>crypto-org-chain-mainnet-1</code></td></tr><tr><td>Testnet</td><td><code>https://rest.testnet-croeseid-4.cronos-pos.org</code></td><td><code>testnet-croeseid-4</code></td></tr></tbody></table>

***

### Position Lifecycle

```
Enter a tier
  ├── Lock fresh CRO            → lock-tier
  └── Commit existing stake     → commit-delegation-to-tier
            │
            ▼
     Active position
     Earning base + bonus rewards
     [can: add tokens, redelegate, claim rewards]
            │
            ▼
     Trigger exit               → trigger-exit
     Exit commitment countdown begins
     Still earning full rewards
     [can: redelegate, claim rewards, cancel exit]
            │
     Exit commitment elapses — bonus stops
            │
            ├── Instant exit    → exit-tier-with-delegation
            │   Stake returns to your wallet on the same validator. No unbonding wait.
            │   Partial exits supported.
            │
            └── Standard exit   → tier-undelegate
                Wait 28 days (unbonding period)
                                → withdraw-from-tier
                Tokens available for transfer
```

{% hint style="info" %}
You can cancel exit at any time using `clear-position`. The exit timer resets and bonus rewards resume immediately.
{% endhint %}

***

### Transaction Commands

Replace `[YOUR_KEY]` and `[CHAIN_ID]` with your key name and the appropriate chain ID.

**Common flags:**

```bash
--from [YOUR_KEY]        # Signing key
--chain-id [CHAIN_ID]    # e.g. crypto-org-chain-mainnet-1 or testnet-croeseid-4
--gas auto               # Recommended: auto-estimate gas
--fees [amount]basecro   # e.g. 20000basecro
```

#### Entering a Tier

**Option A - Lock fresh CRO into a tier:**

```bash
chain-maind tx tieredrewards lock-tier [tier-id] [amount] [validator-address] \
  --from [YOUR_KEY] --chain-id [CHAIN_ID] --gas auto
```

| Argument            | Description                                           |
| ------------------- | ----------------------------------------------------- |
| `tier-id`           | `1`, `2`, or `3`                                      |
| `amount`            | In basecro (1 CRO = 100,000,000 basecro)              |
| `validator-address` | Validator operator address (starts with `crocncl...`) |

Optional flag: `--trigger-exit-immediately` - starts the exit countdown immediately at lock time.

Example:

```bash
chain-maind tx tieredrewards lock-tier 1 10000000000basecro crocncl1abc...xyz \
  --from mykey --chain-id crypto-org-chain-mainnet-1 --gas auto
```

**Option B - Lock an existing delegation (no unbonding required):**

```bash
chain-maind tx tieredrewards commit-delegation-to-tier [validator-address] [amount] [tier-id] \
  --from [YOUR_KEY] --chain-id [CHAIN_ID] --gas auto
```

* Converts your existing stake on that validator into a tier position in one step
* Partial commits are supported — you can commit a portion of your delegation
* Optional flag: `--trigger-exit-immediately`

Example:

```bash
chain-maind tx tieredrewards commit-delegation-to-tier crocncl1abc...xyz 10000000000basecro 2 \
  --from mykey --chain-id crypto-org-chain-mainnet-1 --gas auto
```

#### Managing a Position

Query the positions by owner:

```bash
chain-maind query tieredrewards positions-by-owner [THE_ADDRESS_OF_YOUR_KEY] 
```

* here is [the explanation of fields in response](#key-fields-in-position-responses)

Add more CRO to an existing position:

```bash
chain-maind tx tieredrewards add-to-tier-position [position-id] [amount] \
  --from [YOUR_KEY] --chain-id [CHAIN_ID] --gas auto
```

{% hint style="warning" %}
Cannot add tokens while an exit is in progress. Cancel the exit with `clear-position` first.
{% endhint %}

Move your position (redelegate) to a different validator (does not trigger exit):

```bash
chain-maind tx tieredrewards tier-redelegate [position-id] [dst-validator-address] \
  --from [YOUR_KEY] --chain-id [CHAIN_ID] --gas auto
```

Claim base and bonus rewards (explicit):

```bash
chain-maind tx tieredrewards claim-tier-rewards [position-id ...] \
  --from [YOUR_KEY] --chain-id [CHAIN_ID] --gas auto
```

Multiple position IDs can be claimed in a single transaction (space-separated):

```bash
chain-maind tx tieredrewards claim-tier-rewards 313 314 315 \
  --from mykey --chain-id crypto-org-chain-mainnet-1 --gas auto
```

**Other user transactions that settle rewards first**

The keeper runs the same base + bonus settlement **before** the main execution of these messages: `tier-undelegate`, `tier-redelegate`, `add-to-tier-position`, `exit-tier-with-delegation`, and `clear-position`.

**Slashing a position**

When the staking module slashes an **active redelegation** that is mapped to your position, any **outstanding rewards** on the position will also be claimed.

{% hint style="warning" %}
Rewards are **not** distributed automatically. `claim-tier-rewards` is the dedicated explicit claim, and **other messages and hook settlements** may initiate claims too.
{% endhint %}

#### Exiting a Tier

**Step 1 - Trigger exit (starts the commitment countdown):**

```bash
chain-maind tx tieredrewards trigger-exit [position-id] \
  --from [YOUR_KEY] --chain-id [CHAIN_ID] --gas auto
```

Your position continues earning full base and bonus rewards during the commitment period.

**Cancel exit at any time:**

```bash
chain-maind tx tieredrewards clear-position [position-id] \
  --from [YOUR_KEY] --chain-id [CHAIN_ID] --gas auto
```

**Step 2 - After exit commitment elapses, choose one route:**

**Option A - Instant exit (no unbonding):**

```bash
chain-maind tx tieredrewards exit-tier-with-delegation [position-id] [amount] \
  --from [YOUR_KEY] --chain-id [CHAIN_ID] --gas auto
```

Your stake transfers back to your wallet on the same validator immediately. Partial exits are supported that the remaining position must still meet the tier minimum (100 CRO on mainnet).

**Option B - Standard unbonding (28-day wait):**

```bash
# Step 1: Start unbonding
chain-maind tx tieredrewards tier-undelegate [position-id] \
  --from [YOUR_KEY] --chain-id [CHAIN_ID] --gas auto

# Step 2: After 28 days, withdraw tokens
chain-maind tx tieredrewards withdraw-from-tier [position-id] \
  --from [YOUR_KEY] --chain-id [CHAIN_ID] --gas auto
```

**Option C - Renew your commitment with `clearPosition`**&#x20;

After exit commitment elapses, you can use clear-position to cancel the exit instead of withdrawing. This resets the exit timer and resumes bonus rewards, effectively renewing your commitment without needing to re-lock.&#x20;

```shellscript
 chain-maind tx tieredrewards clear-position [position-id] \                                
    --from [YOUR_KEY] --chain-id [CHAIN_ID] --gas auto
```

### Query Commands

```bash
# List all available tiers and their parameters
chain-maind query tieredrewards tiers

# View all positions for an address
chain-maind query tieredrewards positions-by-owner [address]

# View a specific position by ID
chain-maind query tieredrewards position [position-id]

# Estimate pending base + bonus rewards for a position
chain-maind query tieredrewards estimate-position-rewards [position-id]

# Check the rewards pool balance
chain-maind query tieredrewards rewards-pool-balance

# Check module parameters (TargetBaseRewardsRate)
chain-maind query tieredrewards params

# Check governance voting power from tier positions
chain-maind query tieredrewards voting-power [address]

# Check validator reward data
chain-maind query tieredrewards validator-data [validator-address]

# Query inflation parameters (max supply, decay rate)
chain-maind query inflation params
```

***

### REST API Reference

No authentication required. Standard HTTP GET requests.

| Network | Base URL                                         |
| ------- | ------------------------------------------------ |
| Mainnet | `https://rest.mainnet.crypto.org`                |
| Testnet | `https://rest.testnet-croeseid-4.cronos-pos.org` |

#### x/tieredrewards Endpoints

<table><thead><tr><th width="528.37109375">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td><code>GET /chainmain/tieredrewards/v1/tiers</code></td><td>All tier definitions</td></tr><tr><td><code>GET /chainmain/tieredrewards/v1/params</code></td><td>Module parameters</td></tr><tr><td><code>GET /chainmain/tieredrewards/v1/position/{position_id}</code></td><td>Single position by ID</td></tr><tr><td><code>GET /chainmain/tieredrewards/v1/positions/{owner_address}</code></td><td>All positions for an owner</td></tr><tr><td><code>GET /chainmain/tieredrewards/v1/positions</code></td><td>All positions (paginated)</td></tr><tr><td><code>GET /chainmain/tieredrewards/v1/estimate_rewards/{position_id}</code></td><td>Estimated pending rewards</td></tr><tr><td><code>GET /chainmain/tieredrewards/v1/rewards_pool_balances</code></td><td>Rewards pool balance</td></tr><tr><td><code>GET /chainmain/tieredrewards/v1/voting_power/{owner}</code></td><td>Voting power by owner</td></tr><tr><td><code>GET /chainmain/tieredrewards/v1/total_delegated_voting_power</code></td><td>Total voting power</td></tr><tr><td><code>GET /chainmain/tieredrewards/v1/validator_data/{validator}</code></td><td>Validator reward data</td></tr><tr><td><code>GET /chainmain/tieredrewards/v1/position_mappings/{position_id}</code></td><td>Unbonding/redelegation mappings</td></tr></tbody></table>

#### x/inflation Endpoints

| Endpoint                             | Description                                                        |
| ------------------------------------ | ------------------------------------------------------------------ |
| `GET /chainmain/inflation/v1/params` | Inflation parameters (max\_supply, decay\_rate, burned\_addresses) |

#### Pagination

List endpoints that support pagination via query parameters:

```
?pagination.limit=50&pagination.offset=0
```

***

### Integration

Tier positions are queryable via standard public REST endpoints.

#### Recommended queries for balance and position tracking

```bash
# All positions for a user
GET https://rest.mainnet.crypto.org/chainmain/tieredrewards/v1/positions/{owner_address}

# Estimated current rewards for a position
GET https://rest.mainnet.crypto.org/chainmain/tieredrewards/v1/estimate_rewards/{position_id}

# Current tier definitions
GET https://rest.mainnet.crypto.org/chainmain/tieredrewards/v1/tiers
```

#### Key fields in position responses

<table><thead><tr><th width="283.0234375">Field</th><th>Notes</th></tr></thead><tbody><tr><td><code>tier_id</code></td><td>Which tier: 1, 2, or 3</td></tr><tr><td><code>amount</code></td><td>Amount of tokens stored in the position</td></tr><tr><td><code>delegated_shares</code></td><td>Shares held by the tier module on behalf of this position</td></tr><tr><td><code>validator</code></td><td>Current validator operator address</td></tr><tr><td><code>exit_triggered_at</code></td><td>Zero value = not exiting</td></tr><tr><td><code>exit_unlock_at</code></td><td>When exit commitment elapses and tokens become withdrawable</td></tr><tr><td><code>last_bonus_accrual</code></td><td>Timestamp of last bonus settlement</td></tr></tbody></table>

Partners signing and submitting transactions use standard Cosmos SDK transaction signing - the same flow as regular staking transactions. No new signing logic is required.

***

### Key Rules and Gotchas

<table><thead><tr><th width="279.046875">Topic</th><th>Rule</th></tr></thead><tbody><tr><td>Rewards settlement</td><td>Rewards do not distribute automatically. Users either claim directly <code>claim-tier-rewards</code> or through other messages that will initiate an claim.</td></tr><tr><td>Exit commitment timing</td><td>The commitment period starts when you <em>trigger</em> exit, not when you entered the tier.</td></tr><tr><td>Bonus stops at exit unlock</td><td>Bonus stops accruing once the exit commitment elapses. Base rewards continue.</td></tr><tr><td>No auto-rollover</td><td>When exit commitment elapses, the position stays active until the user submits an exit transaction.</td></tr><tr><td>Add to position</td><td>Cannot add tokens while an exit is in progress. Cancel with <code>clear-position</code> first.</td></tr><tr><td>Redelegate freely</td><td>Moving to a different validator does not trigger exit or affect tier status.</td></tr><tr><td>Partial exits</td><td>Instant exit supports partial amounts. Remaining balance must still meet the tier minimum.</td></tr><tr><td>Pool can be empty</td><td>If the rewards pool has insufficient balance, the claim transaction fails. Retry after replenishment.</td></tr><tr><td>Slashing applies</td><td>Tier-locked positions are subject to standard validator slashing rules.</td></tr><tr><td>Voting rights retained</td><td>Tier-locked positions count toward governance voting power throughout the lock.</td></tr><tr><td>Validator jailed or removed</td><td>Position stays valid. User can redelegate to another validator without triggering exit.</td></tr></tbody></table>

***

### Quick Reference

<table><thead><tr><th width="228.08984375">Action</th><th>Command</th></tr></thead><tbody><tr><td>Lock fresh CRO</td><td><code>tx tieredrewards lock-tier [tier-id] [amount] [validator]</code></td></tr><tr><td>Commit existing stake</td><td><code>tx tieredrewards commit-delegation-to-tier [validator] [amount] [tier-id]</code></td></tr><tr><td>Add to position</td><td><code>tx tieredrewards add-to-tier-position [position-id] [amount]</code></td></tr><tr><td>Redelegate</td><td><code>tx tieredrewards tier-redelegate [position-id] [dst-validator]</code></td></tr><tr><td>Claim rewards</td><td><code>tx tieredrewards claim-tier-rewards [position-id ...]</code></td></tr><tr><td>Trigger exit</td><td><code>tx tieredrewards trigger-exit [position-id]</code></td></tr><tr><td>Cancel exit</td><td><code>tx tieredrewards clear-position [position-id]</code></td></tr><tr><td>Instant exit</td><td><code>tx tieredrewards exit-tier-with-delegation [position-id] [amount]</code></td></tr><tr><td>Start unbonding</td><td><code>tx tieredrewards tier-undelegate [position-id]</code></td></tr><tr><td>Withdraw after unbonding</td><td><code>tx tieredrewards withdraw-from-tier [position-id]</code></td></tr><tr><td>View my positions</td><td><code>query tieredrewards positions-by-owner [address]</code></td></tr><tr><td>Estimate rewards</td><td><code>query tieredrewards estimate-position-rewards [position-id]</code></td></tr><tr><td>View tiers</td><td><code>query tieredrewards tiers</code></td></tr><tr><td>Inflation params</td><td><code>query inflation params</code></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cronos-pos.org/cronos-pos-chain-protocol/tiered-staking.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.