# 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_...
```

Live purchases are paid from the payer's own [wallet](/docs/wallets) at
Perflo. There is nothing to set up first: the first live purchase that needs
the wallet pauses with a link where the payer connects it.

<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 --header "Authorization: Bearer $OPENINTENTS_API_KEY"
> 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 from the wallet

At checkout, the API pays from the payer's wallet within the limits they set.
When the payer has a step to take first (connect the wallet, add money,
confirm who they are), the intent pauses and gives you a link for them:

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

Send `payment_url` to the payer. It runs only the steps this purchase needs,
and once they're done the intent carries on by itself. See
[Wallets & 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": 0,
    "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.