Quickstart

This guide takes a new user from an empty account to the first agent-authorized card payment.

Use the production web app links below while following this guide:

Action	Product link
Create account	Register
Sign in	Sign in
Dashboard home	Dashboard
Verify identity	KYC
Fund Balance	Deposit
Manage cards	Cards
Connect device	Devices
Review activity	Activity

The professional happy path is:

1. Create an account and verify email.
2. Complete KYC.
3. Fund the wallet balance.
4. Create and fund a virtual card.
5. Connect a device with klw (KleePay Local Wallet).
6. Let the agent create scoped authorizations.

There is one important variation: after the wallet is funded, you can connect a device first and let the agent create the card. That path is useful for agent-native onboarding. The dashboard-first path is easier for most users because it proves KYC, balance, and card setup before the agent enters the loop.

1. Create your account

Register or sign in to the KleePay web app. Complete email verification if the dashboard asks for it.

The dashboard uses an onboarding state machine to guide new users. It may show a NextStepCard for email verification, KYC, funding, card setup, or device setup.

2. Complete KYC

Go to KYC and complete identity verification. Card creation is gated by cardholder/KYC requirements, so this should be done before relying on any card or agent flow.

KYC is resumable. If the document upload or review is still in progress, return to the same page to view status or continue verification.

3. Fund your balance

Go to Deposit from the dashboard and fund your wallet balance.

Current product behavior:

• USDT is the live funding asset.
• USDC appears in the deposit and withdrawal pickers but is gated as coming soon; deposit USDT for now.
• Deposit status is tracked through Activity and deposit state polling.
• The dashboard home reconciles Balance plus On cards into total assets.

You need available balance before you can reliably create or fund a card.

4. Create a card

You now have two valid paths.

Path A: dashboard-first

Use this for the clearest first setup:

1. Go to Cards.
2. Create a new virtual card.
3. Allocate funds from Balance to the card if needed.
4. Confirm the card appears in the dashboard and has usable spending power.

This path is easiest to debug because the human has already confirmed KYC, balance, card creation, and card funding before involving an agent.

Path B: agent-assisted

Use this when you want the agent to create the card:

1. Finish KYC.
2. Fund Balance.
3. Connect a device with klw.
4. Ask the agent to call kleepay_create_card.
5. Ask the agent to call kleepay_wallet_allocate if the card needs funding.

This path requires the device step before card creation because the agent needs MCP or HTTP access to perform card and wallet actions.

5. Connect a device

Go to Devices and choose Connect device. In the current frontdesk route structure, Devices is served from /dashboard/api-keys. The dashboard returns an install command containing a setup token.

The device itself does not expire, but the setup command does. The current frontdesk shows a countdown and lets you regenerate the command if it expires.

On macOS or Linux:

curl -fsSL https://klw.kleepay.ai/install.sh | sh -s -- --token '<YOUR_TOKEN>'

On Windows PowerShell:

$env:SETUP_TOKEN='<YOUR_TOKEN>'; irm https://klw.kleepay.ai/install.ps1 | iex

The installer downloads klw, binds this device with the setup token, and starts the local signer daemon.

For staging and development frontdesk builds, the install URL may point at https://klw-stag.kleepay.ai. The frontdesk derives this from NEXT_PUBLIC_KLW_BASE_URL or the current API environment.

6. Check the local daemon

The local daemon listens on:

http://127.0.0.1:7723

Check health:

curl -s http://127.0.0.1:7723/health

All endpoints except /health require the local daemon token:

TOKEN=$(cat ~/.kleepay/daemon_token)

For MCP-compatible agents, configure the agent to run:

{
  "command": "klw",
  "args": ["mcp"],
  "env": {}
}

For HTTP-only integrations, call the daemon directly:

curl -s http://127.0.0.1:7723/cards \
  -H "Authorization: Bearer $TOKEN"

7. Authorize the first payment

Agents do not receive raw card credentials. They create bounded authorizations:

curl -s http://127.0.0.1:7723/authorize \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": "card_7f3a9c2d",
    "amount": 49.00,
    "currency": "USD",
    "merchant_name": "vercel.com",
    "authorization_type": "exact",
    "ttl_minutes": 30
  }'

The authorization is locally signed and bounded by the requested amount, card, merchant context, and expiration window.

8. Audit the result

After an authorization is created, use the same local tools to audit the result:

kleepay_check_tx
kleepay_card_transactions
kleepay_list_authorizations

In the frontdesk, live money movement appears in Activity. For settled-only reconciliation, export a formal statement (PDF) from the Activity page.

Recommended first-run checklist

Step	Dashboard surface	Agent/tool surface
Verify identity	KYC	none
Fund wallet	Deposit / Balance	kleepay_deposit_address, kleepay_wallet_balance
Create card	Cards	kleepay_create_card
Fund card	Card detail / Balance	kleepay_wallet_allocate
Connect agent	Devices	klw mcp or local HTTP
Authorize payment	Activity for result	kleepay_authorize, kleepay_check_tx