Verification policy

Every tracking page has a verification policy — the owner-configured rules that gate visitor submissions. The policy controls three things:

  1. Whether submitters must hold the page's token (the CA holding gate).
  2. How pending submissions get approved (the approval mode).
  3. How many submissions can sit in the pending queue before new ones are rejected (the queue cap).

Owners edit the policy in the dashboard under Settings → Embed API → Verification policy. Defaults ship with the tracking page and apply until the owner changes them.

The CA holding gate

Owners can require submitters to hold a minimum balance of a given token mint. When the gate is enabled, the server fetches the submitter's balance for the gated mint (the page's own token by default, or an owner-specified override) and checks it against the configured minimum. If the balance is below the minimum, the submission fails with 422 ca_gate_failed and the response includes the observed balance and minimum.

Balance fetches are cached briefly to absorb repeated attempts without hammering Solana RPC on every request.

Owners typically use this to require visitors to hold a minimum amount of the project's token, which in turn filters out throwaway-wallet spam. Setting the minimum to zero still records the balance on the submission without gating it.

Approval modes

Every submission starts life as pending unless the policy says otherwise. The approval mode decides what happens next.

strict

Every submission is pending until the owner manually approves or rejects it in the dashboard. Trusted pubkeys get no special treatment. Use this when the wallet list is sensitive and needs review every time.

trust_ladder (default)

Starts like strict — submissions queue for manual review. After an owner has approved a given pubkey enough times (configurable per page), that pubkey is promoted to trusted, and all future submissions from it auto-approve instantly.

This is the recommended mode for communities: early submissions get human review, repeat contributors get fast-path throughput. See Trust ladder for details including manual trust/revoke.

auto

Every submission that clears the CA gate auto-approves with no human review. The only filter is the holding-gate and signature check. Use this only when you trust the audience (e.g. a token-gated community with a meaningful minimum balance).

Pending queue cap

Each page has a configurable cap on how many submissions can sit in the pending queue at once. If the cap is reached, new submissions are rejected with 429 queue_full and a Retry-After header. The count decrements when the owner approves or rejects existing entries.

This protects owners from firehose spam: if your approval backlog is already huge, new submissions wait. Raise the cap only if you know you can keep up with review.

Duplicate handling

Before any policy evaluation, the server checks whether this wallet already has a pending, approved, or auto_approved submission on this page. If so, it returns 409 duplicate. Resubmitting a wallet that was previously rejected is allowed (but subject to the per-wallet cooldown — see Cooldowns and rate limits).

Changing policy on a live page

Policy changes take effect immediately. The next submission evaluates against the new values. Existing pending submissions are untouched — you don't retroactively re-gate previously-written records.

Related