tony strk

SETUP / STARKNET

Back to landing

Local MCP / STRK20 x402

RUN THE
PRIVATE ROUTE.

Set up a local Tony Strk server that browses through Tor and can pay a compatible HTTP x402 paywall with shielded STRK. Sepolia is the safe default; Mainnet uses the same MCP flow with real STRK.

Two hosting boundaries. The key-holding MCP stays local at 127.0.0.1:8787/mcp. The merchant must have a public HTTPS origin, either a temporary tunnel for testing or a permanent deployment.

  1. 01 / PREREQUISITES

    Bring the right tools.

    Use macOS, Node 24, npm, and a running Tor process. The privacy SDK requires Node 24. Tor must listen at the SOCKS URL you configure, usually socks5://127.0.0.1:9050. Create an AVNU account and obtain an API key; store it with the paymaster setup command below. Never put a private key, viewing key, passphrase, or AVNU key in this page or in a committed file.

  2. 02 / INSTALL

    Install the stack.

    Run these commands from the project root.

    Project install

    nvm use
npm install
npm run setup

  3. 03 / WALLET

    Create, fund, deploy, shield.

    The wallet lifecycle is explicit. The local Keychain stores the spending key and privacy passphrase; the MCP returns public status and transaction values only.

    1. Run npm run wallet:create. Save the printed public address for the network you selected.
    2. Fund that address with public STRK on the same network. The first shield must cover the private balance, pool fee, and gas.
    3. Call wallet_status. When it reports needs_deployment, call wallet_deploy.
    4. Obtain an AVNU key from the AVNU portal, then run npm run paymaster:set to store it.
    5. After wallet_status reports ready, call wallet_shield with the public STRK amount to shield.
    6. Wait for the shield receipt and its spendableAfterBlock. A new deployment, top-up, or private note needs 12 blocks of maturity before the next proof.

    Wallet creation

    npm run wallet:create

    The pool fee is read from the external stack. Always quote it on the selected network before funding a live wallet.

  4. 04 / CONFIGURATION

    Choose the trust boundary.

    Set a helper contract you have chosen to trust and a per-resource ceiling. PAYWALL_ANONYMIZER_ADDRESS is a payer trust decision: the paywall's invoke leg sends the withdrawn amount to that contract. NETWORK selects the matching chain, pool, prover, discovery service, paymaster, and explorer.

    Place these non-secret settings in the repository's gitignored.env file, or export them in both the server and merchant shells. The server and merchant must use the same helper address from PAYWALL_ANONYMIZER_ADDRESS; without it,pay_paywall is not registered on the server.

    Shared non-secret Sepolia settings for .env

    PAYWALL_ANONYMIZER_ADDRESS=YOUR_TRUSTED_HELPER_ADDRESS
PAYWALL_MAX_PRICE=0.5
STARKNET_RPC_URL=https://starknet-sepolia-rpc.publicnode.com
TOR_SOCKS_PROXY=socks5://127.0.0.1:9050

    Mainnet settings — sponsored AVNU path

    NETWORK=mainnet
PAYWALL_ANONYMIZER_ADDRESS=YOUR_MAINNET_HELPER_ADDRESS
PAYWALL_MAX_PRICE=0.5
TOR_SOCKS_PROXY=socks5://127.0.0.1:9050
    Mainnet fallback when AVNU sponsorship is unavailable

    The explicit public relay fallback still proves and executes the real STRK20 action, but the configured account submits it and is visible on-chain. It is not anonymous at the account-to-payment layer. The account must first approve the Mainnet privacy pool to collect its protocol fee. Set a hard gas ceiling and, when needed, a private STRK refill back to the submitting account.

    Public-relay fallback (real Mainnet STRK)

    NETWORK=mainnet
PUBLIC_PRIVACY_RELAY=true
PUBLIC_PRIVACY_RELAY_MAX_FEE=7
PUBLIC_PRIVACY_RELAY_REFILL=4.6

    Treat the fee cap and refill as operator-selected limits, not universal defaults. Estimate current fees and fund both public gas and the shielded payment balance before enabling this mode.

    Keep API keys and wallet material in the macOS Keychain. The settings above are addresses, limits, and service URLs, not credentials. The merchant reads the same .env when started from this repository.

  5. 05 / SERVICES

    Give the merchant a public origin.

    Start the paywalled merchant, then expose its loopback port through a temporary Cloudflare Quick Tunnel. Set MERCHANT_TRUST_PROXY=1 so the merchant advertises the public HTTPS URL instead of its local HTTP listener.

    Merchant and Cloudflare Quick Tunnel

    MERCHANT_TRUST_PROXY=1 npm run start:merchant
cloudflared tunnel --url http://127.0.0.1:8788

    Copy the tunnel's https:// host and append/article/agent-privacy. Use the full paid resource URL, for examplehttps://<your-tunnel-host>/article/agent-privacy; the merchant's root index is free and does not exercise the 402 flow. The MCP correctly rejects localhost for merchant payment requests because Tor cannot reach a local listener.

    Local MCP server (not hosted on Vercel)

    TOR_SOCKS_PROXY=socks5://127.0.0.1:9050 npm run start:server
    Legacy script versus the recommended MCP flow

    The standalone scripts/pay-paywall.mjs is a legacy/manual maintenance path, not part of the Keychain setup and not the recommended verifier. It requires separate raw-key environment values: ACCOUNT_ADDRESS,ACCOUNT_PRIVATE_KEY, AVNU_API_KEY,HELPER_ADDRESS, and POOL_ADDRESS. The Keychain setup does not provide these raw-key variables, so this command is not compatible with it. Do not put literal keys in this page; use a private, gitignored .env only for manual maintenance of this legacy script.

    Direct localhost payer (separate legacy path)

    npm run pay:paywall -- http://127.0.0.1:8788/article/agent-privacy --dry

    The recommended path is the MCP verifier below: it uses the Keychain wallet setup, the public HTTPS paid resource URL, and Tor for both the unpaid and signed requests.

  6. 06 / CLIENTS

    Connect Codex or Claude.

    Register the same loopback Streamable HTTP MCP endpoint in your client.

    Codex

    codex mcp add tony-strk --url http://127.0.0.1:8787/mcp

    Claude Code

    claude mcp add --scope user --transport http tony-strk http://127.0.0.1:8787/mcp

    Ask the client for wallet_status first. Then usepay for a direct private transfer or pay_paywall with the copied public HTTPS merchant URL.

  7. 07 / VERIFICATION

    Prove each boundary.

    Deterministic tests spend nothing. The verifier checks the live MCP, Tor, tool registration, and wallet status before it attempts a payment. Add --live only when the shielded note is mature and you intend to spend STRK on the configured network.

    Deterministic and preflight checks

    npm test
npm run verify:mcp
npm run verify:x402 -- --url https://<your-tunnel-host>/article/agent-privacy

    Opt-in live x402 payment

    npm run verify:x402 -- --url https://<your-tunnel-host>/article/agent-privacy --live

    A successful live run reports paid: true, HTTP 200, the settlement transaction hash, an explorer URL, and protected content. Do not paste a secret or a private URL into shell examples.

  8. 08 / LIMITS

    Know what the route reveals.

    Tor hides the MCP host IP from the merchant, while the stateless fetcher keeps no browser session. The merchant still sees a public settlement receipt, amount, timing, and its own public URL. Deposits and withdrawals are visible on-chain; privacy begins inside the shared STRK20 pool. OHTTP is not configured by this app, and this is not logged-in browsing.

    Mainnet scope. The AVNU-sponsored route keeps the submitting account out of the transaction. The public-relay fallback does not: its relayer and payment timing are public on-chain even though the STRK20 proof and merchant receipt are genuine.

    Return to the landing page