Install the SDK
Runinit in your app’s folder:
init is the only way to create an Agentcard account. The website and the dashboard can’t create one. init also replaces the manual setup, so you don’t run npm install or copy credentials from the dashboard.init asks which stores your agent buys from, then, after one yes, does the rest:
- signs you in, or creates your Agentcard account and your company in the browser,
- installs the SDK,
- puts your production credentials in your env file, kept out of git,
- has Agentcard’s agent build the buy tool into your code, and ends with the command that starts your app.
init first sets up Agentcard’s example app, a terminal chat that buys, so you have a working agent to try.
init needs Node 22 or later. The SDK it installs runs on Node 18 or later and has no dependencies. To use your own coding agent instead of Agentcard’s, run npx agent-cards init --print, and the CLI prints the instructions for it.
The rest of this page explains what init builds, so you can read and change it.
Give your agent the buy tool
Build oneAgentcardClient when your server starts and keep it. Build one buy tool for each shopper, name the shopper by your own id for them, and keep that tool too. Open one turn for each message the shopper sends, and give the turn to your model in place of the tool.
agentcard.ts
externalUserId. Agentcard refuses a call when two of your shoppers share one id.
A shopper can write to your agent in several chats at once when your app has group chats or threads. In such an app, build one tool per shopper and chat, and name the chat with threadId, your own id for it:
agentcard.ts
sendLink, and the turn hands it every Vault, approval, store sign-in, product, and store link, so your model never reads or writes one. “Send each link” shows how to render each kind.
The tab for your model API shows the same turn in each shape. Pick the one your agent already uses.
- Anthropic
- Vercel AI SDK
- OpenAI or OpenRouter
chat.ts
deliverLink and yourModel stand for your own code. The model calls buy with the shopper’s words, shows the shopper the cart, and confirms the cart only after the shopper says yes. OpenRouter’s agent SDK takes the tool through toOpenRouterTool(turn, { tool, z }), as the buyTool reference shows.
Pass deliveryAddress to buyTool when you already hold the shopper’s address. The order goes there, and Agentcard never asks the shopper for it. The model can change neither the address nor the shopper.
Check it in the sandbox
init puts production credentials in your env file, and those place real orders. Copy your sandbox credentials to test without placing any:
init wrote: .env.local for Next.js, .env otherwise.
111111.
Run the scripted walkthrough with your sandbox credentials. It connects a test shopper with the code 111111, asks for a restaurant table, picks one, and confirms it, with no model in the loop.
declined with decline_code: sandbox_unavailable, and the run ends with:
examples/anthropic.mjs and examples/openrouter.mjs, which run the buy tool as a chat in your terminal and print the links your app would send. Each guide in this section ends with a check you run in the sandbox.
Hear from Agentcard
Agentcard tells your server about every moment a shopper should hear about, even when the shopper is not chatting: a card saved, an approval about to expire, an order placed, a delivery on its way. The SDK hands you each one as a message withtext ready to post into that shopper’s chat. Pick the way your host runs.
When you build your tools with threadId, post each message into the chat its threadId names. A message about the shopper alone, such as a saved card, carries threadId: null, and Keep a purchase per chat says where it goes.
Listen from a long-running server
Calllisten once when your server starts, on the same AgentcardClient your tools use. Your server opens one connection to Agentcard, so you host no public URL and check no signature.
server.ts
onMessage gets each message under the externalUserId you gave the buy tool. onEvent gets every other event Agentcard sends your company, such as order.placed. The listener reconnects after a dropped connection and resumes after the last event it handled. Run one listener for each company and mode. The listen reference lists the options, including a cursor store that resumes a restarted server where the last process stopped.
Take events at a webhook endpoint on serverless
A host that ends each request after a few seconds cannot keep a connection open. MountagentcardWebhook on a route instead. The handler checks each delivery’s signature, skips an event it already handled, and calls onMessage with your own id for the shopper.
app/api/agentcard/route.ts
POST /api/v2/webhook_endpoints, and subscribe it to purchase.message, order.confirmed, and order.updated by name. A catch-all * alone does not turn purchase.message on. The handler answers 200 once onMessage returns and 500 when it throws, and Agentcard then delivers the event again, so a failed post is not lost. In an Express route, mount the same handler with express.raw({ type: 'application/json' }) before any express.json(). The webhook handler reference shows both.
Let your model read what the shopper read
Between turns, Agentcard posts messages such as “Your Visa ending 3132 is saved” into the shopper’s chat. Your model has to read them too, or it answers “ok lets checkout” with “did you save your card?”. Passturn.messages(history) as the model’s messages, as the code above does, and the turn adds each message the history does not hold yet. “Take the next step once the shopper finishes outside the chat” shows how your agent moves on without waiting for the shopper to say “ok”.
The client keeps each message in the process that received it, so a server that runs listen beside your model hands them to the next turn on its own. A webhook endpoint on serverless answers in another process than your chat route, so write each message into the shopper’s history as an assistant message, as the handler above does, and your model reads it from there. Post the message’s own text to the shopper, and save stripLinks(message.text) for the model, so the model never repeats a link that has since expired. The buy tool hands the shopper a current one.
The order events your company receives are documented in Order events: order.placed, order.confirmed, order.failed, and order.updated.
See what your agent can buy
The buy tool covers four kinds of purchase, and the model picks the right one from the shopper’s words.
Each guide in this section covers one moment of the shopper’s experience, from the product cards to the approval.
Check where Agentcard can pay
Ask Agentcard whether it can pay at a store before you send a shopper there. CallGET /buy/merchants with the token await agentcard.bearer() returns, $AGENTCARD_TOKEN below, and put the store’s name or domain in q:
supported to see whether Agentcard can buy at the store, supported_reason to see why, and supported_detail for the processor or the stop behind a false. true means a real purchase at the store went through, or a shopper’s conversation reached the store’s total at a card form Agentcard pays through, on supported_read_at. false means the store’s card form uses a payment processor Agentcard cannot pay through, or the last conversation there stopped before the total. null means no purchase or conversation in the last 14 days says either way. Target, like every store whose buys_through is retail, reads true with no reason, no detail and no date, because Agentcard pays there without a card form. Agentcard checks the card form again on every purchase and types a card only when the check passes.
Compare each entry’s
domain with your store, because q matches part of a name or domain. A call returns up to 50 entries, or as many as limit asks for, up to 100. When your store is not among them and next_cursor is not null, send the same call again with cursor set to that value, until you find the store or next_cursor is null. Agentcard has no answer yet for a store missing from every page, so treat that store as one Agentcard cannot pay at.
An entry carries held_back when the store cancelled orders Agentcard placed there as a guest. Until held_back.until, Agentcard offers the shopper another store, unless the shopper signed in to that store and checks out as themselves.
countries names the countries a store sells in, and is empty when Agentcard has none on record.
Leave out kind=catalog to also search the merchants Agentcard works with directly, such as DoorDash, whose entries carry kind: "direct".
Add &external_user_id=user-42, the externalUserId you give the buy tool, to read the list as that shopper: each direct entry then carries link_status, which says whether the shopper still has to link that merchant, and a store the shopper signed in to carries no held_back.
Agentcard answers 403 when no connected shopper carries that id:
Go live
Switch from sandbox to live in two steps. The code stays the same.- Choose Go live in the dashboard’s banner. It creates your production credentials and opens Settings, Developers, Credentials on the Production tab. Copy the production client ID and secret into
AGENTCARD_CLIENT_IDandAGENTCARD_CLIENT_SECRET. A webhook endpoint belongs to a mode, so create a live endpoint for the live credentials and use its secret. - Open Commerce SDK, Balance in the dashboard and choose how to pay the fee. Agentcard takes 1% of each live purchase. With prefund, you add money to a balance and each fee comes out of it. With pay as you go, you save a card and each fee is charged to it as the purchase completes. Fees too small to charge wait and are charged together with the next one.
Keep going
Showing products and carting the one the shopper picks
Render product cards and cart the exact product the shopper taps.
Sending each link: approval, Vault and store sign-in
Deliver every link to the shopper while the model never reads one.
Approving a purchase
Send the approval link and place the order only after the shopper says yes.
Commerce SDK reference
Every export, option, and message type.