Skip to main content
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, or connect it to the Commerce MCP server.

Run init in your app’s folder

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, 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:
Put the two lines in place of the production ones in the env file init wrote, .env.local for Next.js and .env otherwise:
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.
agentcard.ts
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:
chat.ts
deliverLink stands for your own code. For the Vercel AI SDK, the OpenAI format and OpenRouter, see 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:
server.ts
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. The listen reference 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:
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:
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