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 ttlDays it reads returned and 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 or invites.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.
  • lookup picks the take to show. postId is 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, null and your landing page picks a question itself. lookup is not cached, because state flips the moment someone redeems.
  • mine().held is what the Invite button may offer now; hold is the cap, so “2 of 3” is held of hold. sent is the newest 100, each with its state and, once used, the joiner’s wallet in redeemedBy.
  • membership.member agrees 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 api 69e8fa2, 20 Oct 2026, it read false for 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.