# 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 --header "Authorization: Bearer $OPENINTENTS_API_KEY"`
   - Codex: `codex mcp add openintents --url https://api.openintents.io/mcp --bearer-token-env-var OPENINTENTS_API_KEY`

   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, with
   the header Authorization: Bearer <the user's API key>.
   Without MCP, use the REST API at https://api.openintents.io/v1
   (https://0.0.0.0:3000/docs/raw/api).
2. **Authenticate.** Ask the user to create a key at
   https://0.0.0.0:3000/dashboard/api-keys and provide it as OPENINTENTS_API_KEY: the MCP
   server and the REST API both take it as Authorization: Bearer <key> (the
   commands above read it from that variable). 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 (over MCP, call
  wait_for_intent again while it is queued or running), then report the
  merchant, items, total and any fee. If it returns requires_payment, pass
  the payment_url to the user and wait.
- If it returns requires_input, the shop asked for something only the user
  knows (a phone number or email to sign in with, a one-time code, an
  approval, a detail of the order): ask them input_request.prompt and send
  their answer (answer_input over MCP, POST /v1/intents/{id}/input
  otherwise). Never answer for them.
- If it returns requires_login, give the user sign_in.url, a link for them
  alone, 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.
- Live purchases are paid from the user's own wallet, within the limits they
  set there. When the wallet needs a step first (connecting it, adding money,
  raising a limit, an identity check), the intent returns status
  requires_payment with a payment_url and a reason: show the user what it is
  buying and give them the link. Never try to pay it yourself. The intent
  carries on by itself once they are done.
- Never ask for, store or invent card numbers. OpenIntents types the
  wallet's card into the shop's form itself.
- 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.
- [Wallets & payments](https://0.0.0.0:3000/docs/raw/wallets): How purchases are paid from the payer's own wallet, what to do when one waits, wallet links and spending limits.
- [Browser profiles](https://0.0.0.0:3000/docs/raw/profiles): The logins, cookies and carts each payer keeps between intents.
- [Browser sessions](https://0.0.0.0:3000/docs/raw/sessions): Drive a payer's browser step by step, to sign them in to a shop once.
- [Secrets](https://0.0.0.0:3000/docs/raw/vault): Store a payer's address, contact details or shop password once; write-only, never read back.

### 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.
- [Events & live streams](https://0.0.0.0:3000/docs/raw/events): An intent's or a session's timeline, as a page or live over Server-Sent Events.
- [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.