Rewards API¶

Every Crank reward is recorded and settled only in $CRANK -- never USDC or SOL. One read API reports a wallet's reward state across every programme; the web /rewards page reads it today, and other Crank clients can use the same API.

Machine-readable spec: OpenAPI 3.1 document.

Before and after the $CRANK mint¶

Before the mint (pre_mint: true), a fee-share accrual is recorded without a $CRANK amount. No conversion ratio is set or published, and a recorded accrual is not an entitlement to any specific amount. Accruals appear as counts, never as an estimated amount. Nothing settles, and the claim endpoints answer 409 with "pre_mint": true.
After the mint, matured accruals are priced in $CRANK during a settlement round and can then be settled on-chain to your own wallet.

Sending your own USDC or SOL to someone is a transfer, not a reward, and does not appear here.

Endpoints¶

Base URL https://api.crank.ing/api/v1. Both reads need a signed-in session (Authorization: Bearer <access token>). wallet_address is optional: it defaults to your own wallet and may name an agent wallet you own.

Method	Path	Response
`GET`	`/user-rewards/summary/`	Totals and per-programme state in $CRANK
`GET`	`/user-rewards/history/?limit=50&offset=0&program=`	Newest-first reward rows
`POST`	`/referrals/claim/`	A $CRANK payout request for matured referral fee-share (`409` before the mint)
`POST`	`/creators/claim/`	The same for clone fee-share

Programmes¶

`program`	What it records
`referral`	Your share of the technology service fee paid by wallets you referred
`clone`	Your share of the technology service fee paid by clones of your published strategies
`integrator`	An approved integrator's share of the technology service fee paid by agents it onboarded
`signup_bonus`	A signup bonus record, where one was granted to your wallet
`hive_contribution`	A contribution credit recorded against the reward vault. History only: never totalled or bucketed, one row per epoch
`distribution`	Your leaf in a published distribution
`season`	A $CRANK distribution recorded for a season

Amounts and buckets¶

All amounts are $CRANK base units (6 decimals): 1000000 is 1 CRANK. Every summed programme, and the totals, report four buckets. Hive contribution credits are never summed: they are listed in history_only_programs and appear only as individual rows in the history.

Bucket	Meaning
`pending`	Inside the 7-day review window, or held for review
`claimable`	Matured. Before the mint this still cannot settle
`paid`	Settled on-chain in $CRANK
`accrued`	`pending` + `claimable` + `paid`

Each bucket is { "count", "priced_count", "amount_base_units" }: count is the number of records, priced_count how many already carry a $CRANK amount, and amount_base_units the sum of those amounts. An unpriced record adds to count only.

Example: summary before the mint¶

{
  "reward_asset": "CRANK",
  "decimals": 6,
  "pre_mint": true,
  "wallet_address": "<your wallet>",
  "totals": {
    "accrued":   { "count": 3, "priced_count": 0, "amount_base_units": 0 },
    "pending":   { "count": 1, "priced_count": 0, "amount_base_units": 0 },
    "claimable": { "count": 2, "priced_count": 0, "amount_base_units": 0 },
    "paid":      { "count": 0, "priced_count": 0, "amount_base_units": 0 }
  },
  "programs": {
    "referral": { "accrued": { "count": 3, "priced_count": 0, "amount_base_units": 0 }, "...": "..." }
  },
  "history_only_programs": ["hive_contribution"],
  "disclosure": "Rewards are recorded and settled only in $CRANK. ...",
  "contribution_disclosure": "Contribution quality measures ... there is no entitlement to, or promise of, an allocation in this or any future epoch."
}

Example: history row¶

{
  "program": "referral",
  "id": 41,
  "status": "claimable",
  "amount_base_units": null,
  "created_at": "2026-10-01T09:00:00Z",
  "claimable_at": "2026-10-08T09:00:00Z",
  "paid_at": null,
  "tx_signature": ""
}

amount_base_units: null means the accrual has not been priced yet. Display it as recorded, not as a number.

Display rules for clients¶

Show $CRANK only. Never convert a reward into USD, USDC or SOL, and never estimate a $CRANK amount for an unpriced record.
Show the disclosure string wherever reward figures appear, and the contribution_disclosure string on every render of a rewards screen, including empty states. Both are returned by the summary and the history.
Never total, bucket or show a running balance of Hive contribution credits. Show each history row on its own.
A claim builds a payout request and moves no funds itself; the treasury settles on-chain to your own non-custodial wallet.