Rewards
How value is defined, earned, held, converted and paid out on Tanitar, and which API routes drive each part.
The rewards domain is where everything your players earn ends up: currency balances, badges,
medals and trophies, cash prizes and, when you enable it, on-chain tokens. It is one service
(REWARD_API_URL), scoped to your tenant, and every route on this page is called with an API key.
The building blocks
| Concept | What it is | Guide |
|---|---|---|
| Currency | A unit of value you define and publish, such as red or gems | Currencies |
| Wallet and ledger | A player's balances, one wallet per scope, every change a balanced ledger entry | Wallets |
| Grant | The settled record of value delivered to a player, applied or rejected, exactly once | Grants |
| Award | A badge, medal, trophy, prize, achievement, organization badge or a kind you define, optionally carrying currency | Award kinds and awards |
| Exchange | A player converting one currency into another: Red to Blue, or Red to and from a testnet token | Exchanges |
| Payout | A cash prize paid from your own Stripe Connect account to a player's connected account | Payouts |
flowchart LR G[Gamification: missions, chests, battle pass] -->|grant request| S[Grant spine] T[Tournament completion] -->|placements| A[Awards] I[Your integration] -->|award grant| A A -->|award value| S S -->|one balanced ledger effect| W[Player wallets] W --> X[Exchanges] A -->|prize| P[Payouts to Stripe Connect] A -->|testnet mint| F[On-chain fulfillment]
Value never reaches a wallet by a side door. Missions, chests, battle-pass tiers and awards all settle through the same grant spine, which writes one balanced ledger effect and one outcome, and never pays the same grant twice.
Scopes
Every rewards route takes one of two scopes:
| Scope | Grants |
|---|---|
rewards:read | Every GET on this section, including KPI, search and the Web3 capability and verification reads |
rewards:mutate | Every write: currencies, award kinds and definitions, award grants, wallet postings, exchange and payout actions, fulfillment requests |
Every write requires an Idempotency-Key header, except POST /v1/web3/deployments/verifications,
which is safe to repeat. See Idempotency.
Route map
| Area | Routes |
|---|---|
| Currencies | GET /v1/currencies, POST /v1/currencies, POST /v1/currencies/:currencyKey/publish, POST /v1/currencies/:currencyKey/archive |
| Wallets | GET /v1/wallets/:playerId, POST /v1/wallet-value/post |
| Grants | GET /v1/reward-grants/:playerId |
| Award kinds | GET /v1/award-kinds, POST /v1/award-kinds, PATCH /v1/award-kinds/:awardKindKey, POST /v1/award-kinds/:awardKindKey/publish, POST /v1/award-kinds/:awardKindKey/archive |
| Award definitions | GET /v1/awards/definitions, GET /v1/awards/definitions/:awardKey, POST /v1/awards/definitions, PATCH /v1/awards/definitions/:awardKey, POST /v1/awards/definitions/:awardKey/publish, POST /v1/awards/definitions/:awardKey/retire, GET /v1/awards/trigger-policy |
| Awards | GET /v1/awards, GET /v1/awards/:awardId, POST /v1/awards/grants, POST /v1/awards/:awardId/recipient, POST /v1/awards/tournaments/:tournamentId/settle |
| On-chain fulfillment | GET /v1/web3/capabilities, GET /v1/awards/:awardId/fulfillments, POST /v1/awards/:awardId/fulfillments, GET /v1/awards/:awardId/mint-records, POST /v1/awards/:awardId/mint-records |
| Exchanges | GET /v1/exchanges, GET /v1/exchanges/:exchangeId, POST /v1/exchanges/:exchangeId/reconcile, POST /v1/exchanges/:exchangeId/release |
| Payouts | GET /v1/payouts/capabilities, GET /v1/payouts, POST /v1/awards/:awardId/payouts, GET /v1/awards/:awardId/payouts, POST /v1/payouts/:payoutId/reconcile |
| KPI and search | GET /v1/kpi/summary, GET /v1/kpi/trends, GET /v1/search |
Web3 verification has its own guide: Web3 verification.
KPI and search
The KPI routes summarise your tenant's exchanges, mints and on-chain fulfillments over a time window.
GET /v1/kpi/summaryreturns totals for the window: exchanges by kind and by status, the whole Red credited by settled deposits (redIn) and debited by settled internal exchanges and payouts (redOut), mint count, and fulfillments by status. Red volumes are decimal strings, so they never lose precision.GET /v1/kpi/trendsreturns the same counts in buckets.
Both take from and to as ISO 8601 timestamps (UTC). A missing to is now; a missing from is
thirty days before to. The window may not be inverted or longer than 366 days. trends also takes
granularity: day (default), week or month. Anything else is refused with
400 KPI_QUERY_INVALID before any data is read.
curl "$REWARD_API_URL/v1/kpi/summary?from=2026-09-01T00:00:00Z&to=2026-09-30T23:59:59Z" \
-H "Authorization: Bearer $TANITAR_API_KEY"GET /v1/search is a closed search over your award definitions and awards:
| Parameter | Rule |
|---|---|
q | Required, 1 to 64 characters after trimming, matched literally |
category | all (default), definitions or awards |
playerId | Optional; narrows the search to one player |
limit | 1 to 50, default 20 |
An invalid query is refused with 400 SEARCH_QUERY_INVALID. Neither KPI nor search returns
another tenant's data or any internal record identifier.
What your players see
Players reach their own rewards through the Player surface with their player context, never with
your API key: their wallets (GET /player/v1/wallets), settled grants (GET /player/v1/reward-grants),
awards and the badge they equip, their exchanges and payouts, the chains available to them, and a
self-scoped search. See Player identity.
Events
Settlements are published as events you can receive by webhook: reward.grant-applied,
reward.award-granted, reward.wallet.balance-changed, reward.exchange-settled and
reward.payout-settled. Their payloads are in the event catalog.