@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 credentialsinit 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:
init wrote, .env.local for Next.js and .env otherwise:
Give your agent the buy tool
Build oneAgentcardClient 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
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. Calllisten 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:declined with decline_code: sandbox_unavailable, and the run ends with:
111111.
Go live
- Choose Go live in the dashboard’s banner. Copy the production client ID and secret into
AGENTCARD_CLIENT_IDandAGENTCARD_CLIENT_SECRET. - 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.
Keep going
- Give your model instructions
- Show products and show the cart
- Send each link and take the next step
- Answer each message, so your agent tells the shopper about saved cards, placed orders and deliveries
- Check where Agentcard can pay
- Test in the sandbox and read a refusal
- Commerce SDK reference, every export and option