Shinjuku Shielded

io.github.ShinjukuStaitionv0.1.1Updated Oct 8, 2026

Private x402 payments on Solana: shield, pay, and unshield USDC under caps you set.

VerifiedSTDIODesktop onlySecurity & MonitoringFinance

Overview

AI-generated overview

A local MCP server that lets an agent make private x402 USDC payments on Solana from a shielded balance, under spending caps you set.

What it does
It exposes tools for shielded USDC payments on Solana: wallet_balance shows shielded and unshielded balances, wallet_shield moves USDC into the shielded balance, x402_preview checks a seller's price against your caps without paying, x402_pay pays a URL and returns the answer, wallet_unshield sends shielded USDC to a public address, wallet_receipts lists recent receipts, and wallet_cancel releases an unfinished payment. Caps and per-host limits are set at launch and tool calls can only lower them.
When to use it
Use it when an agent needs to pay x402-enabled sellers or APIs from a self-custodied Solana wallet while keeping the payer hidden on chain, and when you want hard per-payment and per-session spending limits enforced locally.
Requirements
Runs locally over stdio as the npm package shinjuku-shielded via npx, needing Node.js 22 or later. Requires a wallet folder set by SHIELDED_WALLET_HOME and a passphrase supplied at start via --passphrase-file or SHIELDED_WALLET_PASSPHRASE. --max-payment and --max-session are required at launch. Optional flags enable Tor, shield and unshield proof tools, and your own Solana RPC. No account or API key is needed.
Before you install
It handles real money: x402_pay spends USDC, wallet_shield deposits it, and wallet_unshield sends it out. The passphrase is read from --passphrase-file or SHIELDED_WALLET_PASSPHRASE at start, never from a tool call. Without --max-unshield a confirmed send can move the whole shielded balance. By default payments go through the provider's relay, which sees your IP and which accounts the wallet reads; --tor hides your IP. The agent host and model provider see every URL, price, and unshield…

Installation

In SourceWeft

  1. Open Shinjuku Shielded in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[Shinjuku Shielded MCP: the private x402 facilitator, inside your agent]

[Solana mainnet] [x402 facilitator] [MCP] [Self-custody] [Tor]

Shinjuku Shielded MCP

The private x402 facilitator, inside your agent.

Shinjuku Shielded settles x402 payments from a shielded USDC balance on Solana: on chain, a shielded payment does not show who paid. This MCP server is how your agent uses it. It runs on your machine, under caps that only you set.

  • Self-custody. The server runs on your machine. Your keys never leave it. We never run it, and we never hold your money.
  • Shielded payments. Your agent pays from a shielded balance. Add --tor and no server sees your IP.
  • Caps that only you set. --max-payment and --max-session are required at launch. A tool call can only lower them, never raise them.
  • Look before you pay. x402_preview shows the price and whether your caps allow it. It pays nothing.
  • Never twice. A retry with the same request_id resumes the same payment, deposit, or unshield. It never starts a second one.
  • No RPC, no account, no API key. Reads go through our relay by default. Your own RPC always wins if you give one.

Every Shinjuku Shielded service joins this MCP as it ships.

The server is the mcp command of shinjuku-wallet, one file. This repository holds the setup guide and examples. The wallet file, its SHA-256, and its release history are in ShinjukuStaition/shinjuku-shielded.

Talk to it in plain words

Ask your agent the way you would ask a person:

You sayYour agent calls
"what is my balance"wallet_balance
"shield 5 USDC"wallet_shield
"pay this URL"x402_preview, then x402_pay
"send 2 USDC privately to "wallet_unshield

Each answer tells the agent the exact next call. The wallet reads the chain and writes an encrypted backup by itself, so you never run a command for upkeep.

Tools

SHIELD

ToolWhat it does
wallet_shieldMoves USDC from the wallet's own Solana key into your shielded balance. It is on with --proof-tools. --no-shield turns it off. Funding takes minutes: the first call starts it and returns a stage. Call again with the same request_id to see the stage. It never starts a second deposit. When the deposit lands, the wallet reads it from the chain and writes an encrypted backup. The wallet's own key needs the USDC and about 0.01 SOL.

PAY

ToolWhat it does
x402_previewOne unpaid request. Returns the seller's price, the scheme, and whether your caps allow it. Pays nothing.
x402_payPays the URL (if it asks for payment) and returns the answer. A URL that does not answer 402 is fetched once and nothing is paid. Alias: fetch_paid.

UNSHIELD

ToolWhat it does
wallet_unshieldSends shielded USDC to a public Solana address. It is on with --exit-proof-tools and --profile. Our facilitator pays every network fee. The same request_id never unshields twice. An address that you named with --unshield-to is sent at once. Any other address is sent only after you confirm it in your MCP client: "Send X USDC from your shielded balance to ?". A decline, or no answer in 5 minutes, sends nothing. A client that cannot ask is refused, so a prompt injection cannot pick an address by itself. The wallet's own key is refused: it made the deposits, so an exit there would link them.

ACCOUNT

ToolWhat it does
wallet_balanceSHIELDED (what your agent can pay with) and UNSHIELDED (plain USDC on the wallet's own Solana key), each on its own line, plus pockets, unfinished payments, and what this session may still pay. A stale balance is read from the chain first. UNSHIELDED is one network read; if it fails, that line is empty and says why.
wallet_receiptsYour most recent paid receipts: host (never the full URL), amount, transaction, time.

Also: wallet_cancel closes one unfinished payment, so its reserved balance comes back.

wallet_shield and wallet_unshield always appear in the tool list. When one is off, it answers "error": "mcp_tool_disabled" and tells the agent what to ask you.

What it pays: x402 scheme shielded-exact from your shielded balance, and standard Solana exact from a ready pocket. A ready pocket pays any Solana x402 exact seller, whichever facilitator settles it. For sellers that offer only confidential (hidden amounts), use shinjuku-wallet laneb pay-url.

Privacy modes

Default--tor
On chainA shielded payment does not show who paid.The same.
Your IPPayments go to pay.shinjukustaition.com, with no CDN in the path. Our server sees your IP. It keeps no access logs.Hidden from everyone, us included.
The sellerSees your IP.Does not see your IP.
SpeedFaster.About 1-2 s slower per request.
NeedsNothing extra.Tor with HTTPTunnelPort 127.0.0.1:9080 IsolateDestAddr in torrc.

Setup

You need Node.js 22 or later. The current wallet release is 1a336885.

Fastest install (npm)

The npm package [email protected] is wallet release 1a336885. It has two commands: shinjuku-shielded and shinjuku-wallet. npx gets it for you:

sh
npx -y shinjuku-shielded help mcp

Or download the file and check it

Download the release file and check its SHA-256 before you run it. The current file and hash are also in the Releases table and in section 7b of https://shinjukustaition.com/skill.md.

sh
curl -fsSLO https://shinjukustaition.com/wallet/1a336885/shinjuku-wallet.mjsecho "1a3368854f4bdfe185a2ac398106c9b39a7148225f1a3ec6a6dcead563c7ed53  shinjuku-wallet.mjs" | sha256sum -c -node shinjuku-wallet.mjs help mcp

With the file, replace npx -y shinjuku-shielded below with node /abs/path/shinjuku-wallet.mjs.

Make and fund the wallet

Follow https://shinjukustaition.com/skill.md section 7b: init, the proof tools, and funding your shielded balance. The proof tools are a separate download with both install options (Linux, or WSL on Windows; about 144 MB, every file hash-checked). help init and help add-funds say the same on your machine. Your agent can also fund the shielded balance itself with wallet_shield.

Add it to your agent

The session flags for the production pool:

--pool AAG16mNWTtC1sBeu2tTVTwWjqWXCefLTCByVPj5X3kV8--program 8PYPw3FSFTMbvSneXdcoH6jNoN4VD23nHwPY2A2riUy1--memo-service https://pay.shinjukustaition.com--proof-tools /abs/path/shinjuku-proof-tools/proof-tools.json--exit-proof-tools /abs/path/shinjuku-proof-tools/exit-proof-tools.json--profile /abs/path/shinjuku-proof-tools/public-profile.json--passphrase-file /abs/path/passphrase.txt

Caps are in atomic USDC units: 50000 = 0.05 USDC. --proof-tools turns wallet_shield on. --exit-proof-tools and --profile (both in the shinjuku-proof-tools folder) turn wallet_unshield on.

Claude Code
sh
claude mcp add shinjuku -- npx -y shinjuku-shielded mcp \  --max-payment 50000 --max-session 200000 --tor \  --pool AAG16mNWTtC1sBeu2tTVTwWjqWXCefLTCByVPj5X3kV8 \  --program 8PYPw3FSFTMbvSneXdcoH6jNoN4VD23nHwPY2A2riUy1 \  --memo-service https://pay.shinjukustaition.com \  --proof-tools /abs/path/shinjuku-proof-tools/proof-tools.json \  --exit-proof-tools /abs/path/shinjuku-proof-tools/exit-proof-tools.json \  --profile /abs/path/shinjuku-proof-tools/public-profile.json \  --passphrase-file /abs/path/passphrase.txt
Claude Desktop, Cursor, and other JSON-config hosts

Use absolute paths: a host starts the server from its own folder. On Windows, write C:/Users/you/....

json
{  "mcpServers": {    "shinjuku": {      "command": "npx",      "args": [        "-y", "shinjuku-shielded", "mcp",        "--max-payment", "50000", "--max-session", "200000", "--tor",        "--pool", "AAG16mNWTtC1sBeu2tTVTwWjqWXCefLTCByVPj5X3kV8",        "--program", "8PYPw3FSFTMbvSneXdcoH6jNoN4VD23nHwPY2A2riUy1",        "--memo-service", "https://pay.shinjukustaition.com",        "--proof-tools", "/home/you/shinjuku/shinjuku-proof-tools/proof-tools.json",        "--exit-proof-tools", "/home/you/shinjuku/shinjuku-proof-tools/exit-proof-tools.json",        "--profile", "/home/you/shinjuku/shinjuku-proof-tools/public-profile.json",        "--passphrase-file", "/home/you/shinjuku/passphrase.txt"      ],      "env": { "SHIELDED_WALLET_HOME": "/home/you/.shielded-wallet" }    }  }}

Claude Desktop: claude_desktop_config.json. Cursor: ~/.cursor/mcp.json.

A send to a new address needs a host that supports MCP elicitation (it shows you the confirmation). With a host that does not, name each address with --unshield-to.

Examples

examples/ has complete configs and a walkthrough:

  • Claude Code: the claude mcp add command with and without Tor, each flag explained, and how to check it works.
  • Claude Desktop and Cursor: complete JSON configs.
  • Hermes Agent: the config.yaml entry.
  • First 10 minutes: install, make the wallet, fund it, shield, pay, send, and check the balance.
  • Plain requests: 10 requests, the tool each one calls, and the shape of the answer.

Caps and flags

Flag
--max-payment <atomic>Required. The most one payment may cost. Without it the server does not start (mcp_cap_required).
--max-session <atomic>Required. The most this server process may pay in total. Must be at least --max-payment.
--max-per-host-day <atomic>Optional. The most one seller host may receive in 24 hours.
--allow-host <host>Optional, repeatable. Pay only these seller hosts.
--no-shieldOptional. Turns wallet_shield off. It is on with --proof-tools.
--max-shield <atomic>Optional. The most one shield call may move, and the most this process may shield in total. Without it, no cap beyond the balance.
--allow-shieldAccepted for older configs. wallet_shield is on without it.
--exit-proof-tools <file>, --profile <file>Optional. Turn wallet_unshield on (with --proof-tools).
--unshield-to <address>Optional, repeatable. These addresses receive with no confirmation. Any other address needs your confirmation in the MCP client. The wallet's own key is refused: the server does not start when you name it here.
--max-unshield <atomic>Optional. The most one unshield call may move, and the most this process may unshield in total. Without it, a send you confirm can move the whole shielded balance.
--torOptional. Every request goes through Tor; our facilitator is reached over its onion service. Needs Tor with HTTPTunnelPort 127.0.0.1:9080 in torrc. See Privacy modes.
--rpc-file <file>Optional. Your own Solana RPC URL. Without it, reads go to our relay, which sees which accounts the wallet reads.

The passphrase comes from --passphrase-file or SHIELDED_WALLET_PASSPHRASE at start, never from a tool call. A refusal is a normal answer ({"ok": false, "error", "detail", "next"}); the agent does what next says. A cap refusal tells the agent to ask you: only you set the caps.

An unshield is your own money, so it does not count against the payment budget of the wallet file (init --max-payment, --max-cumulative). Payments to sellers still count.

Upkeep is automatic. After a deposit lands, and before a payment or unshield when the local balance is stale, the server reads the chain itself. After each shield and unshield, the wallet writes an encrypted backup to <SHIELDED_WALLET_HOME>/auto-backups/<pool>/. It keeps the newest 5 complete, verified backups. They are on the same disk as the wallet: copy one to another place.

What others can see

  • The seller sees your request, the price, the time, and your IP unless you use --tor.
  • Your agent host and its model provider see every URL, body, price, paid answer, amount, and unshield address the agent handles. A local model removes that observer.
  • Your MCP client app (Claude Code, Claude Desktop, Cursor, ...) answers the confirmation of a send, not the model. So a prompt-injected agent cannot approve a send. But the wallet trusts the client app to show the dialog to you: a malicious or modified client app could answer "accept" by itself. For a strict setup, name your addresses with --unshield-to and use a client without elicitation. Then any other address is refused.
  • Our facilitator processes your payment. It keeps no access logs.
  • On chain, a shielded-exact payment does not show who paid. A pocket exact payment is a normal USDC transfer from the pocket address.
  • wallet_shield is a public step: the chain shows USDC leave the wallet's own key, the amount, and the time.
  • wallet_unshield is a public step: the chain shows the amount, the address that receives it, and the time.
  • The UNSHIELDED line of wallet_balance reads the wallet's own key. The RPC (our relay by default) sees which key it reads.
  • Privacy needs a crowd. With few users, timing can still link payments.

Status

Listed in the official MCP Registry as io.github.ShinjukuStaition/shinjuku-mcp. npm: shinjuku-shielded, published from this repository's workflow with npm provenance (from 0.1.1).

Live on Solana mainnet with wallet release 1a336885 (2026-10-08). Proven with real money through this MCP server, against our production facilitator:

ToolTransaction
wallet_shield (1 USDC in)hWzDiR1R…izn
wallet_unshield (0.5 USDC out)self-pay 5evVHz8X…r9uv · exit 4yY2YXLS…pgF2i
wallet_unshield with your confirmation (0.25 USDC, release 1a336885)self-pay 3jQyPgrA…QEWw · exit 4yA3qkHU…jCoh
x402_pay (pocket exact)kX2zbbuR…8wW

No unshield transaction contains the wallet that shielded; our facilitator paid every network fee of each unshield.

Full guide: https://shinjukustaition.com/skill.md · Onion: http://2kfhlfuyuwvhmibjrpxqsg4nrbcxasjgjq7kmnfzgfwzptkhhznz3dad.onion/skill.md · X: @Shin_StAItion

Source: README.md at commit b767f54

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.1.1LatestOct 8, 2026