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

# Share links

> Mint a link that opens your app inside Bankroll, and credit the user who shared it under Bankroll's referral program.

`playLink()` builds the link that opens your app inside Bankroll. Pass a
`referrer` and it does a second job: whoever opens it, if they're new to
Bankroll, is attributed as that user's referral.

```ts theme={null}
import { playLink } from "@joinbankroll/sdk";

const link = playLink("https://acme.example/game", {
  referrer: session.user.wallet, // the user doing the sharing
});
// → https://joinbankroll.com/play?url=https%3A%2F%2Facme.example%2Fgame&ref=…
```

That's the whole integration. You don't run a referral program, hold a ledger,
or pay anyone — Bankroll's existing program does it, and your app gets the
player.

## What the referrer is

**The wallet of the Bankroll user sharing the link**, from a verified
[session](/build/session). Not a referral code: codes are the `XXX-XXX` shape
built for a person to read aloud or type into a box, and there's no person in
this loop. Your app already holds the wallet, and it's the canonical user id, so
there's nothing extra to fetch.

## Who can be credited

Bankroll's referral program is **person to person**. The referrer has to be a
real Bankroll user's wallet, so:

* Your app's **treasury address doesn't work**. It's a keypair your app
  generated; no Bankroll account stands behind it, so it's attributed to nobody
  and the link still opens normally.
* An **unrecognized or malformed** `referrer` costs the attribution, never the
  link. There's no error to handle — the app opens either way.
* **Self-referral is refused**, and a user can be referred at most once, ever.

## The program, in numbers

|                      |                                                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| New user             | attributed at signup; referred at most once                                                                               |
| Qualifies by         | \$30 of HSUSD play across [verified apps](/build/verified), within 30 days                                                |
| New user gets        | 1,000 points (\$10) on qualifying                                                                                         |
| Referrer gets        | 1,000 points (\$10), first 30 qualifying referrals per month                                                              |
| Your app gets        | \$10 HSUSD to your treasury per qualifying referral from your links, once [verified](/build/verified) — first 100 a month |
| Paid and notified by | Bankroll — both sides get a push                                                                                          |

Play in your app counts once it's [verified](/build/verified). Terms are
stamped when the link is opened — Bankroll can change them for future
referrals, so keep amounts in one place in your copy.

## What to tell your users

> Invite a friend to Bankroll. They get $10 after their first $30 of play —
> and you get \$10 too.

<Warning>
  No reward for signing up alone, for play in unverified apps, or for a friend who
  already has an account. Unverified app? Say "play on Bankroll", not "play here".
</Warning>

## Where the link can be opened

A `/play` link works the same everywhere, which is worth knowing before you put
one in a tweet:

* **Phone, Bankroll installed** — opens your app in the host.
* **Phone, no Bankroll** — verifies a phone number, then sends them to install.
  Your link is remembered for 24 hours and they land in your app after signup —
  and that's where the referral attaches.
* **Desktop** — shows a QR that reopens the same link, referrer intact, on a
  phone.

The referrer survives every one of those hops, so a link scanned off a laptop
attributes exactly like one tapped on a phone.

## The referrer's notification

When an attribution lands, Bankroll notifies the referrer that their link was
used. The copy is Bankroll's and doesn't name your app — from their side the
news is that someone accepted their invite, and which app the friend picked
isn't yours to broadcast. There's nothing to configure and no webhook to
handle.