> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Agentcard is for companies whose agent buys for their users. Pick one path: the opencommerce SDK (@agent-cards/commerce-sdk) gives your agent one buy tool that finds the product, builds the cart, gets the user's approval and places the order at real stores; the Agentcard SDK (@agent-cards/sdk) pays with the user's own card when your agent already shops in a browser (Browser Use, Kernel, Browserbase, Anchor or Notte); the Purchase API (POST /buy) does the same purchase flow over plain HTTP in any language; Issuing gives the agent its own card.
> Start with `npx agent-cards init` in the app's folder (Node 22 or later). No invite is needed: it creates your Agentcard account if you don't have one, installs the opencommerce SDK and puts the credentials in the env file, kept out of git. From a coding agent, run `npx agent-cards init --print --categories all --implementation tool --wallet vault --skip-install` to get the setup steps to apply yourself.
> Vault is by invitation: request it at https://agentcard.com/get-started?utm_source=docs&utm_medium=llms&utm_campaign=agent-instructions. opencommerce needs no invite.
> Never ask a user for a card number, expiry date or CVV in chat. Send them the Vault link; they add their card on Agentcard's page, and the agent never sees the number.
> Every purchase is approved by the user, with a passkey or Face ID, or by an auto-approval they granted. An approval covers one merchant and one exact total. If the total changes, ask again. When a result says the user already said yes, don't ask again.
> `init` writes PRODUCTION credentials, which place real orders, so test in sandbox first. For opencommerce, run `npx agent-cards credentials --mode sandbox` and put the two lines it prints in place of the production ones in the env file `init` wrote, because that command only prints them; sandbox then runs the whole flow against real stores and stops before payment, so no order is placed and nobody is charged. For Vault and Issuing, sandbox credentials issue test cards that no real merchant accepts; try the checkout against shop.agentcard.sh, a test store on Stripe test mode.
> Tell the user an order is placed only after Agentcard reports it placed.
> Vault is free up to 5,000 users (https://agentcard.com/pricing). opencommerce takes 1% of each completed order. Full docs in one file: https://docs.agentcard.com/llms-full.txt

# Show each store as it is searched

> Show the shopper every store Agentcard is searching, and what each one answered, from the first second of the search.

A search for "a men's linen shirt" asks several stores at once. Your chat can show each store the moment Agentcard starts on it, `checking Gap`, and change the line when the store answers: two shirts at Gap, nothing at 1-800-Flowers, Sephora too slow to wait for. The shopper sees work happening before the first product arrives.

> [!NOTE]
>
> Store statuses are not on for every company yet. Until they reach yours, your app hears no store update and the answer carries no `search`, so code written from this guide shows no store line and needs no change when they turn on.

## Show each store as it changes

Agentcard sends a store's status each time it changes: `searching` when Agentcard starts on the store, then the status it ends with. An update carries these fields:

| Field | What it holds |
| - | - |
| Conversation id | The conversation the search serves. |
| Search id | This message's search. A later message that searches again has a new one. |
| `merchant` | The store's id, such as `gap`, or its domain, such as `livlyclothing.com`. |
| Merchant name | The store's name to show the shopper, such as `Gap`. |
| `status` | Where the store stands. See [Read each status](#read-each-status). |
| `results` | How many products the search found at the store. |
| `confirmed` | How many of them had their price and stock read at the store in this search or the last hour. |
| First result time | Milliseconds from the start of the store's search to its first product, or `null`. |
| `ms` | Milliseconds the store's search took, or has taken so far. |

Match each line to its store by `merchant`, and replace the line on each update. A store can change more than once in an answer, and a store searched twice reads `searching` again.

> [tab] SDK
>
> Pass `onMerchantStatus` to the buy tool:
>
> ```ts chat.ts theme={null}
> const buy = buyTool({
>   agentcard,
>   externalUserId: shopper.id,
>   onMerchantStatus: (update) => showStoreLine(shopper.id, update.merchant, update.merchantName, update.status), // your code
> });
> ```
>
> The fields are `conversationId`, `searchId`, `merchant`, `merchantName`, `status`, `results`, `confirmed`, `firstResultMs` and `ms`.

> [tab] MCP
>
> The MCP server sends no store updates. The `buy` result lists the products the search found, so show those.

> [tab] API
>
> Ask for a streamed answer, which sends each part as soon as it is ready, as server-sent events. Add `?stream=1`:
>
> ```bash theme={null}
> curl -N "https://api.agentcard.sh/buy?stream=1" \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{ "external_user_id": "user-42", "ask": "a men'\''s linen shirt" }'
> ```
>
> Each change arrives as a `merchant` event. This run shows each event's `data` with the milliseconds since the call started:
>
> ```text theme={null}
> event: merchant  2625 ms  {"merchant":"gap","merchant_name":"Gap","status":"searching","results":0,"confirmed":0,"first_result_ms":null,"ms":5}
> event: merchant  2625 ms  {"merchant":"sephora","merchant_name":"Sephora","status":"searching","results":0,"confirmed":0,"first_result_ms":null,"ms":4}
> event: merchant  3025 ms  {"merchant":"1800flowers","merchant_name":"1-800-Flowers","status":"no_results","results":0,"confirmed":0,"first_result_ms":null,"ms":402}
> event: merchant  3443 ms  {"merchant":"gap","merchant_name":"Gap","status":"confirmed","results":2,"confirmed":2,"first_result_ms":591,"ms":821}
> event: merchant  4722 ms  {"merchant":"sephora","merchant_name":"Sephora","status":"timed_out","results":0,"confirmed":0,"first_result_ms":null,"ms":2091}
> ```
>
> Each event also carries `conversation_id` and `search_id`. A call without `?stream=1` gets no `merchant` events.

## Read each status

| Status | What it means | What to show |
| - | - | - |
| `searching` | Agentcard is still searching the store. | `checking Gap` |
| `confirmed` | The store's own site answered with products, their price and stock read in this search. | `2 at Gap` |
| `recently_confirmed` | Products Agentcard already knew, their price and stock read at the store in the last hour. | `3 at Target` |
| `confirmation_unavailable` | Products found for the store, none read at the store in this search. Their prices are read again at checkout. | `4 at Walmart` |
| `no_results` | The store answered, with nothing for the ask. | `none at 1-800-Flowers` |
| `timed_out` | Agentcard answered without the store, which was still being searched. | `Sephora is slow right now` |
| `failed` | The store's search failed. | `couldn't reach Amazon` |
| `unavailable` | Agentcard could not reach the store this time. | `still loading Walmart` for a store the shopper named; nothing for one they did not name |

A `timed_out`, `failed` or `unavailable` store says nothing about whether the store carries the product. Tell the shopper so in your own words, and never as "none at Sephora".

A shopper who asked for a candle at Walmart while Agentcard could not reach Walmart reads `still loading Walmart` beside the products from the stores that did answer. A store the shopper did not name gets no line: it drops out, and the other stores fill the answer.

> [tab] SDK
>
> Pass the stores the shopper named to `merchantStatusLine`, and show the line it gives:
>
> ```ts chat.ts theme={null}
> import { merchantStatusLine } from '@agent-cards/commerce-sdk';
>
> const onMerchantStatus = (update) => {
>   const line = merchantStatusLine(update, shopper.namedStores); // your list, such as ['walmart.com']
>   if (line) showNote(shopper.id, line); // "still loading Walmart"
> };
> ```
>
> For the whole answer at once, `searchStatusLines(result.search ?? null, shopper.namedStores)` gives every line. An app on an SDK version before 0.18.8 leaves an `unavailable` store out and never hears its update.

> [tab] MCP
>
> The MCP server sends no store statuses, so there is no line to word.

> [tab] API
>
> Word each line yourself from `status` and `merchant_name`, and keep your own list of the stores the shopper named.

## Read every store at the end

The answer's `search` holds every store the search asked, in the order their searches started, with the same fields. `final` is `true` once no store is still being searched. While it reads `false`, show a note such as "still checking a store or two". `search` is `null` for an answer that searched no store, such as a reply about the cart.

> [tab] SDK
>
> ```ts chat.ts theme={null}
> const result = await turn.answer(input);
> for (const store of result.search?.merchants ?? []) showStoreLine(shopper.id, store.merchant, store.merchant_name, store.status);
> if (result.search && !result.search.final) showNote(shopper.id, 'still checking a store or two'); // your code
> ```
>
> A chat that searched one store reads that store's line with `searchAt`, which matches the store by its id, its domain, or its name:
>
> ```ts store-line.ts theme={null}
> import { searchAt, isMerchantStatusAt } from '@agent-cards/commerce-sdk';
>
> const gap = searchAt(result.search ?? null, 'gap.com')?.merchants[0]; // the one line, or undefined when the answer did not search Gap
> const onMerchantStatus = (update) => {
>   if (isMerchantStatusAt(update, 'gap.com')) showStoreLine(shopper.id, update.merchant, update.merchantName, update.status);
> };
> ```

> [tab] MCP
>
> The `buy` result has no `search` list. There is nothing to read at the end.

> [tab] API
>
> The stream ends with an `envelope` event, which carries the whole answer. A call without `?stream=1` carries the same body:
>
> ```json theme={null}
> {
>   "status": "needs_input",
>   "conversation_id": "conv_...",
>   "search": {
>     "search_id": "srch_...",
>     "final": true,
>     "elapsed_ms": 2096,
>     "merchants": [
>       { "merchant": "gap", "merchant_name": "Gap", "status": "confirmed", "results": 2, "confirmed": 2, "first_result_ms": 591, "ms": 821 },
>       { "merchant": "sephora", "merchant_name": "Sephora", "status": "timed_out", "results": 0, "confirmed": 0, "first_result_ms": null, "ms": 2091 },
>       ...
>     ],
>     "index": { "results": 12, "ms": 35 }
>   }
> }
> ```
>
> `index` holds how many products came from Agentcard's own list of products it has seen before, and how long that lookup took, or `null` when the answer used none.

## Check it in the sandbox

Once store statuses are on for your company, try them in the sandbox, Agentcard's test mode, which charges nothing:

1. Ask for "a men's linen shirt" as a test shopper, over the SDK or the API with `?stream=1`.
2. Check that a line appears for each store, `searching` first.
3. Check that each store's line changes as it answers, and that the answer's `search` lists the same stores with `final: true`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.