@metalntwx/metal-agent 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nexus Networks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,177 @@
-# Temporary Holding Version
+# @metalntwx/metal-agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `metal-agent` CLI an agent pays x402 payees on Metal with: create or
+import a key, fund it, pay a URL, look up a settlement, or serve the same
+commands as MCP tools.
+
+```bash
+npm install -g @metalntwx/metal-agent
+
+metal-agent key create
+metal-agent key import <file|hex>
+metal-agent fund <address> --network testnet
+metal-agent pay https://x402-demo-testnet.metalntwx.com/quote --network testnet
+metal-agent status <txHash> --network testnet --rpc-url <endpoint>
+metal-agent mcp
+```
+
+`npx -y @metalntwx/metal-agent <command>` runs one command without
+installing.
+
+Every command that touches the chain names `--network devnet` or
+`--network testnet`; there is no default. Each network's facilitator URL,
+its RPC (devnet's default endpoint, or the console that issues testnet
+endpoints) and the `*USDZ` address come from `@metalntwx/metal-pay`, and
+`networks.json` holds its demo payee URL and, on testnet, its faucet and
+explorer URLs.
+`METAL_RPC_URL` and `METAL_FAUCET_URL` override those defaults, and
+`--rpc-url` and `--faucet-url` override both.
+
+On testnet, `pay` and `fund` need no RPC. `status --network testnet` needs
+an endpoint of your own: sign up in the Metal console,
+https://console-testnet.metalntwx.com, create an endpoint, and pass it with
+`--rpc-url` or `METAL_RPC_URL`. On testnet, `pay` and `fund` print
+an `explorer` line with the transaction's page on
+https://testnet.metalntwx.com.
+
+The key file defaults to `~/.metal-agent/key.json` and holds the private key
+in the clear, owner-readable only. `key import` takes a hex key (with or
+without `0x`), a file holding one, or a key file, and prints only the
+address.
+
+`fund --network testnet` asks the public faucet's `POST /api/fund`, and the
+faucet sets the amount. An address that already holds a full grant counts
+as funded. A rate-limited request fails with what to do next: retry after
+the stated wait, try tomorrow, or import a key someone funded for you.
+`fund --network devnet [--amount <n>]` spends from Foundry test account #0,
+which the devnet funds at genesis.
+
+`pay` refuses, before it signs, an offer in any token but `*USDZ` and any
+offer above `--max`, 1 `*USDZ` per payment by default. A refusal at
+verification prints `payment refused: <reason>`.
+A refusal at settlement prints `payment refused at settlement: <reason>`,
+with the transaction hash when there is one.
+
+`pay` sends `--method` (GET by default, POST with a body), `--body` (as `application/json`
+unless a `--header` names a content type) and each repeated
+`--header 'name: value'`, and sends them again with the payment. A JSON-RPC
+call to an RPC endpoint sold over x402, for example:
+
+```bash
+metal-agent pay <rpc url> --network testnet --method POST \
+  --body '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
+```
+
+`pay` prints the response headers before the body, as
+`header <name>: <value>` lines, leaving out transport, caching and CORS
+headers and the payment it reports above. An RPC seller such as Metal's
+answers with `rpc-aas-endpoint`, the endpoint the payment bought: send
+further JSON-RPC calls there, without paying again, until its credit runs
+out.
+
+## Spending limits
+
+A mandate lets an agent pay from its owner's account with a P-256 key of its
+own, within limits Metal enforces on chain: the most per payment, a budget
+for the mandate's whole life, an expiry and, when `--payee` names any, the
+addresses it may pay; with none named it may pay any address.
+
+```bash
+metal-agent mandate credential create --principal <MetalAccount address> [--payee <address>]... \
+  --cap 5 --budget 10 --out ./mandate.json --network testnet
+metal-agent mandate bind --credential ./mandate.json --key <owner key file> --network testnet --rpc-url <endpoint>
+metal-agent pay <url> --mandate ./mandate.json --network testnet
+metal-agent mandate status --credential ./mandate.json --network testnet --rpc-url <endpoint>
+metal-agent mandate replace --credential ./wider.json --replaces ./mandate.json --key <owner key file> --network testnet --rpc-url <endpoint>
+metal-agent mandate revoke --credential ./wider.json --key <owner key file> --network testnet --rpc-url <endpoint>
+metal-agent mandate pull --credential ./mandate.json --to <address> --amount 2.50 --network testnet --rpc-url <endpoint>
+metal-agent mandate verify --credential ./mandate.json --network testnet --rpc-url <endpoint>
+metal-agent mandate verify --credential ./mandate.json --tx <hash> --signed-offer <text> --network testnet --rpc-url <endpoint>
+```
+
+`credential create` writes the limits into a credential file, a Verifiable
+Intent mandate, and the agent's keys beside it: its mandate key in
+`mandate.agent-key.json`, and in `mandate.gas-key.json` the key that pays
+for its pulls. `--agent-key <file>` names a mandate key the agent already
+has instead, with its gas key beside that. The issuer keys that sign the
+credential are created on first use (`~/.metal-agent/issuer.json`, with its
+public half beside it in `issuer.public.json`). Every other command takes
+that credential file: the owner's account, the mandate's reference, its
+terms and the agent's key files derive from it. Amounts are whole cents; a
+mandate lasts 30 days unless `--expires-in` says otherwise.
+
+`account create --out <owner key file>` writes the owner's key and names the
+owner's Metal account, a smart account that key controls with threshold one,
+which the owner's first `bind` creates on chain; `--key <file>` uses a key
+that exists. Fund the account and name it as the credential's `--principal`.
+The account factory is the one `@metalntwx/metal-pay` names for the network;
+on a devnet `just deploy` deploys it there, and `--factory <address>` names
+another. The testnet's factory is redeployed with each reset, and
+`@metalntwx/metal-pay` names the current one.
+
+`bind`, `replace` and `revoke` execute self-calls through the account's weighted
+quorum. `--key` names the gas sponsor and defaults as the sole signer; repeat
+`--signer-key <file>` to supply the EOA signers of an existing multisig instead.
+The SDK's `authorizeMandateCall` accepts a quorum-signing callback for mixed
+keys and passkeys. Keep owner keys outside the agent's reach: quorum-approved
+transfers remain independent of mandates. `replace` revokes the mandate
+`--replaces` names and carries its spend into the new one.
+
+Verification trusts that factory, never one a payer names: it checks the
+account's immutable clone code against the factory's implementation at the
+binding and payment blocks, and checks successful token-transfer receipts.
+
+`pay --mandate <credential>` pays from the owner's account, signed by the
+agent's mandate key, and takes neither `--key` nor `--max`. A payment
+outside the mandate is refused at the facilitator's simulation, which names
+the limit: `payment refused: mandate_cap_exceeded (…)`. `pay` prints the
+payment's `nonce` as soon as it signs; the facilitator's
+`/settlements?payTo=<payee>` lists a settled payment by an id ending in it.
+
+`mandate pull` pays an address the mandate allows directly, with no seller:
+the agent's mandate key signs, and the `--key` account, the agent's gas key
+by default, submits the transaction and pays its gas, so fund it with a
+little `*USDZ`. A pull outside the mandate is recorded on chain as a
+refusal, in a transaction that succeeds and moves nothing, and exits 1.
+
+`mandate verify` checks the mandate and every payment under it from the
+chain alone, through any RPC endpoint: the binding on the owner's account,
+the credential against it and under its issuer, and each payment and
+refusal as the agent key's own signed per-payment mandate, rebuilt from its
+transaction. Anyone holding the credential can run it; `--tx <hash>`
+verifies one transaction, with `--signed-offer <text>` the offer the agent
+signed for it, and a check that fails exits 1. A seller that asks for the
+agent's signed order (`requireSignedOffer` in `@metalntwx/metal-pay/mandates`,
+with `extra.signedOffer: "required"` on the route) is paid with it, and
+`pay` prints it. From code, `verifyMandate` and `verifyMandatePayment` do
+the same, the latter for a payee that holds no credential.
+
+`skills/metal-agent/SKILL.md` is an installable skill: the setup steps for
+an agent, then the commands.
+
+`metal-agent mcp` serves `pay`, `fund` and `status` over stdio,
+each taking a `network`, and `pay` takes the same limit as an optional
+`max`, the request as optional `method`, `body` and `headers`, and a
+credential file as an optional `mandate`, with its `agentKey`. Keys
+enter only through the CLI, and so do the mandate commands: the server has
+no tool that sets or changes a mandate. An MCP host starts it with:
+
+```json
+{ "command": "npx", "args": ["-y", "@metalntwx/metal-agent", "mcp"] }
+```
+
+## Develop
+
+In the `mx56db/metal` repository, `just agent <command>` runs the CLI from
+source. Devnet `fund` signs through
+metal-ts's wasm codec; build it once with `just metal-ts-wasm`.
+
+`METAL_RPC_URL=<endpoint> just agent-testnet-smoke`
+(`scripts/testnet-smoke.ts`) runs the pay quickstart against the testnet
+services: it checks the
+facilitator's `/supported`, funds a throwaway key through the faucet (or uses
+`METAL_SMOKE_PRIVATE_KEY`), pays the demo payee, confirms the
+`MIP20Transfer` on chain, and exits non-zero on any failure.
+`METAL_FACILITATOR_URL` and `METAL_DEMO_PAYEE_URL` point it elsewhere.
+
+Run `pnpm test` and `pnpm typecheck`.

package/dist/chain.js

@@ -0,0 +1,55 @@
+import { readFileSync } from "node:fs";
+import { createPublicClient, defineChain, http } from "viem";
+import { USDZ, metalNetwork, rpcUrlFor } from "@metalntwx/metal-pay";
+const NETWORKS_FILE = new URL("../networks.json", import.meta.url);
+export function readNetworksFile() {
+    const parsed = JSON.parse(readFileSync(NETWORKS_FILE, "utf8"));
+    const settings = (name) => {
+        const entry = parsed[name];
+        if (!entry?.demoPayeeUrl) {
+            throw new Error(`networks file ${NETWORKS_FILE.pathname} has no complete "${name}" entry`);
+        }
+        return {
+            demoPayeeUrl: entry.demoPayeeUrl,
+            ...(entry.faucetUrl !== undefined && { faucetUrl: entry.faucetUrl }),
+            ...(entry.explorerUrl !== undefined && { explorerUrl: entry.explorerUrl }),
+        };
+    };
+    return { devnet: settings("devnet"), testnet: settings("testnet") };
+}
+export function resolveSettings(network, file, flags, env) {
+    const rpcUrl = flags.rpcUrl ?? env["METAL_RPC_URL"];
+    const faucetUrl = flags.faucetUrl ?? env["METAL_FAUCET_URL"] ?? file.faucetUrl;
+    return {
+        ...(rpcUrl !== undefined && { rpcUrl }),
+        facilitatorUrl: env["METAL_FACILITATOR_URL"] ?? network.facilitatorUrl,
+        demoPayeeUrl: env["METAL_DEMO_PAYEE_URL"] ?? file.demoPayeeUrl,
+        ...(faucetUrl !== undefined && { faucetUrl }),
+        ...(file.explorerUrl !== undefined && { explorerUrl: file.explorerUrl }),
+        nusd: USDZ.address,
+    };
+}
+export function target(networkFlag, flags = {}, env = process.env) {
+    if (!networkFlag)
+        throw new Error("--network devnet|testnet is required; there is no default network");
+    const network = metalNetwork(networkFlag);
+    if (!network || network.name !== networkFlag) {
+        throw new Error(`unknown network "${networkFlag}"; use devnet or testnet`);
+    }
+    return { ...resolveSettings(network, readNetworksFile()[network.name], flags, env), network };
+}
+/**
+ * A client for the target's JSON-RPC endpoint: --rpc-url, then METAL_RPC_URL,
+ * then the network default. On a network without a default it throws, saying
+ * how to get an endpoint and, using `how`, how to pass it.
+ */
+export function rpcClient({ network, rpcUrl }, how = "pass --rpc-url or set METAL_RPC_URL") {
+    const url = rpcUrlFor(network, rpcUrl, how);
+    const chain = defineChain({
+        id: network.chainId,
+        name: `Metal ${network.name}`,
+        nativeCurrency: { name: "Gas", symbol: "GAS", decimals: 18 },
+        rpcUrls: { default: { http: [url] } },
+    });
+    return createPublicClient({ chain, transport: http(url) });
+}

package/dist/commands/fund.js

@@ -0,0 +1,128 @@
+import { createWalletClient, custom, erc20Abi, getAddress, isAddress } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { USDZ, formatUsdz, usdzBaseUnits } from "@metalntwx/metal-pay";
+import { rpcClient } from "../chain.js";
+// Foundry test account #0, funded at genesis by `just devnet`. The key is
+// public, so it only ever signs on devnet.
+const DEVNET_PRINCIPAL_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
+// Gas and the 1-per-gas fee are explicit for the reason
+// `buildSubmitAuthorizationTx` gives.
+const FUND_GAS_LIMIT = 200000n;
+export async function fund(target, addressArg, amountArg, print, fetchImpl = fetch) {
+    if (!addressArg || !isAddress(addressArg))
+        throw new Error("fund needs the agent's address");
+    const to = getAddress(addressArg);
+    if (target.network.name === "testnet") {
+        if (amountArg !== undefined) {
+            throw new Error("on testnet the faucet sets the amount; run fund without --amount");
+        }
+        await fundFromFaucet(target, to, print, fetchImpl);
+        return;
+    }
+    const publicClient = rpcClient(target);
+    await fundFromDevnetPrincipal(target, publicClient, to, BigInt(usdzBaseUnits(amountArg ?? "10")), print);
+    const balance = await publicClient.readContract({
+        address: target.nusd,
+        abi: erc20Abi,
+        functionName: "balanceOf",
+        args: [to],
+    });
+    print(`balance ${formatUsdz(balance)} ${USDZ.symbol}`);
+}
+async function fundFromFaucet(target, to, print, fetchImpl) {
+    if (!target.faucetUrl)
+        throw new Error(`no faucet is configured for ${target.network.name}`);
+    const url = new URL("/api/fund", target.faucetUrl);
+    const response = await fetchImpl(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ address: to, symbol: "USDZ" }),
+    });
+    const text = await response.text();
+    if (response.ok) {
+        const grant = safeJson(text);
+        if (!grant?.txHash || !grant.amount)
+            throw new Error(unexpectedAnswer(url, response, "a transaction"));
+        // The faucet answers 200 only once the grant's receipt shows success.
+        print(`funded ${to} with ${formatUsdz(grant.amount)} ${USDZ.symbol} from the testnet faucet`);
+        print(`transaction ${grant.txHash}`);
+        if (target.explorerUrl)
+            print(`explorer ${target.explorerUrl}/tx/${grant.txHash}`);
+        return;
+    }
+    const error = faucetError(text);
+    if (error?.code === "already_funded") {
+        print(`${to} already holds a full ${USDZ.symbol} grant from the testnet faucet`);
+        return;
+    }
+    if (!error && response.status === 429) {
+        throw new Error("faucet answered 429: the faucet's edge rate limit refused this client; retry shortly");
+    }
+    if (!error)
+        throw new Error(unexpectedAnswer(url, response, "an error code"));
+    throw new Error(`faucet answered ${response.status} ${error.code}: ${faucetRefusal(error)}`);
+}
+// Describes the response instead of quoting it, because a proxy in front of
+// the faucet answers with a full HTML document.
+function unexpectedAnswer(url, response, missing) {
+    const mediaType = response.headers.get("content-type")?.split(";")[0]?.trim() || "no content type";
+    return `faucet answered ${response.status} ${mediaType} from ${url} without ${missing}`;
+}
+function faucetRefusal(error) {
+    const keyImport = "or load a funded key with `metal-agent key import`";
+    switch (error.code) {
+        case "client_rate_limited":
+            return `this client asked the faucet too recently; ${error.retryAfter === undefined ? "retry shortly" : `retry in ${error.retryAfter} s`}`;
+        case "client_daily_limit_reached":
+            return `this client reached its daily faucet limit; try tomorrow, ${keyImport}`;
+        case "daily_limit_reached":
+            return `the faucet reached its daily grant limit for every client; try tomorrow, ${keyImport}`;
+        default:
+            return error.message;
+    }
+}
+function faucetError(text) {
+    const body = safeJson(text);
+    if (typeof body !== "object" || body === null)
+        return undefined;
+    const { code, message, retryAfter } = body;
+    if (typeof code !== "string" || typeof message !== "string")
+        return undefined;
+    return { code, message, ...(typeof retryAfter === "number" && { retryAfter }) };
+}
+async function fundFromDevnetPrincipal(target, publicClient, to, amount, print) {
+    const principal = privateKeyToAccount(DEVNET_PRINCIPAL_KEY);
+    const walletClient = createWalletClient({
+        account: principal,
+        chain: publicClient.chain,
+        transport: custom(publicClient),
+    });
+    // The SDK root loads its wasm codec, a build output only devnet funding
+    // needs; importing it here keeps every other command working without it.
+    const { writeMip20Contract } = await import("@metalntwx/metal-ts");
+    const hash = await writeMip20Contract({
+        walletClient,
+        publicClient,
+        abi: erc20Abi,
+        address: target.nusd,
+        functionName: "transfer",
+        args: [to, amount],
+        gasToken: target.nusd,
+        gasFallback: FUND_GAS_LIMIT,
+        gasLimit: FUND_GAS_LIMIT,
+        maxFeePerGas: 1n,
+    });
+    const receipt = await publicClient.waitForTransactionReceipt({ hash });
+    if (receipt.status !== "success")
+        throw new Error(`funding transaction ${hash} reverted`);
+    print(`funded ${to} with ${formatUsdz(amount)} ${USDZ.symbol} from ${principal.address}`);
+    print(`transaction ${hash}`);
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/commands/key.js

@@ -0,0 +1,38 @@
+import { readFile } from "node:fs/promises";
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+import { DEFAULT_KEY_PATH, isPrivateKey, writeKey } from "../keystore.js";
+export async function keyCreate(out, print) {
+    await store(generatePrivateKey(), out, print);
+}
+export async function keyImport(source, out, print) {
+    if (!source)
+        throw new Error("key import needs a hex private key or a file holding one");
+    const privateKey = asPrivateKey(source) ?? asPrivateKey(await readKeySource(source));
+    if (!privateKey)
+        throw new Error("key import found no 32-byte hex private key in the source");
+    await store(privateKey, out, print);
+}
+async function store(privateKey, out, print) {
+    const path = out ?? DEFAULT_KEY_PATH;
+    const { address } = privateKeyToAccount(privateKey);
+    await writeKey(path, { address, privateKey });
+    print(`address ${address}`);
+    print(`keyfile ${path}`);
+}
+async function readKeySource(path) {
+    const text = (await readFile(path, "utf8").catch(() => {
+        throw new Error("key import: the argument is neither a 32-byte hex private key nor a readable file");
+    })).trim();
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed.privateKey === "string" ? parsed.privateKey : "";
+    }
+    catch {
+        return text;
+    }
+}
+function asPrivateKey(value) {
+    const trimmed = value.trim();
+    const hex = trimmed.startsWith("0x") ? trimmed : `0x${trimmed}`;
+    return isPrivateKey(hex) ? hex : undefined;
+}