Vaaya

Official13 toolsLive

by vaaya-ai · JavaScript

Paid APIs and tokenized shares for agents. Prepaid funding, including authorized Instinct checkout.

Vaaya MCP (ai.vaaya/mcp)

The Vaaya MCP server provides payments for AI agents using the Model Context Protocol. It lets an agent call paid APIs—covering search, scraping, contact/data access, public records, compute, media/video generation, product demos, and research—from a single balance, governed by a per-call spend ceiling.

🛠️ Key Features

Pay-per-call API access for MCP hosts
Spend ceiling stated on every call
No vendor keys in environment
Costs only when calls succeed
x402 USDC on Base, Stripe MPP, or Tempo billing support
Refused/failed calls cost nothing
Tool availability: 9 tools

🚀 Use Cases

Media/video generation
Product demos
Research and deep-research workflows
GTM-related tasks
Web scraping and web search
Compute and agent skills requiring paid actions
Agent wallet / spend-limit management

⚡ Developer Benefits

One balance for paid API calls from an MCP host
Centralized spend control via spend ceiling
Avoids vendor key management in the environment
Works across Cursor, Claude Code, Claude Desktop, and Codex-style MCP hosts

⚠️ Limitations

Payment-based access is tied to specific success/billing behavior (failed/refused calls are not charged)
Tooling is limited to what the server exposes (9 tools)

Topics

agent-payments, ai-agents, mcp, model-context-protocol, mcp-server, web-scraping, web-search, pay-per-call, spend-limit, cli, agent-wallet

Topics

agent-paymentsai-agentscode-sandboxdeep-researchmcpmodel-context-protocolweb-scrapingweb-searchx402agent-skillscliagent-walletclaudeclaude-codecodexcursorpay-per-callinstinctprepaidtokenized-stocks

Captured live from the server via tools/list.

stocks

Buy tokenized stocks on Base using only the user’s prepaid Vaaya balance, never the welcome credit or the GitHub credit line. Commands: list (supported token tickers), portfolio (owned stocks and buying power), quote {symbol, amount_cents}, buy {symbol, amount_cents, idempotency_key}, order {order_id}. When the user asks to buy a specified stock and dollar amount, resolve its supported token ticker (Apple = AAPLc) and call buy directly; no activation or additional approval step. amount_cents is the maximum total prepaid spend including provider fees. Use a unique idempotency_key for each intended purchase and reuse it on retries. Query order until confirmed/failed; queued/submitted is not success. Do not increase the user’s spend or retry a failed purchase as a new order without instruction. Ask only for missing or ambiguous purchase details. If prepaid_required or buyingPowerCents is insufficient, offer a $10/$30/$100 prepaid pack: POST /api/v1/topup with pack_cents 1000/3000/10000 and the same account bearer token returns a Stripe Checkout url. With authorization for that pack amount, the user’s Instinct agent can pay the URL in its browser using the card saved in Instinct; otherwise give the URL to the user. Vaaya cannot charge Instinct’s card directly. Do not include card details or tokens in a handoff. Check GET /api/v1/wallet wallet.prepaid_cents, then portfolio buyingPowerCents before resuming the same purchase key. A share purchase alone does not authorize a top-up. Stop on needs_review as well as failed.

Parameters5

command	string	required	list (supported tickers), portfolio (holdings + buying power), quote, buy, or order (status by id).
symbol	string	optional	Token ticker from list, e.g. AAPLc. Required for quote and buy.
amount_cents	integer	optional	Maximum prepaid spend in cents, pool fees included. Required for quote and buy.
idempotency_key	string	optional	Unique per intended purchase; reuse it on retries. Required for buy.
order_id	string	optional	Order id returned by buy. Required for order.

Raw schema

{
  "type": "object",
  "properties": {
    "command": {
      "type": "string",
      "enum": [
        "list",
        "portfolio",
        "quote",
        "buy",
        "order"
      ],
      "description": "list (supported tickers), portfolio (holdings + buying power), quote, buy, or order (status by id)."
    },
    "symbol": {
      "type": "string",
      "description": "Token ticker from list, e.g. AAPLc. Required for quote and buy."
    },
    "amount_cents": {
      "type": "integer",
      "minimum": 100,
      "maximum": 1000000,
      "description": "Maximum prepaid spend in cents, pool fees included. Required for quote and buy."
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128,
      "description": "Unique per intended purchase; reuse it on retries. Required for buy."
    },
    "order_id": {
      "type": "string",
      "description": "Order id returned by buy. Required for order."
    }
  },
  "required": [
    "command"
  ],
  "additionalProperties": false
}

vaaya_test_connection

Round-trip ping that confirms the agent → Vaaya connection and whether the user is linked. Returns { ok:true, userId, scope, version, server_time, first_call } when linked — SHOW `first_call.show_to_user` to the user as written, it is the same set of starter examples the website and installer give them. Returns { ok:false, needs_auth:true, verification_uri, signup_uri, instructions } when not linked yet — relay that to the user so they can connect (and sign up if new).

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

vaaya_onboard

Public onboarding hint for an agent whose user isn't linked to Vaaya yet. Returns where the human should go to connect (and sign up if new). Call this when vaaya_test_connection reports needs_auth, or any tool returns unauthorized, then relay the instructions to the user. If the user IS already linked it returns `first_call` instead — show `first_call.show_to_user` as written so they know what to try.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

vaaya_account

Show which Vaaya account this connection is linked to and its money state. Returns { email, name, user_id, connected_client, scopes, balance_cents, credit_line, available_cents, credits_url, switch_account }. Call it whenever the user asks "which account is connected", "what's my balance", "how much credit is left", or "how do I switch accounts" — and relay the answer. `credit_line` is the credit the account can spend past its prepaid balance (the welcome credit plus any GitHub-score line); `available_cents` = balance + active line, the number calls are gated on.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

vaaya_logout

Disconnect this client from the current Vaaya account: revokes this connection's authorization server-side, so every later call fails with 401 until the user reconnects. Call it when the user asks to log out, sign out, disconnect, or switch Vaaya accounts — then relay the returned switch steps VERBATIM (the browser sign-out step is what actually enables switching accounts).

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

docs

Vaaya's deep reference, FREE and instant. Pass `topic` to get the full playbook for a capability area — exact services, actions, params, prices, model lists, and gotchas — the same reference files the vaaya skill ships. Topics: 'setup' (connecting an agent, a chat app, or an unattended process), 'tools' (exact params of every Vaaya tool, GTM suite included), 'media' (image/video/audio models + product-demo videos), 'gtm' (leads, enrichment, outreach, signals, email), 'research' (OneSearch lanes, deep research, company/market research playbooks), 'data' (scraping, people, social platforms, public records, onchain, compliance), 'compute' (sandboxes, browser automation, files, memory, workers, phone calls, llm). Read the matching topic BEFORE non-trivial work in that area — it is cheaper than a wrong call. Never bills; safe to call any time.

Parameters1

topic

string

required

Which reference to fetch.

Raw schema

{
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "enum": [
        "setup",
        "tools",
        "media",
        "gtm",
        "research",
        "data",
        "compute"
      ],
      "description": "Which reference to fetch."
    }
  },
  "required": [
    "topic"
  ]
}

consult

Vaaya's consultant. Describe ANY external capability you or the user might want — generate an image/video, search or scrape the web, run code in a sandbox, send/receive email, enrich a contact — and it helps figure out the best way, teaching the user what Vaaya can do. It is CONVERSATIONAL and remembers prior turns. It returns: mode='converse' (a reply to RELAY to the user verbatim — questions, options, ideas; get the user's response and call consult again with it, so the conversation continues), mode='call' (an ordered list of calls to run via `use`, with a message explaining the preferred choice + alternatives + why; multi-step results may contain placeholders like '<from step 1: sandbox_id>' — run earlier steps first and substitute), or mode='unsupported'. Every reply includes `suggestions` (2-3 things to do next) — surface these to the user. AFTER you run a `call` result's calls via `use`, call consult ONE more time with a short note on the outcome (what was produced / any failures) — it returns result-aware, Vaaya-grounded next steps to offer the user (the `call` result's `after_running` field reminds you). Call consult whenever you hit a capability gap or the user wants to know what's possible. It does NOT execute or bill — you run returned calls via `use`. ALWAYS show the user consult's `message` and `suggestions` and let them steer.

Parameters1

intent

string

required

Plain-English description of what you want, or your answer to a previous clarify question. Be concrete — include the prompt text, URL, budget, or target the task implies.

Raw schema

{
  "type": "object",
  "properties": {
    "intent": {
      "type": "string",
      "description": "Plain-English description of what you want, or your answer to a previous clarify question. Be concrete — include the prompt text, URL, budget, or target the task implies."
    }
  },
  "required": [
    "intent"
  ]
}

use

Execute a single external call, and bill on success. Used for any external capability (image/video/audio generation, web search, scraping, email, document parsing, code sandbox, browser automation, embeddings, etc.). The server validates params against a registered schema and proxies to the upstream — you never pass URLs or API keys. Call it directly when you know the exact (service, action, params, max_cost_cents) — from the vaaya skill's catalog or a call you've made before; when unsure, get the call from `consult` rather than guessing.

Parameters5

service	string	required	Service identifier, taken verbatim from the call `consult` returned.
action	string	required	Action within the service (e.g. "search", "generate", "create_session"), taken from the call `consult` returned.
params	object	required	Parameters from the call `consult` returned, validated against the service's registered schema.
max_cost_cents	number	required	Hard ceiling in cents on what you will be charged. `use` refuses if the registry price exceeds this. Pick at least 2× the listed price so retries work.
intent	string	optional	Optional: the one-line `why` from the consult call you're running (or the user's goal for it). Used only for internal transaction visibility — it never affects validation, billing, or execution. Pass it through when you have it.

Raw schema

{
  "type": "object",
  "properties": {
    "service": {
      "type": "string",
      "description": "Service identifier, taken verbatim from the call `consult` returned."
    },
    "action": {
      "type": "string",
      "description": "Action within the service (e.g. \"search\", \"generate\", \"create_session\"), taken from the call `consult` returned."
    },
    "params": {
      "type": "object",
      "description": "Parameters from the call `consult` returned, validated against the service's registered schema.",
      "additionalProperties": true
    },
    "max_cost_cents": {
      "type": "number",
      "description": "Hard ceiling in cents on what you will be charged. `use` refuses if the registry price exceeds this. Pick at least 2× the listed price so retries work."
    },
    "intent": {
      "type": "string",
      "description": "Optional: the one-line `why` from the consult call you're running (or the user's goal for it). Used only for internal transaction visibility — it never affects validation, billing, or execution. Pass it through when you have it."
    }
  },
  "required": [
    "service",
    "action",
    "params",
    "max_cost_cents"
  ]
}

result

Fetch the status + output of an async job started by `use` (e.g. a video render). Pass the `job_id` that `use` returned with `{ async: true }`. Returns `{ status, result?, progress?, charged_cents }`: `running` (still working — when the job reports it, `progress` carries `{ phase, percent, rendered_frames, total_frames, eta_sec }` and `hint` is a one-line summary like "rendering 42% (380/900 frames, ~120s left)", so you can tell real progress from a hang; wait a bit and call again), `succeeded` (`result` holds the output, e.g. the video URL; the call is charged now), or `failed`/`cancelled` (no charge; on `failed`, read `error` AND `hint` — `hint` carries the service's usage notes, which usually explain how to fix the call). Safe to call repeatedly — it never starts new work or double-charges. ALWAYS use this to retrieve an async result instead of re-running `use` (re-running starts a new paid job).

Parameters1

job_id

string

required

The job_id returned by an async `use` call.

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "The job_id returned by an async `use` call."
    }
  },
  "required": [
    "job_id"
  ]
}

buy

Find and buy products, tickets, bookings and subscriptions for the user at supported stores. Start with `search` { query } to find the item and merchant page using Vaaya OneSearch (5¢ per search); the user can describe what they need without supplying a link. Before checkout, use `setup` to check payment and shipping readiness; resolve missing setup once. Persistent merchant accounts are managed at /store-connections. Use store_connection_id to select an account. Passwords and verification codes belong only on the merchant page, never in chat. PRODUCT DISCOVERY: if the user describes what to buy but provides no URL, use `search` { query: <product, variant, budget and preferred merchant if specified> } to locate it under the existing tool spending permissions; do not ask them to paste a link or say search for it first. Search is not purchase authorization. Respect search fees and spending limits; if search is unavailable, explain the actual error and then ask for a link. Verify the merchant, item and variant from the result; ask only when matches are ambiguous or details cannot be verified. Never invent a product URL, final total or delivery date from a search snippet. THE SEAMLESS PATH: once the user has told you what to buy and you have the exact item, merchant page URL and total, call `purchase` { item, merchant, url, total_cents, confirmed: true, confirmation: <the user's own words> } — it approves from their message (under the chat limit), starts buying in the user's cloud browser in the background and returns `message` ("Hold on — buying it now."): RELAY IT, then poll `status` { approval_id } every ~10 seconds and relay its `message` when the status is completed ("Done — …"), requires_action (read action_required.reason for the exact blocker) or failed. If `status` says the user's shipping address is missing, ask for it and call `address` { name, line1, line2?, city, state?, postal_code, country, phone? } then `checkout` { approval_id } to resume; if merchant authentication is pending, relay handoff_url and handoff_deadline. The durable worker checks authentication and resumes the same authorized purchase automatically. Do not ask the user to send done or submit codes in chat. If the handoff expires, relay the recovery page; it does not clear order or payment uncertainty. Other sub-commands: `search` { query } (protocol merchants plus a real web search; the web half bills 5¢), `propose` { item, merchant, total_cents, url?, notes?, confirmed?, confirmation? } (creates an approval; without `confirmed` it returns an approval link the user opens — show its `message` VERBATIM), `checkout` { approval_id, params? } (buys an approved purchase; for a browser merchant it runs in the background like `purchase`). Use the user's existing authorization of the exact item and total; do not ask them to confirm twice. Ask only for missing purchase details. Nothing is ever bought without the user's yes: `checkout` refuses anything else. Use `reconcile` { approval_id } after an uncertain submission: it only inspects the existing checkout and never submits payment. For an unavailable checkout or inconclusive reconciliation, relay recovery_url and recovery_instructions from status. The user can resolve the attempt on its approval page only after checking both merchant orders and payment records. A chat statement alone does not clear the lock, and expiration does not clear it. If status or replay says purchase_resolved, never reuse checkout on that approval. When the user requests another attempt, call propose with retry_of set to that resolved ID, current item/price and no confirmed flag, then show the new approval link. Check setup browser_allowance first; a daily_browser_limit requires waiting until resets_at, not reconnecting or changing request text. For a handoff, return action_required.url and the deadline. The user fixes 2FA, CAPTCHA, payment, address or booking issues on that authenticated page and uses Return control to Vaaya; do not call checkout to bypass a pending handoff. Status polling never creates a replacement. Resume on

Parameters26

command	string	required	Use `search` to find an item with OneSearch, `purchase` to buy an authorized item, and `status` to track it.
query	string	optional	Describe the product, variant, budget and preferred store if any. `search` uses OneSearch to find matching items and merchant pages (5¢).
item	string	optional	What exactly is being bought, in the user's words — variant, size, quantity (`purchase`, `propose`).
merchant	string	optional	Merchant host or URL, e.g. bombas.com (`purchase`, `propose`, `credentials`).
retry_of	string	optional	For propose only: the previous approval ID resolved by the owner as no order/payment. Use only when the user requests a new attempt; omit confirmed and show the fresh approval link. Never vary item text or confirmation to bypass replay or locks.
store_connection_id	string	optional	Merchant account connection ID from /store-connections. Required when multiple accounts are connected to the same store. Sign in and enter verification codes directly on that page, never in chat.
booking	any	optional	Required for Expedia flights and Booking.com hotels: exact itinerary/stay, counts, fare/room, baggage/cancellation and payment terms. These are shown for approval and cannot be substituted. Traveler identity documents are entered directly on the merchant page, never in chat. Final booking review requires the authenticated handoff page.
total_cents	number	optional	The full total the user will pay, in cents (`purchase`, `propose`).
currency	string	optional	ISO currency, default 'usd'.
url	string	optional	The exact product page the item came from — the driver starts there (`purchase`, `propose`).
notes	string	optional	One line for the driver/user: variant, size, colour, quantity, delivery window.
confirmed	boolean	optional	true when the user has said yes to this exact item and total in the conversation (`purchase`, `propose`).
confirmation	string	optional	The user's own words approving it, verbatim (`purchase`, `propose`).
approval_id	string	optional	The approval returned by purchase/propose (`status`, `checkout`).
params	object	optional	The merchant's own purchase body (product id, quantity, email, shipping) for a protocol merchant (`purchase`, `checkout`).
name	string	optional	Full name for shipping (`address`).
line1	string	optional	Street address (`address`).
line2	string	optional	Apartment / unit (`address`).
city	string	optional	City (`address`).
state	string	optional	State / region (`address`).
postal_code	string	optional	Postal / ZIP code (`address`).
country	string	optional	Two-letter country code, e.g. US (`address`).
phone	string	optional	Contact phone for delivery (`address`).
email	string	optional	Contact email for the order; defaults to the account email (`address`).
username	string	optional	Email/username at the merchant (`credentials`).
password	string	optional	Password at the merchant — stored encrypted, never returned (`credentials`).

Raw schema

{
  "type": "object",
  "properties": {
    "command": {
      "type": "string",
      "enum": [
        "setup",
        "search",
        "purchase",
        "propose",
        "status",
        "checkout",
        "reconcile",
        "address",
        "credentials"
      ],
      "description": "Use `search` to find an item with OneSearch, `purchase` to buy an authorized item, and `status` to track it."
    },
    "query": {
      "type": "string",
      "description": "Describe the product, variant, budget and preferred store if any. `search` uses OneSearch to find matching items and merchant pages (5¢)."
    },
    "item": {
      "type": "string",
      "description": "What exactly is being bought, in the user's words — variant, size, quantity (`purchase`, `propose`)."
    },
    "merchant": {
      "type": "string",
      "description": "Merchant host or URL, e.g. bombas.com (`purchase`, `propose`, `credentials`)."
    },
    "retry_of": {
      "type": "string",
      "format": "uuid",
      "description": "For propose only: the previous approval ID resolved by the owner as no order/payment. Use only when the user requests a new attempt; omit confirmed and show the fresh approval link. Never vary item text or confirmation to bypass replay or locks."
    },
    "store_connection_id": {
      "type": "string",
      "description": "Merchant account connection ID from /store-connections. Required when multiple accounts are connected to the same store. Sign in and enter verification codes directly on that page, never in chat."
    },
    "booking": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "flight"
            },
            "travelers": {
              "type": "integer",
              "minimum": 1,
              "maximum": 9
            },
            "segments": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$"
                  },
                  "destination": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$"
                  },
                  "departureDate": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  },
                  "departureTime": {
                    "type": "string",
                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
                  },
                  "flightNumber": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 500
                  },
                  "cabin": {
                    "$ref": "#/anyOf/0/properties/segments/items/properties/flightNumber"
                  },
                  "fare": {
                    "$ref": "#/anyOf/0/properties/segments/items/properties/flightNumber"
                  }
                },
                "required": [
                  "origin",
                  "destination",
                  "departureDate",
                  "departureTime",
                  "flightNumber",
                  "cabin",
                  "fare"
                ],
                "additionalProperties": false
              },
              "minItems": 1,
              "maxItems": 8
            },
            "baggage": {
              "$ref": "#/anyOf/0/properties/segments/items/properties/flightNumber"
            },
            "changeCancellationTerms": {
              "$ref": "#/anyOf/0/properties/segments/items/properties/flightNumber"
            }
          },
          "required": [
            "kind",
            "travelers",
            "segments",
            "baggage",
            "changeCancellationTerms"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "hotel"
            },
            "property": {
              "$ref": "#/anyOf/0/properties/segments/items/properties/flightNumber"
            },
            "address": {
              "$ref": "#/anyOf/0/properties/segments/items/properties/flightNumber"
            },
            "checkIn": {
              "$ref": "#/anyOf/0/properties/segments/items/properties/departureDate"
            },
            "checkOut": {
              "$ref": "#/anyOf/0/properties/segments/items/properties/departureDate"
            },
            "rooms": {
              "type": "integer",
              "minimum": 1,
              "maximum": 9
            },
            "adults": {
              "type": "integer",
              "minimum": 1,
              "maximum": 30
            },
            "children": {
              "type": "integer",
              "minimum": 0,
              "maximum": 30
            },
            "roomType": {
              "$ref": "#/anyOf/0/properties/segments/items/properties/flightNumber"
            },
            "ratePlan": {
              "$ref": "#/anyOf/0/properties/segments/items/properties/flightNumber"
            },
            "cancellationTerms": {
              "$ref": "#/anyOf/0/properties/segments/items/properties/flightNumber"
            },
            "paymentTiming": {
              "type": "string",
              "enum": [
                "pay_now",
                "pay_at_property",
                "deposit"
              ]
            },
            "mandatoryFeesCents": {
              "type": "integer",
              "minimum": 0
            }
          },
          "required": [
            "kind",
            "property",
            "address",
            "checkIn",
            "checkOut",
            "rooms",
            "adults",
            "children",
            "roomType",
            "ratePlan",
            "cancellationTerms",
            "paymentTiming",
            "mandatoryFeesCents"
          ],
          "additionalProperties": false
        }
      ],
      "$schema": "http://json-schema.org/draft-07/schema#",
      "description": "Required for Expedia flights and Booking.com hotels: exact itinerary/stay, counts, fare/room, baggage/cancellation and payment terms. These are shown for approval and cannot be substituted. Traveler identity documents are entered directly on the merchant page, never in chat. Final booking review requires the authenticated handoff page."
    },
    "total_cents": {
      "type": "number",
      "description": "The full total the user will pay, in cents (`purchase`, `propose`)."
    },
    "currency": {
      "type": "string",
      "description": "ISO currency, default 'usd'."
    },
    "url": {
      "type": "string",
      "description": "The exact product page the item came from — the driver starts there (`purchase`, `propose`)."
    },
    "notes": {
      "type": "string",
      "description": "One line for the driver/user: variant, size, colour, quantity, delivery window."
    },
    "confirmed": {
      "type": "boolean",
      "description": "true when the user has said yes to this exact item and total in the conversation (`purchase`, `propose`)."
    },
    "confirmation": {
      "type": "string",
      "description": "The user's own words approving it, verbatim (`purchase`, `propose`)."
    },
    "approval_id": {
      "type": "string",
      "description": "The approval returned by purchase/propose (`status`, `checkout`)."
    },
    "params": {
      "type": "object",
      "description": "The merchant's own purchase body (product id, quantity, email, shipping) for a protocol merchant (`purchase`, `checkout`).",
      "additionalProperties": true
    },
    "name": {
      "type": "string",
      "description": "Full name for shipping (`address`)."
    },
    "line1": {
      "type": "string",
      "description": "Street address (`address`)."
    },
    "line2": {
      "type": "string",
      "description": "Apartment / unit (`address`)."
    },
    "city": {
      "type": "string",
      "description": "City (`address`)."
    },
    "state": {
      "type": "string",
      "description": "State / region (`address`)."
    },
    "postal_code": {
      "type": "string",
      "description": "Postal / ZIP code (`address`)."
    },
    "country": {
      "type": "string",
      "description": "Two-letter country code, e.g. US (`address`)."
    },
    "phone": {
      "type": "string",
      "description": "Contact phone for delivery (`address`)."
    },
    "email": {
      "type": "string",
      "description": "Contact email for the order; defaults to the account email (`address`)."
    },
    "username": {
      "type": "string",
      "description": "Email/username at the merchant (`credentials`)."
    },
    "password": {
      "type": "string",
      "description": "Password at the merchant — stored encrypted, never returned (`credentials`)."
    }
  },
  "required": [
    "command"
  ]
}

session

Run a command or code in an open E2B sandbox session (started by `use` with action `create_session`, which returns a `session_id`). Pass `session_id` plus either `command` (a shell command) or `code` (+ optional `language`: python/javascript/bash). Returns stdout/stderr/exit_code (or the code result). The sandbox stays alive — and billed per second of uptime — until you `close` it; re-running reuses the SAME box, so filesystem + process state persist between calls. ALWAYS `close` when done.

Parameters4

session_id	string	required	The session_id returned by create_session.
command	string	optional	Shell command to run in the sandbox.
code	string	optional	Code to execute (alternative to `command`).
language	string	optional	Language for `code`: python (default), javascript, or bash.

Raw schema

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "description": "The session_id returned by create_session."
    },
    "command": {
      "type": "string",
      "description": "Shell command to run in the sandbox."
    },
    "code": {
      "type": "string",
      "description": "Code to execute (alternative to `command`)."
    },
    "language": {
      "type": "string",
      "description": "Language for `code`: python (default), javascript, or bash."
    }
  },
  "required": [
    "session_id"
  ]
}

close

Close an E2B sandbox session and stop its billing. Pass the `session_id`. Captures the final metered uptime cost and releases the hold. ALWAYS call this when finished with a session — an open session keeps billing per second of uptime. Safe to call repeatedly (idempotent).

Parameters1

session_id

string

required

The session_id to close.

Raw schema

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "description": "The session_id to close."
    }
  },
  "required": [
    "session_id"
  ]
}

llm

Ask a DIFFERENT LLM a question and get its answer, billed per token from the Vaaya wallet (model cost + 3%, usually a fraction of a cent). Use it to get a second opinion from a rival model, cross-check an answer, summarize a huge blob cheaply, or query a specific model the user names (Kimi, GPT, Gemini, Claude, DeepSeek, and 300+ more). `model` accepts 'auto' (default: short prompts go cheap, long go mid), 'cheap' | 'mid' | 'best' tiers, or any exact OpenRouter slug like 'moonshotai/kimi-k3'. Typical costs: cheap tier well under 0.1 cents, best tier 1-3 cents per call. Not for the conversation you are already having — it is a one-shot ask to another model.

Parameters4

prompt	string	required	The question or task for the other model.
model	string	optional	'auto' (default), 'cheap', 'mid', 'best', or an exact OpenRouter model slug (e.g. 'moonshotai/kimi-k3', 'anthropic/claude-opus-5').
system	string	optional	Optional system prompt for the other model.
max_tokens	number	optional	Optional cap on the response length in tokens (default 4096, max 16384).

Raw schema

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "The question or task for the other model."
    },
    "model": {
      "type": "string",
      "description": "'auto' (default), 'cheap', 'mid', 'best', or an exact OpenRouter model slug (e.g. 'moonshotai/kimi-k3', 'anthropic/claude-opus-5')."
    },
    "system": {
      "type": "string",
      "description": "Optional system prompt for the other model."
    },
    "max_tokens": {
      "type": "number",
      "description": "Optional cap on the response length in tokens (default 4096, max 16384)."
    }
  },
  "required": [
    "prompt"
  ]
}

README.md10 KBView on GitHub

Vaaya

Vaaya MCP — payments for any agent

MCP server for AI agent payments. An agent in Cursor, Claude Code, Claude Desktop, Codex, or any MCP host can call paid APIs (search, scraping, contact data, public records, compute, media, research) from one balance, with a spend ceiling it states on every call, and no vendor keys anywhere in its environment. Billed only on success (x402 USDC on Base, Stripe MPP, or Tempo); a refused or failed call costs nothing.

bash

npx @vaaya/mcp install            # Cursor, Claude Code, Claude Desktop, Codex
claude mcp add --transport http vaaya https://vaaya.ai/mcp

First paid call: consult returns a priced plan; use({ service, action, params, max_cost_cents }) runs one line of it. If the quoted price is above max_cost_cents, the call is refused before it reaches the provider and the reason comes back:

json

{ "error": "over_max", "message": "price is 5¢ but max_cost_cents was 1", "price_cents": 5 }

Runnable examples: examples/pay-for-an-api (one call allowed, one refused), examples/cursor, examples/claude. Guides: give an agent a budget, Cursor setup, Claude setup, what is an AI agent wallet.

Buy tokenized shares — including with Instinct

Agents can buy supported tokenized stocks on Base with Vaaya prepaid funds. These are tokenized stocks, not direct brokerage shares. Discover the current supported tickers with stocks({ command: "list" }) (for example Apple AAPLc and NVIDIA NVDAc), then check stocks({ command: "portfolio" }) for buyingPowerCents. Welcome grants and credit lines cannot buy shares.

For a user-authorized $10 Apple purchase:

json

{ "command": "buy", "symbol": "AAPLc", "amount_cents": 1000, "idempotency_key": "<unique purchase key>" }

Call the dedicated stocks MCP tool with this input; it is separate from consult/use. The amount is the maximum total prepaid spend including fees. Save the returned id, then poll stocks({ command: "order", order_id: "<id>" }). Only confirmed means purchased. Stop on failed or needs_review; reuse the same purchase key on uncertain retries, never place a new order to check status.

Insufficient prepaid balance? With the user's authorization for a $10, $30, or $100 pack, POST https://vaaya.ai/api/v1/topup with JSON { "pack_cents": 1000 } (or 3000 / 10000) using the same account's bearer token. An Instinct agent with access to the user's saved card can pay the returned Stripe Checkout url in its own browser when authorized for that pack amount. For a handoff, provide the URL and authorized amount to the user's Instinct agent; otherwise give the URL to the user. Keep card details and bearer tokens out of the handoff. Vaaya cannot charge a card stored in Instinct directly. A share purchase alone does not authorize an extra card charge.

Poll GET /api/v1/wallet (wallet.prepaid_cents), then recheck stock buying power before resuming the original purchase key. Do not pay again while a payment's outcome is uncertain. Stock availability and account permissions apply.

Full MCP and REST purchase guide · Complete tool reference

What your agent can do through Vaaya

Capability	What you get
🎨 Media generation	Images & video with top models — Nano Banana Pro 2, GPT Image 2, Seedream v4.5, Kling v3, Seedance 2.0 — plus TTS voices & music
🎬 Product demo videos	Record a raw, silent screen capture of your live product; Vaaya auto-authors narration + zoom/cut plan and renders a finished narrated demo
🖼️ Website imagery	Derive a site's brand and generate an on-brand image set straight into your repo
🔎 Web search	Exa & Parallel: query search, URL contents, async deep research tasks
🕷️ Web scraping	Firecrawl scrape / crawl / map / search / extract, persisted to files
📚 Deep research	Multi-hop, source-verified, cited research reports
📊 Market & competitive research	Company reports (people, hiring, ads, reviews, SEO/LLM visibility), product & feature catalogs with review sentiment, UX research with interactive product maps, "best X for my data" bake-offs, persistent competitive knowledge repos
🎯 GTM & sales	Find ICP-matched leads with verified contacts, enrich contacts, track buying signals (funding/hiring/launch/press), 24×7 LinkedIn discovery, segment-based outbound email — every draft held for human approval
⏰ Monitoring workers	Scheduled watches (30 min–weekly) over competitor pricing, deals, reviews, job postings, news — only new/changed findings surface
🖥️ Compute sandboxes	Per-second-billed code execution (Modal) for benchmarks, untrusted code, GPU inference, data jobs
🌐 Browser automation	Browserbase sessions to click, type, log in, fill forms
📧 Email	AgentMail inboxes your agent owns — send and receive replies
🧠 Memory	Persistent cross-session memory via mem0, Zep, or Letta

Install

One command (recommended)

bash

npx @vaaya/mcp install

(npx vaaya-cli install runs the same installer.)

Sets up the Vaaya MCP server for every agent it detects on your machine — Claude Code, Claude Desktop, Cursor, Codex — plus the agent skill. Idempotent: re-run any time to update. Then restart your agent; the first Vaaya call opens a short browser approval (sign-up happens right there).

Remote (Streamable HTTP + OAuth)

json

{ "mcpServers": { "vaaya": { "url": "https://vaaya.ai/mcp" } } }

Claude Code:

bash

claude mcp add --transport http vaaya https://vaaya.ai/mcp

OpenClaw:

bash

openclaw mcp add vaaya --url https://vaaya.ai/mcp --transport streamable-http --auth oauth
openclaw mcp login vaaya

Hermes (~/.hermes/config.yaml):

yaml

mcp_servers:
  vaaya:
    url: "https://vaaya.ai/mcp"
    auth: oauth

On first use your client runs the OAuth flow in the browser; approve and you're connected. Revoke anytime at vaaya.ai/connected-apps.

npm stdio shim (for stdio-only clients: opencode, …)

json

{ "mcpServers": { "vaaya": { "command": "npx", "args": ["-y", "@vaaya/mcp"] } } }

The shim (@vaaya/mcp) opens the OAuth flow on first call, stores a refresh token locally (0o600), and proxies the live tool list from the backend — new server-side tools appear without a shim upgrade. It also ships an agent skill so your client routes every capability gap through consult automatically.

Agent skill (works across 70+ agents)

bash

npx skills add vaaya-ai/vaaya-mcp

Installs the vaaya skill for Claude Code, Codex, Cursor, Gemini CLI, Copilot, and any other client that supports the open Agent Skills standard. The skill bootstraps the Vaaya MCP server if it's missing and keeps the install updated.

As a plugin

Claude Code: /plugin marketplace add vaaya-ai/vaaya-mcp then /plugin install vaaya@vaaya — bundles the remote MCP server, the vaaya skill, and the SessionStart reminder hook
Codex: codex plugin marketplace add vaaya-ai/vaaya-mcp then install vaaya from the Plugins panel
Gemini CLI: gemini extensions install https://github.com/vaaya-ai/vaaya-mcp

How it works

consult(intent) — describe any goal in plain English ("generate a hero video", "find 50 heads of RevOps with verified emails", "watch my competitor's pricing page"). It converses, clarifies, and returns the exact call(s) to run.
use(service, action, params, max_cost_cents) — execute the call. Billed on success; max_cost_cents is a hard spend ceiling. Long jobs return { async: true, job_id } — poll with result(job_id).
session / close — per-second-billed code sandbox sessions.

Plus a full GTM suite (gtm_leads_find, gtm_lead_enrich, gtm_signal_create, gtm_segments, gtm_message, gtm_replies, …) and scheduled monitoring workers (worker_create, worker_findings, …) — the tool list is proxied live from the backend.

Example prompts

"Generate a hero video for our landing page in 16:9."
"Record my product and turn it into a narrated demo video."
"Find 50 heads of RevOps at Series-B SaaS companies with verified emails."
"Watch my competitor's pricing page and tell me when it changes."
"Do deep research on the agentic payments market with cited sources."
"Scrape these 200 product pages into structured JSON."
"Run this benchmark in a GPU sandbox."

CLI

The vaaya-cli CLI manages everything from the terminal:

bash

npx vaaya-cli install        # set up the MCP server for every detected agent
npx vaaya-cli status         # connection state + live tool count
npx vaaya-cli consult "..."  # ask Vaaya how it would do something (returns the plan)
npx vaaya-cli reauthorize    # re-run the browser auth flow
npx vaaya-cli logout         # disconnect & delete local credentials

Security & billing

Your agent never sees vendor API keys or upstream URLs — Vaaya proxies every call server-side.
OAuth 2.1 (PKCE, dynamic client registration); anonymous tools/list for discovery; revocable grants.
Pay-per-call on x402 (USDC on Base), Stripe MPP/SPT, or Tempo. Failed calls are never charged. Every call carries a max_cost_cents guard.

Install

Tools (13)

stocksvaaya_test_connectionvaaya_onboardvaaya_accountvaaya_logoutdocsconsultuse

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@vaaya/mcp@0.6.8"
      ]
    }
  }
}

Vaaya

Vaaya MCP (ai.vaaya/mcp)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

Topics

stocks

vaaya_test_connection

vaaya_onboard

vaaya_account

vaaya_logout

docs

consult

use

result

buy

session

close

llm

Vaaya MCP — payments for any agent

Buy tokenized shares — including with Instinct

What your agent can do through Vaaya

Install

One command (recommended)

Remote (Streamable HTTP + OAuth)

npm stdio shim (for stdio-only clients: opencode, …)

Agent skill (works across 70+ agents)

As a plugin

How it works

Example prompts

CLI

Security & billing

Links

Install

Related servers