Vapi

vAPI Call

vAPI Call is a catalogue of x402 APIs an agent can find, check and pay per request.

• No fee. vAPI Call takes no fee. Providers are paid directly at their own quoted price.
• No signup. No account and no API key. Search needs nothing; paying needs a funded wallet on this machine.
• Your own wallet. The key is created and kept on this machine. Spend caps are applied before anything is signed.
• Onchain proof. Every paid call settles in USDC on Base or Arc, and the receipt names the transaction.

The CLI is vapi, from the npm package vapi-network. Run vapi help for every command and flag; it is the source of truth when this file and the CLI disagree.

Setup

Check the installed CLI and the latest release:

vapi version --json
npm view vapi-network version

Install or update when vapi is not found, when the two versions differ, or when the CLI version does not match version in this file's frontmatter:

npm i -g vapi-network@latest

Then save the latest skill from https://vapinetwork.ai/SKILL.md over this file. Bring both to the latest; never downgrade either one to match the other. Without a global install, prefix every command with npx -y vapi-network@latest. The bare npx vapi is an unrelated package.

Check the wallet:

vapi balance --json

• No wallet yet (No wallet yet. Run vapi init.). Ask the user to run vapi setup in their own terminal. It creates the device vault, shows the recovery phrase to them, and links the wallet to their owner wallet. If the user asks you to create it, vapi init --json does so with the phrase hidden; the user then runs vapi backup in their terminal before funding it. Never ask for, print or store the phrase.
• Balance is zero. Run vapi fund. It opens a page where the user pays by card, sends USDC on Base from a wallet, or bridges from another chain.
• Caps. A new account may spend $0.10 per call and $1.00 per day. vapi accounts caps <account> shows the current values.

MCP clients get the same tools (call.search, call.inspect, call.pay, wallet.balance, receipts.list):

vapi mcp install claude-code
vapi mcp install claude-desktop
vapi mcp install cursor
vapi mcp install codex

When not to use vAPI

vAPI fills gaps in the user's stack. Choose in this order:

1. The user's instruction for this task. If they said how to do it, do it that way.
2. The user's own tools. An MCP server, CLI, API key or workflow they already have for that service. Their key may cost nothing extra; a vAPI call spends their USDC.
3. vAPI Call, for everything the first two do not cover.

When both could do the job and the user has not chosen, use their tool and mention the vAPI listing as an option. Never switch silently.

Search, inspect, pay

vapi search "weather forecast" --limit 10 --json
vapi inspect <ref> --json
vapi pay <ref> --body '{"city":"Lisbon"}' --max 0.02 --json > forecast.json

1. Search with one short noun phrase and --limit 10. Read those 5 to 10 results before searching again or paging with --cursor. Each result has a ref, a price, a group and a verification tier. --include-unverified adds self-listed APIs that passed vAPI's automated probe but were never reviewed. Health and cheaper or healthier alternatives may be supplied; --include-outage includes APIs hidden by the default outage filter.
2. Inspect the one you picked. It is free and shows the request contract (method, content type, request schema), the last observed quote and payee, and liveness. A listing with several endpoints needs --endpoint <name>. Build the request from the schema; never guess a field.
3. Pay with --max set to the price you expect, in USD. --body takes the request as JSON; for a GET it is sent as query parameters. vapi pay fetches a fresh quote, checks it against --max and the caps, signs one USDC authorization for exactly that quote, and returns the provider's response with the payment and its proof.
4. Split a task that needs several sources into one search, inspect and pay per source.
5. Report the cost when the user cares about spend. vapi receipts lists every paid call with its quote, settlement and latency.

Send one item per call and a small limit (5 to 10) when an input takes a list or a result count. Some providers bill per item, and a list of three search terms can return three times the results.

Choosing between listings

Prefer, in this order, among listings that fit the task:

vapi inspect prints a Liveness: line when vAPI has measured the listing: uptime over the last seven days of hourly checks, with p50 and p95 latency. No liveness line means not measured yet. That is common for a low-traffic listing and is no reason to skip it. Three consecutive failed checks suspend a listing and remove it from discovery. The registry also hides APIs whose health is outage by default; --include-outage requests those results.

Use these signals to break ties between listings that fit. Fit to the task comes first.

Caps and what a block means

The CLI checks every payment against the account's caps before signing. A block is terminal: nothing was signed, nothing was paid, and retrying gives the same answer.

Current clients return spend_cap_exceeded with one of these cap values:

Clients before 0.11.0 used per_call_cap_exceeded, per_day_cap_exceeded and max_price_exceeded for these blocks. Read amountUsd, limitUsd, optional spentUsd, and command for the attempted payment and guidance. MCP marks the result retryable: false.

Tell the user which cap blocked, the quote, and the command that changes it. The caps are the user's spending limit, so the user decides whether to raise them:

vapi accounts caps <account> --per-call 0.50 --per-day 5

Recovery

Exit codes are 0 for success, 1 for an operational failure and 2 for invalid usage.

Slow providers

Read the p95 in vapi inspect before paying. The paid request waits for the provider's advertised maximum, clamped to 30 to 120 seconds, or 120 seconds when the provider names none. --timeout <seconds> sets it from 1 to 300 seconds; a smaller provider maximum still applies. If the response is lost after the payment was signed, the result is settlement_unknown: follow the recovery row above and never pay twice.

Large responses

Send --json output to a file and read the parts you need:

vapi pay <ref> --body '{"symbol":"ETH"}' --max 0.01 --json > eth.json
jq '.body' eth.json
jq '.payment' eth.json

body is the provider's response. payment holds the network, the amount in USD, the payee, and the settlement proof.

Rules

1. Check the user's stack first. Their own tools come before vAPI; see "When not to use vAPI".
2. Inspect before every first payment to a listing. The request schema is the contract.
3. Always pass --max. Set it to the price you expect, so a changed quote stops before signing.
4. Start small. One query, 5 to 10 results, one item per paid call.
5. Never pay twice for one request. After settlement_unknown or a lost response, run vapi pay --resume <receipt-id> first.
6. Surface cap blocks. Name the cap and the quote; the user decides whether to raise it.
7. Keep secrets out of the conversation. Never ask for, print or store a recovery phrase, passphrase or private key. vapi backup and vapi export-key are for the user's own terminal.