Gate sign-in on what wallets hold
A gate in the brand on the brand itself, its apps, its Discord roles, its Telegram groups, or any mix: signing in to one of its apps, the person's wallets must meet its `rule`, or a page tells them why not (with `refusal_message` first) and the app gets `access_denied`. That holds however they signed in: someone who signed in with email or a social account and has no wallet on their account that meets it is stopped there too, and on the brand's own apps, where it offers wallets as a way in, the page lets them add the wallet that holds it. A gate belongs to one brand: `brands` may name only that brand (every app of it), and `apps`, `discord_roles` and `telegram_groups` only its apps and the servers and groups connected to it (400 at the field otherwise, naming both brands). A gate never moves to another brand: make one there instead. `rule` is a tree of `all` and `any` groups (at most 3 deep, each with 1 to 20 children, 20 conditions in all) of conditions on the wallets on the person's account in the brand: `token` (hold at least `min_amount` of a mint, every account and compressed balance of it counted), `collection` (hold at least `min_count` NFTs of a verified Core or Token Metadata collection, compressed and Core NFTs included), `nft` (hold one NFT), `allowlist` (have a wallet on a list of at most 1000 addresses a gate, never shown to anyone), `program_activity` (at least `min_count` successful transactions in the last `window_days` days that ran a program, signed by a wallet of theirs unless `role: any`) and `address_activity` (as many with an address, by who signed them: `direction` `sent`, `received` or `either`). An activity condition asks for 1 to 100 transactions in 1 to 90 days (on `solana:devnet`, at most 14, as far back as its history is read), counts each transaction once however many of the person's wallets are in it, and reads each wallet's newest 1000 successful transactions in the window at most, and as many it is in only through a compressed token account (compressed tokens and compressed NFTs count, as uncompressed ones do); its window slides, so a check that meets one says `until` when it lapses. `token`, `collection` and the activity conditions count every wallet together (`wallets: combined`, the default) or one alone (`single`). Each condition names its `chain`, which must be one this API reads (the list's `chains`) unless it is an allowlist. Synq reads every token, collection, NFT and program the rule names from the chain as it is written (400 for one that isn't what its condition says, at its path, such as `rule.root.conditions.1.collection`, or for an activity address that is a program; 503 when the chain can't be read), once nothing else in the request is wrong and from the org's own reads (`token_gate.org_reads`, as its dry runs; 429 once they're spent), and keeps their names as each condition's `display`. `schedule` is an optional window in an IANA time zone, open at one end or both, with what happens `outside` it: `let_in` (the gate doesn't apply) or `refuse` (the app is closed to everyone). A sign-in reads at most 40 conditions from the chain across every enabled gate on an app (409 `conflict` naming the app otherwise). `discord_roles` names roles in the brand's connected Discord servers (Communities): Synq's bot gives the role to people whose wallets meet the rule once they verify, and takes it back, never the person, from someone who stops qualifying once the grace period ends. Each role is read from Discord as it is added (400 at `discord_roles.0.role` when the bot can't give it, with the fix; 409 `discord_unavailable` where this API has no Discord bot). `telegram_groups` names the brand's connected Telegram groups: the bot approves join requests from people who qualify, and mutes (`on_lost: mute`, the default, supergroups only) or removes (`remove`) those who stop. A role or group follows one gate (400 naming the gate that has it). Everyone each lets in is checked again every `recheck_seconds` (6 hours by default) and keeps access `grace_seconds` (24 hours by default) after a check finds they stopped; a check that can't read the chain keeps their access. Gates are checked at every sign-in and on every refresh, where a refusal or a closed window ends the app's grant (`invalid_grant`), so access ends within one access token's life; what can't be read refuses a sign-in, and answers a refresh 503 `temporarily_unavailable` with the grant kept. What wallets hold is kept for a minute. Every check is recorded as `user.token_gate_checked`. At most 100 gates per org, across its brands. Needs `org.tokenGates.edit`, a plan with token gating (403 `plan_feature_unavailable` otherwise, naming the plan in `required_plan`) and, for a rule that reads a chain, an API that reads one (409 `token_gates_unavailable` otherwise). A gate is on once made: make it with no brands or apps for one that applies nowhere yet, and `POST …/disable` turns one off. Recorded as `token_gate.created`, in the brand.
/v1/orgs/{org}/brands/{brand}/token-gatesA gate in the brand on the brand itself, its apps, its Discord roles, its Telegram groups, or any mix: signing in to one of its apps, the person's wallets must meet its rule, or a page tells them why not (with refusal_message first) and the app gets access_denied. That holds however they signed in: someone who signed in with email or a social account and has no wallet on their account that meets it is stopped there too, and on the brand's own apps, where it offers wallets as a way in, the page lets them add the wallet that holds it. A gate belongs to one brand: brands may name only that brand (every app of it), and apps, discord_roles and telegram_groups only its apps and the servers and groups connected to it (400 at the field otherwise, naming both brands). A gate never moves to another brand: make one there instead. rule is a tree of all and any groups (at most 3 deep, each with 1 to 20 children, 20 conditions in all) of conditions on the wallets on the person's account in the brand: token (hold at least min_amount of a mint, every account and compressed balance of it counted), collection (hold at least min_count NFTs of a verified Core or Token Metadata collection, compressed and Core NFTs included), nft (hold one NFT), allowlist (have a wallet on a list of at most 1000 addresses a gate, never shown to anyone), program_activity (at least min_count successful transactions in the last window_days days that ran a program, signed by a wallet of theirs unless role: any) and address_activity (as many with an address, by who signed them: direction sent, received or either). An activity condition asks for 1 to 100 transactions in 1 to 90 days (on solana:devnet, at most 14, as far back as its history is read), counts each transaction once however many of the person's wallets are in it, and reads each wallet's newest 1000 successful transactions in the window at most, and as many it is in only through a compressed token account (compressed tokens and compressed NFTs count, as uncompressed ones do); its window slides, so a check that meets one says until when it lapses. token, collection and the activity conditions count every wallet together (wallets: combined, the default) or one alone (single). Each condition names its chain, which must be one this API reads (the list's chains) unless it is an allowlist. Synq reads every token, collection, NFT and program the rule names from the chain as it is written (400 for one that isn't what its condition says, at its path, such as rule.root.conditions.1.collection, or for an activity address that is a program; 503 when the chain can't be read), once nothing else in the request is wrong and from the org's own reads (token_gate.org_reads, as its dry runs; 429 once they're spent), and keeps their names as each condition's display. schedule is an optional window in an IANA time zone, open at one end or both, with what happens outside it: let_in (the gate doesn't apply) or refuse (the app is closed to everyone). A sign-in reads at most 40 conditions from the chain across every enabled gate on an app (409 conflict naming the app otherwise). discord_roles names roles in the brand's connected Discord servers (Communities): Synq's bot gives the role to people whose wallets meet the rule once they verify, and takes it back, never the person, from someone who stops qualifying once the grace period ends. Each role is read from Discord as it is added (400 at discord_roles.0.role when the bot can't give it, with the fix; 409 discord_unavailable where this API has no Discord bot). telegram_groups names the brand's connected Telegram groups: the bot approves join requests from people who qualify, and mutes (on_lost: mute, the default, supergroups only) or removes (remove) those who stop. A role or group follows one gate (400 naming the gate that has it). Everyone each lets in is checked again every recheck_seconds (6 hours by default) and keeps access grace_seconds (24 hours by default) after a check finds they stopped; a check that can't read the chain keeps their access. Gates are checked at every sign-in and on every refresh, where a refusal or a closed window ends the app's grant (invalid_grant), so access ends within one access token's life; what can't be read refuses a sign-in, and answers a refresh 503 temporarily_unavailable with the grant kept. What wallets hold is kept for a minute. Every check is recorded as user.token_gate_checked. At most 100 gates per org, across its brands. Needs org.tokenGates.edit, a plan with token gating (403 plan_feature_unavailable otherwise, naming the plan in required_plan) and, for a rule that reads a chain, an API that reads one (409 token_gates_unavailable otherwise). A gate is on once made: make it with no brands or apps for one that applies nowhere yet, and POST …/disable turns one off. Recorded as token_gate.created, in the brand.
Authorization
bearer An org API key (sk_live_…, sk_test_…), or an access token from the Synq issuer (the synq brand, on the accounts host) for this API.
In: header
Path Parameters
The org's id
^org_[0-9a-hjkmnp-tv-z]{26}$The brand's id
^brd_[0-9a-hjkmnp-tv-z]{26}$Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://api.synq.build/v1/orgs/org_01h455vb4pex5vsknk084sn02q/brands/brd_01h455vb4pex5vsknk084sn02q/token-gates" \ -H "Authorization: Bearer $SYNQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme", "rule": { "version": 1, "root": { "type": "all", "conditions": [ { "type": "token", "chain": "solana:mainnet", "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "min_amount": "1000", "wallets": "combined", "label": "USDC", "display": { "name": "Acme", "symbol": "string", "decimals": 0, "image": "string" } } ] } }, "schedule": { "timezone": "America/New_York", "all_day": false, "starts": "2026-10-10T09:00", "ends": "2026-10-10T17:00", "outside": "refuse" }, "refusal_message": "Acme Club is for holders of the Acme pass. Get one at acme.example/pass.", "brands": [ "string" ], "apps": [ "string" ], "discord_roles": [ { "server": "dsv_01h455vb4pex5vsknk084sn02q", "role": "1187390245566001234", "grace_seconds": 86400, "recheck_seconds": 21600, "existing_members": "verify" } ], "telegram_groups": [ { "group": "tgg_01h455vb4pex5vsknk084sn02q", "on_lost": "mute", "grace_seconds": 86400, "recheck_seconds": 21600, "existing_members": "verify" } ] }'{ "id": "tkg_01h455vb4pex5vsknk084sn02q", "brand": "brd_01h455vb4pex5vsknk084sn02q", "name": "Acme holders", "enabled": true, "rule": { "version": 1, "root": { "type": "all", "conditions": [ { "type": "token", "chain": "solana:mainnet", "mint": "string", "min_amount": "string", "wallets": "combined", "label": "USDC", "display": { "name": "Acme", "symbol": "string", "decimals": 0, "image": "string" } } ] } }, "schedule": { "timezone": "string", "all_day": true, "starts": "string", "ends": "string", "outside": "let_in", "starts_at": "2026-10-21T12:00:00.000Z", "ends_at": "2026-10-21T12:00:00.000Z", "state": "in_effect" }, "refusal_message": "string", "summary": "All of: At least 1,000 USDC; One of (At least 3 NFTs from Mad Lads; The NFT Mad Lad #42)", "brands": [ "brd_01h455vb4pex5vsknk084sn02q" ], "apps": [ "app_01h455vb4pex5vsknk084sn02q" ], "discord_roles": [ { "server": "string", "server_name": "Mollyverse", "role": "string", "role_name": "MDP Holder", "grace_seconds": 0, "recheck_seconds": 0, "existing_members": "verify", "adopt_by": "2026-10-21T12:00:00.000Z", "adoption": { "state": "none", "verify_by": "2026-10-21T12:00:00.000Z", "counted": 0, "unverified": 0, "member_listing": "full", "problem": "members_intent", "problem_detail": "string" } } ], "telegram_groups": [ { "group": "string", "title": "RODAI Holders", "on_lost": "mute", "grace_seconds": 0, "recheck_seconds": 0, "existing_members": "verify", "adopt_by": "2026-10-21T12:00:00.000Z", "adoption": { "state": "none", "verify_by": "2026-10-21T12:00:00.000Z", "counted": 0, "unverified": 0, "member_listing": "full", "problem": "members_intent", "problem_detail": "string" } } ], "created_at": "2026-10-21T12:00:00.000Z", "updated_at": "2026-10-21T12:00:00.000Z"}Enable a token gate POST
Turns a token gate on, with its rule, schedule and targets as they are: the next sign-in or refresh at an app it applies to checks it. Its rule's chains are checked again (400), and a rule that reads a chain needs an API that reads one (409 `token_gates_unavailable`). Needs `org.tokenGates.edit` and a plan with token gating (403 `plan_feature_unavailable`). Recorded as `token_gate.updated`.
Test a token gate or a draft rule POST
Checks a gate (`gate`), or a rule not saved yet (`rule`, with an optional `schedule`), against wallets (`wallets`, at most 10 addresses) or a user's wallets in a brand (`user` and `brand`), as a sign-in would, at `at` (an ISO time, for the window and the end of every activity condition's days; now when left out), with what was read in the last minute unless `fresh`. Answers what each condition came to, how many reads it cost, and the refusal page's words for it, worded by what the gate does (`goal`: its saved targets, or `brands`, `apps`, `discord_roles` and `telegram_groups` as given). A draft is read from the chain as saving it would read it (400 at the path of what isn't what its condition says, 503 when the chain can't say), so it is tested as the gate it would be. Saves nothing. Wants the org's plan to have token gating (`auth.token_gating`, 403 `plan_feature_unavailable` otherwise), since every test may read the chain through Synq's own key. Needs `org.tokenGates.view`, and `org.users.view` to test a user, which is recorded as `user.token_gate_dry_run` (a test against addresses reads only public chain data, and isn't). Limited per org (`token_gate.dry_runs`), and reads the chain from the org's own budget (`token_gate.org_reads`), never a brand's sign-ins'. Kept for callers of the org's own routes from before gates belonged to a brand: `/v1/orgs/{org}/brands/{brand}/token-gates` does the same within one brand.