Skip to main content

Reputation Integration Guide

Karma is Status Network's soulbound reputation token. Every address earns Karma through genuine network participation such as staking SNT, bridging assets, providing liquidity, using apps, or paying premium gas fees. Karma cannot be bought, sold, or transferred.

This guide covers how to read Karma data and build apps that respond to a user's reputation tier.

Reading Karma On-Chain​

Karma state is split across two contracts:

  • Karma β€” the soulbound ERC-20 token. balanceOf returns the net balance after any slashing. Transfers and approvals always revert.
  • KarmaTiers β€” maps balances to tiers. Call getTierIdByKarmaBalance(balance) then getTierById(tierId) to resolve a user's tier and its txPerEpoch quota.
// SPDX-License-Identifier: MIT
pragma solidity 0.8.26;

/// @notice Minimal interface for the Karma soulbound token.
interface IKarma {
    /// @notice Net Karma balance of `account` after slashing.
    function balanceOf(address account) external view returns (uint256);

    /// @notice Total amount slashed from `account` across all distributors.
    function slashedAmountOf(address account) external view returns (uint256);
}

/// @notice Minimal interface for the KarmaTiers registry.
interface IKarmaTiers {
    struct Tier {
        uint256 minKarma;
        uint256 maxKarma;
        string  name;
        uint32  txPerEpoch; // gasless transactions allowed per epoch
    }

    /// @notice Returns the highest tier ID the given karma balance qualifies for.
    function getTierIdByKarmaBalance(uint256 karmaBalance) external view returns (uint8);

    /// @notice Returns the full Tier struct for a given tier ID.
    function getTierById(uint8 tierId) external view returns (Tier memory);

    /// @notice Returns the total number of configured tiers.
    function getTierCount() external view returns (uint256);
}

contract KarmaGated {
    IKarma      public karma;
    IKarmaTiers public karmaTiers;

    constructor(address _karmaContract, address _karmaTiersContract) {
        karma      = IKarma(_karmaContract);
        karmaTiers = IKarmaTiers(_karmaTiersContract);
    }

    /// @notice Resolves the tier ID for `user` from their current Karma balance.
    function tierIdOf(address user) public view returns (uint8) {
        return karmaTiers.getTierIdByKarmaBalance(karma.balanceOf(user));
    }

    modifier onlyTier(uint8 minTier) {
        require(tierIdOf(msg.sender) >= minTier, "Karma tier too low");
        _;
    }

    function premiumAction() external onlyTier(3) {
        // Only users at tier 3 or above can call this
    }

    function getDiscount(address user) external view returns (uint256) {
        uint8 tierId = tierIdOf(user);
        // Higher tiers get bigger discounts
        return uint256(tierId) * 5; // 0%, 5%, 10%, ...
    }
}
Contract Addresses

Karma and KarmaTiers contract addresses for testnet are published on the Contract Addresses page.

Possible Integration Patterns​

Feature Gating​

Unlock features based on Karma tier. The onlyTier modifier you can check from the Reading Karma On-Chain section can restrict access at the contract level. Alternatively, you can use tierId in your code to gate features:

Catalog idea: Karma-Gated Content Feed β€” a ready-to-scope app built entirely around this pattern.

function accessPremiumContent() external onlyTier(3) {
    // Only users at tier 3 or above can call this
}

Dynamic Pricing​

Offer discounts or better rates to high-Karma users:

Catalog idea: Karma-Tiered NFT Marketplace β€” a marketplace where fees and access windows scale automatically with a buyer's Karma tier.

function calculateFee(address user, uint256 baseAmount) public view returns (uint256) {
    uint8 tierId = karmaTiers.getTierIdByKarmaBalance(karma.balanceOf(user));
    // Each tier gives 5% discount
    uint256 discount = uint256(tierId) * 5;
    return baseAmount * (100 - discount) / 100;
}

Reputation Display​

Show Karma tier as a trust index in your UI by reading the tier name directly from the KarmaTiers contract:

Catalog idea: Gasless Micro-Blogging Platform β€” a social feed with Karma trust badges embedded in profiles and posts.

// Fetch tier name on-chain β€” no hardcoded array needed
const balance = await karma.balanceOf(userAddress);
const tierId  = await karmaTiers.getTierIdByKarmaBalance(balance);
const tier    = await karmaTiers.getTierById(tierId);

function KarmaBadge({ tierName }) {
  return <span className="karma-badge">{tierName}</span>;
}

// Usage
<KarmaBadge tierName={tier.name} />

Weighted Governance​

Use Karma for vote weighting in your app's governance:

Catalog idea: DAO Proposal & Karma-Weighted Voting App β€” polling and signal voting with optional Karma-weighted participation.

function vote(uint256 proposalId, bool support) external {
    uint256 weight = karma.balanceOf(msg.sender);
    proposals[proposalId].votes += support ? int256(weight) : -int256(weight);
}

Next Steps​