![\"Dexter\"](\"https://raw.githubusercontent.com/Dexter-DAO/dexter-x402-sdk/main/assets/dexter-wordmark.svg\")
\n\n \n
\n Composable MCP registrations for finding, pricing, and calling x402 services.\n
\n\nThis is the shared registration library used by the local\n[`@dexterai/opendexter`](https://www.npmjs.com/package/@dexterai/opendexter)\nCLI/MCP package. It provides tool schemas and adapters; it does not provide a\nwallet, durable store, or hosted account by itself.\n\nThe hosted OpenDexter connector has its own reviewed server lineage. Sharing a\nwire contract does not mean the local and hosted runtimes have identical wallet\nor execution capabilities.\n\n## Install\n\nUse Node.js 22 or newer with these package versions:\n\n```bash\nnpm install @dexterai/x402-mcp-tools@0.9.2 \\\n @dexterai/x402@6.0.3 @dexterai/vault@0.43.4\n```\n\n\n## Register the x402 tools\n\n```ts\nimport {\n buildToolMetas,\n composeAllTools,\n} from \"@dexterai/x402-mcp-tools\";\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\n\nconst server = new McpServer({\n name: \"my-opendexter-server\",\n version: \"1.0.0\",\n});\n\ncomposeAllTools(server, {\n apiBaseUrl: \"https://x402.dexter.cash\",\n metas: buildToolMetas(widgetUris),\n wallet,\n getTabLane,\n getPurchaseAttemptStore,\n getMaxAmountUsdc,\n getBudgetRuntime,\n});\n```\n\n`composeAllTools` installs five registrar families. For backward compatibility,\nthe fetch registrar exposes both `x402_fetch` and its exact alias `x402_pay` by\ndefault. New product surfaces should set `registerPayAlias: false` and expose\nonly the canonical fetch name:\n\n```ts\ncomposeAllTools(server, {\n // ...\n registerPayAlias: false,\n});\n```\n\nThe compatibility-default roster is:\n\n| Tool | What it does | Can move money |\n|---|---|---|\n| `x402_search` | Finds services by capability | No |\n| `x402_check` | Reads current terms and prepares explicit purchase choices | No payment |\n| `x402_access` | Presents a wallet-control proof to SIWX services | No payment |\n| `x402_fetch` | Executes one approved prepared purchase | Yes |\n| `x402_pay` | Exact alias of `x402_fetch` | Yes |\n| `x402_wallet` | Reads the injected wallet view | No |\n\nThere are no Dextercard MCP registrars. Card operations retained in this\npackage support non-tool wallet/card surfaces and legacy consumers only.\n\n## The purchase contract\n\n`x402_check` returns `purchaseOptions`. Each option uses one explicit mode:\n\n- `direct_exact`\n- `native_tab`\n- `gateway_cash`\n- `gateway_credit`\n\nThe option preserves:\n\n- the original and resolved public HTTPS URL;\n- method and request-body digest;\n- the complete seller accept through `rawAcceptSha256`;\n- network, asset, atomic amount, recipient, and expiry;\n- route, offer, mode, and prepared identities.\n\nAmounts and ceilings are positive decimal strings. They are never reconstructed\nfrom display prices.\n\nA mode is `ready` only when its concrete wallet/adapter exists and its prepared\nidentity has been written to the injected durable store. Missing capabilities\nproduce `integration_required` or `unavailable`; a caller must not silently\nswitch modes.\n\nAfter explicit approval, pass the selected option's `preparedPurchase`\nunchanged to `x402_fetch.purchase` and pass the approved atomic ceiling as\n`maxAmountAtomic`. MCP consumers normally call `composeAllTools` and inject the\nsame durable store into check and fetch.\n\n## Required adapters\n\n### Wallet\n\n`WalletAdapter` supplies verified balances and the signers that actually exist\non the current surface. Passing `null` makes money execution unavailable.\n\n### Durable purchase store\n\nThe preparation/attempt store must:\n\n1. persist a prepared identity before check reports it as ready;\n2. atomically claim that same identity before execution;\n3. mark dispatching before sending a proof or voucher;\n4. preserve terminal and reconciliation receipts;\n5. reject caller-synthesized or mismatched identities.\n\nThere is intentionally no in-memory fallback for explicit purchases.\n\n### Native Tab\n\n`getTabLane` supplies the local Native Tab executor. If it is absent,\n`native_tab` is not ready. Native Tab never falls through to Direct Exact after\nselection or consequential dispatch.\n\nV6 grant tabs require a context-bound high-bit grant and a\n`reserveFinalVoucherV2` provider. Server consumers can construct that provider\nwith `createManagedFinalVoucherV2Reservation`, using the facilitator's internal\nactuator credential only on the server. The helper obtains the provider\nreceipt; `tabFromGrant` then validates it and independently reads the submitted\nSolana transaction and coherent post-state at `confirmed` or stronger before\nreleasing the signed claim. The interactive request does not wait for\n`finalized` commitment.\nA provider receipt by itself is not proof.\n\nHistorical low-bit grants require explicit owner reapproval. V2 reservation,\nsigning, response-loss, and seller-refusal outcomes are terminal for the call:\npreserve the exact claim and reconcile it instead of rolling back or selecting\nanother payment rail.\n\n## Receipts and retries\n\nReceipts keep four different facts separate:\n\n- Direct Exact seller settlement;\n- Native Tab voucher acceptance and seller cash settlement;\n- Gateway cash commitment and seller settlement;\n- Gateway credit exposure, buyer obligation, and seller settlement.\n\nAn unknown or post-dispatch outcome is reconciliation-only. Do not\nautomatically send the request again. A new prepared identity is not permission\nto duplicate an uncertain prior attempt.\n\nSee [PURCHASE-CONTRACT.md](./PURCHASE-CONTRACT.md) for the typed integration\ncontract.\n\n## Widget metadata\n\n`buildToolMetas` creates the dual metadata used by MCP Apps hosts and ChatGPT\nApps SDK hosts. Each consumer supplies its own content-hashed `ui://` resource\nURIs.\n\n## Package boundary\n\nThis package contains registrars and contracts. It does not:\n\n- create or migrate wallets;\n- choose a user's funding mode;\n- implement Gateway/CrossPay;\n- provide the hosted OpenDexter OAuth connector;\n- deploy, publish, or mutate a running MCP server.\n\n## Links\n\n- [OpenDexter local package](https://www.npmjs.com/package/@dexterai/opendexter)\n- [Dexter](https://dexter.cash)\n- [x402](https://x402.org)\n\n## License\n\nMIT\n","readmeFilename":"README.md"}