---
title: "POST /api/v1/referrals/redeem"
method: POST
path: "/api/v1/referrals/redeem"
tags: ["Referrals"]
---

# POST /api/v1/referrals/redeem

`POST /api/v1/referrals/redeem`

Redeems a referral code for an account. Validates the code in ClickHouse,
then submits an `admin_create_new_subaccount` transaction on-chain to create
the user's subaccount (bypassing invite-only gating).

Referral tracking (code → user → referrer) stays entirely off-chain in ClickHouse.
Fee discounts and on-chain referral relationships will be bulk-registered post-TGE.

After successful on-chain tx, writes a record to `referral_redemptions` in ClickHouse
to track usage_count for code exhaustion.

This handler is **idempotent**: retrying the same (account, code) pair returns 200.
Retrying with a *different* code returns 409.

**Graceful degradation**: if ClickHouse writes fail after on-chain tx success,
the handler still returns 200 (the tx is the source of truth). Failed CH writes
are logged with `RECONCILE_NEEDED` prefix for manual follow-up.

## Request body

- RedeemReferralRequestDto — Request body for POST /api/v1/referrals/redeem
  - `account` string, required — The wallet address redeeming the code (not a subaccount address)
  - `referral_code` string, required — The referral code to redeem

## Response `200`

Referral code redeemed

- RedeemReferralResponseDto — Response for POST /api/v1/referrals/redeem
  - `account` string, required — The wallet address that redeemed the code (not a subaccount address)
  - `referral_code` string, required — The referral code that was redeemed

## Other responses

- `400` — Invalid account or referral code format
- `404` — Referral code not found
- `409` — Already redeemed or code inactive
- `500` — Internal server error
- `501` — Referral redemption not enabled

---

[API](https://skmtc.net/decibel/apis/decibel-trading-api.md) · [All operations](https://skmtc.net/decibel/apis/decibel-trading-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/decibel/decibel-trading-api/revisions/37a02083ff59/schema)