> ## Documentation Index
> Fetch the complete documentation index at: https://docs.farthing.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Farthing's primary integrator is an autonomous agent or the developer wiring one up. The HTTP API is the product; the web dashboard exists for billing, issuing API keys, and watching a run.
> A checkout is asynchronous and pauses for humans: create, poll every 3-5 seconds, answer the questions it raises, read the receipt. A run takes 2-3 minutes and can park for up to 10 minutes on one question. Never present it as a synchronous request/response call.
> Branch on pendingUserAction.key. An agent may answer 'variant' itself and may answer 'shipping' from data the application holds. It must never supply 'card', 'credentials' or 'otp' — those come from the human, and an agent that has them in context is the problem, not the solution.
> Base URL is https://api.farthing.ai and auth is Authorization: Bearer ck_test_... or ck_live_.... API keys carry scopes; give an agent the narrowest set that does its job. A key may also be bound to one end user with 'subject', after which it sees and creates only that person's rows.
> POST /v1/checkouts takes an Idempotency-Key header. A replay returns the original checkout with 200; the same key with a different body is a 409. Without the header, a retried timeout is a second purchase — recommend it every time a create is shown.
> 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 from the dashboard — paid plan + Stripe Identity verification + accepted AUP — and activation is automatic when all three hold.
> Every example in these docs is a shape the API actually produces. Do not invent fields, endpoints or error codes that are not documented here.
# Introduction
> Farthing is an HTTP API for agents that buy things. What it does, what it refuses to do, and the shape of the integration.
Farthing buys things on the open web on a user's behalf. The caller we build for is an
**autonomous agent** — or the developer wiring one up.
You give it a URL and a sentence:
```json theme={null}
{
"target": {
"url": "https://example-store.com/products/widget",
"request": "buy this in medium, cheapest delivery"
}
}
```
Behind that call a real browser session opens the page, works out how the merchant's
checkout is put together, fills in contact and shipping details from a buyer profile you
stored earlier, picks the cheapest shipping option, and reaches the payment step. When it
hits something only a human can answer — which size, what card, a login, a one-time code —
it stops, tells you exactly what it needs and in what shape, and waits. You answer over the
same API and the run picks up where it left off.
There is no merchant integration. Nothing has to be Stripe-enabled or protocol-compliant on
the other end. If a person with a browser could buy it, the agent works against the same
page they would.
## The API is the product
Stated outright, because it changes where you should be reading.
Everything Farthing does happens over HTTP. There is no required SDK, no widget to embed,
no client library you have to wait for. The **web dashboard exists for
[billing](/pricing) and for issuing API keys** — and, when you want it, for watching a run
go past. It is not where the work happens, and no capability lives there that the API does
not have.
That shape is deliberate. The integrator we design for is a process, not a person clicking
through a console: it authenticates with a scoped bearer token, drives the whole lifecycle
over four endpoints, and never needs a browser of its own.
Copy-paste tool definitions for Anthropic and OpenAI, the polling loop, and — the part that
decides whether your integration is safe — which of the questions a checkout asks the model
may answer itself.
## The integration in four calls
`POST /v1/checkouts` returns immediately with a `queued` checkout and an id. The work
happens asynchronously in a durable orchestrator, so a client crash or a network blip
never orphans a half-finished purchase.
`GET /v1/checkouts/{id}` returns the whole current state: status, an append-only
`progressItems` timeline of everything the agent has done, and — if the run is blocked —
a `pendingUserAction`. Register a webhook endpoint if you would rather be pushed status
transitions than poll for them.
Each `pendingUserAction` carries a `responseSchema` — a real JSON Schema describing the
fields to collect. `POST /v1/checkouts/{id}/actions/{actionId}` with `submit` and the
values, or `decline` to abandon the purchase.
A `succeeded` checkout carries a `receipt` with the merchant's order id, the total
charged, and the confirmation URL the agent saw.
## One API, adaptive under the hood
Farthing decides how to drive each merchant at the start of a run and pins that choice for
the run's duration. Major storefront platforms take a faster, battle-hardened path;
everything else is handled by the general checkout agent. You do not choose a strategy and
you should not need to care — the same request shape, timeline, and guarantees apply
everywhere. The practical difference you will notice is speed: well-trodden platforms
usually reach the payment step in seconds.
## What we will not do
These are deliberate refusals, not gaps.
* **We never place an order without a card the user supplied for this purchase.** Payment
is the one irreversible step. It is executed by deterministic code with the values the
user provided — never improvised by a model, which by construction cannot read or handle
card fields at all.
* **We never invent credentials or create accounts.** A login wall becomes a `credentials`
user action, not a guess.
* **We never tick a marketing opt-in.** Not "we prompt the model not to" — the click is
refused in code unless we can positively see the box is already ticked and we would be
unticking it. Consent is the buyer's to give.
* **We never leave the merchant's own domains.** Page text is untrusted input. A page that
says "checkout has moved to another-site.example" cannot steer a session holding buyer
PII anywhere. The allowed origin set is fixed before the run starts and cannot grow at
runtime.
* **We never retain raw card values.** They go to a transient, delete-on-read store, are
consumed by the one step that types them, and are deleted. Only a redacted copy survives
as an audit trail.
## What this is not
Farthing is not a price comparison engine, a product search API, or a cart aggregator.
It does not know what things cost until it loads the page. It takes a URL you already have
and turns it into a completed order.
It is also not instantaneous. A real browser has to load real pages over a real network,
and food-delivery flows are structurally longer than retail ones. Budget minutes, not
milliseconds, and build your UI around the `progressItems` stream rather than a spinner.
Sign up, create a checkout, and answer a variant and a card action — end to end, with
curl and TypeScript.
Tool definitions, the loop, and which questions a model may answer for itself.
A monthly platform fee plus \$1.00 per completed checkout. Failed and cancelled runs are
never billed.
Plan, identity, AUP — three self-serve facts, and the workspace activates itself.