CardCheck API v1

CardCheck API & MCP Reference

The CardCheck API gives developers programmatic access to India's most comprehensive verified credit card dataset — covering 150+ cards with official MITC data, real-time spend optimization, and an MCP server for AI agent integration.

@cardcheck/mcp-server

One unified tool for Claude Desktop, Cursor & Antigravity

REST API

JSON over HTTPS for PFM apps, fintech, and browser use

API Keys

Scoped Bearer tokens with rate limiting and tier quotas

MCP Telemetry

Non-blocking invocation events for your admin dashboard

Base URL: https://cardcheck.in/api/v1

Authentication

All REST API endpoints require a Bearer token in the Authorization header. MCP users pass the key via the CARDCHECK_API_KEY environment variable.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxx

http

API Key Tiers

Tier	Rate Limit	Monthly Quota	Scopes
Sandbox	60 req/min	10,000 req/mo	`cards:read`
Starter	120 req/min	100,000 req/mo	`cards:readoptimize:execute`
Pro	300 req/min	1,000,000 req/mo	`All Scopes`

No key? The MCP server works in offline mode without a key — using a bundled 7-card benchmark dataset. Set CARDCHECK_API_KEY to unlock all 150+ cards in real-time.

MCP Quick Start

The CardCheck MCP server uses the Model Context Protocol over stdio. It registers one tool — cardcheck_advisor — covering all four actions. Works with Claude Desktop, Cursor, and Antigravity.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "cardcheck": {
      "command": "npx",
      "args": ["-y", "@cardcheck/mcp-server"],
      "env": {
        "CARDCHECK_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

json — claude_desktop_config.json

Cursor IDE

Add to .cursor/mcp.json

{
  "mcpServers": {
    "cardcheck": {
      "command": "npx",
      "args": ["-y", "@cardcheck/mcp-server"],
      "env": { "CARDCHECK_API_KEY": "YOUR_API_KEY" }
    }
  }
}

json — .cursor/mcp.json

Antigravity IDE

Add to .agents/mcp_config.json

{
  "mcpServers": {
    "cardcheck": {
      "command": "npx",
      "args": ["-y", "@cardcheck/mcp-server"],
      "env": { "CARDCHECK_API_KEY": "YOUR_API_KEY" },
      "lazyLoad": true
    }
  }
}

json — .agents/mcp_config.json

cardcheck_advisor

MCPcardcheck_advisor

The unified CardCheck tool. Every AI agent call routes through this single entry point. The action parameter determines which capability is invoked.

Tool Input Parameters

actionenumrequired

The credit card intelligence operation to execute. Determines which backend routine or endpoint calculates the recommendation.

Allowed values:optimize_spendsearch_cardsget_card_detailsrecommend_portfolio

spend_amount_inrnumberoptionaldefault: 1000

Transaction amount in INR for spend optimization. Example: 6000.

merchantstringoptional

Merchant name to match accelerated partnership multipliers (e.g. "swiggy", "amazon", "flipkart", "makemytrip", "zomato").

categoryenumoptionaldefault: online

Spend category used when merchant multiplier is not explicitly specified.

Allowed values:onlinediningtravelgroceriesfuelutilitiesintlother

user_cardsstring[]optional

Optional array of card IDs currently held in the user's wallet (e.g. ["hdfc-infinia-metal", "axis-ace"]). If omitted, evaluates across all cards in the database.

querystringoptional

Search term or card slug used for search_cards and get_card_details.

monthly_spendsRecord<string, number>optional

Monthly spend breakdown by category for portfolio recommendation (e.g. {"online": 25000, "dining": 8000, "travel": 10000}).

cibil_scorenumberoptionaldefault: 750

User's CIBIL credit score (300–900) for strict eligibility filtering.

Dual Mode Execution: Without CARDCHECK_API_KEY, runs locally in offline benchmark mode using a pre-bundled 7-card dataset (<1ms). With an API key, performs live HTTPS sync against all 150+ cards with a 3.5s timeout and automatic offline failover.

optimize_spend

MCPcardcheck_advisor { action: "optimize_spend" }

Returns the mathematically optimal card for a specific transaction. Evaluates merchant-level multipliers first, then category-level, then base reward rate.

{
  "action": "optimize_spend",
  "spend_amount_inr": 6000,
  "merchant": "swiggy",
  "category": "dining",
  "user_cards": ["hdfc-infinia-metal", "swiggy-hdfc"]
}

mcp tool call

Response

{
  "action": "optimize_spend",
  "live_sync": false,
  "transaction": {
    "amount_inr": 6000,
    "merchant": "swiggy",
    "category": "dining",
    "filtered_to_user_wallet": true
  },
  "top_recommendation": {
    "card_name": "HDFC Bank Infinia Metal Credit Card",
    "bank": "HDFC Bank",
    "estimated_reward_inr": 996,
    "effective_rate_pct": 16.6,
    "reward_type": "reward_points",
    "reason": "HDFC Bank Infinia Metal Credit Card offers accelerated 16.6% return on swiggy"
  },
  "alternative_options": [
    { "card_name": "Swiggy HDFC Bank Credit Card", "effective_rate_pct": 10.0, "estimated_reward_inr": 600 },
    { "card_name": "Axis Bank Cashback Credit Card", "effective_rate_pct": 5.0, "estimated_reward_inr": 300 }
  ],
  "data_tier": {
    "mode": "offline_benchmark",
    "cards_evaluated": "7 flagship cards",
    "unlock_all_150_cards": "Generate a free API key at https://cardcheck.in/developers..."
  }
}

json

search_cards

MCPcardcheck_advisor { action: "search_cards" }

Fuzzy-searches cards by name, bank, reward type, lounge description, or key perks. Returns summary fields only — no full MITC details.

{
  "action": "search_cards",
  "query": "hdfc lounge"
}

mcp tool call

Response

{
  "action": "search_cards",
  "live_sync": false,
  "query": "hdfc lounge",
  "count": 2,
  "cards": [
    {
      "id": "hdfc-infinia-metal",
      "name": "HDFC Bank Infinia Metal Credit Card",
      "bank": "HDFC Bank",
      "annual_fee_inr": 12500,
      "reward_type": "reward_points",
      "base_reward_pct": 3.3,
      "domestic_lounge": "Unlimited via DreamFolks (Primary & Add-on)",
      "international_lounge": "Unlimited worldwide via Priority Pass",
      "forex_markup_pct": 2.0,
      "key_perks": ["10X on SmartBuy", "Golf privileges", "Concierge"]
    }
  ]
}

json

get_card_details

MCPcardcheck_advisor { action: "get_card_details" }

Fetches the full verified MITC factsheet for a card — all fees, lounge rules, forex markup, reward rates, and merchant multipliers.

{
  "action": "get_card_details",
  "query": "hdfc-infinia-metal"
}

mcp tool call

Response

{
  "action": "get_card_details",
  "found": true,
  "factsheet": {
    "card_id": "hdfc-infinia-metal",
    "name": "HDFC Bank Infinia Metal Credit Card",
    "bank": "HDFC Bank",
    "fees": {
      "joining_fee_inr": 12500,
      "annual_fee_inr": 12500,
      "annual_fee_waiver_spend_inr": 1000000
    },
    "eligibility": { "min_cibil_score": 750 },
    "lounge_access": {
      "domestic": "Unlimited via DreamFolks (Primary & Add-on)",
      "international": "Unlimited worldwide via Priority Pass"
    },
    "forex_markup_fee_pct": 2.0,
    "rewards": {
      "type": "reward_points",
      "base_rate_pct": 3.3,
      "top_merchant_multipliers": { "swiggy": 16.6, "amazon": 6.6 },
      "category_multipliers": { "travel": 6.6, "dining": 6.6 }
    },
    "key_benefits": ["10X on SmartBuy", "Golf privileges", "Concierge service"]
  }
}

json

recommend_portfolio

MCPcardcheck_advisor { action: "recommend_portfolio" }

Recommends the best credit card portfolio based on monthly spend profile and CIBIL score. Returns net annual value after fees for each eligible card.

{
  "action": "recommend_portfolio",
  "monthly_spends": {
    "online": 25000,
    "dining": 8000,
    "travel": 10000,
    "fuel": 5000
  },
  "cibil_score": 780
}

mcp tool call

Response

{
  "action": "recommend_portfolio",
  "user_spend_profile": {
    "total_monthly_spend_inr": 48000,
    "cibil_score_evaluated": 780
  },
  "top_recommended_card": {
    "card_id": "hdfc-infinia-metal",
    "card_name": "HDFC Bank Infinia Metal Credit Card",
    "monthly_reward_inr": 1848,
    "annual_gross_reward_inr": 22176,
    "annual_fee_inr": 12500,
    "net_annual_value_inr": 9676,
    "effective_overall_return_pct": 3.85,
    "lounge_access": "Unlimited via DreamFolks"
  },
  "ranked_alternatives": [...]
}

json

Search Cards

GET/api/v1/cards/search

Full-text search across card names, banks, and benefits. Returns up to 10 results with summary fields only. Requires cards:read scope.

Query Parameters

qstringrequired

Search term (min 2 characters). Matches across card names, bank names, reward tags, and network badges. Example: "hdfc" or "cashback".

GET https://cardcheck.in/api/v1/cards/search?q=hdfc
Authorization: Bearer cc_live_xxx

http

Response

{
  "results": [
    {
      "id": "hdfc-infinia-metal",
      "name": "HDFC Bank Infinia Metal Credit Card",
      "bank": "HDFC Bank",
      "annual_fee_inr": 12500,
      "reward_type": "reward_points",
      "base_reward_pct": 3.3,
      "network": "Visa Infinite",
      "image_url": "https://cardcheck.in/images/cards/hdfc-infinia-metal.webp"
    }
  ],
  "count": 1,
  "query": "hdfc"
}

json

Get Card by ID

GET/api/v1/cards/:cardId

Returns the full verified factsheet for a specific card. Includes fees, lounge rules, reward structure, forex markup, UPI linkability, and eligibility criteria.

Path Parameters

cardIdstringrequired

Unique card URL slug identifier. Example: "hdfc-infinia-metal", "axis-atlas", "sbi-cashback".

GET https://cardcheck.in/api/v1/cards/hdfc-infinia-metal
Authorization: Bearer cc_live_xxx

http

Response

{
  "id": "hdfc-infinia-metal",
  "name": "HDFC Bank Infinia Metal Credit Card",
  "bank": "HDFC Bank",
  "network": "Visa Infinite",
  "joining_fee_inr": 12500,
  "annual_fee_inr": 12500,
  "fee_waiver_spend_inr": 1000000,
  "min_income_inr": 2400000,
  "min_cibil_score": 750,
  "forex_markup_pct": 2.0,
  "upi_linkable": true,
  "lounge_domestic": "Unlimited via DreamFolks (Primary & Add-on)",
  "lounge_international": "Unlimited worldwide via Priority Pass",
  "reward_type": "reward_points",
  "base_reward_pct": 3.3,
  "key_perks": ["10X on SmartBuy", "Golf privileges", "Concierge service"]
}

json

Optimize Spend

POST/api/v1/optimize/spend

Given a transaction amount and merchant/category, returns ranked cards with estimated reward values. Requires optimize:execute scope.

Request Body JSON

amount_inrnumberrequired

Transaction amount in INR. Values are automatically clamped to positive numbers.

merchantstringoptional

Merchant name to match specific accelerated rewards (e.g. "swiggy", "amazon", "flipkart").

categorystringoptionaldefault: online

Fallback spend category used if merchant rule is not found.

user_cardsstring[]optional

Array of card slugs to filter results to. Omit to rank across all cards in the database.

POST https://cardcheck.in/api/v1/optimize/spend
Authorization: Bearer cc_live_xxx
Content-Type: application/json

{
  "amount_inr": 6000,
  "merchant": "swiggy",
  "category": "dining"
}

http

Response

{
  "top_recommendation": {
    "card_name": "HDFC Bank Infinia Metal Credit Card",
    "bank": "HDFC Bank",
    "estimated_reward_inr": 996,
    "effective_rate_pct": 16.6,
    "reward_type": "reward_points"
  },
  "ranked_cards": [
    { "card_name": "Swiggy HDFC Bank Credit Card", "effective_rate_pct": 10.0 },
    { "card_name": "Axis Bank Cashback Credit Card", "effective_rate_pct": 5.0 }
  ]
}

json

Recommend Cards

POST/api/v1/recommend/cards

Recommends a credit card portfolio based on monthly spend profile and CIBIL score. Returns net annual value after fees. Requires recommend:execute scope.

Request Body JSON

monthly_spendsRecord<string, number>required

Map of category spend amounts in INR. Categories include online, dining, travel, groceries, fuel.

cibil_scorenumberoptionaldefault: 750

User CIBIL score (300–900). Cards requiring a higher score are automatically excluded.

POST https://cardcheck.in/api/v1/recommend/cards
Authorization: Bearer cc_live_xxx
Content-Type: application/json

{
  "monthly_spends": {
    "online": 25000,
    "dining": 8000,
    "travel": 10000
  },
  "cibil_score": 780
}

http

Response

{
  "top_card": {
    "id": "hdfc-infinia-metal",
    "name": "HDFC Bank Infinia Metal Credit Card",
    "net_annual_value_inr": 9676,
    "annual_gross_reward_inr": 22176,
    "annual_fee_inr": 12500,
    "effective_return_pct": 3.85
  },
  "alternatives": [...]
}

json

Send OTP

POST/api/v1/developer-leads/otp/send

Sends a 6-digit OTP to the developer's email via Supabase Auth. Rate-limited. OTP expires in 10 minutes. No auth required.

Request Body JSON

emailstringrequired

Corporate or developer email address.

namestringrequired

Developer full name.

companystringrequired

Company or startup name.

use_casestringoptional

Intended usage (e.g. "PFM / Spend Recommendations").

volumestringoptional

Expected monthly request volume tier.

POST https://cardcheck.in/api/v1/developer-leads/otp/send
Content-Type: application/json

{
  "email": "dev@fintech.in",
  "name": "Priya Sharma",
  "company": "FinTech Ventures",
  "use_case": "PFM / Spend Recommendations",
  "volume": "10k-50k requests/mo"
}

http

Response `200 OK`

{ "success": true, "message": "OTP sent to dev@fintech.in" }

json

Verify OTP & Get API Key

POST/api/v1/developer-leads/otp/verify

Verifies the 6-digit OTP, inserts a verified lead into Supabase, provisions a scoped API key, and returns it immediately. Key is shown once — store securely.

Request Body JSON

emailstringrequired

The registered email address matching the OTP dispatch.

otpstringrequired

The 6-digit OTP code received via email.

companystringrequired

Company name for lead record creation.

POST https://cardcheck.in/api/v1/developer-leads/otp/verify
Content-Type: application/json

{
  "email": "dev@fintech.in",
  "otp": "621577",
  "name": "Priya Sharma",
  "company": "FinTech Ventures",
  "use_case": "PFM / Spend Recommendations",
  "volume": "10k-50k requests/mo"
}

http

Response `201 Created`

{
  "success": true,
  "api_key": "cc_test_27af_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "key_prefix": "cc_test_27af",
  "message": "API key provisioned. Store it securely — it will not be shown again.",
  "scope": ["cards:read", "optimize:execute", "recommend:execute"],
  "tier": "sandbox"
}

json

One-time display: The full API key is returned only once. Store it immediately in your backend environment variables or secrets store.

HTTP Error Responses

Status	Code	Description
400	INVALID_OTP	Wrong or expired 6-digit OTP code
401	UNAUTHORIZED	Missing or invalid Bearer API key in Authorization header
403	INSUFFICIENT_SCOPE	API key lacks required scope (e.g. optimize:execute)
429	RATE_LIMITED	Rate limit or monthly quota exhausted — retry after cooldown

CardCheck API & MCP Reference

Authentication

API Key Tiers

MCP Quick Start

Claude Desktop

Cursor IDE

Antigravity IDE

cardcheck_advisor

Tool Input Parameters

optimize_spend

Response

search_cards

Response

get_card_details

Response

recommend_portfolio

Response

Search Cards

Query Parameters

Response

Get Card by ID

Path Parameters

Response

Optimize Spend

Request Body JSON

Response

Recommend Cards

Request Body JSON

Response

Send OTP

Request Body JSON

Response 200 OK

Verify OTP & Get API Key

Request Body JSON

Response 201 Created

HTTP Error Responses

Response `200 OK`

Response `201 Created`