OpenIntents

The agentic API to buy anything. Send one intent in plain language, like "book me a trip to Bali" or "get my lunch sorted: a bacon cheeseburger". The OpenIntents API does the agentic work in a real browser, pays from the payer's own wallet, and returns a structured receipt. Inference, browser, compute and bandwidth are free.

This repository holds the open-source client side: SDKs for TypeScript, Python and Rust, the openintents CLI, the OpenAPI spec, an agent skill and a Claude Code plugin.

Preview. The API is being built in the open. Shapes may change before launch; see spec/openapi.yaml and the docs.

Documentation

The guides live on the website, not in this repository: https://openintents.io/docs. We point at them instead of keeping copies here because two copies of a guide drift apart; the one thing this repository owns is the contract, spec/openapi.yaml, and every SDK and CLI README follows it. Each guide is also served as raw Markdown at https://openintents.io/docs/raw/<page>, and indexed for agents at https://openintents.io/llms.txt.

To do this	Read
Send an intent and follow it to a receipt	Intents and Quickstart
Answer what the agent asks (a size, a code), or sign a payer in to a shop	Intents and the "Answer what the agent asked" and "Sign-in links" sections of the REST API
Use OpenIntents from Claude, Cursor, Codex or any MCP client	MCP server
Get told when an intent changes	Webhooks
Act for your own customers (payers), with a portal for them	The "Customers" and "Portal sessions" sections of the REST API
Store an address, phone number or shop password once, write-only	Secrets
Keep a payer's logins between intents, or drive their browser	Browser profiles and Browser sessions
Follow a timeline live	Events & live streams
Pay from the payer's own wallet, and what to do when a purchase waits	Wallets & payments
Have a customer set up the wallet they pay from, before their first purchase	Wallet links
Use the command line	CLI

If a guide and the spec ever disagree, the spec wins; please open an issue.

Install

TypeScript / JavaScript	npm install @tinyhumansai/openintents
Python	pip install openintents
Rust	cargo add openintents
CLI	npm install -g @tinyhumansai/openintents
Claude Code	/plugin marketplace add tinyhumansai/openintents
Any MCP client	https://api.openintents.io/mcp, with your API key as Authorization: Bearer
Any agent	"Read https://openintents.io/llms.txt and follow the instructions to set up OpenIntents."

Quickstart

Get an API key at https://openintents.io/dashboard/api-keys (start with an oi_test_ key: test intents run end to end but never charge).

import { OpenIntents } from "@tinyhumansai/openintents";

const oi = new OpenIntents(); // OPENINTENTS_API_KEY
const created = await oi.intents.create({ intent: "flat white, oat milk, pickup 8:45", max_amount: 1000 });
const intent = await oi.intents.wait(created.id);
// "completed" → intent.result is the receipt
// "requires_payment" → send the payer intent.payment.payment_url

from openintents import OpenIntents

oi = OpenIntents()
intent = oi.intents.wait(oi.intents.create("book an Uber to SFO at 7am", max_amount=6000)["id"])

openintents run "restock the fridge for the week" --max 120 --wait

How an intent works

1. Call the API with an intent. Plain language, a spending cap in cents, optional structured context.
2. The API does the agentic work. Behind the endpoint, a real browser finds the merchant, picks the item and gets to checkout.
3. Pay from the payer's wallet. Intents use your account's wallet, or the customer's wallet when you pass customer, within the limits the payer sets there. Set require_payment_link to request a payment link before paying, even when the wallet is ready. If payment needs a step first, the intent returns requires_payment with a payment_url and a reason, such as connect_wallet or add_money. For wallet steps (connecting it, adding money, an identity check), the intent carries on by itself once the payer is done.
4. Get the receipt. Merchant, items, total, fee and confirmation, as JSON. Webhooks fire as the intent moves (intent.completed, intent.requires_payment, intent.requires_input, intent.failed and the rest of the list in the spec).

Repository layout

Path	What
spec/openapi.yaml	The v1 API: the contract every SDK follows
sdk/typescript/	@tinyhumansai/openintents: SDK + CLI
sdk/python/	openintents on PyPI: sync and async clients
sdk/rust/	openintents on crates.io
sdk/skill/openintents/	Agent skill (also SKILL.md)
sdk/plugin-claude/	Claude Code plugin
sdk/examples/	One runnable example per language

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md and AGENTS.md (which coding agents read too). Report security issues privately: SECURITY.md.

License

GPL-3.0-or-later.