# agentPickup AGENTS.md > Commerce and fulfilment infrastructure for AI agents buying from physical businesses. An agent finds a business, orders, and pays or hands the customer the business's own checkout; the person collects in person with a signed QR that staff scan. This is the starting point for AI agents that order from agentPickup shops. The short index is [llms.txt](https://agentpickup.app/llms.txt), and the guide for developers and platforms is [docs/developers](https://agentpickup.app/docs/developers). ## The easy way: the MCP server Connect to `https://agentpickup.app/mcp` (streamable HTTP), or run `npx -y @agentpickup/mcp`. A cards-only version, with no USDC tools, is at `https://agentpickup.app/mcp/cards`. Its tools cover every step below. Run locally with no wallet key, it hands each payment to the wallet the user already has, such as Coinbase's agent wallet. Agents that use skills can install these instructions as one: `npx skills add Tokenise-au/agentpickup-sdk`. ## Ordering for a user, step by step 1. **Find a shop.** `GET https://agentpickup.app/directory/v1/shops` with `q` (what the user wants), `place` (a suburb), or `lat` and `lng` with an optional `radius_km`. Add `open_now=true` for shops open now. Each result's `url` is the shop's address; the steps below use it as `{shop}`. 2. **Read the menu.** `GET {shop}/api/catalog` returns the items with their ids and prices, the pickup location, the payment methods the shop takes, and the shop's social accounts (`merchant.socials`). Items can carry `dietary` labels (vegan, gluten-free...), `allergens`, `calories`, an `image` and `soldOut`: don't order a sold-out item. For questions the menu doesn't answer (dietary needs, allergies, hours, parking), `POST {shop}/api/question` with `{"question": "gluten-free options?"}`; send the question without names or personal details. 3. **Confirm with the user.** Show the items, the total and where to collect, and wait for a yes before paying. 4. **Pay**, in one of three ways: - **From the agent's wallet** (x402, USDC on Base), where `payments.x402` is set: `GET {shop}/api/x402/order?items={id}:{qty},...` answers 402 with the price; pay it, and the response carries the order and the pickup pass. To have the QR emailed as well, `POST` the same address with `{"items": [{"id": "...", "qty": 1}], "email": "..."}`. - **By card, paid by the user**, where `payments.square` or `payments.card` is set: `POST {shop}/api/orders` with `{"items": [...], "email": "...", "rail": "square"}` (the shop's Square) or `"rail": "card"` (the shop's own Stripe), then give the user `next.url`, the shop's checkout page. The card is held until the order is collected. - **Free, to try the whole flow**, where `payments.test` is set: `POST {shop}/api/orders` with `{"items": [...], "email": "...", "rail": "test"}`. The order is marked paid with no money moving, and the response carries the pass link. With the MCP tools, `create_pickup_order` with `payment: "test"`. 5. **Hand over the pass.** Give the user the pass link and the pickup code. They show the QR at the counter, and staff scan it. `GET {shop}/api/orders/{id}` reports the status: paid, ready or collected. Keep the `claim` that `POST {shop}/api/orders` returns: `GET {shop}/api/orders/{id}/pass` with the header `X-Pickup-Claim: {claim}` fetches the pass again once it's paid. In chat apps that show cards, the MCP tools show the order as a card that becomes the pass and updates itself until it's collected, and the shop emails the pass as well. ## Questions about agentPickup itself When the user asks how agentPickup works rather than about a shop (how paying works, who sees their details, what happens if they don't collect, how a shop joins), answer from https://agentpickup.app/faq. ## Rules - Never pay before the user agrees to the items and the total. - Prices come from the shop's menu. Don't calculate or send prices yourself. - The pickup QR works like a ticket: whoever holds it can collect. Give it only to the user. - To try it for free, use a test payment at any shop with `payments.test` set. The Demo Café at https://agentpickup.app takes real USDC on Base, and the Demo Café on the test network, https://agentpickup.app/v/demo-cafe-testnet, takes testnet USDC on Base Sepolia. Neither makes anything. - To try paying by card, order from the Square Sandbox Café, https://agentpickup.app/v/square-sandbox-cafe, with `"rail": "square"` (MCP: `payment: "card"`), and pay on its checkout page with Square's test card 4111 1111 1111 1111, any future expiry and any CVV. Nothing is charged. - Standard x402 clients cap each payment at $1. Raise the cap for real orders, within the limit the user set. - If nobody collects in time, card payments are refunded. Whether USDC is paid back depends on the shop. ## Machine-readable files Every shop serves these under its own address: `/api/catalog`, `/openapi.json`, `/.well-known/agentpickup.json` (its directory listing), `/.well-known/ucp`, `/.well-known/acp.json`, `/.well-known/collect-keys.json` (the keys that verify a pass offline) and `/.well-known/did.json`. ## Open code - https://github.com/Tokenise-au/agentpickup-sdk: the pickup pass spec (`SPEC.md`) and library (`@agentpickup/core`), the MCP server (`@agentpickup/mcp`) and the agent skill. ## News agentPickup posts news, new shops and new features at https://x.com/agentPickup, and company news, pilots and partners at https://www.linkedin.com/company/agentpickup.