HTTP API

The klw daemon exposes a local REST API for agents and integrations that do not support MCP. The API runs on the user's device.

Item	Value
Base URL	http://127.0.0.1:7723
Auth	Authorization: Bearer <token>
Token path	~/.kleepay/daemon_token
Unauthenticated endpoint	GET /health

Connection example

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

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

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

Convenience endpoints

Method	Path	Description
GET	/health	Daemon health, version, loaded signing key, and uptime. No auth required.
GET	/cards	List cards for the authenticated user. Returns safe metadata such as card_id, label, last four, status, and balance.
POST	/authorize	Authorize a card payment. Signs a scoped authorization; incoming charges are approved only when they match it (amount, merchant, time window).
POST	/merchant-bind	Create a server-capped merchant verification authorization for first-add card checks.
POST	/recurring	Create a recurring subscription authorization.
POST	/sign-policy-window	Low-level signing primitive. Prefer /authorize, /merchant-bind, or /recurring for agent integrations.
POST	/sign-card-policy-window	Low-level card-authorization signing primitive backing /authorize. Prefer /authorize for agent integrations.
POST	/sign-revocation	Low-level revocation primitive. Prefer authorization cancellation through MCP when possible.

Prefer MCP for agent integrations when possible. Use HTTP for agents or services that cannot run an MCP client.

Authorize a payment

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,
    "merchant_name": "vercel.com",
    "currency": "USD",
    "authorization_type": "exact",
    "ttl_minutes": 30
  }'

Request fields:

Field	Required	Notes
card_id	yes	Card to authorize.
amount	yes	Charge amount.
merchant_name	yes	Merchant to scope the authorization to.
currency	no	Defaults to USD.
authorization_type	no	exact (default) or ceiling (charge up to this amount).
ttl_minutes	no	Authorization lifetime; defaults to 30 minutes.

The daemon HTTP /authorize field is merchant_name. The equivalent MCP tool, kleepay_authorize, uses merchant_domain for the same scope. Use whichever matches the interface you are calling.

Example response:

{
  "policy_id": "pw_a1b2c3d4",
  "card_id": "card_7f3a9c2d",
  "amount": "49.00",
  "currency": "USD",
  "authorization_type": "exact",
  "expires_at": "2026-04-09T10:45:00Z",
  "status": "active"
}

The policy_id field is a legacy-named identifier for the created authorization. Some MCP or cloud surfaces may also return authorization_id; user-facing flows should describe the object as a scoped authorization either way.

Signing proxy

Beyond the convenience endpoints, the daemon forwards any request under /v1/* to the KleePay cloud API and adds Ed25519 signature headers for you.

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

Use this path when an agent needs access to wallet, transaction, or authorization operations that are implemented by the cloud API but should still be signed locally.

What not to expose

The local API should not be treated as a card-details API. Agents should operate on safe identifiers and authorizations. Do not put PAN, CVV, or unrestricted card credentials in agent prompts, logs, or tool outputs.