> ## Documentation Index
> Fetch the complete documentation index at: https://docs.darkbloom.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Darkbloom referral program: share and earn

> Create a personal referral code, share it with others, and track your referral activity. Manage everything via the Darkbloom API or web console.

Darkbloom has a referral program that lets you generate a personal referral code and share it with others. When someone uses your code during their first deposit, both parties may receive a benefit. You can manage and track your referrals entirely through the API. This page shows the three steps: registering a code, applying a code, and checking your stats.

## Step 1 — Register a referral code

To create a referral code for your account, call `POST /v1/referral/register`. This requires authentication.

```bash theme={null}
curl -X POST https://api.darkbloom.dev/v1/referral/register \
  -H "Authorization: Bearer $DARKBLOOM_API_KEY" \
  -H "Content-Type: application/json"
```

The response returns your referral code, which you can share with others.

## Step 2 — Apply a referral code

When someone else is making a deposit and has a referral code, they can apply it at checkout time. Pass the code in the `referral_code` field when creating a Stripe checkout session:

```bash theme={null}
curl -X POST https://api.darkbloom.dev/v1/billing/stripe/create-session \
  -H "Authorization: Bearer $DARKBLOOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": "10.00",
    "referral_code": "YOURCODE"
  }'
```

Alternatively, you can apply a code directly via `POST /v1/referral/apply`:

```bash theme={null}
curl -X POST https://api.darkbloom.dev/v1/referral/apply \
  -H "Authorization: Bearer $DARKBLOOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "referral_code": "YOURCODE"
  }'
```

<Note>
  Referral codes are validated before the checkout session is created. If the code is invalid, the request will return a `400` error and no checkout session will be started.
</Note>

## Step 3 — Check referral stats

To see how many people have used your code and any associated activity, call `GET /v1/referral/stats`:

```bash theme={null}
curl https://api.darkbloom.dev/v1/referral/stats \
  -H "Authorization: Bearer $DARKBLOOM_API_KEY"
```

## Endpoint summary

| Method | Endpoint                | Description                             |
| ------ | ----------------------- | --------------------------------------- |
| `POST` | `/v1/referral/register` | Create a referral code for your account |
| `POST` | `/v1/referral/apply`    | Apply a referral code to your account   |
| `GET`  | `/v1/referral/stats`    | View referral activity and stats        |

All three endpoints require a valid API key or Privy session.