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

# Referral program

> Referred users save 10% on BRDG's platform fee. Referrers earn points on their referrals' volume, three levels deep.

Every BRDG account can claim a referral link. A user who signs in through it pays 10% less platform fee on every transfer from then on, and the owner of the link earns 1 point for each dollar those transfers move, plus a share of what the users they refer go on to refer.

## Referral links

A link is `https://brdg.now/ref/<code>`, for example `https://brdg.now/ref/alice`. Anyone signed in to [brdg.now](https://brdg.now/ref) with a wallet can claim one code for their account, on the referrals page.

Codes are not case-sensitive and follow these rules:

| Rule | |
| - | - |
| Length | 3 to 15 characters |
| Characters | Letters, numbers and hyphens (`-`), no spaces |
| Hyphens | Not first, not last, never two in a row |
| Reserved | Words such as `brdg`, `admin`, `support`, `fees` and `free` cannot be claimed |

An account holds one live code, and a code belongs to one account for good. Its owner can change it, at most 5 codes per account in total. A code changed away from is retired, not freed: nobody else can ever claim it, and an old link keeps referring users to the same account. Points and the users already referred stay with the account.

## How a user is referred

**1. Open the link**

BRDG remembers the code in that browser for 12 hours.

**2. Sign in**

Signing in with a wallet within those 12 hours ties the account to the referrer. A user who is already signed in when they open the link is tied at once.

A signed-in user who arrived without a link can type a code on the [referrals page](https://brdg.now/ref) instead. It asks for confirmation first, because the choice is permanent.

* **Only future volume counts.** Transfers made before the user was referred never count.
* **It is permanent.** The first referrer is kept; a later link does not replace it.
* **No self-referral.** An account cannot be referred by its own code, and a transfer that sends from, delivers to or refunds to a wallet of the code's owner pays the full fee and earns no points.
* **Links are one-way.** If you referred someone, they can never be your referrer, and a code whose owner you referred pays the full fee on your transfers. Longer loops are allowed: A can refer B, B refer C and C refer A. Nobody earns points on their own transfers, at any level.

## The discount

A referred user pays 10% less platform fee, in whole basis points, rounded down in the user's favour:

| Platform fee | With a referral |
| - | - |
| None | None |
| 5 bps | 4 bps |
| 10 bps | 9 bps |
| 15 bps | 13 bps |

Only BRDG's own [platform fee](https://docs.brdg.now/concepts/fees.md) is discounted. Venue fees, gas, the Hyperliquid relayer charge and any [integrator share](https://docs.brdg.now/concepts/referrals.md) are charged in full. The \$10 cap still applies.

The quote shows the fee that is charged, and what it would have been without the code:

```json theme={null}
"fees": {
  "platform": {
    "bps": 4,
    "amountAtomic": "40000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "tierSavedBps": 55,
    "discount": { "code": "alice", "pct": 10, "fullBps": 5, "fullAmountAtomic": "50000" }
  },
  "referral": null
}
```

`discount` is `null` when no code applied, and when there is no platform fee to discount. Every `feeBps`, `feeAmountAtomic` and `amountOutAtomic` in the quote is already discounted, and the build charges exactly the quoted fee. To show the saving, strike through `fullAmountAtomic` and show `amountAtomic` beside it.

## Points and the leaderboard

Points come from referral volume: transfers that reach `COMPLETED` or `PARTIAL`, counted at three levels:

| Level | Whose transfers | Each \$1 counts |
| - | - | - |
| 1 | Users you referred | \$1 |
| 2 | Users they referred | \$0.10 |
| 3 | One level further | \$0.01 |

You earn 1 point per whole dollar of referral volume. It is summed across the three levels first, then rounded down once: level 1 transfers of \$250.40 and \$99.80 make \$350.20 and 350 points.

A refers B, B refers C, and C refers D. When D bridges \$1,000, C gets \$1,000 of referral volume and 1,000 points, B \$100 and 100, and A \$10 and 10. A level with nobody on it stays empty: the next referrer up never takes its place.

* **Only volume after a link exists counts.** Each transfer's levels are fixed when it is quoted. A link made later never adds volume for earlier transfers.
* **API volume counts the same.** A transfer quoted through the API with a code, or by a referred user, counts at every level exactly like one made on brdg.now.

Points belong to the account, so they carry over when the code changes.

[`GET /referrals/leaderboard`](https://docs.brdg.now/api-reference/referrals/leaderboard) ranks codes by points, then by which code was claimed first. It returns the top 25 by default and up to 100, and is refreshed about every 30 seconds. `volumeUsd` is the code's referral volume and `points` its whole dollars; `wallets` is the number of distinct wallets referred directly.

## For integrators

If your users arrive with a BRDG referral code, send it as `referralCode` on [`POST /bridge/quote`](https://docs.brdg.now/api-reference/quote/quote) or [`POST /fastfill/quote`](https://docs.brdg.now/api-reference/fastfill/quote). The build takes it from the quote, so there is no build field.

Each transfer is attributed once, at quote time, in this order:

1. If the `sender` wallet is already locked to a referrer, that referrer gets it. The code on the request is ignored.
2. Otherwise, a user signed in to BRDG, or the BRDG account that owns `sender`, keeps their referrer if they have one. The code is ignored.
3. Otherwise the transfer is credited to the code's owner, unless `sender`, `recipient` or the refund address belongs to that owner.
4. A malformed or unknown code is ignored. The quote still succeeds, with the full fee.

**A wallet locks on its first completed transfer.** When a wallet with no BRDG account completes a transfer it signed itself with a code, through a venue whose signed transaction is unique to the order (Relay, Mayan, Rhino and Eco today), it is tied to that referrer for good. From then on its transfers go to that referrer whatever code you send, and if the user later signs in on brdg.now, their account inherits it. Quotes never lock a wallet: only a transaction the wallet signed and completed does.

`referralCode` is separate from `referralWallet` and `referralBps`, which pay your own share as an integrator. Send either, both or neither. See [Referrals](https://docs.brdg.now/concepts/referrals.md).

To check a code before you store it, call [`GET /referrals/{code}`](https://docs.brdg.now/api-reference/referrals/resolve). It answers `200`, with `{ "valid": true, "code": "alice" }` or `{ "valid": false, "reason": "not_found" }` (`reason` is `invalid` or `not_found`). It allows 60 lookups a minute per IP address and answers `429` past that.

## Script

This script checks a code, quotes with it, and prints the discount and the leaderboard. It uses the [TypeScript project](https://docs.brdg.now/guides/typescript-setup.md); save it as `src/referrals.ts` and run `npx tsx src/referrals.ts alice`.

```typescript src/referrals.ts theme={null}
import { createClient } from '@kernlog/brdg-sdk';

const brdg = createClient();

async function main(code: string) {
  // 1. Check the code
  const resolved = await brdg.resolveReferral(code);
  if (!resolved.valid) throw new Error(`referral code ${code}: ${resolved.reason}`);

  // 2. Quote with it
  const quote = await brdg.getQuote({
    fromChain: 'base',
    toChain: 'solana',
    fromToken: 'USDC',
    toToken: 'USDC',
    amountAtomic: '100000000',
    sender: '0xUserWallet',
    recipient: 'UserSolanaWallet',
    referralCode: resolved.code,
  });

  // 3. The platform fee, with what it would have been without the code
  const platform = quote.fees.platform;
  if (platform?.discount) console.log(`fee ${platform.discount.fullAmountAtomic} -> ${platform.amountAtomic}`);

  // 4. The top 10 referrers
  const { rows } = await brdg.getReferralLeaderboard({ limit: 10 });
  for (const row of rows) console.log(`${row.rank}. ${row.code}: ${row.points}`);
}

main(process.argv[2] ?? '').catch((e) => { console.error(e); process.exit(1); });
```

The SDK checks `referralCode` against the code rules before it sends anything, and throws a `BrdgError` with the code `invalid_referral_code` for a malformed one. The API itself ignores a malformed code.

## Endpoints used

| SDK | Endpoint |
| - | - |
| `resolveReferral` | [`GET /referrals/{code}`](https://docs.brdg.now/api-reference/referrals/resolve) |
| `getQuote` | [`POST /bridge/quote`](https://docs.brdg.now/api-reference/quote/quote) |
| `getFastFillQuote` | [`POST /fastfill/quote`](https://docs.brdg.now/api-reference/fastfill/quote) |
| `getReferralLeaderboard` | [`GET /referrals/leaderboard`](https://docs.brdg.now/api-reference/referrals/leaderboard) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.