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

# Set up the opencommerce SDK

> Create your Agentcard account, install the opencommerce SDK, give your agent the buy tool and make a test purchase that charges nothing.

Give your agent one tool that buys for your shoppers at real stores. This page sets up your account, installs the SDK, wires the tool into your model and runs a test purchase that charges nothing.

The SDK is the TypeScript package `@agent-cards/commerce-sdk`. It runs on Node 18 or later and has no dependencies. If your agent runs in another language, make the same purchase over plain HTTP with [Make your first purchase over HTTP](https://docs.agentcard.com/purchase-api/http.md), or connect it to the [Commerce MCP server](https://docs.agentcard.com/commerce-mcp.md).

## Run init in your app's folder

```bash theme={null}
npx agent-cards init
```

[`init`](https://docs.agentcard.com/tools/cli/init) is the only way to create an Agentcard account. It asks which stores your agent buys from, then, after one yes, signs you in or creates your account and your company in the browser, installs the SDK, puts your production credentials in your env file and builds the buy tool into your code. In an empty folder it first sets up Agentcard's [example app](https://github.com/tiny-agent-company/commerce-sdk-example), a chat in your terminal that buys.

`init` needs Node 22 or later. To have your own coding agent do the wiring, run `npx agent-cards init --print`, and the CLI prints the instructions for it.

## Switch to sandbox credentials

The credentials `init` writes are production ones, and those place real orders. The sandbox is Agentcard's test mode: it runs the whole purchase against real stores and stops before payment, so no order is placed and nobody is charged. Copy your sandbox credentials:

```bash theme={null}
npx agent-cards credentials --mode sandbox
```

Put the two lines in place of the production ones in the env file `init` wrote, `.env.local` for Next.js and `.env` otherwise:

```text theme={null}
AGENTCARD_CLIENT_ID=your_client_id
AGENTCARD_CLIENT_SECRET=your_client_secret
```

Keep both in your app's secret store. Never hard-code them, log them or commit them.

## Give your agent the buy tool

Build one `AgentcardClient` when your server starts. Build one buy tool for each shopper, named by your own id for them in `externalUserId`, and keep it. Agentcard refuses a call when two of your shoppers share one id.

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

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

const tools = new Map<string, BuyTool>();

export function buyFor(shopperId: string): BuyTool {
  let buy = tools.get(shopperId);
  if (!buy) {
    buy = buyTool({ agentcard, externalUserId: shopperId });
    tools.set(shopperId, buy);
  }
  return buy;
}
```

For each message the shopper sends, open a turn, the tool's view of that one message, and give it to your model in place of the tool. `sendLink` receives every link the shopper needs, such as the page to add a card or approve a payment, so your model never reads or writes one. This example uses Anthropic's tool runner:

```ts chat.ts theme={null}
import Anthropic from '@anthropic-ai/sdk';
import { buyFor } from './agentcard';

const anthropic = new Anthropic();
const histories = new Map<string, any[]>();

export async function answer(shopperId: string, message: string) {
  const turn = buyFor(shopperId).turn(message, {
    sendLink: (link) => deliverLink(shopperId, link), // your code
  });
  const runner = anthropic.beta.messages.toolRunner({
    model: 'claude-opus-5-5',
    max_tokens: 16000,
    tools: [turn],
    messages: turn.messages(histories.get(shopperId)),
  });
  const final = await runner;
  histories.set(shopperId, runner.params.messages);
  return final;
}
```

`deliverLink` stands for your own code. For the Vercel AI SDK, the OpenAI format and OpenRouter, see [Frameworks](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool.md#frameworks) in the `buyTool` reference.

## Hear from Agentcard

Agentcard tells your server when a shopper should hear something while they are not chatting, such as a saved card or a placed order. Call `listen` once when your server starts, and post each message's `text` into that shopper's chat:

```ts server.ts theme={null}
import { agentcard } from './agentcard';

agentcard.listen({
  onMessage: (shopperId, message) => postToChat(shopperId, message.text), // your code
});
```

`listen` keeps one connection open, so you host no public URL. On a serverless host that ends each request after a few seconds, take the same messages at a webhook endpoint, a URL on your server that Agentcard sends each event to, with the [webhook handler](https://docs.agentcard.com/api-reference/commerce-sdk/webhook-handler.md). The [`listen` reference](https://docs.agentcard.com/api-reference/commerce-sdk/listen) lists every option.

## Make a test purchase

Run the walkthrough that ships with the package, with your sandbox credentials. It connects a test shopper, asks for a restaurant table, picks one and confirms it, with no model involved:

```bash theme={null}
AGENTCARD_CLIENT_ID=your_client_id AGENTCARD_CLIENT_SECRET=your_client_secret node node_modules/@agent-cards/commerce-sdk/examples/walkthrough.mjs
```

The sandbox refuses the booking itself, so nothing is booked or charged. The last answer is `declined` with `decline_code: sandbox_unavailable`, and the run ends with:

```text theme={null}
walkthrough passed
```

Then send your own agent "two packs of AA batteries from Amazon" as a test shopper, and look for product cards, a short reply and a cart. In the sandbox, the code that connects a test shopper is always `111111`.

## Go live

1. Choose Go live in the dashboard's banner. Copy the production client ID and secret into `AGENTCARD_CLIENT_ID` and `AGENTCARD_CLIENT_SECRET`.
2. Open Commerce SDK, Balance in the dashboard and choose how to pay Agentcard's fee of 1% of each live purchase: prefund a balance, or save a card that pays each fee as the purchase completes.

Live credentials place real orders and charge real cards. Test the full flow with your own card first.

## Keep going

* [Give your model instructions](https://docs.agentcard.com/opencommerce/guides/give-your-model-instructions.md)
* [Show products](https://docs.agentcard.com/opencommerce/guides/showing-products.md) and [show the cart](https://docs.agentcard.com/opencommerce/guides/showing-the-cart.md)
* [Send each link](https://docs.agentcard.com/opencommerce/guides/sending-each-link.md) and [take the next step](https://docs.agentcard.com/opencommerce/guides/taking-the-next-step.md)
* [Answer each message](https://docs.agentcard.com/opencommerce/guides/answering-each-message.md), so your agent tells the shopper about saved cards, placed orders and deliveries
* [Check where Agentcard can pay](https://docs.agentcard.com/opencommerce/guides/checking-where-agentcard-can-pay.md)
* [Test in the sandbox](https://docs.agentcard.com/opencommerce/guides/testing-in-the-sandbox.md) and [read a refusal](https://docs.agentcard.com/opencommerce/guides/reading-a-refusal.md)
* [Commerce SDK reference](https://docs.agentcard.com/api-reference/commerce-sdk/overview.md), every export and option


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