crossmint-wallets-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,303 @@
+# crossmint-wallets-mcp
+
+> An MCP server that exposes Crossmint smart wallet primitives as tools for
+> any MCP-native client: Claude Desktop, Continue.dev, Cline, Codex CLI,
+> and anything else that speaks the Model Context Protocol.
+
+**Status:** v0.1.0 — Solana mainnet verified end-to-end. Base EVM planned.
+
+## What this gives you
+
+Four tools, callable from any MCP client, each wrapping a primitive from
+[`@crossmint/wallets-sdk`](https://www.npmjs.com/package/@crossmint/wallets-sdk):
+
+| Tool                              | What it does                                                        |
+|-----------------------------------|---------------------------------------------------------------------|
+| `crossmint_create_wallet`         | Create a new Crossmint smart wallet on the given chain              |
+| `crossmint_get_balance`           | Read native token + USDC + optional extra balances for a wallet     |
+| `crossmint_transfer_token`        | Send USDC (or any supported token) from a Crossmint wallet          |
+| `crossmint_pay_x402_endpoint`     | Fetch an HTTP URL, handle its x402 payment challenge, return the paid response |
+
+The killer tool is `crossmint_pay_x402_endpoint`. One call, any URL, any
+MCP client. The agent handles the 402 parse, the wallet signing, the
+on-chain confirmation, and the retry automatically.
+
+## Why this exists
+
+[lobster.cash](https://lobster.cash) is Crossmint's payment engine for AI
+agents. It ships as a CLI (`@crossmint/lobster-cli`) that installs into
+Claude Code, Cursor, and OpenClaw via the skills architecture. But a lot
+of 2026's agent surface speaks MCP, not skills:
+
+- **Claude Desktop** (Anthropic's desktop app)
+- **Continue.dev** (IDE assistant)
+- **Cline** (VS Code agent extension)
+- **Codex CLI** (OpenAI's command-line agent)
+- And everything else that has shipped against the MCP spec
+
+`crossmint-wallets-mcp` is the MCP-native companion to lobster.cash —
+same wallets, same payments, same chain, different transport. It is not
+a replacement. It is the piece lobster.cash doesn't ship.
+
+## Install
+
+```bash
+# Global install
+npm install -g crossmint-wallets-mcp
+
+# Or one-off via npx (recommended for MCP clients)
+npx crossmint-wallets-mcp
+```
+
+Node.js ≥ 20 required.
+
+## Configure
+
+You need a **Crossmint server API key** with the following scopes:
+
+- `wallets.create`
+- `wallets.read`
+- `wallets:transactions.create`
+- `wallets:transactions.sign`
+- `wallets:balance.read`
+
+Create one at [crossmint.com/console](https://www.crossmint.com/console).
+
+You also need a **server recovery signer secret** — any random 32+ char
+string. Generate one with:
+
+```bash
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+This secret is what lets the server recover wallets if the wallet was
+created with a `type: "server"` recovery config. Keep it safe; losing it
+means losing access to wallets created under it.
+
+Copy `.env.example` to `.env` and fill in the values, OR use the
+file-reference pattern if you want secrets to live outside the project
+tree (useful for Docker secrets, Kubernetes secrets, or streaming
+safety):
+
+```bash
+# Either inline:
+CROSSMINT_API_KEY=sk_prod_...
+CROSSMINT_RECOVERY_SECRET=...
+
+# Or by reference:
+CROSSMINT_API_KEY_FILE=/run/secrets/crossmint-api-key
+CROSSMINT_RECOVERY_SECRET_FILE=/run/secrets/crossmint-recovery-secret
+
+# Plus:
+DEFAULT_CHAIN=solana
+SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
+```
+
+## Hook it up to Claude Desktop
+
+Edit `%APPDATA%\Claude\claude_desktop_config.json` on Windows, or
+`~/Library/Application Support/Claude/claude_desktop_config.json` on
+macOS, and add:
+
+```json
+{
+  "mcpServers": {
+    "crossmint-wallets": {
+      "command": "npx",
+      "args": ["-y", "crossmint-wallets-mcp"],
+      "env": {
+        "CROSSMINT_API_KEY": "sk_prod_your_key_here",
+        "CROSSMINT_RECOVERY_SECRET": "your_random_hex_here",
+        "DEFAULT_CHAIN": "solana"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You should see the MCP indicator appear in the
+chat input. Try asking Claude:
+
+> *Create a Crossmint smart wallet on Solana with alias "my-demo".*
+
+Claude will call `crossmint_create_wallet` and return the wallet
+address plus a Solana explorer link. You can then ask:
+
+> *Pay the x402 endpoint at http://my.example.com/paid-data from that
+> wallet, max 0.1 USDC.*
+
+Claude will call `crossmint_pay_x402_endpoint`, move the USDC on-chain,
+and return the paid response.
+
+## Hook it up to other MCP clients
+
+### Continue.dev
+
+In your `~/.continue/config.json`:
+
+```json
+{
+  "experimental": {
+    "modelContextProtocolServers": [
+      {
+        "transport": {
+          "type": "stdio",
+          "command": "npx",
+          "args": ["-y", "crossmint-wallets-mcp"],
+          "env": {
+            "CROSSMINT_API_KEY": "sk_prod_...",
+            "CROSSMINT_RECOVERY_SECRET": "...",
+            "DEFAULT_CHAIN": "solana"
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+### Cline
+
+In the Cline MCP settings panel (gear icon → MCP Servers), add:
+
+- **Name:** `crossmint-wallets`
+- **Command:** `npx`
+- **Args:** `-y crossmint-wallets-mcp`
+- **Env:** same three vars as above
+
+### Codex CLI
+
+In `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.crossmint-wallets]
+command = "npx"
+args = ["-y", "crossmint-wallets-mcp"]
+
+[mcp_servers.crossmint-wallets.env]
+CROSSMINT_API_KEY = "sk_prod_..."
+CROSSMINT_RECOVERY_SECRET = "..."
+DEFAULT_CHAIN = "solana"
+```
+
+## Demo
+
+The repo includes a standalone smoke test that exercises every tool
+against Solana mainnet with real USDC. It:
+
+1. Creates (or loads from cache) a Crossmint smart wallet
+2. Reads its balances
+3. Boots a local x402 paywall server (`demo/paywall-server.ts`)
+4. Calls the paywall, handles the 402, signs + sends the payment via the
+   Crossmint wallet, retries with the `X-PAYMENT` header
+5. Re-reads merchant balances to confirm the transfer landed
+
+Run it:
+
+```bash
+pnpm install
+pnpm tsx demo/create-merchant-wallet.ts  # one-time: create a merchant wallet
+pnpm demo
+```
+
+Expected output (abbreviated):
+
+```
+=== WALLET READY ===
+chain:    solana
+address:  4xHkMCaKVBGw4GtdpeKoNZhGFDMi1tMCJDvXvxUmL8hM
+explorer: https://explorer.solana.com/address/4xHkMCaKVBGw4GtdpeKoNZhGFDMi1tMCJDvXvxUmL8hM
+====================
+
+=== PAYER BALANCES ===
+  native   0.015 (decimals=9)
+  usdc     2.000000 (decimals=6)
+======================
+
+[paywall] listening on http://localhost:4021/paid-data
+[payX402Endpoint] paying 0.01 usdc to Fxr4...yqo on solana...
+[payX402Endpoint] tx confirmed: KRjW2uK7LBioyyy1P3xcJTkpS2ibpCjBq1Ektnf4icL6GH25VnesoCGdQN7DbWYbbyjv9MxHoFrS3hsx7ZgkbEg
+[paywall] 200 — payment verified
+
+=== PAYMENT RESULT ===
+status:    200
+tx sig:    KRjW2uK7LBioyyy1P3xcJTkpS2ibpCjBq1Ektnf4icL6GH25VnesoCGdQN7DbWYbbyjv9MxHoFrS3hsx7ZgkbEg
+======================
+
+=== MERCHANT BALANCES ===
+  usdc     0.01 (decimals=6)
+=========================
+```
+
+The first successful mainnet tx from this repo's smoke test is pinned at
+[`KRjW2uK7LBioyyy1P3xcJTkpS2ibpCjBq1Ektnf4icL6GH25VnesoCGdQN7DbWYbbyjv9MxHoFrS3hsx7ZgkbEg`](https://explorer.solana.com/tx/KRjW2uK7LBioyyy1P3xcJTkpS2ibpCjBq1Ektnf4icL6GH25VnesoCGdQN7DbWYbbyjv9MxHoFrS3hsx7ZgkbEg)
+for anyone who wants to verify the claim on-chain.
+
+## The Solana CPI nuance (and the companion skill)
+
+Crossmint smart wallets on Solana are program-derived addresses (PDAs),
+which means you **cannot** hand-roll a plain SPL token transfer to move
+USDC out of one. The wallet PDA has no private key — only the Crossmint
+wallet program can sign for it, via a cross-program invocation (CPI)
+that wraps the SPL transfer as an inner instruction.
+
+If you try to write the transaction directly, you will get "signer not
+found" or "missing signature" errors and waste a day debugging it. The
+high-level `Wallet.send()` method from the Crossmint SDK handles this
+correctly — it builds a transaction that invokes the Crossmint wallet
+program, which then CPIs into the SPL token program with the right
+authority. `crossmint_transfer_token` and `crossmint_pay_x402_endpoint`
+in this MCP server both use `wallet.send()` under the hood.
+
+The companion repo
+[`crossmint-cpi-skill`](https://github.com/0xultravioleta/crossmint-cpi-skill)
+is a lobster.cash-compatible skill that teaches AI agents this nuance in
+detail, including a working recipe, common errors, and guidance for
+x402 facilitator authors who need to verify Crossmint payments via
+inner-instruction parsing.
+
+## Fees
+
+Crossmint charges a small service fee (approximately 0.001 USDC per
+`wallet.send` operation) for the gasless relayer — Crossmint pays the
+Solana network fee for the transaction, and recovers the cost from the
+payer wallet. Budget for this when setting `maxUsdcAtomic` guardrails on
+`crossmint_pay_x402_endpoint`.
+
+## Environment variables
+
+| Variable                          | Required | Default                                      | Description                                             |
+|-----------------------------------|----------|----------------------------------------------|---------------------------------------------------------|
+| `CROSSMINT_API_KEY`               | yes*     | —                                            | Crossmint server API key                                |
+| `CROSSMINT_API_KEY_FILE`          | yes*     | —                                            | Path to file containing the API key (alternative)      |
+| `CROSSMINT_RECOVERY_SECRET`       | yes*     | —                                            | Server recovery signer (32+ char hex string)           |
+| `CROSSMINT_RECOVERY_SECRET_FILE`  | yes*     | —                                            | Path to file containing the recovery secret            |
+| `DEFAULT_CHAIN`                   | no       | `solana`                                     | `solana`, `base`, or `base-sepolia`                     |
+| `SOLANA_RPC_URL`                  | no       | `https://api.mainnet-beta.solana.com`        | Solana RPC endpoint (override for private RPCs)        |
+
+\* Exactly one of `CROSSMINT_API_KEY` or `CROSSMINT_API_KEY_FILE` is
+required. Same for the recovery secret.
+
+## License
+
+MIT — so Crossmint can fork this repo into the `@crossmint` organization
+with zero friction if they want to ship it as an official package.
+
+## Acknowledgements
+
+- [Crossmint](https://www.crossmint.com) for shipping the smart wallets
+  and the `@crossmint/wallets-sdk` that makes this possible
+- [lobster.cash](https://lobster.cash) for the skill architecture and
+  the CLI that this MCP server is designed to complement
+- [Faremeter](https://github.com/faremeter) for the x402 facilitator
+  pattern that correctly handles CPI inner-instruction verification
+- [The x402 foundation](https://x402.org) for the protocol and the
+  `@x402/core` + `@x402/svm` reference implementation
+- [The Model Context Protocol team](https://modelcontextprotocol.io)
+  for the spec and the TypeScript SDK
+
+## Companion artifact
+
+- [`crossmint-cpi-skill`](https://github.com/0xultravioleta/crossmint-cpi-skill) —
+  the lobster.cash skill that teaches the Solana CPI inner-instruction
+  nuance this MCP server is built around

package/dist/core/client.d.ts

@@ -0,0 +1,24 @@
+import { CrossmintWallets } from "@crossmint/wallets-sdk";
+import type { Chain } from "./types.js";
+/**
+ * Config loader.
+ *
+ * Supports two ways of providing secrets:
+ *   1. Direct env var: CROSSMINT_API_KEY / CROSSMINT_RECOVERY_SECRET
+ *   2. File ref env var: CROSSMINT_API_KEY_FILE / CROSSMINT_RECOVERY_SECRET_FILE
+ *
+ * The file-ref pattern is useful for Docker secrets, Kubernetes secrets, and
+ * for keeping secrets out of any file that could be shown on screen during
+ * streams or pair programming. If both are set, the direct env var wins.
+ */
+export interface CrossmintConfig {
+    apiKey: string;
+    recoverySecret: string;
+    defaultChain: Chain;
+    solanaRpcUrl: string;
+}
+export declare function getConfig(): CrossmintConfig;
+/** Reset the cached config. Only intended for tests. */
+export declare function resetConfigCache(): void;
+export declare function getWalletsClient(): ReturnType<typeof CrossmintWallets.from>;
+//# sourceMappingURL=client.d.ts.map

package/dist/core/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC3E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,KAAK,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAsCD,wBAAgB,SAAS,IAAI,eAAe,CAmB3C;AAED,wDAAwD;AACxD,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAID,wBAAgB,gBAAgB,IAAI,UAAU,CAAC,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAM3E"}

package/dist/core/client.js

@@ -0,0 +1,51 @@
+import { readFileSync } from "node:fs";
+import { createCrossmint, CrossmintWallets } from "@crossmint/wallets-sdk";
+function readSecret(directEnv, fileEnv, label) {
+    const direct = process.env[directEnv];
+    if (direct && direct.trim().length > 0)
+        return direct.trim();
+    const filePath = process.env[fileEnv];
+    if (filePath && filePath.trim().length > 0) {
+        try {
+            return readFileSync(filePath.trim(), "utf8").trim();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`${label}: failed to read from ${fileEnv}=${filePath}: ${msg}`);
+        }
+    }
+    throw new Error(`${label} is required. Set ${directEnv} or ${fileEnv} in your environment.`);
+}
+function parseChain(value, fallback) {
+    const allowed = ["solana", "base", "base-sepolia"];
+    if (!value)
+        return fallback;
+    if (allowed.includes(value))
+        return value;
+    throw new Error(`DEFAULT_CHAIN=${value} is not supported. Allowed: ${allowed.join(", ")}`);
+}
+let cachedConfig = null;
+export function getConfig() {
+    if (cachedConfig)
+        return cachedConfig;
+    const apiKey = readSecret("CROSSMINT_API_KEY", "CROSSMINT_API_KEY_FILE", "CROSSMINT_API_KEY");
+    const recoverySecret = readSecret("CROSSMINT_RECOVERY_SECRET", "CROSSMINT_RECOVERY_SECRET_FILE", "CROSSMINT_RECOVERY_SECRET");
+    const defaultChain = parseChain(process.env.DEFAULT_CHAIN, "solana");
+    const solanaRpcUrl = process.env.SOLANA_RPC_URL?.trim() || "https://api.mainnet-beta.solana.com";
+    cachedConfig = { apiKey, recoverySecret, defaultChain, solanaRpcUrl };
+    return cachedConfig;
+}
+/** Reset the cached config. Only intended for tests. */
+export function resetConfigCache() {
+    cachedConfig = null;
+}
+let cachedWalletsClient = null;
+export function getWalletsClient() {
+    if (cachedWalletsClient)
+        return cachedWalletsClient;
+    const { apiKey } = getConfig();
+    const crossmint = createCrossmint({ apiKey });
+    cachedWalletsClient = CrossmintWallets.from(crossmint);
+    return cachedWalletsClient;
+}
+//# sourceMappingURL=client.js.map

package/dist/core/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAqB3E,SAAS,UAAU,CACjB,SAAiB,EACjB,OAAe,EACf,KAAa;IAEb,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACtC,IAAI,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IAE7D,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3C,IAAI,CAAC;YACH,OAAO,YAAY,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QACtD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7D,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,yBAAyB,OAAO,IAAI,QAAQ,KAAK,GAAG,EAAE,CAC/D,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,qBAAqB,SAAS,OAAO,OAAO,uBAAuB,CAC5E,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,KAAyB,EAAE,QAAe;IAC5D,MAAM,OAAO,GAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC;IAC5D,IAAI,CAAC,KAAK;QAAE,OAAO,QAAQ,CAAC;IAC5B,IAAK,OAAoB,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAc,CAAC;IACjE,MAAM,IAAI,KAAK,CACb,iBAAiB,KAAK,+BAA+B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC1E,CAAC;AACJ,CAAC;AAED,IAAI,YAAY,GAA2B,IAAI,CAAC;AAEhD,MAAM,UAAU,SAAS;IACvB,IAAI,YAAY;QAAE,OAAO,YAAY,CAAC;IAEtC,MAAM,MAAM,GAAG,UAAU,CACvB,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,CACpB,CAAC;IACF,MAAM,cAAc,GAAG,UAAU,CAC/B,2BAA2B,EAC3B,gCAAgC,EAChC,2BAA2B,CAC5B,CAAC;IACF,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;IACrE,MAAM,YAAY,GAChB,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,EAAE,IAAI,qCAAqC,CAAC;IAE9E,YAAY,GAAG,EAAE,MAAM,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;IACtE,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,gBAAgB;IAC9B,YAAY,GAAG,IAAI,CAAC;AACtB,CAAC;AAED,IAAI,mBAAmB,GAAoD,IAAI,CAAC;AAEhF,MAAM,UAAU,gBAAgB;IAC9B,IAAI,mBAAmB;QAAE,OAAO,mBAAmB,CAAC;IACpD,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,CAAC;IAC/B,MAAM,SAAS,GAAG,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9C,mBAAmB,GAAG,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACvD,OAAO,mBAAmB,CAAC;AAC7B,CAAC"}

package/dist/core/create-wallet.d.ts

@@ -0,0 +1,17 @@
+import type { Chain, CreateWalletResult } from "./types.js";
+/**
+ * Creates a Crossmint smart wallet on the given chain, using the configured
+ * server recovery signer. This is idempotent for a given (API key + recovery
+ * secret + owner) tuple — calling it twice yields the same wallet.
+ *
+ * The `owner` field is an optional free-form identifier (email, user id,
+ * hashed handle, etc). It is passed straight through to the Crossmint API
+ * so downstream tools can resolve a wallet by owner later.
+ */
+export declare function createWallet(opts: {
+    chain: Chain;
+    owner?: string;
+    alias?: string;
+}): Promise<CreateWalletResult>;
+export declare function getExplorerLink(address: string, chain: Chain): string;
+//# sourceMappingURL=create-wallet.d.ts.map

package/dist/core/create-wallet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-wallet.d.ts","sourceRoot":"","sources":["../../src/core/create-wallet.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAwB9B;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,CASrE"}

package/dist/core/create-wallet.js

@@ -0,0 +1,44 @@
+import { getConfig, getWalletsClient } from "./client.js";
+/**
+ * Creates a Crossmint smart wallet on the given chain, using the configured
+ * server recovery signer. This is idempotent for a given (API key + recovery
+ * secret + owner) tuple — calling it twice yields the same wallet.
+ *
+ * The `owner` field is an optional free-form identifier (email, user id,
+ * hashed handle, etc). It is passed straight through to the Crossmint API
+ * so downstream tools can resolve a wallet by owner later.
+ */
+export async function createWallet(opts) {
+    const { chain, owner, alias } = opts;
+    const { recoverySecret } = getConfig();
+    const wallets = getWalletsClient();
+    // Crossmint's owner field is a user locator — valid formats are the
+    // literal "COMPANY" or prefixed strings like "email:x@y.com",
+    // "userId:abc", "phoneNumber:+123", "twitter:handle", "x:handle". Free-form
+    // strings are rejected server-side. If the caller did not provide a
+    // locator, we omit the field entirely so the wallet is owned by the API
+    // key account (no specific user).
+    const wallet = await wallets.createWallet({
+        chain,
+        ...(owner ? { owner } : {}),
+        ...(alias ? { alias } : {}),
+        recovery: { type: "server", secret: recoverySecret },
+    });
+    return {
+        owner: owner ?? null,
+        chain,
+        address: wallet.address,
+        explorerLink: getExplorerLink(wallet.address, chain),
+    };
+}
+export function getExplorerLink(address, chain) {
+    switch (chain) {
+        case "solana":
+            return `https://explorer.solana.com/address/${address}`;
+        case "base":
+            return `https://basescan.org/address/${address}`;
+        case "base-sepolia":
+            return `https://sepolia.basescan.org/address/${address}`;
+    }
+}
+//# sourceMappingURL=create-wallet.js.map

package/dist/core/create-wallet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-wallet.js","sourceRoot":"","sources":["../../src/core/create-wallet.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG1D;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAIlC;IACC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;IACrC,MAAM,EAAE,cAAc,EAAE,GAAG,SAAS,EAAE,CAAC;IACvC,MAAM,OAAO,GAAG,gBAAgB,EAAE,CAAC;IAEnC,oEAAoE;IACpE,8DAA8D;IAC9D,4EAA4E;IAC5E,oEAAoE;IACpE,wEAAwE;IACxE,kCAAkC;IAClC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC;QACxC,KAAK;QACL,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3B,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3B,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE;KACrD,CAAC,CAAC;IAEH,OAAO;QACL,KAAK,EAAE,KAAK,IAAI,IAAI;QACpB,KAAK;QACL,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,YAAY,EAAE,eAAe,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC;KACrD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,KAAY;IAC3D,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,QAAQ;YACX,OAAO,uCAAuC,OAAO,EAAE,CAAC;QAC1D,KAAK,MAAM;YACT,OAAO,gCAAgC,OAAO,EAAE,CAAC;QACnD,KAAK,cAAc;YACjB,OAAO,wCAAwC,OAAO,EAAE,CAAC;IAC7D,CAAC;AACH,CAAC"}

package/dist/core/get-balance.d.ts

@@ -0,0 +1,16 @@
+import type { BalanceResult, Chain } from "./types.js";
+/**
+ * Reads the on-chain balances for a Crossmint wallet by address. Returns
+ * the native token (SOL/ETH), USDC (always included per SDK contract),
+ * and any other token balances the wallet holds.
+ *
+ * This is the Phase 4 Task 4.1 implementation from
+ * 03-mcp-build-and-skill-plan.md, lifted forward so we can verify funding
+ * before running Tool 4 (pay_x402_endpoint).
+ */
+export declare function getBalance(opts: {
+    address: string;
+    chain: Chain;
+    tokens?: string[];
+}): Promise<BalanceResult>;
+//# sourceMappingURL=get-balance.d.ts.map

package/dist/core/get-balance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-balance.d.ts","sourceRoot":"","sources":["../../src/core/get-balance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAgB,MAAM,YAAY,CAAC;AAErE;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB,GAAG,OAAO,CAAC,aAAa,CAAC,CAsBzB"}

package/dist/core/get-balance.js

@@ -0,0 +1,31 @@
+import { getWalletsClient } from "./client.js";
+/**
+ * Reads the on-chain balances for a Crossmint wallet by address. Returns
+ * the native token (SOL/ETH), USDC (always included per SDK contract),
+ * and any other token balances the wallet holds.
+ *
+ * This is the Phase 4 Task 4.1 implementation from
+ * 03-mcp-build-and-skill-plan.md, lifted forward so we can verify funding
+ * before running Tool 4 (pay_x402_endpoint).
+ */
+export async function getBalance(opts) {
+    const { address, chain, tokens } = opts;
+    const wallets = getWalletsClient();
+    const wallet = await wallets.getWallet(address, { chain });
+    const raw = await wallet.balances(tokens);
+    const formatted = [
+        { symbol: "native", amount: raw.nativeToken.amount, decimals: raw.nativeToken.decimals ?? 0 },
+        { symbol: "usdc", amount: raw.usdc.amount, decimals: raw.usdc.decimals ?? 0 },
+        ...raw.tokens.map((t) => ({
+            symbol: t.symbol,
+            amount: t.amount,
+            decimals: t.decimals ?? 0,
+        })),
+    ];
+    return {
+        address,
+        chain,
+        balances: formatted,
+    };
+}
+//# sourceMappingURL=get-balance.js.map

package/dist/core/get-balance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-balance.js","sourceRoot":"","sources":["../../src/core/get-balance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAIhC;IACC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxC,MAAM,OAAO,GAAG,gBAAgB,EAAE,CAAC;IAEnC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3D,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE1C,MAAM,SAAS,GAAmB;QAChC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,WAAW,CAAC,QAAQ,IAAI,CAAC,EAAE;QAC7F,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,EAAE;QAC7E,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACxB,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,QAAQ,EAAE,CAAC,CAAC,QAAQ,IAAI,CAAC;SAC1B,CAAC,CAAC;KACJ,CAAC;IAEF,OAAO;QACL,OAAO;QACP,KAAK;QACL,QAAQ,EAAE,SAAS;KACpB,CAAC;AACJ,CAAC"}

package/dist/core/pay-x402-endpoint.d.ts

@@ -0,0 +1,36 @@
+import type { Chain, PayX402Result } from "./types.js";
+/**
+ * Pay an x402-protected HTTP endpoint using a Crossmint smart wallet.
+ *
+ * Flow:
+ *   1. Fetch `url` with the caller's original headers/body
+ *   2. If the server responds 200, return directly — nothing to pay
+ *   3. If the server responds 402, parse the PaymentRequired body and pick
+ *      the first PaymentRequirements entry on a supported chain (Solana
+ *      mainnet in v0.1)
+ *   4. Load the payer wallet via `wallets.getWallet(payerAddress, ...)`,
+ *      passing the server recovery signer through the args so the
+ *      returned Wallet has its `#recovery` field populated. Without this,
+ *      the SDK's useSigner path crashes because `isRecoverySigner` tries
+ *      to call `.startsWith` on an undefined secret (chunk-XNZLCUTY:395).
+ *      The WalletArgsFor TypeScript type doesn't declare a `recovery`
+ *      field, but the runtime `createWalletInstance` reads it when
+ *      present, so we pass it via an explicit cast.
+ *   5. Call `wallet.send(payTo, tokenSymbol, decimalAmount)` — Crossmint
+ *      handles the CPI inner instruction wrapping, signing via the server
+ *      recovery signer, fee payment, and confirmation internally
+ *   6. Build the X-PAYMENT header as base64(JSON(PaymentPayload)) with the
+ *      resulting transaction signature in the payload
+ *   7. Retry the original request with the X-PAYMENT header appended
+ *   8. Return the response body plus the on-chain tx signature
+ */
+export declare function payX402Endpoint(opts: {
+    url: string;
+    payerAddress: string;
+    chain: Chain;
+    headers?: Record<string, string>;
+    method?: string;
+    jsonBody?: unknown;
+    maxUsdcAtomic?: bigint;
+}): Promise<PayX402Result>;
+//# sourceMappingURL=pay-x402-endpoint.d.ts.map

package/dist/core/pay-x402-endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pay-x402-endpoint.d.ts","sourceRoot":"","sources":["../../src/core/pay-x402-endpoint.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAyEvD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,aAAa,CAAC,CAuIzB"}