Shinjuku Shielded

Shinjuku Shield

Shinjuku Shield is a privacy-only x402 payment facilitator on Solana. An agent pays an x402 endpoint from a balance that it holds itself. The chain does not show who paid.

• Privacy-only. We do not offer a cheaper path that is not private.
• You keep your keys. The wallet makes your keys on your machine. We never hold them, and we never hold your money.
• We relay and pay the fees. Our relayer sends your relayed deposits and exits and pays their network fees. Our facilitator pays the network fee of each payment that it settles.
• One balance. Your Shinjuku Shielded balance is a set of redeemable notes that you hold. The wallet shows it as one number.
• Outside sellers work. Any Solana x402 exact seller that takes USDC gets paid, whichever facilitator it uses (Coinbase CDP, PayAI, or any other). The seller changes nothing. Your wallet pays us privately, and we pay the seller from our own float. The chain shows Shinjuku paying the seller, never your wallet.

What your agent gets

The private x402 facilitator, inside your agent.

Shinjuku Shield 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.
• One command to set up. npx -y --no-audit --no-fund shinjuku-shield@0.3.86 setup makes the wallet, a private passphrase file, and the checked proof tools, and writes config.json. Then your agent host starts npx -y --no-audit --no-fund shinjuku-shield@0.3.86 mcp. --no-audit --no-fund stop npx from asking npm's audit and funding services when it installs a new version. Once, that request held the start for 5 minutes.
• Add funds from 0.01 USDC. Ask your agent to add funds. wallet_add_funds gives a one-time address. Send USDC to it from any wallet or exchange, and it becomes private by itself.
• Caps that only you set. Spending limits are optional; by default there is none (only the balance bounds a payment). Setup records the ones you set. A tool call can only lower them, never raise them.
• Find sellers. x402_discover searches public x402 listings (Coinbase x402 Bazaar, PayAI, Dexter, and others) on your machine.
• Pay any Solana exact seller. A seller on Coinbase CDP, PayAI, or any other facilitator is paid through Shinjuku: your wallet pays us privately, and we pay the seller from our own float. Nothing to fill or set aside.
• Look before you pay. x402_preview shows the price and whether your caps allow it. It pays nothing.
• No SOL. wallet_add_funds and wallet_shield need only USDC. Our facilitator's relayer pays the network fee.
• 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 sign-up, no API key. Reads go through our relay by default. Your own RPC always wins if you give one.

This repository holds the setup guide, the examples, the docs, the changelog, and the published SHA-256 hashes of every wallet file and its proof tools (Releases). It holds no server code, no circuit code, and no wallet source code.

Docs

• How it works: x402, our three schemes, the flow of one payment, and what runs where.
• Privacy model: what the chain, the seller, our facilitator, the RPC, and the MCP host see, with each limit.
• Sell with Shinjuku Shielded: get paid by Shinjuku Shielded buyers with stock x402 middleware, and get listed.
• Proof: live mainnet transactions, and what each one shows and hides.
• FAQ: custody, cost, networks, Tor, recovery, and audits.
• Changelog: what changed in each release. The first changelog of the wallet file, up to 08a4b56f (npm 0.3.8): changelog-to-0.3.8.md.

Release 0.3.86

Stable version, pinned 2026-10-23. A self-custody wallet for AI agents. It pays any x402 endpoint from a shielded balance, so the chain does not show which wallet paid. One command sets it up. Your agent does the rest from plain requests.

Get started

You need Node.js 22.21 or newer, or Node.js 24. Tor is optional: run it if you also want to hide your IP address.

1. Set up the wallet. One command makes the wallet on your machine, a private passphrase file, and downloads every proof file it needs (about 191 MB, checked by hash). Add --tor to do the download and every later request over Tor.

    npx -y --no-audit --no-fund shinjuku-shield@0.3.86 setup

2. Add it to your agent host. Setup prints the exact lines for Claude Code, Claude Desktop, Cursor and other MCP hosts. The host then starts the wallet with:

    npx -y --no-audit --no-fund shinjuku-shield@0.3.86 mcp

3. Add money. Ask your agent "Add 1 USDC to my private balance." It gives you a one-time address. Send USDC on Solana to it from any wallet or exchange. You need no SOL. A few minutes after it arrives, the money is private.
4. Use it. Ask your agent to pay a URL, find a paid API, send money out, or ask an AI model. Every feature below works from a plain request.

For a terminal, install the wallet once: npm install -g --no-audit --no-fund shinjuku-shield@0.3.86, then shinjuku-shield help lists every command.

Features

Every feature here passed a live run on the published 0.3.86 package, on production, with real USDC, on 2026-10-23.

Add money

• Add funds (wallet_add_funds, shinjuku-shield add-funds). A new one-time address for each deposit, from 0.01 USDC. Send from any wallet or exchange; no SOL needed. The wallet makes it private by itself after it lands, even if your agent app closed. Ask: "Add 1 USDC to my private balance." Terminal: shinjuku-shield add-funds --route exchange --amount 1
• Make public USDC private (wallet_shield). USDC that sits on the wallet's own public address moves into the shielded balance. The facilitator pays the network fee. Ask: "Make the USDC on my address private."
• Send any token privately (wallet_transfer_token, wallet_transfer_token_status). Any token on the wallet's own address is sold for USDC, made private, and sent on in pieces. The receiver gets USDC with no link to the token wallet. Ask: "Sell my JUP for USDC and send it privately to my main wallet."

Pay

• Pay any x402 endpoint (x402_pay, shinjuku-shield pay, shinjuku-shield curl). Pays an x402 URL from the shielded balance and returns the answer. The seller gets paid as usual; the chain does not show which wallet paid. The price and the fee show in the answer. Ask: "Pay for this endpoint and show me what it returns: <url>"
• Price preview (x402_preview). Shows what a URL costs before you pay. Nothing is paid or signed. Ask: "How much does this URL cost?"
• Find paid APIs (x402_discover). Searches public x402 endpoints for a job. Your search words stay on your machine; nothing is paid. Ask: "Find a paid API for Brazil inflation data."
• Automatic refunds (x402_pay). If the seller fails before it takes the money, the full amount comes back to the private balance by itself. If the seller took the money and gave nothing, the receipt says so with the seller's transaction. Nothing to ask: the receipts show each refund and its transaction.
• Slow sellers, never paid twice (x402_pay). When a seller is slow, the wallet answers early and keeps waiting. Asking again with the same request continues the same payment. It never pays twice. Ask again with the same request when the agent tells you the seller is still working.
• Images and files (x402_pay). A paid answer that is an image or a file is saved in the wallet folder, with its path and hash. Ask: "Buy a QR code for this text from <url>."
• Cancel (wallet_cancel, shinjuku-shield cancel). Closes a payment that can no longer settle, so its reserved money comes back. A finished payment cannot be taken back, and the wallet says so. Ask: "Cancel that payment."

Send money out

• Send to an address (wallet_unshield, shinjuku-shield unshield). Sends some or all of the private balance to any Solana wallet as plain USDC. The facilitator pays the network fee. Ask: "Send my whole private balance to my main wallet." Terminal: shinjuku-shield unshield --amount all --to <address>
• Send in pieces at random times (wallet_unshield with a time window). Splits a send into pieces that leave at random times, so the amount and the time do not match one payment. The pieces go out in the background, even after your agent app closes. Ask: "Send 0.02 USDC to my main wallet in 2 pieces within the next 10 minutes."
• Send all of it (wallet_unshield, shinjuku-shield unshield --amount all). A balance from several deposits is readied by itself when you send all of it. You do nothing extra. Ask: "Send all of it."
• Spend a received payment (wallet_unshield). A wallet that only received private payments can send them out directly, with no extra step. Ask: "Send what I received to <address>."

Your wallet

• Balance (wallet_balance, shinjuku-shield balance). One number: what you can spend. It also shows any public USDC on the wallet's own address and any money still on its way. Ask: "What is my private balance?"
• Receipts (wallet_receipts). Every payment, refund, deposit and send, newest first, with the seller, the price, the fee and the transactions. Ask: "Show my receipts from today. Did I get my money back on failed payments?"
• Spending limits (--max-payment, --max-session, shinjuku-shield limits). Optional limits per payment and per 24 hours. A payment over a limit is refused before anything is paid, and the answer says how to change the limit. Set them in setup or in your host's MCP entry, for example --max-payment 0.05.
• Version pin and update notice (npx ... shinjuku-shield@0.3.86 mcp). Your host runs the exact version it names. When a new release is ready, the wallet tells you to restart. Nothing to ask.

Private AI

• Ask an AI model (inference_chat). Your agent asks an AI model and pays for the answer from the shielded balance. The chain does not show which wallet paid. Ask: "Ask a private AI model: what is the capital of France?"
• Terminal chat (shinjuku-shield chat). A private AI chat in your terminal. The conversation stays in memory only and is gone when you exit. Terminal: shinjuku-shield chat, then /cost and /exit
• One question (shinjuku-shield infer). One question, one paid answer, no setup flags. Terminal: shinjuku-shield infer "Say hello" or echo "Say hello" | shinjuku-shield infer -
• Private AI address for your apps (shinjuku-shield infer start, inference_server). A local OpenAI-compatible address (http://127.0.0.1:11402/v1) with an API key. Any app that speaks the OpenAI chat API, streaming included, gets private paid answers. It runs in the background after the terminal closes, but not after the computer restarts: then run shinjuku-shield infer start again (the API key stays the same). Ask: "Start my local private AI address." Terminal: shinjuku-shield infer start, shinjuku-shield infer status, shinjuku-shield infer stop

Privacy and setup

• Tor (setup --tor, --tor, --no-tor). With Tor, every request goes through Tor and reaches the facilitator through its onion service, so no server sees your IP address. After a Tor setup, every command uses Tor by itself. Run Tor with HTTPTunnelPort 127.0.0.1:9080, then setup --tor.
• Self-custody (shinjuku-shield setup, backup-export). The keys are made and kept on your machine. Only your keys move your balance. The facilitator settles and pays network fees; it never holds your money. Back up after setup: shinjuku-shield help backup-export
• The terminal command (npm install -g --no-audit --no-fund shinjuku-shield@0.3.86). Every wallet action from a terminal: setup, add-funds, balance, pay, unshield, chat, infer and more. Terminal: shinjuku-shield help

Speed

The time from "pay" to the seller's data, for the first payment to a seller the wallet never paid before (a fresh wallet process, production, 2026-10-23):

Known issues

None of these loses money. Each one gets its own fix release, tested live before the next.

1. When a seller fails before it takes the money, the answer starts with "Paid". The money is not taken and comes back by itself.
2. The terminal send prints one internal line that starts with SELLER_STORE.
3. shinjuku-shield chat can print raw Tor lines while Tor is slow.
4. When the spending limit comes from the host's MCP entry, the refusal names setup as the place to change it.
5. Before a send that needs the balance readied first, the agent may not tell you it takes about 2 minutes.
6. In a terminal, balance, infer and unshield print internal Tor, RPC and history lines.
7. A plain shinjuku-shield balance right after a deposit can show no number. shinjuku-shield balance --refresh shows it.

Payments to outside sellers show the price and the seller on chain as any x402 payment does; what the chain does not show is which wallet paid. Every release and its changes: CHANGELOG.md.

Talk to it in plain words

Ask your agent the way you would ask a person:

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

SETUP

On a machine with no wallet, the server starts in setup mode.

In setup mode, every money tool answers wallet_not_set_up and does nothing.

FUND

PAY

UNSHIELD

WALLET

RECEIVE AND TRADE

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.

The tool list shows 12 of the tools above: wallet_receive_shielded is not in the list from 0.3.54 (it comes back with private escrow deals), but it still answers when an agent calls it by name. Some older tools are not in the list either, and they also answer by name: wallet_shield_from_elsewhere, wallet_pay_me, wallet_pay_me_status, wallet_unshield_cancel, wallet_move_status, and inference_models.

What it pays:

• shielded-exact, from your shielded balance, whenever the seller offers it.
• Standard Solana exact, through Shinjuku (float pay). For a seller on any facilitator (Coinbase CDP, PayAI, or any other), x402_pay pays us privately from your shielded balance: the seller's price plus a flat fee (feeAtomic, 0.001 USDC on 2026-10-22). We pay the seller at once from our own shared float. The chain shows Shinjuku paying the seller, never your wallet. max_payment_atomic must cover price plus fee. The largest price that one request can pay is largestAtomic in GET https://pay.shinjukustaition.com/api/x402/float/config (10 USDC on 2026-10-22).
• A retry with the same request_id never pays twice.

Hidden amounts (scheme confidential, the V0b vault) are retired: the V0b program was closed on chain on 2026-10-11.

Value that an older version put in pockets still counts in the one balance. When the server has --proof-tools, --exit-proof-tools, and --profile, it returns that value to the shielded balance by itself while it is idle. shinjuku-wallet pocket reshield does the same by hand.

A balance from several deposits: one payment can spend only a few of them at once. The server gathers them into one by itself (a private payment to itself; nothing leaves the shielded balance, and our facilitator pays the network fee). When no single deposit covers a price yet, x402_pay says so, the gathering starts within about a minute, and the answer says when to pay again.

Privacy modes

Setup

You need Node.js 22.21 or later (or Node.js 24 or later), on Windows or Linux. macOS is not supported yet.

The stable version is shinjuku-shield@0.3.86 (pinned 2026-10-23; the same files are on npm as shinjuku-shielded@0.3.86), and every command here names it. Setup prints host lines that name this exact version. A candidate is out for testing: shinjuku-shield@0.3.103 (npm tag next, 2026-10-24). It fixes known issues 1 to 7 of 0.3.86, shows a QR code for a deposit, asks for your own wallet address in setup, asks "Use Tor?" when your agent app sets up the wallet, waits for your answer in the setup box, names your recovery file when setup ends, says when you confirmed a send, and asks for each value in a terminal instead of a flag. It adds slash commands in Claude Code: type / and pick a command, then add its value, or press Enter and the agent asks. It gives you the shinjuku command for a terminal (npm install -g --no-audit --no-fund shinjuku@0.3.103, then shinjuku help). The private AI chat and the private AI address use one default model, qwen3-8-flash, with 4096 tokens for an answer; the address names its model and says what to do after a restart. When a seller refuses a payment at once, it says when the refund lands. See the changelog.

A later stable version gets its own row in the Releases table: run its setup once and put its version in your host's config. Your wallet, its address, and its balance stay the same.

1. Run the setup in a terminal

npx -y --no-audit --no-fund shinjuku-shield@0.3.86 setup

It asks for the caps (Enter keeps the default) and Tor. --yes asks nothing. --add-to claude-code (or claude-desktop, cursor) also adds the server to that host's config. In our runs, setup took about 10-16 s on a fast line, with the proof-tool download of about 191 MB. Over Tor (--tor), it took 89 s to 5 min in our 0.3.86 tests (2026-10-23). At the end it prints a summary, for example:

Shinjuku Shielded is set up.
  limits       no limit per payment, no limit in any 24 hours, no limit for the life of the wallet
  config       <home>/config.json
  passphrase   <home>/passphrase.txt (a new random passphrase; only you can read the file; it is never printed)
  proof tools  <home>/proof-tools/a9af32df (29 files downloaded, every hash checked)
  wallet       created; your public address (solanaFeePayer): <address>
  recovery     <home>/recovery-<time>.txt

Setup writes to ~/.carbon-shielded-wallet (or SHIELDED_WALLET_HOME):

• The wallet, and a recovery file with the seed and the key. Copy the recovery file to two offline places, then delete it from this machine.
• passphrase.txt: a new random passphrase, readable by you alone. It is never printed, and no tool takes or returns it. Keep it: the wallet file opens only with it.
• The proof tools. Setup checks every file against the set that this wallet release pins.
• config.json: the caps, the paths, and Tor. With it, mcp needs no flags. A flag on the command line still wins.

Spending limits are optional and off by default: with none, only the balance bounds a payment. To set them, give --max-payment, --max-session, or --max-cumulative, in USDC (0.05 = 5 cents). A setup rerun lifts the old default caps (0.05 / 1 / 20 USDC) of earlier versions. --prefer-tor records Tor (see Privacy modes).

You can run setup again at any time. It never changes an existing wallet, and it checks every proof-tool file again.

2. Add the server to your agent host

If you gave --add-to, this step is done. Setup also prints these lines.

Claude Code:

claude mcp add --scope user shinjuku-shielded -- npx -y --no-audit --no-fund shinjuku-shield@0.3.86 mcp

On native Windows, the line that setup prints puts cmd /c before npx. With a wallet folder that is not the default, it adds -e SHIELDED_WALLET_HOME=<home> (or an "env" block in JSON).

Claude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json), and other JSON-config hosts:

{
  "mcpServers": {
    "shinjuku-shielded": {
      "command": "npx",
      "args": ["-y", "--no-audit", "--no-fund", "shinjuku-shield@0.3.86", "mcp"]
    }
  }
}

Or: start the server first and accept the setup

You can also add the server first, with no wallet on the machine. Then the server starts in setup mode. Ask your agent "what is my balance". Your MCP client asks you to confirm: create a Shinjuku Shielded wallet on this machine. Accept, and the setup runs (with the proof-tool download of about 191 MB). Then the same server switches to the wallet tools. You do not restart it. A client that cannot ask is told to run npx -y --no-audit --no-fund shinjuku-shield@0.3.86 setup in a terminal.

In a terminal, npx -y --no-audit --no-fund shinjuku-shield@0.3.86 mcp asks "Set up Shinjuku Shielded now? (y/n)".

3. Add funds

The wallet starts empty. Ask your agent "Add 0.50 USDC to my shielded balance". It calls wallet_add_funds and gives a one-time address. Send that USDC on Solana from any wallet or exchange. Amounts from 0.01 USDC work, and you need no SOL. The USDC becomes private by itself while the MCP server runs: our relayer pays every fee.

From an exchange, in a terminal, whole USDC only:

npx -y --no-audit --no-fund shinjuku-shield@0.3.86 add-funds --route exchange --amount 2

It prints a one-time address. Withdraw exactly that amount of USDC (Solana SPL) from the exchange to it, and it shields the USDC by itself. --amount is a whole number of USDC (2 = 2 USDC).

USDC that is already on the wallet's own address (ownAddress in wallet_balance) goes in with wallet_shield. The steps are in First 10 minutes.

Advanced: 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.

curl -fsSLO https://shinjukustaition.com/wallet/b650bf06/shinjuku-wallet.mjs
echo "b650bf0682830e05207f52bad2ba426ec7f8fa1bbbfdb7e028057865e3d83d24  shinjuku-wallet.mjs" | sha256sum -c -
node shinjuku-wallet.mjs setup

With the file, replace npx -y --no-audit --no-fund shinjuku-shield@0.3.86 with node /abs/path/shinjuku-wallet.mjs.

Advanced: flags instead of config.json

mcp reads config.json only when you give no --pool and no --wallet. To give the flags yourself (for example, for a wallet that you made with init before 0.2.0):

claude mcp add --scope user shinjuku-shielded -- npx -y --no-audit --no-fund shinjuku-shield@0.3.86 mcp \
  --max-payment 0.05 --max-session 0.2 --tor \
  --pool <pool> \
  --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

With --pool, --program and --memo-service are required. Setup writes the pool, the program, and the facilitator into config.json: <pool> is the pool in your config.json. npx -y --no-audit --no-fund shinjuku-shield@0.3.86 help mcp prints every flag.

Use absolute paths: a host starts the server from its own folder. On Windows, write C:/Users/you/.... --proof-tools turns wallet_shield on. --exit-proof-tools and --profile turn wallet_unshield on.

For an older wallet, you can also run setup once with SHIELDED_WALLET_HOME set to your wallet folder and --passphrase-file set to your passphrase file. It keeps your wallet and writes config.json beside it.

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 setup command, the claude mcp add command, Tor, each flag explained, and how to check it works.
• Claude Desktop and Cursor: complete JSON configs.
• Hermes Agent: the config.yaml entry.
• Vercel AI SDK: the server's tools in generateText through @ai-sdk/mcp, with no other package.
• Solana Agent Kit: npm solana-agent-kit-plugin-shinjuku, the wallet as Solana Agent Kit v2 actions.
• First 10 minutes: set it up, add the server, add funds, pay, send, and check the balance.
• Plain requests: 13 requests, the tool each one calls, and the shape of the answer.

Caps and flags

After setup, config.json holds the caps and the paths. You can add any of these flags to the mcp command. A flag wins over config.json.

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. To show, change, or remove those wallet-file caps, run shinjuku-wallet limits (none removes a cap). A refusal by one of them tells the agent to ask you for this.

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. By default it reads the pool history through our facilitator's https history proxy: a new wallet is ready in about 60 s. 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 float pay payment is a pool payment to us (the payer hidden), then a normal USDC transfer from a Shinjuku float pocket to the seller. Many buyers pay from the same float pockets. The transfer lands seconds after the pool payment, so time can pair the two.
• For a float payment, our server sees which private payment paid which seller, the price, the URL, and the time, until the payment is final or refunded. It does not see your wallet.
• wallet_add_funds: the chain shows the USDC that arrives at the one-time address, the amount, and the time. Use each address for one payer.
• 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.
• inference_chat: usePod and the model provider see the prompt and the answer.
• 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.

Which endpoints you can pay

• A seller whose 402 offers shielded-exact. The wallet pays it from your shielded balance, and our facilitator settles the payment.
• Any other Solana x402 exact endpoint that takes USDC, whichever facilitator settles it (float pay). pay (or the MCP x402_pay) pays us privately from your shielded balance: the seller's price plus a flat fee of 0.001 USDC. We then pay the seller at once from our own shared float. You fill nothing and set nothing aside. If the seller does not take the payment, we refund price and fee to your shielded balance by ourselves. This path, and every other payment, needs wallet release 08a4b56f (npm shinjuku-shielded@0.3.8) or later: the pool program was upgraded on 2026-10-11, and earlier releases refuse to pay.

The largest price that float pay can pay for one request is the size of our largest float pocket. Read it, and the fee, before you pay:

curl -fsS https://pay.shinjukustaition.com/api/x402/float/config

feeAtomic is the fee and largestAtomic is the largest price, in atomic USDC (1000000 = 1 USDC). On 2026-10-22 they were 1000 (0.001 USDC) and 10000000 (10 USDC). A higher price is refused before anything is paid (p03_float_price_above_capacity).

The 3D market game Shinjuku Undermarket is our first customer and our live demo.

Status

• Stable version (pinned 2026-10-23): wallet release b650bf06, npm shinjuku-shield@0.3.86 (the same files as shinjuku-shielded@0.3.86). Install that exact version. It adds private AI in the terminal and for agent apps. Every feature and how to use it: the 0.3.86 release notes. Hash: the b650bf06 row of Releases.
• The stable version before it: wallet release 98296ff0 (npm 0.3.80).
• Candidate (2026-10-24, not the stable version): wallet release b5da74cb, npm shinjuku-shield@0.3.103 under the tag next. It fixes known issues 1 to 7 of 0.3.86, shows a QR code for a deposit, takes any amount from 0.01 USDC in a terminal, keeps every tool text short enough for agent apps to read in full, asks "Use Tor?" when an agent app sets up the wallet, waits for your answer in the setup box, names your recovery file when setup ends, says when you confirmed a send, and asks for each value in a terminal instead of a flag. It adds slash commands in Claude Code (type / and pick a command, then add its value, or press Enter and the agent asks), the shinjuku command for a terminal (npm install -g --no-audit --no-fund shinjuku@0.3.103), one default AI model (qwen3-8-flash, 4096 tokens for an answer) for the chat and the private AI address, and the time when a refund lands after a seller refuses at once.
• shielded-exact payments from the shielded balance: live on mainnet.
• Float pay to any Solana x402 exact endpoint that takes USDC: live on mainnet since 2026-10-11 (wallet release e3348092 and later). On 2026-10-11 it paid two stock sellers on the PayAI facilitator, 0.10 USDC in 15 s and 1.50 USDC in 20 s, and a stock seller on our own facilitator (488372b4 and later), 0.01 USDC in 16 s and 17 s: see proof.md.
• Faster pool anchors: live on mainnet since the pool program upgrade of 2026-10-11 (wallet release 08a4b56f and later). The pool takes an anchor about every 30 s when it grew. In our test, 12 of 12 new deposits could pay within 45 s (median 18 s).
• Pool moves: live from wallet release 701809bd (npm shinjuku-shielded@0.3.9). When we open a new pool, the old pool keeps serving until it is empty, and move moves your whole balance to the new pool privately: you pay our float in the old pool, and the float pays you in the new pool. Nothing goes through a public address.
• Per-user pockets: replaced by float pay. The wallet fills no new pocket for a payment. pocket reshield returns the USDC of an old pocket to your shielded balance.
• Hidden amounts (scheme confidential, the V0b vault): retired. The V0b program was closed on chain on 2026-10-11.
• The wallet file and its proof tools, served from our site and our onion service with SHA-256 hashes: live.
• Key ceremonies: a multi-party ceremony: not yet.
• Independent audit: none yet.

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

Live on Solana mainnet. The current wallet release is b650bf06 (npm 0.3.86, pinned 2026-10-23). Every feature and how to use it: Release 0.3.86.

Every release and its changes: CHANGELOG.md.

Float pay paid two stock sellers on the PayAI facilitator on production on 2026-10-11, 0.10 USDC and 1.50 USDC, and a stock seller on our own facilitator, 0.01 USDC twice: the transactions are in proof.md.

These transactions were made with real money through this MCP server, against our production facilitator, on an earlier pool (retired 2026-10-10). The first two came from a new wallet with the default setup and no SOL at any time (wallet release 94a357bc). The others used wallet release 1a336885 (2026-10-08).

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

Releases

Each release is one file, shinjuku-wallet.mjs, and a set of proof tools. Our website serves the files and their SHA-256 hashes at https://shinjukustaition.com/wallet/<sha8>/ and https://shinjukustaition.com/proof-tools/<sha8>/. This repository is a second, separate place for those hashes: each release adds its row here.

The stable version is b650bf06, on npm as shinjuku-shield@0.3.86 and shinjuku-shielded@0.3.86 (pinned 2026-10-23). Use it for a new install. A row marked "candidate" is a newer release served beside the stable version and published on npm under the tag next, not latest; it becomes the stable version only when we say so here. Rows marked "no longer served" are gone from the website; the other older rows stay for the record. Some short-lived releases served between 2026-10-05 and 2026-10-07 have no row here. What changed in each release after 08a4b56f is in the changelog.

Beside each wallet file, the website also serves LICENSE.txt (the copyright notice), THIRD_PARTY_NOTICES.txt (the open-source licenses inside the file), and manifest.json (the source commit and every bundled package). The manifest's source commit names our private development repository. This public repository publishes the hashes, not the source code. Every release is reproducible: two independent builds (Windows and Linux) of that commit give the same SHA-256, and our server refuses to start if the file it serves differs from the pinned hash.

Get the wallet

The wallet needs Node.js 22.21 or later (or Node.js 24 or later) and nothing else. The stable release is b650bf06: put it in place of <sha8> below.

1. Download

curl -fsSLO https://shinjukustaition.com/wallet/<sha8>/shinjuku-wallet.mjs

On Windows, type curl.exe, not curl (in Windows PowerShell, curl is a different command).

Over Tor, from our onion service (production):

curl --socks5-hostname 127.0.0.1:9050 -fsSLO \
  http://2kfhlfuyuwvhmibjrpxqsg4nrbcxasjgjq7kmnfzgfwzptkhhznz3dad.onion/wallet/<sha8>/shinjuku-wallet.mjs

2. Check the SHA-256

Compare the file with the hash in the Releases table above. Go on only when the check prints OK. On any other result, delete the file and do not run it.

Linux:

echo "<sha256>  shinjuku-wallet.mjs" | sha256sum -c -

macOS:

echo "<sha256>  shinjuku-wallet.mjs" | shasum -a 256 -c -

Windows (PowerShell):

if ((Get-FileHash .\shinjuku-wallet.mjs -Algorithm SHA256).Hash -eq "<sha256>") { "OK" } else { "MISMATCH" }

Windows (cmd.exe): certutil -hashfile shinjuku-wallet.mjs SHA256 prints the hash. It must equal the SHA-256 in the table.

A match proves that your copy is complete and equals the file whose hash we published here. It does not prove who made the file.

3. Read the help

node shinjuku-wallet.mjs help
node shinjuku-wallet.mjs help init

help <command> prints a working example, every flag, and the next step. Exit code 0 means done. Exit code 1 means the command ran and failed (one line says why). Exit code 2 means the command line is wrong (it shows a working example).

With the wallet file alone, these commands work: every help page, init, backup-export, backup-verify, restore, balance (without --refresh), and limits. The money commands also need the proof tools (next section).

Get the proof tools

add-funds, deposit, recover, balance --refresh, pay, buy-item, unshield, and pocket reshield need the proof tools of the facilitator that you use: two manifests, the facilitator's public profile, Linux x86-64 provers, and the signed proving parameters (30 files, about 191 MB, for proof tools a9af32df).

The provers are Linux programs.

• Linux: run the steps below as written.
• Windows: install WSL (Ubuntu). Run the steps in a WSL shell, in a folder on a Windows drive (for example /mnt/c/Users/<you>/shinjuku-proof-tools). Then run the wallet from Windows with the C:\ paths. The wallet runs each prover through wsl.exe.
• macOS: not supported. Use a Linux machine or a Linux container.

mkdir shinjuku-proof-tools && cd shinjuku-proof-tools
base=https://shinjukustaition.com/proof-tools/<sha8>
curl -fsSO "$base/SHA256SUMS"
echo "<sha256 of the file list>  SHA256SUMS" | sha256sum -c -
while read -r sum path; do mkdir -p "$(dirname "$path")"; curl -fsS -o "$path" "$base/$path"; done < SHA256SUMS
sha256sum -c --strict --quiet SHA256SUMS && echo ALL_OK
chmod +x bin/* house/bin/* bundle/bin/*

Go on only when the list check prints OK and the last check prints ALL_OK. Then give the wallet:

• --proof-tools shinjuku-proof-tools/proof-tools.json (--payer-proof-tools for unshield),
• --exit-proof-tools shinjuku-proof-tools/exit-proof-tools.json,
• --profile shinjuku-proof-tools/public-profile.json.

The wallet checks the SHA-256 of each binary again before every run.

Quick start

The full guide is the wallet's own help. The steps below follow it.

What you need

• Node.js 22.21 or later, or Node.js 24 or later. (The two privacy-cash commands need Node.js 24 and the Privacy Cash SDK, which the wallet file does not include.)
• The proof tools (previous section).
• A Solana RPC URL in a private file, rpc.txt. With --tor, use an RPC URL that has no API key in it: a keyed URL names its owner.
• A private folder for the wallet, and a passphrase of 8 or more characters.
• The public identities (program, pool, mint, network, facilitator): run node shinjuku-wallet.mjs help. Each release names its own facilitator.

export SHIELDED_WALLET_HOME=<a private folder>
export SHIELDED_WALLET_PASSPHRASE=<your passphrase>
W=shinjuku-wallet.mjs

Keep the same passphrase in passphrase.txt and your RPC URL in rpc.txt.

Hide your IP

Add --tor to any command. Start Tor with one line in torrc: HTTPTunnelPort 127.0.0.1:9080 IsolateDestAddr. The wallet checks that it reaches the network through Tor before it sends any other request, and it refuses any connection that does not go through the proxy.

1. Create the wallet

node $W init --pool $POOL --network $NETWORK --asset $MINT \
  --binding carbon-shielded-exact/svm-v3 --backup-out recovery.txt

Caps are optional: by default there is no limit, and only the balance bounds a payment. init --max-payment and --max-cumulative set caps in the wallet file. limits shows them, and changes or removes them later (none removes a cap):

node $W limits --pool $POOL
node $W limits --pool $POOL --max-payment none --max-cumulative none

init writes your recovery text (the seed and the Solana secret key) only to the new --backup-out file, never to the screen. Copy that file to two offline places, then delete it from this machine. Keep the solanaFeePayer and seedFingerprint that init prints beside it.

2. Back up (after every step that moves value)

node $W backup-export --pool $POOL --to /backups/01-created
node $W backup-verify --pool $POOL --backup-dir /backups/01-created

3. Add funds privately

node $W help add-funds

add-funds runs every funding step in order and waits between them. It ends with ready and your balance. Three routes:

• exchange: withdraw the exact amount from an exchange to the one-time address that the wallet prints. The exchange knows you, the amount, and the address.
• changenow: a fixed-rate ChangeNOW swap to the one-time address, paid with Monero (best), BTC, or ETH. ChangeNOW sees the amount and the address.
• privacy-cash: your own wallet pays into the Privacy Cash pool; at least 24 hours and 10 other deposits later, Privacy Cash pays the one-time address. It takes about a day.

Never fund the one-time address from a wallet that you use elsewhere. That transfer links you.

4. Pay

node $W help pay

• A seller whose 402 offers shielded-exact: pay pays it from your shielded balance at the seller's price.
• Any other Solana x402 exact endpoint that takes USDC: pay pays it through Shinjuku (float pay). Your wallet pays us privately, price plus the fee, and we pay the seller from our float. --maximum-atomic must cover price plus fee. Nothing to fill or set up.
• A rerun with the same --request-id never pays twice.

A balance that came in by several deposits (for example 0.779 and 2.000 USDC) cannot pay 2.001 USDC in one payment, although the total covers it. node $W help names the command that readies such a balance for one payment: nothing leaves the pool, and our relayer pays every fee. After it, wait for the next pool anchor (usually within a minute), then pay.

5. Check your balance and withdraw

node $W help balance
node $W help unshield

unshield sends some or all of your balance to a public Solana address; our relayer sends the exit and pays its fees. Run backup-export again after each step that moves value.

The self-custody model

• Your keys are a Solana key and a shielded seed. init makes both on your machine. No sign-up, no Ethereum key, and no identity signature.
• We never receive your keys, seed, passphrase, or recovery file. We cannot recover them. If you lose the seed and the recovery file, your funds are lost.
• restore rebuilds the wallet from the recovery file. recover reads your shielded notes from your seed, the public chain history, and the public memos.
• The wallet writes deposit, payment, and unshield steps to its log before it sends them. After an interruption, run the same command again. The help of each command says how it resumes.
• Our relayer pays the network fees of relayed deposits and exits. A self-broadcast deposit and the first Privacy Cash step are paid by your own key.
• We never ask for your seed, passphrase, or recovery file. Anyone who asks is not us.

What the privacy covers, and what it does not

What the chain does not show: who paid a seller from a Shinjuku Shielded balance. With float pay, the chain shows a pool payment (the payer hidden) and then a Shinjuku float pocket that pays the seller. Many buyers pay from the same float pockets, so a chain observer cannot group one buyer's purchases.

What it does not hide:

• Our server sees what it processes: your deposits, payments, and exits, their times, and the IP address of each request (a Tor exit with --tor).
• Deposits are public. A deposit's amount and time are public. With few depositors in a pool, time can pair your deposit with your later payments. When you are the only user (k=1), waiting buys nothing. Our pools are new and have few users.
• Float pay: our server sees both sides. For a float payment, our server sees that this private payment paid seller X, the price, the resource URL, and the time. It does not see your wallet. It keeps that link only until the payment is final or refunded.
• Float pay: the seller's price is public. The transfer from our float pocket to the seller shows the amount, the seller, and the time. It lands seconds after your pool payment, so time can pair the two.
• Another facilitator sees its last step. The seller's own facilitator settles the transfer from our float pocket. It sees our pocket, the seller, the amount, and the time, as the chain does.
• Your own traces. A keyed RPC URL names you. The timing of your requests links them. Everything you sign on chain is public.

Keys, audits, and limits:

• The production keys of the main shielded pool came from a single-operator offline setup. No multi-party ceremony has run.
• No independent audit of the circuits, the verifiers, or the binding has run.
• Do not expect a cold wallet to settle at once: on 2026-09-23 a payment took 1.5 to 4 minutes.
• A new deposit pays after the next pool anchor (about every 30 s when the pool grew; 12 of 12 within 45 s in our test on 2026-10-11). So a balance from several deposits can need one extra step and one anchor wait before a large payment.
• Float pay needs our float to hold enough. When it is busy or being filled, the wallet refuses before it pays (p03_float_busy_retry_later, p03_float_not_ready_retry_later); try again later.

Copyright

Each wallet file comes with this notice (LICENSE.txt beside the file):

Shinjuku Shielded wallet Copyright (c) 2026 Shinjuku Shielded. All rights reserved.

The open-source packages inside this file keep their own licenses: see THIRD_PARTY_NOTICES.txt.

THIRD_PARTY_NOTICES.txt beside each release lists every open-source component inside the file, with its license text. One of them, rpc-websockets, is under LGPL-3.0-only.

Security

See SECURITY.md.