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

# Commerce SDK

> Give your agent one tool that buys for your shoppers at real stores, and post each purchase update into the shopper's chat.

The `@agent-cards/commerce-sdk` package gives your agent a `buy` tool that searches stores, builds a cart, and places the order once the shopper approves it. The package also hands your server a message, ready to post into the shopper's chat, for each moment the shopper should hear about, such as a saved card or a placed order.

## Install

```bash theme={null}
npm install @agent-cards/commerce-sdk
```

The package runs on Node 18 or later and has no dependencies. The browser entry `@agent-cards/commerce-sdk/browser` imports no Node module, so any build tool takes it.

## Wire it up

```ts agent.ts theme={null}
import { AgentcardClient, buyTool } from '@agent-cards/commerce-sdk';

const agentcard = new AgentcardClient({
  clientId: process.env.AGENTCARD_CLIENT_ID ?? '',
  clientSecret: process.env.AGENTCARD_CLIENT_SECRET ?? '',
});

const buy = buyTool({ agentcard, externalUserId: 'user-42' });
const turn = buy.turn('two packs of AA batteries from Amazon');
```

The snippet builds one `AgentcardClient`, one `buy` tool for the shopper `user-42`, and one turn for the shopper's message. Pass `turn` to your model as its tool. The [Quickstart](https://docs.agentcard.com/commerce-sdk/quickstart.md) page walks through each framework.

When a shopper writes to your agent in several chats at once, such as group chats, build one tool per shopper and chat, and pass your own id for the chat as `threadId`. Each message about that chat's purchase carries the chat as `threadId`, so post it into that chat. [Keep a purchase per chat](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool.md#keep-a-purchase-per-chat) shows how.

## Exports

Every name below comes from `@agent-cards/commerce-sdk`, except the browser entry.

### Client

| Export | Kind | What it is |
| - | - | - |
| [`AgentcardClient`](https://docs.agentcard.com/api-reference/commerce-sdk/agentcard-client) | class | Holds your credentials and talks to Agentcard. |
| [`AgentcardApiError`](https://docs.agentcard.com/api-reference/commerce-sdk/agentcard-client#agentcardapierror) | class | The error every refusal and failed call throws. |
| [`DEFAULT_BASE_URL`](https://docs.agentcard.com/api-reference/commerce-sdk/agentcard-client#constants) | constant | `https://api.agentcard.sh`. |
| [`BUY_TURN_TIMEOUT_MS`](https://docs.agentcard.com/api-reference/commerce-sdk/agentcard-client#constants) | constant | The wait for one purchase turn, in milliseconds. |

### Buy tool

| Export | Kind | What it is |
| - | - | - |
| [`buyTool`](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool) | function | Builds the buy tool for one shopper. |
| [`BUY_TOOL_NAME`, `BUY_TOOL_DESCRIPTION`, `buyToolDefinition`, `parseBuyToolInput`](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool#standalone-helpers) | values | The tool's name, description, definition and input check. |
| [`forModel`, `forModelError`, `replyAsWritten`, `stripLinks`](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool#standalone-helpers) | functions | Turn an answer or an error into what a model may read. |
| [`asBullets`, `textingStyle`](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool#show-bullets-and-texting-style) | functions | Write any text with `• ` bullets, or in a chat's texting style. |
| [`withChoice`, `choiceLines`](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool#list-a-choice-one-per-line) | functions | List a choice's values one per line under its question. |
| [`stepAsWritten`](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool#read-the-step-lines), [`withoutCardList`](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool#leave-out-the-lists-the-cards-show) | functions | Write a step's fixed line, and drop the lists the cards show from a reply. |
| [`instantAck`, `instantReaction`, `ackFor`, `keepsYes`, `ACK_REACTION`](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool#standalone-helpers) | values | Decide whether a message gets a reaction or an instant reply. |
| [`toOpenRouterTool`, `toAnthropicTool`](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool#frameworks) | functions | Adapters for OpenRouter's agent SDK, and a deprecated pass-through. |
| [`productAction`](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool#buytoolproduct) | function | Names what taking a product does: `buy`, `reserve` or `book`. |

### Turn

| Export | Kind | What it is |
| - | - | - |
| [`buy.turn`](https://docs.agentcard.com/api-reference/commerce-sdk/turn) | method | Opens the turn of one shopper message. |
| [`buy.nextStep`](https://docs.agentcard.com/api-reference/commerce-sdk/turn#next-step) | method | Opens the turn your agent takes once the shopper finishes a step outside the chat. |
| [`nextStepPrompt`](https://docs.agentcard.com/api-reference/commerce-sdk/turn#next-step) | function | Writes the model's message for a next-step turn. |
| [`toMessages`, `messageStream`, `typingDelay`](https://docs.agentcard.com/api-reference/commerce-sdk/turn#message-helpers) | functions | Cut text into chat messages and space them. |

### Listen

| Export | Kind | What it is |
| - | - | - |
| [`agentcard.listen`, `listenToAgentcard`](https://docs.agentcard.com/api-reference/commerce-sdk/listen) | method, function | Hear every event over one connection your server opens. |
| [`AGENTCARD_EVENT_TYPES`](https://docs.agentcard.com/api-reference/commerce-sdk/listen#event-types) | constant | Every event type Agentcard sends your company. |

### Webhooks

| Export | Kind | What it is |
| - | - | - |
| [`agentcardWebhook`](https://docs.agentcard.com/api-reference/commerce-sdk/webhook-handler) | function | Builds the handler for your webhook endpoint. |
| [`purchaseAgentWebhook`](https://docs.agentcard.com/api-reference/commerce-sdk/webhook-handler#purchaseagentwebhook) | function | The earlier handler, for `purchase.message` events only. |
| [`verifyAgentcardWebhook`, `AgentcardSignatureError`](https://docs.agentcard.com/api-reference/commerce-sdk/webhook-handler#verify-a-delivery) | function, class | Check a delivery's signature. |
| [`readShopperMessage`, `readPurchaseMessage`, `isStale`](https://docs.agentcard.com/api-reference/commerce-sdk/webhook-handler#read-a-message) | functions | Read the message an event carries. |

### Messages and steps

| Export | Kind | What it is |
| - | - | - |
| [`ShopperMessage`, `ShopperFacts`, `ShopperMessageKind`](https://docs.agentcard.com/api-reference/commerce-sdk/messages) | types | The message you post into a shopper's chat. |
| [`SHOPPER_EVENT_TYPES`, `NEXT_STEP_KINDS`](https://docs.agentcard.com/api-reference/commerce-sdk/messages#event-types-and-next-step-kinds) | constants | The event types that carry a message, and the kinds that advance a step. |
| [`ACTION_LINK_KINDS`, `ACTION_LINK_ENDINGS`, `actionLinkId`, `actionLinkOutcome`, `isActionLink`](https://docs.agentcard.com/api-reference/commerce-sdk/messages#action-link-helpers) | values | Tell which message ends which link. |
| [`ACTION_LINK_HOSTS`, `actionLinkRefusal`, `ActionLinkRefusedError`](https://docs.agentcard.com/api-reference/commerce-sdk/messages#action-link-helpers) | values, class | Tell which links a pop-up opens. |

### Browser entry

| Export | Kind | What it is |
| - | - | - |
| [`actionWindows`](https://docs.agentcard.com/api-reference/commerce-sdk/messages#action-windows) | function | Opens each step in a pop-up and closes it when the step ends. |

The browser entry also re-exports the action-link helpers.

## Guides

Each guide shows what the shopper sees, the code that implements it, and how to check it in the sandbox.

* [Quickstart](https://docs.agentcard.com/commerce-sdk/quickstart.md)
* [Showing products and carting the one the shopper picks](https://docs.agentcard.com/opencommerce/guides/showing-products.md)
* [Showing stores and their menus](https://docs.agentcard.com/opencommerce/guides/showing-stores-and-menus.md)
* [Sending each link: approval, Vault and store sign-in](https://docs.agentcard.com/opencommerce/guides/sending-each-link.md)
* [Adding a card for a new shopper](https://docs.agentcard.com/commerce-sdk/guides/adding-a-card.md)
* [Approving a purchase](https://docs.agentcard.com/commerce-sdk/guides/approving-a-purchase.md)
* [Signing in to a store's account](https://docs.agentcard.com/opencommerce/guides/sending-each-link.md)
* [Taking the next step once the shopper finishes outside the chat](https://docs.agentcard.com/opencommerce/guides/taking-the-next-step.md)
* [Showing the cart](https://docs.agentcard.com/opencommerce/guides/showing-the-cart.md)
* [Bring back a saved cart](https://docs.agentcard.com/opencommerce/guides/bringing-back-a-saved-cart.md)
* [Answering each shopper message in its own turn](https://docs.agentcard.com/opencommerce/guides/answering-each-message.md)
* [Acknowledging the shopper: a reaction or a short text](https://docs.agentcard.com/opencommerce/guides/acknowledging-the-shopper.md)


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