Quickstart

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. Exchange them for an access token:

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.

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"}'

{
  "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:

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"}'

3. Complete KYC

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

curl "https://api.agentcard.sh/api/v2/kyc?user_id=user_7g8h9i" \
  -H "Authorization: Bearer $ORG_TOKEN"

{ "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:

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"}'

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:

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:

{ "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 →

5. Use the card

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

{ "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 →

What’s next

Authenticating a user

Tokens, consent, refresh, and what each credential may call.

Completing a KYC

Hosted or custom verification, statuses, sandbox simulation.

Issuing a card

Funding, single-use and multi-use cards, merchant locks.

Using the cards

Reading credentials, paying, pausing, closing, webhooks.

Getting started

Vault

Issuing

1. Get your credentials

2. Authenticate a user

3. Complete KYC

4. Fund the balance and issue a card

5. Use the card

What’s next

Authenticating a user

Completing a KYC

Issuing a card

Using the cards

​1. Get your credentials

​2. Authenticate a user

​3. Complete KYC

​4. Fund the balance and issue a card

​5. Use the card

​What’s next

Authenticating a user

Completing a KYC

Issuing a card

Using the cards

1. Get your credentials

2. Authenticate a user

3. Complete KYC

4. Fund the balance and issue a card

5. Use the card

What’s next