# Referral links > Share a LayerHop link with ?r=, record who referred each swap with the `referrer` quote parameter, and read a wallet's referred orders and volume from GET /v1/referrals/{address}. Source: https://docs.layerhop.com/guides/referrals A LayerHop referral link is any LayerHop link with `?r=` added, for example `https://app.layerhop.com/?r=0x2222…`. The referrer is the sharer's own wallet, so there is nothing to register. Swaps made by people who arrive through the link are recorded as referred by that wallet, and anyone can read the totals from `GET /v1/referrals/{address}`. > [!NOTE] > Referral rewards aren't switched on yet. Referrals are recorded (attribution only); they never change the fee or the price a user gets. `rewardBps` is `0` and `estimatedRewardsUsd` stays `0` until a reward rate is set. ## How does a referral link work? 1. Someone opens a LayerHop page with `?r=` (an EVM `0x` address or a Solana address). 2. The web app stores that wallet in the browser for **30 days**. The first valid link wins; later links don't replace it until it expires. Invalid values are ignored. 3. While it is stored, every quote the swap app requests carries `referrer=`. The partner [widget](/guides/embed-widget) never sends one: its swaps belong to the partner that embedded it. 4. The order built from that quote (`POST /v1/orders`) records the referrer. Your own swaps don't count: a `referrer` equal to the quote's `sender` or `recipient` is ignored, and orders whose sender or recipient is the referrer never count towards stats or the leaderboard. Get your link in the app under **Referrals** (connect a wallet; with both an EVM and a Solana wallet connected you get one link per wallet), or build it yourself: ```text https://app.layerhop.com/?r=0x2222222222222222222222222222222222222222 ``` ## How do I attribute a referral through the API? Pass `referrer` on `GET /v1/quote` (or in the `POST /v1/quote` body). It is optional and never an error: an invalid value or a referrer equal to `sender` or `recipient` is ignored, and the quote is the same with or without it. ```bash curl "https://api.layerhop.com/v1/quote?srcChain=base&srcToken=USDC&amount=100000000&dstChain=solana&dstToken=SOL&sender=0x1111111111111111111111111111111111111111&recipient=9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM&referrer=0x2222222222222222222222222222222222222222" ``` With the TypeScript SDK: ```ts const q = await layerhop.quote({ ...params, referrer: "0x2222222222222222222222222222222222222222" }); ``` EVM referrers are stored lowercased. The referrer is attached to each `quoteId` in the response, and recorded when you build the order with `POST /v1/orders`. > [!TIP] > `referrer` is not the same as `integrator`. `integrator` selects a registered [partner fee](/guides/partner-fees); `referrer` only records which wallet sent the user, and adds no fee. ## How do I read a wallet's referral stats? `GET /v1/referrals/{address}` is public and read-only (no key; the usual per-IP rate limit applies): ```bash curl https://api.layerhop.com/v1/referrals/0x2222222222222222222222222222222222222222 ``` ```json { "address": "0x2222222222222222222222222222222222222222", "referredOrders": 12, "filledOrders": 9, "referredVolumeUsd": 4210.55, "rewardBps": 0, "estimatedRewardsUsd": 0 } ``` | Field | Meaning | |---|---| | `referredOrders` | Live orders built with this referrer (test-mode orders are excluded) | | `filledOrders` | The filled ones | | `referredVolumeUsd` | Filled volume in USD: each order's input value at fill when it was recorded (see [Trade history](/guides/trade-history#how-is-the-usd-value-at-fill-recorded)), otherwise at the **current** price of its source token. Only listed tokens count (LayerHop's curated list, or verified / popular on a provider list); unlisted tokens and tokens without a price count as $0. Rounded to cents | | `rewardBps` | The referral reward rate, in bps of filled volume. `0` = rewards off | | `estimatedRewardsUsd` | `referredVolumeUsd × rewardBps / 10000`; `0` while `rewardBps` is `0`. An estimate, not a balance | The answer may be cached for up to 30 seconds. An address that is not an EVM or Solana wallet returns `INVALID_PARAMS`. A self-hosted API without a database answers zeros. ## Is there a leaderboard? `GET /v1/referrals/leaderboard` ranks the top 50 referring wallets by referred filled volume in USD. It is public and read-only, and the app's **Referrals** page shows it with your own rank. ```bash curl "https://api.layerhop.com/v1/referrals/leaderboard?window=30d&address=0x2222222222222222222222222222222222222222" ``` ```json { "window": "30d", "updatedAt": "2026-10-25T12:00:00.000Z", "entries": [ { "rank": 1, "referrer": "0x12…abcd", "filledOrders": 14, "referredVolumeUsd": 5230.4 }, { "rank": 2, "referrer": "0x22…2222", "filledOrders": 9, "referredVolumeUsd": 4210.55 } ], "you": { "rank": 2, "filledOrders": 9, "referredVolumeUsd": 4210.55 } } ``` - `window`: `7d`, `30d` or `all` (default), by when the order was created. Live, filled orders only. - Volume counts each order at its USD value at fill where recorded, otherwise at the source token's current price, as in the stats above. Only listed tokens add volume (an order in an unlisted token counts as a filled order with $0), and self-referred orders (referrer = sender or recipient) are left out. Ties rank by filled orders. - Addresses are truncated by the server (first and last 4 characters). Pass `address` to get that wallet's own rank in `you` (`null` when it isn't ranked in the window). - Cached for 5 minutes (`updatedAt`). An invalid `window` or `address` is `INVALID_PARAMS`. The leaderboard is a ranking only: rewards are off and nothing is paid for a rank.