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

# API reference

> Every v2 endpoint, grouped by the resource it acts on. Each page has parameters, responses, and a live playground.

Base URL: `https://api.agentcard.sh`

There is no separate sandbox host. Whether a call runs in **sandbox** or **production** is decided by the credential you use, never by the URL.

## Resources

> [card] [Access tokens](https://docs.agentcard.com/api-reference/access-tokens/overview.md)
>
> Exchange client credentials for the platform token every call needs.

> [card] [Connections](https://docs.agentcard.com/api-reference/connections/overview.md)
>
> Connect a user to your platform and get a token that acts as them.

> [card] [Vault](https://docs.agentcard.com/api-reference/vault/overview.md)
>
> Store a user's own card and authorize checkouts with it.

> [card] [Commerce SDK](https://docs.agentcard.com/api-reference/commerce-sdk/overview.md)
>
> Give your agent a buy tool and hear when a shopper saves a card or an order goes through.

> [card] [Cards](https://docs.agentcard.com/api-reference/cards/overview.md)
>
> Issue virtual cards to your users from your server, with one credential.

> [card] [Company wallet](https://docs.agentcard.com/api-reference/company-wallet/overview.md)
>
> Read your company balance and add test money in sandbox.

> [card] [User balance](https://docs.agentcard.com/api-reference/user-balance/overview.md)
>
> Let a user fund their own balance with Apple Pay or Google Pay.

> [card] [Transactions](https://docs.agentcard.com/api-reference/transactions/overview.md)
>
> Read every charge and Vault checkout on your company, the same way the webhooks report them.

> [card] [Identity verification](https://docs.agentcard.com/api-reference/identity-verification/overview.md)
>
> KYC: documents, extra fields, face scan, status.

> [card] [Webhook endpoints](https://docs.agentcard.com/api-reference/webhook-endpoints/overview.md)
>
> Register where events are delivered and rotate signing secrets.

> [card] [Blooio connection](https://docs.agentcard.com/api-reference/blooio/overview.md)
>
> Let Agentcard send Vault links from your Blooio numbers.

## Authentication

Every endpoint is called from your backend with a **platform access token**:

```
Authorization: Bearer <access_token>
```

Mint it on [Create an access token](https://docs.agentcard.com/api-reference/access-tokens/create.md) from your `client_id` and `client_secret` (dashboard → Settings → Developers → Credentials). A sandbox client mints sandbox tokens, a production client mints production tokens. Tokens live one hour.

## Two tokens, two jobs

| Token | Where you get it | What it does |
| - | - | - |
| **Platform access token** | [Create an access token](https://docs.agentcard.com/api-reference/access-tokens/create.md) | Authenticates **your platform**. The bearer on almost every endpoint here. |
| **Connection token** | [Verify the code](https://docs.agentcard.com/api-reference/connections/verify.md) | Acts **as one user**. The bearer on the MCP server. |

The connection token belongs to the user. Platform endpoints name the user with `user_id` instead of taking their token. Keep it fresh with [Refresh the connection](https://docs.agentcard.com/api-reference/connections/refresh.md).

## Test from this reference

1. Open [Create an access token](https://docs.agentcard.com/api-reference/access-tokens/create.md), paste a sandbox `client_id` and `client_secret`, hit **Send**.
2. Paste the `access_token` into the **Authorization** field on any endpoint page. It is remembered as you move between pages.
3. Fill the parameters and hit **Send**. You are hitting the live API. In sandbox the connect code is always `111111`.

## Ids

Every id Agentcard issues starts with a prefix that names the object it points to, then an underscore and a random part, such as `card_3f9a1c2e4b5d6a7f8e9d0c1b`. The prefix tells you what an id holds when you read a log, a response, or a webhook.

| Prefix | Object |
| - | - |
| `org_` | An organization |
| `usr_` | A user |
| `ch_` | A cardholder |
| `card_` | A card Agentcard issued |
| `cc_` | An added card |
| `vc_` | A stored card in the Vault |
| `ca_` | A connect attempt |
| `cns_` | A consent |
| `oa_` | An onboarding attempt |
| `cos_` | A cardholder onboarding session |
| `vs_` | A vault session |
| `cprep_` | A checkout preparation |
| `cauth_` | A checkout authorization |
| `cout_` | A reported checkout outcome |
| `apg_` | An autopilot grant |
| `ape_` | An autopilot execution |
| `pol_` | A preset |
| `appr_` | An approval |
| `conv_` | A purchase conversation |
| `txn_` | A card transaction |
| `owt_` | A company wallet transfer |
| `rcv_` | A recovery |
| `wd_` | A withdrawal |
| `wrec_` | A withdrawal recipient |
| `we_` | A webhook endpoint |
| `whd_` | A webhook delivery |
| `evt_` | An event |
| `rdm_` | A rewards redemption |
| `pl_` | A pending merchant link |

An id you received earlier may carry no prefix, such as `cmturxopj0004cbpswhqdeyju` on a stored card. Treat every id as an opaque string: store it and pass it back exactly as you received it, never parse it, and never check it for a prefix. Three values are not Agentcard object ids and keep their own shape: `client_id` is your OAuth client identifier, `external_user_id` is the id you gave Agentcard for a user, and the `id` on a `transaction.*` event is the card network's reference for that charge.

## Errors

Every error uses the same envelope:

```json theme={null}
{
  "error": {
    "code": "invalid_code",
    "message": "That code is invalid or expired.",
    "docs": "https://docs.agentcard.sh/api-reference/overview"
  }
}
```

`code` is stable and machine-readable. Branch on it. `message` is safe to log. Each endpoint page lists the codes it can return.

## Webhooks

Events are signed and delivered to the endpoints you register under [Webhook endpoints](https://docs.agentcard.com/api-reference/webhook-endpoints/overview.md). Every event and its payload is documented in the [Webhooks](https://docs.agentcard.com/webhooks/overview.md) tab.


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