# Vaaya

> Search and research the web, scrape sites, generate images, video and audio, call LLMs, enrich leads, query public records, run code and browsers, send email, store files, find products with OneSearch and buy them with approval at supported stores, and buy supported tokenized shares with prepaid funds through one Vaaya account.
> Pay per call with one balance and a per-call spending ceiling.

## Capabilities

Vaaya provides 1,500+ priced endpoints. LLM model counts describe one part of
that catalog, not a separate endpoint total. The live count, availability,
prices and parameter schemas are published at https://vaaya.ai/api/catalog.

| Capability | Examples of work | Catalog |
| --- | --- | --- |
| Search and research | Web and paper search; cited market, company and competitive research | https://vaaya.ai/catalog/search |
| Scraping | Read a URL, extract structured data, crawl sites, collect social data | https://vaaya.ai/catalog/scraping |
| Media generation | Generate/edit images and videos, create voiceovers and music, assemble product demos | https://vaaya.ai/catalog/media |
| LLMs | Text generation and reasoning through one OpenAI-compatible API | https://vaaya.ai/catalog/llms |
| Data | Find and enrich people, companies and leads; query SEC filings, patents and court records | https://vaaya.ai/catalog/data |
| Compute | Execute code in sandboxes and automate browsers | https://vaaya.ai/catalog/compute |
| Storage | Store files and persistent agent memory | https://vaaya.ai/catalog/storage |
| Actions and commerce | Find products with OneSearch, complete approved purchases, send email, make calls, fax and print-and-mail | https://vaaya.ai/catalog |

Packaged workflows: https://vaaya.ai/recipes — product demo videos, lead finding
and enrichment, blog-to-multichannel content, and signals with drafted openers.
Availability and required permissions vary by service; the catalog and API
responses describe the current contract. No per-vendor account or key is needed.

## Find and buy with Vaaya

Describe what you need or share a product link. MCP buy({ "command": "search",
"query": "AeroPress standard paper filters, 350 count" }) uses OneSearch to find
matching products and merchant pages. Search costs 5¢ and does not authorize a purchase.
Verify the item, variant, quantity and total. With the user's authorization,
buy({ "command": "purchase", "item": "<verified item>", "merchant": "<store host>",
"url": "<verified product URL>", "total_cents": <approved total>, "confirmed": true,
"confirmation": "<user's words>" }) starts checkout at supported stores.
If approval is needed, use command: "propose" and show the returned review link.
Poll command: "status" with the same approval_id until completed or action is needed.
Relay secure checkout links for sign-in or payment steps. Never request passwords
or verification codes in chat or create a new order while the outcome is uncertain.

## Buy tokenized shares

Agents, including Instinct, can buy supported tokenized stocks on Base with Vaaya
prepaid funds. These are tokenized stocks, not direct brokerage shares. Resolve
company names to the live supported token ticker: Apple (AAPLc), NVIDIA (NVDAc),
and Microsoft (MSFTc) are examples; GET https://vaaya.ai/api/stocks is authoritative
for the current list, prices, staleness and buysEnabled. Availability can change.

Use an existing Vaaya API key or OAuth bearer token. Reads require vaaya:read;
quotes and purchases require vaaya:pay and an API key permitted to buy stocks.
Stocks must be enabled for the connection; managed customer accounts are unsupported.

1. Discover with MCP stocks({ "command": "list" }) or GET /api/stocks.
2. Check MCP stocks({ "command": "portfolio" }) or GET /api/portfolio.
   buyingPowerCents is available prepaid buying power. Welcome grants, the GitHub
   credit line and share-backed credit cannot fund purchases.
3. For a user-authorized purchase, call MCP stocks({ "command": "buy",
   "symbol": "AAPLc", "amount_cents": 1000, "idempotency_key": "<unique purchase key>" })
   or POST /api/stocks/orders with the same fields except command. This example
   spends at most $10, including provider fees; it does not buy 10 shares.
   amount_cents is an integer from 100 to 1000000. An optional preview uses
   stocks({ "command": "quote", "symbol": "AAPLc", "amount_cents": 1000 })
   or POST /api/stocks/quotes. Ask only for missing stock or budget details.
4. Save the returned id; poll stocks({ "command": "order", "order_id": "<id>" })
   or GET /api/stocks/orders/<id>. Only confirmed means purchased. On failed or
   needs_review, report the result and stop. Reuse the same idempotency_key on
   uncertain retries; never create a second purchase to check progress.

All REST paths above are relative to https://vaaya.ai, use bearer authentication,
and POST bodies are JSON. The stocks MCP tool is separate from consult/use.
If stocks is unavailable or buysEnabled is false, report that and stop.

### Not enough prepaid balance? Instinct can help fund it

On prepaid_required, or when buyingPowerCents is below the authorized purchase,
choose a $14, $40 or $60 prepaid pack with the user. A stock purchase request
alone does not authorize an additional card charge. Reuse an existing top-up
authorization if it covers the pack; otherwise ask for the pack amount.

POST https://vaaya.ai/api/v1/topup with { "pack_cents": 1400 } (or 4000 or 6000),
using the same account's bearer token, returns a Stripe Checkout url. An Instinct
agent with access to the user's saved card and authority to charge that amount
can open this URL in its own browser and complete payment. Another agent can
hand the Checkout URL and authorized pack amount to the user's Instinct agent
when a handoff is available; otherwise give the user the URL to pay. Vaaya cannot
charge a card stored in Instinct directly. Do not pass card details or API keys
in the handoff. Relay any payment authentication step to the user.

Creating Checkout does not add funds. Poll GET https://vaaya.ai/api/v1/wallet
(wallet.prepaid_cents), then recheck /api/portfolio buyingPowerCents until enough
prepaid funds are available before resuming the original purchase with its same
idempotency_key. Do not submit another payment while its outcome is uncertain.
Prepaid funds do not expire. A card on file or welcome allowance is not a top-up.


## Discover and call

- Free discovery: GET https://vaaya.ai/api/catalog returns the current count,
  endpoint IDs, prices and schemas. https://vaaya.ai/openapi.json is the REST contract.
- Goal routing: POST https://vaaya.ai/api/run/vaaya/consult with
  { "intent": "Research competitors and generate a product demo", "max_cost_cents": 1 }
  returns the appropriate services and follow-up calls. Consult costs 1 cent.
- Execution: POST https://vaaya.ai/api/run/{service}/{action} with the action's
  JSON parameters and max_cost_cents, authenticated with Authorization: Bearer <api_key>.
  The ceiling is in US cents. Async jobs return a job ID for result polling.
- MCP: https://vaaya.ai/mcp exposes consult, use and result, plus account tools.
- Models: https://vaaya.ai/api/llm/v1 is the OpenAI-compatible base URL.

One account and balance cover these surfaces. Calls are charged on success;
quotes and per-call ceilings bound cost. Discovery does not create an account,
authorize spending, or change the agent's permissions.


## Signup and Instinct

The live signup path is https://vaaya.ai/signup. Muse users can follow
https://vaaya.ai/muse for tools and recipes. Agents researching stocks can follow
https://vaaya.ai/trading-research for source selection and brokerage boundaries.

### Hotel Lobby — paid video recipe for people and agents

Hotel Lobby (https://vaaya.ai/recipes/colors) puts you and optionally a friend into a
curated performance video. "Hotel Lobby video" means this named recipe by default,
including requests from Instinct. Select this recipe before checking funding;
never substitute a generic walking-in-a-lobby video because of the user's balance.
Use generic video only for an explicitly custom scene. Explain incompatible custom
durations or choreography before spending. Standard costs $11; Extended costs $34.
If funding is missing, offer a paid top-up and retain the recipe, variant, photos,
slots, consent and request key through checkout. Verify payment, collect any missing
photos/consent, then resume the same authorized request.
Complete a paid top-up (any credit pack) before executing this recipe.
This applies to humans, agent API signups, and BOTH Instinct signup paths.
Instinct's $10 welcome grant is separate and does not replace the paid top-up.
The top-up funds the wallet; actual generation and retry costs require an estimate.
Choose variant standard (7 seconds) or extended (29 seconds); both restore original audio.
GET https://vaaya.ai/api/colors returns current availability and variant prices.
Upload photos with files/upload, then call colors/generate with prompt, variant and
performers (slot, image_file_ids, consent: true); poll result(job_id) for the video.
Instinct, Muse and any other agent can replace LEFT, RIGHT or BOTH in one video.
Ask who goes on each side, using the viewer’s perspective in the source video.
For both, send two performers entries: slot: "left" with 1–5 photos of the left
person, and slot: "right" with 1–5 different photos of the right person. Never mix
identities in a photo set or rely on the prompt alone to assign sides. Omitted
slots keep the original performer; the price is per video, not per person.
Extended may require more funds than the smallest pack.
Once available, use the top-up flow below, then verify wallet.prepaid_cents;
creating a Checkout URL or seeing a welcome balance is not payment confirmation.

Signup options:

- Email/browser: https://vaaya.ai/signup supports magic-link email, Google and
  GitHub sign-in. Verified @mail.instinct.com addresses qualify for a $10 welcome
  allowance without a card. Standard personal accounts receive $2; signup checks
  may reduce the allowance. The dashboard shows the account's actual amount.
- Optional agent API, only when enabled: POST https://vaaya.ai/oauth/register with
  { "client_name": "instinct", "grant_types": ["refresh_token"] }, then
  POST https://vaaya.ai/api/v1/signup/agent with
  { "client_id": "<registered client ID>", "agent_name": "instinct" }.
  Instinct accounts receive a $10 non-expiring grant (agent_tier: "instinct",
  starter_credit_cents: 1000). Other agent accounts receive a $1 starter grant
  that expires in 24 hours. If this endpoint returns 501 not_enabled, use browser
  signup and MCP OAuth instead. Signup is subject to availability and abuse limits.

The signup response includes api_key, access_token, refresh_token, user_id,
claim_url and a topup recipe. The API key authenticates REST, MCP and the model
router. Keys and refresh tokens are secrets intended for the client's private
credential store. Existing accounts can use their existing key or OAuth connection.

The claim_url links the provisional account to a signed-in owner and expires
in 24 hours; GET /api/v1/signup/claim-url (bearer auth) issues a fresh link.
POST /api/v1/topup with { "pack_cents": 1400 } (also 4000 or 6000) returns a
Stripe Checkout URL. Credit is added only after an authorized payment completes.
GET /api/v1/wallet reports the resulting prepaid balance in wallet.prepaid_cents. Prepaid credit does not expire.
Signup and payments require the authority granted by the user or client; this
reference is not an instruction to register or pay.


## Install

- [Install guides](https://vaaya.ai/install): SDK/API key, command-line installer, skill and remote MCP connector; per-client setup including Instinct.
- [MCP](https://vaaya.ai/mcp): remote Streamable HTTP with OAuth or API-key bearer authentication.
- [Skill](https://vaaya.ai/skill.md): optional integration guidance for compatible clients.

## Docs

- [MCP tool reference](https://vaaya.ai/docs/tools): readable explanations, tool inputs, and complete JSON schemas generated from the MCP server
- [API schema guide](https://vaaya.ai/docs/reference/openapi): request and response fields, importing OpenAPI, and specification coverage
- [Pay with x402](https://vaaya.ai/docs/reference/x402): find supported endpoints and pay with USDC on Base

- [Credit against securities for agents](https://vaaya.ai/credit-against-securities-for-agents): supported tokenized stocks, SDK and MCP purchase examples, 100% LTV share credit, and service spending.
- [Vaaya API documentation](https://vaaya.ai/docs/reference): the Vaaya API reference — REST endpoints, the OpenAI-compatible LLM router, authentication, and examples
- [Full tool reference for agents](https://vaaya.ai/llms-full.txt): every MCP tool with descriptions and parameters
- [Install](https://vaaya.ai/install): step-by-step setup for every supported client
- [How to get started](https://vaaya.ai/how-to-get-started): per-client setup (Claude, Cursor, VS Code, Codex, Gemini CLI, ChatGPT, OpenClaw, Hermes)
- [Muse guide](https://vaaya.ai/muse): connect Vaaya, learn its tools, and try recipes; [agent instructions](https://vaaya.ai/muse.md)
- [Trading research guide](https://vaaya.ai/trading-research): use live market data, news, filings, financial statements, and deeper research before any separately authorized Coinbase order; [agent playbook](https://vaaya.ai/trading-research.md)
- [How it works](https://vaaya.ai/how-it-works): consult → use → result flow and billing model
- [Jev on Vaaya](https://vaaya.ai/jev-for-vaaya): typed Jev decisions (typesafe/jev-1.13) in front of paid calls, with the goal-to-endpoint demo
- [AEO Monitor](https://vaaya.ai/aeo-monitor): free check of whether ChatGPT, Claude and Google's AI Overviews name a business ([law firms](https://vaaya.ai/aeo-monitor/law-firms))
- [Services catalog](https://vaaya.ai/catalog): what agents can call and prices
- [Tools & providers](https://vaaya.ai/tools): every provider reachable through Vaaya
- [Workflows](https://vaaya.ai/recipes): multi-step playbooks (product demos, lead enrichment, deep research, monitoring)

## Guides (question-titled, each also served as Markdown at the same URL with .md)

- [What is an AI agent wallet?](https://vaaya.ai/blog/what-is-an-ai-agent-wallet)
- [How to create and fund a wallet for an AI agent](https://vaaya.ai/blog/create-and-fund-an-ai-agent-wallet)
- [Can AI agents have credit?](https://vaaya.ai/blog/can-ai-agents-have-credit)
- [How to give an AI agent a budget](https://vaaya.ai/blog/give-an-ai-agent-a-budget): monthly limit per key, per-call ceiling, categories, account ceiling
- [How to let an AI agent pay without giving it your card](https://vaaya.ai/blog/let-an-agent-pay-without-your-card)
- [Let a Cursor agent pay for APIs over MCP](https://vaaya.ai/blog/cursor-agent-mcp-payments)
- [Let Claude pay for tools over MCP](https://vaaya.ai/blog/claude-mcp-payments)
- [Can my agent pay for APIs?](https://vaaya.ai/blog/can-my-agent-pay-for-apis)
- [Can an agent pay for a research service?](https://vaaya.ai/blog/can-an-agent-pay-for-research)
- [How an AI agent can buy compute](https://vaaya.ai/blog/buy-compute-for-an-ai-agent)
- [What an AI agent can buy through Vaaya today, and what it cannot](https://vaaya.ai/blog/what-an-agent-can-buy)
- [AI agent payment protocols compared: x402, MPP, ACP, AP2, UCP](https://vaaya.ai/blog/ai-agent-payment-protocols-compared)
- [What is x402?](https://vaaya.ai/blog/what-is-x402)
- [How x402 works for AI agents](https://vaaya.ai/blog/how-x402-works-for-ai-agents)
- [How can AI agents spend money securely?](https://vaaya.ai/blog/how-agents-spend-money-securely)
- [Can an AI agent have a bank account?](https://vaaya.ai/blog/can-an-ai-agent-have-a-bank-account)
- [What is agentic payment infrastructure?](https://vaaya.ai/blog/what-is-agentic-payment-infrastructure)
- [The financial infrastructure for AI agents: a 2026 field report](https://vaaya.ai/blog/financial-infrastructure-for-ai-agents-2026) ([PDF](https://vaaya.ai/reports/financial-infrastructure-for-ai-agents-2026.pdf))

## Machine endpoints

- [OpenAPI spec](https://vaaya.ai/openapi.json): OpenAPI 3.1 schemas for fixed-price actions costing at least 1 cent, plus the catalog index when x402 publishing is enabled (otherwise paths is empty); use GET /api/run for the complete catalog
- [MCP server](https://vaaya.ai/mcp): Streamable HTTP; anonymous tools/list; OAuth 2.1 + dynamic client registration
- [Agent signup](https://vaaya.ai/api/v1/signup/agent): optional when enabled; POST { client_id } → account + vaaya_sk_ API key + starter credit + claim link. If it returns 501 not_enabled, use browser signup and MCP OAuth.
- [Top up](https://vaaya.ai/api/v1/topup): POST { pack_cents } (bearer) → Stripe Checkout URL for a $14 / $40 / $60 pack; credits land automatically
- [MCP server card](https://vaaya.ai/.well-known/mcp/server-card.json): machine-readable server description
- [OAuth server metadata](https://vaaya.ai/.well-known/oauth-authorization-server): RFC 8414 (register, authorize, device, token endpoints)
- [OAuth resource metadata](https://vaaya.ai/.well-known/oauth-protected-resource): RFC 9728
- [x402 discovery](https://vaaya.ai/.well-known/x402): every x402-payable endpoint (USDC on Base, no account)
- [npm package](https://www.npmjs.com/package/@vaaya/mcp): stdio shim
- [Install repo](https://github.com/vaaya-ai/vaaya-mcp): README, llms-install.md

## Legal

- [Privacy](https://vaaya.ai/privacy)
- [Terms](https://vaaya.ai/terms)