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

# Quickstart

> Authenticate a user, verify their identity, fund a card, and issue it from your server so your agent can pay with it. Sandbox, about fifteen minutes.

Issuing gives your agent a card number. Your server creates a virtual card for a user, and your agent types it into any checkout. The user verifies their identity once, then you can create as many cards for them as you need.

The flow in one line: authenticate the user → they complete KYC → you fund the balance → your server creates a card → your agent pays with it.

Steps 1 to 4 are setup. Steps 5 and 6 happen on every purchase.

## 1. Get your credentials

You need an Agentcard organization `client_id` and `client_secret` from the [dashboard](https://app.agentcard.sh). Exchange them for an access token:

```bash theme={null}
curl -X POST https://api.agentcard.sh/api/v2/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=$AGENTCARD_CLIENT_ID \
  -d client_secret=$AGENTCARD_CLIENT_SECRET
```

Use the returned token as `$ORG_TOKEN`. Sandbox credentials create sandbox users and test cards. Start there.

## 2. Authenticate a user

Send the user a one-time code, then verify it. In sandbox the code is always `111111`.

```bash theme={null}
curl -X POST https://api.agentcard.sh/api/v2/connect/start \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

curl -X POST https://api.agentcard.sh/api/v2/connect/verify \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"connect_id": "CONNECT_ATTEMPT_ID", "code": "111111"}'
```

```json theme={null}
{
  "object": "connection",
  "access_token": "act_1a2b3c…",
  "refresh_token": "rct_4d5e6f…",
  "expires_in": 3600,
  "user": { "id": "usr_7g8h9i", "email": "user@example.com" }
}
```

Store `user.id`. Every card call names the user with it, using your org token. You don't need the `access_token` or `refresh_token` for the steps below.

Record consent once:

```bash theme={null}
curl -X POST https://api.agentcard.sh/api/v2/connect/consent \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "usr_7g8h9i"}'
```

[More on authenticating →](https://docs.agentcard.com/issuing/authenticating-a-user.md)

## 3. Complete KYC

Issued cards require identity verification. Read the status, and hand the user the hosted page it returns:

```bash theme={null}
curl "https://api.agentcard.sh/api/v2/kyc?user_id=usr_7g8h9i" \
  -H "Authorization: Bearer $ORG_TOKEN"
```

```json theme={null}
{ "object": "kyc", "status": "requires_verification", "iframe_url": "https://in.sumsub.com/websdk/p/…" }
```

The user completes document capture and a face scan on that page. You learn the outcome from `identity.verification.updated` or by reading the status again. In sandbox nothing is reviewed, so approve the test user directly:

```bash theme={null}
curl -X POST https://api.agentcard.sh/api/v2/kyc/simulate \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "usr_7g8h9i", "outcome": "approved"}'
```

[More on KYC →](https://docs.agentcard.com/issuing/completing-a-kyc.md)

## 4. Fund the company balance

Your company balance funds this card. If your organization is user-funded, switch it to company-funded once, in the dashboard under Settings, Issuing. An org owner has to do this. The change takes effect in sandbox immediately, and sandbox needs no plan or subscription. Until you switch, creating the card below is refused with `company_flow_unavailable`.

Then add test money. In sandbox it is a mock balance and never real money:

```bash theme={null}
curl -X POST https://api.agentcard.sh/api/v2/company_wallet/test_fund \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 5000}'
```

```json theme={null}
{
  "object": "company_wallet",
  "livemode": false,
  "balance_cents": 5000,
  "committed_cents": 0,
  "available_cents": 5000,
  "flow_of_funds": "company",
  "default_funds_source": "company_flow"
}
```

To have users pay for their own cards instead, see [Fund the card](https://docs.agentcard.com/issuing/issuing-a-card.md#fund-the-card).

## 5. Create a card

Create the card with the user's id:

```bash theme={null}
curl -X POST https://api.agentcard.sh/api/v2/cards \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "usr_3305e8868868f3665f6cb0ed", "amount_cents": 2500}'
```

```json theme={null}
{
  "object": "card",
  "id": "card_22943fc47c3865e20527c7a5",
  "status": "open",
  "spend_limit_cents": 2500,
  "balance_cents": 2500,
  "last4": "6803",
  "expiry": "11/28",
  "created_at": "2026-11-02T02:22:03.304Z",
  "type": "single_use",
  "user_id": "usr_3305e8868868f3665f6cb0ed",
  "funds_source": "company_flow",
  "transfer_id": "owt_ca3c70fc335e4ba093851ac4"
}
```

Sandbox issues a test card immediately. In production a create can be refused first, for example with `kyc_required` or `org_wallet_funding_required`, which point back to steps 3 and 4.

[More on issuing →](https://docs.agentcard.com/issuing/issuing-a-card.md)

## 6. Use the card

Read the credentials when your agent is at the checkout, not before:

```bash theme={null}
curl https://api.agentcard.sh/api/v2/cards/card_22943fc47c3865e20527c7a5/credentials \
  -H "Authorization: Bearer $ORG_TOKEN"
```

```json theme={null}
{
  "object": "card_credentials",
  "id": "card_22943fc47c3865e20527c7a5",
  "number": "…",
  "exp_month": "11",
  "exp_year": "2028",
  "cvc": "…",
  "last4": "6803"
}
```

Type them into the merchant's form. A single-use card closes itself after its first approved charge. `transaction.authorized` tells your server money moved.

[More on using cards →](https://docs.agentcard.com/issuing/using-the-cards.md)

## What's next

> [card] [Authenticating a user](https://docs.agentcard.com/issuing/authenticating-a-user.md)
>
> Tokens, consent, refresh, and what each credential may call.

> [card] [Completing a KYC](https://docs.agentcard.com/issuing/completing-a-kyc.md)
>
> Hosted or custom verification, statuses, sandbox simulation.

> [card] [Issuing a card](https://docs.agentcard.com/issuing/issuing-a-card.md)
>
> Funding, single-use and multi-use cards, merchant locks.

> [card] [Using the cards](https://docs.agentcard.com/issuing/using-the-cards.md)
>
> Reading credentials, paying, pausing, closing, webhooks.


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