# Klutch

> Klutch (Klutch Card) issues an "app-powered" programmable credit card whose behavior is extended by user-installable Mini Apps. Its public GraphQL API exposes enriched card transactions with acquirer metadata, virtual card lifecycle, server-side transaction rules that approve or decline spend, account balances, ACH card payments, and Mini App panel rendering. Klutch runs a production and a sandbox GraphQL endpoint, OAuth 2.1 with PKCE and dynamic client registration, transaction webhooks, a developer CLI, a first-party JavaScript SDK, and a remote MCP server for Claude and ChatGPT.

Generated by the API Evangelist enrichment pipeline on 2026-07-19. Klutch does not publish its own /llms.txt (probed 404).

## API

- [Klutch Public API (GraphQL)](https://api-docs.klutchcard.com/): Postman-published reference for the whole operation surface.
- Production endpoint: https://graphql.klutchcard.com/graphql
- Sandbox endpoint: https://sandbox.klutchcard.com/graphql
- Introspection is DISABLED on both endpoints; use the Postman collection as the contract.

## Developer

- [Developer overview](https://www.klutchcard.com/developer): what the API and Mini App platform can do.
- [Tutorials](https://www.klutchcard.com/tutorials): differential budgeting, swipe twice, AI product categorization, Klutch MCP.
- [GitHub organization](https://github.com/KlutchCard): api-samples, miniapp-example, klutch-cli.
- [Help center](https://help.klutchcard.com/)

## Agents

- Klutch MCP server (remote, hosted): https://mcp.klutchcard.com — OAuth 2.1 + PKCE, dynamic client registration, works with Claude and ChatGPT.
- [Klutch MCP article](https://www.klutchcard.com/articles/klutch-mcp)

## Authentication

- Bearer token on every GraphQL call.
- Developer flow: `mutation { createSessionToken(clientId: $clientId, secretKey: $secretKey) }` using credentials from My Account -> Developers.
- Agent/user flow: OAuth 2.1 authorization code with PKCE (S256). Metadata: https://graphql.klutchcard.com/.well-known/oauth-authorization-server
- Scopes are identity-only (openid, email, phone, profile). Resource access for Mini Apps is governed by the per-install permission grant.

## Core operations

- Transactions: `transactions`, `transactionsPaginated(filter, sortOrder, limit, nextCursor)`, `transaction(id)`, `sumTransactions(filter)`, `groupTransactions(filter, groupByProperty, operation)`
- Categories: `transactionCategories`, `createTransactionCategory`, `transactionCategory(id){rename|delete}`, `transaction(id){item(id){change(categoryId)}}`
- Cards: `cards`, `createCard`, `card(id){activateCard|editCard|lock|unlock|cancelCard}`
- Rules: `createTransactionRule(name, displayName, cardIds, spec)`, `transactionRules`, `transactionRule(id){delete}`, `transactionRule(name){disableFor(durationInSeconds)}`
- Account and payments: `account{revolvingLoan{balance limit}}`, `transferSources`, `createPayment(transferSourceId, type, amount)`
- Mini Apps: `recipeInstall(id){createToken|addPanel|panel(id){changeData|delete}}`
- Sandbox only: `sandbox{createTransaction|reverseTransaction|settleTransaction}`

## Events

- Webhooks are registered in the Klutch account UI under My Account -> Developers.
- Event types observed: `com.alloycard.core.entities.transaction.TransactionCreatedEvent`, `com.alloycard.core.entities.transaction.TransactionItemCreatedEvent`
- Payloads carry entity IDs only; re-read state through the API.

## Packages

- @klutch-card/klutch-js (JavaScript SDK) — https://www.npmjs.com/package/@klutch-card/klutch-js
- @klutch-card/klutch-cli (CLI, `klutch`) — https://www.npmjs.com/package/@klutch-card/klutch-cli
- @klutch-card/klutch-components (Mini App components) — https://www.npmjs.com/package/@klutch-card/klutch-components

## Cautions for agents

- No idempotency contract is documented. Treat `createPayment`, `createCard` and `createTransactionRule` as non-idempotent; verify state before retrying.
- No rate limits are published.
- Errors arrive as HTTP 200 with a GraphQL `errors[]` array; check `extensions.classification`.
- A declined card authorization is NOT an API error — it is a transaction with `transactionStatus: DECLINED` and a free-text `declineReason`.
- Money movement (`createPayment`) and card issuance are consequential actions; require explicit human confirmation.

## API Evangelist artifacts

- apis.yml: https://raw.githubusercontent.com/api-evangelist/klutch/refs/heads/main/apis.yml
- Operation catalog: graphql/klutch-graphql-operations.yml
- Conventions: conventions/klutch-conventions.yml
- Authentication: authentication/klutch-authentication.yml
- Webhook catalog: asyncapi/klutch-webhooks.yml
- Sandbox: sandbox/klutch-sandbox.yml
- Data model: data-model/klutch-data-model.yml
- Errors: errors/klutch-error-codes.yml