Koin Finance API Skill

Manage personal finances through the Koin API.

Configuration

Set these environment variables before using:

export KOIN_API_URL="{{API_URL}}"
export KOIN_API_TOKEN="<your-token-here>"

Authentication

All requests require the Bearer token:

curl -H "Authorization: Bearer $KOIN_API_TOKEN" "$KOIN_API_URL/endpoint"

Endpoints

Transactions

List Transactions

curl -H "Authorization: Bearer $KOIN_API_TOKEN" \
  "$KOIN_API_URL/transactions?startDate=2024-01-01&endDate=2024-12-31&type=expense"

Query params:

• startDate — ISO datetime filter (inclusive)
• endDate — ISO datetime filter (inclusive)
• type — income or expense
• categoryId — UUID of category

Create Transaction

curl -X POST -H "Authorization: Bearer $KOIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$KOIN_API_URL/transactions" \
  -d '{
    "type": "expense",
    "amount": "25.50",
    "description": "Lunch at cafe",
    "categoryId": "uuid-here",
    "date": "2024-01-15T12:00:00Z"
  }'

Required: type, amount

• type — income or expense
• amount — positive decimal value

Optional: description, categoryId, date (defaults to now)

Note: For balance corrections or adjustments, use the Koin web UI.

Get Transaction

curl -H "Authorization: Bearer $KOIN_API_TOKEN" "$KOIN_API_URL/transactions/:id"

Update Transaction

curl -X PATCH -H "Authorization: Bearer $KOIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$KOIN_API_URL/transactions/:id" \
  -d '{"amount": "30.00"}'

Delete Transaction

curl -X DELETE -H "Authorization: Bearer $KOIN_API_TOKEN" "$KOIN_API_URL/transactions/:id"

Categories

List Categories

curl -H "Authorization: Bearer $KOIN_API_TOKEN" "$KOIN_API_URL/categories"

Create Category

curl -X POST -H "Authorization: Bearer $KOIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$KOIN_API_URL/categories" \
  -d '{
    "name": "Food & Dining",
    "description": "Restaurants, groceries, coffee",
    "color": "#ef4444"
  }'

Required: name Optional: description, color (hex format)

Update Category

curl -X PATCH -H "Authorization: Bearer $KOIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$KOIN_API_URL/categories/:id" \
  -d '{"color": "#22c55e"}'

Delete Category

curl -X DELETE -H "Authorization: Bearer $KOIN_API_TOKEN" "$KOIN_API_URL/categories/:id"

Summary

Get Financial Summary

curl -H "Authorization: Bearer $KOIN_API_TOKEN" \
  "$KOIN_API_URL/summary?startDate=2024-01-01&endDate=2024-01-31"

Returns:

{
  "data": {
    "income": 5000.00,
    "expenses": 2500.00,
    "adjustments": 100.00,
    "balance": 2600.00,
    "byCategory": [
      {"categoryId": "...", "categoryName": "Food", "total": "500.00", "count": 15}
    ]
  }
}

Balance formula: income - expenses + adjustments

Note: adjustments are balance corrections made via the web UI.

AI Commands

Use natural language to bulk update transactions. Commands are staged for review before execution.

Create Command (Interpret & Preview)

curl -X POST -H "Authorization: Bearer $KOIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$KOIN_API_URL/ai/command" \
  -d '{"prompt": "Put all coffee expenses in Food category"}'

Returns:

{
  "data": {
    "commandId": "uuid",
    "interpretation": "I'll categorize transactions containing 'coffee' as Food.",
    "preview": {
      "matchCount": 5,
      "records": [
        {
          "id": "tx-uuid",
          "before": {"description": "Coffee", "category": null, "amount": "5.50"},
          "after": {"description": "Coffee", "category": "Food", "amount": "5.50"}
        }
      ]
    },
    "expiresIn": 300
  }
}

Get Command Status

curl -H "Authorization: Bearer $KOIN_API_TOKEN" "$KOIN_API_URL/ai/command/:id"

Confirm Command (Execute)

curl -X POST -H "Authorization: Bearer $KOIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$KOIN_API_URL/ai/command/:id/confirm" \
  -d '{}'

Returns:

{
  "data": {
    "commandId": "uuid",
    "status": "confirmed",
    "updatedCount": 5,
    "message": "Successfully updated 5 transaction(s)"
  }
}

Cancel Command

curl -X POST -H "Authorization: Bearer $KOIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$KOIN_API_URL/ai/command/:id/cancel" \
  -d '{}'

Supported filters: description, amount, amount range, date range, category name, transaction type

Supported changes: category, amount, description, type

Rate limit: 10 requests per minute per user

Note: Commands expire after 5 minutes (300 seconds) if not confirmed.

Settings

Get User Settings

curl -H "Authorization: Bearer $KOIN_API_TOKEN" "$KOIN_API_URL/settings"

Returns:

{
  "data": {
    "currency": "USD",
    "name": "John Doe"
  }
}

Update User Settings

curl -X PATCH -H "Authorization: Bearer $KOIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$KOIN_API_URL/settings" \
  -d '{"currency": "EUR"}'

Optional fields: currency (3-char code, e.g., USD, EUR, IDR), name

Common Tasks

Log an expense

curl -X POST -H "Authorization: Bearer $KOIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$KOIN_API_URL/transactions" \
  -d '{"type": "expense", "amount": "15.00", "description": "Coffee"}'

Log income

curl -X POST -H "Authorization: Bearer $KOIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$KOIN_API_URL/transactions" \
  -d '{"type": "income", "amount": "3000.00", "description": "Salary"}'

Check this month's spending

START=$(date -d "$(date +%Y-%m-01)" +%Y-%m-%dT00:00:00Z)
END=$(date +%Y-%m-%dT23:59:59Z)
curl -H "Authorization: Bearer $KOIN_API_TOKEN" "$KOIN_API_URL/summary?startDate=$START&endDate=$END"

Response Format

All responses follow:

{
  "data": { ... }
}

Errors:

{
  "error": "Error message or validation issues"
}

Setup Instructions

1. Copy this file to your AI agent's workspace (e.g., skills/koin/SKILL.md)
2. The API_URL above is pre-configured for your account
3. Create an API token in Settings → API Tokens, then set KOIN_API_TOKEN
4. Your agent can now manage your finances using the endpoints above