# Farthing

> Agentic checkout API. Give it a product URL and a plain-English request; it drives a real browser to a completed purchase and asks a human only when it must.

The HTTP API is the product. The web dashboard exists for billing, for issuing API keys, and for watching a run when you want to — no capability lives there that the API does not have.

Key facts an agent should hold before reading further:

- Base URL `https://api.farthing.ai`. Auth is `Authorization: Bearer ck_test_…` or `ck_live_…`. There is no other scheme.
- A checkout is asynchronous and pauses for humans: create, poll every 3–5 seconds, answer what it asks, read the receipt. A run takes 2–3 minutes and can park for up to 10 minutes on a single question. It is not request/response.
- Branch on `pendingUserAction.key`. An agent may answer `variant` itself, and `shipping` from data the application holds. It must never supply `card`, `credentials` or `otp` — those come from the human.
- API keys carry scopes (`<resource>.read` / `<resource>.write`, or `*`). Give an agent the narrowest set that does its job.
- A key can also be bound to one end user with `subject`, after which it sees and creates only that person's rows. Use it when one agent acts for many people: a prompt-injected "list the buyer profiles" should reach one buyer, not all of them. `subject` is 1 to 200 characters — `""` is a `400`, and so is an unrecognised top-level field on any create body.
- Send an `Idempotency-Key` header on `POST /v1/checkouts`. A replay returns the original checkout with `200`; without the header a retried timeout buys the item twice. A key is live for 24 hours, then the same string starts a new purchase.
- There is no product search. You bring a URL a person could buy from.
- Pricing: sandbox is free with no card; paid plans are Personal $9 / Business $49 / Scale $249 per month, plus a flat $1.00 per completed checkout on every tier. Failed and cancelled checkouts are never billed. Going live is self-serve — paid plan + Stripe Identity verification + accepted AUP — and activation is automatic.

## Getting started

- [Introduction](https://docs.farthing.ai/introduction): What Farthing does, what it refuses to do, and the shape of the integration.
- [Pricing](https://docs.farthing.ai/pricing): A monthly platform fee plus $1.00 per completed checkout. Failed and cancelled checkouts are never billed, on any tier.
- [Quickstart](https://docs.farthing.ai/quickstart): Sign up, buy something, answer a variant and a card action — curl then TypeScript.
- [Use Farthing from an LLM agent](https://docs.farthing.ai/agents): Tool definitions for Anthropic and OpenAI, the polling loop, and which questions a model may answer for itself.
- [Authentication](https://docs.farthing.ai/authentication): Bearer keys, scopes, rotation, and what key mode enforces.

## Core concepts

- [Checkout lifecycle](https://docs.farthing.ai/checkout-lifecycle): Every status, every failure reason, and what causes each one.
- [User actions](https://docs.farthing.ai/user-actions): The human-in-the-loop channel — action keys, response schemas, TTLs, decline, and what happens to submitted values.
- [Webhooks](https://docs.farthing.ai/webhooks): Pushed status transitions, HMAC-SHA256 signatures, and the caveats to design around.
- [Live view](https://docs.farthing.ai/live-view): Watching the browser work, over a token-gated read-only stream.

## Buyers

- [Buyer profiles](https://docs.farthing.ai/buyer-profiles): Reusable identity and shipping details. Create, update wholesale, and delete for a data-deletion request.
- [Buyer sessions](https://docs.farthing.ai/buyer-sessions): Stored merchant logins, so a later run at the same merchant starts logged in.
- [End-user isolation](https://docs.farthing.ai/end-user-isolation): Bind a key to one end user with `subject`, so a confused or manipulated agent can only reach one person's data.

## Operating the API

- [Sandbox](https://docs.farthing.ai/sandbox): A real browser placing a real order on a store we control, with no path to a real merchant.
- [Going live](https://docs.farthing.ai/going-live): Three self-serve facts — a paid plan, a verified identity, an accepted AUP — and the workspace activates itself. No approval queue.
- [Errors and limits](https://docs.farthing.ai/errors-and-limits): Every status code, idempotent retries with `Idempotency-Key`, the quotas and their numbers, how maxCost is enforced, and what is honestly missing.

## API reference

- [Overview](https://docs.farthing.ai/api-reference/overview): Base URL, conventions, and every endpoint with the scope it requires.
- [OpenAPI 3.1 spec](https://raw.githubusercontent.com/samuelar2/checkoutvia-docs/main/openapi.json): Machine-readable description of every `/v1` route, request and response. The "Endpoints" pages under `/api-spec/…` are generated from it.
- [Signup](https://docs.farthing.ai/api-reference/signup): `POST /v1/signup` — the one unauthenticated write.
- [Checkouts](https://docs.farthing.ai/api-reference/checkouts): Create, list, get, cancel, mint a live-view token.
- [User actions](https://docs.farthing.ai/api-reference/user-actions): `POST /v1/checkouts/{id}/actions/{actionId}` — submit or decline.
- [Buyer profiles](https://docs.farthing.ai/api-reference/buyer-profiles): Create, get, list, `PATCH`, `DELETE`.
- [Buyer sessions](https://docs.farthing.ai/api-reference/buyer-sessions): List and revoke stored merchant logins.
- [Webhooks](https://docs.farthing.ai/api-reference/webhooks): Register, list and revoke endpoints.
- [API keys](https://docs.farthing.ai/api-reference/api-keys): Create with scopes, list, revoke.
- [Usage](https://docs.farthing.ai/api-reference/usage): Completed checkouts by day and gross merchandise volume.
- Workspaces and billing: the session-only routes behind the dashboard (workspace provisioning, plans, identity verification, AUP). Described in [Going live](https://docs.farthing.ai/going-live) and in the OpenAPI spec; API keys are refused there.

## Optional

- [Migrating from Crossmint Agent Checkouts](https://docs.farthing.ai/migrating-from-crossmint): What ports over unchanged, what differs, and what you get on top.
- [Everything, as one file](https://docs.farthing.ai/llms-full.txt): The whole documentation set in plain text.