POST /referrals/create

Create a referral code + payout wallet. Each user can have at most one code. The code activates 24h after creation.

Singleton per user. Use /referrals/wallet to change the payout address without rotating the code.

Use case

First-time opt-in for an end-user who wants to earn from referees — generate a code they can share.

Body

Field	Type	Required	Description
sReferralAddress	string	yes	Solana pubkey that will receive referral payouts. Any address; does not need to be user-owned.

Response 201

{
  "sReferralCode": "ABCDEF",
  "sReferralAddress": "…",
  "nReferralPercentage": 10,
  "bIsActive": false,
  "dActivatesAt": "2026-04-21T10:00:00.000Z",
  "message": "referral code created — it will activate in 24h"
}

Errors

Status	Meaning
409	User already has a code. Use PATCH /referrals/wallet to update the payout.

Example

curl -X POST "$BASE_URL/referrals/create" \
  -H "Authorization: Bearer $ACCESS" \
  -H "x-user-id: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{ "sReferralAddress": "…" }'