# OttoAuth for AI agents

OttoAuth lets AI agents submit commerce orders through a human-linked account without taking custody of the human's retailer passwords or payment credentials.

## Start Here

- [Full LLM context](https://ottoauth.vercel.app/llms-full.txt): Complete Markdown bundle for coding agents.
- [Agent operating skill](https://ottoauth.vercel.app/skill.md): Detailed hosted-agent workflow.
- [Human developer docs as Markdown](https://ottoauth.vercel.app/docs.md): Human docs in clean Markdown.
- [Human visual docs](https://ottoauth.vercel.app/docs): Browser-friendly docs for people.
- [Service index](https://ottoauth.vercel.app/api/services): Machine-readable service catalog.
- [General order API docs](https://ottoauth.vercel.app/api/services/order/docs): Markdown reference for the universal order endpoint.

## Stable Hosted Contract

- Browser apps can load https://ottoauth.vercel.app/checkout.js and call `OttoAuth.buy({ task, max, files })`. OttoAuth owns login, confirmation, file upload, and fulfillment after the click.
- Use only /api/services/* for normal hosted agent integrations.
- Authenticate service calls with dashboard-generated username + private_key.
- The human must generate Agent API Keys in https://ottoauth.vercel.app/dashboard and send them to you.
- The human must keep credits available.
- Use dry-run previews before real submissions when testing a store or generated payload.
- Submit flexible checkout, pickup, delivery, ride, manufacturing, cancellation, return, refund, and support orders through the active order service.
- Amazon, Snackpass, and other store-specific work goes through POST https://ottoauth.vercel.app/api/services/order/submit with store, merchant, store_url, item_name, and order_details fields.
- Show `order.pricing.display_total_cents` when present and `order.pricing.max_charge_cents` as the hard spend limit.
- Save order.id after submission.
- Poll task status every 15-60 seconds until completed, failed, canceled, disputed, blocked, or human_required.
- Cancel in-flight tasks with POST https://ottoauth.vercel.app/api/services/order/tasks/<taskId>/cancel when the human changes their mind before completion.
- Use messages for provider/operator communication, clarifications for blocked details, and disputes for support/refund cases.

## Default Agent Loop

1. Ask the human to sign in at https://ottoauth.vercel.app/login.
2. Ask the human to generate Agent API Keys in https://ottoauth.vercel.app/dashboard.
3. Store the returned username and private_key securely.
4. Ask the human to keep credits available.
5. GET https://ottoauth.vercel.app/api/services and choose a service with status active or beta.
6. For commerce orders, POST https://ottoauth.vercel.app/api/services/order/submit.
7. Store order.id and poll POST https://ottoauth.vercel.app/api/services/order/tasks/<orderId>.
8. Send messages, answer clarification, cancel, or open disputes through the order lifecycle endpoints.
9. If the human cancels, POST https://ottoauth.vercel.app/api/services/order/tasks/<taskId>/cancel.
10. If completed, report summary, pickup/tracking details, totals, and errors if present.

## Do Not

- Do not ask the human for retailer passwords or card numbers.
- Do not use legacy pairing-key flows for new integrations.
- Do not use old public browser-task APIs such as /api/services/computeruse/*, /api/computeruse/tasks*, /api/computeruse/runs*, /api/computeruse/register-device, /api/pay/amazon/create-session, or /api/pay/snackpass/create-session. They return 410 and point to /api/services/order/submit.
- Do not use lower-level /api/computeruse/device/* routes unless you are building worker-side fulfillment infrastructure.
- Do not call services marked coming_soon.
- Do not exceed max_charge_cents.

## Services

- [General Order](https://ottoauth.vercel.app/api/services/order): active; Submit, track, message, clarify, cancel, and dispute commerce orders through one provider-capability router with human admin fallback; markdown docs: https://ottoauth.vercel.app/api/services/order/docs
- [OttoAuth Wallet](https://ottoauth.vercel.app/api/services/wallet): active; Resolve OttoAuth usernames and let linked agents send credits to human or linked-agent addresses.; markdown docs: https://ottoauth.vercel.app/api/services/wallet/docs