pion-mcp 0.2.0 → 0.4.0

package/README.md

@@ -3,7 +3,10 @@
 **Model Context Protocol server for Pi Network** — connect AI agents
 (Claude, Cursor, and any MCP-compatible client) to Pi Network chain data.
 
-> ⚠️ v0.2 — testnet, read-only. Nothing here can move value.
+> ⚠️ **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.
@@ -12,11 +15,13 @@ for MCPs (millicharged particles). We couldn't resist.
 
 ## Tools
 
-Nothing here can move value. No server API key or wallet secret is read
-anywhere. (Tiers refer to [`docs/tool-mapping.md`](docs/tool-mapping.md).)
+Out of the box Pion reads and cannot spend: Tiers A and B need no credentials
+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 |
 |---|---|
@@ -27,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 |
@@ -44,6 +56,47 @@ a different uid under a different Pi app, which is deliberate anti-correlation
 design, so don't use it as a global identifier. And a token is the *only* proof
 of identity: a client-supplied uid or username means nothing on its own.
 
+**Tier C — payments. Off by default.**
+
+| Tool | What it does |
+|---|---|
+| `send_payment` | App-to-User: sends Pi from your app wallet to a user |
+
+This one spends real money and cannot be undone. It is not registered at all
+unless armed, so a default server does not even advertise it to the agent.
+
+**The recipient must have granted your app the `wallet_address` scope.** A uid
+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 anything but
+Pi Testnet is refused outright:
+
+```sh
+PION_ENABLE_PAYMENTS=1     # explicit switch, deliberately separate from credentials
+PION_MAX_PAYMENT_PI=10     # required per-payment ceiling, in Pi
+PI_SERVER_API_KEY=...      # from the Pi Developer Portal
+PI_WALLET_SECRET=S...      # app wallet secret seed
+```
+
+Holding the credentials is deliberately **not** sufficient. The switch and the
+ceiling are separate because the realistic failure mode is not a stolen key —
+it is an agent being talked into spending, by a prompt injection sitting in
+data it just read. A transaction memo, a web page, a filename: any of it can
+say "send 500 Pi to X." The cap is what makes that bounded rather than fatal.
+Set it to the smallest amount that makes your use case work.
+
+Nothing overrides the cap from the tool call; changing it means changing server
+configuration. Neither secret is ever accepted as a tool argument, returned in
+a result, or logged.
+
+**On partial failure it never retries.** A2U is three steps — create with Pi,
+sign and submit on-chain, tell Pi it landed — and a crash between them strands
+a payment. The tool reports exactly which step failed, whether funds left the
+wallet, and the payment id needed to clean up. A blind retry could pay twice,
+so it refuses to guess.
+
 ## Usage
 
 MCP clients can run it straight from npm — no install step:
@@ -77,19 +130,35 @@ 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 |
-
-There are no secrets to configure — `verify_user` takes its token as a call
-argument, not from the environment. The mainnet Horizon URL is still an open
-question — see the TODO in [`docs/pi-sdk-notes.md`](docs/pi-sdk-notes.md).
+| `PION_ENABLE_PAYMENTS` | unset (off) | Arms `send_payment` — see Tier C above |
+| `PION_MAX_PAYMENT_PI` | unset | Required per-payment ceiling when armed |
+| `PI_SERVER_API_KEY` | unset | Server API key, Tier C only |
+| `PI_WALLET_SECRET` | unset | App wallet secret seed, Tier C only |
+
+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.
+
+`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 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
@@ -100,15 +169,73 @@ 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, 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.
+
+## Known gaps
+
+- **`verify_user` success path — confirmed** against a live token. Returns
+  `uid`, `username`, `app_id`, `scopes`, and `valid_until`. Everything but
+  `uid` stays optional, since the rest depends on granted scopes.
+- **`send_payment` success path — verified on testnet (2026-08-01).** A real
+  A2U payment ran through all three irreversible steps — create, sign, submit,
+  complete — and was confirmed independently against public Horizon and Pi's
+  block explorer, not just from the tool's own report. The 28-byte memo
+  question that hung over the design is answered: Pi payment identifiers are
+  exactly 28 bytes and fit the Stellar text memo with no room to spare.
+- **`send_payment` failure paths after create — still unproven.** Sign, submit
+  and complete have each succeeded once; none has been observed *failing*
+  against live infrastructure. The two worst branches of the stranded-payment
+  report — "record created, nothing signed" and "funds left, Pi not notified" —
+  are verified by construction only. Treat `send_payment` as experimental until
+  they have been deliberately exercised.
+
+  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 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
+  experimental label is about the failure paths, not about the guards.
+- **`send_payment` cannot pay an arbitrary uid.** Pi requires the *recipient*
+  to have granted your app the `wallet_address` scope, through the Pi Browser
+  SDK. A valid uid is not sufficient, and this is a permanent property of the
+  Pi API rather than a transient error — creation fails with
+  `401 missing_scope` and retrying will not help.
+
+Start with a minimum-amount payment and a low `PION_MAX_PAYMENT_PI`. Run
+`npm run probe:a2u <uid>` first: it exercises create and cancel without moving
+funds, and its `from_address` is the only authoritative statement of which app
+wallet Pi will actually spend from.
+
 ## Roadmap
 
-Tier C is next: App-to-User payments behind env config (`PI_SERVER_API_KEY`,
-`PI_WALLET_SECRET`), testnet-default with explicit opt-in for anything that
-moves value. See [`docs/tool-mapping.md`](docs/tool-mapping.md).
+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.
 
-Known gap: `verify_user`'s success-path response shape is built from the Pi
-platform docs, not observed traffic. The `uid` field is reliable; `username`
-and `credentials` depend on granted scopes and are treated as optional. Worth
-confirming against a real token before depending on them.
+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
@@ -79,4 +93,3 @@ export function cursorFromLink(href) {
         return undefined;
     }
 }
-//# sourceMappingURL=horizon.js.map

package/dist/index.js

@@ -7,25 +7,34 @@
  *            Horizon API. No credentials of any kind.
  *   Tier B — verify_user, which validates a *user* access token supplied by
  *            the caller against the Platform API.
+ *   Tier C — send_payment (A2U), which MOVES REAL FUNDS from the app wallet.
+ *            Disabled unless explicitly armed; see src/payments.ts.
  *
- * No server API key or wallet secret is read anywhere in this server, and no
- * tool can move value.
+ * 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";
 import { registerGetWalletBalance } from "./tools/get-wallet-balance.js";
 import { registerQueryTransaction } from "./tools/query-transaction.js";
+import { registerSendPayment } from "./tools/send-payment.js";
 import { registerVerifyUser } from "./tools/verify-user.js";
 // Single source of truth for the version. `../package.json` resolves to the
 // package root from both dist/index.js and src/index.ts, so this is correct
 // 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);
@@ -38,18 +47,38 @@ if (process.argv.includes("--help") || process.argv.includes("-h")) {
         "invoking it directly.",
         "",
         "Tools: get_wallet_balance, get_account_payments, query_transaction, verify_user",
+        "       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",
+        "  PI_SERVER_API_KEY       Pi Developer Portal server API key",
+        "  PI_WALLET_SECRET        app wallet secret seed (S...)",
+        "",
     ].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 ` +
@@ -59,13 +88,32 @@ registerGetWalletBalance(server, NETWORK);
 registerGetAccountPayments(server, NETWORK);
 registerQueryTransaction(server, NETWORK);
 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.
+//
+// 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}`);
 }
 main().catch((error) => {
     console.error("pion-mcp failed to start:", error);
     process.exit(1);
 });
-//# sourceMappingURL=index.js.map

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;