Skip to main content
A campaign distributes a reward to a group of wallets in a point system. Rewards come in two kinds — tokens (an on-chain merkle airdrop wallets claim themselves) and gift cards (off-chain secret codes) — and every campaign starts life as an editable draft before you publish it. Campaigns live under the Campaigns section of the dashboard.
Publishing a token campaign settles on-chain and needs a wallet signature, so it always happens in the dashboard. An AI assistant or the MCP can prepare a campaign down to the last wallet, but only you can sign it. See MCP Server and Assistant.

​
The two reward kinds

Token campaigns are deployed on Somnia and Base only. The token can be a native coin (SOMI on Somnia, ETH on Base), a stablecoin (USDC / USDT), or any other ERC-20 by contract address. See the supported chains table.

​
Who’s included

Every campaign targets a cohort. You choose how that cohort is built: Blacklisted wallets are always excluded, whatever the mode. See Blacklist.

​
How much each wallet gets

For token campaigns, a total amount is split across winners by an allocation type:
  • Proportional — each wallet’s share scales with its points (total × walletPoints / totalEligiblePoints).
  • Equal — the total is divided evenly across all winners.

​
From draft to live

A campaign moves through a few states:

​
Publishing a token campaign

  1. Draft — set the token, chain, cohort, and amount.
  2. Compute distributions — Rewards works out each wallet’s allocation and builds the merkle tree.
  3. Deposit — your wallet signs a transaction depositing the total into the campaign contract.
  4. Active — once the deposit is confirmed, the campaign flips to active and wallets can claim.
If you reject the wallet transaction or it reverts, the campaign returns to draft with its distributions cleared — nothing is left half-published.

​
Publishing a gift-card campaign

Gift cards skip the on-chain steps. On publish, Rewards picks the winners, assigns each one a code, encrypts the codes, and flips the campaign to active in a single step. Codes are stored in plaintext only while the campaign is a draft (so you can still edit them); once published they are encrypted at rest and only the winning wallet can reveal its own.
Every campaign is checked against a value cap at publish — a safety limit (default $500 of estimated token or gift-card value) that a campaign cannot exceed. This is enforced server-side and cannot be bypassed from the dashboard, the API, or the MCP.

​
Gift-card codes

Paste your codes one per line when building the campaign. Each line is CODE, with up to three optional comma-separated fields:
CODE, tierLabel, tierValue, shareCount — the tier label and value are shown to the winner and used to order tiers (highest-value codes go to the top-ranked winners); shareCount is only used when one code is shared by several winners. Up to 5000 codes per campaign. A gift-card campaign can hand out codes three ways:
  • Unique — one distinct code per winner. The number of winners is capped by how many codes you provide.
  • Single shared code — one promo code delivered to the whole cohort.
  • Shared groups — several codes, each shared by a fixed number of winners (shareCount).

​
Claiming

Once a campaign is active, wallets claim through your own UI or a Rewards claim page:
  • Token — the wallet fetches its merkle proof and submits it to the contract. Two public endpoints support this: /rewards/proof and /rewards/claim-status.
  • Gift card — the winner signs a message to reveal their code. Codes are never exposed without a valid signature from the winning wallet.
To list what a wallet is eligible for and what it has already claimed, call GET /rewards with an address.

​
Cancelling

Cancelling a campaign sets it to cancelled. For a token campaign the deposited funds are refunded to the sender wallet; for a gift card it simply stops new reveals. A campaign that has been claimed against cannot be deleted — cancel it instead.