@insumermodel/mppx-token-gate 1.0.0

package/README.md

@@ -0,0 +1,108 @@
+# @insumermodel/mppx-token-gate
+
+Token-gate [mppx](https://github.com/wevm/mppx) routes using signed wallet attestations. One API call checks token/NFT ownership across 30 EVM chains + Solana + XRPL — no RPC management, no viem transports, no in-house balance checks.
+
+## How it works
+
+mppx embeds the payer's identity in every payment credential as a DID string (`credential.source: "did:pkh:eip155:8453:0xABC..."`). `tokenGate` reads that address, calls [InsumerAPI](https://insumermodel.com) to check on-chain ownership, and short-circuits the payment flow for holders.
+
+1. Request arrives with a payment credential
+2. `tokenGate` extracts the payer address from `credential.source`
+3. [InsumerAPI](https://insumermodel.com/developers/api-reference/) checks ownership and returns an ECDSA P-256 signed result
+4. **Token holder** → free receipt returned (`reference: "token-gate:free:{attestationId}"`)
+5. **Non-holder** → delegates to the original `verify` (normal payment proceeds)
+
+The attestation signature is verifiable offline via [JWKS](https://insumermodel.com/.well-known/jwks.json) — downstream services can independently verify the gate decision.
+
+## Install
+
+```bash
+npm install @insumermodel/mppx-token-gate
+```
+
+## Usage
+
+```ts
+import { Mppx, tempo } from 'mppx/server'
+import { tokenGate } from '@insumermodel/mppx-token-gate'
+
+const tempoCharge = tempo({
+  currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+  recipient: '0xYourAddress',
+})
+
+const gatedCharge = tokenGate(tempoCharge, {
+  apiKey: process.env.INSUMER_API_KEY,
+  conditions: [{
+    type: 'nft_ownership',
+    contractAddress: '0xYourNFT',
+    chainId: 8453,        // Base
+  }],
+})
+
+const mppx = Mppx.create({ methods: [gatedCharge] })
+```
+
+Works with any framework (Hono, Express, Elysia, Next.js) and any payment method (tempo, stripe) — it wraps `Method.Server`, so no middleware changes needed.
+
+## API key
+
+Get a free key (instant, no signup):
+
+```bash
+curl -X POST https://api.insumermodel.com/v1/keys/create \
+  -H "Content-Type: application/json" \
+  -d '{"email":"you@example.com","appName":"my-app","tier":"free"}'
+```
+
+Or set `INSUMER_API_KEY` as an environment variable.
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | `env.INSUMER_API_KEY` | InsumerAPI key |
+| `conditions` | `TokenCondition[]` | — | Token/NFT conditions to check |
+| `matchMode` | `'any' \| 'all'` | `'any'` | Whether holder must satisfy any or all conditions |
+| `cacheTtlSeconds` | `number` | `300` | In-memory ownership cache TTL |
+| `jwt` | `boolean` | `false` | Request ES256 JWT alongside raw attestation |
+| `apiBaseUrl` | `string` | `https://api.insumermodel.com` | API base URL override |
+
+### TokenCondition
+
+| Field | Type | Description |
+|---|---|---|
+| `contractAddress` | `string` | Token/NFT contract address |
+| `chainId` | `number \| 'solana' \| 'xrpl'` | Chain identifier |
+| `type` | `'token_balance' \| 'nft_ownership'` | Condition type |
+| `threshold` | `number` | Min balance (token_balance only, default 1) |
+| `decimals` | `number` | Token decimals (auto-detected on most EVM chains) |
+| `label` | `string` | Human-readable label |
+| `currency` | `string` | XRPL currency code |
+| `taxon` | `number` | XRPL NFT taxon filter |
+
+## Supported chains
+
+30 EVM chains (Ethereum, Base, Polygon, Arbitrum, Optimism, BNB, Avalanche, and 23 more) + Solana + XRPL.
+
+[Full chain list](https://insumermodel.com/developers/api-reference/)
+
+## Distinguishing free vs paid access
+
+```ts
+const receipt = Receipt.fromResponse(response)
+if (receipt.reference.startsWith('token-gate:free:')) {
+  // Free access — attestation ID is in the reference
+  const attestationId = receipt.reference.replace('token-gate:free:', '')
+} else {
+  // Paid access
+}
+```
+
+## Fail-open behavior
+
+If the attestation API is unreachable, the wrapper falls through to the original payment method. Token holders pay normally; non-holders are unaffected.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,115 @@
+import type { Method } from 'mppx';
+export type TokenCondition = {
+    /** Token or NFT contract address. For XRPL native XRP, use "native". */
+    contractAddress: string;
+    /**
+     * Chain identifier.
+     * EVM chain ID (number), "solana", or "xrpl".
+     */
+    chainId: number | 'solana' | 'xrpl';
+    /** "token_balance" or "nft_ownership". */
+    type: 'token_balance' | 'nft_ownership';
+    /** Minimum balance for token_balance conditions. Defaults to 1. */
+    threshold?: number;
+    /** Token decimals (auto-detected on most EVM chains if omitted). */
+    decimals?: number;
+    /** Human-readable label (max 100 chars). */
+    label?: string;
+    /** XRPL currency code (e.g. "USD", "RLUSD"). Only for XRPL trust-line tokens. */
+    currency?: string;
+    /** XRPL NFT taxon filter. Only for XRPL nft_ownership. */
+    taxon?: number;
+};
+export type TokenGateOptions = {
+    /** InsumerAPI key. Falls back to INSUMER_API_KEY env var. */
+    apiKey?: string;
+    /** One or more token/NFT conditions to check. */
+    conditions: TokenCondition[];
+    /** Whether the payer must satisfy "any" (default) or "all" conditions. */
+    matchMode?: 'any' | 'all';
+    /** In-memory cache TTL in seconds. Defaults to 300 (5 minutes). */
+    cacheTtlSeconds?: number;
+    /**
+     * InsumerAPI base URL. Defaults to "https://api.insumermodel.com".
+     * Override for testing or self-hosted deployments.
+     */
+    apiBaseUrl?: string;
+    /** Request JWT format alongside the raw attestation. Defaults to false. */
+    jwt?: boolean;
+};
+export type InsumerAttestation = {
+    ok: boolean;
+    data: {
+        attestation: {
+            id: string;
+            pass: boolean;
+            results: Array<{
+                condition: number;
+                label?: string;
+                type: string;
+                chainId: number | string;
+                met: boolean;
+                evaluatedCondition: Record<string, unknown>;
+                conditionHash: string;
+                blockNumber?: string;
+                blockTimestamp?: string;
+                ledgerIndex?: number;
+                ledgerHash?: string;
+            }>;
+            passCount: number;
+            failCount: number;
+            attestedAt: string;
+            expiresAt: string;
+        };
+        sig: string;
+        kid: string;
+        jwt?: string;
+    };
+    meta: {
+        version: string;
+        timestamp: string;
+        creditsRemaining: number;
+        creditsCharged: number;
+    };
+};
+/** Clear the in-memory ownership cache. Useful in tests. */
+export declare function clearTokenGateCache(): void;
+/**
+ * Extracts an EVM address from a `did:pkh:eip155:{chainId}:{address}` string.
+ * Returns null for non-EVM or unparseable DIDs.
+ */
+export declare function parseDid(source: string): `0x${string}` | null;
+/**
+ * Extracts a Solana address from a `did:pkh:solana:{chainId}:{address}` string.
+ */
+export declare function parseSolanaDid(source: string): string | null;
+/**
+ * Extracts an XRPL address from a `did:pkh:xrpl:{chainId}:{address}` string.
+ */
+export declare function parsXrplDid(source: string): string | null;
+/**
+ * Wraps an mppx `Method.Server` to grant free access to token holders.
+ *
+ * Extracts the payer address from `credential.source` (DID), calls InsumerAPI
+ * to check token/NFT ownership across 32 chains, and returns a free receipt
+ * for holders. Non-holders fall through to the original payment method.
+ *
+ * The attestation is ECDSA P-256 signed and verifiable offline via JWKS.
+ *
+ * @example
+ * ```ts
+ * import { tokenGate } from 'mppx-token-gate'
+ *
+ * const gatedCharge = tokenGate(tempoCharge, {
+ *   conditions: [{
+ *     type: 'nft_ownership',
+ *     contractAddress: '0xYourNFT',
+ *     chainId: 8453,
+ *   }],
+ * })
+ *
+ * const mppx = Mppx.create({ methods: [gatedCharge] })
+ * ```
+ */
+export declare function tokenGate(server: Method.AnyServer, options: TokenGateOptions): Method.AnyServer;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,217 @@
+const cache = new Map();
+function cacheKey(address, conditions) {
+    const sorted = [...conditions].sort((a, b) => {
+        const ca = `${a.chainId}:${a.contractAddress}`.toLowerCase();
+        const cb = `${b.chainId}:${b.contractAddress}`.toLowerCase();
+        return ca < cb ? -1 : ca > cb ? 1 : 0;
+    });
+    return `${address.toLowerCase()}:${JSON.stringify(sorted)}`;
+}
+/** Clear the in-memory ownership cache. Useful in tests. */
+export function clearTokenGateCache() {
+    cache.clear();
+}
+// ---------------------------------------------------------------------------
+// DID parsing
+// ---------------------------------------------------------------------------
+/**
+ * Extracts an EVM address from a `did:pkh:eip155:{chainId}:{address}` string.
+ * Returns null for non-EVM or unparseable DIDs.
+ */
+export function parseDid(source) {
+    const parts = source.split(':');
+    if (parts.length !== 5)
+        return null;
+    if (parts[0] !== 'did' || parts[1] !== 'pkh' || parts[2] !== 'eip155')
+        return null;
+    const address = parts[4];
+    if (!address || !address.startsWith('0x'))
+        return null;
+    return address;
+}
+/**
+ * Extracts a Solana address from a `did:pkh:solana:{chainId}:{address}` string.
+ */
+export function parseSolanaDid(source) {
+    const parts = source.split(':');
+    if (parts.length !== 5)
+        return null;
+    if (parts[0] !== 'did' || parts[1] !== 'pkh' || parts[2] !== 'solana')
+        return null;
+    return parts[4] || null;
+}
+/**
+ * Extracts an XRPL address from a `did:pkh:xrpl:{chainId}:{address}` string.
+ */
+export function parsXrplDid(source) {
+    const parts = source.split(':');
+    if (parts.length !== 5)
+        return null;
+    if (parts[0] !== 'did' || parts[1] !== 'pkh' || parts[2] !== 'xrpl')
+        return null;
+    const address = parts[4];
+    if (!address || !address.startsWith('r'))
+        return null;
+    return address;
+}
+// ---------------------------------------------------------------------------
+// InsumerAPI call
+// ---------------------------------------------------------------------------
+async function callAttest(wallet, walletType, conditions, options) {
+    const apiKey = options.apiKey || process.env.INSUMER_API_KEY;
+    if (!apiKey) {
+        throw new Error('mppx-token-gate: Missing API key. Pass apiKey in options or set INSUMER_API_KEY env var. ' +
+            'Get a free key: POST https://api.insumermodel.com/v1/keys/create');
+    }
+    const baseUrl = options.apiBaseUrl || 'https://api.insumermodel.com';
+    const body = {
+        conditions: conditions.map((c) => {
+            const cond = {
+                type: c.type,
+                contractAddress: c.contractAddress,
+                chainId: c.chainId,
+            };
+            if (c.type === 'token_balance') {
+                cond.threshold = c.threshold ?? 1;
+            }
+            if (c.decimals !== undefined)
+                cond.decimals = c.decimals;
+            if (c.label)
+                cond.label = c.label;
+            if (c.currency)
+                cond.currency = c.currency;
+            if (c.taxon !== undefined)
+                cond.taxon = c.taxon;
+            return cond;
+        }),
+    };
+    if (walletType === 'solana')
+        body.solanaWallet = wallet;
+    else if (walletType === 'xrpl')
+        body.xrplWallet = wallet;
+    else
+        body.wallet = wallet;
+    if (options.jwt)
+        body.format = 'jwt';
+    const response = await fetch(`${baseUrl}/v1/attest`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'x-api-key': apiKey,
+        },
+        body: JSON.stringify(body),
+    });
+    const data = await response.json();
+    if (!response.ok || !data.ok) {
+        const msg = data?.error?.message || `HTTP ${response.status}`;
+        throw new Error(`mppx-token-gate: Attestation failed — ${msg}`);
+    }
+    return data;
+}
+// ---------------------------------------------------------------------------
+// tokenGate wrapper
+// ---------------------------------------------------------------------------
+/**
+ * Wraps an mppx `Method.Server` to grant free access to token holders.
+ *
+ * Extracts the payer address from `credential.source` (DID), calls InsumerAPI
+ * to check token/NFT ownership across 32 chains, and returns a free receipt
+ * for holders. Non-holders fall through to the original payment method.
+ *
+ * The attestation is ECDSA P-256 signed and verifiable offline via JWKS.
+ *
+ * @example
+ * ```ts
+ * import { tokenGate } from 'mppx-token-gate'
+ *
+ * const gatedCharge = tokenGate(tempoCharge, {
+ *   conditions: [{
+ *     type: 'nft_ownership',
+ *     contractAddress: '0xYourNFT',
+ *     chainId: 8453,
+ *   }],
+ * })
+ *
+ * const mppx = Mppx.create({ methods: [gatedCharge] })
+ * ```
+ */
+export function tokenGate(server, options) {
+    const { conditions, matchMode = 'any', cacheTtlSeconds = 300 } = options;
+    const originalVerify = server.verify;
+    const gatedVerify = async (params) => {
+        const credential = params.credential;
+        const source = credential.source;
+        // No DID → fall through to payment
+        if (!source)
+            return originalVerify(params);
+        // Determine wallet type and address
+        let wallet = null;
+        let walletType = 'evm';
+        wallet = parseDid(source);
+        if (!wallet) {
+            wallet = parseSolanaDid(source);
+            if (wallet)
+                walletType = 'solana';
+        }
+        if (!wallet) {
+            wallet = parsXrplDid(source);
+            if (wallet)
+                walletType = 'xrpl';
+        }
+        // Unparseable DID → fall through to payment
+        if (!wallet)
+            return originalVerify(params);
+        // Check cache
+        const key = cacheKey(wallet, conditions);
+        const cached = cache.get(key);
+        if (cached && cached.expiresAt > Date.now()) {
+            if (cached.pass) {
+                return {
+                    method: server.name,
+                    reference: `token-gate:free:${cached.attestationId}`,
+                    status: 'success',
+                    timestamp: new Date().toISOString(),
+                };
+            }
+            // Cached non-holder → fall through
+            return originalVerify(params);
+        }
+        // Call InsumerAPI
+        try {
+            const result = await callAttest(wallet, walletType, conditions, options);
+            const attestation = result.data.attestation;
+            // Determine pass based on matchMode
+            let pass;
+            if (matchMode === 'all') {
+                pass = attestation.pass; // all conditions must be met
+            }
+            else {
+                // "any" — at least one condition met
+                pass = attestation.results.some((r) => r.met);
+            }
+            // Cache the result
+            cache.set(key, {
+                pass,
+                attestationId: attestation.id,
+                expiresAt: Date.now() + cacheTtlSeconds * 1000,
+            });
+            if (pass) {
+                return {
+                    method: server.name,
+                    reference: `token-gate:free:${attestation.id}`,
+                    status: 'success',
+                    timestamp: new Date().toISOString(),
+                };
+            }
+        }
+        catch {
+            // Attestation API error → fall through to payment (fail open)
+        }
+        return originalVerify(params);
+    };
+    return {
+        ...server,
+        verify: gatedVerify,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@insumermodel/mppx-token-gate",
+  "version": "1.0.0",
+  "description": "Token-gate mppx routes using signed wallet attestations — 32 chains, no RPC management",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mppx",
+    "mpp",
+    "token-gate",
+    "token-gating",
+    "wallet",
+    "attestation",
+    "erc20",
+    "erc721",
+    "nft",
+    "solana",
+    "xrpl",
+    "web3"
+  ],
+  "author": "douglasborthwick-crypto",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/douglasborthwick-crypto/mppx-token-gate.git"
+  },
+  "peerDependencies": {
+    "mppx": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "mppx": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "mppx": "latest",
+    "typescript": "^5.7.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,325 @@
+import type { Method, Receipt } from 'mppx'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type TokenCondition = {
+  /** Token or NFT contract address. For XRPL native XRP, use "native". */
+  contractAddress: string
+  /**
+   * Chain identifier.
+   * EVM chain ID (number), "solana", or "xrpl".
+   */
+  chainId: number | 'solana' | 'xrpl'
+  /** "token_balance" or "nft_ownership". */
+  type: 'token_balance' | 'nft_ownership'
+  /** Minimum balance for token_balance conditions. Defaults to 1. */
+  threshold?: number
+  /** Token decimals (auto-detected on most EVM chains if omitted). */
+  decimals?: number
+  /** Human-readable label (max 100 chars). */
+  label?: string
+  /** XRPL currency code (e.g. "USD", "RLUSD"). Only for XRPL trust-line tokens. */
+  currency?: string
+  /** XRPL NFT taxon filter. Only for XRPL nft_ownership. */
+  taxon?: number
+}
+
+export type TokenGateOptions = {
+  /** InsumerAPI key. Falls back to INSUMER_API_KEY env var. */
+  apiKey?: string
+  /** One or more token/NFT conditions to check. */
+  conditions: TokenCondition[]
+  /** Whether the payer must satisfy "any" (default) or "all" conditions. */
+  matchMode?: 'any' | 'all'
+  /** In-memory cache TTL in seconds. Defaults to 300 (5 minutes). */
+  cacheTtlSeconds?: number
+  /**
+   * InsumerAPI base URL. Defaults to "https://api.insumermodel.com".
+   * Override for testing or self-hosted deployments.
+   */
+  apiBaseUrl?: string
+  /** Request JWT format alongside the raw attestation. Defaults to false. */
+  jwt?: boolean
+}
+
+export type InsumerAttestation = {
+  ok: boolean
+  data: {
+    attestation: {
+      id: string
+      pass: boolean
+      results: Array<{
+        condition: number
+        label?: string
+        type: string
+        chainId: number | string
+        met: boolean
+        evaluatedCondition: Record<string, unknown>
+        conditionHash: string
+        blockNumber?: string
+        blockTimestamp?: string
+        ledgerIndex?: number
+        ledgerHash?: string
+      }>
+      passCount: number
+      failCount: number
+      attestedAt: string
+      expiresAt: string
+    }
+    sig: string
+    kid: string
+    jwt?: string
+  }
+  meta: {
+    version: string
+    timestamp: string
+    creditsRemaining: number
+    creditsCharged: number
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Cache
+// ---------------------------------------------------------------------------
+
+type CacheEntry = {
+  pass: boolean
+  attestationId: string
+  expiresAt: number
+}
+
+const cache = new Map<string, CacheEntry>()
+
+function cacheKey(address: string, conditions: TokenCondition[]): string {
+  const sorted = [...conditions].sort((a, b) => {
+    const ca = `${a.chainId}:${a.contractAddress}`.toLowerCase()
+    const cb = `${b.chainId}:${b.contractAddress}`.toLowerCase()
+    return ca < cb ? -1 : ca > cb ? 1 : 0
+  })
+  return `${address.toLowerCase()}:${JSON.stringify(sorted)}`
+}
+
+/** Clear the in-memory ownership cache. Useful in tests. */
+export function clearTokenGateCache(): void {
+  cache.clear()
+}
+
+// ---------------------------------------------------------------------------
+// DID parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Extracts an EVM address from a `did:pkh:eip155:{chainId}:{address}` string.
+ * Returns null for non-EVM or unparseable DIDs.
+ */
+export function parseDid(source: string): `0x${string}` | null {
+  const parts = source.split(':')
+  if (parts.length !== 5) return null
+  if (parts[0] !== 'did' || parts[1] !== 'pkh' || parts[2] !== 'eip155') return null
+  const address = parts[4]
+  if (!address || !address.startsWith('0x')) return null
+  return address as `0x${string}`
+}
+
+/**
+ * Extracts a Solana address from a `did:pkh:solana:{chainId}:{address}` string.
+ */
+export function parseSolanaDid(source: string): string | null {
+  const parts = source.split(':')
+  if (parts.length !== 5) return null
+  if (parts[0] !== 'did' || parts[1] !== 'pkh' || parts[2] !== 'solana') return null
+  return parts[4] || null
+}
+
+/**
+ * Extracts an XRPL address from a `did:pkh:xrpl:{chainId}:{address}` string.
+ */
+export function parsXrplDid(source: string): string | null {
+  const parts = source.split(':')
+  if (parts.length !== 5) return null
+  if (parts[0] !== 'did' || parts[1] !== 'pkh' || parts[2] !== 'xrpl') return null
+  const address = parts[4]
+  if (!address || !address.startsWith('r')) return null
+  return address
+}
+
+// ---------------------------------------------------------------------------
+// InsumerAPI call
+// ---------------------------------------------------------------------------
+
+async function callAttest(
+  wallet: string,
+  walletType: 'evm' | 'solana' | 'xrpl',
+  conditions: TokenCondition[],
+  options: Pick<TokenGateOptions, 'apiKey' | 'apiBaseUrl' | 'jwt'>,
+): Promise<InsumerAttestation> {
+  const apiKey = options.apiKey || process.env.INSUMER_API_KEY
+  if (!apiKey) {
+    throw new Error(
+      'mppx-token-gate: Missing API key. Pass apiKey in options or set INSUMER_API_KEY env var. ' +
+      'Get a free key: POST https://api.insumermodel.com/v1/keys/create',
+    )
+  }
+
+  const baseUrl = options.apiBaseUrl || 'https://api.insumermodel.com'
+
+  const body: Record<string, unknown> = {
+    conditions: conditions.map((c) => {
+      const cond: Record<string, unknown> = {
+        type: c.type,
+        contractAddress: c.contractAddress,
+        chainId: c.chainId,
+      }
+      if (c.type === 'token_balance') {
+        cond.threshold = c.threshold ?? 1
+      }
+      if (c.decimals !== undefined) cond.decimals = c.decimals
+      if (c.label) cond.label = c.label
+      if (c.currency) cond.currency = c.currency
+      if (c.taxon !== undefined) cond.taxon = c.taxon
+      return cond
+    }),
+  }
+
+  if (walletType === 'solana') body.solanaWallet = wallet
+  else if (walletType === 'xrpl') body.xrplWallet = wallet
+  else body.wallet = wallet
+
+  if (options.jwt) body.format = 'jwt'
+
+  const response = await fetch(`${baseUrl}/v1/attest`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': apiKey,
+    },
+    body: JSON.stringify(body),
+  })
+
+  const data = await response.json() as InsumerAttestation
+  if (!response.ok || !data.ok) {
+    const msg = (data as any)?.error?.message || `HTTP ${response.status}`
+    throw new Error(`mppx-token-gate: Attestation failed — ${msg}`)
+  }
+  return data
+}
+
+// ---------------------------------------------------------------------------
+// tokenGate wrapper
+// ---------------------------------------------------------------------------
+
+/**
+ * Wraps an mppx `Method.Server` to grant free access to token holders.
+ *
+ * Extracts the payer address from `credential.source` (DID), calls InsumerAPI
+ * to check token/NFT ownership across 32 chains, and returns a free receipt
+ * for holders. Non-holders fall through to the original payment method.
+ *
+ * The attestation is ECDSA P-256 signed and verifiable offline via JWKS.
+ *
+ * @example
+ * ```ts
+ * import { tokenGate } from 'mppx-token-gate'
+ *
+ * const gatedCharge = tokenGate(tempoCharge, {
+ *   conditions: [{
+ *     type: 'nft_ownership',
+ *     contractAddress: '0xYourNFT',
+ *     chainId: 8453,
+ *   }],
+ * })
+ *
+ * const mppx = Mppx.create({ methods: [gatedCharge] })
+ * ```
+ */
+export function tokenGate(
+  server: Method.AnyServer,
+  options: TokenGateOptions,
+): Method.AnyServer {
+  const { conditions, matchMode = 'any', cacheTtlSeconds = 300 } = options
+
+  const originalVerify = server.verify
+
+  const gatedVerify: typeof originalVerify = async (params: any) => {
+    const credential = params.credential as { source?: string }
+    const source = credential.source
+
+    // No DID → fall through to payment
+    if (!source) return originalVerify(params)
+
+    // Determine wallet type and address
+    let wallet: string | null = null
+    let walletType: 'evm' | 'solana' | 'xrpl' = 'evm'
+
+    wallet = parseDid(source)
+    if (!wallet) {
+      wallet = parseSolanaDid(source)
+      if (wallet) walletType = 'solana'
+    }
+    if (!wallet) {
+      wallet = parsXrplDid(source)
+      if (wallet) walletType = 'xrpl'
+    }
+
+    // Unparseable DID → fall through to payment
+    if (!wallet) return originalVerify(params)
+
+    // Check cache
+    const key = cacheKey(wallet, conditions)
+    const cached = cache.get(key)
+    if (cached && cached.expiresAt > Date.now()) {
+      if (cached.pass) {
+        return {
+          method: server.name,
+          reference: `token-gate:free:${cached.attestationId}`,
+          status: 'success' as const,
+          timestamp: new Date().toISOString(),
+        }
+      }
+      // Cached non-holder → fall through
+      return originalVerify(params)
+    }
+
+    // Call InsumerAPI
+    try {
+      const result = await callAttest(wallet, walletType, conditions, options)
+      const attestation = result.data.attestation
+
+      // Determine pass based on matchMode
+      let pass: boolean
+      if (matchMode === 'all') {
+        pass = attestation.pass // all conditions must be met
+      } else {
+        // "any" — at least one condition met
+        pass = attestation.results.some((r) => r.met)
+      }
+
+      // Cache the result
+      cache.set(key, {
+        pass,
+        attestationId: attestation.id,
+        expiresAt: Date.now() + cacheTtlSeconds * 1000,
+      })
+
+      if (pass) {
+        return {
+          method: server.name,
+          reference: `token-gate:free:${attestation.id}`,
+          status: 'success' as const,
+          timestamp: new Date().toISOString(),
+        }
+      }
+    } catch {
+      // Attestation API error → fall through to payment (fail open)
+    }
+
+    return originalVerify(params)
+  }
+
+  return {
+    ...server,
+    verify: gatedVerify,
+  }
+}