Referral rewards API

The referral rewards API returns the signed-in account's accrued, claimable, pending, and paid rewards. A claim credits available rewards to that account's Launchpad trading balance.

Rewards are paid through an account claim. nextPayoutAt on the trading-referrals summary is null because no automatic payout is scheduled.

Both endpoints require a customer bearer token. Read and trade API keys do not authorize them. Use the signed-in product session; a trade-key signature is not required for this flow.

Read the current balance#

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $SUPANOVA_SESSION_TOKEN" \
  'https://launch-api.supanova.app/api/v1/me/referral-rewards'

Amounts are decimal strings or null when unknown. Preserve null in the interface rather than displaying zero. Only enable claiming when claimAvailable is true; a positive accrued amount alone does not establish availability.

Claim available rewards#

Create a UUID for one logical claim and persist it before sending the request. Save this body as claim.json, replacing the placeholder with that UUID:

{
  "claimId": "<a-new-UUID-for-this-claim>"
}

curl --fail-with-body --silent --show-error \
  'https://launch-api.supanova.app/api/v1/me/referral-rewards/claims' \
  -H "Authorization: Bearer $SUPANOVA_SESSION_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @claim.json

The account must have accepted the current product terms. This endpoint identifies a repeated claim through claimId in the body; it does not use the order API's Idempotency-Key header.

A successful response has status: "paid", creditedCc, receiptIds, epoch, updateId, and asOfOffset. Use creditedCc as the amount paid by this claim, then refresh rewards and the trading balance. Do not assume the pre-request claimable amount is the final credited amount.

Retry the same claim#

A completed claim result is retained for replay for 24 hours. Within that period, a repeat with the same claimId normally returns the original result. Reuse the ID after a timeout or an in-progress response; generating a new ID does not help reconcile the first request.

If a payout was credited but its cached response could not be saved, the same ID can remain in progress for up to 120 seconds. A later retry recalculates only rewards still owed. Refresh the account's rewards and balance instead of interpreting a timeout as a failed payment.

The route permits 10 claim requests per minute in addition to other applicable session and IP limits. Respect HTTP 429 and Retry-After, and avoid polling the claim endpoint to read a balance.

Handle unavailable claims#

unavailableReason can identify indexing, suspension, or another temporary or account-specific restriction. Do not infer an automatic payout schedule from an unavailable claim. The reward view and claim response are the authoritative states for this integration.