klutch – OpenClaw Skill

---

name: klutch description: OpenClaw skill for Klutch programmable credit card API integration. View cards, transactions, spending categories, and analyze spending patterns. metadata: openclaw: emoji: 💳 requires: env: [] optional_env: - KLUTCH_CLIENT_ID - KLUTCH_SECRET_KEY - KLUTCH_API_KEY - KLUTCH_API_SECRET - KLUTCH_1PASSWORD_ITEM install: - id: pip kind: pip requirements: requirements.txt

Klutch Skill

OpenClaw skill for Klutch programmable credit card API integration.

Overview

This skill provides a command-line interface for accessing Klutch credit card data through their GraphQL API. It supports viewing card information, transaction history, spending categories, and spending analysis.

Prerequisites

1. Klutch Account: Active Klutch credit card account
2. API Credentials: Client ID and Secret Key from Klutch developer portal
3. Python 3.10+: Required for running the scripts

Configuration

Environment Variables

Set your Klutch API credentials:

# Option 1: Direct credentials
export KLUTCH_CLIENT_ID="your-client-id"
export KLUTCH_SECRET_KEY="your-secret-key"

# Option 2: 1Password CLI integration (requires 'op' CLI)
export KLUTCH_1PASSWORD_ITEM="Klutch API Credential"

Configuration File

The skill stores configuration and session tokens in ~/.config/klutch/:

~/.config/klutch/
├── config.json      # User preferences
└── token.json       # Cached session token (auto-managed)

Configuration Options

Edit ~/.config/klutch/config.json to customize:

{
  "api": {
    "endpoint": "https://graphql.klutchcard.com/graphql",
    "timeout": 30
  }
}

Commands Reference

Balance

# Check card information
python scripts/klutch.py balance

# Example output:
{
  "cards": [
    {
      "id": "crd_xxx",
      "name": "Martin Kessler",
      "status": "ACTIVE"
    }
  ]
}

Transactions

# List recent transactions (last 30 days)
python scripts/klutch.py transactions

# Limit results
python scripts/klutch.py transactions --limit 25

# Example output:
{
  "transactions": [
    {
      "id": "txn_xxx",
      "amount": -100.0,
      "merchantName": "Checking",
      "transactionStatus": "SETTLED"
    }
  ]
}

Card Management

List Cards

python scripts/klutch.py card list

View Categories

python scripts/klutch.py card categories

View Spending by Category

python scripts/klutch.py card spending

Configuration Management

# Get configuration value
python scripts/klutch.py config get api.timeout

# Set configuration value
python scripts/klutch.py config set api.timeout 60

# View all configuration
python scripts/klutch.py config get

API Endpoints

The skill connects to Klutch's GraphQL API:

Environment	Endpoint
Production	https://graphql.klutchcard.com/graphql
Sandbox	https://sandbox.klutchcard.com/graphql

Authentication Flow

The skill uses Klutch's session token authentication:

1. Initial Request: Sends createSessionToken mutation with Client ID and Secret Key
2. Token Caching: Stores the JWT session token in ~/.config/klutch/token.json
3. Subsequent Requests: Uses cached token until it expires
4. Auto-Refresh: Creates a new session token when the cached one fails

Hypothetical Agent Use Cases

The Klutch skill enables agents to handle their own budget or provide personal finance assistance.

• Sub-Agent Budgeting: Create a virtual card for a sub-agent to pay for its own usage (AWS, OpenAI) with a hard limit.
• Budget Guardrails: Monitor spending categories (e.g., 'FOOD') and alert the user if they exceed a monthly budget.
• Transaction Alerts: Watch for specific merchants or unusual activity and notify the user immediately.
• Expense Summary: Summarize monthly spending and categorize transactions for personal journaling.

Error Handling

The skill handles common error scenarios:

• Authentication failures: Prompts to verify credentials
• Session expiration: Automatically creates a new session token
• Network errors: Clear error messages with retry suggestions
• GraphQL errors: Detailed error messages from the API

Integration with OpenClaw

Using from OpenClaw Sessions

# OpenClaw can invoke the skill directly
klutch balance
klutch transactions --limit 5
klutch card list

Troubleshooting

Authentication Issues

If you receive authentication errors:

1. Verify your credentials with python scripts/klutch.py config get
2. Delete ~/.config/klutch/token.json to force re-authentication
3. Check that your API credentials are correct

Session Token Issues

Force token refresh:

rm ~/.config/klutch/token.json

Security Notes

• Never commit credentials to version control
• The skill stores tokens in ~/.config/klutch/token.json
• Session tokens are refreshed automatically when needed

OpenClaw Klutch Skill

💳 OpenClaw skill for Klutch programmable credit card API integration.

Features

• Card Info: View your Klutch card details and status
• Transaction History: List recent transactions with merchant details
• Spending Categories: View transaction categories and MCC codes
• Spending Analysis: Group transactions by category
• Configuration Management: Customize API endpoint and timeouts

Prerequisites

1. Klutch Account: Active Klutch credit card account
2. API Credentials: Client ID and Secret Key from Klutch developer portal
3. Python 3.10+: Required for running the scripts

Installation

From Source

# Clone the repository
git clone https://github.com/kesslerio/openclaw-skill-klutch.git
cd openclaw-skill-klutch

# Install dependencies
pip install -r requirements.txt

Via OpenClaw

clawhub install klutch

Configuration

Environment Variables

Set your Klutch API credentials:

# Direct credentials
export KLUTCH_CLIENT_ID="your-client-id"
export KLUTCH_SECRET_KEY="your-secret-key"

# OR 1Password CLI integration (item must have "api key" and "api secret" fields)
export KLUTCH_1PASSWORD_ITEM="Klutch API Credential"

Configuration File

The skill stores configuration and session tokens in ~/.config/klutch/:

~/.config/klutch/
├── config.json      # User preferences
└── token.json       # Cached session token (auto-managed)

API Endpoints

The skill connects to Klutch's GraphQL API:

• Production: https://graphql.klutchcard.com/graphql
• Sandbox: https://sandbox.klutchcard.com/graphql (for testing)

Usage

Check Card Info

python scripts/klutch.py balance

Output:

{
  "cards": [
    {
      "id": "crd_xxx",
      "name": "Martin Kessler",
      "status": "ACTIVE"
    }
  ]
}

List Transactions

# Default (last 30 days)
python scripts/klutch.py transactions

# Custom limit
python scripts/klutch.py transactions --limit 20

Output:

{
  "transactions": [
    {
      "id": "txn_xxx",
      "amount": -100.0,
      "merchantName": "Checking",
      "transactionStatus": "SETTLED"
    }
  ]
}

Card Management

# List all cards
python scripts/klutch.py card list

# View transaction categories
python scripts/klutch.py card categories

# View spending by category
python scripts/klutch.py card spending

Configuration Management

# View all configuration
python scripts/klutch.py config get

# Get specific value
python scripts/klutch.py config get api.timeout

# Set configuration value
python scripts/klutch.py config set api.timeout 60

Troubleshooting

Authentication Issues

If you receive authentication errors:

1. Verify your credentials are set correctly
2. Delete ~/.config/klutch/token.json to force re-authentication
3. Check that your API key hasn't expired

Session Token Expired

The skill automatically creates session tokens. If you encounter issues:

rm ~/.config/klutch/token.json

Security Notes

• Never commit credentials to version control
• The skill stores tokens in ~/.config/klutch/token.json
• Session tokens are refreshed automatically when needed
• Consider using 1Password CLI for credential injection (see issue #10)

Hypothetical Agent Use Cases & Prompts

The Klutch skill enables OpenClaw agents to manage their own financial resources or act as your personal financial assistant.

1. Autonomous Sub-Agent Budgeting

Allow a sub-agent to handle its own costs for a specific task.

• Prompt: "Spawn a research agent to analyze this market. Create a Klutch virtual card for it named 'Research Task' with a $20 limit for API and tool access."

2. Smart Subscription Monitoring

Monitor recurring charges and alert on changes.

• Prompt: "Check my Klutch transactions every Monday. If my Netflix or AWS subscription cost changes by more than 10%, send me an alert on Telegram."

3. Category Spending Analysis

Get insights into where your money is going.

• Prompt: "Summarize my Klutch spending for the 'FOOD' and 'FUN' categories this month. Tell me if I'm on track to stay under my $500 budget."

4. Merchant-Locked Security

Automatically secure your online shopping.

• Prompt: "I'm about to buy something from a new store. Create a Klutch virtual card named 'One-time Shop' with a $50 limit and lock it to the merchant name 'CoolGadgets.com'."

5. Expense Reporting

Generate automated summaries for your records.

• Prompt: "At the end of every month, list my top 10 Klutch transactions and categorize them into a Markdown table for my journal."

License

MIT License - see LICENSE file for details.

Disclaimer

This is an unofficial integration. Use at your own risk. Always verify operations in the official Klutch app.