Eligibility

A Pair Market is a token plus a financial Pair. The token is an open Solana asset. The Pair Instrument behind it may come with terms set by its issuer or provider: a tokenized fund that is not offered to U.S. persons, a municipal exposure offered only in the Americas, an instrument that requires provider verification of the holder.

PairStreet attaches those requirements to the instrument, not to the token or to the creator. Every Pair Market that pairs with an instrument inherits its rules. When an instrument’s rules change, every market paired with it follows the same rules from the next request.

The Eligibility EngineEligibility EngineEvaluates a viewer's region and verification state against a Pair Instrument's rules and returns allow or restrict before any Pair interaction. is a pure function, evaluateEligibility, in src/lib/eligibility.ts. It takes the instrument’s rules and the viewer’s country and returns a verdict. It has no I/O and no state, which makes it identical in every call site and straightforward to test.

Each rule is a row in instrument_eligibility: the instrument it belongs to, the rule type, a list of countries, a list of regions and an optional note shown to the viewer.

// src/lib/eligibility.ts
export type EligibilityRule = {
  rule: "allow_countries" | "block_countries" | "allow_regions" | "block_regions" | "kyc_required" | "accredited_only";
  countries: string[];
  regions: string[];
  note?: string | null;
};

export type EligibilityVerdict =
  | { eligible: true }
  | { eligible: false; code: "REGION_RESTRICTED" | "UNKNOWN_REGION" | "KYC_REQUIRED"; reason: string };

/**
 * Pure eligibility evaluation. Infrastructure, not branding: the UI only ever
 * renders "Pair unavailable in your region" and blocks the transaction.
 *
 * `strictUnknown`: in production an unknown viewer country cannot interact with
 * instruments that carry geographic rules.
 */
export function evaluateEligibility(
  rules: EligibilityRule[],
  country: string | null,
  opts: { strictUnknown: boolean } = { strictUnknown: false },
): EligibilityVerdict;

Countries map to regions through a fixed table in src/lib/domain.ts (for example US and BR to americas, DE and GB to europe, JP to asia). The regions are americas, europe, asia, middle_east, africa and global.

Rules in the catalog

Most instruments carry no rules. These carry rules in the current catalog:

The verdict is deterministic. The server evaluates in this order and returns at the first restriction:

1. Step 01INSTRUMENT_UNAVAILABLE
   Instrument status

   Before any rule is read, the instrument must be active. A paused, coming_soon, provider_unavailable or deprecated instrument returns INSTRUMENT_UNAVAILABLE with a reason such as “This Pair is paused.”

2. Step 02
   Split the rules

   Rules are divided into geographic rules (allow and block, by country or region) and verification rules (kyc_required, accredited_only).

3. Step 03UNKNOWN_REGION
   Unknown country

   If the instrument has geographic rules and the viewer’s country is unknown, production returns UNKNOWN_REGION (“We could not determine your region for this Pair.”). The development network treats the viewer as eligible so the rest of the flow can be exercised.

4. Step 04REGION_RESTRICTED
   Geographic rules

   The country is upper-cased and mapped to its region. Each geographic rule is checked in order. The first rule that fails returns REGION_RESTRICTED, with the rule’s note as the reason, or “Pair unavailable in your region.” when the rule has no note.

5. Step 05KYC_REQUIRED
   Verification rules

   If any kyc_required or accredited_only rule exists, the verdict is KYC_REQUIRED, with its note or “This Pair requires provider verification.”

6. Step 06
   Allow

   No rule restricted the viewer. The verdict is { eligible: true }.

An instrument with no rules is open to every viewer, including viewers whose country is unknown. An instrument with only verification rules does not need the viewer’s country. These cases are covered by the engine’s tests, along with country blocks, region allow-lists and the strict and lenient handling of unknown countries.

The same verdict type is exposed by every provider through checkEligibility, so a provider can add its own checks on top of the instrument’s rules. See Provider Interface.

The viewer’s country is resolved on the server from the edge. On Vercel that is the x-vercel-ip-country header; cf-ipcountry and x-country-code are accepted as fallbacks for other edges. The value must be a two-letter code, otherwise the country is treated as unknown. The browser never supplies the country in production.

// src/server/request-context.ts
export async function getViewerCountry(): Promise<string | null> {
  if (isDevMode()) {
    const c = (await cookies()).get(DEV_COUNTRY_COOKIE)?.value?.toUpperCase();
    if (c && COUNTRIES[c]) return c;
  }
  const h = await headers();
  const v = (h.get("x-vercel-ip-country") ?? h.get("cf-ipcountry") ?? h.get("x-country-code"))?.toUpperCase() ?? null;
  return v && /^[A-Z]{2}$/.test(v) ? v : null;
}

GET /api/region returns the resolved country. On the development network a cookie override, set through POST /api/region, lets engineers exercise each regional rule from the dev toolbar. In production that endpoint answers 403 and the override is ignored.

strictUnknown in production

Every production call site passes strictUnknown when PAIRSTREET_MODE is production. A viewer whose country the edge could not determine is treated as restricted for any instrument that has geographic rules. An unknown location never satisfies an allow-list, and it never slips past a block-list.

Eligibility is computed on the server for each request and returned with the data the page renders. The transaction-building paths enforce it before anything is built or written.

• ·Instrument catalog and Pair pages: /pairs, /pair/[slug], GET /api/instruments and GET /api/instruments/[slug] return a verdict for every instrument.
• ·Token pages and portfolio: each Pair Market shows its instrument’s verdict, and each reward line in the portfolio carries one.
• ·Launch: the launch service evaluates the chosen instrument before preparing transactions. A restricted viewer receives HTTP 403 with code PAIR_UNAVAILABLE_IN_REGION and no transaction is built. Covered by an integration test.
• ·Claims: POST /api/rewards/claim evaluates every instrument in the request before any row is written. Covered by an integration test.

What a restricted viewer can do

Allocations themselves are computed without reference to location. A restriction gates the claim, not the allocation. See the claim flow.

Verification rules are part of the model today. Their verdict is KYC_REQUIRED until a provider’s verification flow is connected for that instrument, at which point the provider’s checkEligibility confirms the holder. Instruments and their providers are described in Pair Instruments and Providers.