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

# Send the shopper each link

> Find the add-a-card, store sign-in and approval links in each answer, deliver each one to the shopper unchanged, and know when the shopper finished the step.

Some steps of a purchase happen outside your chat, and only the shopper can take them. Agentcard hands your app a link for each one. Your app sends the link as one clear call to action, the shopper finishes the step on the page it opens, and the purchase moves on.

## Know the three links

A purchase needs a link at three moments:

| Step | What the shopper does on the page |
| - | - |
| Add a card | Saves a card in the Vault, Agentcard's page where the shopper keeps their card and approves payments. A shopper with no card saved sees this before they can pay. |
| Sign in to a store | Signs in to their own account at a store that places orders only on the shopper's account, such as DoorDash. |
| Approve the payment | Approves this one payment with a passkey, the fingerprint or face check on their phone or computer. Agentcard places the order only after this. |

Every answer names the one step the shopper takes next in `next_action`. Agentcard asks for one step at a time, in the order of this table:

| `next_action` | The step | Link |
| - | - | - |
| `shipping_details` | Agentcard needs an address and a phone number. | None |
| `guest_details` | A booking needs a name, an email and a phone number. | None |
| `store_login` | The shopper signs in to the store. | Sign in to a store |
| `add_card` | The shopper saves a card. | Add a card |
| `confirm` | The shopper says yes to the cart's total. | None |
| `verification_code` | The shopper sends the code a booking texted them. | None |
| `approve` | The shopper approves the payment. | Approve the payment |
| `bank_challenge` | The shopper answers their bank's check on the payment, as [Wait for the bank's approval](https://docs.agentcard.com/commerce-sdk/guides/approving-a-purchase.md#wait-for-the-banks-approval) shows. | None |

A shopper who still has a card to save and a store to sign in to hears about the sign-in first, and the card second.

## Find each link in an answer

Each link comes with the moment it stops working, as an ISO 8601 date and time such as `2026-11-19T21:14:12.178Z`. A store sign-in link also names its store, so your button can read "Sign in to DoorDash".

> [tab] SDK
>
> Pass `sendLink` to `buy.turn`, the call that runs the buy tool for one shopper message. The tool hands `sendLink` each link and waits for it, so the shopper holds the link before your model answers.
>
> ```ts chat.ts theme={null}
> const turn = buyFor(shopper.id).turn(message, {
>   sendLink: async (link) => {
>     switch (link.kind) {
>       case 'vault':
>         return sendStep(shopper.id, 'Add a card', link); // your code
>       case 'approval':
>         return sendStep(shopper.id, 'Approve the payment', link);
>       case 'store_login':
>         return sendStep(shopper.id, `Sign in to ${link.store ?? 'the store'}`, link);
>       default:
>         return sendCard(shopper.id, link); // product and store cards
>     }
>   },
> });
> ```
>
> | `kind` | The step | Fields |
> | - | - | - |
> | `vault` | Add a card | `url`, `expiresAt`, `id` |
> | `approval` | Approve the payment | `url`, `expiresAt`, `id`, and `store` when the answer names the cart's store |
> | `store_login` | Sign in to a store | `url`, `expiresAt`, `id`, `store` |
>
> `expiresAt` is null when Agentcard did not say. Without `sendLink`, read the same links from `turn.links` or from the `onResult` callback.

> [tab] MCP
>
> The `buy` tool's result lists the links in `links`, each with a `kind` of `add_card`, `approval` or `store_login`, a `url`, `expires_at` and `store`. `link_sent` is `true` while a page waits for the shopper.
>
> ```json theme={null}
> {
>   "tool": "buy",
>   "arguments": {
>     "shopper_id": "user_8f3a21",
>     "thread_id": "chat_5521",
>     "ask": "yes add it, then lets checkout",
>     "confirm": false,
>     "new_order": false,
>     "product_id": null,
>     "store_id": null
>   }
> }
> ```
>
> ```json theme={null}
> {
>   "status": "needs_input",
>   "next_action": "store_login",
>   "links": [
>     {
>       "kind": "store_login",
>       "url": "https://app.agentcard.sh/connect/...",
>       "expires_at": "2026-11-19T21:14:12.178Z",
>       "store": "DoorDash"
>     }
>   ],
>   "link_sent": true,
>   "reply": "Added the Burrito from Chipotle, about $15.35 before delivery and tax. Sign in to DoorDash to place it.",
>   "conversation_id": "conv_0758c600dc272b6abdbc5e5e",
>   ...
> }
> ```
>
> `reply` comes with the links taken out. [`buy`](https://docs.agentcard.com/commerce-mcp/tools/buy) lists every field of the result.

> [tab] API
>
> Every answer to `POST /buy` carries three fields, one for each link: `add_card_url`, `store_login_url` and `approval_url`. A field holds a URL only when the shopper has that step to take, and is `null` otherwise. Each has an expiry beside it, and `store_login_merchant_name` names the store.
>
> ```bash theme={null}
> curl https://api.agentcard.sh/buy \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "conversation_id": "conv_0758c600dc272b6abdbc5e5e",
>     "external_user_id": "docs-guide-links-2",
>     "ask": "yes add it, then lets checkout",
>     "payment_source": "vault"
>   }'
> ```
>
> ```json theme={null}
> {
>   "conversation_id": "conv_0758c600dc272b6abdbc5e5e",
>   "status": "needs_input",
>   "reply": "Added the Burrito from Chipotle, about $15.35 before delivery and tax.\n\nSign in to DoorDash with this link to place it: https://app.agentcard.sh/connect/...",
>   "next_action": "store_login",
>   "store_login_url": "https://app.agentcard.sh/connect/...",
>   "store_login_expires_at": "2026-11-19T21:14:12.178Z",
>   "store_login_merchant_name": "DoorDash",
>   "add_card_url": null,
>   "add_card_expires_at": null,
>   "approval_url": null,
>   "approval_expires_at": null,
>   "cart": {
>     "merchant": "doordash",
>     "merchant_name": "DoorDash",
>     "store": { "id": "270561", "name": "Chipotle Mexican Grill" },
>     "items": [ { "name": "Burrito", "qty": 1, "priceCents": 1535, "options": ["Chicken"], ... } ],
>     "totalCents": 1573,
>     "totalIsEstimate": true,
>     "hash": "d2af60c58141488c"
>   }
> }
> ```
>
> The approval link arrives on the answer to a confirm, the call that sends the shopper's yes to a cart. That answer reads `status: "declined"` with `decline_code: "vault_approval_required"`. Nothing was refused: the order waits for the shopper to approve.
>
> ```json theme={null}
> {
>   "conversation_id": "conv_...",
>   "status": "declined",
>   "decline_code": "vault_approval_required",
>   "next_action": "approve",
>   "approval_url": "https://app.agentcard.sh/a/cauth_...",
>   "approval_expires_at": "2026-11-19T21:30:00.000Z",
>   "authorization_id": "cauth_...",
>   "approval_in_progress": null
> }
> ```
>
> `authorization_id` names this approval. `approval_in_progress: true` means the shopper already approved and the order is going in, so show no link then. A shopper with no card saved gets `add_card_url` on the same kind of answer, with `decline_code: "vault_unavailable"` and `next_action: "add_card"`.

## Send each link as it is

Send each URL exactly as Agentcard gave it, alone in its own message or behind one button. An approval or add-a-card link with anything added to it no longer works, and the shopper lands on the Vault's sign-in page instead of the step.

Never let your language model retype a link. A model that copies a URL into its answer can change one character and break it. Name each link by what it is for instead: the link to add a card, to sign in to the store, or to approve the payment.

In a text chat such as SMS or iMessage, send the sentence that asks for the step first, then the URL alone in the next message. iMessage shows a URL that stands alone as a preview card, and it breaks one with words attached.

> [tab] SDK
>
> Your model never reads a link. A tool runner puts each tool answer straight into the model's context, so the tool hands each link to your code and the model reads only `link_sent: true`. The model's description tells it never to write a link.
>
> With `onItem` on the turn, the turn holds each step link until the message that asks for it went out, then sends the link right after it. A held link also goes out when the turn's next call starts, or after 20 seconds, so a model that writes nothing still sends it. [Answer each message](https://docs.agentcard.com/opencommerce/guides/answering-each-message.md) shows `onItem`.
>
> A `sendLink` that throws on a Vault or approval link makes the call throw, and the model never reads that a link went out. Catch the error, tell the shopper something went wrong, and let them ask again. A link your `sendLink` throws on stays out of `turn.links`.

> [tab] MCP
>
> Pick one of two ways and keep to it:
>
> * Your app shows links itself, as buttons. Your model never writes a link in its reply. When `link_sent` is `true`, the model tells the shopper a link is waiting.
> * Your model writes the reply, so it hands over every `url` exactly as `links` holds it, with every query parameter, never shortened or rewritten.
>
> Links belong to one shopper. Never send one to anyone else or keep it in notes. [The shopping skill](https://docs.agentcard.com/opencommerce/guides/give-your-model-instructions.md) gives your model these rules.

> [tab] API
>
> `reply`, the text Agentcard wrote for the shopper, contains the link too, as the answer above shows. Post `reply` as it is, or post your own words and a button built from the field. Never pass the URL through your own model.

## Send the store sign-in link

A store such as DoorDash places an order only on the shopper's own account. When the shopper reaches checkout there, the answer reads `next_action: "store_login"` and carries a sign-in link named for the store. The shopper signs in on the store's page, comes back to the chat, and the purchase moves on without them typing "done", as [Move the purchase on](https://docs.agentcard.com/opencommerce/guides/taking-the-next-step.md) shows.

A shopper can hold sign-in links for two stores at once, each with its own cart. Each link and each message about a sign-in names its store, so match them by store before you mark a sign-in as done.

A store that prices the order only once it is in the shopper's own account answers with a total marked as an estimate. DoorDash is one. Show that total as an estimate, such as "about \$15.73 before tax and delivery".

> [tab] SDK
>
> The link reaches `sendLink` with `kind: 'store_login'` and the store's name in `store`. The cart reads `totalIsEstimate: true`, and the model reads `total_is_estimate` and `total_leaves_out`, so it says the total is before those costs.

> [tab] MCP
>
> The result's `links` holds a link of kind `store_login` with the store in `store`. The cart reads `total_is_estimate: true`.

> [tab] API
>
> The answer carries `store_login_url`, `store_login_expires_at` and `store_login_merchant_name`. The cart reads `totalIsEstimate: true`.

## Send a link again

When the shopper asks for the link again, pass their words on as a new message in the same chat. While a link still has time left, Agentcard answers with the same link, so the shopper never has two links for one step. An expired link is replaced with a new one.

Agentcard also reminds the shopper on its own: `approval_expiring` and `card_link_unfinished` messages carry the link again in their `text`, ready to post. These reminders leave the step open.

> [tab] SDK
>
> The model calls the tool again, and the tool hands the same link to `sendLink` again. The reminders arrive through `listen` or the webhook handler.

> [tab] MCP
>
> Call `buy` again in the same chat with the shopper's words. [`get_conversation`](https://docs.agentcard.com/commerce-mcp/tools/get_conversation) also returns `last_checkout`, with the latest `approval_url` and `add_card_url` and their expiry. The reminders arrive through [`get_updates`](https://docs.agentcard.com/commerce-mcp/tools/get_updates).

> [tab] API
>
> Send the shopper's words as the `ask` of the next call. You can also read the conversation at any time: `last_checkout` holds the latest `approval_url` and `add_card_url`, with their expiry.
>
> ```bash theme={null}
> curl "https://api.agentcard.sh/buy/conversations/conv_0758c600dc272b6abdbc5e5e?external_user_id=docs-guide-links-2" \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN"
> ```
>
> The reminders arrive as `purchase.message` webhooks, requests Agentcard sends to your server when something happens. Your webhook endpoint receives them only when it lists `purchase.message` by name, as [Move the purchase on](https://docs.agentcard.com/opencommerce/guides/taking-the-next-step.md) shows.

## Open each step in a pop-up

On the web, open each step in a pop-up window over the chat, so the shopper never leaves it, and close the pop-up when the message that ends the step arrives.

> [tab] SDK
>
> `actionWindows` from `@agent-cards/commerce-sdk/browser` opens a step in a pop-up centered over the chat and closes it when the step ends. The browser entry imports no Node module, so any bundler takes it.
>
> ```ts chat-ui.ts theme={null}
> import { actionWindows } from '@agent-cards/commerce-sdk/browser';
>
> const windows = actionWindows({
>   onEnded: (step, outcome) => markStepDone(step.id, outcome), // your code
>   onClosed: (step) => keepOfferingStep(step.id), // your code
> });
>
> // The link's own click handler, so the browser counts the tap as the reason for the pop-up.
> // When the browser blocks it, `open` returns null and the link opens as a new tab.
> // For a link `open` refuses, it throws, and the handler cancels the tap so the link never opens.
> stepLink.addEventListener('click', (event) => {
>   try {
>     if (windows.open(link)) event.preventDefault();
>   } catch (error) {
>     event.preventDefault();
>     console.error(error);
>   }
> });
>
> // Each shopper message your server forwards from `listen` or the webhook handler.
> onShopperMessage((message) => windows.settle(message)); // your code
> ```
>
> Each step link carries a stable `id`, such as `vault_1x9k2qd`, the same every time the same link is handed over, with no part of the URL in it. Use it as a DOM key or in a log. `actionLinkId(link)` reads the id from a link that has none.
>
> `settle` closes each open pop-up whose step the message ends and returns `[{ step, outcome }]`. A pop-up the shopper closes before the step ends reaches `onClosed`, checked every 500 milliseconds. The step is still open, so keep its link on screen, and a tap opens it again. A tap on a step whose pop-up is open brings that window to the front.
>
> The pop-up is 480 by 760 pixels by default. Pass `width` and `height` to change it. A phone's browser opens the pop-up as a tab, and `settle` closes that tab the same way. `dispose()` stops watching and leaves every pop-up open, so a chat that remounts never shuts the page where a shopper is typing a card.
>
> `open` opens only an absolute `https:` page, and a store sign-in only on `agentcard.sh`, `agentcard.com` and their subdomains. For any other link it throws `ActionLinkRefusedError` and opens nothing. A chat on a local stack that opens its `http://localhost` Vault link logs:
>
> ```text theme={null}
> ActionLinkRefusedError: A vault link was not opened: its page is not an https URL.
>   kind: 'vault', reason: 'not_https'
> ```
>
> | `reason` | What it means | What to do next |
> | - | - | - |
> | `not_https` | The link's page is not an absolute `https:` URL, or it names a user before its host. | Pass the link exactly as the buy tool handed it over. |
> | `host_not_allowed` | A store sign-in link points outside `agentcard.sh`, `agentcard.com` and their subdomains. | Pass the link exactly as the buy tool handed it over. |
>
> The buy tool never hands over a link `open` refuses, so a refusal means your code built or changed the link.

> [tab] MCP
>
> The MCP server has no pop-up helper. Open each `url` in a window of your own, and close it when [`get_updates`](https://docs.agentcard.com/commerce-mcp/tools/get_updates) brings the message that ends the step.

> [tab] API
>
> The API has no pop-up helper. Open each URL in a window of your own, and close it when the `purchase.message` webhook that ends the step arrives.

## Know when a step ends

Each step ends with a message from Agentcard whose `kind` says how:

| Link | Done | Declined | Failed | Expired |
| - | - | - | - | - |
| Add a card | `card_added` | | | `card_link_expired` |
| Sign in to a store | `store_connected` | | `store_connect_failed` | `store_connect_expired` |
| Approve the payment | `order_placing`, `order_placed`, `order_not_placed_yet`, `order_unconfirmed`, `order_confirmed`, `order_failed`, `payment_declined` | `approval_declined` | | `approval_expired` |

Once a step ends, take its button off the screen. An approval is done once the shopper approved, even when the order then failed or the payment was refused, because the approval page has nothing more to do. The message's `text` tells the shopper what happened. After `store_connect_failed` or `store_connect_expired`, `text` offers a new sign-in link, so post it as it is.

A message about another store leaves a step open: a `store_connected` for DoorDash never ends a sign-in to Locale that the shopper has open beside it. A message that names a different approval or add-a-card link leaves this link's step open too. [Message types](https://docs.agentcard.com/api-reference/commerce-sdk/messages.md#kinds) lists every `kind`.

> [tab] SDK
>
> `actionLinkOutcome(link, message)` returns how a message ended the step, `completed`, `declined`, `failed` or `expired`, or null when it left the step open. It compares the store in the link with `facts.merchantName`, and the link with `facts.approvalUrl` or `facts.cardLinkUrl`. `ACTION_LINK_ENDINGS` holds the whole table.

> [tab] MCP
>
> Each message from [`get_updates`](https://docs.agentcard.com/commerce-mcp/tools/get_updates) carries `kind`, and a message about an order carries `ends_step`, the step link the message ends.

> [tab] API
>
> Each message arrives as a `purchase.message` webhook. Compare the store in `facts.merchant_name`, and the link in `facts.approval_url` or `facts.card_link_url`, before you mark a step done.

## Check it in the sandbox

The sandbox is Agentcard's test mode: it searches real stores, charges nothing and stops before payment.

1. As a new test shopper, send `a chicken burrito from chipotle on doordash`, pick the options, and say "lets checkout". Check that a store sign-in link arrives, named for DoorDash.
2. Ask for the link again. Check that it is the same link.
3. Search your model's replies for `https://`. Check that none is there.

> [tab] SDK
>
> 4. Send "two packs of AA batteries from Amazon" as a test shopper who has no card. Check that `sendLink` receives a `vault` link and that the model's reply says a link is waiting, without containing it.
> 5. Open the link in a pop-up, then close the pop-up before you finish. Check that `onClosed` fires and the link stays on screen.

> [tab] MCP
>
> 4. Check that `link_sent` reads `true` while the sign-in link waits, and that your model either hands the `url` over unchanged or only says a link is waiting.

> [tab] API
>
> 4. The sandbox makes no add-a-card link on `POST /buy`. To try the Vault page, create a Vault link yourself with [`POST /api/v2/vault_sessions`](https://docs.agentcard.com/api-reference/vault/sessions-create) and the same `external_user_id`, and save a test card on it, as [Test in the sandbox](https://docs.agentcard.com/opencommerce/guides/testing-in-the-sandbox.md) shows.

The sandbox sends no `card_added`, `store_connected` or `approval_declined` message, and it places no order, so check the endings and the approval link with live credentials by buying one inexpensive item with your own card, as [Approving a purchase](https://docs.agentcard.com/commerce-sdk/guides/approving-a-purchase.md) shows.


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