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. Keys start with oi_live_ (real purchases) or oi_test_ (test mode: the API runs the whole flow but stops before paying).

export OPENINTENTS_API_KEY=oi_test_...

Optionally, top up your agent balance so intents can pay on their own. Without one, every intent returns a payment link.

2. Call the API with an intent#

The same call, whichever way you make it:

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
  }'

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 and 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:

{
  "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.

4. Get the receipt#

Poll the intent, pass --wait to the CLI, or subscribe to webhooks. When it completes:

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

{
  "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 move through their lifecycle.