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

# Make your first purchase over HTTP

> Get an access token, send a shopper's request to POST /buy, pick a product and confirm the cart with test credentials that never charge a card.

Make your first purchase for a shopper with plain web requests, from any programming language. This page takes you from your company's credentials to a confirmed cart, with test credentials that search real stores and never charge a card.

Every request goes to `https://api.agentcard.sh`. If your agent runs in TypeScript, the [Commerce SDK](https://docs.agentcard.com/commerce-sdk/quickstart.md) makes these same requests for you.

## Get your test credentials

Credentials come from the Agentcard CLI, a command-line tool that installs nothing in your project. Sign in, where a new email creates your account, then copy your sandbox credentials:

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

The sandbox is Agentcard's test mode: it runs everything against real stores and charges nothing. [`credentials`](https://docs.agentcard.com/tools/cli/credentials) asks your company's name the first time and copies a `client_id` and a `client_secret` to your clipboard.

## Get an access token

Trade your `client_id` and `client_secret` for an access token, a short-lived key you send with every request:

```bash theme={null}
curl https://api.agentcard.sh/api/v2/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'
```

```json theme={null}
{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api",
  "sandbox": true
}
```

Send it as `Authorization: Bearer <access_token>` on every request below, and ask for a new one after an hour. `sandbox: true` confirms the token comes from test credentials.

## Send what the shopper asked for

Send the shopper's words as `ask`, and your own id for the shopper as `external_user_id` on every request. Agentcard keeps each shopper's purchases, saved cards and addresses under that id.

```bash theme={null}
curl https://api.agentcard.sh/buy \
  -H "Authorization: Bearer $AGENTCARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ask": "a pack of AA batteries from amazon", "external_user_id": "user-42" }'
```

The answer carries `reply`, the text to show the shopper, a `catalog` block with the products Agentcard found, and a `conversation_id`, the id of this purchase. Send the `conversation_id` back on every later request about the same purchase:

```json theme={null}
{
  "conversation_id": "conv_527d0e58fbd792e797b4d099",
  "status": "needs_input",
  "reply": "Which pack size do you want? ...",
  "catalog": {
    "merchant_name": "Amazon",
    "items": [
      {
        "ref": "p_0a02f4ebb745",
        "name": "Amazon Basics 20-Pack AA Alkaline Batteries, 1.5 Volt, 10-Year Leak-Free Shelf Life, for Everyday and Household Devices",
        "priceCents": 999,
        "currency": "usd",
        "url": "https://www.amazon.com/dp/B00NTCH52W"
      },
      ...
    ]
  }
}
```

`status: needs_input` means Agentcard needs something from the shopper. Show them `reply` and the products, and send their answer with the same `conversation_id`.

## Pick a product

When the shopper picks one, send their words as `ask` and the product's `ref` as `pick.product_id`:

```bash theme={null}
curl https://api.agentcard.sh/buy \
  -H "Authorization: Bearer $AGENTCARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_...",
    "external_user_id": "user-42",
    "ask": "the first one",
    "pick": { "product_id": "p_0a02f4ebb745" }
  }'
```

## Confirm the cart

The answer now carries a `cart` block with the lines, the fees and the total. Show the shopper the cart from this block, an excerpt here:

```json theme={null}
{
  "cart": {
    "merchant_name": "Amazon",
    "currency": "usd",
    "items": [
      { "name": "Amazon Basics 20-Pack AA Alkaline Batteries", "qty": 1, "priceCents": 999, "lineTotalCents": 999, "line_id": "..." }
    ],
    "subtotalCents": 999,
    "serviceFeesCents": 25,
    "totalCents": 1024,
    "totalIsEstimate": true,
    "hash": "ad9cdf1a1a5037ab"
  }
}
```

The cart's `hash` is a short code that stands for this exact cart: these products, these prices, this total. When the shopper says yes, send it back as `confirm`:

```bash theme={null}
curl https://api.agentcard.sh/buy \
  -H "Authorization: Bearer $AGENTCARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_...",
    "external_user_id": "user-42",
    "confirm": "ad9cdf1a1a5037ab"
  }'
```

Agentcard charges only for the cart the shopper saw. When the shopper still has a step to take, such as saving a card or approving the payment on their phone, the answer carries a link for them, and [Send each link](https://docs.agentcard.com/opencommerce/guides/sending-each-link.md) shows how to hand it over.

## Check the test run

With test credentials, the confirm stops before the card reaches the store and answers with `decline_code: sandbox_mode`. That answer means the test passed: the search, the cart and the approval worked as they do live, and nothing was charged. Swap in your live credentials to place real orders.

## Keep going

* [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)
* [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)
* [Bring back a saved cart](https://docs.agentcard.com/opencommerce/guides/bringing-back-a-saved-cart.md) and [pay with Stripe Link](https://docs.agentcard.com/purchase-api/link-seal.md)
* [Create an access token](https://docs.agentcard.com/api-reference/access-tokens/create.md), the token request in full


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