Setup guide

Last updated 21 November 2026

Xpenvo Agents puts a spending limit in front of your AI agents. Your agent sends its requests through Xpenvo; each one is checked against your budgets and rules before it reaches your AI provider. If a request would go over, it is stopped and the provider never sees it, so it is never billed.

Setup takes about five minutes and one change to your agent’s code. You keep your own provider account and key (OpenAI, Anthropic, Google Gemini, Mistral, OpenRouter, Azure OpenAI or Amazon Bedrock), and you keep paying them directly. Xpenvo never stores your prompts, answers or provider keys.

1. Create your organisation

Sign in with a one-time email code, Google or GitHub. Then create an organisation: it holds your budgets, agent keys and team. You can invite teammates later as admins (can change budgets and keys) or viewers (can only look).

2. Create a budget

Open Budgets and fill in:

NameAnything that helps you recognise it, for example “Support agents”.
ResetsEvery day, every month, or never (a lifetime cap). Days and months start at midnight in the budget’s time zone, which you choose when you create it (UTC unless you pick another).
LimitThe most all agents on this budget may spend in that period, in US dollars, the currency AI providers bill in.
Most per requestOptional. Stops any single request that could cost more than this, even when there is money left.
Inside budgetOptional. Put a budget inside another one, for example “Support: $20 a day” inside “Company: $500 a month”. A request must fit every level above it.

3. Create an agent key

Open Agent keys, give the key a name (for example the agent’s name) and choose its budget. Give each agent its own key: you then see what each one spends, and you can switch one off without stopping the others.

4. Store the keys safely

Your agent needs two keys: the Xpenvo key from step 3, and your own OpenAI or Anthropic key, which you already use. Keep both in environment variables or your hosting platform’s secrets settings, never written into your code. Every cloud and hosting platform has a place for these, usually called “environment variables” or “secrets”.

export XPENVO_KEY="your-xpenvo-key"
export OPENAI_API_KEY="your-openai-key"     # or ANTHROPIC_API_KEY

Variables set in a terminal last only while that terminal is open. On a server or hosting platform, set them in its settings so they survive restarts.

5. Connect your agent

In your agent’s code, find where it creates its OpenAI or Anthropic client, and add two things: Xpenvo’s address and the Xpenvo key. Nothing else changes: the same models, prompts, streaming and tool use all work as before.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://agents.xpenvo.com/v1",
    default_headers={"X-Xpenvo-Key": os.environ["XPENVO_KEY"]},
)  # your own OPENAI_API_KEY is used as usual

Using another language or tool? Any OpenAI or Anthropic client works: set its base address to https://agents.xpenvo.com/v1 for OpenAI or https://agents.xpenvo.com for Anthropic, and send the header X-Xpenvo-Key with your Xpenvo key.

Using Google Gemini, Mistral, OpenRouter, Azure OpenAI or Amazon Bedrock? See Providers for their addresses.

6. Send a first request

Before changing a live agent, try one small request from your computer. This complete example also shows how to handle a request Xpenvo stops.

  1. Make a new folder outside your other projects and save the example below in it, for example as test.py or test.mjs.
  2. Install the provider’s library: pip install openai (or anthropic), or npm install openai (or @anthropic-ai/sdk).
  3. Set the two keys as in step 4, in the same terminal.
  4. Run it: python test.py or node test.mjs.
import os
from openai import OpenAI, APIStatusError

client = OpenAI(
    base_url="https://agents.xpenvo.com/v1",
    default_headers={"X-Xpenvo-Key": os.environ["XPENVO_KEY"]},
)

try:
    reply = client.chat.completions.create(
        model="gpt-5-nano",
        max_completion_tokens=2000,  # caps the most this request can cost
        messages=[{"role": "user", "content": "Say hello in five words."}],
    )
    print(reply.choices[0].message.content)
except APIStatusError as e:
    if e.status_code == 402:  # stopped by Xpenvo: it would go over a budget
        print("Budget limit reached:", e.message)
    else:
        raise

Then open Activity in your dashboard: the request is there with its model, tokens and cost. Overview shows the totals.

How limits work

Tip: always set a maximum answer length (max_tokens, or max_completion_tokens on newer OpenAI models). Without it, Xpenvo must assume the model’s largest possible answer, which can be enough to stop a request on a small budget even though the real answer would cost far less.

Xpenvo only sends requests it can price. A model that is not on our price list is stopped, never let through unchecked.

Providers

Use your provider’s own key, as before. Only the base address changes, and you add the X-Xpenvo-Key header.

OpenAIhttps://agents.xpenvo.com/v1 (Chat Completions and Responses)
Anthropichttps://agents.xpenvo.com (Messages)
Google Geminihttps://agents.xpenvo.com/v1/gemini with an OpenAI client (Gemini’s OpenAI-compatible API)
Mistralhttps://agents.xpenvo.com/v1/mistral (Chat Completions)
OpenRouterhttps://agents.xpenvo.com/v1/openrouter (Chat Completions)
Azure OpenAIhttps://agents.xpenvo.com/v1/azure/<resource>, where the resource is the part before .openai.azure.com. First add each deployment and the model it runs under Developers, so it can be priced.
Amazon Bedrockhttps://agents.xpenvo.com/v1/bedrock/<region>/model/<model id>/converse for Anthropic Claude models, using a Bedrock API key (sent as Authorization: Bearer). AWS signature (SigV4) signing is not supported, because the signature covers the address.

Streaming works on every provider. Prices are kept on our server and updated when providers change them; a model we cannot price is stopped, never let through unchecked.

SDKs and sample agents

You do not need our SDK: the change above is enough. For extras, small helpers for JavaScript and TypeScript and for Python, with no dependencies, give the address for each provider, add the headers below, and wait for a person to approve a big request before sending it again. Each is one file: download it under Developers in your dashboard, or directly as xpenvo.mjs (types: xpenvo.d.mts) and xpenvo.py, and save it next to your agent’s code. Sample agents for OpenAI and Anthropic are there too.

Runs and end customers

Two optional headers make your activity easier to follow and to limit:

Use 1 to 64 letters, digits, _ . : -. Never use an email address or a name; Xpenvo refuses ids that look like an email.

Rules

Under Budgets → Rules, an admin can set, per budget: which providers and models are allowed, which days and hours it may be used (in the budget’s time zone), a limit per end customer, a limit per run, whether a customer id is required, and the amount above which a request needs approval. Each key can also have a requests-per-minute limit and an hourly spend limit, under Agent keys → Limits.

Approvals

When a request could cost more than the budget’s approval amount, Xpenvo stops it with status 402 and the header x-xpenvo-approval, and tells your team by email and alert channels. An admin approves or denies it under Approvals. Once approved, send the exact same request again within an hour and it goes through. Your agent can check GET https://agents.xpenvo.com/v1/xpenvo/approvals/<id> with its X-Xpenvo-Key; our SDKs do this for you. Requests waiting longer than 30 minutes are flagged again, and unanswered ones expire after 24 hours.

Safety stops

Admins can tune these under Safety.

Alerts

The owner and admins get an email when a budget reaches 80% of its limit, when it is full, and the first time it stops a request. Each kind is sent at most once per budget per period, and changing a budget’s limit starts the count again. Admins can switch these emails off under Settings.

Under Alerts you can also send alerts to Slack, Microsoft Teams or your own webhook. Webhooks are signed (Standard Webhooks: webhook-id, webhook-timestamp, webhook-signature) so you can check they came from us; the dashboard shows how. Alerts never include prompts or answers.

Management API

To manage budgets, keys and activity from your own tools, create a read-only or read-and-write token under Developers (the token starts with xpm_ and is shown once). Send it as Authorization: Bearer to https://agents.xpenvo.com/v1/manage/…. The full list of calls is in the dashboard.

Try it without an account

The demo runs a pretend budget in your browser. Nothing is sent to any provider and nothing is saved.

How fast it is

Every reply carries a Server-Timing header, for example xpenvo;dur=4;desc="Xpenvo checks". The number is how many milliseconds our checks added before your request was sent to the provider. Browsers show it in the developer tools; in code, read the server-timing response header.

Errors and fixes

402 over_budgetThe request could cost more than is left on its budget, or a budget above it. Wait for the reset, raise the limit, or set a lower maximum answer length.
402 request_limitThe request could cost more than the budget’s “Most per request”. Set a lower maximum answer length or raise that limit.
402 customer_limit, run_limit, hourly_limitThe end customer, the run or the key reached its limit. Raise it under Rules or Limits, or wait.
402 approval_required / approval_pendingA person must approve this request. The id is in the x-xpenvo-approval header. Send the same request again once approved.
402 approval_deniedA person denied it. Change the request (for example a smaller model or a lower maximum answer length).
403 kill_switch, key_paused, budget_pausedStopped on purpose by an admin. They can turn it off in the dashboard.
403 loop_detected, spend_spikeThe key was paused for safety. Check the agent, then an admin can resume the key.
403 policy_provider, policy_model, policy_time, customer_requiredThe budget’s rules do not allow this request. See the message for which rule.
429 rate_limitThe key reached its requests-per-minute limit. Wait for the retry-after seconds.
400 unknown_deployment(Azure) Add the deployment under Developers, then retry.
401 invalid_xpenvo_keyThe X-Xpenvo-Key header is missing, mistyped, or the key was switched off. Check the variable is set where the agent runs.
400 unknown_modelThe model is not on our price list yet. Check the spelling, or [email protected] to ask us to add it.
400 unsupported_featureThe request uses something Xpenvo cannot price yet, so it was not sent.
429 rate_limitedToo many requests with one key in a short time. Retry after a short pause.
502 / 503The provider or Xpenvo’s budget check could not be reached. Nothing was sent or charged; retry.
KeyError: XPENVO_KEY(Python) The variable is not set in this terminal or server. Set it as in step 4, in the same place you run the agent.

The short code is always in the x-xpenvo-error response header. Any other error comes from your provider and is passed back to your agent unchanged.

Questions? Email [email protected].