# OttoAuth Developer Documentation

OttoAuth lets agents submit commerce orders through one provider-capability router without taking custody of the human's retailer credentials or payment details.

## Send This To Your Coding Agent

```text
Integrate OttoAuth into this codebase.

Read these first, in this order:
1. https://ottoauth.vercel.app/llms.txt
2. https://ottoauth.vercel.app/llms-full.txt
3. https://ottoauth.vercel.app/skill.md
4. https://ottoauth.vercel.app/api/services
5. https://ottoauth.vercel.app/api/services/order/docs

Use dashboard-generated OttoAuth credentials:
- OTTOAUTH_USERNAME=<human dashboard generated username>
- OTTOAUTH_PRIVATE_KEY=sk-oa-<human dashboard generated secret>
- OTTOAUTH_BASE_URL=https://ottoauth.vercel.app

For a human-facing web checkout button:
- Load https://ottoauth.vercel.app/checkout.js.
- Call `OttoAuth.buy({ task, max, files })` from the click handler.
- `max` is cents; use `maxUsd` for dollar values.
- Do not add local OttoAuth auth, local checkout-session routes, or private keys to the app. OttoAuth handles login, account creation, confirmation, files, and fulfillment after the click.

Build against the general order API:
- Submit orders with POST https://ottoauth.vercel.app/api/services/order/submit.
- Before live submission, test order shapes with dry_run: true. Dry runs need no credentials, create no DB rows, charge no credits, and queue no fulfillment.
- Put store-specific intent in fields like store, merchant, store_url, item_name, quantity, order_details, shipping_address, estimated_total_cents, and max_charge_cents.
- max_charge_cents is required for real orders. estimated_total_cents is optional and non-binding; display order.pricing to users and treat max_charge_cents as the hard fulfillment limit.
- For CAD, PCB, BOM, artwork, or document uploads, POST files to https://ottoauth.vercel.app/api/services/order/files first and pass the returned files[] into submit.
- Discover the focused 50-platform catalog at https://ottoauth.vercel.app/api/services/order/platforms.
- Do not use store-specific endpoints for Amazon, Snackpass, or other stores.
- Save order.id, for example ord_123. task.id is kept only for compatibility.
- Poll POST https://ottoauth.vercel.app/api/services/order/tasks/<orderId> until completed, failed, canceled, disputed, blocked, or human_required.
- If status is blocked, answer through the clarification endpoint.
- Use POST https://ottoauth.vercel.app/api/services/order/tasks/<orderId>/messages for provider/operator messages and POST https://ottoauth.vercel.app/api/services/order/tasks/<orderId>/disputes for disputes.

Security rules:
- Never ask the human for retailer passwords, card numbers, CVVs, bank details, or one-time codes.
- Never exceed max_charge_cents.
- Use only services with status active or beta.
```

## Human Setup

1. Sign in at https://ottoauth.vercel.app/login.
2. Open https://ottoauth.vercel.app/dashboard.
3. Pick a unique OttoAuth username address such as @alice.
4. Generate Agent API Keys and give the username plus private key to your coding agent.
5. Add credits before submitting orders.

## Browser Buy Button

For human-facing apps, use one script tag and one function call. The app should
not store OttoAuth credentials, create checkout sessions, upload files through a
local proxy, or manage OttoAuth login.

```html
<script src="https://ottoauth.vercel.app/checkout.js"></script>
<button id="buy">Buy</button>
<script>
  buy.onclick = () => OttoAuth.buy({
    task: "Print this T-shirt design on one medium natural cotton tee.",
    max: 2000,
    files: ["#shirtSvg"]
  });
</script>
```

`max` is cents. Use `maxUsd: 20` if the app works in dollars. Optional
fields such as `title`, `merchant`, `item`, `quantity`, `shipping`,
`quote`, `details`, and `metadata` only improve the hosted confirmation
page and operator context.

## LLM-Friendly Markdown

- Short AI-readable index: https://ottoauth.vercel.app/llms.txt
- Full-context AI-readable docs: https://ottoauth.vercel.app/llms-full.txt
- Agent operating skill: https://ottoauth.vercel.app/skill.md
- This page as Markdown: https://ottoauth.vercel.app/docs.md
- Machine-readable service catalog: https://ottoauth.vercel.app/api/services
- General order Markdown docs: https://ottoauth.vercel.app/api/services/order/docs

## Core Integration Contract

- Use `/api/services/*` for hosted agent integrations.
- Use dashboard-generated `username` and `private_key` on service calls.
- Use the general order endpoint for Amazon, Snackpass, and any other store.
- Use `dry_run: true` to validate payloads before creating a real order.
- Pass store-specific details as `store`, `merchant`, `store_url`, `item_name`, `quantity`, `order_details`, `shipping_address`, and `max_charge_cents`.
- Real orders require `max_charge_cents`. OttoAuth returns `order.pricing` with estimated, quoted, or final price state. Estimates are not final charges.
- Upload CAD, PCB, BOM, artwork, or document files through `/api/services/order/files`, then include the returned `files[]` references on the order.
- Use `/api/services/order/platforms` to inspect the focused 50-platform catalog.
- Save `order.id`.
- Poll task status every 15-60 seconds.
- Use messages, clarification, cancellation, and dispute endpoints for follow-up.
- If no provider API is enabled, OttoAuth routes the order to the admindash human fulfillment queue.

## 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

## General Order

Status: active

Submit, track, message, clarify, cancel, and dispute commerce orders through one provider-capability router with human admin fallback

Tool JSON: https://ottoauth.vercel.app/api/services/order

Markdown docs: https://ottoauth.vercel.app/api/services/order/docs

### submit_order

`POST /api/services/order/submit`

Create a canonical OttoAuth order. OttoAuth stores a non-browser quote when available, uses a native provider API when enabled, otherwise routes the order to the admindash human fulfillment queue.

Parameters:
  - `username` (string, required): Agent username.
  - `private_key` (string, required): Agent private key.
  - `store` (string, optional): Store or platform, such as amazon, treatstock, xometry, jlcpcb, instacart, uber, ubereats, or snackpass. Omit when the app wants OttoAuth to choose the route.
  - `platform` (string, optional): Alias for store.
  - `merchant` (string, optional): Specific merchant, restaurant, retailer, manufacturer, or store name.
  - `store_url` (string, optional): Product, menu, quote, order, receipt, tracking, return, or merchant URL.
  - `kind` (string, optional): Optional order kind: retail_purchase, grocery_delivery, restaurant_delivery, ride, manufacturing_3d_print, or manufacturing_pcb.
  - `task_prompt` (string, optional): Freeform work order. Required only when structured fields do not fully describe the order.
  - `items` (array, optional): Structured item rows with name, quantity, details, and url.
  - `files` (array, optional): Structured file references for CAD, PCB, or quote-first manufacturing orders.
  - `order_type` (string, optional): shipping, delivery, pickup, quote, order, return, cancellation, refund, exchange, support, status_check, or dispute.
  - `pickup_location` (string, optional): Pickup, destination, or search location.
  - `shipping_address` (string, optional): Shipping or delivery address to use exactly as written.
  - `item_name` (string, optional): Single item shorthand when items[] is not used.
  - `quantity` (string, optional): Single item quantity shorthand.
  - `order_details` (string, optional): Variants, modifiers, substitutions, quote requirements, account/order numbers, or other instructions.
  - `max_charge_cents` (number, optional): Required for real orders; optional for dry_run previews. Maximum spend in cents. Human operators and native adapters cannot complete above this cap without approval.
  - `estimated_total_cents` (number, optional): Optional non-binding estimate from the integrating app. OttoAuth returns it in order.pricing and still enforces max_charge_cents as the hard limit.
  - `quote` (object, optional): Optional manual/operator price quote. Supports total_cents, goods_cents, shipping_cents, tax_cents, currency, confidence, source, and source_label.
  - `dry_run` (boolean, optional): When true, validate and preview routing without authentication, credit checks, DB rows, or fulfillment.

### quote_order

`POST /v1/quotes`

Return the best non-browser price quote for an order request without creating an order. Uses manual price fields, deterministic direct Amazon product-page scraping, curated McMaster-Carr/DigiKey estimate catalogs, configured supplier APIs, configured JLC pricing models, then retroactive billing fallback.

Parameters:
  - `Authorization` (string, required): Bearer private key.
  - `task_prompt` (string, optional): Freeform work order used to detect supplier context and pricing strategy.
  - `store` (string, optional): Store or platform, such as amazon, digikey, mcmaster, mouser, ebay, jlcpcb, or manual.
  - `store_url` (string, optional): Product or merchant URL. Direct Amazon product links are scraped server-side without browser automation.
  - `quote` (object, optional): Optional manual/operator quote. Supports total_cents, goods_cents, shipping_cents, tax_cents, currency, confidence, source, and source_label.

### upload_order_files

`POST /api/services/order/files`

Upload CAD, Gerber, BOM, artwork, document, or personalization files before creating an order. Returns file references to pass in submit_order.files[].

Parameters:
  - `username` (string, required): Agent username for JSON uploads or multipart forms.
  - `private_key` (string, required): Agent private key for JSON uploads or multipart forms.
  - `file` (file, optional): Multipart file field. Repeat file/files for multiple uploads.
  - `files` (array, optional): JSON files with filename, content_type, content_base64, purpose, and optional metadata.
  - `purpose` (string, optional): cad_model, gerber_zip, bom, cpl, artwork, proof, document, or order_attachment.

### platform_catalog

`GET /api/services/order/platforms`

Return the focused 50-platform coverage catalog used for provider recognition, file-upload support, homepage coverage, and operator routing.

Parameters:
  - none

### get_order_status

`POST /api/services/order/tasks/:taskId`

Return normalized order state, provider capabilities, payment fields, messages, and event timeline.

Parameters:
  - `taskId` (string, required): Order id returned by submit_order, such as ord_123.
  - `username` (string, required): Agent username.
  - `private_key` (string, required): Agent private key.

### history

`POST /api/services/order/history`

List recent canonical orders submitted by this agent.

Parameters:
  - `username` (string, required): Agent username.
  - `private_key` (string, required): Agent private key.

### cancel_order

`POST /api/services/order/tasks/:taskId/cancel`

Cancel an order that has not completed. Native providers are handled by an adapter when available; otherwise the human queue sees the cancellation state.

Parameters:
  - `taskId` (string, required): Order id returned by submit_order.
  - `username` (string, required): Agent username.
  - `private_key` (string, required): Agent private key.
  - `reason` (string, optional): Cancellation reason.

### send_order_message

`POST /api/services/order/tasks/:taskId/messages`

Record an agent message for requester, operator, vendor, shopper, driver, or provider follow-up. If no native messaging API exists, the message is flagged for human delivery.

Parameters:
  - `taskId` (string, required): Order id returned by submit_order.
  - `username` (string, required): Agent username.
  - `private_key` (string, required): Agent private key.
  - `channel` (string, optional): provider_vendor, requester, human_operator, driver, shopper, or support.
  - `message` (string, required): Message body.

### respond_clarification

`POST /api/services/order/tasks/:taskId/clarification`

Answer an open operator/provider clarification so the order can resume from blocked to human_required or ready_to_fulfill.

Parameters:
  - `taskId` (string, required): Order id that is awaiting clarification.
  - `username` (string, required): Agent username.
  - `private_key` (string, required): Agent private key.
  - `clarification_id` (number, optional): Specific clarification id; defaults to the newest open clarification.
  - `clarification_response` (string, required): Answer to the clarification question.

### open_dispute

`POST /api/services/order/tasks/:taskId/disputes`

Open a dispute/refund/support case against a completed or problematic order. Native dispute APIs can be added per provider; otherwise admindash exposes it to an operator.

Parameters:
  - `taskId` (string, required): Order id.
  - `username` (string, required): Agent username.
  - `private_key` (string, required): Agent private key.
  - `reason` (string, required): Dispute reason.
  - `requested_resolution` (string, optional): Refund, replacement, cancellation, status correction, or other desired resolution.
  - `evidence` (object, optional): Optional structured evidence payload.

### v1_orders

`POST /v1/orders`

Resource-oriented v1 alias for submit_order. Also supports GET with Authorization: Bearer <private_key> to list recent orders.

Parameters:
  - `Authorization` (string, optional): Bearer private key. Body username/private_key still works for POST.

## OttoAuth Wallet

Status: active

Resolve OttoAuth usernames and let linked agents send credits to human or linked-agent addresses.

Tool JSON: https://ottoauth.vercel.app/api/services/wallet

Markdown docs: https://ottoauth.vercel.app/api/services/wallet/docs

### resolve_address

`POST /api/services/wallet/resolve`

Resolve an OttoAuth address such as @alice or a linked agent username before sending money.

Parameters:
  - `username` (string, required): Agent username.
  - `private_key` (string, required): Agent private key.
  - `recipient` (string, required): OttoAuth username, @address, linked agent username, or profile URL.

### send_money

`POST /api/services/wallet/send`

Send OttoAuth credits from the human wallet linked to this agent to another OttoAuth username address.

Parameters:
  - `username` (string, required): Agent username.
  - `private_key` (string, required): Agent private key.
  - `recipient` (string, required): OttoAuth username address, for example @alice or @alice_agent.
  - `amount_cents` (number, required): Amount in cents.
  - `note` (string, required): Short payment note shown in the credit ledger.