# Quickstart

Let your agent make its first purchase in under a minute. An intent goes
through four steps: your agent sends it, OpenIntents does the work in a real
browser, the purchase gets paid, and the intent resolves to a receipt.

## 1. Get an API key

Create a key in the [dashboard](/dashboard/api-keys). Keys start with
`oi_live_` (real purchases) or `oi_test_` (test mode: the API runs the whole
flow but stops before paying).

```bash
export OPENINTENTS_API_KEY=oi_test_...
```

Optionally, top up your [agent balance](/docs/wallets#agent-balance) so intents
can pay on their own. Without one, every intent returns a payment link.

<Callout type="tip">
  Start with a test key. Test intents go all the way to checkout, return a
  receipt marked `"test": true`, and never charge anyone.
</Callout>

## 2. Call the API with an intent

The same call, whichever way you make it:

<CodeTabs labels={["cURL", "TypeScript", "Python", "MCP", "CLI"]}>

```bash
curl https://api.openintents.io/v1/intents \
  -H "Authorization: Bearer $OPENINTENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "flat white, oat milk, pickup 8:45 at the Blue Bottle on 5th",
    "max_amount": 1000
  }'
```

```ts
const res = await fetch("https://api.openintents.io/v1/intents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPENINTENTS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    intent: "flat white, oat milk, pickup 8:45 at the Blue Bottle on 5th",
    max_amount: 1000,
  }),
});
const intent = await res.json(); // { id: "int_7f3a2c", status: "queued", ... }
```

```python
import os, requests

intent = requests.post(
    "https://api.openintents.io/v1/intents",
    headers={"Authorization": f"Bearer {os.environ['OPENINTENTS_API_KEY']}"},
    json={
        "intent": "flat white, oat milk, pickup 8:45 at the Blue Bottle on 5th",
        "max_amount": 1000,
    },
).json()
```

```text
# Claude Code, after: claude mcp add --transport http openintents https://api.openintents.io/mcp
> Use OpenIntents to get me a flat white with oat milk from the Blue Bottle on 5th, pickup 8:45, max $10.

● openintents.create_intent({
    intent: "flat white, oat milk, pickup 8:45 at the Blue Bottle on 5th",
    max_amount: 1000
  })
```

```bash
npm install -g @tinyhumansai/openintents
openintents run "flat white, oat milk, pickup 8:45 at the Blue Bottle on 5th" --max 10 --wait
```

</CodeTabs>

`max_amount` is in cents: this intent will never spend more than $10.00. The
call returns immediately with `"status": "queued"` while the API does the
agentic work in a real browser. See [MCP server](/docs/mcp) and [CLI](/docs/cli)
for setup.

## 3. Pay with your balance or a link

At checkout, the API pays from your agent balance if it covers the total. If it
can't, the intent pauses and gives you a payment link:

```json
{
  "id": "int_7f3a2c",
  "status": "requires_payment",
  "payment": {
    "reason": "insufficient_balance",
    "payment_url": "https://pay.openintents.io/p_7f3a2c",
    "merchant": "Blue Bottle Coffee",
    "total": 550,
    "fee": 28,
    "currency": "usd",
    "expires_at": "2026-10-01T09:00:00Z"
  }
}
```

Open `payment_url` (or send it to whoever should pay). Once it's paid, the
intent carries on. See [Balance & payments](/docs/wallets).

## 4. Get the receipt

Poll the intent, pass `--wait` to the CLI, or subscribe to
[webhooks](/docs/webhooks). When it completes:

```bash
curl https://api.openintents.io/v1/intents/int_7f3a2c \
  -H "Authorization: Bearer $OPENINTENTS_API_KEY"
```

```json
{
  "id": "int_7f3a2c",
  "object": "intent",
  "status": "completed",
  "result": {
    "merchant": "Blue Bottle Coffee",
    "items": [{ "name": "Flat white, oat milk", "quantity": 1, "amount": 550 }],
    "total": 550,
    "fee": 28,
    "currency": "usd",
    "confirmation": "BB-48213",
    "receipt_url": "https://openintents.io/r/int_7f3a2c"
  }
}
```

That's it. Next, read how [intents](/docs/intents) move through their lifecycle.