# OpenIntents

> OpenIntents lets your agents buy anything. Your agent sends an intent in
> plain language ("book me a trip to Bali", "get my lunch sorted") over MCP,
> the REST API or the CLI, and it gets bought end to end in a real browser,
> with a structured receipt at the end.
> Inference, the browser, the machine it runs on, compute and bandwidth are
> free. The only charge is a 5% fee on each completed transaction.

The API is in preview, so endpoints may change.

## Setup instructions for AI agents

If a user asked you to read this file and set up OpenIntents, do this:

1. **Connect over MCP** if your harness supports it. The server is
   https://api.openintents.io/mcp. Run the matching command yourself if you can:
   - Claude Code: `claude mcp add --transport http openintents https://api.openintents.io/mcp`
   - Codex: `codex mcp add openintents --url https://api.openintents.io/mcp`

   Other agents (OpenClaw, Hermes, OpenHuman, or your own harness): add https://api.openintents.io/mcp as a
   remote HTTP MCP server named "openintents" in your own MCP config.
   Without MCP, use the REST API at https://api.openintents.io/v1
   (https://0.0.0.0:3000/docs/raw/api).
2. **Authenticate.** The MCP server signs the user in through the browser on
   first use. For the REST API, ask the user to create a key at
   https://0.0.0.0:3000/dashboard/api-keys and provide it as OPENINTENTS_API_KEY. Suggest
   a test key (oi_test_...) first: test intents run end to end but never charge.
3. **Confirm it works** by listing intents, then tell the user you're ready.

When sending intents:

- Be specific: what, where or from whom, when, and any constraints.
- Always pass a spending cap (max_amount, in cents) the user agreed to.
- Put structured details (addresses, names) in context, not in the sentence.
- Intents run asynchronously. Wait for a final status, then report the
  merchant, items, total and the 5% fee. If it returns requires_payment, pass
  the payment_url to the user and wait.

Rules:

- Confirm with the user before any live purchase you weren't explicitly asked
  to make, and before going over the budget they gave you.
- Intents pay from the user's topped-up agent balance when it covers them.
  Otherwise the intent returns status requires_payment with a payment_url:
  show the user what it is buying and give them the link. Never try to pay it
  yourself.
- Never ask for, store or invent card numbers. Payment comes from the agent
  balance or the hosted payment link.
- If an intent fails, report the error and ask before retrying.

## Docs

Each link below is the raw Markdown of a docs page.

### Getting started

- [Introduction](https://0.0.0.0:3000/docs/raw/introduction): Let your agents buy anything: what OpenIntents does and how an intent gets done.
- [Quickstart](https://0.0.0.0:3000/docs/raw/quickstart): Send your first intent in under a minute.
- [Pricing](https://0.0.0.0:3000/docs/raw/pricing): Free inference and compute; 5% per completed transaction.

### Concepts

- [Intents](https://0.0.0.0:3000/docs/raw/intents): The intent object and its lifecycle.
- [Balance & payments](https://0.0.0.0:3000/docs/raw/wallets): Paying from a topped-up agent balance or a payment link, and spending limits.

### Interfaces

- [MCP server](https://0.0.0.0:3000/docs/raw/mcp): Use OpenIntents from Claude, Cursor, Codex or any MCP client.
- [REST API](https://0.0.0.0:3000/docs/raw/api): Endpoints, request and response shapes, errors.
- [CLI](https://0.0.0.0:3000/docs/raw/cli): The openintents command for shell-driven agents.
- [Webhooks](https://0.0.0.0:3000/docs/raw/webhooks): Events for completed, failed and payment-required intents.