@subly_fi/pay 0.6.0 → 0.6.2

package/LICENSE

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

@@ -6,7 +6,12 @@ deposited USDC, and the principal is never spent. Non-custodial: it signs
 locally with your own Solana key; Subly never holds it.
 
 Current payments target standard x402 sellers that offer a Solana USDC `exact`
-rail with facilitator `extra.feePayer` support.
+rail with facilitator `extra.feePayer` support (meaning the seller side
+sponsors the payment transaction's network fee — true of common facilitators
+such as PayAI and Coinbase CDP).
+
+> [!WARNING]
+> `@subly_fi/pay` is beta software and has not undergone an external security audit. It signs and submits transactions involving real Solana mainnet funds through a separate relayer and Kamino vault. The client package currently passes its production dependency audit, but this is not a guarantee of relayer, protocol, or vault safety. Use only amounts you can afford to lose and review the relayer operator and configuration before use.
 
 Ships one `pay` dispatcher bin with subcommands, all runnable with `npx` (no clone):
 
@@ -25,18 +30,42 @@ Ships one `pay` dispatcher bin with subcommands, all runnable with `npx` (no clo
 - `pay deposit <amountRawUsdc> [apr_...]` / `pay withdraw <amountRawUsdc>
   [apr_...]` — vault deposit / withdraw with the same owner-approval flow
 - `pay setup-link [--initial-deposit <raw>] [--approval-threshold <raw>] ...`
-  / `pay setup-status <sessionId>` — owner onboarding for CLI/skill harnesses
-  (same flow as the MCP setup tools)
+  / `pay setup-status <st_sessionId | setupUrl>` — owner onboarding for
+  CLI/skill harnesses (same flow as the MCP setup tools)
 
 ## Wallet
 
-Subly does not create wallets — bring your own Solana keypair:
+Subly does not create wallets — bring your own Solana keypair (`solana-keygen`
+ships with the [Solana CLI](https://docs.anza.xyz/cli/install)):
 
 ```bash
 solana-keygen new --no-bip39-passphrase -o ~/.subly/agent.json
 export SUBLY_DEMO_AGENT_KEYPAIR_PATH=~/.subly/agent.json
 ```
 
+Or bring a custody-held agent wallet — the key then never touches this
+machine; every signature is requested from the provider's API and verified
+locally before use:
+
+```bash
+# Circle developer-controlled wallet (a Solana wallet in your wallet set):
+export SUBLY_SIGNER_PROVIDER=circle
+export CIRCLE_API_KEY=... CIRCLE_ENTITY_SECRET=... CIRCLE_WALLET_ID=...
+
+# Privy server wallet (Solana), incl. agentic wallets owned by an
+# authorization key — pass that key so requests carry the required
+# privy-authorization-signature:
+export SUBLY_SIGNER_PROVIDER=privy
+export PRIVY_APP_ID=... PRIVY_APP_SECRET=... PRIVY_WALLET_ID=...
+export PRIVY_AUTHORIZATION_KEY=wallet-auth:...   # only for owner-key wallets
+```
+
+Each Circle/Privy credential var also accepts a `SUBLY_`-prefixed form (e.g.
+`SUBLY_CIRCLE_API_KEY`) that wins over the plain one, so Subly can use a
+different credential than other tooling on the same machine. Note the
+`circle` CLI "agent wallet" (email + OTP) is a different Circle product that
+exposes no signing API and cannot be used here.
+
 Send USDC (Solana mainnet) to the printed address — no SOL needed, fees are
 sponsored — then deposit (vault minimum is just over 1 USDC: share rounding
 refuses exactly 1.000000; deposit self-registers the wallet):
@@ -55,14 +84,80 @@ claude mcp add subly -- npx -y @subly_fi/pay mcp
 npx -y @subly_fi/pay fetch https://seller.example.com/api/premium
 ```
 
+### Claude Desktop
+
+Prerequisites: [Node.js](https://nodejs.org) 20+ installed, and an agent
+keypair (see [Wallet](#wallet) above).
+
+1. Open the config file (create it if it does not exist):
+   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+   Or in the app: **Settings → Developer → Edit Config**.
+
+2. Add the `subly` server. Claude Desktop is a GUI app and does **not**
+   inherit your shell environment (`.zshrc`, `.env` files), so every
+   variable must go in the `env` block:
+
+   ```json
+   {
+     "mcpServers": {
+       "subly": {
+         "command": "npx",
+         "args": ["-y", "@subly_fi/pay", "mcp"],
+         "env": {
+           "SUBLY_DEMO_AGENT_KEYPAIR_PATH": "/Users/you/.subly/agent.json"
+         }
+       }
+     }
+   }
+   ```
+
+   Use an absolute path for the keypair (`~` is not expanded). For a
+   custody wallet, replace the keypair var with the `circle` / `privy`
+   variables from [Environment](#environment). Optional vars
+   (`SUBLY_MCP_MAX_AMOUNT_RAW_USDC`, `SOLANA_RPC_URL`, …) go in the same
+   `env` block.
+
+3. Restart Claude Desktop (quit fully, then reopen). The tools icon under
+   the chat input should now list **subly-payments** with the tools above.
+
+   If the server fails to start, the usual cause is that Claude Desktop
+   cannot find `npx` (e.g. Node installed via nvm). Point `command` at the
+   absolute path instead — run `which npx` in a terminal and use that
+   value, e.g. `"command": "/opt/homebrew/bin/npx"`.
+
+4. Use it by chatting. First time: "set up Subly" walks you through the
+   owner setup link (spending mandate + first deposit). After that,
+   asking for anything behind an x402 paywall ("fetch
+   https://seller.example.com/api/premium") pays from vault yield
+   automatically and returns the response plus a payment receipt.
+   Payments above the owner's approval threshold return an `approveUrl` —
+   open it in a browser, approve, then tell Claude to retry.
+
+   Claude Desktop asks for permission on each first tool use. The permission
+   prompt is effectively your payment confirmation: "Allow always" on
+   `fetch_with_subly_payment` removes that human check and relies entirely on
+   the spending-mandate caps — keep per-use approval for payments, and reserve
+   "Allow always" for read-only tools like `get_subly_yield_budget`.
+
 ## Environment
 
 | Var | Required | Default |
 |---|---|---|
-| `SUBLY_DEMO_AGENT_KEYPAIR_PATH` | yes (or `SUBLY_DEMO_AGENT_KEYPAIR` base58) | — |
+| `SUBLY_SIGNER_PROVIDER` | no | `local` (`circle` / `privy` for custody wallets) |
+| `SUBLY_DEMO_AGENT_KEYPAIR_PATH` | with `local` (or `SUBLY_DEMO_AGENT_KEYPAIR` base58) | — |
+| `CIRCLE_API_KEY` / `CIRCLE_ENTITY_SECRET` / `CIRCLE_WALLET_ID` | with `circle` | — |
+| `PRIVY_APP_ID` / `PRIVY_APP_SECRET` / `PRIVY_WALLET_ID` | with `privy` | — |
+| `PRIVY_AUTHORIZATION_KEY` | only for owner-key (agentic) Privy wallets | — |
 | `SUBLY_RELAYER_URL` | no | `https://api.demo.sublyfi.com` |
 | `SOLANA_RPC_URL` | no | public mainnet RPC |
 | `SUBLY_MCP_MAX_AMOUNT_RAW_USDC` | no | `10000` (0.01 USDC) per-payment cap |
+| `SUBLY_MCP_STATE_PATH` | no | `~/.subly/standard-x402-pending.json` (pending-payment store, double-payment protection) |
+| `SUBLY_PAY_METHOD` / `SUBLY_PAY_BODY` | no (`pay fetch` only) | `GET` / — (JSON body for POST-body sellers) |
+| `SUBLY_PAY_FORCE_NEW_PAYMENT` | no (`pay fetch` only) | unset (`1` forces a fresh payment — may double-pay) |
+| `CIRCLE_BASE_URL` / `PRIVY_BASE_URL` | no | provider API defaults |
+| `SUBLY_VAULT_ADDRESS` / `SUBLY_VAULT_SHARE_MINT` / `SUBLY_VAULT_USDC_MINT` / `SUBLY_VAULT_FARM` | only with a custom-vault relayer | Subly's public vault and Farm. These are your signer's trust anchor (intents are validated against this local config, never the relayer's claims) — set them only to addresses you independently verified or control |
 
 Requests authenticate with a signature from your wallet key — there is no API
 token. `SUBLY_FACILITATOR_URL` is still accepted as a legacy fallback for

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Single dispatcher bin for @sublyfi/pay so `npx -y @sublyfi/pay <subcommand>`
+// Single dispatcher bin for @subly_fi/pay so `npx -y @subly_fi/pay <subcommand>`
 // resolves cleanly. Subcommands map to the bundled entry points; argv is
 // reshaped so each entry sees its own positional args at the usual index.
 import { dirname, join } from "node:path";
@@ -18,7 +18,7 @@ const [sub, ...rest] = process.argv.slice(2);
 const target = sub === undefined ? undefined : TARGETS[sub];
 if (target === undefined) {
   console.error(
-    "usage: subly <mcp|fetch <url>|deposit <amountRawUsdc>|withdraw <amountRawUsdc>|setup-link|setup-status <sessionId>>"
+    "usage: pay <mcp|fetch <url>|deposit <amountRawUsdc>|withdraw <amountRawUsdc>|setup-link|setup-status <sessionId|setupUrl>>"
   );
   process.exit(1);
 }