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

# Choose how long a reply waits for stores

> Set how long Agentcard waits for store searches before it writes the reply, and whether a slower store's products still show after it.

Set how long a reply waits for the stores a search asks, and what happens to a store that answers after the reply. A chat that shows products as they come can show a slow store's products after the reply. A texting app sends the reply once, as its last word.

## Set the wait

Agentcard writes the reply once every store answered, or once your wait passed, whichever comes first. Leave the wait out and Agentcard chooses it.

The wait is in milliseconds. Agentcard ends every store search at 30 seconds, so a wait above 30 seconds waits no longer than 30 seconds does, and a wait under 2 seconds counts as 2 seconds.

> [tab] SDK
>
> Pass `storeWaitMs` and `lateResults` to the buy tool:
>
> ```ts agentcard.ts theme={null}
> const buy = buyTool({ agentcard, externalUserId: shopper.id, storeWaitMs: 25000, lateResults: 'stream' });
> ```

> [tab] MCP
>
> The `buy` tool takes no wait. Agentcard chooses it for every MCP call.

> [tab] API
>
> Send `store_wait_ms` and `late_results` with each `POST /buy`:
>
> ```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": "lacroix lime 12 pack",
>     "store_wait_ms": 25000,
>     "late_results": "stream"
>   }'
> ```

## Show late products in a streaming chat

A chat that shows products as cards the moment they arrive waits 25 seconds and streams the late stores. Each store's products show the moment that store answers, so the shopper sees products long before the reply. The reply waits up to 25 seconds, and 99.7% of stores show their first products within that wait. A store that answers later sends its products in the same answer, after the reply, with one message that says what they added:

```text theme={null}
Target has the LaCroix Lime 12 pack. Walmart is still being checked.
[card: LaCroix Lime 12 pack (Walmart)]
Walmart has it too, and it costs less there.
```

Keep your chat ready to add a card below the reply, not only above it.

> [tab] SDK
>
> Use `storeWaitMs: 25000` and `lateResults: 'stream'`. The late cards reach the same callbacks as the first ones: `sendLink`, `onProducts`, or `onItem`. The turn's `onResult` lists the late cards in `result.products`, after the answer's own, so a cart panel or a list of products built from `onResult` shows them too.

> [tab] MCP
>
> The MCP server has no late products to stream. The `buy` result arrives whole, with the products it found.

> [tab] API
>
> Send `"store_wait_ms": 25000` and `"late_results": "stream"` on a streamed call with `?stream=1`. Once the reply is written, the stream sends a `reply_written` event, whose `texts` holds the reply's messages. The late store's products follow as more `catalog` events, and the `envelope` comes last. Show each late `catalog` below the reply.

## Hold late products in a texting app

A texting app that cannot add a card after it sent the reply waits 20 seconds and holds the late stores. The shopper waits up to 20 seconds for the reply, and the reply is the answer's last message. 96% of stores show their first products within that wait. A store that answers after the reply sends nothing in that answer, so about 4 stores in 100 miss the reply. A longer wait catches more of them, up to the 30-second limit, and the shopper waits that much longer.

> [tab] SDK
>
> ```ts sms.ts theme={null}
> const buy = buyTool({ agentcard, externalUserId: shopper.id, storeWaitMs: 20000, lateResults: 'hold' });
> ```

> [tab] MCP
>
> The MCP server always answers once, so there is nothing to hold.

> [tab] API
>
> Send `"store_wait_ms": 20000` and `"late_results": "hold"`.

## Set a wait for one message

Change the wait for one message only, such as a reply you want sooner. The next message goes back to your usual wait.

> [tab] SDK
>
> Pass the same options to `buy.turn`. An option the turn leaves out keeps the tool's:
>
> ```ts chat.ts theme={null}
> const turn = buy.turn(message, { storeWaitMs: 10000 }); // this message replies sooner, and late cards still stream
> ```
>
> An app that calls `client.buy` itself sends the fields `store_wait_ms` and `late_results` on the request.

> [tab] MCP
>
> The `buy` tool takes no wait.

> [tab] API
>
> The fields apply only to the call that carries them, so send a different `store_wait_ms` on that one call.

## Fix a wait that is refused

A wait that is not a number, or a `late_results` other than `stream` or `hold`, is refused before anything runs, so a typo never reaches a shopper.

> [tab] SDK
>
> The SDK checks the options when you build the tool or open a turn. `buyTool({ agentcard, externalUserId: shopper.id, storeWaitMs: '25s' })` throws:
>
> ```text theme={null}
> TypeError: Pass storeWaitMs as a whole number of milliseconds, 0 or more, or leave it out.
> ```
>
> Pass the wait as a number of milliseconds instead:
>
> ```ts agentcard.ts theme={null}
> const buy = buyTool({ agentcard, externalUserId: shopper.id, storeWaitMs: 25000 });
> ```

> [tab] MCP
>
> The `buy` tool takes no wait, so there is nothing to refuse.

> [tab] API
>
> `"store_wait_ms": "25s"` answers:
>
> ```text theme={null}
> 400
> {
>   "error": "store_wait_ms must be a number of milliseconds",
>   "code": "invalid_request"
> }
> ```
>
> Send the wait as a number, `"store_wait_ms": 25000`. A `late_results` such as `"later"` answers `400` with `late_results must be 'stream' or 'hold'`.


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