@vapi-network/mcp 0.1.1 → 0.2.0

package/README.md

@@ -1,188 +1,336 @@
-# Agent Cash (`@vapi-network/mcp`)
+# vAPI Network
 
-Agent Cash gives Claude, Cursor, and other MCP clients a small local wallet that
-can discover and pay x402 APIs directly.
+**One wallet, every x402 API.** vAPI Network is an open-source, non-custodial
+TypeScript toolkit for discovering and paying x402 services from a CLI, MCP
+client, or your own code. Call works today. Tasks and Compute are next.
 
-For the Call launch, this buyer-local client is the npm-distributed payment path
-for native and external Bazaar listings. The browser-wallet flow is also
-available where a provider permits a direct browser request. Legacy wrapped
-rows remain hidden and non-callable while the optional Wrap gateway is disabled.
-The hosted Go MCP remains free (`echo` and `search`).
+Your key stays encrypted on your machine. vAPI Network applies spend policy
+before signing, sends payment directly to the service, and writes receipts to a
+local append-only ledger. It does not hold funds, proxy payments, or send
+telemetry off the machine by default.
 
-The private key is generated locally and stored only in the Agent Cash home
-(default `~/.vapi/agent-cash`, overridden by `VAPI_AGENT_CASH_HOME`), encrypted
-with scrypt (`N=2^15`) and AES-256-GCM. Your MCP client signs each exact
-EIP-3009 payment locally. vAPI supplies public discovery metadata; it never
-receives the private key and cannot spend the wallet balance. Fund this like
-pocket money, not a treasury.
+## 60-second quickstart
 
-Direct x402 calls need no vAPI account or API key: the agent pays the selected
-API directly from the buyer-controlled wallet.
+Install once, then every command is `vapi …`:
 
-## Install and run
+```bash
+npm i -g vapi-network
+vapi init                      # encrypted wallet + config under ~/.vapi (or $VAPI_HOME), prints the address
+```
 
-Create the encrypted local wallet:
+Fund that address with `vapi fund` (card or Apple Pay via Coinbase Onramp) or by
+sending USDC on Base to it. Then:
 
-```sh
-npx -y @vapi-network/mcp init
+```bash
+vapi fund                      # hosted onramp link, or direct-transfer instructions
+vapi search "weather"          # every catalog, merged, with provenance
+vapi inspect <listing-ref>     # request contract and the live 402 quote, before paying
+vapi pay <listing-ref> --max 0.02
+vapi balance
+vapi accounts                   # balances plus network-specific deposit guidance
+vapi receipts                  # one line per paid call: quote, settlement, latency
 ```
 
-Running `npx -y @vapi-network/mcp` with no command starts the MCP stdio server.
+`vapi search` tags each listing with its group — `[vapi]`, `[added]`,
+`[partner]`, or `[external]` — and prints the network fee already inside the
+price: vAPI and added APIs carry a 5% network fee inside the quoted price, while
+partner and external listings carry none. `vapi inspect` and `--json` return the
+same `group` and `fee` fields.
+
+No install? Prefix any command with `npx vapi-network`, for example `npx vapi-network init`.
+(`npx vapi` cannot work: the bare `vapi` name on npm belongs to an unrelated package.)
 
-Fund the printed address with a small amount of canonical Base-mainnet USDC
-(`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`). Agent Cash does not need ETH to
-authorize ordinary x402 calls; send a little Base ETH only if you want it to
-sweep USDC back to another wallet later.
+### Use it from an agent (MCP)
 
-Configure an MCP client to launch the package through npm:
+Add this to Claude Desktop, Claude Code, or Cursor. The passphrase unlocks the local keystore; it never leaves the machine.
 
 ```json
 {
   "mcpServers": {
-    "agent-cash": {
+    "vapi": {
       "command": "npx",
-      "args": ["-y", "@vapi-network/mcp", "serve"],
-      "env": {
-        "VAPI_KEYSTORE_PASSWORD": "replace-with-your-keystore-passphrase"
-      }
+      "args": ["-y", "vapi-network", "mcp"],
+      "env": { "VAPI_KEYSTORE_PASSWORD": "your-passphrase" }
     }
   }
 }
 ```
 
-`VAPI_AGENT_CASH_HOME` optionally moves the wallet directory from
-`~/.vapi/agent-cash`. Desktop MCP hosts normally need
-`VAPI_KEYSTORE_PASSWORD` in the process environment because they cannot answer
-an interactive passphrase prompt. Protect that configuration with the same
-care as the pocket-money wallet.
+Tools: `call.search`, `call.inspect`, `call.pay`, `wallet.address`, `wallet.balance`,
+`wallet.accounts`, `wallet.fund`, `receipts.list`, `receipts.stats`, `support.report`. Spend caps
+default to $0.10 per call and $1.00 per day; the wallet checks both before it signs a payment.
 
-For a workspace-only development run, build from the repository root and keep
-the test wallet isolated under the gitignored `.context` directory:
+## Sign-in with X
 
-```sh
-pnpm --filter @vapi-network/mcp build
-VAPI_AGENT_CASH_HOME="$PWD/.context/agent-cash" \
-  pnpm --filter @vapi-network/mcp exec node dist/cli.js init
+x402 v2 services can require Sign-In-With-X (SIWX) before returning a price. When `call.pay` or
+`vapi pay` receives that challenge, vAPI checks that both the challenge domain and URI match the
+final resource origin, signs the canonical EIP-4361 message locally with EVM `personal_sign`, and
+retries once with `SIGN-IN-WITH-X`. The proof is never sent to a redirect or a different host.
+
+If the retry returns a normal 402 quote, the usual spend-policy and payment flow continues. If the
+resource is free after sign-in, the result has `outcome: "signed_in"` and the local receipt records
+`amountAtomic: "0"`.
+
+## Fund the wallet
+
+```bash
+vapi fund                 # ask the registry for a hosted onramp session
+vapi fund --amount 25     # prefill a US dollar amount
+vapi fund --json          # stable machine-readable shape
 ```
 
-For the first staging test, send a small amount of Base USDC to the printed
-address. Also send a little Base ETH only if you intend to test sweep-back.
+`vapi fund` POSTs `{ address, network: "base", asset: "USDC", fiatAmount }` to
+`<registry>/api/wallet/onramp-session` through the same guarded network client as
+every other command, prints the returned URL, and opens it in your default
+browser when you are on a terminal. The onramp is **Coinbase's**: Coinbase takes
+the card or Apple Pay payment and sends USDC straight to your local address.
+**vAPI never holds your funds**, never proxies the payment, and never sees your
+card details or your private key.
+
+When the registry replies `503 onramp_unavailable` — or cannot be reached at all
+— the command stays useful instead of failing: it prints your address and
 
-Then point the MCP client at the built CLI. Replace both absolute paths with
-this checkout's paths:
+```text
+Send USDC on Base (eip155:8453) to this address; add a little ETH for gas if you plan to sweep.
+```
+
+Either way it finishes by printing the current balance. MCP clients can use the
+`wallet.fund` tool, which returns the same `{ url }` or the same fallback text.
+
+## Accounts and deposits
+
+`vapi accounts` lists one deposit account for every configured network, including its CAIP-2 ID,
+network name, address, atomic and formatted USDC balance, gas-token balance, and deposit guidance.
+Use `--json` for the stable `{ "accounts": [...] }` shape. `vapi init` prints the same account list
+after creating the encrypted keystore and configuration. MCP clients can use `wallet.accounts`.
+
+Base uses the wallet's EVM address and tells you to send USDC on Base. For Arc testnet, add the
+faucet URL or instructions to that network's `config.json` entry:
 
 ```json
 {
-  "mcpServers": {
-    "agent-cash": {
-      "command": "node",
-      "args": ["/absolute/path/to/vapi-app/packages/vapi-mcp/dist/cli.js", "serve"],
-      "env": {
-        "VAPI_AGENT_CASH_HOME": "/absolute/path/to/vapi-app/.context/agent-cash",
-        "VAPI_KEYSTORE_PASSWORD": "replace-with-your-keystore-passphrase"
-      }
-    }
-  }
+  "depositUrl": "https://your-arc-faucet.example",
+  "depositInstructions": "Use the configured Arc testnet faucet, then send USDC to this address."
 }
 ```
 
-Base uses its public RPC by default. Leave `ARC_TESTNET_RPC_URL` unset for the
-Base-only staging slice.
+Account lookup dispatches by CAIP namespace: the EVM and Solana adapters use their corresponding
+local address and guarded RPC balance calls without coupling one wallet family to the other.
 
-Restart the MCP client. The agent can now:
+## Reporting a bug
 
-- `search {query?, kinds?, network?, limit?, cursor?}` across the public
-  marketplace. API results are callable; other results carry their canonical
-  vAPI web action.
-- `call {id|url, method?, body?, maxPriceUsd?, network?}` and pay an x402
-  `exact` challenge directly over HTTPS. An `id` must be an API ref returned by
-  `search` in the current Agent Cash process; an explicit published `url` may be
-  called directly. Set `network` to require a specific configured CAIP-2
-  network before Agent Cash signs.
-- `wallet {}` to inspect the address and USDC balance on each network.
+```bash
+vapi report "the provider returned 402 twice"
+vapi report "the provider returned 402 twice" --include-addresses
+vapi report "the provider returned 402 twice" --send
+```
 
-`tools/list` exposes exactly these three tools: `search`, `call`, and `wallet`.
+The command first writes `$VAPI_HOME/reports/<timestamp>.json`, then prints that path and a prefilled
+GitHub issue URL. Reports contain the message, client version, OS/Node information, and only the
+newest five receipt IDs. Wallet and payee addresses are included only with `--include-addresses`;
+amounts are never included. No report is uploaded unless `--send` is explicit. With `--send`, vAPI
+uses the guarded network client to POST the same JSON to the configured registry and prints the HTTP
+response code, including non-success responses such as 404. MCP clients can use `support.report`
+with the corresponding `includeAddresses` and `send` booleans.
 
-## Spend caps
+## Networks
 
-The Agent Cash home's `config.json` contains atomic-USDC caps (USDC has 6 decimals):
+| Network        | x402 identifier                                       | USDC                                           | Gas / RPC notes                                        |
+| -------------- | ----------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------ |
+| Base mainnet   | `eip155:8453`                                         | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`   | ETH; defaults to `https://mainnet.base.org`            |
+| Arc testnet    | `eip155:5042002`                                      | `0x3600000000000000000000000000000000000000`   | USDC is also the gas token; set `ARC_TESTNET_RPC_URL`  |
+| Solana mainnet | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d` | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | SOL; defaults to `https://api.mainnet-beta.solana.com` |
 
-```json
-{
-  "spendCaps": {
-    "perCallAtomic": "100000",
-    "perDayAtomic": "1000000"
-  }
-}
+The x402 reference packages shorten the Solana CAIP-2 reference to
+`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`; vAPI accepts that identifier as an
+alias while persisting the full genesis hash above. Arc mainnet is not enabled:
+**not yet — placeholder only.** Arc and the x402 packages do not publish a
+mainnet RPC plus canonical USDC, so the client deliberately carries only a
+non-routable code placeholder instead of guessing a production configuration.
+
+Create both local accounts during initialization:
+
+```bash
+vapi init --networks base,solana
 ```
 
-Those defaults are $0.10 per call and $1.00 per UTC day. Agent Cash checks both caps and reserves the quote in its atomic local daily ledger **before signing**. `maxPriceUsd` can set a still-lower ceiling for one tool call. The ledger is `spend-ledger.json` in the same Agent Cash home and rolls over when the UTC date changes.
+Or add an Ed25519 account to an existing encrypted keystore:
 
-The `call` tool requires HTTPS and blocks private, loopback, and link-local destinations by default. It validates every redirect before carrying a method or body forward. For local development only, setting `"allowPrivateNetwork": true` in `~/.vapi/agent-cash/config.json` permits an unpaid HTTP `localhost`, `*.localhost`, or loopback request; it does not permit HTTP calls to remote hosts, and Agent Cash still refuses to send a signed payment over HTTP.
+```bash
+vapi accounts --enable solana
+```
 
-`discoveryUrl` remains the Calls compatibility endpoint used to resolve a
-searched native vAPI ref into its payable endpoint. `marketplaceDiscoveryUrl`
-is the unified search route. Override them independently with
-`VAPI_DISCOVERY_URL` and `VAPI_MARKETPLACE_DISCOVERY_URL`. Agent Cash rejects an
-uncached or evicted `id` because its source and marketplace kind are no longer
-known; run `search` again or use the result's explicit published URL. It never
-attempts to call a service offer or open request; those actions continue in the
-web marketplace.
+Fund the printed Solana address with SPL USDC. Exact x402 payments use the
+facilitator advertised in the challenge as fee payer, so they do not consume the
+local SOL balance. `vapi sweep <solana-address> --network
+solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d` is a separate transaction
+and requires a small amount of SOL locally for fees and, when necessary,
+creation of the destination token account. The default public Solana RPC is
+rate-limited and has no availability guarantee; set `SOLANA_RPC_URL` to a
+trusted dedicated endpoint for regular use.
+
+## Discovery sources
+
+Discovery is a plugin interface. The client can merge listings from multiple
+sources, de-duplicate them by resource URL, and retain each listing's
+provenance:
+
+- **vAPI Registry** is enabled by the default distribution, using
+  `https://api.vapinetwork.ai/api/call/discovery` for discovery and
+  `https://api.vapinetwork.ai/api/call/services` for service details. If the
+  primary returns HTTP 404 or cannot be resolved, the client logs one notice
+  and tries the configured fallback at `https://console.vapinetwork.ai`, using
+  the same canonical paths. The registry's historical `/api/marketplace/discovery`
+  and `/api/network/services` paths still answer for one release and reply with
+  `Deprecation: true` plus a `Link` header naming the successor; a base URL
+  supplied on either of them is normalized to the canonical pair.
+- **Coinbase Bazaar** reads the public x402 v2
+  `/discovery/resources` catalog exposed by a facilitator.
+- **Local file** reads a JSON array of listings for private or development
+  catalogs.
+- **x402scan** is a deliberate stub for now. The source research documents its
+  discovery convention, but not a stable public read API that this client can
+  safely target.
+
+Use `@vapi-network/sources` to compose only the catalogs you trust. Network
+access is guarded against local and private destinations before a request is
+made.
+
+Set `VAPI_REGISTRY_URL` to replace the registry base; the client derives
+`/api/call/discovery` and `/api/call/services` beneath it. The existing
+`VAPI_MARKETPLACE_DISCOVERY_URL` and `VAPI_DISCOVERY_URL` variables can still
+override either full endpoint separately. Registry fallbacks are stored in
+`config.json` under `registryFallbacks`.
+
+## Packages
+
+| Package                 | Purpose                                                                  |
+| ----------------------- | ------------------------------------------------------------------------ |
+| `@vapi-network/core`    | x402 protocol, wallet, spend policy, discovery merge, and receipts       |
+| `@vapi-network/sources` | vAPI Registry, Coinbase Bazaar, local-file, and x402scan source adapters |
+| `@vapi-network/mcp`     | stdio MCP server with namespaced payment tools                           |
+| `@vapi-network/cli`     | `init`, discovery, payment, wallet, receipt, and MCP commands            |
+| `vapi-network`          | zero-dependency distribution with the `vapi` binary and defaults         |
+
+Every npm tarball is bundled and has zero runtime dependencies. The scoped
+packages are useful for embedding; most users should start with
+`vapi-network`.
+
+## SDK
+
+The core and source packages can be used without the CLI or MCP layer. See the
+runnable [SDK example](./examples/pay-with-sdk.ts) for discovery, policy
+validation, local signing, and direct x402 payment construction.
+
+Run it after initialization with `pnpm example:pay -- weather`.
+
+## Local state and migration
+
+By default, local state lives in `~/.vapi/`:
+
+```text
+config.json
+keystore.json
+receipts.jsonl
+spend-ledger.json
+reports/
+```
 
-## Paid-call receipts
+Set `VAPI_HOME` to use a different directory. On first use of the default home,
+the client copies an existing `~/.vapi/agent-cash/` configuration into
+`~/.vapi/` when it can do so without overwriting files, prints a migration
+notice, and leaves the old directory untouched.
 
-The `call` result keeps both payment receipt surfaces under `payment`:
+## Metrics
 
-- `settlement` is the decoded x402 `Payment-Response` (or compatible `X-Payment-Response`) header.
-- `proof` is normally `null` for launch-approved native endpoints. Agent Cash
-  preserves an `X-VAPI-Payment-Proof` value if a future reviewed Wrap endpoint
-  returns one.
+vAPI measures call and discovery health locally. Call receipts can include the
+listing name and provider host, policy decision, retry count, client version,
+outcome, total latency, and discovery, quote, signing, request, and settlement
+phase timings. Policy declines are recorded with the quoted amount but without
+a payer or transaction, so blocked spend remains visible without creating a
+payment authorization. Search events record the query, sources tried,
+per-source latency and result count, merged result count, and timestamp.
 
-A proof value alone is not verification. A future Wrap consumer must pin and
-verify its signer and fields and enforce replay protection.
+Call receipts are appended to `$VAPI_HOME/receipts.jsonl`; search events are
+appended to `$VAPI_HOME/searches.jsonl`. Nothing in either ledger is uploaded,
+and vAPI sends no telemetry off the machine by default. The vAPI website can
+show public on-chain usage for a wallet address directly from the chain; that
+view does not require uploading these local files.
 
-## Balances and sweep-back
+Use `vapi stats --range 24h|7d|30d` for a human-readable summary or add `--json`
+for the stable `{ range, generatedAt, totals, outcomes, latency, topServices,
+search }` shape. `receipts.stats` exposes the same shape through MCP. Export raw
+receipts for spreadsheets and dashboards with:
 
 ```sh
-VAPI_AGENT_CASH_HOME="$PWD/.context/agent-cash" pnpm --filter @vapi-network/mcp exec node dist/cli.js balance
-VAPI_AGENT_CASH_HOME="$PWD/.context/agent-cash" pnpm --filter @vapi-network/mcp exec node dist/cli.js sweep-back 0xYourMainWallet
-VAPI_AGENT_CASH_HOME="$PWD/.context/agent-cash" pnpm --filter @vapi-network/mcp exec node dist/cli.js sweep-back 0xYourMainWallet --network eip155:8453
+vapi receipts export --format json --range 30d
+vapi receipts export --format csv --range 30d
 ```
 
-Without `--network`, sweep-back attempts every configured network. Base transfers the full USDC balance because gas is paid in ETH. Arc gas is paid in USDC, so Agent Cash keeps 0.05 USDC by default instead of stranding the sweep transaction. Configure that reserve with `VAPI_ARC_GAS_HEADROOM_USDC` (for example, `0.10`).
+## Roadmap
 
-## Networks
+- A local gateway daemon (`vapi serve`) with per-key budgets
+- OpenTelemetry traces and metrics, with exporters enabled only by the user
+- `task.*` tools for posting, funding, delivering, and reviewing work
+- `compute.*` tools for discovering models and paying for inference
+
+Until the gateway lands, `vapi serve` and the provider-side `vapi publish`
+command exit with a preview message. Payments remain direct from the local
+wallet to each service.
 
-| Network      | CAIP-2           | Chain ID | USDC                                         | Gas token | RPC                                                    |
-| ------------ | ---------------- | -------: | -------------------------------------------- | --------- | ------------------------------------------------------ |
-| Base mainnet | `eip155:8453`    |     8453 | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | ETH       | `BASE_RPC_URL`, defaults to `https://mainnet.base.org` |
-| Arc testnet  | `eip155:5042002` |  5042002 | `0x3600000000000000000000000000000000000000` | USDC      | `ARC_TESTNET_RPC_URL` is required                      |
+## Development
 
-Agent Cash configures Base only by default. For the staging test, first run
-`search {"query":"<capability>","kinds":["api"],"network":"eip155:8453"}`.
-In the same Agent Cash process, call the returned ref with
-`call {"id":"<search-result-ref>","network":"eip155:8453","maxPriceUsd":"0.02"}`.
-Arc remains opt-in: set a nonblank `ARC_TESTNET_RPC_URL` to add it. The same
-exact-scheme EIP-3009 code path handles both CAIP-2 networks. You can also edit
-the `networks` map in `~/.vapi/agent-cash/config.json`; entries with blank RPC
-URLs are ignored and cannot be selected for payment. A custom token/network
-entry must pin its EIP-712 domain as `"eip712Domain": { "name": "…", "version":
-"…" }`; provider-supplied domain text is never trusted on its own.
+This is a pnpm workspace for Node.js 22 and pnpm 10.
 
-## Custody and recovery
+```sh
+pnpm install
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm pack:check
+```
 
-This package is self-custodied software: the encrypted payment key and spend ledger live on your machine. vAPI is discovery only in this lane. Vendors receive only narrowly scoped EIP-3009 authorizations for the exact quoted amount, recipient, token, chain, nonce, and validity window. A stolen unlocked key or passphrase can still drain the wallet, so keep only a small working balance and sweep unused funds back.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development workflow,
+[CHANGELOG.md](./CHANGELOG.md) for what shipped in each release, and
+[SECURITY.md](./SECURITY.md) for private vulnerability reports.
 
-Back up the encrypted keystore if you need recovery. Losing both the keystore and its backup permanently loses access to its funds; losing the passphrase does too. Never share the decrypted private key.
+CLI commands exit `0` on success, `1` on an operational failure, and `2` for
+invalid usage or an announced preview-only command. `--json` sends both success
+values and errors to stdout as one JSON value; `mcp --json` is accepted as a
+no-op because the stdio transport is already JSON-RPC.
 
 ## Publishing
 
-npm reads `package.json` before any `prepack` hook runs, so the manifest cannot be rewritten in
-place. Publish from the staged directory instead:
+All five packages share one version and are published together. npm reads a
+package manifest before lifecycle hooks run, so the release is made from the
+generated `publish/` directories, never from the workspace package roots.
 
-```bash
-pnpm --filter @vapi-network/mcp publish:npm
+First update every package to the same version and verify the exact tarballs:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm pack:check
 ```
 
-That builds, stages `publish/` with an empty `dependencies` map (everything is bundled), runs the
-pack check against the staged tarball, then publishes it.
+After reviewing the output, a maintainer with npm access runs these commands
+manually:
+
+```sh
+npm login
+pnpm --dir packages/core publish:npm
+pnpm --dir packages/sources publish:npm
+pnpm --dir packages/mcp publish:npm
+pnpm --dir packages/cli publish:npm
+pnpm --dir packages/vapi-network publish:npm
+```
+
+Each package's `publish:npm` script publishes its staged `./publish` directory
+to the `latest` npm tag. Every package also has a `publish:npm:next` script that
+publishes the same tarball to `next` instead, for preview builds. The manual
+release workflow verifies and prints these commands; it never receives npm
+credentials or publishes automatically.
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { callService, createVapiServer, loadServerConfig, startStdioServer, type CallToolInput, type CallToolResult, type VapiServerOptions, } from "./server.js";
+export { inspectService, type InspectToolInput, type InspectToolResult } from "./tools/inspect.js";
+export { resolveServiceEndpoint, resolveServiceListing, searchMarketplace, type MarketplaceSearchInput, } from "./tools/search.js";
+export { getWallet, type WalletBalance } from "./tools/wallet.js";
+export { buildSIWxProof, parseSIWxResponse } from "./siwx.js";