> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

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

Issuing gives your agent a card number. Agentcard creates a virtual card for the user, funded from a balance they hold with us, and your agent types it into any checkout. The user verifies their identity once, then can create as many cards as they need.

**The flow in one line:** authenticate the user → they complete KYC → they add funds → your agent creates a card → your agent pays with it.

Steps 1 to 3 happen once per user. Steps 4 and 5 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": "user_7g8h9i", "email": "user@example.com" }
}
```

Store all three. `user.id` names the user on every call your server makes. `access_token` is the **connection token**: it acts as the user, and it is what your agent will create and use cards with.

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": "user_7g8h9i"}'
```

[More on authenticating →](/issuing/authenticating-a-user)

## 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=user_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": "user_7g8h9i", "outcome": "approved"}'
```

[More on KYC →](/issuing/completing-a-kyc)

## 4. Fund the balance and issue a card

Cards draw on the user's balance. Your agent does both steps through the Agentcard MCP server, connected with the user's connection token:

```bash theme={null}
claude mcp add agentcard-user --transport http https://mcp.agentcard.sh/mcp \
  --header "Authorization: Bearer act_1a2b3c…"
```

Call `add_funds` with an amount. It returns a single-use Apple Pay / Google Pay link. The user pays in their own browser. Then create the card:

```json theme={null}
{ "tool": "create_card", "arguments": { "source": "issued", "amount_cents": 2500 } }
```

The response carries the card id. Sandbox issues a test card immediately. In production, `create_card` may first return `kyc_required` or `wallet_funding_required`, which point back to steps 3 and 4.

[More on issuing →](/issuing/issuing-a-card)

## 5. Use the card

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

```json theme={null}
{ "tool": "get_card_details", "arguments": { "card_id": "card_…" } }
```

You get the number, expiry, CVC and remaining balance. 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 →](/issuing/using-the-cards)

## What's next

<CardGroup cols={2}>
  <Card title="Authenticating a user" href="/issuing/authenticating-a-user">
    Tokens, consent, refresh, and what each credential may call.
  </Card>

  <Card title="Completing a KYC" href="/issuing/completing-a-kyc">
    Hosted or custom verification, statuses, sandbox simulation.
  </Card>

  <Card title="Issuing a card" href="/issuing/issuing-a-card">
    Funding, single-use and multi-use cards, merchant locks.
  </Card>

  <Card title="Using the cards" href="/issuing/using-the-cards">
    Reading credentials, paying, pausing, closing, webhooks.
  </Card>
</CardGroup>