Invites
Per-venue invite codes tied to a member's open take — how a venue turns them on, what invite-only does to writes, the mutual follow on redeem, and the sdk calls for making, listing and redeeming codes.
A member of your venue hands out a code tied to one of their open takes; whoever redeems it joins
the venue, and Connect remembers who invited whom. Invites are off until the venue turns them on, and
invite-only sign-up is a separate switch on top. The contract lives in
packages/wire/src/invites.ts; this page is what a venue builder needs from it.
The model
- A code belongs to one venue. It is made on the venue the member is signed in to and redeems only
there. A code from another venue reads as
not-found, never “wrong venue” — saying which venue a code belongs to would let anyone probe codes across venues. - A code is tied to a take. Making one needs an open take by the inviter on this venue (a post with a stance, on a market that has not settled). The landing page shows that take, so the invitee sees the call before they see the sign-up.
- The referrer is kept, for good. A membership made by redeeming records the inviter.
- The follow is mutual and automatic. Redeeming makes the invitee follow the inviter and the inviter follow the invitee. Sending the invite is the inviter’s consent to that follow.
- An unredeemed code comes back. After
ttlDaysit readsreturnedand its slot is free again.
Codes are 10 characters from a lowercase alphabet with no look-alikes (no 0/o, 1/l/i), because they
get read aloud and typed from screenshots. The sdk trims and lowercases what the user typed.
Turning invites on: settings.invites
Invites are part of the venue’s settings. No invites block means the venue has no invites at all
— create answers invites-off. The owner (or the venue’s deploy key) writes it with the rest of
settings through the gateway’s PATCH /admin/venue/:id/meta, which merges, so you can send only
this block.
{
"settings": {
"invites": {
"required": true,
"start": 2,
"hold": 3,
"ttlDays": 14,
"earn": ["first-landed-call", "take-streak-2w"],
"seeds": { "0xabc…": { "start": 5, "hold": 5, "earnEvery": 1 } }
}
}
}
| Field | Default | What it does |
|---|---|---|
required |
false |
Invite-only sign-up: a non-member’s social writes are refused until they redeem (below). |
start |
0 |
Invites every member starts with, before anything is earned. 0–50. |
hold |
3 |
The most a member can hold unsent at once. Earned invites above this wait. 0–50. |
ttlDays |
14 |
Days before an unredeemed code returns to its sender. 1–365. |
earn |
[] |
Rules that earn more invites (below). Counted by Connect, never asserted by the venue. |
seeds |
— | Per-person overrides, keyed by lowercase wallet. At most 200. |
Earn rules count only takes on this venue:
first-landed-call— one invite, once: the member’s first take here whose side won. CLOB markets have no settled results yet, so a CLOB take never earns this one.take-streak-2w— one invite for every two consecutive ISO weeks (UTC, Monday start) with a take. The weeks are spent: four weeks in a row earn two, three earn one.
Seeds hand a named person more invites or a faster streak. Each field replaces the venue’s for that
person (earnEvery is the streak length in weeks, 1–8; the venue’s is 2). A seed applies to the
account owning the wallet, so a second wallet neither escapes nor doubles it; two seeded wallets of
one account take the more generous value of each field. Seeds name people, so the public settings read
(client.venues.settings(id)) never returns them.
What a member can send right now is start + everything earned − codes still open or already used,
capped at hold.
Changes take up to a minute to reach every write: the api memoises each venue’s rules per isolate for 60 seconds.
What invite-only does to writes
With required: true, a signed-in non-member’s social writes on your venue fail with 403 and
reason: 'invite-required' — every social write made through the venue, such as takes, comments, follows
and making invites. Reads are never gated. Four writes stay open so a newcomer can get in and
protect themselves: signing in (/v1/social/me), redeeming, block and unblock.
Who counts as a member:
- anyone who redeemed a code here (
via: 'invite'); - anyone already active on the venue before it went invite-only — a take or a follow made through
it. They are members without a code (
via: 'existing'), recorded the first time the gate orinvites.mine()sees them.
Agent accounts are not gated and cannot redeem.
If the api cannot read the venue’s settings (a gateway outage), the write gate does not guess open: a
venue that has ever issued a code stays invite-only for accounts not already recorded as members (one
active before the switch still gets through), and a venue that never has stays open. The other invite
calls see no rules during an outage: mine() answers membership.required: false and member only
for accounts already recorded, and create answers 409 invites-off. Treat invites-off on a
venue you know has invites as transient — retry rather than hiding the invite button for good.
Handle the 403 by showing the invite door, not an error. reason: 'invite-required' is the only
signal you need; check membership from invites.mine() to decide up front.
The sdk: client.social.invites
Everything but lookup acts on the venue the session is signed in to, and needs a session.
// Make a code on one of your open takes.
const invite = await client.social.invites.create() // your newest open take here
const onTake = await client.social.invites.create(post.postId) // a specific open take of yours
// → { code, venueId, postId, state: 'open', createdAt, expiresAt, redeemedBy: null, redeemedAt: null }
// Your standing and your codes on this venue.
const mine = await client.social.invites.mine()
// → { membership, held, hold, start, earned: [{ rule, count }], sent: Invite[] }
// Public, no session: what an invite landing page shows.
const look = await client.social.invites.lookup(code)
// → { code, venueId, inviter: { wallet }, postId, rolled, state, expiresAt }
// Spend a code. Returns the new membership.
const membership = await client.social.invites.redeem(code)
// → { venueId, member, required, via, invitedBy, joinedAt }
Refusals come back as { error, reason }:
| Call | Status | reason |
|---|---|---|
create |
409 | invites-off (settings.invites is missing, or could not be read just now), no-invites-left, no-open-take, not-your-take (the postId is not your open take here) |
redeem |
404 | not-found (no such code on this venue) |
redeem |
409 | used, own-invite |
redeem |
410 | returned (expired) |
lookup |
404 | not-found |
a gated write (any social write except sign-in, redeem, block and unblock) |
403 | invite-required |
Details worth building around:
- Redeeming while already a member spends nothing and returns the existing membership, so a double-tap or a member opening someone’s link is harmless.
lookuppicks the take to show.postIdis the invite’s own take while its market is open; once it settles, the inviter’s newest open take on the venue (rolled: true); if they have none,nulland your landing page picks a question itself.lookupis not cached, becausestateflips the moment someone redeems.mine().heldis what the Invite button may offer now;holdis the cap, so “2 of 3” isheldofhold.sentis the newest 100, each with itsstateand, once used, the joiner’s wallet inredeemedBy.membership.memberagrees with the gate. On an invite-only venue,mine()makes an account that was active before the switch a member before answering, so you can trust it to hide the invite door from your regulars. (Before api69e8fa2, 20 Oct 2026, it readfalsefor them until their first write.)- Two taps on Invite at once cannot both spend the last one: the allowance check and the insert run in one locked transaction.
Not built yet
There is no react hook and no venue-kit component for invites yet. Use the sdk calls above
(useConnect().social.invites under your provider) and wire the 403 into your own composer.