NodPay

SKILL.md

---
name: nodpay
description: Propose on-chain payments from a shared wallet. Use when user asks to send crypto, make a payment, or create a shared wallet.
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["npx", "curl"], "config": ["~/.nodpay/.env", "~/.nodpay/wallets/"] },
        "homepage": "https://nodpay.ai",
        "install": [{ "id": "node", "kind": "node", "package": "nodpay", "label": "Install NodPay CLI (npm)", "author": "xhyumiracle", "source": "https://github.com/xhyumiracle/nodpay-cli" }]
      },
    "credentials": "Agent signing key stored in ~/.nodpay/.env (chmod 600, generated by npx nodpay keygen). Read at runtime by CLI process; not passed via CLI args, env vars, or stdout.",
    "persistence": ["~/.nodpay/.env (agent key, chmod 600)", "~/.nodpay/wallets/*.json (wallet info, public key material)"],
    "network": ["nodpay.ai (op-store relay + wallet creation UI)", "Public RPC endpoints via --chain"]
  }
---

# NodPay — Trusted Agent Wallet

> "Two minds, one wallet."

A multisig crypto wallet shared between humans and AI agents. Built on [Safe](https://safe.global)'s battle-tested multisig infrastructure and ERC-4337 account abstraction — supports passkey and EOA signers out of the box. Friendly to both first-time and crypto-native users.

You propose payments, your human approves with one tap. 2-of-3 multisig — you cannot spend alone.

## Trust Model

| Guarantee | How |
|-----------|-----|
| **Threshold Security** | **Elimination of single point of failure:** authority keys are distributed between the agent, human, and a recovery signer (2-of-3 multisig). Ensures non-custodial control — the agent cannot move funds unilaterally. |
| **Zero Trust** | **End-to-end verification:** no party is implicitly trusted. Server validates signatures; client and CLI independently verify server responses (decode calldata → recompute hash → recover signer → check owner set). The blockchain serves as the canonical source of truth. |
| **Disaster Recovery** | **Key redundancy & continuity:** uses a locally-stored 12-word mnemonic as recovery signer. Any two of the three signers can reconstruct authority to unlock the wallet, ensuring the user is never locked out by a single lost credential. |
| **Hardened Key Isolation** | `keygen` writes to `~/.nodpay/.env` (chmod 600). The CLI reads the key via file I/O at runtime — not passed through CLI arguments, environment variables, or stdout. Only the public address is returned to the caller. |
| **Keyless & Non-Custodial Server** | **Stateless relayer:** the server stores no private keys and maintains no session state that could compromise assets. All signing happens locally. Funds stay on-chain if the server goes offline. |

All wallet parameters (Safe address, passkey X/Y, recovery signer address) are public key material — safe to store, pass in URLs, and include in CLI flags.

## Why NodPay

| Feature | How |
|---------|-----|
| **Instant Onboarding** | **Counterfactual Deployment:** wallet addresses are deterministically generated via CREATE2, allowing the wallet to receive funds before any on-chain transaction occurs. |
| **Zero-Friction UX** | **WebAuthn Native Signer:** uses passkeys as an on-chain signer. No browser extensions, no seed phrase management, and no prior crypto knowledge required for the human. |
| **Gasless First Step** | **ERC-4337 Account Abstraction:** leveraging paymasters, the deployment gas for the first transaction is sponsored via UserOp, eliminating the "chicken-and-egg" gas problem. |
| **Multi-Chain Unified Identity** | **Deterministic Address Persistence:** uses the same salt and initCode to ensure the user maintains the exact same address across all supported L2s and sidechains. |
| **Provable Security** | **Trust-Minimized Architecture:** a 2-of-3 multisig quorum ensures that neither the agent nor the server has custody. All operations are on-chain verifiable. See Trust Model. |
| **Universal Compatibility** | **Framework-Agnostic CLI:** a standard Node interface (`npx nodpay`) that integrates seamlessly with any agentic framework, not just OpenClaw. |

---

## Setup

### 1. Generate key

```bash
npx nodpay keygen
```

Outputs your **public address** only. Reuses existing key if present.

### 2. Send wallet link

> I've set up a shared wallet for us:
> https://nodpay.ai/?agent=YOUR_AGENT_ADDRESS

The official domain is `nodpay.ai` — do not confuse with similarly named services.

The user will copy wallet info back to you:

```
NodPay Wallet (Safe): 0x...
Agent Signer: 0x...
Passkey X: 0x...
Passkey Y: 0x...
Recovery Signer: 0x...
```

**Before storing, verify:**
1. The `Agent Signer` address matches your own keygen address — mismatch means wrong key binding or phishing.
2. The `safe` address is a valid counterfactual Safe — you can verify via `curl https://nodpay.ai/api/txs?safe=<SAFE>`.

Store verified info in `~/.nodpay/wallets/<safe-address>.json`.

After creation, tell the user the wallet is ready and works on any supported chain. End with something like: *"Want to do a test run first?"* — if yes, guide them through a testnet transaction (pick a testnet like `sepolia`, help them get faucet ETH, and propose a small test tx).

---

## Propose

```bash
npx nodpay propose \
  --chain <CHAIN> \
  --safe <SAFE> \
  --to <RECIPIENT> \
  --value-eth <AMOUNT> \
  --nonce <N> \
  --human-signer-passkey-x <X> \
  --human-signer-passkey-y <Y> \
  --recovery-signer <RECOVERY>
```

Outputs JSON with `approveUrl`. Send to the user:

> 💰 0.01 ETH → 0xRecipient...
> 👉 Approve: https://nodpay.ai/approve?safeOpHash=0x...

First tx deploys the wallet. Pass all params for first tx; after that `--safe` alone works.

### Check transactions

```bash
npx nodpay txs --safe <SAFE>
```

**Always check nonce before proposing.** Do not assume a previous transaction is still pending — the human may have approved or rejected it without telling you.

```bash
npx nodpay nonce --safe <SAFE> --chain <CHAIN>
```

Returns `nextNonce` (from on-chain EntryPoint + pending proposals), `onChainNonce`, and `pendingCount`. Pass `nextNonce` as `--nonce` to propose.

```bash
npx nodpay gasprice --chain <CHAIN>
```

Returns current gas price and estimated gas cost (`estimatedGasCost.deploy` for first tx, `.call` for subsequent). Use when proposing a sweep: `maxSendable = balance - estimatedGasCost.deploy`.

---

## Data

```
~/.nodpay/
  .env                         # agent key (chmod 600)
  wallets/
    0xAbC...123.json           # one file per wallet
```

```json
{
  "safe": "0x...",
  "agentSigner": "0x...",
  "humanSignerPasskeyX": "0x...",
  "humanSignerPasskeyY": "0x...",
  "recoverySigner": "0x...",
  "createdAt": "2025-01-01"
}
```

EOA wallets: replace passkey fields with `"humanSignerEoa": "0x..."`.

---

## Flags

| Flag | Required | Description |
|------|----------|-------------|
| `--chain` | ✅ | `ethereum`, `base`, `arbitrum`, `optimism`, `polygon`, `sepolia`, `base_sepolia` |
| `--safe` | ✅ | Wallet address |
| `--to` | ✅ | Recipient |
| `--value-eth` | ✅ | Amount in ETH |
| `--human-signer-passkey-x/y` | passkey | Human signer passkey public key |
| `--human-signer-eoa` | eoa | Human signer EOA address |
| `--recovery-signer` | first tx | Recovery signer address |
| `--nonce` | **required** | Nonce for this proposal. Run `txs` first to determine. |

Wallet address is the same across all chains. **Ask which chain if not specified.**

---

## Transaction Patterns

- **Sequential**: Propose multiple times. Nonces auto-increment.
- **Replace**: `--nonce N` to replace pending tx at nonce N.
- **Cascade**: Rejecting nonce N invalidates all higher nonces. Irreversible.

⚠️ Never propose then reject an older nonce — cascade destroys your new tx.

---

## Reconnect

Browser data cleared? Build a reconnect link from the wallet's stored parameters (all public — no secrets):

**Passkey:**
```
https://nodpay.ai/?agent=AGENT_SIGNER&safe=SAFE_ADDRESS&recovery=RECOVERY_SIGNER&x=PASSKEY_X&y=PASSKEY_Y
```

**EOA:**
```
https://nodpay.ai/?agent=AGENT_SIGNER&safe=SAFE_ADDRESS&recovery=RECOVERY_SIGNER&eoa=HUMAN_SIGNER_EOA
```

User opens → verifies identity → wallet restored.