Karma API
Award and deduct karma, query an avatar's karma breakdown, and retrieve global leaderboards. Karma is the OASIS reputation layer — it gates features, unlocks achievements, and drives OApp economies.
Karma Types
Each karma award is tagged with a KarmaTypePositive or KarmaTypeNegative enum value so OApps can track domain-specific reputation separately from the total.
| Type | Direction | Description |
|---|---|---|
JoinedOASIS | Positive | Awarded once on first login |
JoinedOAPP | Positive | First time an avatar joins an OApp |
PlayedGame | Positive | Awarded per game session by the OApp |
CompletedQuest | Positive | Awarded when a quest is completed |
CompletedMission | Positive | Awarded when a mission is completed |
GiftedKarma | Positive | Karma gifted from one avatar to another |
SpreadingLove | Positive | Social positive actions |
HelpingPeople | Positive | Cooperative in-game behaviour |
CreatedOAPP | Positive | OApp developer reward |
NegativeKarmaActivity | Negative | Generic negative action |
Hacking | Negative | Detected exploit or cheat |
Stealing | Negative | Unauthorised asset transfer |
Award Karma
Awards karma to an avatar. Requires a valid JWT. OApps should call this on significant positive player actions.
Request body
| Field | Type | Description |
|---|---|---|
avatarIdrequired | guid | Target avatar ID |
karmaTyperequired | string | KarmaTypePositive enum value |
karmaSourceTyperequired | string | Which OApp or system is awarding (e.g. OAPP, Quest) |
karamSourceTitle | string | Human-readable label for the award event |
karmaSourceDesc | string | Extended description shown in karma history |
await oasis.karma.addKarmaToAvatar({ avatarId: avatar.id, karmaType: 'CompletedQuest', karmaSourceType: 'Quest', karamSourceTitle: 'The Lost Cavern', karmaSourceDesc: 'Completed the introductory quest chain' });
Remove Karma
Deducts karma. Same body shape as Award but uses KarmaTypeNegative enum values for karmaType.
Get Karma for Avatar
Returns the full karma history and total for the given avatar ID.
Response result
| Field | Type | Description |
|---|---|---|
karmaTotal | number | Summed karma across all sources |
karmaAkashicRecords | array | Full karma event history, newest first |
Leaderboard
Filter avatars by karma threshold — useful for building leaderboards or gating OApp features behind reputation levels.
Award karma on game events that matter — quest completions, cooperation, creative contributions. Avoid awarding for trivial actions or players will game it. See Karma System concepts for design guidance.