aeron-wallet 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aeron
+
+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

@@ -0,0 +1,93 @@
+# aeron-wallet
+
+A non-custodial wallet for agents. It holds USDG on Robinhood Chain and pays
+`402 Payment Required` responses on its own, so an agent can call a metered API
+without a card, an account, or a human in the loop.
+
+Ships two ways: a CLI, and an MCP server for Claude and other MCP clients.
+
+## Quickstart
+
+```bash
+npx -y aeron-wallet address
+```
+
+That prints your wallet address and creates a key on first run. Send USDG to
+that address, then pay for a call:
+
+```bash
+npx -y aeron-wallet pay https://inference.aeron.sh/v1/chat/completions \
+  '{"model":"deepseek/deepseek-chat","messages":[{"role":"user","content":"hi"}]}'
+```
+
+The wallet reads the 402 challenge, checks it against your budget caps, signs an
+EIP-3009 transfer, and retries the request with the payment attached. You do not
+need ETH: the facilitator relays the transaction and pays gas.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `address` | Print the wallet address. Creates the key if none exists. |
+| `balance` | ETH and USDG balances, read from chain. |
+| `pay <url> [json]` | Call an x402 endpoint, paying if it answers 402. |
+| `history` | The last 10 payments, from the local log. |
+| `mcp` | Run as an MCP server over stdio. The default with no arguments. |
+
+## MCP
+
+```json
+{
+  "mcpServers": {
+    "aeron-wallet": {
+      "command": "npx",
+      "args": ["-y", "aeron-wallet", "mcp"]
+    }
+  }
+}
+```
+
+Four tools: `get_address`, `get_balance`, `pay`, `history`.
+
+## Your key
+
+The key is generated on your machine on first run and written to
+`~/.aeron/wallet/key` with `0600` permissions. It never leaves the machine and
+nobody else can derive your address. Every install creates a different wallet.
+
+Two consequences worth planning for:
+
+- **Ephemeral containers.** If `$HOME` is wiped between runs, the wallet
+  regenerates and any USDG left on the old address is stranded. Mount a volume
+  for `~/.aeron`, set `AERON_WALLET_DIR` to a path that persists, or supply the
+  key yourself with `AERON_WALLET_KEY`.
+- **Hot wallet.** The key sits unencrypted on disk so an agent can sign without
+  a prompt. Keep the balance small. Fund it the way you would top up a prepaid
+  card, not the way you would fund savings.
+
+## Budget caps
+
+The wallet refuses to sign above either cap, so a loop cannot drain it.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `MAX_PER_CALL_USD` | `0.05` | Largest single payment. |
+| `DAILY_CAP_USD` | `1` | Total for the current UTC day. |
+
+## Configuration
+
+| Variable | Default |
+|---|---|
+| `RPC_URL` | `https://rpc.mainnet.chain.robinhood.com` |
+| `CHAIN_ID` | `4663` |
+| `USDG_ADDRESS` | `0x5fc5360d0400a0fd4f2af552add042d716f1d168` |
+| `AERON_WALLET_DIR` | `~/.aeron/wallet` |
+| `AERON_WALLET_KEY` | unset. Overrides the stored key. |
+
+## Where payments go
+
+Payments settle on Robinhood Chain mainnet in USDG through the Aeron
+facilitator at `x402.aeron.sh`. The wallet works with any x402 endpoint on the
+same network, not only Aeron's.
+
+More at [aeron.sh/wallet](https://aeron.sh/wallet/).

package/dist/balances.js

@@ -0,0 +1,29 @@
+import { createPublicClient, defineChain, http, formatEther } from 'viem';
+const ERC20_ABI = [
+    {
+        type: 'function', name: 'balanceOf', stateMutability: 'view',
+        inputs: [{ name: 'account', type: 'address' }],
+        outputs: [{ type: 'uint256' }],
+    },
+];
+export function createChainClient(cfg) {
+    const chain = defineChain({
+        id: cfg.CHAIN_ID,
+        name: 'Robinhood Chain',
+        nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+        rpcUrls: { default: { http: [cfg.RPC_URL] } },
+    });
+    return createPublicClient({ chain, transport: http(cfg.RPC_URL) });
+}
+export async function readBalances(publicClient, cfg, address) {
+    const [wei, usdgRaw] = await Promise.all([
+        publicClient.getBalance({ address }),
+        publicClient.readContract({
+            address: cfg.USDG_ADDRESS,
+            abi: ERC20_ABI,
+            functionName: 'balanceOf',
+            args: [address],
+        }),
+    ]);
+    return { eth: formatEther(wei), usdg: (Number(usdgRaw) / 1e6).toFixed(6) };
+}

package/dist/cli.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { loadConfig } from './config.js';
+import { loadOrCreateAccount } from './keystore.js';
+import { createHistory } from './history.js';
+import { createChainClient, readBalances } from './balances.js';
+import { payX402, resolveDomain } from './payer.js';
+import { startMcpServer } from './mcp.js';
+const out = (line) => process.stdout.write(`${line}\n`);
+async function main() {
+    const cfg = loadConfig();
+    const { account, created } = loadOrCreateAccount(cfg);
+    const history = createHistory(cfg);
+    const publicClient = createChainClient(cfg);
+    let cachedDomain = null;
+    const domain = async () => {
+        if (!cachedDomain)
+            cachedDomain = await resolveDomain(publicClient, cfg);
+        return cachedDomain;
+    };
+    const [command = 'mcp', ...rest] = process.argv.slice(2);
+    if (created && command !== 'mcp') {
+        out(`new wallet created at ${cfg.AERON_WALLET_DIR} (hot wallet; keep balances small)`);
+    }
+    switch (command) {
+        case 'address': {
+            out(account.address);
+            return;
+        }
+        case 'balance': {
+            const balances = await readBalances(publicClient, cfg, account.address);
+            out(`address ${account.address}`);
+            out(`eth    ${balances.eth}`);
+            out(`usdg   ${balances.usdg}`);
+            return;
+        }
+        case 'pay': {
+            const url = rest[0];
+            if (!url)
+                throw new Error('usage: pay <url> [json-body]');
+            const body = rest[1];
+            const result = await payX402(url, { method: 'POST', headers: { 'content-type': 'application/json' }, ...(body ? { body } : {}) }, { cfg, account, history, domain: await domain() });
+            out(JSON.stringify(result, null, 2));
+            if (!result.paid && result.reason)
+                process.exitCode = 1;
+            return;
+        }
+        case 'history': {
+            for (const r of history.recent(10)) {
+                out(`${r.ts} $${r.amountUsd} ${r.status} ${r.transaction ?? ''} ${r.url}`);
+            }
+            return;
+        }
+        case 'mcp': {
+            await startMcpServer({ cfg, account, history, publicClient, domain });
+            return;
+        }
+        default:
+            throw new Error(`unknown command: ${command} (use address|balance|pay|history|mcp)`);
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/config.js

@@ -0,0 +1,29 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
+const envSchema = z.object({
+    RPC_URL: z.string().url().default('https://rpc.mainnet.chain.robinhood.com'),
+    CHAIN_ID: z.coerce.number().int().positive().default(4663),
+    USDG_ADDRESS: z
+        .string()
+        .regex(/^0x[0-9a-fA-F]{40}$/)
+        .default('0x5fc5360d0400a0fd4f2af552add042d716f1d168'),
+    /** Override the stored key (hot wallets only; small balances). */
+    AERON_WALLET_KEY: z
+        .string()
+        .regex(/^0x[0-9a-fA-F]{64}$/)
+        .optional()
+        .or(z.literal('').transform(() => undefined)),
+    AERON_WALLET_DIR: z.string().default(join(homedir(), '.aeron', 'wallet')),
+    /** Budget caps, USD. The wallet refuses to sign above these. */
+    MAX_PER_CALL_USD: z.coerce.number().positive().default(0.05),
+    DAILY_CAP_USD: z.coerce.number().positive().default(1),
+});
+export function loadConfig(env = process.env) {
+    const parsed = envSchema.safeParse(env);
+    if (!parsed.success) {
+        const detail = parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
+        throw new Error(`Invalid configuration: ${detail}`);
+    }
+    return { ...parsed.data, network: `eip155:${parsed.data.CHAIN_ID}` };
+}

package/dist/history.js

@@ -0,0 +1,37 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export function createHistory(cfg) {
+    const filePath = join(cfg.AERON_WALLET_DIR, 'history.jsonl');
+    function readAll() {
+        if (!existsSync(filePath))
+            return [];
+        return readFileSync(filePath, 'utf8')
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((r) => r !== null);
+    }
+    return {
+        append(record) {
+            mkdirSync(cfg.AERON_WALLET_DIR, { recursive: true, mode: 0o700 });
+            appendFileSync(filePath, `${JSON.stringify(record)}\n`);
+        },
+        recent(limit) {
+            return readAll().slice(-limit).reverse();
+        },
+        spentTodayUsd(now = new Date()) {
+            const midnight = new Date(now);
+            midnight.setHours(0, 0, 0, 0);
+            return readAll()
+                .filter((r) => r.status === 'settled' && new Date(r.ts) >= midnight)
+                .reduce((sum, r) => sum + r.amountUsd, 0);
+        },
+    };
+}

package/dist/keystore.js

@@ -0,0 +1,24 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
+/**
+ * Load or create the wallet key. Stored at <dir>/key with 0600 perms.
+ * This is a hot wallet for small, metered spending; not for savings.
+ */
+export function loadOrCreateAccount(cfg) {
+    if (cfg.AERON_WALLET_KEY) {
+        return { account: privateKeyToAccount(cfg.AERON_WALLET_KEY), created: false };
+    }
+    const keyPath = join(cfg.AERON_WALLET_DIR, 'key');
+    if (existsSync(keyPath)) {
+        const key = readFileSync(keyPath, 'utf8').trim();
+        if (!/^0x[0-9a-fA-F]{64}$/.test(key))
+            throw new Error(`corrupt key file at ${keyPath}`);
+        return { account: privateKeyToAccount(key), created: false };
+    }
+    mkdirSync(cfg.AERON_WALLET_DIR, { recursive: true, mode: 0o700 });
+    const key = generatePrivateKey();
+    writeFileSync(keyPath, `${key}\n`, { mode: 0o600 });
+    chmodSync(keyPath, 0o600);
+    return { account: privateKeyToAccount(key), created: true };
+}

package/dist/mcp.js

@@ -0,0 +1,33 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { readBalances } from './balances.js';
+import { payX402 } from './payer.js';
+export async function startMcpServer(deps) {
+    const { cfg, account, history, publicClient } = deps;
+    const server = new McpServer({ name: 'aeron-wallet', version: '0.1.0' });
+    server.tool('get_address', 'The wallet address on Robinhood Chain. Fund it with USDG to pay for services.', {}, async () => ({
+        content: [{ type: 'text', text: JSON.stringify({ address: account.address, network: cfg.network }) }],
+    }));
+    server.tool('get_balance', 'ETH and USDG balances of this wallet.', {}, async () => {
+        const balances = await readBalances(publicClient, cfg, account.address);
+        return { content: [{ type: 'text', text: JSON.stringify({ address: account.address, ...balances }) }] };
+    });
+    server.tool('pay', 'Call a machine-payable (x402) endpoint and pay in USDG if it answers 402. Budget caps apply.', {
+        url: z.string().url(),
+        method: z.enum(['GET', 'POST']).default('POST'),
+        body: z.string().optional().describe('JSON body to send'),
+    }, async ({ url, method, body }) => {
+        const domain = await deps.domain();
+        const result = await payX402(url, {
+            method,
+            headers: { 'content-type': 'application/json' },
+            ...(body ? { body } : {}),
+        }, { cfg, account, history, domain });
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+    server.tool('history', 'Recent payments made by this wallet.', { limit: z.number().int().min(1).max(50).default(10) }, async ({ limit }) => ({
+        content: [{ type: 'text', text: JSON.stringify(history.recent(limit)) }],
+    }));
+    await server.connect(new StdioServerTransport());
+}

package/dist/payer.js

@@ -0,0 +1,157 @@
+import { randomBytes } from 'node:crypto';
+import { z } from 'zod';
+import { hashDomain } from 'viem';
+/** EIP-3009 typed data, mirrored from the facilitator side. */
+const TRANSFER_WITH_AUTHORIZATION_TYPES = {
+    TransferWithAuthorization: [
+        { name: 'from', type: 'address' },
+        { name: 'to', type: 'address' },
+        { name: 'value', type: 'uint256' },
+        { name: 'validAfter', type: 'uint256' },
+        { name: 'validBefore', type: 'uint256' },
+        { name: 'nonce', type: 'bytes32' },
+    ],
+};
+const DOMAIN_ABI = [
+    { type: 'function', name: 'name', stateMutability: 'view', inputs: [], outputs: [{ type: 'string' }] },
+    { type: 'function', name: 'DOMAIN_SEPARATOR', stateMutability: 'view', inputs: [], outputs: [{ type: 'bytes32' }] },
+];
+export function computeDomainSeparator(domain) {
+    return hashDomain({
+        domain: { ...domain, chainId: BigInt(domain.chainId) },
+        types: {
+            EIP712Domain: [
+                { name: 'name', type: 'string' },
+                { name: 'version', type: 'string' },
+                { name: 'chainId', type: 'uint256' },
+                { name: 'verifyingContract', type: 'address' },
+            ],
+        },
+    });
+}
+export async function resolveDomain(publicClient, cfg) {
+    const address = cfg.USDG_ADDRESS;
+    const [name, onchain] = await Promise.all([
+        publicClient.readContract({ address, abi: DOMAIN_ABI, functionName: 'name' }),
+        publicClient.readContract({ address, abi: DOMAIN_ABI, functionName: 'DOMAIN_SEPARATOR' }),
+    ]);
+    for (const version of ['1', '2', '3']) {
+        const domain = { name, version, chainId: cfg.CHAIN_ID, verifyingContract: address };
+        if (computeDomainSeparator(domain).toLowerCase() === onchain.toLowerCase())
+            return domain;
+    }
+    throw new Error('could not match the token EIP-712 domain version');
+}
+const requirementsSchema = z.looseObject({
+    scheme: z.literal('exact'),
+    network: z.string(),
+    maxAmountRequired: z.string().regex(/^\d+$/),
+    payTo: z.string().regex(/^0x[0-9a-fA-F]{40}$/),
+    asset: z.string().regex(/^0x[0-9a-fA-F]{40}$/),
+    maxTimeoutSeconds: z.number().optional(),
+});
+const body402Schema = z.looseObject({
+    x402Version: z.number(),
+    accepts: z.array(requirementsSchema).min(1),
+});
+/**
+ * The x402 client flow: call, read the 402 offer, enforce budget caps, sign
+ * an exact-amount EIP-3009 authorization, retry with X-PAYMENT.
+ */
+export async function payX402(url, init, deps) {
+    const { cfg, account, history, domain } = deps;
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const now = deps.now ?? (() => Math.floor(Date.now() / 1000));
+    const first = await fetchImpl(url, init);
+    const firstBody = await first.text();
+    if (first.status !== 402) {
+        return { paid: false, status: first.status, amountUsd: 0, transaction: null, body: firstBody };
+    }
+    const parsed = body402Schema.safeParse(JSON.parse(firstBody));
+    if (!parsed.success) {
+        return { paid: false, status: 402, amountUsd: 0, transaction: null, body: firstBody, reason: 'unrecognized 402 offer' };
+    }
+    const offer = parsed.data.accepts[0];
+    if (offer.network !== cfg.network) {
+        return { paid: false, status: 402, amountUsd: 0, transaction: null, body: firstBody, reason: `network mismatch: ${offer.network}` };
+    }
+    if (offer.asset.toLowerCase() !== cfg.USDG_ADDRESS.toLowerCase()) {
+        return { paid: false, status: 402, amountUsd: 0, transaction: null, body: firstBody, reason: 'offer asset is not USDG' };
+    }
+    const amountUsd = Number(offer.maxAmountRequired) / 1e6;
+    if (amountUsd > cfg.MAX_PER_CALL_USD) {
+        return {
+            paid: false, status: 402, amountUsd, transaction: null, body: firstBody,
+            reason: `amount $${amountUsd} exceeds per-call cap $${cfg.MAX_PER_CALL_USD}`,
+        };
+    }
+    const spent = history.spentTodayUsd();
+    if (spent + amountUsd > cfg.DAILY_CAP_USD) {
+        return {
+            paid: false, status: 402, amountUsd, transaction: null, body: firstBody,
+            reason: `daily cap reached ($${spent.toFixed(4)} of $${cfg.DAILY_CAP_USD})`,
+        };
+    }
+    const t = now();
+    const authorization = {
+        from: account.address,
+        to: offer.payTo,
+        value: BigInt(offer.maxAmountRequired),
+        validAfter: BigInt(t - 60),
+        validBefore: BigInt(t + (offer.maxTimeoutSeconds ?? 60) + 540),
+        nonce: `0x${randomBytes(32).toString('hex')}`,
+    };
+    const signature = await account.signTypedData({
+        domain,
+        types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+        primaryType: 'TransferWithAuthorization',
+        message: authorization,
+    });
+    const paymentHeader = Buffer.from(JSON.stringify({
+        x402Version: 1,
+        scheme: 'exact',
+        network: cfg.network,
+        payload: {
+            signature,
+            authorization: {
+                from: authorization.from,
+                to: authorization.to,
+                value: String(authorization.value),
+                validAfter: String(authorization.validAfter),
+                validBefore: String(authorization.validBefore),
+                nonce: authorization.nonce,
+            },
+        },
+    })).toString('base64');
+    const second = await fetchImpl(url, {
+        ...init,
+        headers: { ...init.headers, 'x-payment': paymentHeader },
+    });
+    const secondBody = await second.text();
+    let transaction = null;
+    const receiptHeader = second.headers.get('x-payment-response');
+    if (receiptHeader) {
+        try {
+            const receipt = JSON.parse(Buffer.from(receiptHeader, 'base64').toString('utf8'));
+            if (typeof receipt.transaction === 'string')
+                transaction = receipt.transaction;
+        }
+        catch {
+            /* receipt header is informational */
+        }
+    }
+    const settled = second.status < 400;
+    history.append({
+        ts: new Date().toISOString(),
+        url,
+        amountUsd,
+        payer: account.address,
+        transaction,
+        status: settled ? 'settled' : 'rejected',
+        reason: settled ? undefined : secondBody.slice(0, 200),
+    });
+    return {
+        paid: settled, status: second.status, amountUsd, transaction, body: secondBody,
+        reason: settled ? undefined : 'payment rejected by the service',
+    };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "aeron-wallet",
+  "version": "0.1.0",
+  "description": "Non-custodial agent wallet for Robinhood Chain. Pays x402 requests in USDG. Ships as a CLI and an MCP server.",
+  "license": "MIT",
+  "homepage": "https://aeron.sh/wallet/",
+  "type": "module",
+  "bin": {
+    "aeron-wallet": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "x402",
+    "mcp",
+    "agent",
+    "wallet",
+    "usdg",
+    "stablecoin",
+    "micropayments",
+    "robinhood-chain"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/cli.js",
+    "mcp": "tsx src/cli.ts mcp",
+    "cli": "tsx src/cli.ts",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.21.1",
+    "viem": "^2.44.3",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "^3.2.4",
+    "fastify": "^5.6.1",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}