Currencies
Define the currencies your tenant uses, publish them so value can move in them, and archive them when you retire them.
Every amount on Tanitar is denominated in a currency from your tenant's currency registry. Nothing is pre-loaded: a mission reward, an award's value, a shop price, a rename price or a wallet posting can only name a currency you have created and published.
Lifecycle
flowchart LR D[draft] -->|publish| P[published] P -->|archive| A[archived]
| State | Meaning |
|---|---|
draft | Created, not yet usable. No value can move in it. |
published | Live. Grants, postings, prices and exchanges may name it. |
archived | Retired. No new value can move in it. Existing balances stay readable. |
Transitions go one way: only a draft can be published and only a published currency can be
archived. Anything else is refused with 409.
Create a currency
POST /v1/currencies with scope rewards:mutate.
| Field | Rule |
|---|---|
currencyKey | Lowercase slug (^[a-z0-9]+(-[a-z0-9]+)*$), unique in your tenant, never changes |
displayName | The label you show players |
scope | platform (held in the player's platform wallet) or game (held per game) |
precision | Integer from 0 to 9 |
curl -X POST "$REWARD_API_URL/v1/currencies" \
-H "Authorization: Bearer $TANITAR_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"currencyKey":"red","displayName":"Red coins","scope":"platform","precision":0}'The response is the new entry with status: "draft" and revision: 1. A key that already exists
is refused with 409.
Amounts on the ledger are always integers. precision tells your own interface where to place the
decimal point; Tanitar never stores fractional amounts.
Publish and archive
curl -X POST "$REWARD_API_URL/v1/currencies/red/publish" \
-H "Authorization: Bearer $TANITAR_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"POST /v1/currencies/:currencyKey/publish makes the currency usable;
POST /v1/currencies/:currencyKey/archive retires it. Each transition increments the entry's
revision and the registry's revision. An unknown key is refused with 404 CURRENCY_UNAVAILABLE.
Read the registry
GET /v1/currencies (scope rewards:read) returns every entry in every state, sorted by key, with
the registry revision:
{
"revision": 3,
"entries": [
{ "currencyKey": "red", "displayName": "Red coins", "scope": "platform", "precision": 0, "status": "published", "revision": 2 }
]
}The registry revision rises on every create and transition, so you can cache the list and refresh
it only when the number moves. The list is not paginated.
Where a currency must be published
Each of these checks the registry at the moment it is used and refuses a currency that is not
published:
- a wallet posting or a grant (a grant for an unpublished currency settles as
rejectedwithGRANT_CURRENCY_UNAVAILABLE, see Grants); - an award definition's
value; - a mission's currency reward, see Gamification catalog;
- a shop listing price, see Listings;
- the player rename price, see Membership tiers and rename pricing.
The internal Red and Blue exchange moves value in the currency keys red and blue, so publish
both if your players will convert between them. See Exchanges.