Koko Finance Developer Docs

{
  "cards": [
    {"card_name": "Chase Sapphire Preferred", "annual_fee": 95},
    {"card_name": "American Express Gold Card", "annual_fee": 250}
  ],
  "params": {
    "spending": {
      "dining": 500, "travel": 300,
      "groceries": 400, "gas": 100,
      "streaming": 30, "shopping": 200,
      "other": 150
    },
    "primary_goal": "travel",
    "point_balances": [
      {"program": "chase_ur", "balance": 150000},
      {"program": "amex_mr", "balance": 80000}
    ],
    "benefit_selections": ["uber", "dining", "travel", "saks"]
  }
}

{
  "success": true,
  "data": {
    "card_details": [
      {
        "card_name": "Chase Sapphire Preferred",
        "net_value": 188,
        "verdict": "keep",
        "break_even": {"status": "spending_required"}
      },
      ...
    ],
    "portfolio_summary": {
      "total_annual_fees": 345,
      "net_value": 434,
      "total_rewards": 444
    },
    "assumptions": {"redemption_rate": 1.0, "point_value": 0.01}
  },
  "metadata": {
    "request_id": "a1b2c3d4e5f6",
    "api_version": "v1",
    "latency_ms": 52,
    "mode": "fast",
    "timestamp": "2026-03-11T14:30:00Z"
  },
  "error": null
}

{
  "card_names": [
    "Chase Sapphire Preferred",
    "Capital One Venture X"
  ],
  "params": {
    "spending": {"dining": 400, "travel": 500, "groceries": 300},
    "primary_goal": "travel"
  }
}

{
  "success": true,
  "data": {
    "comparison_table": [
      {
        "card_name": "Chase Sapphire Preferred",
        "annual_fee": 95,
        "net_value": 188,
        "total_rewards": 198,
        "break_even": {"status": "spending_required"}
      },
      ...
    ],
    "assumptions": {"redemption_rate": 1.0, "point_value": 0.01}
  },
  "metadata": {
    "request_id": "b2c3d4e5f6a1",
    "api_version": "v1",
    "latency_ms": 45,
    "mode": "fast",
    "timestamp": "2026-03-11T14:31:00Z"
  },
  "error": null
}

{
  "category": "dining",
  "params": {
    "spending": {"dining": 600, "groceries": 400},
    "credit_tier": "excellent",
    "primary_goal": "cashback"
  }
}

{
  "success": true,
  "data": {
    "recommendations": [
      {
        "card_name": "American Express Gold Card",
        "issuer": "American Express",
        "annual_fee": 250,
        "net_value": 380,
        "rewards_structure": "4x dining, 4x groceries..."
      }
    ],
    "category": "dining",
    "total_candidates": 8
  },
  "metadata": {...},
  "error": null
}

{
  "card_name": "Chase Sapphire Preferred",
  "params": {
    "spending": {
      "dining": 400, "travel": 300, "groceries": 500
    },
    "primary_goal": "travel"
  },
  "benefit_selections": ["dining", "travel"]
}

{
  "success": true,
  "data": {
    "verdict": "RENEW",
    "year2_net_value": 120.50,
    "confidence": "high",
    "downgrade_options": [...],
    "replacement_options": [...],
    "thresholds_used": {
      "cancel": -100,
      "keep": 50
    }
  },
  "metadata": {...},
  "error": null
}

{
  "merchant": "Starbucks",
  "amount": 35,
  "portfolio": [
    "Chase Sapphire Reserve",
    "Amex Gold",
    "Citi Double Cash"
  ]
}

{
  "success": true,
  "data": {
    "recommended_card": "American Express Gold Card",
    "category_detected": "dining",
    "category_method": "exact",
    "reason": "Starbucks codes as dining — Amex Gold 4x vs CSR 3x vs Citi DC 2%",
    "earnings_comparison": [
      {
        "card": "American Express Gold Card",
        "multiplier": "4x",
        "points_earned": 140,
        "program": "Membership Rewards",
        "estimated_value": "$2.10"
      },
      ...
    ]
  },
  "metadata": {...}
}

{
  "merchant": "Saks Fifth Avenue",
  "portfolio": [
    "Amex Platinum",
    "Chase Sapphire Reserve"
  ]
}

{
  "success": true,
  "data": {
    "matching_benefits": [
      {
        "card": "The Platinum Card from American Express",
        "benefit_key": "saks",
        "name": "Saks Fifth Avenue Credit",
        "value": 100,
        "frequency": "semi-annual",
        "schedule": "$50 Jan-Jun, $50 Jul-Dec",
        "note": "Your Amex Platinum has a $100 Saks Fifth Avenue Credit (semi-annual)."
      }
    ],
    "earning_recommendation": {
      "best_card": "The Platinum Card from American Express",
      "multiplier": "1x",
      "note": "Saks codes as shopping — use Amex Platinum to combine with the credit."
    }
  },
  "metadata": {...}
}

GET /api/v1/card-benefits?card=Amex%20Platinum

{
  "success": true,
  "data": {
    "card": "The Platinum Card from American Express",
    "issuer": "American Express",
    "annual_fee": 695,
    "credits": [
      {
        "benefit_key": "uber",
        "name": "Uber Cash",
        "value": 200,
        "frequency": "monthly",
        "schedule": "$15/mo + $20 Dec"
      },
      {
        "benefit_key": "saks",
        "name": "Saks Fifth Avenue Credit",
        "value": 100,
        "frequency": "semi-annual"
      },
      ...
    ],
    "total_credit_value": 1584,
    "rewards_multipliers": {
      "airlines": 5,
      "hotels": 5,
      "base": 1
    },
    "points_program": "amex_mr",
    "portal_cpp": 1.1
  },
  "metadata": {...}
}

{
  "categories": [
    {
      "category": "dining_credit",
      "label": "Dining Credits",
      "keys": ["dining", "resy_dining"]
    },
    {
      "category": "lounge_access",
      "label": "Lounge Access",
      "keys": ["admirals_club", "united_club_membership"]
    },
    {
      "category": "other",
      "label": "Other Benefits",
      "keys": ["uber", "global_entry", "clear_plus", "lyft", ...]
    },
    ...
  ],
  "all_keys": ["admirals_club", "airline_fee", "avis_budget", ...],
  "usage": {
    "benefit_selections": "Pass individual keys to portfolio/analyze or card/renewal-check...",
    "benefit_categories_used": "Alternative: pass category names instead..."
  }
}