Reward

Mounts the rewards rules engine (github.com/hanzoai/reward) at /v1/reward, with the admin queue at /v1/admin/reward, and feeds it what really happened.

Also for this capability: API · CLI · SDKs

Mounts the rewards rules engine (github.com/hanzoai/reward) at /v1/reward, with the admin queue at /v1/admin/reward, and feeds it what really happened.

All API references → · Get started →

Base URL	`https://api.hanzo.ai`
Operations	17
Auth	`Authorization: Bearer $HANZO_API_KEY`

Specification

Specification pending — no HIP in hanzoai/hips declares capability: reward yet. What this capability serves is below, from the API document; what it is — the store it owns, how it meters, what it publishes — is written as a HIP under HIP-0139.

Four surfaces

Surface	Reaches this capability as	Coverage
REST	`reward` at its own prefix	17 operations
CLI	`hanzo reward …`	17 of 17
SDK	—	no published client declares one yet — regenerating the clients is what adds them
MCP	tool `reward` on `https://api.hanzo.ai/v1/mcp`	7 operations, 0 under the document's own id — ask `describe` for the rest

Quickstart

export HANZO_API_KEY=sk-...   # console.hanzo.ai → API keys

Then the first call — a read that needs nothing but the key. GET /v1/reward/me, operation get_reward_me:

CLI

SDK

HTTP

MCP

hanzo reward me get

.ts

.py

.go

.rs

.java

import { Configuration, RewardApi } from 'hanzoai';

const api = new RewardApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getRewardMe();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import RewardApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = RewardApi(client).get_reward_me()

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.RewardAPI.GetRewardMe(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, reward_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = reward_api::get_reward_me(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.RewardApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new RewardApi(client).getRewardMe();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

curl https://api.hanzo.ai/v1/reward/me \
  -H "Authorization: Bearer $HANZO_API_KEY"

MCP reaches reward through the reward tool, which names its 7 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_reward_me_posts"
         }
       }
     }'

Endpoints

Endpoint	What it does
`GET /v1/reward/badge/{handle}`	The README badge of a person's level, as an SVG
`GET /v1/reward/catalog`	The events, pillars, levels and rule operators the program is built from
`POST /v1/reward/events`	State one event to the rules engine (the platform only)
`GET /v1/reward/health`	Whether the rewards program can answer
`GET /v1/reward/me/claims`	Your claims, and where each stands
`GET /v1/reward/me/explore`	What you could earn next, by pillar
`POST /v1/reward/me/github/badge`	Verifies against GitHub's API that a project of yours carries a Hanzo badge image in its README, and puts one claim to staff for each kind it carries: your live profile badge, your rank badge, or the Built with Hanzo badge.
`POST /v1/reward/me/github/check`	Reads the stars, follows and forks of the GitHub account you linked at sign-in, from GitHub's API, and puts to staff each that is a repository or account of ours, once each.
`POST /v1/reward/me/posts/{id}/recheck`	Looks at one of your pending or removed posts now, with the same checks as the daily look, and adds the look to its history.
`POST /v1/reward/me/posts/scan`	Reads your recent public posts on Bluesky, Mastodon, Reddit, Hacker News or DEV by the handle you give, and holds each that carries your own referral link, as pasting it would.
`GET /v1/reward/me/posts`	Lists your posts, newest first, each with its status and every look at it.
`POST /v1/reward/me/posts`	Takes the address of a post of yours, reads it from its network, and holds it for a week if it is public, is yours, and carries your own referral link.
`GET /v1/reward/me/profile`	Your rewards profile
`PUT /v1/reward/me/profile`	Set your handle, whether your profile is public, and your links
`GET /v1/reward/me`	Your level, lifetime points, redeemable points and badges
`GET /v1/reward/profile/{handle}`	A person's public rewards profile
`GET /v1/reward/rules`	Lists what the rewards program pays for: every active rule of every active program, grouped by pillar (use, share, community, contribute, expert), each with what has to happen, the points, the badge or credit it awards, how often one person can earn it and whether staff verify each claim first.

All Hanzo APIs · Interactive reference

Was this page useful?

Broken link or missing step? Drop it in #docs on Discord or open a PR.

PreviousAllowance NextMarketplace