@vapi-network/mcp 0.2.0-dev.2 → 0.2.0

package/README.md

@@ -18,16 +18,25 @@ npm i -g vapi-network
 vapi init                      # encrypted wallet + config under ~/.vapi (or $VAPI_HOME), prints the address
 ```
 
-Fund that address with USDC on Base. Then:
+Fund that address with `vapi fund` (card or Apple Pay via Coinbase Onramp) or by
+sending USDC on Base to it. Then:
 
 ```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
 ```
 
+`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.)
 
@@ -47,8 +56,118 @@ Add this to Claude Desktop, Claude Code, or Cursor. The passphrase unlocks the l
 }
 ```
 
-Tools: `call.search`, `call.inspect`, `call.pay`, `wallet.address`, `wallet.balance`, `receipts.list`.
-Spend caps default to $0.10 per call and $1.00 per day; the wallet checks both before it signs.
+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.
+
+## Sign-in with X
+
+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
+```
+
+`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
+
+```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
+{
+  "depositUrl": "https://your-arc-faucet.example",
+  "depositInstructions": "Use the configured Arc testnet faucet, then send USDC to this address."
+}
+```
+
+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.
+
+## Reporting a bug
+
+```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
+```
+
+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.
+
+## Networks
+
+| 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` |
+
+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
+```
+
+Or add an Ed25519 account to an existing encrypted keystore:
+
+```bash
+vapi accounts --enable solana
+```
+
+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
 
@@ -60,7 +179,11 @@ provenance:
   `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`.
+  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
@@ -110,6 +233,7 @@ config.json
 keystore.json
 receipts.jsonl
 spend-ledger.json
+reports/
 ```
 
 Set `VAPI_HOME` to use a different directory. On first use of the default home,
@@ -167,7 +291,8 @@ pnpm build
 pnpm pack:check
 ```
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development workflow and
+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.
 
 CLI commands exit `0` on success, `1` on an operational failure, and `2` for
@@ -181,8 +306,7 @@ 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.
 
-First update every package to the same version, keep
-`publishConfig.tag = "next"`, and verify the exact tarballs:
+First update every package to the same version and verify the exact tarballs:
 
 ```sh
 pnpm install --frozen-lockfile
@@ -202,9 +326,10 @@ pnpm --dir packages/vapi-network publish:npm
 ```
 
 Each package's `publish:npm` script publishes its staged `./publish` directory
-with `npm publish ./publish --access public --tag next`. The manual release
-workflow verifies and prints these commands; it never receives npm credentials
-or publishes automatically.
+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
 

package/dist/index.d.ts

@@ -1,4 +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, searchMarketplace, type MarketplaceSearchInput, } from "./tools/search.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";