Vaaya: Let your agents pay

Setup guide

Claude Code

Add Vaaya to Claude Code so it can use services while you work in your terminal.

Before you start. Have Claude Code installed and open it at least once. The installer needs Node.js 20 or later.

1
Run the installer
Open Terminal on macOS or a terminal on Linux or Windows. Run this command to add the Vaaya connection and skill to Claude Code.
Terminal
```
npx -y @vaaya/mcp install --only=claude-code
```
2
Connect your Vaaya account
Restart Claude Code, run /mcp, and select vaaya. Follow the authentication prompt to sign in to Vaaya in your browser and approve the connection.
Inside Claude Code
```
/mcp
```
3
Check the connection
Start a new conversation and paste this prompt. Your agent should show your Vaaya balance and the tools it can use.
Try this prompt
```
Use Vaaya to show my balance and available tools. Do not run any paid tools yet.
```

Setup guide

Codex

Connect Vaaya to the Codex CLI or IDE extension. Local Codex clients share the same MCP configuration.

Before you start. Have the Codex CLI installed and run it at least once. The Vaaya installer needs Node.js 20 or later.

1
Install the Vaaya integration
Run this in your terminal. It adds Vaaya to your Codex configuration and installs the instructions Codex uses to work with Vaaya.
Terminal
```
npx -y @vaaya/mcp install --only=codex
```
Sign in to Vaaya
Restart Codex or reload the IDE extension. Ask Codex to connect to Vaaya. Its first Vaaya call provides a browser sign-in link; open it, sign in, and approve access.
3
Check the connection
Start a new conversation and paste this prompt. Your agent should show your Vaaya balance and the tools it can use.
Try this prompt
```
Use Vaaya to show my balance and available tools. Do not run any paid tools yet.
```

Setup guide

Cursor

Make Vaaya available to Cursor Agent in your editor.

Before you start. Have Cursor installed and open it at least once. The installer needs Node.js 20 or later.

1
Run the installer in Cursor’s terminal
Open Terminal → New Terminal in Cursor, then paste this command. It adds Vaaya to your global Cursor configuration and installs the Vaaya skill.
Terminal
```
npx -y @vaaya/mcp install --only=cursor
```
Restart Cursor and sign in
Quit and reopen Cursor. Open its MCP settings and check that vaaya is enabled. Ask Cursor Agent to connect to Vaaya, then open the sign-in link it provides and approve access.
3
Check the connection
Start a new conversation and paste this prompt. Your agent should show your Vaaya balance and the tools it can use.
Try this prompt
```
Use Vaaya to show my balance and available tools. Do not run any paid tools yet.
```

Setup guide

Devin

Connect Devin to Vaaya from your organization’s MCP settings.

Before you start. You need permission to manage MCP servers in your Devin organization.

Get an API key
Sign in to Vaaya and copy your API key from this page. For a shared or unattended agent, create a separate key in API keys and set its monthly spending limit.
Manage API keys
2
Add a custom MCP server
In Devin, open Settings → MCP Marketplace → Add Your Own. Name the server Vaaya, choose HTTP as the transport, and enter this server URL.
Server URL
```
https://vaaya.ai/mcp
```
3
Add authentication and save
Choose Auth Header. Set the header name to Authorization and the value to Bearer followed by a space and your Vaaya API key. Save, then click Test listing tools. Devin should return Vaaya’s tools.
Authentication header
```
Authorization: Bearer YOUR_VAAYA_API_KEY
```
4
Check the connection
Start a new conversation and paste this prompt. Your agent should show your Vaaya balance and the tools it can use.
Try this prompt
```
Use Vaaya to show my balance and available tools. Do not run any paid tools yet.
```

Setup guide

TypeScript / JavaScript

Use the Vaaya client in a Node.js service or an agent application. It handles authentication, spending ceilings, and receipts for you.

Before you start. Use Node.js 20 or later. Run these commands from your project folder. Keep the client and your API key on the server.

Get an API key
Sign in to Vaaya and copy your API key from this page. For a shared or unattended agent, create a separate key in API keys and set its monthly spending limit.
Manage API keys
2
Install the package
Add the SDK to your project. It supports TypeScript, JavaScript, ESM, and CommonJS.
Terminal
```
npm install @vaaya/sdk
```
3
Set your API key
Replace the placeholder with your key. This command works in bash or zsh; in production, add VAAYA_API_KEY to your hosting secrets.
Terminal · bash / zsh
```
export VAAYA_API_KEY='YOUR_VAAYA_API_KEY'
```
4
Check the connection
Save this as quickstart.mjs, then run node quickstart.mjs. It prints your available balance in cents. Reading your balance is free.
quickstart.mjs
```
import { Vaaya } from '@vaaya/sdk'

const vaaya = new Vaaya()
const wallet = await vaaya.wallet()
console.log(wallet.availableCents)
```
5
Create a wallet for each customer
For applications with end users, use managed customer accounts (SDK 0.2.0 and managed customer access required). Call this from your signup handler using the authenticated user’s stable ID. Retrying with the same ID returns the same customer. The wallet starts empty.
Your server · signup handler
```
const customer = await vaaya.customers.ensure({
  externalId: appUser.id,
  budgetCents: 500, // $5 lifetime funding and spending limit
})
await vaaya.customers.waitUntilReady(customer.id)
// Save customer.id alongside your application user.
```
6
Fund their first request
Before the customer’s first paid request, move an amount you choose from your prepaid Vaaya balance into their wallet. This example moves $1. Save a funding operation ID in your database and reuse it on retries. A spending limit alone does not move money.
Your server · explicit funding
```
const funding = await vaaya.customers.fund(customer.id, {
  amountCents: 100,
  idempotencyKey: fundingOperation.id,
})
await vaaya.customers.waitForFunding(customer.id, funding.id)
```
7
Run requests as that customer
Create a customer-scoped client after authenticating the user in your app. It uses a restricted token that lasts one hour. Supported synchronous catalog calls pay from this customer’s wallet. Streaming LLM calls, routed One methods, and background jobs are not supported by managed wallets yet.
Your server · customer request
```
const client = await vaaya.forCustomer(customer.id)
const result = await client.use('exa/search', { query: 'resume writing advice' }, {
  maxCostCents: 5,
  idempotencyKey: requestOperation.id,
})
console.log(result.data, result.chargedCents)
```

Setup guide

Python

Use the Python client in a script, service, or agent. The core client needs no additional runtime packages.

Before you start. Use Python 3.9 or later. These terminal commands use bash or zsh on macOS or Linux; on Windows, use WSL or your usual Python virtual environment.

Get an API key
Sign in to Vaaya and copy your API key from this page. For a shared or unattended agent, create a separate key in API keys and set its monthly spending limit.
Manage API keys
2
Create an environment and install the package
Run these commands from your project folder. A virtual environment keeps the SDK separate from your system Python.
Terminal
```
python3 -m venv .venv
source .venv/bin/activate
python -m pip install vaaya
```
3
Set your API key
Replace the placeholder with your key. In production, add VAAYA_API_KEY to your hosting secrets rather than putting it in your source code.
Terminal · bash / zsh
```
export VAAYA_API_KEY='YOUR_VAAYA_API_KEY'
```
4
Check the connection
Save this as quickstart.py, then run python quickstart.py. It prints your available balance in cents without running a paid service.
quickstart.py
```
from vaaya import Vaaya

vaaya = Vaaya()
wallet = vaaya.wallet()
print(wallet["available_cents"])
```
5
Create a wallet for each customer
Managed customer accounts require SDK 0.2.0 and managed customer access. In your signup handler, use the authenticated user’s stable ID. Repeated calls return the same customer and wallet. The $5 budget below is a limit, not a deposit.
Your server · signup handler
```
customer = vaaya.customers.ensure(app_user.id, budget_cents=500)
vaaya.customers.wait_until_ready(customer["id"])
# Save customer["id"] alongside your application user.
```
6
Fund the wallet before its first paid request
This moves $1 from your prepaid Vaaya balance to the customer’s wallet. Keep funding_operation.id in your database and reuse it if the request times out. Wait for confirmation before spending. Later requests reuse the remaining wallet balance.
Your server · explicit funding
```
funding = vaaya.customers.fund(
    customer["id"], amount_cents=100,
    idempotency_key=funding_operation.id,
)
vaaya.customers.wait_for_funding(customer["id"], funding["id"])
```
7
Run requests as that customer
Use a customer-scoped client for supported synchronous catalog calls. Its credential expires after one hour; create a fresh scoped client when needed. Streaming LLM calls, routed One methods, and background jobs do not yet support managed-wallet settlement.
Your server · customer request
```
client = vaaya.for_customer(customer["id"])
result = client.use(
    "exa/search", {"query": "resume writing advice"},
    max_cost_cents=5, idempotency_key=request_operation.id,
)
print(result["data"], result["charged_cents"])
```

Setup guide

REST API

Use HTTP from any language. These examples use curl on macOS or Linux. On Windows, use WSL or Git Bash.

Before you start. You need a Vaaya account, an API key, and curl.

Get an API key
Sign in to Vaaya and copy your API key from this page. For a shared or unattended agent, create a separate key in API keys and set its monthly spending limit.
Manage API keys
2
Set your API key
Replace YOUR_VAAYA_API_KEY with the key you copied. In a deployed app, save VAAYA_API_KEY in your hosting provider’s environment variables. Keep it on the server.
Terminal · bash / zsh
```
export VAAYA_API_KEY='YOUR_VAAYA_API_KEY'
```
3
Provision a separate customer wallet
For an application with end users, request managed customer access and call this endpoint from your signup handler. Use a stable user ID from your own database. The response includes a customer ID, agent ID, wallet address, and provisioning status; retries reuse the same customer.
Terminal · customer signup
```
curl --fail-with-body https://vaaya.ai/api/v1/customers/ensure \
  -H "Authorization: Bearer $VAAYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"your-user-id","budget_cents":500}'
```
4
Wait for the wallet to be ready
Save the returned customer ID with your application user. Replace YOUR_CUSTOMER_ID below, then check until status is ready. Wallet creation does not move money.
Terminal · wallet status
```
export CUSTOMER_ID='YOUR_CUSTOMER_ID'
curl --fail-with-body "https://vaaya.ai/api/v1/customers/$CUSTOMER_ID" \
  -H "Authorization: Bearer $VAAYA_API_KEY"
```
5
Fund the first paid request
This moves $1 from your prepaid Vaaya balance into this customer’s wallet. Save a unique funding operation key in your database and reuse it if you retry. Give later top-ups a new key. Keep the returned funding operation ID.
Terminal · fund $1
```
curl --fail-with-body "https://vaaya.ai/api/v1/customers/$CUSTOMER_ID/fund" \
  -H "Authorization: Bearer $VAAYA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_SAVED_FUNDING_KEY" \
  -d '{"amount_cents":100}'
```
6
Confirm the transfer
Replace YOUR_FUNDING_ID with the operation ID from the funding response. Wait until status is confirmed before spending. If a request times out, check this same operation; do not submit a replacement transfer.
Terminal · funding status
```
curl --fail-with-body "https://vaaya.ai/api/v1/customers/$CUSTOMER_ID/funding/YOUR_FUNDING_ID" \
  -H "Authorization: Bearer $VAAYA_API_KEY"
```
7
Get the customer’s access token
This returns a restricted token that lasts one hour. Use it to run requests as this customer. It cannot create customers or move money into wallets.
Terminal · customer access
```
curl --fail-with-body -X POST "https://vaaya.ai/api/v1/customers/$CUSTOMER_ID/access" \
  -H "Authorization: Bearer $VAAYA_API_KEY"
```
8
Make a request from the customer wallet
Replace YOUR_CUSTOMER_TOKEN with the token above. This search allows a charge of up to 5¢ and uses the customer’s wallet. Reuse the wallet for later requests. Managed wallets currently support synchronous catalog calls; streaming LLM calls, routed One methods, and background jobs are not supported yet.
Terminal · customer request
```
curl --fail-with-body https://vaaya.ai/api/run/exa/search \
  -H "Authorization: Bearer YOUR_CUSTOMER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_SAVED_REQUEST_KEY" \
  -d '{"query":"resume writing advice","max_cost_cents":5}'
```

Setup guide

Instinct

Instinct can register through the agent API or sign in by magic link with its @mail.instinct.com address. Both paths start with $10 welcome credit. Hotel Lobby is a paid video recipe requiring a separate paid top-up and enough paid balance. Choose Hotel Lobby Standard (7 seconds) or Extended (29 seconds), both with original audio. Check availability and the price before paying.

Before you start. Have Instinct set up and reachable over text or WhatsApp. If you want it to add credit for you, it needs a card stored with it, as most Instinct accounts do.

Tell Instinct to open a Vaaya account

Send this message. Instinct registers, gets an API key that works on every Vaaya endpoint, and a $10 welcome credit on the account right away, with no expiry. It keeps the key in its own private state, so do not ask it to show you.

Message to Instinct

Connect to Vaaya for me using the signup reference at https://vaaya.ai/llms.txt. Use my existing account if connected; otherwise register with agent_name "instinct" or sign in with your Instinct email. Keep credentials in your secret store. Show me what you can search, scrape and generate, with prices before spending.

Claim the account
Instinct sends you a claim link. Open it and sign in with Google, GitHub, or your email. That puts the account under your name, gives you the dashboard, and lets you set a spending limit on Instinct’s key. Instinct keeps working through the claim.
Where the account lives after claiming
3
Hotel Lobby: buy a credit pack before using the paid recipe
Hotel Lobby requires a paid top-up (any credit pack) even if your $10 welcome grant is unused. Check Hotel Lobby availability and choose Standard (7 seconds) or Extended (29 seconds). Standard costs $11 and Extended costs $34. Instinct can replace the left performer, the right performer, or both in one video. Tell it who belongs on each side from the viewer’s perspective and provide 1–5 separate photos per person. It sends one performers entry per chosen slot; unassigned performers stay unchanged. Instinct can open Stripe Checkout for an authorized credit pack using your stored card, or send you the payment link. It verifies prepaid funds after payment. The top-up funds your wallet; review the video estimate separately.
Message to Instinct
```
Check https://vaaya.ai/recipes/colors for availability. When Hotel Lobby is available, help me buy a prepaid credit pack for it. Confirm the amount before paying; welcome credit is separate.
```
4
Ask for something
Vaaya covers video and image generation, web search and research, scraping, data lookups, compute, and more. Instinct checks the price before every call and is only charged when a call succeeds.
Try this prompt
```
Use Vaaya to make a 10-second product video from this photo. Show me the price first.
```

Setup guide

OpenClaw

Give OpenClaw the Vaaya skill so it knows how to find services, check prices, and make calls.

Before you start. Have OpenClaw running, with access to the internet and permission to install skills.

Get an API key
Sign in to Vaaya and copy your API key from this page. For a shared or unattended agent, create a separate key in API keys and set its monthly spending limit.
Manage API keys
2
Save the key where OpenClaw runs
Add VAAYA_API_KEY to your agent’s environment or hosting secrets. Use the key from step 1. Restart the agent so it can read the new variable; do not paste the key into chat.
Environment variable
```
VAAYA_API_KEY=YOUR_VAAYA_API_KEY
```
3
Ask OpenClaw to install the skill
Paste this message into your OpenClaw conversation. The skill contains the setup instructions and API details your agent needs.
Message to OpenClaw
```
Read https://vaaya.ai/skill.md and install the Vaaya skill. Use the existing VAAYA_API_KEY environment variable for authentication. Do not print the key or create a new account.
```
4
Check the connection
Start a new conversation and paste this prompt. Your agent should show your Vaaya balance and the tools it can use.
Try this prompt
```
Use Vaaya to show my balance and available tools. Do not run any paid tools yet.
```

Setup guide

Hermes

Add Vaaya as a remote MCP server in your Hermes configuration.

Before you start. Have Hermes installed with MCP support. Use a separate Vaaya API key with a monthly limit for unattended work.

Get an API key
Sign in to Vaaya and copy your API key from this page. For a shared or unattended agent, create a separate key in API keys and set its monthly spending limit.
Manage API keys
2
Add Vaaya to your MCP configuration
Open ~/.hermes/config.yaml. Add this entry under mcp_servers, keeping any servers you already have. Replace YOUR_VAAYA_API_KEY with your key and keep this configuration file private.
~/.hermes/config.yaml
```
mcp_servers:
  vaaya:
    url: "https://vaaya.ai/mcp"
    headers:
      Authorization: "Bearer YOUR_VAAYA_API_KEY"
```
Restart Hermes
Start a new Hermes session so it loads the server configuration. If you run Hermes as a gateway or service, restart that process as well.
4
Check the connection
Start a new conversation and paste this prompt. Your agent should show your Vaaya balance and the tools it can use.
Try this prompt
```
Use Vaaya to show my balance and available tools. Do not run any paid tools yet.
```

Setup guide

ChatGPT

Add Vaaya as a custom app in ChatGPT on the web.

Before you start. Custom MCP apps require Developer mode on a supported ChatGPT plan. Your workspace administrator may need to enable access.

Enable Developer mode
In ChatGPT on the web, open Settings → Security and login, then turn on Developer mode. If the option is unavailable, check your plan or ask your workspace administrator.
2
Create the Vaaya app
Open ChatGPT’s Plugins page and use the plus button to create a developer-mode app. Name it Vaaya, paste this MCP server URL, and choose OAuth authentication.
MCP server URL
```
https://vaaya.ai/mcp
```
Open ChatGPT Plugins
Sign in and enable Vaaya
Complete the Vaaya sign-in and approve access. In a new chat, open the plus menu, choose Developer mode, and select Vaaya for that conversation.
4
Check the connection
Start a new conversation and paste this prompt. Your agent should show your Vaaya balance and the tools it can use.
Try this prompt
```
Use Vaaya to show my balance and available tools. Do not run any paid tools yet.
```

Setup guide

Claude

Add Vaaya as a custom connector in Claude on the web or desktop.

Before you start. For a Team or Enterprise account, an organization owner must add the connector before members can connect.

Open your connectors
In Claude, go to Customize → Connectors. Click the plus button, then Add custom connector. Organization owners can add it from Organization settings → Connectors → Add → Custom → Web.
2
Add the Vaaya server
Name the connector Vaaya, paste this URL, and click Add. You can leave the advanced OAuth fields empty.
Remote MCP server URL
```
https://vaaya.ai/mcp
```
Connect your account
Click Connect next to Vaaya. Sign in to your Vaaya account and approve access. In a new conversation, open the plus menu → Connectors and enable Vaaya.
4
Check the connection
Start a new conversation and paste this prompt. Your agent should show your Vaaya balance and the tools it can use.
Try this prompt
```
Use Vaaya to show my balance and available tools. Do not run any paid tools yet.
```

Setup guide

Claude Code

Add Vaaya to Claude Code so it can use services while you work in your terminal.

Before you start. Have Claude Code installed and open it at least once. The installer needs Node.js 20 or later.

1
Run the installer
Open Terminal on macOS or a terminal on Linux or Windows. Run this command to add the Vaaya connection and skill to Claude Code.
Terminal
```
npx -y @vaaya/mcp install --only=claude-code
```
2
Connect your Vaaya account
Restart Claude Code, run /mcp, and select vaaya. Follow the authentication prompt to sign in to Vaaya in your browser and approve the connection.
Inside Claude Code
```
/mcp
```
3
Check the connection
Start a new conversation and paste this prompt. Your agent should show your Vaaya balance and the tools it can use.
Try this prompt
```
Use Vaaya to show my balance and available tools. Do not run any paid tools yet.
```

Setup guide

Codex

Connect Vaaya to the Codex CLI or IDE extension. Local Codex clients share the same MCP configuration.

Before you start. Have the Codex CLI installed and run it at least once. The Vaaya installer needs Node.js 20 or later.

1
Install the Vaaya integration
Run this in your terminal. It adds Vaaya to your Codex configuration and installs the instructions Codex uses to work with Vaaya.
Terminal
```
npx -y @vaaya/mcp install --only=codex
```
Sign in to Vaaya
Restart Codex or reload the IDE extension. Ask Codex to connect to Vaaya. Its first Vaaya call provides a browser sign-in link; open it, sign in, and approve access.
3
Check the connection
Start a new conversation and paste this prompt. Your agent should show your Vaaya balance and the tools it can use.
Try this prompt
```
Use Vaaya to show my balance and available tools. Do not run any paid tools yet.
```

Setup guide

Cursor

Make Vaaya available to Cursor Agent in your editor.

Before you start. Have Cursor installed and open it at least once. The installer needs Node.js 20 or later.

1
Run the installer in Cursor’s terminal
Open Terminal → New Terminal in Cursor, then paste this command. It adds Vaaya to your global Cursor configuration and installs the Vaaya skill.
Terminal
```
npx -y @vaaya/mcp install --only=cursor
```
Restart Cursor and sign in
Quit and reopen Cursor. Open its MCP settings and check that vaaya is enabled. Ask Cursor Agent to connect to Vaaya, then open the sign-in link it provides and approve access.
3
Check the connection
Start a new conversation and paste this prompt. Your agent should show your Vaaya balance and the tools it can use.
Try this prompt
```
Use Vaaya to show my balance and available tools. Do not run any paid tools yet.
```

Setup guide

Devin

Connect Devin to Vaaya from your organization’s MCP settings.

Before you start. You need permission to manage MCP servers in your Devin organization.

Get an API key
Sign in to Vaaya and copy your API key from this page. For a shared or unattended agent, create a separate key in API keys and set its monthly spending limit.
Manage API keys
2
Add a custom MCP server
In Devin, open Settings → MCP Marketplace → Add Your Own. Name the server Vaaya, choose HTTP as the transport, and enter this server URL.
Server URL
```
https://vaaya.ai/mcp
```
3
Add authentication and save
Choose Auth Header. Set the header name to Authorization and the value to Bearer followed by a space and your Vaaya API key. Save, then click Test listing tools. Devin should return Vaaya’s tools.
Authentication header
```
Authorization: Bearer YOUR_VAAYA_API_KEY
```
4
Check the connection
Start a new conversation and paste this prompt. Your agent should show your Vaaya balance and the tools it can use.
Try this prompt
```
Use Vaaya to show my balance and available tools. Do not run any paid tools yet.
```

Setup guide

TypeScript / JavaScript

Use the Vaaya client in a Node.js service or an agent application. It handles authentication, spending ceilings, and receipts for you.

Before you start. Use Node.js 20 or later. Run these commands from your project folder. Keep the client and your API key on the server.

Get an API key
Sign in to Vaaya and copy your API key from this page. For a shared or unattended agent, create a separate key in API keys and set its monthly spending limit.
Manage API keys
2
Install the package
Add the SDK to your project. It supports TypeScript, JavaScript, ESM, and CommonJS.
Terminal
```
npm install @vaaya/sdk
```
3
Set your API key
Replace the placeholder with your key. This command works in bash or zsh; in production, add VAAYA_API_KEY to your hosting secrets.
Terminal · bash / zsh
```
export VAAYA_API_KEY='YOUR_VAAYA_API_KEY'
```
4
Check the connection
Save this as quickstart.mjs, then run node quickstart.mjs. It prints your available balance in cents. Reading your balance is free.
quickstart.mjs
```
import { Vaaya } from '@vaaya/sdk'

const vaaya = new Vaaya()
const wallet = await vaaya.wallet()
console.log(wallet.availableCents)
```
5
Create a wallet for each customer
For applications with end users, use managed customer accounts (SDK 0.2.0 and managed customer access required). Call this from your signup handler using the authenticated user’s stable ID. Retrying with the same ID returns the same customer. The wallet starts empty.
Your server · signup handler
```
const customer = await vaaya.customers.ensure({
  externalId: appUser.id,
  budgetCents: 500, // $5 lifetime funding and spending limit
})
await vaaya.customers.waitUntilReady(customer.id)
// Save customer.id alongside your application user.
```
6
Fund their first request
Before the customer’s first paid request, move an amount you choose from your prepaid Vaaya balance into their wallet. This example moves $1. Save a funding operation ID in your database and reuse it on retries. A spending limit alone does not move money.
Your server · explicit funding
```
const funding = await vaaya.customers.fund(customer.id, {
  amountCents: 100,
  idempotencyKey: fundingOperation.id,
})
await vaaya.customers.waitForFunding(customer.id, funding.id)
```
7
Run requests as that customer
Create a customer-scoped client after authenticating the user in your app. It uses a restricted token that lasts one hour. Supported synchronous catalog calls pay from this customer’s wallet. Streaming LLM calls, routed One methods, and background jobs are not supported by managed wallets yet.
Your server · customer request
```
const client = await vaaya.forCustomer(customer.id)
const result = await client.use('exa/search', { query: 'resume writing advice' }, {
  maxCostCents: 5,
  idempotencyKey: requestOperation.id,
})
console.log(result.data, result.chargedCents)
```

Setup guide

Python

Use the Python client in a script, service, or agent. The core client needs no additional runtime packages.

Before you start. Use Python 3.9 or later. These terminal commands use bash or zsh on macOS or Linux; on Windows, use WSL or your usual Python virtual environment.

Get an API key
Sign in to Vaaya and copy your API key from this page. For a shared or unattended agent, create a separate key in API keys and set its monthly spending limit.
Manage API keys
2
Create an environment and install the package
Run these commands from your project folder. A virtual environment keeps the SDK separate from your system Python.
Terminal
```
python3 -m venv .venv
source .venv/bin/activate
python -m pip install vaaya
```
3
Set your API key
Replace the placeholder with your key. In production, add VAAYA_API_KEY to your hosting secrets rather than putting it in your source code.
Terminal · bash / zsh
```
export VAAYA_API_KEY='YOUR_VAAYA_API_KEY'
```
4
Check the connection
Save this as quickstart.py, then run python quickstart.py. It prints your available balance in cents without running a paid service.
quickstart.py
```
from vaaya import Vaaya

vaaya = Vaaya()
wallet = vaaya.wallet()
print(wallet["available_cents"])
```
5
Create a wallet for each customer
Managed customer accounts require SDK 0.2.0 and managed customer access. In your signup handler, use the authenticated user’s stable ID. Repeated calls return the same customer and wallet. The $5 budget below is a limit, not a deposit.
Your server · signup handler
```
customer = vaaya.customers.ensure(app_user.id, budget_cents=500)
vaaya.customers.wait_until_ready(customer["id"])
# Save customer["id"] alongside your application user.
```
6
Fund the wallet before its first paid request
This moves $1 from your prepaid Vaaya balance to the customer’s wallet. Keep funding_operation.id in your database and reuse it if the request times out. Wait for confirmation before spending. Later requests reuse the remaining wallet balance.
Your server · explicit funding
```
funding = vaaya.customers.fund(
    customer["id"], amount_cents=100,
    idempotency_key=funding_operation.id,
)
vaaya.customers.wait_for_funding(customer["id"], funding["id"])
```
7
Run requests as that customer
Use a customer-scoped client for supported synchronous catalog calls. Its credential expires after one hour; create a fresh scoped client when needed. Streaming LLM calls, routed One methods, and background jobs do not yet support managed-wallet settlement.
Your server · customer request
```
client = vaaya.for_customer(customer["id"])
result = client.use(
    "exa/search", {"query": "resume writing advice"},
    max_cost_cents=5, idempotency_key=request_operation.id,
)
print(result["data"], result["charged_cents"])
```

Setup guide

REST API

Use HTTP from any language. These examples use curl on macOS or Linux. On Windows, use WSL or Git Bash.

Before you start. You need a Vaaya account, an API key, and curl.

Get an API key
Sign in to Vaaya and copy your API key from this page. For a shared or unattended agent, create a separate key in API keys and set its monthly spending limit.
Manage API keys
2
Set your API key
Replace YOUR_VAAYA_API_KEY with the key you copied. In a deployed app, save VAAYA_API_KEY in your hosting provider’s environment variables. Keep it on the server.
Terminal · bash / zsh
```
export VAAYA_API_KEY='YOUR_VAAYA_API_KEY'
```
3
Provision a separate customer wallet
For an application with end users, request managed customer access and call this endpoint from your signup handler. Use a stable user ID from your own database. The response includes a customer ID, agent ID, wallet address, and provisioning status; retries reuse the same customer.
Terminal · customer signup
```
curl --fail-with-body https://vaaya.ai/api/v1/customers/ensure \
  -H "Authorization: Bearer $VAAYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"your-user-id","budget_cents":500}'
```
4
Wait for the wallet to be ready
Save the returned customer ID with your application user. Replace YOUR_CUSTOMER_ID below, then check until status is ready. Wallet creation does not move money.
Terminal · wallet status
```
export CUSTOMER_ID='YOUR_CUSTOMER_ID'
curl --fail-with-body "https://vaaya.ai/api/v1/customers/$CUSTOMER_ID" \
  -H "Authorization: Bearer $VAAYA_API_KEY"
```
5
Fund the first paid request
This moves $1 from your prepaid Vaaya balance into this customer’s wallet. Save a unique funding operation key in your database and reuse it if you retry. Give later top-ups a new key. Keep the returned funding operation ID.
Terminal · fund $1
```
curl --fail-with-body "https://vaaya.ai/api/v1/customers/$CUSTOMER_ID/fund" \
  -H "Authorization: Bearer $VAAYA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_SAVED_FUNDING_KEY" \
  -d '{"amount_cents":100}'
```
6
Confirm the transfer
Replace YOUR_FUNDING_ID with the operation ID from the funding response. Wait until status is confirmed before spending. If a request times out, check this same operation; do not submit a replacement transfer.
Terminal · funding status
```
curl --fail-with-body "https://vaaya.ai/api/v1/customers/$CUSTOMER_ID/funding/YOUR_FUNDING_ID" \
  -H "Authorization: Bearer $VAAYA_API_KEY"
```
7
Get the customer’s access token
This returns a restricted token that lasts one hour. Use it to run requests as this customer. It cannot create customers or move money into wallets.
Terminal · customer access
```
curl --fail-with-body -X POST "https://vaaya.ai/api/v1/customers/$CUSTOMER_ID/access" \
  -H "Authorization: Bearer $VAAYA_API_KEY"
```
8
Make a request from the customer wallet
Replace YOUR_CUSTOMER_TOKEN with the token above. This search allows a charge of up to 5¢ and uses the customer’s wallet. Reuse the wallet for later requests. Managed wallets currently support synchronous catalog calls; streaming LLM calls, routed One methods, and background jobs are not supported yet.
Terminal · customer request
```
curl --fail-with-body https://vaaya.ai/api/run/exa/search \
  -H "Authorization: Bearer YOUR_CUSTOMER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_SAVED_REQUEST_KEY" \
  -d '{"query":"resume writing advice","max_cost_cents":5}'
```

Setup guide

Instinct

Before you start. Have Instinct set up and reachable over text or WhatsApp. If you want it to add credit for you, it needs a card stored with it, as most Instinct accounts do.

Tell Instinct to open a Vaaya account

Message to Instinct

Connect to Vaaya for me using the signup reference at https://vaaya.ai/llms.txt. Use my existing account if connected; otherwise register with agent_name "instinct" or sign in with your Instinct email. Keep credentials in your secret store. Show me what you can search, scrape and generate, with prices before spending.

Claim the account
Instinct sends you a claim link. Open it and sign in with Google, GitHub, or your email. That puts the account under your name, gives you the dashboard, and lets you set a spending limit on Instinct’s key. Instinct keeps working through the claim.
Where the account lives after claiming
3
Hotel Lobby: buy a credit pack before using the paid recipe
Hotel Lobby requires a paid top-up (any credit pack) even if your $10 welcome grant is unused. Check Hotel Lobby availability and choose Standard (7 seconds) or Extended (29 seconds). Standard costs $11 and Extended costs $34. Instinct can replace the left performer, the right performer, or both in one video. Tell it who belongs on each side from the viewer’s perspective and provide 1–5 separate photos per person. It sends one performers entry per chosen slot; unassigned performers stay unchanged. Instinct can open Stripe Checkout for an authorized credit pack using your stored card, or send you the payment link. It verifies prepaid funds after payment. The top-up funds your wallet; review the video estimate separately.
Message to Instinct
```
Check https://vaaya.ai/recipes/colors for availability. When Hotel Lobby is available, help me buy a prepaid credit pack for it. Confirm the amount before paying; welcome credit is separate.
```
4
Ask for something
Vaaya covers video and image generation, web search and research, scraping, data lookups, compute, and more. Instinct checks the price before every call and is only charged when a call succeeds.
Try this prompt
```
Use Vaaya to make a 10-second product video from this photo. Show me the price first.
```

Setup guide

OpenClaw

Give OpenClaw the Vaaya skill so it knows how to find services, check prices, and make calls.

Before you start. Have OpenClaw running, with access to the internet and permission to install skills.

Get an API key
Sign in to Vaaya and copy your API key from this page. For a shared or unattended agent, create a separate key in API keys and set its monthly spending limit.
Manage API keys
2
Save the key where OpenClaw runs
Add VAAYA_API_KEY to your agent’s environment or hosting secrets. Use the key from step 1. Restart the agent so it can read the new variable; do not paste the key into chat.
Environment variable
```
VAAYA_API_KEY=YOUR_VAAYA_API_KEY
```
3
Ask OpenClaw to install the skill
Paste this message into your OpenClaw conversation. The skill contains the setup instructions and API details your agent needs.
Message to OpenClaw
```
Read https://vaaya.ai/skill.md and install the Vaaya skill. Use the existing VAAYA_API_KEY environment variable for authentication. Do not print the key or create a new account.
```
4
Check the connection
Start a new conversation and paste this prompt. Your agent should show your Vaaya balance and the tools it can use.
Try this prompt
```
Use Vaaya to show my balance and available tools. Do not run any paid tools yet.
```

Setup guide

Hermes

Add Vaaya as a remote MCP server in your Hermes configuration.

Before you start. Have Hermes installed with MCP support. Use a separate Vaaya API key with a monthly limit for unattended work.

Get an API key
Sign in to Vaaya and copy your API key from this page. For a shared or unattended agent, create a separate key in API keys and set its monthly spending limit.
Manage API keys
2
Add Vaaya to your MCP configuration
Open ~/.hermes/config.yaml. Add this entry under mcp_servers, keeping any servers you already have. Replace YOUR_VAAYA_API_KEY with your key and keep this configuration file private.
~/.hermes/config.yaml
```
mcp_servers:
  vaaya:
    url: "https://vaaya.ai/mcp"
    headers:
      Authorization: "Bearer YOUR_VAAYA_API_KEY"
```
Restart Hermes
Start a new Hermes session so it loads the server configuration. If you run Hermes as a gateway or service, restart that process as well.
4
Check the connection
Start a new conversation and paste this prompt. Your agent should show your Vaaya balance and the tools it can use.
Try this prompt
```
Use Vaaya to show my balance and available tools. Do not run any paid tools yet.
```

Setup guide

ChatGPT

Add Vaaya as a custom app in ChatGPT on the web.

Before you start. Custom MCP apps require Developer mode on a supported ChatGPT plan. Your workspace administrator may need to enable access.

Enable Developer mode
In ChatGPT on the web, open Settings → Security and login, then turn on Developer mode. If the option is unavailable, check your plan or ask your workspace administrator.
2
Create the Vaaya app
Open ChatGPT’s Plugins page and use the plus button to create a developer-mode app. Name it Vaaya, paste this MCP server URL, and choose OAuth authentication.
MCP server URL
```
https://vaaya.ai/mcp
```
Open ChatGPT Plugins
Sign in and enable Vaaya
Complete the Vaaya sign-in and approve access. In a new chat, open the plus menu, choose Developer mode, and select Vaaya for that conversation.
4
Check the connection
Start a new conversation and paste this prompt. Your agent should show your Vaaya balance and the tools it can use.
Try this prompt
```
Use Vaaya to show my balance and available tools. Do not run any paid tools yet.
```

Setup guide

Claude

Add Vaaya as a custom connector in Claude on the web or desktop.

Before you start. For a Team or Enterprise account, an organization owner must add the connector before members can connect.

Open your connectors
In Claude, go to Customize → Connectors. Click the plus button, then Add custom connector. Organization owners can add it from Organization settings → Connectors → Add → Custom → Web.
2
Add the Vaaya server
Name the connector Vaaya, paste this URL, and click Add. You can leave the advanced OAuth fields empty.
Remote MCP server URL
```
https://vaaya.ai/mcp
```
Connect your account
Click Connect next to Vaaya. Sign in to your Vaaya account and approve access. In a new conversation, open the plus menu → Connectors and enable Vaaya.
4
Check the connection
Start a new conversation and paste this prompt. Your agent should show your Vaaya balance and the tools it can use.
Try this prompt
```
Use Vaaya to show my balance and available tools. Do not run any paid tools yet.
```

Connect your coding agent

Run the installer

Connect your Vaaya account

Check the connection

Install the Vaaya integration

Sign in to Vaaya

Check the connection

Run the installer in Cursor’s terminal

Restart Cursor and sign in

Check the connection

Get an API key

Add a custom MCP server

Add authentication and save

Check the connection

Build with Vaaya

Get an API key

Install the package

Set your API key

Check the connection

Create a wallet for each customer

Fund their first request

Run requests as that customer

Get an API key

Create an environment and install the package

Set your API key

Check the connection

Create a wallet for each customer

Fund the wallet before its first paid request

Run requests as that customer

Get an API key

Set your API key

Provision a separate customer wallet

Wait for the wallet to be ready

Fund the first paid request

Confirm the transfer

Get the customer’s access token

Make a request from the customer wallet

Set up an agent that runs on its own

Tell Instinct to open a Vaaya account

Claim the account

Hotel Lobby: buy a credit pack before using the paid recipe

Ask for something

Get an API key

Save the key where OpenClaw runs

Ask OpenClaw to install the skill

Check the connection

Get an API key

Add Vaaya to your MCP configuration

Restart Hermes

Check the connection

Connect Vaaya to your assistant

Enable Developer mode

Create the Vaaya app

Sign in and enable Vaaya

Check the connection

Open your connectors

Add the Vaaya server

Connect your account

Check the connection

Connect your coding agent

Run the installer

Connect your Vaaya account

Check the connection

Install the Vaaya integration

Sign in to Vaaya

Check the connection

Run the installer in Cursor’s terminal

Restart Cursor and sign in

Check the connection

Get an API key

Add a custom MCP server

Add authentication and save

Check the connection

Build with Vaaya

Get an API key

Install the package

Set your API key

Check the connection

Create a wallet for each customer

Fund their first request