dsh-x402-wallet

English | 中文

A visual x402 payment wallet for DeepSeek Harness. Install one bundle and your agent can discover paid APIs, estimate their cost, and pay-and-call them over the x402 protocol — while a Phantom-style wallet popup gives you multi-wallet custody, QR receive, USDC send, and on-chain activity, all inside the DSH web GUI.

dsh plugin --profile web add @danielng23/dsh-x402-wallet

Restart dsh web — the x402 Wallet entry appears in the sidebar.

What it is

• Your agent can pay for APIs. Four model tools (x402_discover, x402_estimate, x402_balance, x402_pay) discover x402-enabled APIs, probe their price without paying, and pay-and-call them with a spend cap and your approval.
• Your wallet is a first-class GUI surface. A Phantom-style popup manages several wallets (create/import/switch), shows the USDC balance, a QR receive screen, an on-chain transfer history, and a send form — no CLI, no extension, no separate browser. The popup also browses the pay-as-you-go API catalog, switches networks live, exports keystore backups and payment records, and filters history by status/URL/wallet. A live balance pill sits in the sidebar, and the DSH Settings page hosts an x402 card (network, budgets, approval policy) whose changes apply immediately.
• Spend is guarded. A per-call ceiling and a daily budget are enforced before anything is signed, and a host allowlist/blocklist gates which APIs can be paid (trustedHosts, blockedHosts, requireTrustedHost).
• Usable from chat too. /wallet, /balance, and /send <address> <amount> composer commands drive the wallet from any interactive adapter.
• Keys never leave your machine. Private keys live only in the Host credential store; the model, the logs, and the browser page never see them.

How x402 payments work

The wallet speaks the x402 protocol natively with the exact (EIP-3009) scheme: the wallet signs a transfer authorization and the gateway settles on-chain, so the wallet pays no gas. Every paid call enforces maxCostUsdc (abort before signing when the cost exceeds the cap) and asks for your approval with the exact amount first.

Two different transfers, one wallet:

Try it free on testnet

No real money needed: point the host service at Base Sepolia and grab testnet USDC from the in-app faucet link on the receive screen.

# cordis.yml patch rows with a testnet config
- insert:
    - id: x402
      name: '@danielng23/dsh-x402'
      config:
        network: eip155:84532
        rpcUrl: https://sepolia.base.org
    - id: ui-x402
      name: '@danielng23/dsh-client-ui-x402'

Create a wallet, open Receive, and follow the Get testnet USDC link to fund it — then ask the agent to pay for an API.

Install

Published on the npm registry (any DSH installation):

dsh plugin --profile web add @danielng23/dsh-x402-wallet

From this checkout (development):

# installs the local checkout; the `file:` prefix is required — a bare path is
# recorded as pnpm `link:`, which skips installing the bundle's host/ui
# dependencies (see "Local development" below). `pnpm` must be on PATH.
dsh plugin --profile web add file:/absolute/path/to/dsh-x402-wallet/packages/bundle

To undo: dsh plugin --profile web remove @danielng23/dsh-x402-wallet. The wallet is opt-in — the shipped DSH web profile does not include it.

Local development (test before release)

Looking for the general pattern to build and test other DSH plugins the same way? See LOCAL_DEVELOPMENT.md.

Everything below writes only to ~/.dsh (your profile directory); the harness checkout is never modified. Requires a run-from-source harness checkout (built with pnpm run build) and Node ^22.19.0 || >=24.0.0.

# 1. Build the plugin packages (tsc + tsdown emit lib/ for host and ui)
cd /path/to/dsh-x402-wallet
pnpm build
node scripts/repoint-typert.mjs   # only after a typert regeneration — see Known issues

# 2. Install the local checkout into the web profile (run from the harness checkout)
cd /path/to/deepseek-harness
pnpm dsh plugin --profile web add file:/absolute/path/to/dsh-x402-wallet/packages/bundle

# 3. Verify the composed layer without booting
pnpm dsh --profile web --dump-config   # look for "# == @danielng23/dsh-x402-wallet"

# 4. Boot the GUI on a non-default port (the default is 3080)
pnpm dsh web --port 3081               # open http://127.0.0.1:3081 and hard-refresh (⌘⇧R)

Iteration loop — the profile holds copies, not symlinks, so after editing sources you must refresh them before restarting:

cd /path/to/dsh-x402-wallet && pnpm build
cd ~/.dsh/profiles/web && pnpm install   # re-copies the rebuilt lib/ from the checkout
# then restart: cd /path/to/deepseek-harness && pnpm dsh web --port 3081

Notes:

• dsh creates every profile with autoInstallPeers: false and nodeLinker: hoisted, so the @deepseek-ai/* peer packages are not fetched from npm — they resolve at runtime from the healed $DSH_HOME/profiles/node_modules fallback. Only the non-DSH dependencies (@x402/*, viem, schemastery, zod, react-qr-code) are installed.
• A clean boot prints dsh web: http://127.0.0.1:3081 and no did not activate error; the boot audit throws on any pending entry, so a running server means the whole plugin tree settled.
• Before publishing, follow the Publish flow: the bundle's file: deps must be flipped to ^ ranges (node scripts/prepublish.mjs) and lib/ must be freshly built.

Roadmap

Live tracker of planned, in-progress, and shipped features; details and delivery order live in ROADMAP.md. One feature per release — each ships tested, verified, and version-noted below.

• 1. Real-time settlement push to the GUI — fix Known issue #1 (event forwarding) so the popup repaints the instant a payment settles instead of polling.
• 2. Agent spend visibility — x402_spend / x402_receipts tools and /spend / /payments composer commands: the model can report today's spend vs. budget and verify what it paid.
• 3. Budget-race lock — atomic per-day budget reservation so two concurrent x402_pay calls can never overspend the daily budget.
• 4. Custody completeness — reveal the recovery mnemonic, rename wallets, and delete wallets (with key purge).
• 5. Scoped budgets — per-session, per-wallet, and per-host budgets.
• 6. Protocol depth — capped payment scheme, bounded retry/backoff, and idempotency keys.
• 7. Per-host caps + approval rate-limiting — security hardening for trusted hosts and prompt spam.
• 8. Trusted-hosts allowlist UI — manage trustedHosts / blockedHosts from the Settings card.
• 9. Address book + ENS + watch-only wallets + ETH/gas view.
• 10. Spend analytics, activity detail drawer, browser notifications.
• 11. Fiat on-ramp top-up + catalog upgrades (sort by price, network filter, "ask the agent to call this").
• 12. Locale expansion beyond en/zh.

Wallet setup

1. Open the wallet popup and Create wallet (generate or import a private key), or keep the legacy single-key credential X402_PRIVATE_KEY.
2. Fund the selected wallet with a few USDC on Base — the receive screen shows the address and a QR code.
3. Ask the agent for a task that needs a paid API; the approval prompt shows the exact amount and recipient before anything is signed.

Repository layout

packages/host/     @danielng23/dsh-x402             host service + tools + /remote
packages/ui/       @danielng23/dsh-client-ui-x402   browser GUI (dsh.client manifest)
packages/bundle/   @danielng23/dsh-x402-wallet      installable patch layer

Website

Product site: https://ph4310822.github.io/dsh-x402-wallet/ (static, in docs/).

Ecosystem position

• Built on the DeepSeek Harness plugin system — everything is a plugin; this bundle is two rows in a cordis.yml patch layer.
• Speaks the x402 payment protocol (exact / EIP-3009) against the public x402 catalog.
• The same packages live upstream in the DSH monorepo (packages/x402/x402, packages/client/ui-x402) and ship here as a standalone, installable distribution.

Publish (maintainers)

The three packages publish in dependency order, host → ui → bundle:

# bump each version first (e.g. npm version patch), then:
node scripts/regen-typert.mjs           # after any @Remote surface change (see Known issues)
node scripts/prepublish.mjs              # flips the bundle's file: deps to ^ ranges (npm can't resolve file:)
npm publish ./packages/host
npm publish ./packages/ui
npm publish ./packages/bundle
git checkout packages/bundle/package.json   # restore the file: specs for local development

packages/host and packages/ui ship their built lib/ (the /remote typert artifacts included). Rebuilding from source requires the DSH repository's typert generator; build there and copy lib/ back, then run node scripts/repoint-typert.mjs to restore the @danielng23 scope (see Known issues), or keep the committed artifacts. Publishing requires npm two-factor authentication (recovery code or authenticator).

Before the first publish, run a clean-room check that simulates the npm experience in a scratch home:

DSH_HOME=/tmp/dsh-release-check pnpm dsh plugin --profile web add @danielng23/dsh-x402-wallet
DSH_HOME=/tmp/dsh-release-check pnpm dsh web --port 3082   # open the wallet there

Known issues and limitations

1. Payment-completion auto-refresh in the GUI is inert. The wallet subscribes to the host's x402/payment event via ctx.remote.$on, but the harness forwards only its own allowlist (API_REMOTE_FORWARDED_EVENTS in @deepseek-ai/dsh-api-remotes) to the browser, and x402/payment is not on it. The event therefore never reaches the client: wallet operations and manual refresh work, but the popup will not auto-refresh the instant a payment settles. Fixing it requires the harness to allowlist the event (or the plugin to poll).
2. The Typert artifacts regenerate via a vendored protocol copy. The harness's generator only recognizes @deepseek-ai/dsh-typert-protocol symbols when that package is registered under the workspace's packages/; scripts/regen-typert.mjs satisfies that by vendoring a copy of the protocol package at packages/_vendor/protocol (with a paths override in tsconfig.host.json). Run it after changing the host's @Remote surface, then node scripts/repoint-typert.mjs as a scope safeguard. A stale artifact (wrong package field or missing methods) makes the typert-loader reject the host face and the wallet's RPC endpoints misbehave (HTTP 404 or missing methods).
3. Profile installs are copies, not live links. The profile's file: install snapshots lib/ at install time; after editing sources you must pnpm build and re-run pnpm install in the profile, then restart dsh web. A stale profile copy is the usual cause of "bundle loaded without registering" (loader-id mismatch) or a missing GUI.
4. Node engine. The workspace targets ^22.19.0 || >=24.0.0; running on other versions (e.g. v23) works but prints an unsupported-engine warning — pin 22/24 (e.g. with nvm) for a clean run.
5. Peer packages come from the DSH installation, not npm (see Security stance): dsh-created profiles set autoInstallPeers: false, so @deepseek-ai/* peers are resolved from the healed profiles/node_modules fallback and are never fetched from the registry.

Security stance

• The wallet moves real money on a real network. Treat it like shell access with a budget.
• Keep approvalRequired true (the default) in any deployment that touches real funds.
• A key exposure costs only the dedicated spending float.
• Peer dependencies (@deepseek-ai/dsh-*, @deepseek-ai/cordis) resolve from the DSH installation; only the non-DSH dependencies (@x402/*, viem, schemastery, zod, react-qr-code) are fetched from npm.

Version notes

License

MIT