Help Center

Everything you need to get started and earn karma.

What Is KarmaRace?

KarmaRace is a task exchange community for developers. You post tasks for others to complete — like starring or forking your GitHub repository — and in return you complete tasks for others. Everyone earns karma, and karma determines how visible your tasks are in the feed. The more active you are, the more visibility you earn.

Getting Started

  1. Link your accounts. Go to Accounts and connect GitHub (required for GitHub tasks) and Discord (optional, for community access).
  2. Create a task. Go to My Tasks and create your first task. Choose a GitHub repo to star or fork, or set up a Webhook task (Pro only).
  3. Publish it. Hit Publish to make your task visible in the feed. Tasks start hidden until you publish them.
  4. Complete tasks for others. Browse the feed, pick a task, and hit Check. Verification is automatic — your karma goes up on confirmation.

The Feed and Karma

The feed shows tasks from other users, ranked by owner karma balance — then by the owner's custom task order — then by creation time. Owners with higher karma have more visible tasks, which means more completions and continued growth. You never see your own tasks in the feed.

Karma is the engine of the platform. When you complete a task, you earn karma and the task owner pays karma. The reward you earn is computed from the owner's current karma at the moment you pick the task: higher-karma owners pay more. This keeps the economy fair and dynamic.

Use the filters to narrow the feed by completion status, archive status, or task type (GitHub Star, GitHub Fork, Webhook).

Reciprocity and Obligations

Reciprocity is always on. When someone completes a task for you, a reverse obligation is created: you owe them a completion of the same task type. Obligations are an incentive, not a penalty.

Obligation bonus. When you complete a task that settles an open obligation, you earn a higher karma reward — equivalent to what you would have earned from the top task in the free feed at that moment. This compensates for your opportunity cost and makes settling obligations genuinely worthwhile. The task owner still pays only the normal computed cost.

Feed restriction. If you have open obligations and a matching task is available in the feed, the feed is focused on that task until it's settled. If no matching task exists, the feed falls back to normal. This keeps the community balanced without hard-blocking your activity.

You can see which obligation the current feed task would settle directly in the feed interface.

Task Visibility and Karma Balance

Your tasks are ranked in other users' feeds based on your current karma balance. When your karma is low, your tasks appear lower in the feed and receive fewer completions. If your balance drops below your configured threshold, you'll receive a KARMA_LOW notification. You'll be notified again with KARMA_RESTORED when your balance recovers.

Tasks can be in one of three states: hidden (not visible in the feed, either because you haven't published yet or the system unpublished due to health failures), published (visible and active), or deleted (soft-deleted, removed from all views). Unpublishing a task hides it immediately; republishing resets its health counters.

Task Types and Verification

  • GitHub Star — target format owner/repo. Verified against the tester's linked GitHub account.
  • GitHub Fork — target format owner/repo. Verified against the tester's linked GitHub account.
  • Webhook — target is a full URL. Pro-only. Verified by your endpoint's JSON response (see below).

For GitHub tasks, the repo is selected from a dropdown of discovered repositories. Use Reload repos if a recently created repo isn't showing up yet.

Webhook Contract

When a webhook task is checked, KarmaRace sends a POST request to your endpoint:

POST {your_webhook_url}
Content-Type: application/json
Authorization: Bearer {task.webhook_secret}

{
  "task_slug": "your-task-slug",
  "google_email": "tester@gmail.com"
}

google_email is the Google-verified address the tester selected — the email they registered with on your platform. The tester picks from their verified emails in Accounts before submitting the check. The Authorization header confirms the request came from KarmaRace.

Your endpoint must respond with:

{ "verified": true }

If verification fails, the tester sees a generic error. You receive detailed diagnostics in Notifications.

Task Health

GitHub tasks are health-checked periodically. If the repo becomes private or is deleted, the failure streak increments. After two consecutive failures the task is auto-unpublished and you're notified.

Webhook tasks are health-checked based on all recorded verification attempts. When the failure ratio exceeds 50% after at least 5 checks, the task is auto-unpublished and you're notified. Republishing resets the health counters, so fixing your endpoint and republishing is all it takes to recover.

Notification Events

Notification events are always available in-app. Pro users can additionally enable webhook and Discord delivery per event.

  • TASK_CONFIRMED — {"task_id": number, "delta": number}
  • TASK_HEALTH_FAILED — {"task_id": number, "task_type": string, "target_id": string}
  • WEBHOOK_CHECK — {"task_id": number, "phase": string, "status": string, ...}
  • KARMA_LOW / KARMA_RESTORED — {"delta": number, "balance": number, "threshold": number}
  • APPRECIATION — {"message": string}

Linked Accounts

Go to Accounts to connect GitHub and Discord. OAuth tokens are used for verification. If checks start failing due to a token issue, disconnect and reconnect the provider. On Discord link, KarmaRace joins your account to the configured guild, assigns your role, and syncs your nickname to your app username.

Why Did My Publish Fail?

  • Webhook tasks require a Pro account.
  • GitHub repository is private or has been deleted.
  • Webhook URL is not a valid http:// or https:// address.

Pro Plan

Pro removes ads, unlocks Webhook tasks, and enables webhook and Discord notification delivery controls. See the billing page for details.