Rewards Grant a reward

Grant a reward

Submit an exact net token allocation from your trusted backend.

Use rewards.issue() to record a reward for activity your application has already qualified. You supply the existing destination wallet and exact token quantity; Slices does not calculate or purchase the reward.

Endpoint#

http

POST /v1/rewards
Authorization: Bearer <your-server-api-key>
Idempotency-Key: referral_0182
Content-Type: application/json

Request body#

json

{
  "campaignId": "cmp_pilot001",
  "recipient": {
    "walletAddress": "0x0000000000000000000000000000000000001001"
  },
  "amountBaseUnits": "1000000",
  "event": {
    "id": "referral_0182",
    "type": "referral.qualified"
  }
}

Field	Required	Description
`campaignId`	Yes	Approved campaign ID; 1–96 letters, digits, underscores, or hyphens.
`recipient.walletAddress`	Yes	Structurally valid, nonzero EVM address. Incorrect mixed-case checksums are rejected.
`amountBaseUnits`	Unless a rule applies	Exact positive integer string, within uint256 and campaign limits. This is the recipient's net entitlement. Optional when the campaign has a rule for `event.type`; required otherwise.
`event.id`	Yes	Stable, case-sensitive event reference; 1–128 characters. Do not include personal information.
`event.type`	Yes	Case-sensitive reporting label; 1–64 letters, digits, underscores, periods, colons, or hyphens.

Idempotency-Key is a required header of 8–128 characters using letters, digits, periods, underscores, colons, or hyphens. It is not a field in the HTTP JSON body.

Campaign rules and the amount#

A campaign can carry rules, one per event.type, each naming the reward for one event of that type and, optionally, the most one wallet can earn from that event type (campaign.rules, see Campaign object). When the campaign has a rule for the request's event.type, amountBaseUnits may be left out and the rule's amount is used; a request that does carry amountBaseUnits always uses its own amount, checked against the same limits. A request without an amount for an event type that has no rule is 400 INVALID_REQUEST. A reward that would take a wallet past the rule's per-wallet cap, or past the campaign's maximum grant, is 422 GRANT_LIMIT_EXCEEDED; the SDK's events.track() is this call without an amount.

The request schema is strict. Do not add user, email, metadata, activity, verified, value_usd, chainId, or token overrides. The campaign fixes the asset and network.

TypeScript#

const reward = await slices.rewards.issue({
  campaignId: "cmp_pilot001",
  recipient: {
    walletAddress: "0x0000000000000000000000000000000000001001",
  },
  amountBaseUnits: "1000000",
  event: { id: "referral_0182", type: "referral.qualified" },
  idempotencyKey: "referral_0182",
});

console.log(reward.id, reward.status);

Initialize slices as shown in Install. The SDK moves idempotencyKey into the request header and returns the reward resource without the HTTP envelope.

HTTP example#

Save the request above as issue-request.json, then run it only against the approved environment:

bash

curl --silent --show-error --include \
  --request POST "$SLICES_BASE_URL/v1/rewards" \
  --header "Authorization: Bearer $SLICES_API_KEY" \
  --header "Idempotency-Key: referral_0182" \
  --header "Content-Type: application/json" \
  --data-binary @issue-request.json

Response#

The first successful acceptance returns 201 Created:

json

{
  "data": {
    "id": "rwd_demo0001",
    "campaignId": "cmp_pilot001",
    "recipient": {
      "walletAddress": "0x0000000000000000000000000000000000001001",
      "verificationStatus": "unverified",
      "verificationUrl": "http://localhost:3000/verify/vrf_demo0001"
    },
    "asset": {
      "chainId": 31337,
      "tokenAddress": "0x0000000000000000000000000000000000002001",
      "symbol": "TST",
      "decimals": 6
    },
    "amountBaseUnits": "1000000",
    "event": {
      "id": "referral_0182",
      "type": "referral.qualified"
    },
    "source": "partner_attested",
    "status": "accepted",
    "statusReason": null,
    "payoutCampaignId": null,
    "deliveredAmountBaseUnits": "0",
    "deliveryEvidence": null,
    "createdAt": "2026-09-11T12:00:00Z",
    "updatedAt": "2026-09-11T12:00:00Z"
  }
}

All addresses, IDs, amounts, and timestamps in this example are synthetic. TST on chain 31337 is a local test profile, not an available production asset.

Acceptance means the instruction and its capacity reservation were stored durably. It does not mean your operator approved anything or that a wallet sent anything: the grant is queued for approval once the recipient has verified their wallet.

Retries and duplicate events#

The same key and semantic request return 200 OK, the current reward resource, and Idempotency-Replayed: true. No new reward or capacity movement is created.

The same key with changed content returns 409 IDEMPOTENCY_CONFLICT. Reusing the same campaign/event-type/event-ID tuple under another key returns 409 DUPLICATE_EVENT. Changing the key is not a valid way to retry an uncertain request.

Limits and immutable fields#

Amounts must be canonical strings such as "1000000", not JSON numbers or decimal token values. The per-grant maximum and remaining issuance capacity are checked atomically. See Token amounts.

An accepted reward's recipient, amount, asset, and event are not editable. Cancellation is available only before the operator's approval. An unknown delivery outcome is a reconciliation problem, not permission to issue again.

Related: Idempotency, Reward states, and Errors.