API reference List rewards

List rewards

Filter project-scoped rewards and traverse results with opaque cursors.

List the rewards accessible to the current key. Use this operation for reporting, periodic status refresh, or recovery when your application knows the event but has not stored the reward ID.

Endpoint#

http

GET /v1/rewards
Authorization: Bearer <your-server-api-key>

Query parameters#

Parameter	Type	Required	Meaning
`campaignId`	Resource ID	No	Limit results to one accessible campaign.
`walletAddress`	EVM address	No	Filter by the reward's recipient wallet.
`eventId`	String, 1–128 characters	No	Filter by the exact, case-sensitive event ID.
`status`	Reward status	No	One of `accepted`, `queued`, `approved`, `sent`, `delivered`, `failed`, `cancelled`.
`limit`	Integer, 1–100	No	Page size; default `50`.
`cursor`	Opaque string, 1–2048 characters	No	The previous response's non-null `nextCursor`.

Filters combine to narrow the result. The contract does not include eventType, payoutCampaignId, updatedSince, free-text search, offset, sort order, or an array of statuses as query parameters.

TypeScript#

const page = await slices.rewards.list({
  campaignId: "cmp_pilot001",
  eventId: "referral_0182",
  limit: 50,
});

for (const reward of page.data) {
  console.log(reward.id, reward.event.type, reward.status);
}

HTTP#

bash

curl --silent --show-error --get "$SLICES_BASE_URL/v1/rewards" \
  --header "Authorization: Bearer $SLICES_API_KEY" \
  --data-urlencode "campaignId=$SLICES_CAMPAIGN_ID" \
  --data-urlencode "eventId=referral_0182" \
  --data-urlencode "limit=50"

Response#

200 OK:

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"
    }
  ],
  "nextCursor": null
}

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.

The data elements use the full Reward object. An empty matching result is {data: [], nextCursor: null}. Do not interpret an HTTP error as that empty response.

Cursor pagination#

The API uses stable (createdAt, id) ordering with opaque, scoped cursors. Pass the returned cursor back unchanged with the same project, environment, and filters. Stop when nextCursor is null.

Do not decode, construct, or reuse a cursor for a different filter set. The API does not return a total count or promise a point-in-time snapshot of all matching records.

Because reward states can change while you traverse pages, a status-filtered list is not a guaranteed event stream. Keep the reward IDs your own integration issued and refresh those records for authoritative follow-up. Periodic list scans are useful for recovery, not a substitute for your durable issuance records.

Event recovery#

Event uniqueness includes both event.type and event.id within a campaign. A query by eventId can therefore match more than one intended event type. Compare the type, recipient, amount, and campaign before linking a result to your business record.

Related: Get a reward, Track rewards, and Rate limits and retries.