@insumermodel/wdk-protocol-wallet-auth 0.1.0

package/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,136 @@
+# @insumermodel/wdk-protocol-wallet-auth
+
+> **Wallet auth for WDK wallets.** OAuth proves who you are. Wallet auth proves what you hold.
+
+A [Wallet Development Kit](https://docs.wdk.tether.io/) protocol module that adds a new protocol category alongside Swap, Bridge, Lending, and Fiat: **pre-transaction, condition-based access.** Given a wallet and a set of on-chain conditions, it returns a cryptographically signed pass/fail (`attest`) or a multi-dimensional trust profile (`trust`). Results are ECDSA P-256 signed and verifiable offline against a public JWKS — no secrets, no identity-first, no static credentials.
+
+Powered by [InsumerAPI](https://insumermodel.com). Supports 33 chains including all networks used by [tether.wallet](https://tether.wallet) and WDK-based wallets (Ethereum, Polygon, Arbitrum, Optimism, Base, Avalanche, BNB, Plasma, Solana, TRON, TON, Bitcoin, XRPL, and more).
+
+## Why this exists
+
+WDK ships wallet modules and protocol modules (Swap, Bridge, Lending, Fiat) but has **no pre-transaction policy layer** — nothing to answer questions like "is this wallet allowed to receive this payment?" or "does this counterparty pass a sanctions and trust screen?" before signing.
+
+This package fills that gap as a first-class WDK protocol:
+
+```js
+import InsumerWalletAuthProtocol from '@insumermodel/wdk-protocol-wallet-auth'
+
+const walletAuth = new InsumerWalletAuthProtocol({ apiKey: process.env.INSUMER_API_KEY })
+
+// Before broadcasting a transaction, verify the counterparty:
+const { passed, sig, kid } = await walletAuth.attest({
+  address: '0xCounterparty...',
+  conditions: [
+    { type: 'token_balance', contractAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', chainId: 1, threshold: 1000, decimals: 6, label: 'USDC >= 1000' }
+  ]
+})
+
+if (!passed) throw new Error('counterparty failed wallet auth check')
+// `sig` and `kid` are the audit trail: anyone can verify this later against the JWKS.
+```
+
+Use cases:
+
+- **Agent-wallet guardrails.** WDK explicitly targets "humans, machines and AI agents." When an autonomous agent holds keys, the operator wants programmable constraints the agent can't argue its way around — and a cryptographic audit trail the operator can verify after the fact.
+- **Receive-side trust display.** Before a creator accepts a payment, show a trust profile on the sending wallet. Native fit for products like Rumble Wallet.
+- **Compliance cover for consumer apps built on WDK.** Drop-in Travel Rule / sanctions / counterparty-risk screen.
+
+## Install
+
+```bash
+npm install @insumermodel/wdk-protocol-wallet-auth
+```
+
+Get an API key at [insumermodel.com](https://insumermodel.com) (free tier available).
+
+### Buying credits
+
+The free tier ships 100 attestation credits. When you need more, credits can be purchased on-chain with **USDC, USDT, or BTC** via `POST /v1/credits/buy` — no Stripe, no signup, no fiat. Supported payment rails:
+
+- **USDC or USDT** on any major EVM chain (Ethereum, Polygon, Arbitrum, Optimism, Base, Avalanche, BNB, and more) — the endpoint auto-detects which stablecoin you sent.
+- **USDC** on Solana.
+- **BTC** on Bitcoin mainnet.
+
+Send the transfer to the platform wallet for your chosen chain, then `POST /v1/credits/buy` with `{ txHash, chainId, amount }`. Credits post as soon as the transaction is verified on-chain. See the [OpenAPI spec](https://insumermodel.com/openapi.yaml) for the full request shape.
+
+## API
+
+The package exports:
+
+- `InsumerWalletAuthProtocol` (default export) — the InsumerAPI implementation
+- `WalletAuthProtocol` — the abstract base class (implement your own backend)
+- `IWalletAuthProtocol` — the interface
+
+### `new InsumerWalletAuthProtocol(options)`
+
+| Option    | Type      | Description |
+|-----------|-----------|-------------|
+| `apiKey`  | `string`  | **Required.** InsumerAPI key. |
+| `account` | `object`  | Optional WDK wallet account. When bound, its `getAddress()` is used as the default subject. |
+| `baseUrl` | `string`  | Override the API base URL. Defaults to `https://api.insumermodel.com`. |
+| `fetch`   | `fetch`   | Override the `fetch` implementation (useful in Bare / React Native runtimes). |
+
+### `attest(options)` → `Promise<AttestResult>`
+
+Evaluates one to ten on-chain conditions against a wallet and returns a cryptographically signed pass/fail. Maps to [`POST /v1/attest`](https://insumermodel.com/openapi.yaml).
+
+```js
+const result = await walletAuth.attest({
+  address: '0x1234...',                // defaults to bound account
+  conditions: [
+    { type: 'token_balance', contractAddress: '0xA0b8...', chainId: 1, threshold: 1000, decimals: 6 },
+    { type: 'nft_ownership', contractAddress: '0xBC4C...', chainId: 1 }
+  ],
+  jwt: true,          // optional: also return an ES256 JWT
+  merkleProof: true   // optional: include EIP-1186 Merkle storage proofs (2 credits instead of 1)
+})
+
+// result.passed           — true only if every condition is met
+// result.attestation      — full attestation object (per-condition results, block info, condition hash)
+// result.sig / result.kid — ECDSA P-256 signature + key id (verify against JWKS)
+// result.jwt              — ES256 JWT form, when requested
+// result.creditsRemaining — credits remaining on the API key
+```
+
+Supported condition types: `token_balance`, `nft_ownership`, `eas_attestation`, `farcaster_id`. Supported chains: 30 EVM chains plus Solana, XRPL, and Bitcoin. See the [InsumerAPI OpenAPI spec](https://insumermodel.com/openapi.yaml) for the full schema.
+
+### `trust(options)` → `Promise<TrustResult>`
+
+Returns a multi-dimensional trust profile: 36+ signed checks across stablecoins, governance, NFTs, staking, and (optionally) Solana, XRPL, and Bitcoin dimensions. Maps to [`POST /v1/trust`](https://insumermodel.com/openapi.yaml).
+
+```js
+const { trust, sig, kid } = await walletAuth.trust({
+  address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
+  solanaAddress: '...',  // optional, adds Solana dimension
+  xrplAddress: '...',    // optional, adds XRPL dimension
+  bitcoinAddress: '...'  // optional, adds Bitcoin dimension
+})
+
+// trust.id         — TRST-XXXXX profile id
+// trust.dimensions — per-dimension checks (each individually signed)
+// trust.summary    — totalChecks, totalPassed, dimensionsWithActivity
+```
+
+## Verification
+
+Every attestation and trust result is ECDSA P-256 signed. The signature (`sig`) and key id (`kid`) let any party verify the result offline, without calling the API, using the public JWKS:
+
+```
+https://insumermodel.com/.well-known/jwks.json
+```
+
+Use any standard JOSE/JWT library, or `npm install insumer-verify` for a convenience wrapper.
+
+## Supported environments
+
+- Node.js ≥ 18 (uses the built-in `fetch`)
+- Bare / React Native runtimes (pass a `fetch` implementation in the constructor)
+- Browsers (CORS is enabled on `api.insumermodel.com`)
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE).
+
+## Maintainer
+
+Built by [Douglas Borthwick](https://insumermodel.com). Issues and contributions welcome at the [GitHub repo](https://github.com/douglasborthwick-crypto/wdk-protocol-wallet-auth).

package/index.js

@@ -0,0 +1,25 @@
+// Copyright 2026 Douglas Borthwick / InsumerAPI
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict'
+
+/** @typedef {import('./src/wallet-auth-protocol.js').AttestOptions} AttestOptions */
+/** @typedef {import('./src/wallet-auth-protocol.js').AttestResult} AttestResult */
+/** @typedef {import('./src/wallet-auth-protocol.js').TrustOptions} TrustOptions */
+/** @typedef {import('./src/wallet-auth-protocol.js').TrustResult} TrustResult */
+/** @typedef {import('./src/wallet-auth-protocol.js').Condition} Condition */
+
+export { default as WalletAuthProtocol, IWalletAuthProtocol } from './src/wallet-auth-protocol.js'
+export { default as InsumerWalletAuthProtocol } from './src/insumer-wallet-auth-protocol.js'
+export { default } from './src/insumer-wallet-auth-protocol.js'

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@insumermodel/wdk-protocol-wallet-auth",
+  "version": "0.1.0",
+  "description": "WDK protocol module for wallet auth — cryptographically signed, pre-transaction condition-based access. OAuth proves who you are; wallet auth proves what you hold. Powered by InsumerAPI.",
+  "keywords": [
+    "wdk",
+    "protocol",
+    "wallet-auth",
+    "condition-based-access",
+    "attestation",
+    "trust",
+    "insumerapi"
+  ],
+  "author": "Douglas Borthwick <douglas@insumermodel.com>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/douglasborthwick-crypto/wdk-protocol-wallet-auth.git"
+  },
+  "homepage": "https://insumermodel.com/developers/wdk/",
+  "bugs": {
+    "url": "https://github.com/douglasborthwick-crypto/wdk-protocol-wallet-auth/issues"
+  },
+  "main": "index.js",
+  "type": "module",
+  "types": "./types",
+  "files": [
+    "index.js",
+    "src/",
+    "types/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "lint": "standard",
+    "lint:fix": "standard --fix"
+  },
+  "peerDependencies": {
+    "@tetherto/wdk-wallet": "^1.0.0-beta.1"
+  },
+  "peerDependenciesMeta": {
+    "@tetherto/wdk-wallet": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "standard": "^17.1.2"
+  },
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./index.js"
+    },
+    "./package": {
+      "default": "./package.json"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/insumer-wallet-auth-protocol.js

@@ -0,0 +1,170 @@
+// Copyright 2026 Douglas Borthwick / InsumerAPI
+//
+// Licensed under the Apache License, Version 2.0.
+
+'use strict'
+
+import WalletAuthProtocol from './wallet-auth-protocol.js'
+
+/** @typedef {import('./wallet-auth-protocol.js').AttestOptions} AttestOptions */
+/** @typedef {import('./wallet-auth-protocol.js').AttestResult} AttestResult */
+/** @typedef {import('./wallet-auth-protocol.js').TrustOptions} TrustOptions */
+/** @typedef {import('./wallet-auth-protocol.js').TrustResult} TrustResult */
+
+const DEFAULT_BASE_URL = 'https://api.insumermodel.com'
+
+/**
+ * InsumerAPI implementation of the WDK Wallet Auth protocol.
+ *
+ * Wraps POST /v1/attest and POST /v1/trust. Results are ECDSA P-256 signed
+ * and verifiable offline against the JWKS at
+ * https://insumermodel.com/.well-known/jwks.json using any standard JWT or
+ * JOSE library (or the `insumer-verify` npm package).
+ */
+export default class InsumerWalletAuthProtocol extends WalletAuthProtocol {
+  /**
+   * @param {Object} options
+   * @param {string} options.apiKey - InsumerAPI key. Get one at https://insumermodel.com/.
+   * @param {string} [options.baseUrl] - Override the API base URL. Defaults to https://api.insumermodel.com.
+   * @param {any} [options.account] - Optional wallet account to bind. When present, its getAddress() is used as the default subject.
+   * @param {typeof fetch} [options.fetch] - Override the fetch implementation (useful in Bare/React Native runtimes).
+   */
+  constructor (options = {}) {
+    super(options.account)
+    if (!options.apiKey || typeof options.apiKey !== 'string') {
+      throw new Error('InsumerWalletAuthProtocol: apiKey is required')
+    }
+    /** @private */
+    this._apiKey = options.apiKey
+    /** @private */
+    this._baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '')
+    /** @private */
+    this._fetch = options.fetch || globalThis.fetch
+    if (typeof this._fetch !== 'function') {
+      throw new Error('InsumerWalletAuthProtocol: no fetch implementation available. Pass { fetch } in the runtime environment.')
+    }
+  }
+
+  /**
+   * Resolve the default subject address from the bound account, if any.
+   * @private
+   * @returns {Promise<string | undefined>}
+   */
+  async _defaultAddress () {
+    if (!this._account) return undefined
+    if (typeof this._account.getAddress === 'function') {
+      return await this._account.getAddress()
+    }
+    if (typeof this._account.address === 'string') {
+      return this._account.address
+    }
+    return undefined
+  }
+
+  /**
+   * POST to an InsumerAPI endpoint and unwrap the standard response envelope.
+   * @private
+   */
+  async _post (path, body) {
+    const res = await this._fetch(`${this._baseUrl}${path}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-API-Key': this._apiKey
+      },
+      body: JSON.stringify(body)
+    })
+
+    let payload
+    try {
+      payload = await res.json()
+    } catch (_e) {
+      throw new Error(`InsumerAPI ${path} returned non-JSON response (HTTP ${res.status})`)
+    }
+
+    if (!res.ok || payload?.ok !== true) {
+      const code = payload?.error?.code || `http_${res.status}`
+      const msg = payload?.error?.message || res.statusText || 'unknown error'
+      const err = new Error(`InsumerAPI ${path} failed: ${code} — ${msg}`)
+      err.status = res.status
+      err.code = code
+      err.response = payload
+      throw err
+    }
+
+    return payload
+  }
+
+  /**
+   * Evaluate one or more on-chain conditions against a wallet. Returns a
+   * signed pass/fail attestation.
+   *
+   * @param {AttestOptions} options
+   * @returns {Promise<AttestResult>}
+   */
+  async attest (options) {
+    if (!options || !Array.isArray(options.conditions) || options.conditions.length === 0) {
+      throw new Error('attest(options): conditions array is required (1-10 items)')
+    }
+    if (options.conditions.length > 10) {
+      throw new Error('attest(options): at most 10 conditions per call')
+    }
+
+    const address = options.address || await this._defaultAddress()
+
+    /** @type {Record<string, any>} */
+    const body = { conditions: options.conditions }
+    if (address) body.wallet = address
+    if (options.solanaAddress) body.solanaWallet = options.solanaAddress
+    if (options.xrplAddress) body.xrplWallet = options.xrplAddress
+    if (options.bitcoinAddress) body.bitcoinWallet = options.bitcoinAddress
+    if (options.jwt) body.format = 'jwt'
+    if (options.merkleProof) body.proof = 'merkle'
+
+    const payload = await this._post('/v1/attest', body)
+    const data = payload.data || {}
+    const meta = payload.meta || {}
+
+    return {
+      passed: data.attestation?.pass === true,
+      attestation: data.attestation,
+      sig: data.sig,
+      kid: data.kid,
+      jwt: data.jwt,
+      creditsRemaining: meta.creditsRemaining,
+      creditsCharged: meta.creditsCharged
+    }
+  }
+
+  /**
+   * Return a multi-dimensional trust profile for a wallet.
+   *
+   * @param {TrustOptions} [options]
+   * @returns {Promise<TrustResult>}
+   */
+  async trust (options = {}) {
+    const address = options.address || await this._defaultAddress()
+    if (!address) {
+      throw new Error('trust(options): address is required (pass options.address or bind a wallet account)')
+    }
+
+    /** @type {Record<string, any>} */
+    const body = { wallet: address }
+    if (options.solanaAddress) body.solanaWallet = options.solanaAddress
+    if (options.xrplAddress) body.xrplWallet = options.xrplAddress
+    if (options.bitcoinAddress) body.bitcoinWallet = options.bitcoinAddress
+    if (options.merkleProof) body.proof = 'merkle'
+
+    const payload = await this._post('/v1/trust', body)
+    const data = payload.data || {}
+    const meta = payload.meta || {}
+
+    return {
+      trust: data.trust,
+      sig: data.sig,
+      kid: data.kid,
+      creditsRemaining: meta.creditsRemaining,
+      creditsCharged: meta.creditsCharged
+    }
+  }
+}

package/src/wallet-auth-protocol.js

@@ -0,0 +1,150 @@
+// Copyright 2026 Douglas Borthwick / InsumerAPI
+//
+// Licensed under the Apache License, Version 2.0.
+
+'use strict'
+
+/**
+ * Abstract base class defining a new WDK protocol category: Wallet Auth.
+ *
+ * OAuth proves who you are. Wallet auth proves what you hold.
+ *
+ * Alongside WDK's existing Swap, Bridge, Lending, and Fiat protocols, this
+ * defines a pre-transaction verification protocol: given a wallet and a set
+ * of on-chain conditions, return a cryptographically signed pass/fail
+ * (attestation) or a multi-dimensional trust profile. The output is an
+ * ECDSA-signed credential the caller can verify offline; no secrets, no
+ * identity-first, no static credentials.
+ *
+ * Implementations (e.g. InsumerWalletAuthProtocol) call an external
+ * verification service and return signed results. The protocol itself never
+ * touches private keys or broadcasts transactions — it runs before, not
+ * during, the signing flow.
+ *
+ * Shape-compatible with upstream WDK protocol base classes and intended to
+ * be proposed for inclusion in @tetherto/wdk-wallet/protocols.
+ */
+
+/** @typedef {import('@tetherto/wdk-wallet').IWalletAccountReadOnly} IWalletAccountReadOnly */
+/** @typedef {import('@tetherto/wdk-wallet').IWalletAccount} IWalletAccount */
+
+/**
+ * @typedef {Object} Condition
+ * @property {"token_balance"|"nft_ownership"|"eas_attestation"|"farcaster_id"} type
+ * @property {string} [contractAddress]
+ * @property {(number|string)} [chainId]
+ * @property {(number|string|bigint)} [threshold]
+ * @property {number} [decimals]
+ * @property {string} [tokenId]
+ * @property {string} [schemaId]
+ * @property {string} [attester]
+ * @property {string} [indexer]
+ * @property {string} [template]
+ * @property {string} [currency]
+ * @property {string} [label]
+ */
+
+/**
+ * @typedef {Object} AttestOptions
+ * @property {Condition[]} conditions - One to ten on-chain conditions to evaluate.
+ * @property {string} [address] - Address to evaluate. Defaults to the attached account.
+ * @property {string} [solanaAddress] - Solana address, if different from the default EVM address.
+ * @property {string} [xrplAddress] - XRPL r-address.
+ * @property {string} [bitcoinAddress] - Bitcoin address.
+ * @property {boolean} [jwt] - If true, request an ES256 JWT alongside the attestation.
+ * @property {boolean} [merkleProof] - If true, request EIP-1186 Merkle storage proofs (costs 2 credits instead of 1).
+ */
+
+/**
+ * @typedef {Object} AttestResult
+ * @property {boolean} passed - True if every condition is met.
+ * @property {Object} attestation - Raw attestation object (condition-by-condition results, block numbers, condition hash).
+ * @property {string} sig - ECDSA P-256 signature over the attestation (base64).
+ * @property {string} kid - Key ID identifying the signing key in the JWKS.
+ * @property {string} [jwt] - ES256 JWT form of the attestation, when requested.
+ * @property {number} creditsRemaining - Credits remaining on the API key after this call.
+ * @property {number} creditsCharged - Credits consumed by this call.
+ */
+
+/**
+ * @typedef {Object} TrustOptions
+ * @property {string} [address] - EVM address to profile. Defaults to the attached account.
+ * @property {string} [solanaAddress] - Optional Solana address.
+ * @property {string} [xrplAddress] - Optional XRPL r-address.
+ * @property {string} [bitcoinAddress] - Optional Bitcoin address.
+ * @property {boolean} [merkleProof] - If true, request Merkle proofs (costs 6 credits instead of 3).
+ */
+
+/**
+ * @typedef {Object} TrustResult
+ * @property {Object} trust - Full trust profile (dimensions, checks, summary, profile id).
+ * @property {string} sig - ECDSA P-256 signature over the trust object.
+ * @property {string} kid - Key ID identifying the signing key in the JWKS.
+ * @property {number} creditsRemaining
+ * @property {number} creditsCharged
+ */
+
+/** @interface */
+export class IWalletAuthProtocol {
+  /**
+   * Evaluate one or more on-chain conditions against a wallet and return a
+   * cryptographically signed pass/fail attestation. Runs server-side against
+   * live chain state and never exposes raw balances unless merkleProof is
+   * requested.
+   *
+   * @param {AttestOptions} options
+   * @returns {Promise<AttestResult>}
+   */
+  async attest (options) {
+    throw new Error('attest(options) not implemented')
+  }
+
+  /**
+   * Return a multi-dimensional trust profile for a wallet across stablecoins,
+   * governance, NFTs, and staking activity (plus optional Solana, XRPL, and
+   * Bitcoin dimensions). Each check is individually signed.
+   *
+   * @param {TrustOptions} [options]
+   * @returns {Promise<TrustResult>}
+   */
+  async trust (options) {
+    throw new Error('trust(options) not implemented')
+  }
+}
+
+/**
+ * @abstract
+ * @implements {IWalletAuthProtocol}
+ */
+export default class WalletAuthProtocol {
+  /**
+   * @param {IWalletAccountReadOnly | IWalletAccount} [account] - Optional wallet
+   *   account to bind. When present, its address is used as the default subject
+   *   for attest() and trust() calls.
+   */
+  constructor (account) {
+    /**
+     * @protected
+     * @type {IWalletAccountReadOnly | IWalletAccount | undefined}
+     */
+    this._account = account
+  }
+
+  /**
+   * @abstract
+   * @param {AttestOptions} options
+   * @returns {Promise<AttestResult>}
+   */
+  async attest (options) {
+    throw new Error('attest(options) not implemented')
+  }
+
+  /**
+   * @abstract
+   * @param {TrustOptions} [options]
+   * @returns {Promise<TrustResult>}
+   */
+  async trust (options) {
+    throw new Error('trust(options) not implemented')
+  }
+}