Vapi Network

vAPI Network

One wallet, every x402 API. vAPI Network is an open-source, non-custodial TypeScript toolkit for discovering and paying x402 services from a terminal, an MCP client, or your own code. Your key is generated on your machine, encrypted under your passphrase, and never leaves it. vAPI applies spend policy before signing, sends the payment straight to the service, and writes a local receipt. Every payment identifies this client as vapi through x402 builder-code; when an API advertises payment-identifier, the generated id is kept on that receipt.

Call works today. Tasks and Compute are next.

Quickstart

npm i -g vapi-network
vapi init                        # creates ~/.vapi, the wallet main, and prints its address
vapi backup                      # write the 12 words down; vAPI cannot recover them
vapi fund                        # opens the hosted funding page for your address
vapi search "weather"            # every catalogue, merged, with provenance
vapi pay  --max 0.02
vapi receipts                    # one line per paid call: quote, settlement, latency

That is the same order vapi init prints as its next steps, and the same order vapi alone lists. Two more are worth knowing early: vapi inspect shows a listing's request contract and live 402 quote for free, before you pay, and vapi balance shows what the wallet holds.

vapi search tags each listing with its group — [vapi], [added], [partner] or [external] — and prints the network fee that is already inside the price. vAPI and added APIs carry a 5% network fee inside the quoted price; partner and external listings carry none. vapi inspect and --json return the same group and fee fields.

Listing on vAPI is permissionless, and verification is a tier on top of it. Each result also carries [verified], [requested] or [unverified], and a mirrored catalog row carries [external] instead. By default vapi search answers with vAPI-verified listings plus the mirrored external catalogs; --include-unverified also returns self-listed APIs that passed vAPI's automated x402 probe but were never reviewed. vapi inspect prints a Verification: line, vapi pay says so in one line before the result when the listing it just paid is not verified, and --json carries verification on all three.

vapi inspect also says how a listing has behaved lately, when the registry has measured it: a Liveness: line with its uptime over the last seven days of hourly re-probes and its p50 and p95 latency, and a Conformance: line with the x402 version its 402 declares, whether it follows that version, where the offer travels, and any issue codes — the same codes vapi check reports. A registry that has not measured a listing sends neither, and neither line is printed. --json carries them as liveness and conformance.

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.)

Wallets

One machine can hold several wallets: your own, and a capped one per agent. Each keystore lives in $VAPI_HOME/wallets/.json; $VAPI_HOME/wallets.json records which one is the default, what each may spend, and its label. Names are 1 to 32 characters of lowercase letters, digits and dashes.

vapi wallet list                                 # address, default marker, caps, unlocked, label
vapi wallet create agent --label "claude code"   # a wallet of its own for the agent
vapi wallet caps agent --per-call 0.05 --per-day 1
vapi wallet use agent                            # make it the default for later commands
vapi pay  --wallet agent --max 0.02
vapi receipts --wallet agent                     # or --all-wallets for every one

Every command that touches a wallet takes --wallet : balance, accounts, fund, pay, sweep, receipts, stats, export-key, backup, import, passphrase, unlock, lock and mcp. Without it, VAPI_WALLET decides; without that, the default set by vapi wallet use does. Each of them names the wallet it used — Wallet: main (0x…) on the first line, or a wallet field in --json — so neither you nor an agent can be wrong about which key just moved.

Spend caps belong to the wallet, not to the machine, and today's total is counted per wallet: an agent cannot spend your daily allowance. Removing a wallet is a move, not a delete — the encrypted keystore goes to wallets/.trash/, where vapi wallet restore can bring it back.

Coming from 0.2.x? Nothing to do. The first command you run opens the wallet store, moves keystore.json to wallets/main.json with its contents untouched, turns config.json's spend caps into the caps of main, and leaves keystore.json behind as a mode 0600 symlink for one release so existing scripts keep working. A home with no keystore migrates nothing.

Your wallet is yours

vapi init generates a 12-word BIP-39 recovery phrase on your machine, derives the Base account (m/44'/60'/0'/0/0) and, with --networks base,solana, the Solana account (m/44'/501'/0'/0') from it, and writes the phrase encrypted under your passphrase to $VAPI_HOME/wallets/main.json (mode 0600). The phrase is shown once, on a terminal, and never in --json or piped output.

Three things vAPI cannot do:

• See it. No key, phrase or passphrase ever leaves the machine.
• Recover it. There is no copy anywhere to restore from.
• Freeze it. Payments go straight from your wallet to the service.

Back it up

vapi backup                       # the 12 words, numbered, on a terminal
vapi backup --json                # { "wallet": "main", "recoveryPhrase": "..." }

Write the words on paper and keep them somewhere only you reach. Anyone holding them can spend the wallet, so never type them into a website or a chat.

Wallets created before 0.2.5 have no recovery phrase. vapi backup says so and points at vapi export-key, which prints the private key itself; back that key up, or vapi import --key it into a new wallet. Restoring a phrase-based wallet in MetaMask, Rabby, Coinbase Wallet or Phantom gives the same addresses.

Import and move a wallet

vapi import --phrase                          # type the words at the prompt
vapi import --phrase --networks base,solana   # restore both accounts
vapi import --key                             # a 0x private key instead of words
vapi import --phrase --wallet backup-2026     # into a named wallet of its own

vapi import reads the secret from a prompt, never from the command line where a shell history would keep it, and asks for a new passphrase. It writes a new named wallet rather than replacing one: --wallet chooses the name, and main is assumed only on a machine with no wallet yet. --replace moves the named wallet to wallets/.trash/ first, and still refuses a wallet that holds USDC on Base unless you add --force.

Change the passphrase

vapi passphrase                   # current passphrase, then the new one twice

The wallet, its addresses and its recovery phrase are unchanged. Any copy of the old passphrase stored by vapi unlock is removed at the same time, so nothing is left behind that no longer opens the wallet.

Agents and secrets

An agent can drive vAPI all day without ever seeing a secret. It can search, inspect, pay from the wallet you gave it, read balances and receipts, and pick a wallet by name with wallet.use — which changes only that session, never your default on disk. It cannot see a recovery phrase, a private key or a passphrase, and the MCP server has no tool that creates, removes, renames, backs up or exports a wallet.

vapi backup and vapi export-key print a secret, so they run only when a person is demonstrably there: stdin and stdout are both a real terminal, no agent or CI marker is set, and you type the wallet's own name to confirm. Otherwise they print nothing and say:

Run this yourself in a terminal; an agent must never see these words.

The markers vAPI refuses on are VAPI_NO_SECRETS, CLAUDECODE, CLAUDE_CODE, CURSOR_AGENT, CODEX_SANDBOX, OPENAI_CODEX, AGENT and CI. Set VAPI_NO_SECRETS=1 in a machine's agent configuration to switch secret printing off outright. vapi init and vapi wallet create still create the wallet under those conditions; they simply say Recovery phrase: run vapi backup yourself in a terminal to see it.

In the SDK the same line is drawn by the module layout: the functions that return a phrase or a key live in the separate @vapi-network/core/secrets entry point, which the MCP package is forbidden by lint to import.

Where the passphrase lives

An unlock looks in three places, in this order:

1. VAPI_KEYSTORE_PASSWORD, kept for CI and for Windows.
2. The OS secret store: the macOS Keychain, or libsecret on Linux, under the

service vapi-network and the wallet's name.

1. A prompt, when a person is there to answer it.

vapi unlock --wallet agent        # store it, once, in your own terminal
vapi wallet list                  # the UNLOCKED column says which agents can pay
vapi lock --all                   # take every stored passphrase back out

vapi unlock runs only on a real terminal with no agent marker set, and only after it has verified that the passphrase really opens that wallet. The passphrase is handed to the OS binary over its standard input, never as a command-line argument, so it never appears in ps. A run that finds no passphrase anywhere and has no terminal says so and names both other routes; an agent is never prompted. Windows has no store yet and keeps VAPI_KEYSTORE_PASSWORD.

The audit log

Every secret export, every wallet change — create, import, remove, restore, rename, default, caps, passphrase, unlock, lock — and every MCP session wallet switch appends one JSON line to $VAPI_HOME/audit.log (mode 0600): the time, the event, the wallet, whether a terminal was attached, and which marker was set. The line never contains the secret itself, so the log answers "did anything export my phrase while the agent was running" without you having to trust the agent's own account of it.

CLI reference

Every command accepts --json, which writes one JSON value — success or error — to stdout. Exit codes are 0 for success, 1 for an operational failure, and 2 for invalid usage or an announced preview-only command.

| Command | Options | What it does | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | vapi init | --networks | Creates ~/.vapi, the wallet main and the config. Says so if one exists. | | vapi wallet list | — | Name, address, default marker, caps in USD, unlocked, label | | vapi wallet create | --networks , --label | A new wallet, with its own phrase, caps and passphrase | | vapi wallet use | — | Makes it the default for every later command | | vapi wallet rename | — | Renames the keystore, the registry entry and that wallet's receipts | | vapi wallet remove | --force | Moves the keystore to wallets/.trash/; asks you to type the name | | vapi wallet restore | — | Brings a removed wallet back, same passphrase | | vapi wallet caps | --per-call , --per-day | Sets that wallet's spend caps, in US dollars | | vapi fund | --amount , --wallet | Prints and opens the hosted funding page. Makes no network call. | | vapi accounts | --enable solana, --wallet | One deposit account per configured network, with balances and guidance | | vapi search [query] | --kind (repeatable), --network , --limit , --cursor , --include-unverified | Merged discovery across every configured source, tagged by group and tier | | vapi inspect | --endpoint | Verification, fee, liveness, conformance, contract and live quote, for free | | vapi pay | --method, --endpoint, --body , --content-type, --network , --expected-pay-to, --max , --wallet | Calls the API and pays it from the local wallet, naming an unverified tier | | vapi pay --resume | — | Checks settlement, shows its payment id, and never pays | | vapi check | --method | Grades its 402, extensions and same-origin discovery. Never pays | | vapi balance | --wallet

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vAPI-Network
• Source: vAPI-Network/vapi-network
• License: Apache-2.0
• Homepage: https://vapinetwork.ai

Install and usage instructions live in the source repository linked above.