pion-mcp 0.3.0 → 0.4.0

package/README.md

@@ -3,8 +3,10 @@
 **Model Context Protocol server for Pi Network** — connect AI agents
 (Claude, Cursor, and any MCP-compatible client) to Pi Network chain data.
 
-> ⚠️ Testnet only. Read-only by default; `send_payment` moves real funds and
-> must be explicitly armed.
+> ⚠️ **Reads: both networks. Payments: testnet only.** The chain tools query Pi
+> Mainnet or Pi Testnet, selected with `PION_NETWORK`. `send_payment` moves real
+> funds, must be explicitly armed, and *cannot* be armed on mainnet — Pi
+> restricts App-to-User payments to testnet.
 
 ## Why "Pion"?
 The pion is the π meson — the particle physicists named after pi.
@@ -18,7 +20,8 @@ and move no value. Tier C is the exception and is off unless you arm it.
 (Tiers refer to [`docs/tool-mapping.md`](https://github.com/jleeblack/pion-mcp/blob/main/docs/tool-mapping.md).)
 
 **Tier A — chain reads.** Zero-permission queries against Pi's public Horizon
-API. No credentials at all.
+API. No credentials at all. These work on **both Pi chains** — testnet by
+default, mainnet with `PION_NETWORK=mainnet`.
 
 | Tool | What it does |
 |---|---|
@@ -29,6 +32,13 @@ API. No credentials at all.
 Amounts are decimal strings. Pi is reported as the asset `PI`, custom tokens as
 `CODE:ISSUER`, and liquidity-pool shares as `pool:ID`.
 
+Every result names the chain it came from in a `network` field, and the startup
+banner says it too. That redundancy is deliberate: **the same address can hold
+different balances on both chains**, so a query against the wrong network does
+not reliably fail — it can return a plausible, well-formed, wrong number
+(measured 2026-08-14; see [`docs/pi-sdk-notes.md`](https://github.com/jleeblack/pion-mcp/blob/main/docs/pi-sdk-notes.md)).
+Testnet Pi has no monetary value.
+
 **Tier B — identity.**
 
 | Tool | What it does |
@@ -60,8 +70,8 @@ alone is not enough — Pi needs that consent to resolve their wallet, and
 refuses payment creation with `missing_scope` otherwise. This is the
 recipient's consent, not your credentials.
 
-Arming requires **all four**, and Pi restricts A2U to testnet, so a non-testnet
-Horizon URL is refused outright:
+Arming requires **all four**, and Pi restricts A2U to testnet, so anything but
+Pi Testnet is refused outright:
 
 ```sh
 PION_ENABLE_PAYMENTS=1     # explicit switch, deliberately separate from credentials
@@ -120,7 +130,8 @@ claude mcp add pion -- node /absolute/path/to/pion-mcp/dist/index.js
 
 | Variable | Default | Purpose |
 |---|---|---|
-| `PION_HORIZON_URL` | `https://api.testnet.minepi.com` | Horizon base URL |
+| `PION_NETWORK` | `testnet` | Which chain the read tools query — `testnet` or `mainnet` |
+| `PION_HORIZON_URL` | derived from `PION_NETWORK` | Horizon base URL, overriding the above |
 | `PION_PLATFORM_URL` | `https://api.minepi.com` | Platform API base URL |
 | `PION_ENABLE_PAYMENTS` | unset (off) | Arms `send_payment` — see Tier C above |
 | `PION_MAX_PAYMENT_PI` | unset | Required per-payment ceiling when armed |
@@ -130,16 +141,24 @@ claude mcp add pion -- node /absolute/path/to/pion-mcp/dist/index.js
 For read-only use there is nothing to configure — `verify_user` takes its token
 as a call argument, not from the environment. The bottom four are needed only
 if you arm payments, and belong in a secrets manager, never in a committed
-file. The mainnet Horizon URL is still an open
-question — see the TODO in [`docs/pi-sdk-notes.md`](https://github.com/jleeblack/pion-mcp/blob/main/docs/pi-sdk-notes.md).
+file.
+
+`PION_NETWORK` and `PION_HORIZON_URL` are resolved once, in one place, into a
+single network object that the Horizon client, the banner, every tool result and
+the arming check all read. Setting both to contradictory chains is a startup
+error rather than a silent winner, and an unrecognised `PION_HORIZON_URL`
+resolves to an explicitly *unknown* chain — never to a Pi network by
+resemblance.
 
 ## Development
 
 ```sh
 npm run build      # compile src/ -> dist/
 npm run typecheck  # types only, no emit
-npm run smoke      # end-to-end: drives the built server against live testnet
-npm run arming     # Tier C guards and spend cap (no credentials needed)
+npm run smoke          # end-to-end against live testnet
+npm run smoke:mainnet  # the same checks against live mainnet
+npm run crossnet       # proves the two chains are actually distinguished
+npm run arming         # Tier C guards and spend cap (no credentials needed)
 ```
 
 `npm run smoke` spawns the server over stdio as a real MCP client, discovers a
@@ -150,9 +169,15 @@ It covers `verify_user` only on the **rejection** path — confirming a genuine
 token would need a real user credential, which the test deliberately does not
 handle. The success path is unverified; see below.
 
+`npm run crossnet` proves network selection is real rather than cosmetic. It
+does not rely on an address being absent from the other chain — that assumption
+is false — but on a wallet we control being testnet-only, and on a shared
+address returning *different* ledger state from each chain.
+
 `npm run arming` covers Tier C without touching real money: every refusal
 branch, the exact cap boundary, that credentials alone do not arm it, that a
-disarmed server does not advertise the tool, and that neither secret leaks into
+disarmed server does not advertise the tool, that a fully-credentialled mainnet
+server still refuses to advertise it, and that neither secret leaks into
 a result. It uses a freshly generated, never-funded keypair. The one live call
 it makes is a deliberately-rejected create against the Pi API, which proves the
 first failure stage end to end.
@@ -177,7 +202,7 @@ first failure stage end to end.
 
   This is why it ships **off**, and why turning it on takes four separate,
   deliberate acts: `PION_ENABLE_PAYMENTS=1`, a mandatory `PION_MAX_PAYMENT_PI`
-  ceiling, both credentials, and a testnet Horizon URL. Holding the credentials
+  ceiling, both credentials, and Pi Testnet as the selected network. Holding the credentials
   is not enough on its own. Disarmed, the tool is not registered at all, so an
   agent cannot see that a spending capability exists — that gate is deliberate
   design (see Tier C above), not a placeholder for unfinished work. The
@@ -195,9 +220,22 @@ wallet Pi will actually spend from.
 
 ## Roadmap
 
-The rest of Tier C: `get_payment_status`, `list_incomplete_payments`,
+Done in v0.4: mainnet reads. The rest of Tier C: `get_payment_status`, `list_incomplete_payments`,
 `approve_payment` / `complete_payment` / `cancel_payment` — the U2A backend half
 and the recovery tooling for stranded payments. See
 [`docs/tool-mapping.md`](https://github.com/jleeblack/pion-mcp/blob/main/docs/tool-mapping.md).
 
+## Legal
+
+The code is Apache-2.0; see [`LICENSE`](LICENSE). The website and the hosted U2A
+endpoints are covered separately by the
+[Privacy Policy](https://pionmcp.com/privacy) and
+[Terms of Service](https://pionmcp.com/terms) — sources in
+[`site/privacy.html`](site/privacy.html) and [`site/terms.html`](site/terms.html).
+Where the two disagree about the software itself, the Apache licence wins.
+
+Short version: the MCP server has no telemetry and talks only to Pi's public
+endpoints, the site sets no cookies and runs no analytics, and nothing here is
+stored in a database — there isn't one.
+
 *Unofficial community project — not affiliated with Pi Network.*

package/dist/horizon.d.ts

@@ -4,7 +4,13 @@
  * Every endpoint used here is public and unauthenticated — no API key, no
  * bearer token, no wallet secret. See docs/pi-sdk-notes.md, "Layer 3".
  */
-/** Horizon base URL. Defaults to Pi testnet; override with PION_HORIZON_URL. */
+/**
+ * Horizon base URL for the selected network.
+ *
+ * Derived from the resolved network rather than read from the environment
+ * directly, so there is exactly one place that decides which chain we are on.
+ * `PION_NETWORK` and `PION_HORIZON_URL` are both handled in networks.ts.
+ */
 export declare const HORIZON_URL: string;
 /** A Horizon request that failed — network, timeout, or non-2xx response. */
 export declare class HorizonError extends Error {

package/dist/horizon.js

@@ -4,10 +4,16 @@
  * Every endpoint used here is public and unauthenticated — no API key, no
  * bearer token, no wallet secret. See docs/pi-sdk-notes.md, "Layer 3".
  */
-const DEFAULT_HORIZON_URL = "https://api.testnet.minepi.com";
+import { NETWORK } from "./networks.js";
 const REQUEST_TIMEOUT_MS = 15_000;
-/** Horizon base URL. Defaults to Pi testnet; override with PION_HORIZON_URL. */
-export const HORIZON_URL = (process.env.PION_HORIZON_URL ?? DEFAULT_HORIZON_URL).replace(/\/+$/, "");
+/**
+ * Horizon base URL for the selected network.
+ *
+ * Derived from the resolved network rather than read from the environment
+ * directly, so there is exactly one place that decides which chain we are on.
+ * `PION_NETWORK` and `PION_HORIZON_URL` are both handled in networks.ts.
+ */
+export const HORIZON_URL = NETWORK.horizonUrl;
 /** A Horizon request that failed — network, timeout, or non-2xx response. */
 export class HorizonError extends Error {
     status;
@@ -55,7 +61,15 @@ async function describeFailure(response, path) {
         // Non-JSON error body — fall through to the generic message.
     }
     if (response.status === 404) {
-        return `Not found on Horizon (${HORIZON_URL}${path}). The account or transaction does not exist on this network, or has never been funded.`;
+        // Name the network. A common cause of a surprising 404 is looking for an
+        // account on the chain it does not live on, and that is invisible unless
+        // said. Note the asymmetry: a 404 is evidence the address is absent *here*,
+        // but a success is not evidence you asked the right chain — some addresses
+        // exist on both with different balances (docs/FINDINGS.md, finding 5).
+        return (`Not found on ${NETWORK.label} Horizon (${HORIZON_URL}${path}). The account or ` +
+            `transaction does not exist on ${NETWORK.label}, or has never been funded. ` +
+            "Pi Mainnet and Pi Testnet are separate ledgers sharing one address format, so " +
+            "this address may still be real on the other chain.");
     }
     const parts = [problem.title, problem.detail, problem.extras?.reason].filter(Boolean);
     return parts.length > 0

package/dist/index.js

@@ -12,11 +12,17 @@
  *
  * Tiers A and B read no credentials from the environment and cannot move
  * value. Tier C is the sole exception and is off by default.
+ *
+ * Networks: Tier A reads either Pi chain, selected with PION_NETWORK and
+ * reported in the `network` field of every result. Tier C is testnet-only —
+ * Pi restricts A2U to testnet, so mainnet selection makes payments unarmable
+ * rather than merely discouraged. See src/networks.ts and src/payments.ts.
  */
 import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { HORIZON_URL } from "./horizon.js";
+import { NETWORK, NETWORK_ERROR, NETWORK_WARNING } from "./networks.js";
 import { checkPaymentsArming } from "./payments.js";
 import { PLATFORM_URL } from "./platform.js";
 import { registerGetAccountPayments } from "./tools/get-account-payments.js";
@@ -29,7 +35,6 @@ import { registerVerifyUser } from "./tools/verify-user.js";
 // whether running the build or the sources directly. Resolved at runtime
 // rather than imported so the JSON never has to be copied into dist/.
 const { version: VERSION } = createRequire(import.meta.url)("../package.json");
-const NETWORK = HORIZON_URL.includes("testnet") ? "Pi Testnet" : `custom (${HORIZON_URL})`;
 if (process.argv.includes("--version") || process.argv.includes("-v")) {
     process.stdout.write(`${VERSION}\n`);
     process.exit(0);
@@ -45,9 +50,13 @@ if (process.argv.includes("--help") || process.argv.includes("-h")) {
         "       send_payment (only when explicitly armed — see below)",
         "",
         "Environment:",
-        "  PION_HORIZON_URL   Horizon base URL (default: https://api.testnet.minepi.com)",
+        "  PION_NETWORK       testnet (default) or mainnet — which chain the read tools query",
+        "  PION_HORIZON_URL   Horizon base URL, overriding PION_NETWORK's default",
         "  PION_PLATFORM_URL  Platform API base URL (default: https://api.minepi.com)",
         "",
+        "Reads work on both Pi chains. Payments do not: Pi restricts App-to-User",
+        "payments to testnet, so send_payment cannot be armed when PION_NETWORK=mainnet.",
+        "",
         "Arming send_payment (all four required; testnet only):",
         "  PION_ENABLE_PAYMENTS=1  explicit switch, separate from credentials",
         "  PION_MAX_PAYMENT_PI     required per-payment ceiling, in Pi",
@@ -57,10 +66,19 @@ if (process.argv.includes("--help") || process.argv.includes("-h")) {
     ].join("\n"));
     process.exit(0);
 }
+// A network we cannot identify is a network we will not serve. Reported here,
+// after --help/--version, so a misconfigured operator can still read the usage.
+if (NETWORK_ERROR) {
+    console.error(`pion-mcp: ${NETWORK_ERROR.message}`);
+    process.exit(1);
+}
 const server = new McpServer({ name: "pion-mcp", version: VERSION }, {
     instructions: `Pion exposes read-only Pi Network data. get_wallet_balance, get_account_payments, ` +
         `and query_transaction are public ledger reads from Horizon at ${HORIZON_URL} ` +
-        `(${NETWORK}), needing no credentials. Amounts are decimal strings; Pi itself is ` +
+        `(${NETWORK.label}), needing no credentials. This server is reading ` +
+        `${NETWORK.label} — every result repeats it in its "network" field, and the two Pi ` +
+        `chains are separate ledgers, so an address funded on one does not exist on the ` +
+        `other. Amounts are decimal strings; Pi itself is ` +
         'reported as the asset "PI", custom tokens as "CODE:ISSUER", and liquidity-pool ' +
         'shares as "pool:ID". verify_user is different: it checks a user access token ' +
         `against the Pi Platform API at ${PLATFORM_URL} and requires the caller to supply ` +
@@ -73,17 +91,27 @@ registerVerifyUser(server);
 // Tier C is registered only when fully armed. A disarmed server does not
 // advertise a payment tool at all, so an agent cannot try to spend and cannot
 // be talked into thinking it might succeed.
-const payments = checkPaymentsArming(HORIZON_URL);
+//
+// Passed the resolved network, not the URL: arming turns on what chain this
+// *is*, and a string containing "testnet" is not the same claim.
+const payments = checkPaymentsArming(NETWORK);
 if (payments.armed) {
     registerSendPayment(server, payments.config);
 }
 async function main() {
     // stdout is the JSON-RPC channel — every log line must go to stderr.
     await server.connect(new StdioServerTransport());
-    console.error(`pion-mcp ${VERSION} ready on stdio — Horizon: ${HORIZON_URL} (${NETWORK})`);
+    // The chain is stated first and unabbreviated. A user who never sees this
+    // line still gets it on every result, but the one who does see it should not
+    // have to infer mainnet from a hostname.
+    const emphasis = NETWORK.id === "mainnet" ? " — REAL VALUE" : "";
+    console.error(`pion-mcp ${VERSION} ready on stdio — reading ${NETWORK.label}${emphasis} ` +
+        `(Horizon: ${HORIZON_URL})`);
+    if (NETWORK_WARNING)
+        console.error(`⚠ ${NETWORK_WARNING}`);
     console.error(payments.armed
         ? `⚠ send_payment ARMED — can spend up to ${payments.config.maxAmountPi} Pi per call from the app wallet`
-        : `send_payment disabled (${payments.reason})`);
+        : `send_payment disabled — ${payments.reason}`);
 }
 main().catch((error) => {
     console.error("pion-mcp failed to start:", error);

package/dist/networks.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Which Pi chain this server reads.
+ *
+ * One resolved object is the single source of truth. Everything downstream —
+ * the Horizon client, the startup banner, the `network` field on every read
+ * result, and the payments arming check — reads it instead of re-deriving the
+ * network by sniffing a URL string.
+ *
+ * That is the point. Before v0.4 the network was inferred in two places by
+ * testing `HORIZON_URL.includes("testnet")`: once for the banner, once for
+ * arming. Two independent sniffs of one string is how a configuration ends up
+ * testnet by one check and mainnet by another.
+ *
+ * Values below were verified against the live nodes on 2026-08-14, not assumed
+ * from the naming pattern. See docs/pi-sdk-notes.md, "Layer 3".
+ */
+export type NetworkId = "testnet" | "mainnet" | "custom";
+export interface PiNetwork {
+    id: NetworkId;
+    /** Horizon base URL, no trailing slash. */
+    horizonUrl: string;
+    /** Human-facing name, for banners and tool output. NOT a signing input. */
+    label: string;
+    /**
+     * The Stellar network passphrase, as reported by the node itself.
+     * `undefined` for a custom endpoint, whose chain identity we cannot vouch for.
+     */
+    passphrase: string | undefined;
+    /** Block explorer base, for pointing a human at independent confirmation. */
+    explorerUrl: string | undefined;
+    /**
+     * True only for the genuine Pi Testnet. This is the flag payments arm on;
+     * nothing else may set it, including a custom endpoint that looks testnet-ish.
+     */
+    isTestnet: boolean;
+}
+export declare const PI_TESTNET: PiNetwork;
+export declare const PI_MAINNET: PiNetwork;
+/**
+ * Pi publishes a secondary mainnet Horizon at https://api2.mainnet.minepi.com
+ * (from `REACT_APP_MAINNET_SECONDARY_API_URL` in the explorer's production
+ * build). It is live and reports the same passphrase.
+ *
+ * Deliberately not wired as automatic failover. Two hosts silently serving one
+ * client can disagree — different ingestion lag, one stale — and a read that
+ * quietly changes source is exactly the kind of thing that makes a later
+ * "the balance was wrong" impossible to reconstruct. Set PION_HORIZON_URL to it
+ * by hand if the primary is down.
+ */
+export declare const PI_MAINNET_SECONDARY_URL = "https://api2.mainnet.minepi.com";
+/** A `PION_NETWORK` / `PION_HORIZON_URL` combination we refuse to guess at. */
+export declare class NetworkConfigError extends Error {
+    constructor(message: string);
+}
+export interface Resolution {
+    network: PiNetwork;
+    /** Non-fatal note for the operator, printed at startup. */
+    warning?: string;
+}
+/**
+ * Resolves the network from the environment.
+ *
+ * Pure and env-injectable so the guards can be tested without mutating the
+ * real process environment.
+ */
+export declare function resolveNetwork(env?: NodeJS.ProcessEnv): Resolution;
+export declare const NETWORK: PiNetwork;
+export declare const NETWORK_WARNING: string | undefined;
+export declare const NETWORK_ERROR: NetworkConfigError | undefined;

package/dist/networks.js

@@ -0,0 +1,135 @@
+/**
+ * Which Pi chain this server reads.
+ *
+ * One resolved object is the single source of truth. Everything downstream —
+ * the Horizon client, the startup banner, the `network` field on every read
+ * result, and the payments arming check — reads it instead of re-deriving the
+ * network by sniffing a URL string.
+ *
+ * That is the point. Before v0.4 the network was inferred in two places by
+ * testing `HORIZON_URL.includes("testnet")`: once for the banner, once for
+ * arming. Two independent sniffs of one string is how a configuration ends up
+ * testnet by one check and mainnet by another.
+ *
+ * Values below were verified against the live nodes on 2026-08-14, not assumed
+ * from the naming pattern. See docs/pi-sdk-notes.md, "Layer 3".
+ */
+export const PI_TESTNET = {
+    id: "testnet",
+    horizonUrl: "https://api.testnet.minepi.com",
+    label: "Pi Testnet",
+    passphrase: "Pi Testnet",
+    explorerUrl: "https://blockexplorer.minepi.com/testnet",
+    isTestnet: true,
+};
+export const PI_MAINNET = {
+    id: "mainnet",
+    horizonUrl: "https://api.mainnet.minepi.com",
+    label: "Pi Mainnet",
+    /**
+     * "Pi Network" — NOT "Pi Mainnet".
+     *
+     * This is the one value here that the naming pattern gets wrong, and getting
+     * it wrong is expensive: the passphrase is hashed into every signature, so a
+     * transaction signed against the wrong string is invalid on the chain it was
+     * meant for.
+     *
+     * Verified three ways on 2026-08-14:
+     *   1. `GET https://api.mainnet.minepi.com/` reports
+     *      `"network_passphrase": "Pi Network"`. For a Stellar network the node's
+     *      own answer is definitive — it is the string it validates against.
+     *   2. The secondary node, api2.mainnet.minepi.com, reports the same.
+     *   3. The string "Pi Mainnet" *does* appear in Pi's production explorer
+     *      bundle, but only as English UI copy ("...not been activated on the Pi
+     *      Mainnet yet"). It is a display label that reads like corroboration and
+     *      is not. Hence `label` and `passphrase` are separate fields here.
+     */
+    passphrase: "Pi Network",
+    explorerUrl: "https://blockexplorer.minepi.com/mainnet",
+    isTestnet: false,
+};
+/**
+ * Pi publishes a secondary mainnet Horizon at https://api2.mainnet.minepi.com
+ * (from `REACT_APP_MAINNET_SECONDARY_API_URL` in the explorer's production
+ * build). It is live and reports the same passphrase.
+ *
+ * Deliberately not wired as automatic failover. Two hosts silently serving one
+ * client can disagree — different ingestion lag, one stale — and a read that
+ * quietly changes source is exactly the kind of thing that makes a later
+ * "the balance was wrong" impossible to reconstruct. Set PION_HORIZON_URL to it
+ * by hand if the primary is down.
+ */
+export const PI_MAINNET_SECONDARY_URL = "https://api2.mainnet.minepi.com";
+const KNOWN = {
+    testnet: PI_TESTNET,
+    mainnet: PI_MAINNET,
+};
+/** A `PION_NETWORK` / `PION_HORIZON_URL` combination we refuse to guess at. */
+export class NetworkConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NetworkConfigError";
+    }
+}
+/**
+ * Resolves the network from the environment.
+ *
+ * Pure and env-injectable so the guards can be tested without mutating the
+ * real process environment.
+ */
+export function resolveNetwork(env = process.env) {
+    const requestedRaw = env.PION_NETWORK?.trim();
+    const requested = requestedRaw?.toLowerCase();
+    if (requested !== undefined && requested !== "" && KNOWN[requested] === undefined) {
+        throw new NetworkConfigError(`PION_NETWORK must be "testnet" or "mainnet", got "${requestedRaw}". ` +
+            "Refusing to start rather than guessing which chain you meant.");
+    }
+    const selected = requested ? KNOWN[requested] : PI_TESTNET;
+    const override = env.PION_HORIZON_URL?.trim().replace(/\/+$/, "");
+    if (!override)
+        return { network: selected };
+    const matched = Object.values(KNOWN).find((candidate) => candidate.horizonUrl === override);
+    if (matched) {
+        // Both variables are set and they name different chains. One of them is a
+        // mistake and we cannot tell which, so stop instead of picking a winner.
+        if (requested && matched.id !== selected.id) {
+            throw new NetworkConfigError(`PION_NETWORK=${selected.id} and PION_HORIZON_URL=${override} name different ` +
+                `networks (${selected.label} vs ${matched.label}). Set one or the other, not both.`);
+        }
+        return { network: matched };
+    }
+    // An endpoint we have not verified. It may well be a proxy in front of the
+    // real testnet, but we cannot confirm that from here, and "probably testnet"
+    // is not a basis for arming a spend. Label it honestly as unknown.
+    return {
+        network: {
+            id: "custom",
+            horizonUrl: override,
+            label: `custom endpoint (${override})`,
+            passphrase: undefined,
+            explorerUrl: undefined,
+            isTestnet: false,
+        },
+        warning: `PION_HORIZON_URL points at ${override}, which is not a Pi network Pion knows. ` +
+            "Reads will be attempted against it and reported as an unverified chain; " +
+            "payments cannot be armed against a custom endpoint.",
+    };
+}
+/**
+ * Resolved once at startup. On a configuration error this falls back to testnet
+ * — the safe default — and records the error for `index.ts` to report before it
+ * serves anything. Throwing from module scope would surface as a bare stack
+ * trace from an import, which is not a useful thing to hand an operator.
+ */
+let resolutionError;
+let resolved;
+try {
+    resolved = resolveNetwork();
+}
+catch (error) {
+    resolutionError = error;
+    resolved = { network: PI_TESTNET };
+}
+export const NETWORK = resolved.network;
+export const NETWORK_WARNING = resolved.warning;
+export const NETWORK_ERROR = resolutionError;

package/dist/payments.d.ts

@@ -11,6 +11,7 @@
  * argument, returned in a result, or logged.
  */
 import { z } from "zod";
+import { type PiNetwork } from "./networks.js";
 export interface PaymentsConfig {
     serverApiKey: string;
     walletSecret: string;
@@ -59,6 +60,7 @@ export declare function paymentMetadata(supplied?: Record<string, unknown>): Rec
 export declare const createdPaymentSchema: z.ZodObject<{
     identifier: z.ZodString;
     to_address: z.ZodString;
+    from_address: z.ZodString;
     amount: z.ZodNumber;
     status: z.ZodObject<{
         developer_approved: z.ZodBoolean;
@@ -94,4 +96,4 @@ export declare function recordedAmountToStroops(amount: number): bigint;
  * Decides whether payments may run at all. Returns a specific reason on
  * refusal so an operator can tell a missing switch from a missing credential.
  */
-export declare function checkPaymentsArming(horizonUrl: string): PaymentsArming;
+export declare function checkPaymentsArming(network: PiNetwork): PaymentsArming;

package/dist/payments.js

@@ -11,6 +11,7 @@
  * argument, returned in a result, or logged.
  */
 import { z } from "zod";
+import { PI_TESTNET } from "./networks.js";
 /** Stellar amounts carry 7 decimal places; 1 Pi = 10^7 stroops. */
 const STROOPS_PER_PI = 10000000n;
 const AMOUNT_PATTERN = /^\d+(\.\d{1,7})?$/;
@@ -65,6 +66,14 @@ export const createdPaymentSchema = z.object({
     identifier: z.string().min(1),
     /** The recipient's wallet. Present on create — no separate lookup needed. */
     to_address: z.string().regex(STELLAR_ADDRESS, "is not a Stellar public key"),
+    /**
+     * The wallet Pi expects to send from — the app wallet *selected* in the
+     * Developer Portal, which is not necessarily the one `PI_WALLET_SECRET`
+     * unlocks. Observed 2026-08-01: Pi returns the selected wallet here
+     * regardless of what key the app actually holds, so this is the only place
+     * the two can be compared before signing.
+     */
+    from_address: z.string().regex(STELLAR_ADDRESS, "is not a Stellar public key"),
     /** Pi's record of the amount, to be cross-checked against what was asked. */
     amount: z.number().finite(),
     status: z.object({
@@ -106,7 +115,7 @@ export function recordedAmountToStroops(amount) {
  * Decides whether payments may run at all. Returns a specific reason on
  * refusal so an operator can tell a missing switch from a missing credential.
  */
-export function checkPaymentsArming(horizonUrl) {
+export function checkPaymentsArming(network) {
     const enable = process.env.PION_ENABLE_PAYMENTS;
     if (enable !== "1" && enable?.toLowerCase() !== "true") {
         return {
@@ -116,11 +125,29 @@ export function checkPaymentsArming(horizonUrl) {
     }
     // A2U is testnet-only per Pi's payments_advanced.md. Refuse anything else
     // rather than discovering the restriction mid-flow with a created payment.
-    if (!horizonUrl.includes("testnet")) {
+    //
+    // Two conditions, deliberately. Until v0.4 this was a single substring test
+    // for "testnet" in the Horizon URL, which any string containing that word
+    // satisfied — https://api.mainnet.minepi.com/#testnet included. Arming now
+    // requires the resolved network to *be* Pi Testnet, and a custom endpoint
+    // resolves to `custom` however testnet-ish its URL looks.
+    if (!network.isTestnet) {
         return {
             armed: false,
-            reason: `Horizon is set to ${horizonUrl}, which is not testnet. Pi restricts ` +
-                "App-to-User payments to testnet, and Pion will not attempt them elsewhere.",
+            reason: `the selected network is ${network.label} (${network.horizonUrl}), not Pi Testnet. ` +
+                "Pi restricts App-to-User payments to testnet, and Pion will not attempt them " +
+                "elsewhere. Payments cannot be armed while PION_NETWORK=mainnet or while " +
+                "PION_HORIZON_URL points at an endpoint Pion cannot identify.",
+        };
+    }
+    // Self-consistency assertion, not a second guess at the network. It cannot
+    // fire from any environment variable — only from someone editing the table in
+    // networks.ts so that `isTestnet` and the URL disagree.
+    if (network.horizonUrl !== PI_TESTNET.horizonUrl) {
+        return {
+            armed: false,
+            reason: `network table inconsistency: a network marked testnet points at ` +
+                `${network.horizonUrl}, not ${PI_TESTNET.horizonUrl}. Refusing to arm.`,
         };
     }
     const serverApiKey = process.env.PI_SERVER_API_KEY;

package/dist/tools/common.d.ts

@@ -1,5 +1,20 @@
 import { z } from "zod";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { PiNetwork } from "../networks.js";
+/**
+ * The sentence every Tier A tool description ends with.
+ *
+ * Named once so all three read tools say the same thing about the same fact.
+ * An agent that only ever sees a tool description — never the startup banner —
+ * still learns which chain it is reading and why that matters.
+ *
+ * The wording is deliberate about what a wrong-chain read looks like. Measured
+ * 2026-08-14: some Pi addresses hold a balance on *both* chains, with different
+ * amounts (docs/FINDINGS.md, finding 5). So querying the wrong network does not
+ * reliably produce a not-found error — it can produce a well-formed, plausible,
+ * wrong number. That is why the network is stated rather than implied.
+ */
+export declare function networkNote(network: PiNetwork): string;
 /** Stellar/Pi public key: 56 base32 characters beginning with G. */
 export declare const walletAddress: z.ZodString;
 /** Stellar transaction hash: 64 hex characters. */

package/dist/tools/common.js

@@ -1,6 +1,27 @@
 import { z } from "zod";
 import { HorizonError } from "../horizon.js";
 import { PlatformError } from "../platform.js";
+/**
+ * The sentence every Tier A tool description ends with.
+ *
+ * Named once so all three read tools say the same thing about the same fact.
+ * An agent that only ever sees a tool description — never the startup banner —
+ * still learns which chain it is reading and why that matters.
+ *
+ * The wording is deliberate about what a wrong-chain read looks like. Measured
+ * 2026-08-14: some Pi addresses hold a balance on *both* chains, with different
+ * amounts (docs/FINDINGS.md, finding 5). So querying the wrong network does not
+ * reliably produce a not-found error — it can produce a well-formed, plausible,
+ * wrong number. That is why the network is stated rather than implied.
+ */
+export function networkNote(network) {
+    return (`This server reads ${network.label}, and every result repeats that in its ` +
+        '"network" field — always report which chain a figure came from. Pi Mainnet ' +
+        "and Pi Testnet are separate ledgers sharing one address format, and the same " +
+        "address can hold different balances on each, so a result from the wrong chain " +
+        "looks entirely normal. Testnet Pi has no monetary value: never present a " +
+        "testnet balance as real holdings.");
+}
 /** Stellar/Pi public key: 56 base32 characters beginning with G. */
 export const walletAddress = z
     .string()

package/dist/tools/get-account-payments.d.ts

@@ -1,2 +1,3 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare function registerGetAccountPayments(server: McpServer, network: string): void;
+import type { PiNetwork } from "../networks.js";
+export declare function registerGetAccountPayments(server: McpServer, network: PiNetwork): void;

package/dist/tools/get-account-payments.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { cursorFromLink, formatAsset, horizonGet } from "../horizon.js";
-import { fail, ok, pagingCursor, pagingLimit, pagingOrder, walletAddress } from "./common.js";
+import { fail, networkNote, ok, pagingCursor, pagingLimit, pagingOrder, walletAddress, } from "./common.js";
 const paymentShape = z.object({
     id: z.string(),
     type: z.string(),
@@ -72,7 +72,8 @@ export function registerGetAccountPayments(server, network) {
             "a payment arrived, who funded an account, or what it recently sent. Covers " +
             "payments, account creations, path payments, and account merges. Results are " +
             "paginated: pass the returned `next_cursor` back as `cursor` for the next page. " +
-            "Reads public ledger data only.",
+            "Reads public ledger data only. " +
+            networkNote(network),
         inputSchema: {
             address: walletAddress,
             limit: pagingLimit,
@@ -93,7 +94,7 @@ export function registerGetAccountPayments(server, network) {
             // set. Only surface a cursor when the page came back full.
             const nextCursor = payments.length === limit ? cursorFromLink(page._links?.next?.href) : undefined;
             return ok({
-                network,
+                network: network.label,
                 account_id: address,
                 count: payments.length,
                 ...(nextCursor !== undefined ? { next_cursor: nextCursor } : {}),

package/dist/tools/get-wallet-balance.d.ts

@@ -1,2 +1,3 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare function registerGetWalletBalance(server: McpServer, network: string): void;
+import type { PiNetwork } from "../networks.js";
+export declare function registerGetWalletBalance(server: McpServer, network: PiNetwork): void;

package/dist/tools/get-wallet-balance.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { formatAsset, horizonGet } from "../horizon.js";
-import { fail, ok, walletAddress } from "./common.js";
+import { fail, networkNote, ok, walletAddress } from "./common.js";
 const outputSchema = {
     network: z.string(),
     account_id: z.string(),
@@ -21,7 +21,8 @@ export function registerGetWalletBalance(server, network) {
         description: "Read the current Pi and custom-token balances of a Pi wallet address. " +
             "Call this whenever you need to know how much Pi an address holds, whether it " +
             "holds a particular token, or whether the account exists on-chain at all. " +
-            "Reads public ledger data only — it cannot move funds and needs no credentials.",
+            "Reads public ledger data only — it cannot move funds and needs no credentials. " +
+            networkNote(network),
         inputSchema: { address: walletAddress },
         outputSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
@@ -29,7 +30,7 @@ export function registerGetWalletBalance(server, network) {
         try {
             const account = await horizonGet(`/accounts/${address}`);
             return ok({
-                network,
+                network: network.label,
                 account_id: account.account_id,
                 sequence: account.sequence,
                 subentry_count: account.subentry_count,

package/dist/tools/query-transaction.d.ts

@@ -1,2 +1,3 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare function registerQueryTransaction(server: McpServer, network: string): void;
+import type { PiNetwork } from "../networks.js";
+export declare function registerQueryTransaction(server: McpServer, network: PiNetwork): void;

package/dist/tools/query-transaction.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { horizonGet } from "../horizon.js";
-import { fail, ok, transactionHash } from "./common.js";
+import { fail, networkNote, ok, transactionHash } from "./common.js";
 const outputSchema = {
     network: z.string(),
     hash: z.string(),
@@ -23,7 +23,8 @@ export function registerQueryTransaction(server, network) {
             "which ledger it landed in, who submitted it, the fee charged, and its memo. " +
             "Call this to verify that a specific transaction actually went through — a user " +
             "or another service claiming a payment was made is not proof; this is. " +
-            "Reads public ledger data only.",
+            "Reads public ledger data only. " +
+            networkNote(network),
         inputSchema: { hash: transactionHash },
         outputSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
@@ -31,7 +32,7 @@ export function registerQueryTransaction(server, network) {
         try {
             const tx = await horizonGet(`/transactions/${hash.toLowerCase()}`);
             return ok({
-                network,
+                network: network.label,
                 hash: tx.hash,
                 successful: tx.successful,
                 ledger: tx.ledger,

package/dist/tools/send-payment.js

@@ -3,7 +3,23 @@ import { HORIZON_URL } from "../horizon.js";
 import { platformPostAsApp } from "../platform.js";
 import { parseCreatedPayment, paymentMetadata, recordedAmountToStroops, toStroops, } from "../payments.js";
 import { ok } from "./common.js";
-/** Pi testnet's Stellar network passphrase (docs/pi-sdk-notes.md, Layer 3). */
+/**
+ * Pi testnet's Stellar network passphrase (docs/pi-sdk-notes.md, Layer 3).
+ *
+ * Hardcoded on purpose, and deliberately NOT read from the resolved network in
+ * networks.ts even though that object now carries a passphrase for each chain.
+ *
+ * This is the last barrier. Arming already refuses anything but Pi Testnet, so
+ * this constant should be unreachable on another chain — but "should be
+ * unreachable" is a claim about code that can be wrong. A passphrase is hashed
+ * into every signature, so a transaction signed with "Pi Testnet" is rejected
+ * outright by Pi Mainnet rather than moving funds on it. Wiring this to the
+ * network table would turn a bug in the arming logic from a rejected
+ * transaction into a real mainnet spend.
+ *
+ * The cost of keeping it fixed is that mainnet A2U would need a deliberate edit
+ * here. That is the intended cost, and Pi does not permit mainnet A2U anyway.
+ */
 const NETWORK_PASSPHRASE = "Pi Testnet";
 /** Stellar text memos are capped at 28 bytes. */
 const MAX_MEMO_BYTES = 28;
@@ -167,10 +183,34 @@ export function registerSendPayment(server, config) {
                     `${payment.status.developer_approved}). A2U is normally approved on ` +
                     "creation. Nothing was signed.", { paymentId, amount, uid });
             }
+            // Pi will only match a transaction sent from the wallet it selected.
+            // Signing with a different key produces a transfer Pi cannot verify:
+            // funds leave and the payment stays incomplete. The two are genuinely
+            // independent — Pi reports its selected wallet here whatever key we
+            // hold — so this is the one place the mismatch is catchable, and it is
+            // catchable only before signing.
+            if (payment.from_address !== keypair.publicKey()) {
+                return strandedReport("submit", `Pi expects this payment to be sent from ${payment.from_address}, but ` +
+                    `PI_WALLET_SECRET unlocks ${keypair.publicKey()}. Signing with the wrong ` +
+                    "wallet would move funds Pi could not match to this payment. Nothing was " +
+                    "signed. Select the right app wallet in the Developer Portal, or load the " +
+                    "secret for the wallet already selected.", { paymentId, amount, uid });
+            }
             // ---- Step 2: sign and submit on-chain. Irreversible. ----
             stage = "submit";
             const horizon = new Horizon.Server(HORIZON_URL);
-            const account = await horizon.loadAccount(keypair.publicKey());
+            let account;
+            try {
+                account = await horizon.loadAccount(keypair.publicKey());
+            }
+            catch {
+                // Horizon says "Not Found" here, which names neither the account nor
+                // the reason. On Stellar an account exists only once funded, so this
+                // is nearly always an unfunded app wallet.
+                return strandedReport("submit", `the app wallet ${keypair.publicKey()} does not exist on ${HORIZON_URL}. ` +
+                    "A Stellar account only exists once it has been funded, and an unfunded " +
+                    "account cannot send. Fund it and retry. Nothing was signed.", { paymentId, amount, uid });
+            }
             const baseFee = await horizon.fetchBaseFee();
             const tx = new TransactionBuilder(account, {
                 fee: String(baseFee),

package/package.json

@@ -1,58 +1,63 @@
-{
-  "name": "pion-mcp",
-  "version": "0.3.0",
-  "description": "Pion — Model Context Protocol (MCP) server for Pi Network. Read-only chain queries against Pi testnet Horizon.",
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "pi-network",
-    "ai-agents",
-    "blockchain",
-    "stellar",
-    "horizon"
-  ],
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/jleeblack/pion-mcp.git"
-  },
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "pion-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "engines": {
-    "node": ">=18.17"
-  },
-  "scripts": {
-    "build": "tsc",
-    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-    "typecheck": "tsc --noEmit",
-    "start": "node dist/index.js",
-    "smoke": "node scripts/smoke.mjs",
-    "arming": "node scripts/arming-test.mjs",
-    "u2a": "node scripts/u2a-test.mjs",
-    "incomplete": "node scripts/incomplete.mjs",
-    "probe:a2u": "node scripts/probe-a2u.mjs",
-    "diagnose:a2u": "node scripts/diagnose-a2u.mjs",
-    "identify:app": "node scripts/identify-app.mjs",
-    "browser-auth": "node scripts/browser-auth/serve.mjs",
-    "wallet": "node scripts/app-wallet.mjs",
-    "signin": "node scripts/pi-signin.mjs",
-    "prepack": "npm run clean && tsc --sourceMap false",
-    "send": "node scripts/send.mjs"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "@stellar/stellar-sdk": "^16.2.0",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@types/node": "^26.1.2",
-    "typescript": "^7.0.2"
-  }
-}
+{
+  "name": "pion-mcp",
+  "version": "0.4.0",
+  "description": "Pion — Model Context Protocol (MCP) server for Pi Network. Read-only chain queries against Pi Mainnet and Testnet; payments are testnet-only.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "pi-network",
+    "ai-agents",
+    "blockchain",
+    "stellar",
+    "horizon"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jleeblack/pion-mcp.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "pion-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js",
+    "smoke": "node scripts/smoke.mjs",
+    "smoke:mainnet": "node scripts/smoke.mjs --network=mainnet",
+    "crossnet": "node scripts/crossnet-test.mjs",
+    "arming": "node scripts/arming-test.mjs",
+    "u2a": "node scripts/u2a-test.mjs",
+    "incomplete": "node scripts/incomplete.mjs",
+    "probe:a2u": "node scripts/probe-a2u.mjs",
+    "diagnose:a2u": "node scripts/diagnose-a2u.mjs",
+    "identify:app": "node scripts/identify-app.mjs",
+    "browser-auth": "node scripts/browser-auth/serve.mjs",
+    "wallet": "node scripts/app-wallet.mjs",
+    "signin": "node scripts/pi-signin.mjs",
+    "prepack": "npm run clean && tsc --sourceMap false",
+    "send": "node scripts/send.mjs",
+    "get-payment": "node scripts/get-payment.mjs",
+    "cancel": "node scripts/cancel.mjs",
+    "complete": "node scripts/complete.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@stellar/stellar-sdk": "^16.2.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^7.0.2"
+  }
+}