Klutch

OpenClaw skill for Klutch programmable credit card API integration. View cards, transactions, spending categories, and analyze spending patterns.

Security Scan

The skill's code, install, and runtime instructions are consistent with a Klutch API CLI integration; nothing in the package indicates intentional misdirection or exfiltration, though a few documentation claims (hypothetical agent actions) are not implemented in the shipped scripts.

Purpose & Capability

Name/description (Klutch credit-card API integration) align with the included Python scripts, which implement GraphQL calls for cards, transactions, categories, and basic config management. The optional environment variables listed in SKILL.md (KLUTCH_CLIENT_ID, KLUTCH_SECRET_KEY, KLUTCH_API_KEY, KLUTCH_API_SECRET, KLUTCH_1PASSWORD_ITEM) match the auth code paths.

Instruction Scope

Runtime instructions restrict activity to contacting Klutch GraphQL endpoints, caching a session token under ~/.config/klutch/, and optionally reading credentials via the 1Password CLI. However, README/SKILL.md include 'hypothetical agent use cases' (e.g., 'Create a virtual card for a sub-agent', 'lock to merchant') that are not implemented in the provided scripts — documentation overreach rather than hidden functionality. The code does not attempt to read unrelated system files or exfiltrate data to non-Klutch endpoints.

Install Mechanism

Install uses pip (requirements.txt) with two small, common dependencies (requests, click). No downloads from arbitrary URLs or archive extraction are present.

Credentials

The skill requests only Klutch-related credentials (client id/secret or API key/secret) and an optional KLUTCH_1PASSWORD_ITEM for op CLI retrieval — these are proportional. Two small remarks: (1) the registry metadata shows no required env vars while SKILL.md documents optional env vars (this is minor and not a security problem), and (2) the 1Password lookup in auth.py hardcodes the op URI prefix 'op://Clawd/{item}/...' which could be surprising if users keep credentials in a differently named vault.

Persistence & Privilege

The skill caches a JWT session token and a config file under ~/.config/klutch/ (token.json and config.json) with file permissions set to 0600 — expected behavior for this kind of CLI integration. The skill is not set to always:true and does not modify other skills or global agent settings.

Assessment

This package appears to be a straightforward Klutch API client, but before installing consider: 1) The skill source is 'unknown' — only install if you trust the publisher or review the code yourself. 2) Provide only Klutch API credentials (client id/secret or API key/secret). The code will cache a session token at ~/.config/klutch/token.json — review or remove that file if you revoke access. 3) If you plan to use 1Password integration, ensure the 'op' CLI is installed and that your vault/item names match the code's expectations (the code uses the 'Clawd' vault prefix). 4) Do not assume advanced agent capabilities claimed in README (creating virtual cards, merchant locking, autonomous sub-agent billing) are implemented — those are hypothetical prompts and are not present in the provided scripts. 5) If you need higher assurance, run the scripts locally and inspect network calls (or grep for unexpected hosts) before granting credentials.

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